dev_container: Align compose project name with reference CLI and recover from mixed-version duplicates

[antont]

Stacked on zed-industries#54068 (detection). When reviewing, read zed-industries#54068 first.

In antont/zed fork this PR is retargeted to base fix-docker-ps-multi-container so the stack is visible; when upstreamed, rebase onto main and set base to zed-industries:main.

Summary

This PR ships two related changes together, because the second keeps the first from regressing upgraders:

1. Match @devcontainers/cli's full getProjectName precedence. Replaces safe_id_lower(devcontainer.json's name) with the same five-step chain the reference CLI walks (see src/spec-node/dockerCompose.ts in devcontainers/cli):

   1. COMPOSE_PROJECT_NAME from the local environment.
   2. COMPOSE_PROJECT_NAME= in the workspace .env file.
   3. Top-level name: on the merged compose config, when at least one fragment declared it explicitly.
   4. ${workspaceFolderBasename}_devcontainer — only when the first compose file's directory is <workspace>/.devcontainer/.
   5. Otherwise, the plain basename of the first compose file's directory (no suffix).

   The old Zed implementation diverged at every one of those inputs: any user setting COMPOSE_PROJECT_NAME, shipping a .env with one, declaring a top-level compose name:, or pointing dockerComposeFile outside .devcontainer/ (e.g. "../docker-compose.yml") got a different project namespace than the CLI and VS Code, producing two compose projects for the same folder.

2. Mixed-version tiebreak. When check_for_existing_container's label-based lookup returns two candidates (because a pre-fix Zed left a container under the legacy project name alongside a CLI-style one), prefer the container whose com.docker.compose.project label matches the value the new derivation produces. Log the ignored legacy orphan. Two non-canonical candidates still surface MultipleMatchingContainers (dev_container: Detect error state when docker ps returns duplicate containers zed-industries/zed#54068's safety net).

Without the tiebreak, the derivation fix would turn the existing silent-duplicate state on upgrade into a hard MultipleMatchingContainers error. Shipping both makes the change a transparent upgrade in the common case while preserving CLI-parity in the long tail.

As a concrete example exercising rule 4 — a folder devcontainer-compose-test/ with "name": "Compose Duplicate Repro" and docker-compose.yml in .devcontainer/, no .env and no explicit compose name::

• Old Zed → compose_duplicate_repro
• CLI / VS Code → devcontainer-compose-test_devcontainer
• New Zed → devcontainer-compose-test_devcontainer (matches CLI)
• On upgrade, if both already exist: new Zed reuses devcontainer-compose-test_devcontainer, logs the compose_duplicate_repro orphan.

Adds a small sanitize_compose_project_name() helper that implements the CLI's sanitization rules (lowercase + strip [^-_a-z0-9]) — notably preserving hyphens, which safe_id_lower would have replaced with underscores.

Adds two helpers used by the precedence walk:

• parse_dotenv_compose_project_name — line scan extracting COMPOSE_PROJECT_NAME=… from the workspace .env, matching the subset the CLI's regex dotenv reader recognizes.
• compose_fragment_declares_name — parses a compose fragment via serde_yaml and checks for a name key on the root mapping (block, quoted, or flow style all work), matching the CLI's own yaml.load. docker compose config always injects name: devcontainer into its merged output when no fragment declared one, so rule 3 needs to distinguish the user-provided case from the injected default — this helper supplies that signal. On YAML parse failure it returns "not declared" (rule 4 applies), matching the CLI's fallback.

project_name() becomes async and fallible (async fn project_name(&self) -> Result<String, DevContainerError>) so it can load the .env file and each compose fragment via self.fs.load. Four call sites now .await? the derivation. Real I/O errors on the .env read propagate as FilesystemError (matching the CLI's narrow ENOENT/EISDIR swallow); fragment-rescan read errors are logged and skipped (matching the CLI's broader try/catch over its fragment read + parse).

The name field is still used as the features image-tag prefix (generate_features_image_tag); only the compose project namespace is decoupled from it.

