Skip to content

Commit 236811e

Browse files
aledbfclaude
andcommitted
docs: record the divergences kept from the reference CLI
docs/DIVERGENCES.md now records, each with what TS does, what this CLI does, why, and the test that pins it, the upstream bugs still present in the reference that this CLI fixes: GPU detection through nvidia-container-cli (#319), `build [path]` (#8), a Dockerfile's own .dockerignore (#969), a stage's devcontainer.metadata label (#1225), compose `build --label` (#930), generate-docs on a single item (#876), host variables in Feature ENV lines (#308), the secretservice credential helper, the 15s credential-helper timeout, --remove-existing-container before initializeCommand (#844) and the updateUID chown of a missing home (#109). It also records the differences that can't be avoided: Mermaid node ids, the "Run:" log pairs for engine operations done through the SDK, and a digest that fails validation being refused. Two tests pin behavior no test held: generate-docs skipping metadata that is not valid JSONC, and a credential helper that hangs timing out. A relative auth realm fails in both CLIs, so its test name no longer calls it a hardening-only divergence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent d258b90 commit 236811e

5 files changed

Lines changed: 163 additions & 7 deletions

File tree

‎docs/DIVERGENCES.md‎

Lines changed: 115 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,92 @@ touches a compared surface, reflected in the parity matrix.
134134
TS writes in its `devcontainer-feature.json` order. The parsed values are the same; the
135135
parity matrix's `key_order` cases hold the orders that match.
136136

137+
The entries below fix upstream bugs that are still present upstream; each names the
138+
upstream issue it fixes.
139+
140+
- **GPU detection also asks `nvidia-container-cli`.** With `--gpu-availability detect`
141+
(the default), TS `checkDockerSupportForGPU` enables the GPU whenever `docker info`
142+
lists the `nvidia` runtime. The runtime is often installed on machines without a GPU
143+
(cloud images carry it), and `up` then fails starting a container with `--gpus all`
144+
(upstream #319). This CLI also requires `nvidia-container-cli info` to succeed when
145+
that binary is on `PATH`; without the binary it decides from `docker info` alone, as TS
146+
does (`TestCheckGPUAvailability_NvidiaCLIProbe`, `internal/cli/upstream_fixes_test.go`).
147+
- **`build [path]` builds the workspace at `path`.** TS declares the positional
148+
`build [path]` but `doBuild` never reads it, so `devcontainer build ./project` builds
149+
the current folder (upstream #8). This CLI takes the path as the workspace folder when
150+
`--workspace-folder` is not given; the flag wins when both are
151+
(`TestBuildPositionalPathIsTheWorkspace`, `internal/cli/build_repo_held_test.go`).
152+
- **A Dockerfile's own `<Dockerfile>.dockerignore` applies when the CLI builds a
153+
Dockerfile it generated.** BuildKit reads the ignore file next to the Dockerfile it is
154+
given. TS builds a Dockerfile it writes in a folder of its own (to add Features and the
155+
metadata label, also for a Compose service), so the user's
156+
`.devcontainer/Dockerfile.dockerignore` is not read and the files it excludes are sent
157+
in the build context (upstream #969). This CLI copies the ignore file next to every
158+
Dockerfile it generates (`TestCopyDockerignore`,
159+
`TestBuildAndExtendComposeDockerfileService` in `internal/cli/compose_up_held_test.go`,
160+
and `TestE2E_SiblingDockerignore` in `internal/cli/e2e_fixes_test.go`).
161+
- **A `LABEL devcontainer.metadata` in the Dockerfile is kept.** TS builds the image's
162+
metadata label from the base image's label and the configuration and writes it over the
163+
image, so a `LABEL devcontainer.metadata=…` written in the built stage of the user's
164+
Dockerfile is lost (upstream #1225). This CLI merges that stage's entries between the
165+
base image's and the configuration's (`TestStageLabelsDevcontainerMetadata` and
166+
`TestStageLabelsReadsTheNamedStage` in `internal/docker`, `TestDockerfileImageMetadata`
167+
in `internal/cli/build_held_test.go`).
168+
- **`build --label` applies to a Docker Compose configuration.** `docker compose build`
169+
takes no labels, and TS drops `--label` for a Compose configuration without a word
170+
(upstream #930). This CLI applies the labels with one more build, `FROM <image>`, tagged
171+
with the `--image-name` values or, without them, the image's own name
172+
(`TestE2E_ComposeBuildLabel`, `internal/cli/e2e_fixes_test.go`).
173+
- **`features generate-docs` and `templates generate-docs` document the folders they are
174+
given.** TS takes every entry of the project folder as an item folder: pointed at a
175+
single Feature or Template folder it looks for metadata under each of its files and
176+
documents nothing, and each top-level file (a `README.md`, a `LICENSE`) is reported with
177+
a `not found … Skipping...` warning (upstream #876). This CLI documents the folder itself
178+
when it holds `devcontainer-<feature|template>.json`, and otherwise reads only its
179+
sub-folders, skipping files without a word (`TestGenerateDocs_SingleFeatureFolder`,
180+
`TestGenerateDocs_IgnoresTopLevelFiles`, `internal/cli/collection_commands_test.go`).
181+
The metadata is also read strictly: TS's `jsonc.parse` recovers from syntax errors and
182+
documents whatever it could read, while this CLI logs `Failed to parse <file>` and skips
183+
an item whose metadata is not valid JSONC; comments and trailing commas are accepted as
184+
in TS (`TestGenerateDocs_SkipsMetadataThatIsNotValidJSONC`), for the same reason a
185+
devcontainer.json that is not valid JSONC fails to load.
186+
- **Host variables in a Feature's `containerEnv` are resolved in the image's `ENV`
187+
lines.** TS writes a Feature's `containerEnv` into the Features Dockerfile as given, so
188+
`"containerEnv": {"CACHE": "${localEnv:HOME}/.cache"}` becomes
189+
`ENV CACHE="${localEnv:HOME}/.cache"`, which BuildKit rejects (`unsupported modifier
190+
(:H) in substitution`) (upstream #308). This CLI resolves `${localEnv:…}`,
191+
`${localWorkspaceFolder}` and the other host variables before it writes the `ENV` line,
192+
as it does for the configuration's own `containerEnv`
193+
(`TestExtendImageWithFeaturesResolvesFeatureHostVars` in
194+
`internal/cli/feature_install_nodocker_held_test.go`, `TestComposeFeatureSets` in
195+
`internal/cli/compose_up_held_test.go`).
196+
- **The Linux default credential helper is `secretservice`.** When the Docker config
197+
has no `auths`, `credHelpers` or `credsStore` for any registry, TS falls back to
198+
`docker-credential-pass` when `pass` is on `PATH` and otherwise to
199+
`docker-credential-secret`, a binary that does not exist, so the fallback never finds a
200+
credential. This CLI falls back to `docker-credential-secretservice`, the
201+
libsecret helper; the `pass` choice is unchanged (`TestPlatformDefaultHelperFollowsPass`,
202+
`TestDockerConfigWithAuthSkipsPlatformDefault` in `internal/oci/auth_held_test.go`,
203+
`TestDefaultCredentialHelperName` in `internal/oci/auth_helper_test.go`).
204+
- **A credential helper that does not answer within 15 seconds is skipped.** TS waits
205+
for a helper for as long as it runs, so a helper blocked on a locked keyring or an
206+
unanswered prompt hangs the command. This CLI stops the helper after 15 seconds, warns
207+
(`Credential helper "<name>" timed out after 15s for "<registry>"; skipping it …`) and
208+
goes on without that credential (`GITHUB_TOKEN` or anonymous access)
209+
(`TestCredentialHelperThatHangsTimesOut`, `internal/oci/auth_held_test.go`).
210+
- **`up --remove-existing-container` removes the container first.** TS removes the
211+
existing container only when it looks for it to reuse, after the disallowed-Features
212+
check and after `initializeCommand` has run, so a failing `initializeCommand` or a
213+
disallowed Feature leaves the old container in place although the flag asked for it to
214+
go (upstream #844). This CLI removes it before both
215+
(`TestE2E_RemoveExistingBeforeInitialize`, `internal/cli/e2e_fixes_test.go`).
216+
- **`updateRemoteUserUID` changes the UID of a user without a home folder.** The TS
217+
`updateUID.Dockerfile` runs `chown -R $NEW_UID:$NEW_GID $HOME_FOLDER` unconditionally
218+
and unquoted, so a remote user whose home folder does not exist (a system user created
219+
with `--no-create-home`) fails the image update, and a home path with spaces is split
220+
(upstream #109). This CLI's Dockerfile chowns the home folder only when it exists, and
221+
quotes it (`TestE2E_UpdateUIDSystemUser`, `internal/cli/e2e_fixes_test.go`).
222+
137223
## Firm decisions & scope
138224

139225
- **Platform: Linux only** (amd64 / arm64). Windows and macOS are not targets — no
@@ -170,7 +256,12 @@ touches a compared surface, reflected in the parity matrix.
170256
gain), interactive `docker exec -it`, and the credential-helper protocol (external
171257
executables by design). These shell-outs receive the command's `context.Context` (via
172258
`exec.CommandContext`), so a deadline/cancel — or `Ctrl-C` — aborts an in-flight
173-
`build`/`compose` subprocess rather than orphaning it.
259+
`build`/`compose` subprocess rather than orphaning it. One consequence is visible in
260+
the log: TS runs every engine operation through the `docker` CLI (`plainExec`) and logs
261+
each one as a `Start: Run: docker …` / `Stop (N ms): Run: docker …` pair (`start` and
262+
`stop` records with `--log-format json`). An operation this CLI performs through the
263+
Docker Engine SDK (inspecting, listing, creating, starting and removing containers,
264+
lifecycle hooks) writes no such pair; the shell-outs above log a `Run: …` line.
174265

175266
## Accepted limitations
176267

@@ -199,8 +290,9 @@ oversight.
199290
- **Cloud registry auth matrix is out of default CI scope.** The hermetic auth paths
200291
(401→bearer, credential-helper protocol, `DEVCONTAINERS_OCI_AUTH`, `GITHUB_TOKEN`) are
201292
unit-tested; a real ACR (identity/refresh) / ECR / authenticated-GHCR matrix is
202-
secrets-gated and non-blocking. Credential helpers are Linux-only
203-
(`secretservice`/`pass`).
293+
secrets-gated and non-blocking. The platform default credential helper, used when the
294+
Docker config names none, is the Linux one only (`pass`, else `secretservice`; see
295+
*The Linux default credential helper is `secretservice`* above).
204296
- **TS→Go metadata interop** is exercised by `TestMetadataInteropTSToGo`, which builds
205297
the same configuration with the oracle and with this CLI and compares the merged
206298
`devcontainer.metadata` labels; it runs when the oracle is compiled (`task reference`)
@@ -213,3 +305,23 @@ oversight.
213305
- **Legacy Feature fallback via GitHub Releases** is not implemented; feature resolution
214306
is OCI-first (the supported path for v2 features). A configuration that references one fails with the
215307
resolution error (read-configuration included) instead of silently omitting the Feature.
308+
- **Mermaid node ids differ from TS.** `features info dependencies` and
309+
`features resolve-dependencies` print the dependency graph as a Mermaid flowchart. TS
310+
names each node with the first six hex digits of the SHA-256 of `JSON.stringify` of the
311+
whole graph node (`generateMermaidNode`), which includes the resolved Feature set and
312+
its metadata and the node's `dependsOn` / `installsAfter` lists, in the order a
313+
JavaScript object keeps. This CLI hashes the node's type, user Feature id, options,
314+
round priority and aliases instead, since reproducing TS's bytes would mean
315+
reproducing that whole object in insertion order. The graph's nodes, edges and labels
316+
are the same and each edge points at its node's own id; the parity harness replaces
317+
the ids with `<NODE>` (`reMermaidNode` in `normalizeStringOpts`,
318+
`internal/cli/parity_matrix_test.go`) for `features-info.dependencies-text` and
319+
`features.resolve-dependencies-success`.
320+
- **A Feature or Template reference whose digest fails validation is refused.** For
321+
`<ref>@sha256:<hex>` where `<hex>` does not match the version pattern (empty, or
322+
starting with `-`), TS `getRef` logs `Digest for input '…' failed validation` and still
323+
returns the reference, where its other checks (the digest's form and algorithm, the
324+
tag) return no reference. This CLI refuses the reference (`digest "…" does not match expected
325+
pattern`), because accepting it would weaken validation; a valid digest behaves as in
326+
TS. The `internal/oci/testdata/ts-oracle/ref.json` golden records both cases
327+
(`ghcr.io/x/y/z@sha256:`, `ghcr.io/x/y/z@sha256:-bad`), checked by `TestTSOracleRef`.

‎internal/cli/collection_commands_test.go‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,3 +127,22 @@ func TestGenerateDocs_SkipsMissingMetadata(t *testing.T) {
127127
t.Error("no README should be generated for a folder without metadata")
128128
}
129129
}
130+
131+
func TestGenerateDocs_SkipsMetadataThatIsNotValidJSONC(t *testing.T) {
132+
base := t.TempDir()
133+
writeFeature(t, base, "broken", `{"id":"broken" "name":"Broken"}`)
134+
writeFeature(t, base, "jsonc", "// comment\n{\"id\":\"jsonc\",\"name\":\"JSONC\",}")
135+
if err := generateDocs(base, "ghcr.io", "o/r", "", "", "feature", "info"); err != nil {
136+
t.Fatalf("an unparsable Feature must be skipped, not fail the command: %v", err)
137+
}
138+
if _, err := os.Stat(filepath.Join(base, "broken", "README.md")); !os.IsNotExist(err) {
139+
t.Errorf("README generated from metadata that is not valid JSONC (stat err %v)", err)
140+
}
141+
got, err := os.ReadFile(filepath.Join(base, "jsonc", "README.md"))
142+
if err != nil {
143+
t.Fatalf("README for valid JSONC metadata: %v", err)
144+
}
145+
if !strings.Contains(string(got), "# JSONC (jsonc)") {
146+
t.Errorf("README heading missing:\n%s", got)
147+
}
148+
}

‎internal/oci/auth_held_test.go‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,12 @@ import (
44
"bytes"
55
"encoding/base64"
66
"os"
7+
"os/exec"
78
"path/filepath"
89
"runtime"
910
"strings"
1011
"testing"
12+
"time"
1113

1214
"github.com/devcontainers/cli/internal/log"
1315
)
@@ -154,3 +156,23 @@ func TestCredentialHelperOutcomesLog(t *testing.T) {
154156
})
155157
}
156158
}
159+
160+
func TestCredentialHelperThatHangsTimesOut(t *testing.T) {
161+
sleep, err := exec.LookPath("sleep")
162+
if err != nil {
163+
t.Skip("no sleep binary")
164+
}
165+
pathOnly(t, map[string]string{"docker-credential-hangs": "exec " + sleep + " 60"})
166+
var buf bytes.Buffer
167+
logger := log.New(log.Options{Writer: &buf, Level: log.LevelWarning})
168+
start := time.Now()
169+
if cred := getCredentialFromHelper("reg.io", "hangs", logger); cred != nil {
170+
t.Fatalf("credential = %#v, want none", cred)
171+
}
172+
if elapsed := time.Since(start); elapsed < 15*time.Second || elapsed > 30*time.Second {
173+
t.Errorf("helper given up after %s, want 15s", elapsed)
174+
}
175+
if want := `Credential helper "hangs" timed out after 15s for "reg.io"`; !strings.Contains(buf.String(), want) {
176+
t.Errorf("warning log %q lacks %q", buf.String(), want)
177+
}
178+
}

‎internal/oci/authpolicy_held_test.go‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,11 @@ func TestForbiddenChallengeIsInspected(t *testing.T) {
165165
}
166166

167167
// TS fails the authentication when `new URL(realm)` throws, as it does for a
168-
// relative realm; Go refuses such a realm under hardening as unparsable.
169-
func TestRelativeRealmIsUnparsableUnderHardening(t *testing.T) {
168+
// relative realm, with or without hardening. Go fails it in both modes too:
169+
// under hardening this transport refuses it as unparsable; without hardening
170+
// it passes the challenge on and oras-go's validateRealm rejects a realm whose
171+
// scheme is not http or https. Only the error text differs from TS.
172+
func TestHardeningRefusesARelativeRealmAsUnparsable(t *testing.T) {
170173
policy, err := NewAuthPolicy(true, nil, log.Null)
171174
if err != nil {
172175
t.Fatal(err)

‎internal/oci/testdata/ts-oracle/ref.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -527,7 +527,7 @@
527527
"args": [
528528
"ghcr.io/x/y/z@sha256:"
529529
],
530-
"divergence": "unresolved: TS logs a digest that fails validation and still returns the reference (containerCollectionsOCI.ts has no return there); ParseRef rejects it. Matching TS would weaken validation (AGENTS.md), so this needs a decision",
530+
"divergence": "docs/DIVERGENCES.md: a digest that fails validation is refused; TS logs the error and still returns the reference (containerCollectionsOCI.ts has no return there)",
531531
"result": {
532532
"scheme": "https",
533533
"id": "z",
@@ -554,7 +554,7 @@
554554
"args": [
555555
"ghcr.io/x/y/z@sha256:-bad"
556556
],
557-
"divergence": "unresolved: TS logs a digest that fails validation and still returns the reference (containerCollectionsOCI.ts has no return there); ParseRef rejects it. Matching TS would weaken validation (AGENTS.md), so this needs a decision",
557+
"divergence": "docs/DIVERGENCES.md: a digest that fails validation is refused; TS logs the error and still returns the reference (containerCollectionsOCI.ts has no return there)",
558558
"result": {
559559
"scheme": "https",
560560
"id": "z",

0 commit comments

Comments
 (0)