[aledbf]

Summary

The parity matrix, unit tests and e2e suites stayed green while the CLI still differed from the reference in ways nobody had written a case for. This PR adds two kinds of tests that take expected values from the reference itself rather than from hand-written cases, and fixes everything they found.

• TS oracle goldens (tools/tsoracle, internal/tsoracle). The oracle runs the reference's own functions from reference/src, bundled with the reference's esbuild, over JSON cases. task testdata:ts-oracle records the results in internal/*/testdata/ts-oracle, and the Go ports are compared against them. A case marked divergence has to keep differing, so fixing it means deleting the mark. About 480 cases cover the Dockerfile helpers, mergeConfiguration and the metadata label, the Feature build helpers, variable substitution and devcontainerIdForLabels, getRef, the compose helpers, and more.
• Differential runtime tests (TestDifferentialUp, TestDifferentialBuild, next to TestDifferentialReadConfiguration). Each one runs up or build on every upstream fixture with both CLIs and compares what a user sees: the JSON result, the container and image configuration (with devcontainer.metadata parsed), mounts, and id inside the container. The known-differences list can only shrink. Ten entries remain, all the accepted legacy GitHub Release Feature limitation (5 fixtures × up/build).

Bugs fixed

Each fix comes with a golden case, a unit test or a parity case that fails before the fix.

• ${devcontainerId} hashed labels with &<> and U+2028/U+2029 escaped and keys sorted by bytes, so some label sets produced a different id.
• A stage name lost its case (AS Final), CRLF Dockerfiles got AS after the \r, and a Dev target was not found. Nested defaults like ${IMG:-${REG}/app}, the unresolved-variable error, ${...Basename} of /, and win32 trailing separators all differed too.
• devcontainers-contrib refs were not redirected to devcontainers-extra. The features label escaped && and <>. readComposeVersionPrefix kept \r. parseMount cut source=/a=b in the wrong place. mergeConfiguration took runArgs from metadata entries, where TS takes them from the config only.
• The metadata label is where and as the reference puts it. It holds the raw entries (base image, Features, the config's picked properties, unsubstituted). It goes on the container only for an image with no Features, and on the image otherwise. It is written as JSON.stringify writes it. Containers are read back the way getImageMetadataFromContainer reads them.
• Compose build goes through docker compose build with the label override, so the image carries compose's labels and the project name follows getProjectName. --secrets-file does not apply there (documented).
• up's Features image now gets the config's containerEnv as ENV lines, as build already did.
• Base images resolve with the automatic platform ARGs, so FROM img-$TARGETARCH names the right image. EnsureFinalStageName now returns TS's errors for a Dockerfile with no FROM, or with an unparseable final FROM.
• exec probes the environment as the configured remoteUser. Before, it probed as the metadata user and gave the command that user's HOME and PATH. New runtime parity case: exec.config-remote-user-probe-success.
• read-configuration exits 1 when --container-id cannot be inspected. New parity case: read-configuration.container-id-missing-error.
• compose config errors and legacy Feature errors are ContainerErrors, and a failed array lifecycle command is named as TS names it.

Deliberate divergences (docs/DIVERGENCES.md, each recorded as a golden divergence case)

• A final FROM line continued with a backslash keeps its stage name. TS reads only the physical line and writes FROM \ AS dev, a Dockerfile no builder accepts. Here BuildKit reads the stage's name, and every other FROM line is handled exactly as TS handles it.

• Dockerfile ARG/ENV values are read with BuildKit's parser. Upstream fixes #1213 (colons in ${localEnv:VAR:default}) and #881 (:ro in compose volumes) were already ported, and both are newer than the pinned reference. Object keys inside metadata label values are sorted.

• Compose builds may read the Features Dockerfile outside the build context. Now that a compose build goes through docker compose build, bake on buildx ≥ 0.38 refused the Features Dockerfile, written in the cache folder, unless --allow=fs.read was passed, which compose cannot do. TestE2E_ComposeBuildLabel failed this way on the runners. The reference fails there too. This CLI starts its compose processes with BUILDX_BAKE_ENTITLEMENTS_FS=0 unless that variable is already set.

A # escape= directive now follows TS (recorded in the golden).

CI gate for the goldens

testdata:ts-oracle:check was not run by any CI job, so a stale golden would never be caught. TestTSOracleGoldensMatchTheReference compares every golden with what the reference returns now, and task parity:contract, which CI runs after task reference, now runs it too. It caught a hand-edited golden in this branch.

Validation

Check	Result
go vet ./... on every commit	pass
go test -race ./... (Docker unreachable)	pass
task lint	pass
task parity:contract (incl. the new oracle gate)	pass
TestDifferentialReadConfiguration	pass
TestDifferentialUp / TestDifferentialBuild (Docker, local)	pass (up 15 min, build 11 min); skipped: the 5 known legacy-Feature fixtures and 4 arm64 fixtures
go tool mutate over this diff, Docker unreachable, -j 1	547 refused, 0 survived, 53 did not build

go tool mutate -j 4 reported false survivors in extendImageWithFeatures, a different set on each run. Every one of them was refused when run serially, or when the mutation was applied by hand. Mutants that write into the package directory interfere with each other's runs; this is a go-tools follow-up, and it changes nothing here.

🤖 Generated with Claude Code