feat: build — install features + write lockfile for Dockerfile builds (PR-4c)#41
Merged
Conversation
Phase 1 of lockfile graduation per docs/ROADMAP_TO_1.0.md. Ships the schema parity fixes, the user-visible CLI flag surface, the writer helper, and upstream-aligned error messages. The actual writer integration (building a Lockfile from resolved features and writing it after `up`/`build`) is tracked as PR-4b at issue #32. ## Schema parity (deacon-core/lockfile.rs) - LockfileFeature.depends_on now serializes as `dependsOn` (camelCase) via #[serde(rename)], matching upstream `devcontainers/cli`'s generateLockfile in src/spec-configuration/lockfile.ts. Deserializer accepts the camelCase form on read. - write_lockfile() emits a trailing newline to match upstream `JSON.stringify(..., 2) + '\n'`. Byte-identical output keeps the --frozen-lockfile content comparison stable. - LockfileValidationResult::format_error() now emits upstream-aligned strings: "Lockfile does not exist." / "Lockfile does not match." as the leading summary line; trailing actionable guidance references the graduated --frozen-lockfile flag rather than the deprecated --experimental-frozen-lockfile. - New LockfileFeature::from_resolved() helper constructs entries in the upstream canonical form (resolved = "{registry}/{repo}@{digest}", integrity = "{digest}"). This is the writer entry point PR-4b uses. ## CLI surface graduation up + build both gain: - --no-lockfile (visible): skip lockfile generation and verification. - --frozen-lockfile (visible): require an up-to-date lockfile; fail if resolution would change it. Mutual exclusivity (--no-lockfile xor --frozen-lockfile) enforced in the CLI layer, mirroring upstream's pre-parse validation. Deprecation: - --experimental-lockfile and --experimental-frozen-lockfile remain accepted as hidden aliases through the 1.x line. The CLI emits a WARN on use directing users to the graduated flags. - effective_frozen = frozen_lockfile || experimental_frozen_lockfile matches upstream's effectiveFrozenLockfile coalescing. ## Downstream consumers - up/mod.rs frozen-validation path now reads args.frozen_lockfile (the effective value) instead of args.experimental_frozen_lockfile. No behavior change — only the variable name moves. - build/mod.rs args struct gains no_lockfile + frozen_lockfile fields (carrier-only for PR-4b; #[allow(dead_code)] until then). ## Tests Added in deacon-core/lockfile.rs: - test_depends_on_serializes_as_camel_case - test_write_lockfile_emits_trailing_newline - test_from_resolved_constructs_upstream_form Updated in deacon/tests/up_lockfile_frozen.rs (5 assertions): align with the new upstream-format error messages ("Lockfile does not exist." / "Lockfile does not match." / capital "F" on "Features ..." substrings). ## Verified - cargo fmt --all -- --check - cargo clippy --all-targets -- -D warnings - cargo nextest run --profile dev-fast --no-default-features: 1930/1930 pass - cargo test --doc --workspace: 130/130 pass ## Follow-up tracked - #32 — PR-4b: wire writer in up + build feature pipeline. - Build-command lockfile wiring is gated on the pre-existing TODO at build/mod.rs:1285 (build doesn't install features today). Will land with #32 or as a sibling PR. ## Refs - docs/ROADMAP_TO_1.0.md Tier 1 item "Lockfile graduation" - Upstream: devcontainers/cli#1212 (graduated lockfile in v0.87.0) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Follow-up to PR-4a (#33): the user-visible flag surface, schema parity fix, and upstream-aligned error strings landed there, but the actual writer was never invoked. This wires it in. After feature resolution + download, build a Lockfile from the resolved feature set (`build_lockfile_from_features` mirrors upstream `generateLockfile`), thread it back via FeatureBuildOutput, then: - default: write `{config_dir}/devcontainer-lock.json` (sorted by key, trailing newline — byte-identical to upstream `writeLockfile`) - `--frozen-lockfile`: byte-compare against on-disk; fail with the upstream summary strings (`"Lockfile does not exist."` / `"Lockfile does not match."`) so existing CI scripts keep working - `--no-lockfile`: skip entirely - deprecated `--experimental-lockfile <PATH>`: still honored for the custom-path form (hidden alias path through the 1.x line) Wired into both single-container (`container.rs`) and compose (`compose.rs`) flows via shared `handle_lockfile_post_build` helper. EROFS/EACCES on the write path downgrades to a WARN so read-only workspaces (CI mounts, read-only volumes) don't break `up`. Lockfile keys are the user-provided feature ID (e.g. `ghcr.io/devcontainers/features/node:1`), not the canonical no-tag form — matching upstream and keeping the existing pre-build structural validation aligned. Build (`crates/deacon/src/commands/build/mod.rs`) is intentionally out of scope — see issue #32 and the standing TODO at build/mod.rs:1285. That's PR-4c. Closes #32 (PR-4 phase 2 of the lockfile graduation track). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… (PR-4c) Removes the long-standing "Feature installation during build is not yet implemented" fail-fast for the Dockerfile-based build path, and wires the PR-4b lockfile writer into `build`'s post-build flow. ## What this PR does When `deacon build` is invoked against a Dockerfile-based config with features declared: 1. Run the user's `docker build` as before (Dockerfile, build args, cache, labels — all unchanged). 2. **NEW** — layer features on top of the just-built image: synthesize a single-container config with `image: <built_image_id>` and call `up`'s existing `build_image_with_features` helper. That helper resolves + downloads features, generates a BuildKit RUN-mount stage per feature, and produces a feature-extended image + a `Lockfile`. 3. **NEW** — write the lockfile next to `devcontainer.json` via `deacon_core::lockfile::write_lockfile(force_init = true)`. Read-only workspaces (EROFS/EACCES) downgrade to a WARN so CI mounts don't fail. 4. Update `final_result.image_id` to the feature-extended image so downstream consumers (cache, scan, output, push) see the right tag. Compose-based and image-reference builds still fail fast with features — their integration patterns differ enough to warrant separate follow-ups. ## Cache invalidation When features are present, the cache check is skipped (`!features_present` gate added). The current `config_hash` derives from `build_config` only — it does not fold in feature digests, so a cached hit would point at the base image without feature layers. Skipping the cache when features are present trades a rebuild for correctness; a later refinement can include feature digests in the hash for cacheable feature builds. ## Module visibility `crates/deacon/src/commands/up/mod.rs` — `features_build` module was private; promoted to `pub(crate)` so the build command can call `build_image_with_features` without copying ~500 LoC of feature pipeline into `commands/build/`. A future cleanup can lift the helper into a shared `commands/shared/` module. ## Tests 3 new unit tests in `build::tests`: - `is_readonly_filesystem_error_detects_permission_denied` - `is_readonly_filesystem_error_ignores_unrelated_io_errors` (NotFound etc. must propagate so real bugs aren't hidden) - `is_readonly_filesystem_error_ignores_non_io_errors` These pin the WARN-vs-error decision for the lockfile write path. The actual feature-install + lockfile-write integration tests require Docker + BuildKit + an OCI registry; they belong in an integration test suite that I haven't added here (test grouping under `docker-shared` is the right home). Verification: - `cargo fmt --all -- --check` - `cargo clippy --all-targets -- -D warnings` - `cargo test -p deacon --lib` → 229 pass (no regression; 3 new tests) ## Base branch Based on `pr4b-lockfile-writer-wiring` (#35) since this PR consumes `FeatureBuildOutput.lockfile` (the field PR-4b added). Auto-rebases to `main` once #33 and #35 land in order. With this PR, the `build` command supports features for Dockerfile-based configs and writes a lockfile alongside — closes the lockfile track's remaining 1.0 work (PR-4c on issue #34). Refs: issue #34 (Tier 1 progress tracker); PR-4b (#35). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pofallon
added a commit
that referenced
this pull request
May 25, 2026
…ng-build (#45) Follow-up to the Tier 1 merge cascade — closes out the [Unreleased] section with entries for the two tracks that landed after PR-7 (#31) was first drafted: - `upgrade` subcommand (PR-5a #44 + PR-5b #40 pinning) - features-during-build for Dockerfile configs (PR-4c #41) The lockfile and set-up entries were added earlier in commit e6b929c. This commit completes the Unreleased section. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Removes the long-standing "Feature installation during build is not yet implemented" fail-fast for the Dockerfile-based build path, and wires the PR-4b lockfile writer into `build`'s post-build flow.
With this PR, the `build` command supports features for Dockerfile-based configs and writes a lockfile alongside — closes the lockfile track's remaining 1.0 work (PR-4c on issue #34).
What this PR does
When `deacon build` is invoked against a Dockerfile-based config with features declared:
Compose-based and image-reference builds still fail fast with features — their integration patterns differ enough to warrant separate follow-ups.
Cache invalidation
When features are present, the cache check is skipped (`!features_present` gate added). The current `config_hash` derives from `build_config` only — it does not fold in feature digests, so a cached hit would point at the base image without feature layers. Skipping the cache when features are present trades a rebuild for correctness; a later refinement can include feature digests in the hash for cacheable feature builds.
Module visibility
`crates/deacon/src/commands/up/mod.rs` — the `features_build` module was private; promoted to `pub(crate)` so the build command can call `build_image_with_features` without copying ~500 LoC of feature pipeline into `commands/build/`. A future cleanup can lift the helper into a shared `commands/shared/` module.
Tests
3 new unit tests in `build::tests`:
These pin the WARN-vs-error decision for the lockfile write path. The actual feature-install + lockfile-write integration tests require Docker + BuildKit + an OCI registry; they belong in an integration test suite that I haven't added here (`docker-shared` test group is the right home).
Verification:
Out of scope (follow-ups)
Base branch
Based on `pr4b-lockfile-writer-wiring` (#35) since this PR consumes `FeatureBuildOutput.lockfile` (the field PR-4b added). Auto-rebases to `main` once #33 and #35 land in order.
Refs
🤖 Generated with Claude Code