Adds a compose_project field on DockerConfigLabels, serde-renamed to com.docker.compose.project, consumed by the tiebreak's inspect call.

New dependency: serde_yaml_ng

This PR adds a new workspace dependency on serde_yaml_ng = "0.10" (a YAML parser), pulled in only by dev_container. Its entire use is one call in compose_fragment_declares_name that parses a compose fragment to check whether the root mapping has an explicit name: key. That signal is required by getProjectName rule 3 — docker compose config injects a default name: devcontainer into its merged output whenever no fragment declared one, so the only way to distinguish the user-declared case from the injected default is to re-parse each fragment the user wrote. The reference CLI does this via yaml.load. We originally tried a line-based scanner here; a reviewer correctly pointed out (zed-industries#9 in the commit list) that it missed quoted keys and flow-style root mappings, so the scanner was replaced with a real YAML parse.

serde_yaml_ng rather than serde_yaml because dtolnay's serde_yaml is archived and publishes as 0.9.34+deprecated. serde_yaml_ng (acatton) is an active minimal fork with attribution intact, declared drop-in compatibility with serde_yaml's Value/from_str/Mapping API, and no outstanding community concerns. The other notable fork, serde_yml (sebastienrousseau), is also archived and has community concerns about stripped attribution from the dtolnay original — skipped on both counts.

Happy to take guidance here — swap to a different crate, keep the deprecated serde_yaml, or anything else the reviewers prefer.

Why

Full write-up with verified fixtures and captured output: #5

Three failure modes from the same root cause, all resolved by this change:

1. Interop — opening a folder in both Zed and devcontainer up (or Zed on one version and VS Code on another) creates two compose projects with identical devcontainer.local_folder + devcontainer.config_file labels, breaking the spec's uniqueness invariant.
2. Cross-worktree silent db/volume reuse — if multiple git worktrees share a devcontainer.json with the same name, Zed uses the same compose project for all of them; Compose reuses stateful siblings (db, cache, localstack) by config-hash, so worktree B silently inherits worktree A's database. Fixture + captured output: https://github.com/antont/zed-devcontainer-db-share-repro
3. Mixed-version Zed sessions — Rust impl landed in stable v0.232.2 (2026-04-15, Dev containers native implementation zed-industries/zed#52338). Older Zed (≤v0.231.x) shelled out to @devcontainers/cli so it used the reference derivation. The collision shows up when new Zed has already created a container under the name-field project and a CLI-derivation tool (old Zed, devcontainer up, VS Code) runs against the same folder afterwards — the reverse order does not duplicate, because new Zed's label-first lookup reuses the existing CLI-style container. So a v0.231.x → v0.232+ upgrade by itself isn't a reproducer; a mixed-version rhythm where the name-field container was created first is. The tiebreak lets new Zed transparently adopt the canonical container when both already exist.

This PR is a companion to zed-industries#54068 (duplicate-detection on the lookup side). This one fixes the root cause and handles graceful recovery; that one catches remaining genuine ambiguity on the label-lookup path.

Migration / compatibility

Existing Zed-created containers (under the old safe_id_lower(name) project) are still found via check_for_existing_container, which looks them up by devcontainer.local_folder + devcontainer.config_file labels, not by project name. So on first run after upgrade, the existing container is reused; the tiebreak covers the case where both a legacy container and a CLI-style container coexist. No user action required.

Test plan

• cargo test -p dev_container --lib — 86 passed, including:
  • sanitize_compose_project_name_matches_cli_rules
  • --project-name assertion added to test_spawns_devcontainer_with_docker_compose
  • check_for_existing_container_prefers_canonical_compose_project
  • check_for_existing_container_errors_when_none_canonical
  • should_deserialize_inspect_with_compose_project_label
  • derive_project_name_env_wins_over_everything
  • derive_project_name_dotenv_wins_over_compose_and_fallback
  • derive_project_name_compose_name_wins_over_fallback
  • derive_project_name_skips_compose_name_when_not_explicitly_declared
  • derive_project_name_omits_suffix_when_compose_file_outside_devcontainer_dir
  • compose_fragment_declares_name_detects_top_level_name_key (covers block, quoted-key, and flow-style roots, plus parse failure → not-declared)
  • is_missing_file_error_only_accepts_notfound_and_notadirectory
• cargo fmt --all — clean
• cargo clippy --workspace --release --all-targets --all-features -- --deny warnings — clean
• End-to-end with fixture antont/zed-devcontainer-compose-test:
  • Build zed from this branch.
  • Clean slate: docker ps -a --filter "label=devcontainer.local_folder=$PWD" -q | xargs -r docker rm -f
  • zed --dev-container /Users/antont/src/devcontainer-compose-test → Zed creates container under project devcontainer-compose-test_devcontainer (was compose_duplicate_repro before the fix).
  • devcontainer up --workspace-folder $PWD → CLI reports the same containerId Zed created; no second compose project is introduced.
  • Captured: devcontainer-compose-test_devcontainer-app-1 (ID b0cfb5836f92), composeProjectName: "devcontainer-compose-test_devcontainer" reported by both tools.

Commits

1. Derivation RED — pins --project-name expectation to the CLI derivation, no production change. Commit message captures the exact failure output.
2. Derivation GREEN — implements rule 4 (the ${folderBasename}_devcontainer branch), adds the CLI-parity sanitization helper + unit test. Remaining rules land in commits 7–8.
3. Tiebreak RED — failing multi-match test with canonical vs legacy inspect overrides.
4. Tiebreak GREEN — adds pick_canonical_container, routes the MultipleMatchingContainers error arm through it.
5. Serde coverage — deserialization test for the com.docker.compose.project label rename, confirming the new typed field round-trips.
6. Readability — collapses the passthrough arms in check_for_existing_container to result => result so the multi-match interception stands out as the only non-trivial arm. No behavior change.
7. Precedence RED — pins the full five-step CLI precedence via a pure derive_project_name helper and five focused tests (one per rule plus the rule-3 edge case). Commit message captures the RED output.
8. Precedence GREEN — fills in derive_project_name, adds parse_dotenv_compose_project_name and compose_fragment_declares_name scanners, and converts project_name() to async so it can load .env and each compose fragment.
9. Tighten helpers to CLI semantics — addresses two review findings: (a) .env read failures now propagate unless the error is NotFound/NotADirectory (matching the CLI's narrow ENOENT/EISDIR swallow), preventing silent fallback to a non-canonical project name when a workspace has an unreadable .env; (b) compose_fragment_declares_name now parses fragments as YAML via serde_yaml rather than line-scanning, so quoted keys and flow-style root mappings are honored just like the CLI's yaml.load. project_name() becomes Result<_, DevContainerError>; four call sites propagate with ?.
10. Swallow read errors in compose fragment rescan — review follow-up on Copy element debug JSON to the clipboard on cmd-alt-i zed-industries/zed#9. The reference CLI's getProjectName wraps fragment readFile+yaml.load in one try/catch that ignores every failure (dockerCompose.ts 663-673); the prior commit propagated non-missing read errors as FilesystemError, which would fail the whole devcontainer flow for fragments the CLI would have silently skipped. Switches the loop to log + continue on any fs.load failure. The stricter .env policy stays — it mirrors a separate, narrower CLI branch.

Commits 1–2, 3–4, and 7–8 each follow a TDD RED/GREEN pattern; each RED/GREEN commit message captures the transition output.

Release Notes:

• Fixed dev container Docker Compose project name now matches the full getProjectName precedence from the reference devcontainer CLI (COMPOSE_PROJECT_NAME in the environment, then in the workspace .env, then an explicit top-level name: on the merged compose config, then the basename of the first compose file's directory — with the _devcontainer suffix only when that directory is <workspace>/.devcontainer). This prevents duplicate containers when the same folder is opened with both Zed and the devcontainer CLI / VS Code, or with both new Zed and older Zed (≤v0.231.x) that shelled out to the CLI. On first run after the fix, if both a legacy-named and a CLI-style container exist, Zed now reuses the canonical one and logs the orphan instead of erroring.