fix!: close the remaining parity follow-ups with the reference CLI

Taskfile.yml

@@ -249,16 +249,16 @@ tasks:
       - 'echo "Schema refreshed. Run ''task spec:compliance'' — any new spec property fails until modeled in internal/config/types.go."'
 
   testdata:ts-oracle:
-    desc: Rewrite every internal/**/testdata/ts-oracle/*.json with the results of the reference TypeScript functions (tools/tsoracle)
+    desc: Rewrite every internal/**/testdata/ts-oracle/*.json with the results of the reference TypeScript functions (tools/tsoracle), run in the node image versions.yaml pins (needs Docker)
     deps: [reference:compile]
     cmds:
-      - go run ./cmd/devtool ts-oracle
+      - go run ./cmd/devtool ts-oracle "$(go tool versions ref node)"
 
   testdata:ts-oracle:check:
     desc: Fail when a testdata/ts-oracle golden differs from what the reference TypeScript functions return
     deps: [reference:compile]
     cmds:
-      - go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1 -v
+      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1 -v
 
   reference:
     desc: Install and compile the TypeScript parity oracle
@@ -280,7 +280,7 @@ tasks:
       # must be in the inventory (needs reference/ checked out, so it lives here).
       - go test ./internal/cli -run TestOracleFlagCoverage -count=1
       # The ts-oracle goldens must be what the reference's functions return.
-      - go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1
+      - TS_ORACLE_IMAGE="$(go tool versions ref node)" go test ./internal/devtools -run '^TestTSOracleGoldensMatchTheReference$' -count=1
       - PARITY_REPORT_FILE={{.ROOT_DIR}}/artifacts/parity-contract.json PARITY_STRICT=true PARITY_LANE=contract PARITY_SKIP_DOCKER=true PARITY_SKIP_NETWORK=true go test ./internal/cli -run TestParityMatrix -count=1 -timeout 10m -v {{.CLI_ARGS}}
 
   parity:semantic:

docs/DIVERGENCES.md

@@ -34,6 +34,14 @@ touches a compared surface, reflected in the parity matrix.
   "additional privileges requested". This CLI starts its `docker compose` processes with
   `BUILDX_BAKE_ENTITLEMENTS_FS=0` unless the variable is already set
   (`TestWithBakeFSEntitlement`, `TestE2E_ComposeBuildLabel`).
+- **A devcontainer.json that is not valid JSONC fails to load.** TS parses the configuration
+  with jsonc-parser, whose error recovery keeps whatever it could read and reports nothing:
+  `{bad` loads as `{}`, a missing comma or trailing garbage is skipped, and
+  `{"image": , "remoteUser": "u"}` silently loses `image`. This CLI stops with the parse
+  error, naming the file, line and column (`parse config <file>: hujson: line 1, column 2:
+  ...`), because running a configuration with properties silently dropped is worse than
+  refusing it. Valid JSONC (comments, trailing commas) loads as in TS
+  (`TestLoadRejectsAConfigThatIsNotValidJSONC`).
 - **`--override-config` deep-merges** the override onto the base config, whereas TS
   replaces the config wholesale (`readDocument(overrideConfigFile ?? configFile)`). With
   no readable base, the override stands alone — identical to TS. This lets an orchestrator
@@ -72,6 +80,19 @@ touches a compared surface, reflected in the parity matrix.
   reads only the first pair and takes `B`. Variable expansion, stage lookup and the final
   stage name otherwise follow the reference (recorded in
   `internal/{docker,cli}/testdata/ts-oracle/dockerfile.json`).
+- **An unknown `${templateOption:NAME}` is always replaced with the empty string.** TS
+  `replaceTemplatedValues` reads `options[NAME]` from a plain object, so a name that is not
+  an option but an `Object.prototype` property (`constructor`, `toString`, …) becomes the
+  inherited function's source text (`function Object() { [native code] }`) in the applied
+  template. This CLI treats such a name like every other unknown option
+  (`internal/templates/testdata/ts-oracle/templates.json`).
+- **A `devcontainer-lock.json` that parses but is not shaped like a lockfile is an
+  error.** The reference keeps whatever `JSON.parse` returns and looks each Feature up with
+  `lockfile?.features[id]?.…`: an array, a number or a string throws a `TypeError` once a
+  Feature is looked up, and a `features` value that is not an object pins nothing. This CLI
+  refuses such a file when it reads it (`parse lockfile: …`). JSON that does not parse, or a
+  file that cannot be read, fails with the reference's own message, and `null`, `false`, `0`
+  and `""` are no lockfile, as in TS (`internal/features/testdata/ts-oracle/lockfile.json`).
 - **The `devcontainer.metadata` label writes object values with their keys sorted.** The
   label is TS's `JSON.stringify` of the entries: each entry's properties in TS's pick
   order (`pickFeatureProperties` for a Feature, `pickConfigProperties` for the
@@ -81,6 +102,18 @@ touches a compared surface, reflected in the parity matrix.
   given in another order (a base image's label written by another tool) is likewise
   rewritten in pick order. The parsed metadata is the same; only the label's bytes differ
   (`internal/imagemeta/testdata/ts-oracle/imagemeta.json` records both cases).
+- **Command results write nested objects with their keys sorted.** TS writes each result
+  with `JSON.stringify`, so properties come in insertion order. Go matches that order for
+  the results of `up`, `build`, `set-up`, `run-user-commands` and `read-configuration`,
+  for `featuresConfiguration`, for the top level of `configuration` (the document's
+  order, with `customizations` moved from deprecated properties and then `configFilePath`
+  last) and for the top level of `mergedConfiguration` (the configuration without
+  `mergeConfiguration`'s `replaceProperties`, then the properties it sets). Objects nested
+  deeper are written with sorted keys, because a decoded Go map keeps no order: a
+  configuration's `containerEnv` or `customizations`, merged objects such as `remoteEnv`
+  or `portsAttributes`, and each Feature in `featuresConfiguration.featureSets`, which
+  TS writes in its `devcontainer-feature.json` order. The parsed values are the same; the
+  parity matrix's `key_order` cases hold the orders that match.
 
 ## Firm decisions & scope
 
@@ -135,6 +168,13 @@ oversight.
   config, metadata and merge; `TestHookErrorDescribesTheCommandAndItsOrigin` pins the
   current choice.
 
+- **A lone surrogate in a string is written as U+FFFD.** Command results are written as
+  `JSON.stringify` writes them: `&`, `<`, `>`, U+2028 and U+2029 as they are, not
+  escaped as `encoding/json` would (`read-configuration.json-stringify-escapes-success`).
+  A configuration string holding a lone UTF-16 surrogate escape (`"\ud800"`) is the
+  exception: a Go string cannot carry one, so the JSON decoder replaces it with U+FFFD
+  when the file is read, and the result holds that character where TS writes the
+  escape back.
 - **Byte-for-byte tarball parity is unattainable** because of `mtime` differences; tarball
   contents are compared by parsed structure, not raw bytes.
 - **Cloud registry auth matrix is out of default CI scope.** The hermetic auth paths

docs/go-only-features.md

@@ -166,6 +166,12 @@ digests, when committed) and the proxy environment (`HTTP(S)_PROXY`, `NO_PROXY`,
 **hermetic** — no network, no registry resolution — so identical inputs yield the same key
 on any host.
 
+A lockfile that exists but cannot be read or parsed fails the command (exit code 1, error
+result on stdout) instead of being left out of the key, as the upstream CLI fails every
+command that reads it. An empty lockfile pins nothing and keys like no lockfile. Likewise, a
+Dockerfile-based configuration whose Dockerfile cannot be read fails the command with
+`compute cache key: read Dockerfile: …`, the file `build` would fail on.
+
 The flag is **additive**: without it, the output is byte-for-byte identical to the upstream
 CLI; with it, a `cacheKey` field is added.
 

docs/migration.md

@@ -86,6 +86,33 @@ runs the official CLI is unaffected:
   matching container.
 - Features are staged under `<tmp>/devcontainercli-<user>/container-features/`,
   one folder per build, and that folder is kept as the official CLI keeps it.
+- `build` on a Docker Compose configuration without `--image-name` reports
+  `"imageName"` as the image's name, a string, as the official CLI does. Earlier
+  releases wrapped it in an array. With `--image-name`, and for image and
+  Dockerfile configurations, it stays an array.
+- The text log on stderr follows the official CLI's two formats. With stdout
+  redirected or piped, each line starts with its UTC time
+  (`[2026-01-02T03:04:05.678Z] text`) and Stop lines appear at `--log-level debug`
+  and `trace`. With stdout on a terminal, lines keep the elapsed `[N ms]` prefix,
+  are colored and end in `\r\n`, and Stop lines appear only at `trace`. Earlier
+  releases always wrote `[N ms] text` without color. A script that parses the log
+  should read the timestamped form, or use `--log-format json`.
+- `build` and `up` write the Feature lockfile by default whenever the configuration
+  uses Features, as the official CLI does: `devcontainer-lock.json` next to
+  `devcontainer.json` (`.devcontainer-lock.json` next to `.devcontainer.json`) is
+  created when missing and rewritten when the resolved Features change. Earlier
+  releases wrote it only with `--experimental-lockfile` or `--frozen-lockfile`, so
+  the file now appears in projects that never had one. Commit it to pin the
+  Features' versions and digests, or pass `--no-lockfile` to neither read nor write
+  it. `--experimental-lockfile` is accepted but does nothing more and prints
+  `Warning: --experimental-lockfile is deprecated. Lockfiles are now enabled by
+  default.` on stderr; `--experimental-frozen-lockfile` prints a warning to use
+  `--frozen-lockfile` instead.
+- `upgrade` always rewrites the lockfile in its canonical form, even when the
+  existing one differs only in formatting.
+- Only a registry whose host is `localhost` is reached over plain HTTP. Earlier
+  releases also used plain HTTP for `127.0.0.1`, which is now addressed over HTTPS
+  like any other host. Refer to a local plain-HTTP registry as `localhost:<port>`.
 
 ## Rollback