devcontainer-rs

This repository hosts a native Rust implementation of the Dev Containers CLI, with compatibility tracked against the pinned upstream TypeScript sources in upstream/ and the pinned specification assets in spec/.

The shipped runtime is the Rust binary in cmd/devcontainer. Node is kept only for lightweight compatibility tooling such as upstream/spec drift checks, generated compatibility inventories, and the parity smoke harness.

Repository layout

• cmd/devcontainer/: native Rust CLI crate.
• cmd/devcontainer/src/runtime/: native runtime subsystems for container-backed commands.
• acceptance/: repo-owned manual acceptance scenarios and suite manifest.
• upstream/: canonical upstream devcontainers/cli baseline.
• spec/: canonical upstream devcontainers/spec schemas and docs.
• build/: repo-owned compatibility guard scripts.
• src/test/parity/: parity fixtures and golden files for repo-owned checks.
• docs/: contributor and release documentation for the native CLI.

Compatibility contract: this repository targets the exact submodule revision pinned at HEAD:upstream.

Specification contract: schema-sensitive behavior targets the exact submodule revision pinned at HEAD:spec.

Submodules

Initialize submodules before running checks or editing compatibility-sensitive code:

git submodule update --init --recursive

If upstream/ or spec/ is missing or uninitialized, run the same command again and rerun the checks.

Local development

Rust validation:

cargo fmt --manifest-path cmd/devcontainer/Cargo.toml --all -- --check
cargo clippy --manifest-path cmd/devcontainer/Cargo.toml -- -D warnings
cargo test --manifest-path cmd/devcontainer/Cargo.toml

Compatibility/tooling validation:

npm test

Manual acceptance suite shape:

make acceptance-fixtures-check

The Node-based checks do not require installing project dependencies; they use built-in Node modules only. Node 20+ is still required to run them.

Generated command reference:

npm run generate-cli-reference

Generated parity inventory:

npm run generate-parity-inventory

Enable the repository-managed pre-commit hook:

npm run install-git-hooks

Upstream and spec workflow

When updating upstream compatibility baselines:

git submodule update --init --recursive
git -C upstream fetch origin
git -C upstream checkout <new-upstream-commit>
git add upstream
git rev-parse HEAD:upstream
npm run check-upstream-submodule
npm run check-upstream-compatibility
npm run check-command-matrix
npm run check-parity-inventory
npm run check-parity-harness

When changing schema-sensitive behavior, also verify:

git rev-parse HEAD:spec
npm run check-spec-drift

If a pinned submodule revision changes, update the matching generated baseline files in docs/upstream/.

Contributor notes

• Architecture, command flow, and runtime module ownership: docs/architecture.md
• Generated command reference: docs/cli/command-reference.md
• Generated parity inventory: docs/upstream/parity-inventory.md
• Native distribution and release notes: docs/standalone/distribution.md
• Runtime and compatibility guardrails: docs/standalone/cutover.md