[codex] Add acceptance fixture suite

Makefile

@@ -6,6 +6,7 @@
 	build-release \
 	standalone-artifact-smoke \
 	native-only-startup-contract \
+	acceptance-fixtures-check \
 	command-matrix-drift-check \
 	schema-drift-check \
 	parity-harness \
@@ -19,7 +20,7 @@
 RUST_MANIFEST := cmd/devcontainer/Cargo.toml
 RELEASE_BINARY := ./cmd/devcontainer/target/release/devcontainer
 
-tests: rust-fmt rust-clippy rust-check rust-tests build-release standalone-artifact-smoke native-only-startup-contract command-matrix-drift-check schema-drift-check parity-harness no-node-runtime check-parity-inventory check-cli-metadata check-todo-args check-compatibility-dashboard upstream-compatibility
+tests: rust-fmt rust-clippy rust-check rust-tests build-release standalone-artifact-smoke native-only-startup-contract acceptance-fixtures-check command-matrix-drift-check schema-drift-check parity-harness no-node-runtime check-parity-inventory check-cli-metadata check-todo-args check-compatibility-dashboard upstream-compatibility
 
 rust-fmt:
 	cargo fmt --manifest-path $(RUST_MANIFEST) --all -- --check
@@ -42,6 +43,9 @@ standalone-artifact-smoke: build-release
 native-only-startup-contract:
 	node build/check-native-only.js
 
+acceptance-fixtures-check:
+	node build/check-acceptance-fixtures.js
+
 command-matrix-drift-check:
 	node build/generate-command-matrix.js --check
 

README.md

@@ -8,6 +8,7 @@ The shipped runtime is the Rust binary in `cmd/devcontainer`. Node is kept only
 
 - `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.
@@ -44,6 +45,12 @@ Compatibility/tooling validation:
 npm test
 ```
 
