From 90051780eba9774641fb56a8e1436b4a5e46cd24 Mon Sep 17 00:00:00 2001
From: Joongi Kim <me@daybreaker.info>
Date: Mon, 27 Jul 2026 03:24:03 +0000
Subject: [PATCH] =?UTF-8?q?feat:=20variant=20index=20publishing=20?=
 =?UTF-8?q?=E2=80=94=20push,=20list,=20inspect,=20index=20update?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pkg/oci wraps oras-go v2 with Docker credential-store auth and
loopback plain-HTTP detection, and implements the index artifact I/O:
FetchIndexFrom/PushIndexTo work against any OCI target (unit-tested on
in-memory stores), and BuildIndex reconstructs an index by scanning
"<version>-<label>" tags and reading config labels through either OCI
or Docker schema2 manifests and manifest lists — the same computation
the Phase B proxy will serve.

pkg/docker shells out to the docker CLI for engine ops (ADR-4).

New subcommands: `push` (docker push + index upsert, validating tag
suffix against the image's variant label), `list` (table with per-host
match ranking), `inspect` (raw index JSON), and `index update`
(rebuild-from-scan, reconciling plain docker pushes).

Smoke-tested against a local registry:2: push, plain-push + index
update discovery, and list under GPU/CPU-only mocked properties.

Claude-Session: https://claude.ai/code/session_01D383U8kkQkJc1yzyC5H5Nk
---
 cmd/docker-variant/common.go   |  35 ++++++
 cmd/docker-variant/indexcmd.go |  62 ++++++++++
 cmd/docker-variant/inspect.go  |  38 +++++++
 cmd/docker-variant/list.go     |  78 +++++++++++++
 cmd/docker-variant/main.go     |   8 +-
 cmd/docker-variant/push.go     |  82 +++++++++++++
 go.mod                         |   4 +
 go.sum                         |   8 ++
 pkg/docker/docker.go           |  65 +++++++++++
 pkg/oci/client.go              |  98 ++++++++++++++++
 pkg/oci/index.go               | 202 +++++++++++++++++++++++++++++++++
 pkg/oci/oci_test.go            | 138 ++++++++++++++++++++++
 12 files changed, 817 insertions(+), 1 deletion(-)
 create mode 100644 cmd/docker-variant/common.go
 create mode 100644 cmd/docker-variant/indexcmd.go
 create mode 100644 cmd/docker-variant/inspect.go
 create mode 100644 cmd/docker-variant/list.go
 create mode 100644 cmd/docker-variant/push.go
 create mode 100644 pkg/docker/docker.go
 create mode 100644 pkg/oci/client.go
 create mode 100644 pkg/oci/index.go
 create mode 100644 pkg/oci/oci_test.go

diff --git a/cmd/docker-variant/common.go b/cmd/docker-variant/common.go
new file mode 100644
index 0000000..d071d38
--- /dev/null
+++ b/cmd/docker-variant/common.go
@@ -0,0 +1,35 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/achimnol/docker-variant/pkg/oci"
+)
+
+// registryFlags carries the flags shared by every registry-touching
+// subcommand.
+type registryFlags struct {
+	plainHTTP bool
+}
+
+func (f *registryFlags) add(cmd *cobra.Command) {
+	cmd.Flags().BoolVar(&f.plainHTTP, "plain-http", false, "use HTTP for the registry (loopback registries always do)")
+}
+
+func (f *registryFlags) client() (*oci.Client, error) {
+	return oci.NewClient(f.plainHTTP)
+}
+
+// versionRef parses a "<registry>/<repository>:<base-version>" argument.
+func versionRef(arg string) (oci.Ref, error) {
+	ref, err := oci.ParseRef(arg)
+	if err != nil {
+		return oci.Ref{}, err
+	}
+	if ref.Tag == "" {
+		return oci.Ref{}, fmt.Errorf("reference %q must include the base version as its tag", arg)
+	}
+	return ref, nil
+}
diff --git a/cmd/docker-variant/indexcmd.go b/cmd/docker-variant/indexcmd.go
new file mode 100644
index 0000000..6cf4103
--- /dev/null
+++ b/cmd/docker-variant/indexcmd.go
@@ -0,0 +1,62 @@
+package main
+
+import (
+	"fmt"
+	"maps"
+	"slices"
+
+	"github.com/spf13/cobra"
+
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+func newIndexCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "index",
+		Short: "Manage variant index artifacts",
+	}
+	cmd.AddCommand(newIndexUpdateCommand())
+	return cmd
+}
+
+func newIndexUpdateCommand() *cobra.Command {
+	var regFlags registryFlags
+	cmd := &cobra.Command{
+		Use:   "update REGISTRY/REPOSITORY:VERSION",
+		Short: "Rebuild the variant index by scanning the repository's tags",
+		Long: "Scans the repository for <version>-<label> tags, reads each image's\n" +
+			"variant labels, and replaces the <version>-variants index artifact\n" +
+			"with the result. Use to reconcile after plain `docker push`es or\n" +
+			"conflicting index updates.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			ref, err := versionRef(args[0])
+			if err != nil {
+				return err
+			}
+			client, err := regFlags.client()
+			if err != nil {
+				return err
+			}
+			ix, warnings, err := client.BuildIndex(ctx, ref, ref.Tag)
+			if err != nil {
+				return err
+			}
+			for _, warning := range warnings {
+				fmt.Fprintln(cmd.ErrOrStderr(), "Warning:", warning)
+			}
+			if len(ix.Variants) == 0 {
+				return fmt.Errorf("no variant tags found for %s version %s", ref.Name(), ref.Tag)
+			}
+			if _, err := client.PushIndex(ctx, ref, ix); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Rebuilt index %s with variants: %v\n",
+				ref.WithTag(variant.IndexTag(ref.Tag)), slices.Sorted(maps.Keys(ix.Variants)))
+			return nil
+		},
+	}
+	regFlags.add(cmd)
+	return cmd
+}
diff --git a/cmd/docker-variant/inspect.go b/cmd/docker-variant/inspect.go
new file mode 100644
index 0000000..821cdf1
--- /dev/null
+++ b/cmd/docker-variant/inspect.go
@@ -0,0 +1,38 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+func newInspectCommand() *cobra.Command {
+	var regFlags registryFlags
+	cmd := &cobra.Command{
+		Use:   "inspect REGISTRY/REPOSITORY:VERSION",
+		Short: "Print the raw variant index document",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ref, err := versionRef(args[0])
+			if err != nil {
+				return err
+			}
+			client, err := regFlags.client()
+			if err != nil {
+				return err
+			}
+			ix, err := client.FetchIndex(cmd.Context(), ref, ref.Tag)
+			if err != nil {
+				return err
+			}
+			data, err := ix.Marshal()
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), string(data))
+			return nil
+		},
+	}
+	regFlags.add(cmd)
+	return cmd
+}
diff --git a/cmd/docker-variant/list.go b/cmd/docker-variant/list.go
new file mode 100644
index 0000000..ab1381b
--- /dev/null
+++ b/cmd/docker-variant/list.go
@@ -0,0 +1,78 @@
+package main
+
+import (
+	"fmt"
+	"maps"
+	"slices"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+func newListCommand() *cobra.Command {
+	var (
+		regFlags       registryFlags
+		propertiesFile string
+	)
+	cmd := &cobra.Command{
+		Use:   "list REGISTRY/REPOSITORY:VERSION",
+		Short: "List the variants of a base version and their match ranking",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			ref, err := versionRef(args[0])
+			if err != nil {
+				return err
+			}
+			client, err := regFlags.client()
+			if err != nil {
+				return err
+			}
+			ix, err := client.FetchIndex(ctx, ref, ref.Tag)
+			if err != nil {
+				return err
+			}
+			sys, err := systemProperties(cmd, propertiesFile)
+			if err != nil {
+				return err
+			}
+			rank := map[string]int{}
+			for i, r := range variant.Rank(ix, sys) {
+				rank[r.Label] = i + 1
+			}
+			w := tabwriter.NewWriter(cmd.OutOrStdout(), 2, 8, 2, ' ', 0)
+			fmt.Fprintln(w, "LABEL\tTAG\tDIGEST\tMATCH\tPROPERTIES")
+			for _, label := range slices.Sorted(maps.Keys(ix.Variants)) {
+				e := ix.Variants[label]
+				match := "-"
+				if pos, ok := rank[label]; ok {
+					match = fmt.Sprintf("#%d", pos)
+				}
+				fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n",
+					label, e.Tag, shortDigest(e.Digest), match, strings.Join(e.Properties.Triples(), "; "))
+			}
+			if err := w.Flush(); err != nil {
+				return err
+			}
+			if best := variant.Rank(ix, sys); len(best) > 0 {
+				fmt.Fprintf(cmd.OutOrStdout(), "\nBest match for this system: %s (%s)\n", best[0].Label, best[0].Entry.Tag)
+			} else {
+				fmt.Fprintf(cmd.OutOrStdout(), "\nNo compatible variant; `pull` would fall back to %s\n", args[0])
+			}
+			return nil
+		},
+	}
+	regFlags.add(cmd)
+	cmd.Flags().StringVar(&propertiesFile, "properties-file", "", "read system properties from a JSON file instead of detecting")
+	return cmd
+}
+
+func shortDigest(d string) string {
+	if rest, ok := strings.CutPrefix(d, "sha256:"); ok && len(rest) >= 12 {
+		return rest[:12]
+	}
+	return d
+}
diff --git a/cmd/docker-variant/main.go b/cmd/docker-variant/main.go
index 25fe5c5..b953c15 100644
--- a/cmd/docker-variant/main.go
+++ b/cmd/docker-variant/main.go
@@ -60,6 +60,12 @@ func newVariantCommand() *cobra.Command {
 			"following the PEP 817 wheel-variant model mapped onto image labels,\n" +
 			"tags, and a per-version variant index artifact.",
 	}
-	cmd.AddCommand(newDetectCommand())
+	cmd.AddCommand(
+		newDetectCommand(),
+		newPushCommand(),
+		newListCommand(),
+		newInspectCommand(),
+		newIndexCommand(),
+	)
 	return cmd
 }
diff --git a/cmd/docker-variant/push.go b/cmd/docker-variant/push.go
new file mode 100644
index 0000000..6cb6ce2
--- /dev/null
+++ b/cmd/docker-variant/push.go
@@ -0,0 +1,82 @@
+package main
+
+import (
+	"fmt"
+	"maps"
+	"slices"
+
+	"github.com/spf13/cobra"
+
+	"github.com/achimnol/docker-variant/pkg/docker"
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+func newPushCommand() *cobra.Command {
+	var (
+		regFlags      registryFlags
+		skipImagePush bool
+	)
+	cmd := &cobra.Command{
+		Use:   "push REGISTRY/REPOSITORY:VERSION-LABEL",
+		Short: "Push a variant image and update the repository's variant index",
+		Long: "Pushes the given variant tag with `docker push`, reads the variant\n" +
+			"label and properties from the local image's config labels, and\n" +
+			"upserts the corresponding entry in the <version>-variants index\n" +
+			"artifact of the repository.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+			ref, err := versionRef(args[0])
+			if err != nil {
+				return err
+			}
+			labels, err := docker.ImageLabels(ctx, args[0])
+			if err != nil {
+				return err
+			}
+			label, props, err := variant.ParseImageLabels(labels)
+			if err != nil {
+				return fmt.Errorf("%s: %w (variant images must carry %s labels)", args[0], err, variant.PropertyLabelPrefix+"*")
+			}
+			version, err := variant.BaseVersion(ref.Tag, label)
+			if err != nil {
+				return err
+			}
+			if !skipImagePush {
+				if err := docker.Push(ctx, args[0]); err != nil {
+					return err
+				}
+			}
+			client, err := regFlags.client()
+			if err != nil {
+				return err
+			}
+			repo, err := client.Repo(ref)
+			if err != nil {
+				return err
+			}
+			desc, err := repo.Resolve(ctx, ref.Tag)
+			if err != nil {
+				return fmt.Errorf("resolving pushed tag %s: %w", args[0], err)
+			}
+			ix, err := client.FetchIndex(ctx, ref, version)
+			if err != nil {
+				ix = variant.NewIndex(ref.Name(), version)
+			}
+			if err := ix.Upsert(label, variant.Entry{Properties: props, Tag: ref.Tag, Digest: desc.Digest.String()}); err != nil {
+				return err
+			}
+			if _, err := client.PushIndex(ctx, ref, ix); err != nil {
+				return err
+			}
+			fmt.Fprintf(cmd.OutOrStdout(), "Indexed variant %q (%s) for %s version %s\n",
+				label, desc.Digest, ref.Name(), version)
+			fmt.Fprintf(cmd.OutOrStdout(), "Index %s now lists: %v\n",
+				ref.WithTag(variant.IndexTag(version)), slices.Sorted(maps.Keys(ix.Variants)))
+			return nil
+		},
+	}
+	regFlags.add(cmd)
+	cmd.Flags().BoolVar(&skipImagePush, "skip-image-push", false, "only update the index, assuming the tag is already pushed")
+	return cmd
+}
diff --git a/go.mod b/go.mod
index f9ad3db..3da7624 100644
--- a/go.mod
+++ b/go.mod
@@ -3,11 +3,15 @@ module github.com/achimnol/docker-variant
 go 1.26.4
 
 require (
+	github.com/opencontainers/image-spec v1.1.1
 	github.com/spf13/cobra v1.10.2
 	golang.org/x/sys v0.47.0
+	oras.land/oras-go/v2 v2.6.2
 )
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	golang.org/x/sync v0.22.0 // indirect
 )
diff --git a/go.sum b/go.sum
index 6b4c588..c111a3e 100644
--- a/go.sum
+++ b/go.sum
@@ -1,12 +1,20 @@
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+oras.land/oras-go/v2 v2.6.2 h1:N04RXngAp1LJKTG6ifz3xHPipasEkWr+hFmInja5YKo=
+oras.land/oras-go/v2 v2.6.2/go.mod h1:PlTtg4JTDJkDe8yVHpM2wz7/YDc00GVas+i4jAW2TZ4=
diff --git a/pkg/docker/docker.go b/pkg/docker/docker.go
new file mode 100644
index 0000000..dacd31c
--- /dev/null
+++ b/pkg/docker/docker.go
@@ -0,0 +1,65 @@
+// Package docker shells out to the `docker` CLI for Engine operations
+// (ADR-4): this inherits the user's contexts, credential helpers, and
+// daemon configuration without importing the moby client.
+package docker
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+// run executes docker with output streamed to the user (push/pull progress).
+func run(ctx context.Context, args ...string) error {
+	cmd := exec.CommandContext(ctx, "docker", args...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("docker %s: %w", strings.Join(args, " "), err)
+	}
+	return nil
+}
+
+// capture executes docker and returns its stdout.
+func capture(ctx context.Context, args ...string) (string, error) {
+	var out, errOut bytes.Buffer
+	cmd := exec.CommandContext(ctx, "docker", args...)
+	cmd.Stdout = &out
+	cmd.Stderr = &errOut
+	if err := cmd.Run(); err != nil {
+		return "", fmt.Errorf("docker %s: %w: %s", strings.Join(args, " "), err, strings.TrimSpace(errOut.String()))
+	}
+	return out.String(), nil
+}
+
+// Push pushes a tag, streaming progress.
+func Push(ctx context.Context, ref string) error {
+	return run(ctx, "push", ref)
+}
+
+// Pull pulls a reference (tag or digest), streaming progress.
+func Pull(ctx context.Context, ref string) error {
+	return run(ctx, "pull", ref)
+}
+
+// Tag applies a local tag.
+func Tag(ctx context.Context, src, dst string) error {
+	return run(ctx, "tag", src, dst)
+}
+
+// ImageLabels returns the config labels of a local image.
+func ImageLabels(ctx context.Context, ref string) (map[string]string, error) {
+	out, err := capture(ctx, "image", "inspect", "--format", "{{json .Config.Labels}}", ref)
+	if err != nil {
+		return nil, err
+	}
+	var labels map[string]string
+	if err := json.Unmarshal([]byte(strings.TrimSpace(out)), &labels); err != nil {
+		return nil, fmt.Errorf("parsing labels of %s: %w", ref, err)
+	}
+	return labels, nil
+}
diff --git a/pkg/oci/client.go b/pkg/oci/client.go
new file mode 100644
index 0000000..93b795f
--- /dev/null
+++ b/pkg/oci/client.go
@@ -0,0 +1,98 @@
+// Package oci implements the registry-facing operations: resolving
+// references, reading image config labels, and fetching/pushing/building the
+// variant index artifact. It is shared by the CLI plugin and the
+// variant-proxy (ADR-4: registry I/O via oras-go).
+package oci
+
+import (
+	"fmt"
+	"net"
+	"strings"
+
+	"oras.land/oras-go/v2/registry"
+	"oras.land/oras-go/v2/registry/remote"
+	"oras.land/oras-go/v2/registry/remote/auth"
+	"oras.land/oras-go/v2/registry/remote/credentials"
+	"oras.land/oras-go/v2/registry/remote/retry"
+)
+
+// Client creates repository handles with Docker credential-store auth.
+type Client struct {
+	// PlainHTTP forces HTTP for every registry (otherwise only loopback
+	// registries use HTTP).
+	PlainHTTP bool
+
+	authClient *auth.Client
+}
+
+// NewClient returns a client using the Docker config credential store.
+func NewClient(plainHTTP bool) (*Client, error) {
+	store, err := credentials.NewStoreFromDocker(credentials.StoreOptions{})
+	if err != nil {
+		return nil, fmt.Errorf("loading docker credential store: %w", err)
+	}
+	return &Client{
+		PlainHTTP: plainHTTP,
+		authClient: &auth.Client{
+			Client:     retry.DefaultClient,
+			Cache:      auth.NewCache(),
+			Credential: credentials.Credential(store),
+		},
+	}, nil
+}
+
+// Ref is a parsed fully-qualified image reference (registry host required;
+// Docker Hub shorthand like "myimg:tag" is not resolved in v1).
+type Ref struct {
+	Registry   string // e.g. localhost:5000
+	Repository string // e.g. myorg/myimg
+	Tag        string // may be empty
+}
+
+// Name returns "registry/repository".
+func (r Ref) Name() string { return r.Registry + "/" + r.Repository }
+
+// WithTag returns "registry/repository:tag".
+func (r Ref) WithTag(tag string) string { return r.Name() + ":" + tag }
+
+// WithDigest returns "registry/repository@digest".
+func (r Ref) WithDigest(digest string) string { return r.Name() + "@" + digest }
+
+// ParseRef parses "host/repo[:tag]".
+func ParseRef(s string) (Ref, error) {
+	parsed, err := registry.ParseReference(s)
+	if err != nil {
+		return Ref{}, fmt.Errorf("invalid reference %q (fully-qualified <registry>/<repository>[:<tag>] required): %w", s, err)
+	}
+	if parsed.Reference != "" && strings.HasPrefix(parsed.Reference, "sha256:") {
+		return Ref{}, fmt.Errorf("digest references are not accepted here: %q", s)
+	}
+	return Ref{Registry: parsed.Registry, Repository: parsed.Repository, Tag: parsed.Reference}, nil
+}
+
+// Repo returns an oras repository handle for the reference.
+func (c *Client) Repo(ref Ref) (*remote.Repository, error) {
+	repo, err := remote.NewRepository(ref.Name())
+	if err != nil {
+		return nil, err
+	}
+	repo.Client = c.authClient
+	repo.PlainHTTP = c.PlainHTTP || isLoopback(ref.Registry)
+	return repo, nil
+}
+
+// isLoopback reports whether the registry host is local, where unencrypted
+// HTTP is the norm (mirrors dockerd's insecure-registry default).
+func isLoopback(hostport string) bool {
+	host := hostport
+	if h, _, err := net.SplitHostPort(hostport); err == nil {
+		host = h
+	}
+	if host == "localhost" {
+		return true
+	}
+	if ip := net.ParseIP(strings.Trim(host, "[]")); ip != nil {
+		return ip.IsLoopback()
+	}
+	return false
+}
diff --git a/pkg/oci/index.go b/pkg/oci/index.go
new file mode 100644
index 0000000..1c327bd
--- /dev/null
+++ b/pkg/oci/index.go
@@ -0,0 +1,202 @@
+package oci
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sort"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/memory"
+	"oras.land/oras-go/v2/errdef"
+
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+// ErrNoIndex is returned when a repository has no variant index for the
+// requested base version.
+var ErrNoIndex = errors.New("no variant index found")
+
+// FetchIndex retrieves and parses the variant index artifact for
+// (repository, version) via the "<version>-variants" tag.
+func (c *Client) FetchIndex(ctx context.Context, ref Ref, version string) (*variant.Index, error) {
+	repo, err := c.Repo(ref)
+	if err != nil {
+		return nil, err
+	}
+	return FetchIndexFrom(ctx, repo, version)
+}
+
+// ReadOnlyTarget is the storage interface FetchIndexFrom needs: tag
+// resolution plus content fetch (satisfied by *remote.Repository and the
+// in-memory stores used in tests).
+type ReadOnlyTarget interface {
+	content.Fetcher
+	content.Resolver
+}
+
+// FetchIndexFrom retrieves and parses the "<version>-variants" artifact from
+// any OCI target.
+func FetchIndexFrom(ctx context.Context, repo ReadOnlyTarget, version string) (*variant.Index, error) {
+	desc, err := repo.Resolve(ctx, variant.IndexTag(version))
+	if err != nil {
+		if errors.Is(err, errdef.ErrNotFound) {
+			return nil, fmt.Errorf("%w for version %s", ErrNoIndex, version)
+		}
+		return nil, err
+	}
+	manifestData, err := content.FetchAll(ctx, repo, desc)
+	if err != nil {
+		return nil, err
+	}
+	var manifest ocispec.Manifest
+	if err := json.Unmarshal(manifestData, &manifest); err != nil {
+		return nil, fmt.Errorf("parsing index artifact manifest: %w", err)
+	}
+	for _, layer := range manifest.Layers {
+		if layer.MediaType != variant.IndexArtifactType {
+			continue
+		}
+		data, err := content.FetchAll(ctx, repo, layer)
+		if err != nil {
+			return nil, err
+		}
+		return variant.ParseIndex(data)
+	}
+	return nil, fmt.Errorf("tag %s exists but carries no %s layer", variant.IndexTag(version), variant.IndexArtifactType)
+}
+
+// PushIndex packs the index as an OCI artifact and tags it
+// "<version>-variants" in the repository.
+func (c *Client) PushIndex(ctx context.Context, ref Ref, ix *variant.Index) (ocispec.Descriptor, error) {
+	repo, err := c.Repo(ref)
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	return PushIndexTo(ctx, repo, ix)
+}
+
+// PushIndexTo packs and tags the index artifact into any OCI target.
+func PushIndexTo(ctx context.Context, repo oras.Target, ix *variant.Index) (ocispec.Descriptor, error) {
+	data, err := ix.Marshal()
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	tag := variant.IndexTag(ix.Version)
+	store := memory.New()
+	layerDesc, err := oras.PushBytes(ctx, store, variant.IndexArtifactType, data)
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	manifestDesc, err := oras.PackManifest(ctx, store, oras.PackManifestVersion1_1, variant.IndexArtifactType,
+		oras.PackManifestOptions{Layers: []ocispec.Descriptor{layerDesc}})
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	if err := store.Tag(ctx, manifestDesc, tag); err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	if _, err := oras.Copy(ctx, store, tag, repo, tag, oras.DefaultCopyOptions); err != nil {
+		return ocispec.Descriptor{}, fmt.Errorf("pushing variant index tag %s: %w", tag, err)
+	}
+	return manifestDesc, nil
+}
+
+// BuildIndex constructs a variant index by scanning the repository's tags
+// for "<version>-<label>" and reading each image's config labels — the same
+// computation the variant-proxy performs server-side. Tags whose image
+// labels are missing or inconsistent with the tag are skipped and reported
+// in warnings.
+func (c *Client) BuildIndex(ctx context.Context, ref Ref, version string) (*variant.Index, []string, error) {
+	repo, err := c.Repo(ref)
+	if err != nil {
+		return nil, nil, err
+	}
+	var variantTags []string
+	err = repo.Tags(ctx, "", func(tags []string) error {
+		for _, tag := range tags {
+			if _, ok := variant.MatchVariantTag(tag, version); ok {
+				variantTags = append(variantTags, tag)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, nil, fmt.Errorf("listing tags of %s: %w", ref.Name(), err)
+	}
+	sort.Strings(variantTags)
+
+	ix := variant.NewIndex(ref.Name(), version)
+	var warnings []string
+	for _, tag := range variantTags {
+		tagLabel, _ := variant.MatchVariantTag(tag, version)
+		desc, err := repo.Resolve(ctx, tag)
+		if err != nil {
+			warnings = append(warnings, fmt.Sprintf("%s: resolve failed: %v", tag, err))
+			continue
+		}
+		labels, err := imageConfigLabels(ctx, repo, desc)
+		if err != nil {
+			warnings = append(warnings, fmt.Sprintf("%s: reading config labels: %v", tag, err))
+			continue
+		}
+		imgLabel, props, err := variant.ParseImageLabels(labels)
+		if err != nil {
+			warnings = append(warnings, fmt.Sprintf("%s: %v", tag, err))
+			continue
+		}
+		if imgLabel != tagLabel {
+			warnings = append(warnings, fmt.Sprintf("%s: tag says %q but image label says %q; skipping", tag, tagLabel, imgLabel))
+			continue
+		}
+		if err := ix.Upsert(imgLabel, variant.Entry{Properties: props, Tag: tag, Digest: desc.Digest.String()}); err != nil {
+			warnings = append(warnings, fmt.Sprintf("%s: %v", tag, err))
+		}
+	}
+	return ix, warnings, nil
+}
+
+// imageConfigLabels fetches the config labels behind a manifest descriptor,
+// descending through a manifest list/index to its first entry (config labels
+// are per-platform; v1 assumes variant labels are identical across
+// platforms).
+func imageConfigLabels(ctx context.Context, repo oras.ReadOnlyTarget, desc ocispec.Descriptor) (map[string]string, error) {
+	data, err := content.FetchAll(ctx, repo, desc)
+	if err != nil {
+		return nil, err
+	}
+	switch desc.MediaType {
+	case ocispec.MediaTypeImageIndex, "application/vnd.docker.distribution.manifest.list.v2+json":
+		var index ocispec.Index
+		if err := json.Unmarshal(data, &index); err != nil {
+			return nil, err
+		}
+		if len(index.Manifests) == 0 {
+			return nil, errors.New("manifest list is empty")
+		}
+		return imageConfigLabels(ctx, repo, index.Manifests[0])
+	case ocispec.MediaTypeImageManifest, "application/vnd.docker.distribution.manifest.v2+json":
+		var manifest ocispec.Manifest
+		if err := json.Unmarshal(data, &manifest); err != nil {
+			return nil, err
+		}
+		configData, err := content.FetchAll(ctx, repo, manifest.Config)
+		if err != nil {
+			return nil, err
+		}
+		var config struct {
+			Config struct {
+				Labels map[string]string `json:"Labels"`
+			} `json:"config"`
+		}
+		if err := json.Unmarshal(configData, &config); err != nil {
+			return nil, err
+		}
+		return config.Config.Labels, nil
+	default:
+		return nil, fmt.Errorf("unsupported manifest media type %q", desc.MediaType)
+	}
+}
diff --git a/pkg/oci/oci_test.go b/pkg/oci/oci_test.go
new file mode 100644
index 0000000..de62d81
--- /dev/null
+++ b/pkg/oci/oci_test.go
@@ -0,0 +1,138 @@
+package oci
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/content/memory"
+
+	"github.com/achimnol/docker-variant/pkg/variant"
+)
+
+func TestParseRef(t *testing.T) {
+	ref, err := ParseRef("localhost:5000/myorg/myimg:2.1.0")
+	if err != nil {
+		t.Fatalf("ParseRef: %v", err)
+	}
+	if ref.Registry != "localhost:5000" || ref.Repository != "myorg/myimg" || ref.Tag != "2.1.0" {
+		t.Errorf("ParseRef = %+v", ref)
+	}
+	if got := ref.Name(); got != "localhost:5000/myorg/myimg" {
+		t.Errorf("Name = %q", got)
+	}
+	if got := ref.WithTag("x"); got != "localhost:5000/myorg/myimg:x" {
+		t.Errorf("WithTag = %q", got)
+	}
+	if got := ref.WithDigest("sha256:abc"); got != "localhost:5000/myorg/myimg@sha256:abc" {
+		t.Errorf("WithDigest = %q", got)
+	}
+	if _, err := ParseRef("not a ref"); err == nil {
+		t.Error("garbage ref: want error")
+	}
+	if _, err := ParseRef("localhost:5000/img@sha256:0000000000000000000000000000000000000000000000000000000000000000"); err == nil {
+		t.Error("digest ref: want error")
+	}
+}
+
+func TestIsLoopback(t *testing.T) {
+	for host, want := range map[string]bool{
+		"localhost":        true,
+		"localhost:5000":   true,
+		"127.0.0.1:5000":   true,
+		"[::1]:5000":       true,
+		"registry.io":      false,
+		"registry.io:5000": false,
+		"10.0.0.1:5000":    false,
+	} {
+		if got := isLoopback(host); got != want {
+			t.Errorf("isLoopback(%q) = %v, want %v", host, got, want)
+		}
+	}
+}
+
+func TestIndexArtifactRoundTrip(t *testing.T) {
+	ctx := context.Background()
+	store := memory.New()
+	ix := variant.NewIndex("localhost:5000/myimg", "2.1.0")
+	if err := ix.Upsert("cu128", variant.Entry{
+		Properties: variant.Properties{"nvidia": {"cuda_version_lower_bound": {"12.8"}}},
+		Tag:        "2.1.0-cu128",
+		Digest:     "sha256:aaa",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := PushIndexTo(ctx, store, ix); err != nil {
+		t.Fatalf("PushIndexTo: %v", err)
+	}
+	got, err := FetchIndexFrom(ctx, store, "2.1.0")
+	if err != nil {
+		t.Fatalf("FetchIndexFrom: %v", err)
+	}
+	if got.Version != "2.1.0" || len(got.Variants) != 1 || got.Variants["cu128"].Digest != "sha256:aaa" {
+		t.Errorf("round-trip mismatch: %+v", got)
+	}
+
+	if _, err := FetchIndexFrom(ctx, store, "9.9.9"); !errors.Is(err, ErrNoIndex) {
+		t.Errorf("missing version: err = %v, want ErrNoIndex", err)
+	}
+}
+
+// pushJSON stores a JSON blob and returns its descriptor.
+func pushJSON(t *testing.T, store oras.Target, mediaType string, v any) ocispec.Descriptor {
+	t.Helper()
+	data, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	desc := content.NewDescriptorFromBytes(mediaType, data)
+	if err := store.Push(context.Background(), desc, bytes.NewReader(data)); err != nil {
+		t.Fatal(err)
+	}
+	return desc
+}
+
+func TestImageConfigLabels(t *testing.T) {
+	ctx := context.Background()
+	store := memory.New()
+	labels := map[string]string{"dev.pep817.variant-label": "cu128"}
+
+	configDesc := pushJSON(t, store, ocispec.MediaTypeImageConfig, map[string]any{
+		"config": map[string]any{"Labels": labels},
+	})
+	manifestDesc := pushJSON(t, store, ocispec.MediaTypeImageManifest, ocispec.Manifest{
+		MediaType: ocispec.MediaTypeImageManifest,
+		Config:    configDesc,
+	})
+	indexDesc := pushJSON(t, store, ocispec.MediaTypeImageIndex, ocispec.Index{
+		MediaType: ocispec.MediaTypeImageIndex,
+		Manifests: []ocispec.Descriptor{manifestDesc},
+	})
+
+	// Direct manifest and via manifest list must both resolve the labels.
+	for _, desc := range []ocispec.Descriptor{manifestDesc, indexDesc} {
+		got, err := imageConfigLabels(ctx, store, desc)
+		if err != nil {
+			t.Fatalf("imageConfigLabels(%s): %v", desc.MediaType, err)
+		}
+		if got["dev.pep817.variant-label"] != "cu128" {
+			t.Errorf("labels via %s = %v", desc.MediaType, got)
+		}
+	}
+
+	emptyIndexDesc := pushJSON(t, store, ocispec.MediaTypeImageIndex, ocispec.Index{
+		MediaType: ocispec.MediaTypeImageIndex,
+	})
+	if _, err := imageConfigLabels(ctx, store, emptyIndexDesc); err == nil {
+		t.Error("empty manifest list: want error")
+	}
+	unknownDesc := pushJSON(t, store, "application/octet-stream", map[string]any{})
+	if _, err := imageConfigLabels(ctx, store, unknownDesc); err == nil {
+		t.Error("unknown media type: want error")
+	}
+}