feat: `mocker manifest` command for multi-arch OCI image index assembly

[kaovilai]

Problem

mocker build --platform <os/arch> successfully builds per-architecture images (amd64, arm64, ppc64le all confirmed working). However, there is no way to assemble these into a multi-architecture OCI Image Index (manifest list) for publication.

# These all work today:
mocker build --platform linux/amd64  -t test-amd64:latest  .
mocker build --platform linux/arm64  -t test-arm64:latest  .
mocker build --platform linux/ppc64le -t test-ppc64le:latest .

# This does not exist:
mocker manifest create test-multiarch:latest         # ← unknown command
mocker manifest add test-multiarch:latest test-amd64:latest
mocker manifest push test-multiarch:latest

Upstream tracking

Apple upstream issue filed: apple/container#1495 — Feature: container manifest subcommand for multi-arch OCI image index creation

If Apple ships a container manifest plugin, mocker can delegate to it directly. Monitor that issue.

Proposed solution

Add a mocker manifest subcommand group matching Docker and Podman conventions:

Command	Description
mocker manifest create <list> [images...]	Create a new manifest list
mocker manifest add <list> <image>	Add an image to the list
mocker manifest rm <list> <image>	Remove an image from the list
mocker manifest inspect <list>	Inspect a manifest list
mocker manifest push <list>	Push manifest list to a registry
mocker manifest annotate	Annotate a manifest entry

Implementation notes

• Apple's container CLI has no manifest plugin yet (tracked upstream: Feature: container manifest subcommand for multi-arch OCI image index creation apple/container#1495)
• apple/containerization's ImageStore may already have the primitives needed to construct an OCI Index
• Alternatively, mocker could shell out to skopeo if available (skopeo supports --multi-arch and can create manifest lists)

Workaround today

Use skopeo to push per-arch images to a registry, then assemble a manifest list externally:

# 1. Build per-arch
mocker build --platform linux/amd64 -t myrepo/myimage:amd64 .
mocker build --platform linux/arm64 -t myrepo/myimage:arm64 .

# 2. Save + push via skopeo (skopeo handles OCI Index child manifest correctly)
mocker image save myrepo/myimage:amd64 -o amd64.tar
skopeo copy oci-archive:amd64.tar docker://myrepo/myimage:amd64

mocker image save myrepo/myimage:arm64 -o arm64.tar
skopeo copy oci-archive:arm64.tar docker://myrepo/myimage:arm64

# 3. Create manifest list (docker CLI or podman)
docker manifest create myrepo/myimage:latest \
  myrepo/myimage:amd64 myrepo/myimage:arm64
docker manifest push myrepo/myimage:latest

Related

• Feature: container manifest subcommand for multi-arch OCI image index creation apple/container#1495 — upstream container manifest feature request (filed alongside this issue)
• [Bug]: container image push fails to register manifest digests referenced in OCI Index, causing 404s on pull apple/container#1001 — push bug with OCI Index child manifests (skopeo workaround recommended there too)
• track: exotic-arch builds (ppc64le, s390x, riscv64) — Apple QEMU support or mocker workaround #10 — exotic-arch build support (ppc64le, s390x) — dependent on manifest assembly to publish multi-arch images

Note

Responses generated with Claude

[us]

Resolved in v0.3.0.

All six subcommands shipped and verified end-to-end:

• mocker manifest create <list> [images...] ✅
• mocker manifest add <list> <image> ✅
• mocker manifest rm <list> <target> ✅ (target = platform spec or digest)
• mocker manifest inspect <list> ✅
• mocker manifest push <list> ✅ (verified via ttl.sh HTTPS — real OCI image index landed in registry)
• mocker manifest annotate <list> <child> [--os --arch --variant] ✅

Implementation took the pure-Swift path tracked in #11 (Option C — Containerization.ImageStore + LocalContentStore.newIngestSession + ContentWriter). No skopeo dependency. No upstream Apple plugin needed.

Note on annotate: only --os, --arch, --variant are exposed. ContainerizationOCI's Platform Codable drops osVersion/osFeatures on encode (see Platform.swift L284-297), so those flags wouldn't round-trip through the on-disk index. Will re-add when upstream supports them.

Closing as done.