+Manual acceptance suite shape:
+
+```bash
+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:

acceptance/README.md

@@ -0,0 +1,82 @@
+# Acceptance Fixtures
+
+This directory holds repo-owned manual acceptance scenarios for contributor
+checks against the native CLI. The suite manifest lives in
+`acceptance/scenarios.json`.
+
+Prerequisites:
+
+- a `devcontainer` binary on `PATH`, either from a local build or a release
+  artifact
+- a working container engine
+
+## image-lifecycle
+
+Path: `acceptance/image-lifecycle`
+
+Use this as the baseline lifecycle workspace.
+
+```bash
+devcontainer read-configuration --workspace-folder acceptance/image-lifecycle
+devcontainer up --workspace-folder acceptance/image-lifecycle
+devcontainer exec --workspace-folder acceptance/image-lifecycle /bin/cat /workspace/.acceptance/post-create
+devcontainer run-user-commands --workspace-folder acceptance/image-lifecycle
+devcontainer set-up --workspace-folder acceptance/image-lifecycle
+```
+
+## dockerfile-build
+
+Path: `acceptance/dockerfile-build`
+
+Use this to verify Dockerfile-based build args and post-create marker flow.
+
+```bash
+devcontainer read-configuration --workspace-folder acceptance/dockerfile-build
+devcontainer build --workspace-folder acceptance/dockerfile-build --image-name acceptance/dockerfile-build:manual
+devcontainer up --workspace-folder acceptance/dockerfile-build
+devcontainer exec --workspace-folder acceptance/dockerfile-build /bin/cat /workspace/.acceptance/dockerfile-message
+```
+
+## template-node-mongo
+
+Path: `acceptance/template-node-mongo`
+
+This is the template scenario. Apply
+`ghcr.io/devcontainers/templates/node-mongo:latest` into the generated
+workspace at `acceptance/template-node-mongo/workspace`, then run the normal
+runtime checks there. The tracked `workspace/.gitignore` keeps generated files
+out of version control.
+
+```bash
+devcontainer templates apply --workspace-folder acceptance/template-node-mongo/workspace --template-id ghcr.io/devcontainers/templates/node-mongo:latest
+devcontainer read-configuration --workspace-folder acceptance/template-node-mongo/workspace
+devcontainer up --workspace-folder acceptance/template-node-mongo/workspace
+devcontainer exec --workspace-folder acceptance/template-node-mongo/workspace /bin/sh -lc 'ls /workspaces/workspace/.devcontainer'
+```
+
+## local-feature
+
+Path: `acceptance/local-feature`
+
+Use this to verify repo-local Feature resolution and installation.
+
+```bash
+devcontainer read-configuration --workspace-folder acceptance/local-feature
+devcontainer build --workspace-folder acceptance/local-feature --image-name acceptance/local-feature:manual
+devcontainer up --workspace-folder acceptance/local-feature
+devcontainer exec --workspace-folder acceptance/local-feature /usr/local/bin/acceptance-local-feature
+```
+
+## published-feature
+
+Path: `acceptance/published-feature`
+
+Use this as the published-Feature scenario. It is the suite's only scenario
+that depends on published devcontainer collection resolution.
+
+```bash
+devcontainer read-configuration --workspace-folder acceptance/published-feature --include-features-configuration
+devcontainer build --workspace-folder acceptance/published-feature --image-name acceptance/published-feature:manual
+devcontainer up --workspace-folder acceptance/published-feature
+devcontainer exec --workspace-folder acceptance/published-feature /bin/cat /workspace/.acceptance/published-feature
+```

acceptance/dockerfile-build/.devcontainer/Dockerfile

@@ -0,0 +1,6 @@
+FROM alpine:3.20
+
+ARG MESSAGE=unset
+
+RUN mkdir -p /usr/local/etc \
+    && printf '%s\n' "$MESSAGE" > /usr/local/etc/acceptance-dockerfile-message

acceptance/dockerfile-build/.devcontainer/devcontainer.json

@@ -0,0 +1,13 @@
+{
+  "name": "acceptance-dockerfile-build",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "..",
+    "args": {
+      "MESSAGE": "from-build-arg"
+    }
+  },
+  "workspaceFolder": "/workspace",
+  "updateRemoteUserUID": false,
+  "postCreateCommand": "mkdir -p /workspace/.acceptance && cat /usr/local/etc/acceptance-dockerfile-message > /workspace/.acceptance/dockerfile-message"
+}

acceptance/dockerfile-build/README.md

@@ -0,0 +1,4 @@
+# Dockerfile Build
+
+This workspace validates Dockerfile-based builds, build args, and a
+post-create marker copied from the built image into the mounted workspace.

acceptance/image-lifecycle/.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+{
+  "name": "acceptance-image-lifecycle",
+  "image": "alpine:3.20",
+  "workspaceFolder": "/workspace",
+  "updateRemoteUserUID": false,
+  "containerEnv": {
+    "ACCEPTANCE_SCENARIO": "image-lifecycle"
+  },
+  "remoteEnv": {
+    "MANUAL_CHECK": "image-lifecycle-ready"
+  },
+  "onCreateCommand": "mkdir -p /workspace/.acceptance && printf on-create > /workspace/.acceptance/on-create",
+  "updateContentCommand": "printf update-content > /workspace/.acceptance/update-content",
+  "postCreateCommand": "printf post-create > /workspace/.acceptance/post-create",
+  "postStartCommand": "printf post-start > /workspace/.acceptance/post-start",
+  "postAttachCommand": "printf post-attach > /workspace/.acceptance/post-attach"
+}

acceptance/image-lifecycle/README.md

@@ -0,0 +1,4 @@
+# Image Lifecycle
+
+This workspace is the baseline manual check for lifecycle hook execution and
+follow-up commands like `exec`, `run-user-commands`, and `set-up`.

acceptance/local-feature/.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+  "name": "acceptance-local-feature",
+  "image": "debian:bookworm",
+  "workspaceFolder": "/workspace",
+  "updateRemoteUserUID": false,
+  "features": {
+    "./local-feature": {
+      "message": "local-feature-ready"
+    }
+  },
+  "postCreateCommand": "mkdir -p /workspace/.acceptance && /usr/local/bin/acceptance-local-feature > /workspace/.acceptance/local-feature"
+}

acceptance/local-feature/.devcontainer/local-feature/devcontainer-feature.json

@@ -0,0 +1,12 @@
+{
+  "id": "local-feature",
+  "name": "Local Feature",
+  "version": "1.0.0",
+  "description": "Adds a deterministic marker command for acceptance checks.",
+  "options": {
+    "message": {
+      "type": "string",
+      "default": "local-feature-default"
+    }
+  }
+}

acceptance/local-feature/.devcontainer/local-feature/install.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+set -eu
+
+message="${MESSAGE:-local-feature-default}"
+
+mkdir -p /usr/local/bin /usr/local/share/acceptance-local-feature
+
+cat > /usr/local/bin/acceptance-local-feature <<EOF
+#!/bin/sh
+printf '%s\n' "${message}"
+EOF
+
+chmod +x /usr/local/bin/acceptance-local-feature
+printf '%s\n' "${message}" > /usr/local/share/acceptance-local-feature/message

acceptance/local-feature/README.md

@@ -0,0 +1,4 @@
+# Local Feature
+
+This workspace uses a repo-local Feature that installs a deterministic command
+for manual verification after build or `up`.

acceptance/published-feature/.devcontainer/devcontainer.json

@@ -0,0 +1,10 @@
+{
+  "name": "acceptance-published-feature",
+  "image": "debian:bookworm",
+  "workspaceFolder": "/workspace",
+  "updateRemoteUserUID": false,
+  "features": {
+    "ghcr.io/devcontainers/features/git:1.0": {}
+  },
+  "postCreateCommand": "mkdir -p /workspace/.acceptance && printf published-feature > /workspace/.acceptance/published-feature"
+}

acceptance/published-feature/README.md

@@ -0,0 +1,4 @@
+# Published Feature
+
+This workspace keeps a published Feature identifier in the config path so
+manual checks can verify feature-aware configuration and build flows.

acceptance/scenarios.json

@@ -0,0 +1,105 @@
+[
+  {
+    "id": "image-lifecycle",
+    "kind": "workspace",
+    "description": "Image-based workspace that exercises lifecycle hooks and follow-up commands.",
+    "path": "acceptance/image-lifecycle",
+    "workspacePath": "acceptance/image-lifecycle",
+    "requiresNetwork": false,
+    "expectedFiles": [
+      "README.md",
+      ".devcontainer/devcontainer.json"
+    ],
+    "checks": [
+      "read-configuration",
+      "up",
+      "exec",
+      "run-user-commands",
+      "set-up"
+    ]
+  },
+  {
+    "id": "dockerfile-build",
+    "kind": "workspace",
+    "description": "Dockerfile-based workspace with a build argument and a post-create marker.",
+    "path": "acceptance/dockerfile-build",
+    "workspacePath": "acceptance/dockerfile-build",
+    "requiresNetwork": false,
+    "expectedFiles": [
+      "README.md",
+      ".devcontainer/devcontainer.json",
+      ".devcontainer/Dockerfile"
+    ],
+    "checks": [
+      "read-configuration",
+      "build",
+      "up",
+      "exec"
+    ]
+  },
+  {
+    "id": "template-node-mongo",
+    "kind": "template",
+    "description": "Template-driven compose workspace generated from the embedded node-mongo template.",
+    "path": "acceptance/template-node-mongo",
+    "workspacePath": "acceptance/template-node-mongo/workspace",
+    "requiresNetwork": false,
+    "expectedFiles": [
+      "README.md",
+      "workspace/.gitignore"
+    ],
+    "postApplyFiles": [
+      ".devcontainer/devcontainer.json",
+      ".devcontainer/docker-compose.yml"
+    ],
+    "template": {
+      "id": "ghcr.io/devcontainers/templates/node-mongo:latest",
+      "args": {},
+      "features": []
+    },
+    "checks": [
+      "templates-apply",
+      "read-configuration",
+      "up",
+      "exec"
+    ]
+  },
+  {
+    "id": "local-feature",
+    "kind": "workspace",
+    "description": "Image-based workspace with a repo-local Feature that installs a deterministic marker command.",
+    "path": "acceptance/local-feature",
+    "workspacePath": "acceptance/local-feature",
+    "requiresNetwork": false,
+    "expectedFiles": [
+      "README.md",
+      ".devcontainer/devcontainer.json",
+      ".devcontainer/local-feature/devcontainer-feature.json",
+      ".devcontainer/local-feature/install.sh"
+    ],
+    "checks": [
+      "read-configuration",
+      "build",
+      "up",
+      "exec"
+    ]
+  },
+  {
+    "id": "published-feature",
+    "kind": "workspace",
+    "description": "Image-based workspace that keeps one published Feature in the configuration path for manual checks.",
+    "path": "acceptance/published-feature",
+    "workspacePath": "acceptance/published-feature",
+    "requiresNetwork": true,
+    "expectedFiles": [
+      "README.md",
+      ".devcontainer/devcontainer.json"
+    ],
+    "checks": [
+      "read-configuration",
+      "build",
+      "up",
+      "exec"
+    ]
+  }
+]

acceptance/template-node-mongo/README.md

@@ -0,0 +1,4 @@
+# Template Node Mongo
+
+This scenario is driven by `devcontainer templates apply` and uses the embedded
+`ghcr.io/devcontainers/templates/node-mongo:latest` template as its source.

acceptance/template-node-mongo/workspace/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore