[aledbf]

Summary

Round 4 closes the parity follow-ups left by #42, plus what checking them turned up. Every behavior was confirmed by running the TS reference (v0.89.0) and this CLI side by side. Each fix comes with a regression test that fails before the fix and passes after: a parity matrix case, a TS-recorded ts-oracle golden, or a unit test.

Breaking changes

Each commit has a BREAKING CHANGE: footer and a note in docs/migration.md.

• Git worktree common-dir mount (fix(config)!): mounted only when the config leaves workspaceMount or workspaceFolder unset, and placed under /workspaces/<main repo>/.git, as in v0.89.0. This removes an earlier backport of unreleased upstream #1261.
• upgrade (fix(cli)!, three commits):
  • --log-level accepts only TS's choices.
  • A config without Features fails with Failed to update lockfile.
  • Features resolve as build resolves them: an unfetchable Feature fails, and dependencies are included in the lockfile.
• Local Features (fix(features)!): a local Feature outside the workspace's .devcontainer/ fails, with TS's error.
• read-configuration (fix(cli)!): exits 1 when the container lookup fails, including when no Docker engine is reachable.
• exec (fix(cli)!): reads --config/--override-config without a workspace folder, and fails on a missing or invalid config.
• ${containerEnv} without a variable name (fix(cli)!): fails up, set-up, run-user-commands, exec and read-configuration, as TS does.

Output that changes for scripts (migration notes added)

• --log-format json events are no longer HTML-escaped (&<>, U+2028/9), matching JSON.stringify. The same internal/stringify helper now serves results and logs.
• Compose: docker compose config logs at info with its output, and the version detection is logged, as in TS.
• outdated:
  • JSON is indented only on a terminal.
  • Features are listed in the config's order.
  • With no Features, the text output is the table header alone.
• read-configuration featuresConfiguration is built as TS builds it:
  • every metadata property is kept, in TS's key order;
  • manifest is the registry body as served;
  • featureRef is TS's getRef object.
• upgrade:
  • No longer prints Lockfile updated..
  • A missing --config reports Dev container config (...) not found..
  • --feature/--target-version now rewrite the config, as in TS. They used to be ignored.

Other fixes

• --override-config without a base config:
  • configFilePath is .devcontainer/devcontainer.json, and relative paths resolve from there.
  • A missing override is "config not found".
• read-configuration --container-id --override-config without a workspace now reads the override (it printed {}), prints the configured workspace, and resolves ${devcontainerId}. The id labels write undefined as TS does, which also affects exec and run-user-commands.
• Unresolvable host variable: the error loses its apply host substitutions: prefix.
• Failed container lookup in exec and run-user-commands is reported as TS reports it.
• Empty or null workspaceMount is kept as written; up then mounts no workspace.
• Lockfiles are created with Node's default mode (0666 minus umask), in both build/up and upgrade.
• OCI Features take their id from their metadata, so consecutiveId and the staging folder follow a renamed Feature.
• read-configuration traces reading the Features configuration, as TS does.
• test(devtools): the git fixtures no longer inherit GIT_DIR. Under git rebase --exec they had committed into the repository being rebased and set core.bare=true in it.

Validation

Check	Result
go vet + go test ./... on each of the 32 code commits	pass
go test -race ./... (Docker unreachable)	pass
task lint	pass
task vuln	pass
go tool mutate -base origin/main -j 4	582 refused, 0 survived, 27 did not build
task spec:compliance	pass
task parity:contract	105 matched, 0 failed
task parity:semantic	pass
task parity:network	19 matched, 0 failed
task parity:runtime (Docker, full matrix)	pass (1210 s)
task test:e2e	pass
task testdata:ts-oracle:check	goldens match the reference

Left for a next round

• Feature install order: equal-priority Features install in TS's config order. Go sorts them by id, because cfg.Features is a Go map. This affects builds, and the order inside each Feature's value too. Fixing it means carrying ordered maps through the config model.
• workspaceFolder that substitutes to "": TS reports "", and Go keeps the raw string.
• read-configuration's error log level: TS logs a thrown error at debug, and Go logs it at error.
• upgrade stderr: the resolver's progress lines differ from TS's.
• Version-less Features: a Feature without a version gets the tag in Go's lockfile, while TS leaves the version out.
• Log lines Go does not emit, because it does not run the command:
  • git rev-parse: Go walks the tree for .git.
  • docker ps/inspect: Go uses the Engine API.

🤖 Generated with Claude Code