ossein-docker: a docker-shaped front for build, run, pull, stop

[closer-claudio]

cmd/ossein-docker: a docker-shaped front for the docker invocations farcloser projects actually make — build, run, pull, stop, version — with the flags they actually pass (surveyed: forkcloser/curl's build-posix.sh, the bench scripts, the website copy). Anything else is refused loudly (unknown flag/subcommand is an error, never a silent no-op). Meant to be installed as docker on the hermetic PATH (aqua packaging follows in limen once a release carries both binaries). Where docker and ossein disagree, docker wins.

What it does

• run / pull / stop: execve into the sibling ossein (flags already docker-shaped). Translates docker's --cpus 1.5 (rounded up), --memory in docker's grammar (8g, 8gb, 512MiB, 1.5g), --network none; keeps -it, commas in -e, puts -- before the image. A run that sizes nothing gets the whole host (every CPU, all memory — backed lazily), as a docker container does; ossein run's own 2 vCPU / 4 GiB do not apply through the front. stop requires an id, as docker requires a container: a bare stop would have stopped every builder on the machine, which docker never does.
• build / buildx build: the buildkit client library (pinned v0.32.0, same as the daemon image), not buildctl. Starts or reuses this directory's buildkit microVM via ossein buildkit --detach, sized like a daemon (the whole host); solves with dockerfile.v0 (context + Dockerfile as local mounts; -t -f --build-arg --platform --target --no-cache --pull --progress -q); exports an OCI layout and imports every -t tag into ossein's image cache, flattened right away — so docker run <tag> resolves offline. -q without -t is refused: docker would print an image ID, but an untagged build leaves ossein nothing runnable to name, and printing nothing would be the silent divergence this front exists to refuse.
• Registry credentials for FROM: a Credentials-only session attachable backed by go-containerregistry's default keychain (docker login). Not buildkit's authprovider, which would have pulled docker/cli and an MPL-2.0 HTTP helper (rejected by the license lane).

ossein-side changes (first commit)

• ossein buildkit --detach is now idempotent per cache: each instance records buildkit.json (cache dir + socket) in its state dir; a second detach for a cache a live instance serves reprints its BUILDKIT_HOST and exits 0 instead of failing on the lock. A booting instance is waited for, never killed. Foreground and explicit --sock unchanged.
• --cpus 0 / --memory 0 on run and buildkit mean the whole host: the host's logical CPU count and physical memory, each capped at what Virtualization.framework allows for one guest (vm.HostMaxCPUs, vm.HostMaxMemoryMiB). The framework's own maximum is not the host's (64 CPUs on an 18-core machine), hence the cap on the host's count. 0 is docker's spelling of "no limit" and is what the front passes; ossein's defaults are untouched.
• image.Import: records a locally built image under a tag exactly like a registry resolution; marked local so a reclaimed blob says "rebuild" rather than re-fetching a digest no registry has.
• Drive-by fix: kong splits repeated flag values on commas by default, so ossein run -e LIST=a,b arrived as two variables. sep:"none" on -e, --env-file, -v.
• What both binaries must agree on lives in internal/cli: the logger, the --log-level vocabulary, the exit convention, and cli.WholeHost — the one definition of "0 = the whole host" both sides use. One record builder, newResolution, serves Resolve and Import; an imported tag now carries the same manifest chain as a pulled one, and a record Resolve fails to write is logged, not swallowed.

Release / lint

• Second goreleaser build (ossein-docker) in the same archive, no entitlement (it never touches Virtualization itself).
• go-licenses cannot locate the Apache-2.0 license of the two in-toto modules the client pulls (module-layout false positive, LICENSE file in repo root is ignored google/go-licenses#186): --ignored in the Justfile with the reason; both licenses read from the module cache.
• Rebased onto the limen 0.3.0 convergence (tools/ → hack/, tool directives in tools/go.mod) and onto image: write the resolution record durably #14 and image: a digest-pinned ref only trusts a record that hashes back to it #13: the resolution record keeps its manifest chain and is written durably; Import records carry the local flag on top of that and write through the same path, checked. go.mod carries the three direct dependencies, tidied on main.

Verification

• just lint and just test green locally. Unit tests cover argv translation (including the whole-host default and docker's memory grammar), frontend attrs, tag normalization, OCI-layout selection (attestations skipped, platform matched, nested-index errors not masked), Import → offline Resolve → cached rootfs, instance discovery, the -q-without--t and bare-stop refusals.
• Verified live on an 18-core / 64 GiB Mac with build/docker symlinked to ossein-docker:
  • docker build --build-arg GREETING=hi -t smoke:dev . → alpine pulled through the builder, RUN executed, tag imported; docker run --rm smoke:dev printed the build-arg'd file offline.
  • unsized docker run: guest saw nproc=18, 64 GiB; --cpus 1.5 --memory 1gb: nproc=2, 1 GiB.
  • -e LIST=a,b arrived intact; docker build -q . refused (125) with the message; -q -t printed the digest only; buildx build works; second ossein buildkit --detach said reusing; bare docker stop refused; docker stop <id> stopped only that one.
• First consumer: forkcloser/curl's build-posix.sh (Forkcloser session), adapted to docker run … on macOS; its linux-arm64/amd64 legs will be run against this branch's just build output.