[aledbf]

Aligns how a Dockerfile-based dev container is built with the official CLI (TS buildAndExtendImage, singleContainer.ts). Breaking: see docs/migration.md.

Before (Go)

1. build -f <workspace>/.devcontainer/Dockerfile.devcontainer.build --target <stage>. The file is written into the workspace when the final stage has no name, which fails on a read-only workspace. --push/--output were dropped when there were Features.
2. With Features, a second build FROM that image (Dockerfile.extended), re-tagged; on up, tagged …-features.

After (Go = TS v0.90.0)

• One combined Dockerfile-with-features is written to <cache>/container-features/<ver>-<ms>/, never the workspace. It holds the user's Dockerfile with its final stage named, then the dev_containers_target_stage stage that installs the Features and writes the devcontainer.metadata LABEL. With no Features, that stage only writes the label, as TS does.
• One build with --target dev_containers_target_stage. The Dockerfile and the argv are byte-identical to what TS wrote and ran for the same configs (golden-checked).
• Features and the lockfile are resolved before the build, as in TS.
• --push/--output reach the one build.
• docker history matches TS (the label is a LABEL instruction).

Go-only behavior kept, now in the single build: --secrets-file / --ca-bundle secrets, the sibling .dockerignore (#969), the final stage's own devcontainer.metadata (#1225), build contexts, and the build-auth bridge. build --omit-syntax-directive, declared but ignored before, now takes effect for Dockerfile and compose builds.

Breaking

• up tags a Dockerfile config with Features vsc-<folder>-<hash>, as TS does, no longer …-features.
• No <Dockerfile>.devcontainer.build file is written into the workspace.
• An up Feature-fetch error on this path loses the install features: prefix.

Tests

• TestBuildDockerfileBuildsOnce / TestUpDockerfileBuildsOnce assert one build, the cache-folder -f, the target, the tags, and an unchanged read-only workspace. On main they fail with permission denied; with a writable workspace they show two builds.
• TestBuildDockerfileWritesTheReferenceDockerfile: byte-exact goldens of the Dockerfile and argv, compared with TS's output.
• Unit tests for the stage, sibling .dockerignore, metadata label order, build flags, the non-BuildKit path, failures and the syntax directive.
• Runtime parity: build.read-only-workspace-dockerfile-success, up.read-only-workspace-dockerfile-success.
• Tests that asserted the two-step build are replaced. docs/DIVERGENCES.md now cites TestBuildDockerfileMetadataLabel (#1225) and TestBuildDockerfileKeepsTheSiblingDockerignore (#969).

Still different from TS (follow-ups): build --label applies to Dockerfile configs (TS ignores it there); no SELinux --security-opt label=disable for build contexts; build.args order comes from a Go map.

Validation (local, after rebasing onto main with #66)

• task lint: pass.
• task test:race with TMPDIR outside /tmp: pass.
• task parity:contract: only the 2 known /tmp/.git cases fail.
• task spec:compliance: pass (before the rebase).
• test:e2e: all pass with a longer timeout; the 5m task budget ran out under parallel load. After the rebase, TestE2E_BuildUpExec_Dockerfile, TestE2E_SiblingDockerignore and TestE2E_UpSecretsFile pass.
• PARITY_COMMAND=build task parity:runtime: 48 pass; 4 TS-timeout inconclusives pass alone.
• PARITY_COMMAND=up task parity:runtime: the only failures are the /tmp/.git remoteWorkspaceFolder group, also present on main on this machine.

🤖 Generated with Claude Code