From 180c951a4b92dd0a08280f4370d60557fca74081 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 19:42:04 +0000
Subject: [PATCH 01/18] fix: containerUser/remoteUser support across all
 features

- rust: chown RUSTUP_HOME + CARGO_HOME to _REMOTE_USER after install
- homebrew: use _REMOTE_USER as Linux install user when non-root, falling
  back to dedicated linuxbrew account; update test to mirror logic
- node: export shared COREPACK_HOME=/usr/local/share/corepack in profile.d
- package-manager: export same COREPACK_HOME before corepack calls
- zig: remove spurious sudo calls (feature scripts already run as root)
- fix pre-existing missing execute bit on node + package-manager scripts
- bump all changed features to 0.2.0

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/8c66a117-fe5e-463a-a782-560068c2d637

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 src/homebrew/devcontainer-feature.json        |  2 +-
 src/homebrew/install.sh                       | 38 +++++++++++--------
 src/node/devcontainer-feature.json            |  2 +-
 src/node/install.sh                           |  6 +++
 src/package-manager/devcontainer-feature.json |  2 +-
 src/package-manager/install.sh                |  7 ++++
 src/rust/devcontainer-feature.json            |  2 +-
 src/rust/install.sh                           |  9 +++++
 src/zig/devcontainer-feature.json             |  2 +-
 src/zig/install.sh                            | 10 ++---
 test/homebrew/test.sh                         | 13 +++++--
 test/node/test.sh                             |  0
 test/package-manager/test.sh                  |  0
 13 files changed, 65 insertions(+), 28 deletions(-)
 mode change 100644 => 100755 src/node/install.sh
 mode change 100644 => 100755 src/package-manager/install.sh
 mode change 100644 => 100755 test/node/test.sh
 mode change 100644 => 100755 test/package-manager/test.sh

diff --git a/src/homebrew/devcontainer-feature.json b/src/homebrew/devcontainer-feature.json
index ba91667..35f5a7e 100644
--- a/src/homebrew/devcontainer-feature.json
+++ b/src/homebrew/devcontainer-feature.json
@@ -1,6 +1,6 @@
 {
 	"id": "homebrew",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Homebrew",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/homebrew.md",
 	"description": "Installs Homebrew (macOS/Linux) globally. Skips if already installed.",
diff --git a/src/homebrew/install.sh b/src/homebrew/install.sh
index 16b26ca..2cd235d 100755
--- a/src/homebrew/install.sh
+++ b/src/homebrew/install.sh
@@ -5,7 +5,6 @@ set -euo pipefail
 # Installs Homebrew if not already present (macOS/Linux)
 # Idempotent: skips install if brew is already available
 
-BREW_USER="linuxbrew"
 OS=$(uname -s)
 ARCH=$(uname -m)
 
@@ -22,12 +21,9 @@ fi
 
 if [[ -x "$BREW_PREFIX/bin/brew" ]]; then
   echo "[INFO] Homebrew is already installed at $BREW_PREFIX/bin/brew"
-  # Ensure linuxbrew user and profile.d entry are present even on idempotent runs
-  if [[ "$OS" != "Darwin" ]]; then
-    id -u "$BREW_USER" &>/dev/null || useradd -m -s /bin/bash "$BREW_USER"
-    if [[ ! -f /etc/profile.d/homebrew.sh ]]; then
-      echo "eval \"\$($BREW_PREFIX/bin/brew shellenv)\"" > /etc/profile.d/homebrew.sh
-    fi
+  # Ensure profile.d entry is present even on idempotent runs
+  if [[ "$OS" != "Darwin" ]] && [[ ! -f /etc/profile.d/homebrew.sh ]]; then
+    echo "eval \"\$($BREW_PREFIX/bin/brew shellenv)\"" > /etc/profile.d/homebrew.sh
   fi
   exit 0
 fi
@@ -36,17 +32,29 @@ if [[ "$OS" == "Darwin" ]]; then
   echo "[INFO] Installing Homebrew for macOS..."
   NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 else
-  echo "[INFO] Installing Homebrew for Linux..."
-  if [[ $EUID -eq 0 ]]; then
-    # Homebrew refuses to install as root; use a dedicated non-root user
-    useradd -m -s /bin/bash "$BREW_USER" 2>/dev/null || true
-    # shellcheck disable=SC2016
-    su - "$BREW_USER" -s /bin/bash -c \
-      'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+  # Homebrew on Linux must run as a non-root user and installs to
+  # /home/linuxbrew/.linuxbrew. Prefer _REMOTE_USER when set and non-root
+  # so the devcontainer user owns the Homebrew prefix and can run
+  # `brew install` directly without switching users.
+  REMOTE_USER="${_REMOTE_USER:-}"
+  if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]]; then
+    BREW_USER="$REMOTE_USER"
   else
-    NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    BREW_USER="linuxbrew"
+    useradd -m -s /bin/bash "$BREW_USER" 2>/dev/null || true
   fi
 
+  echo "[INFO] Installing Homebrew for Linux as user '${BREW_USER}'..."
+  # Ensure /home/linuxbrew exists and is owned by the install user so the
+  # Homebrew installer can create the .linuxbrew prefix there regardless of
+  # which user is performing the install.
+  mkdir -p /home/linuxbrew
+  chown "$BREW_USER:" /home/linuxbrew
+
+  # shellcheck disable=SC2016
+  su - "$BREW_USER" -s /bin/bash -c \
+    'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+
   # Add brew to PATH for interactive shells
   echo "eval \"\$($BREW_PREFIX/bin/brew shellenv)\"" > /etc/profile.d/homebrew.sh
 fi
diff --git a/src/node/devcontainer-feature.json b/src/node/devcontainer-feature.json
index 4497228..7303d0b 100644
--- a/src/node/devcontainer-feature.json
+++ b/src/node/devcontainer-feature.json
@@ -1,6 +1,6 @@
 {
 	"id": "node",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Node.js",
 	"description": "Installs and configures the Node.js runtime globally.",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/node.md",
diff --git a/src/node/install.sh b/src/node/install.sh
old mode 100644
new mode 100755
index 4c29083..7b1191e
--- a/src/node/install.sh
+++ b/src/node/install.sh
@@ -71,8 +71,14 @@ fi
 ln -sf "$NODE_DIR/bin/corepack" /usr/local/bin/corepack
 
 # Ensure globally installed npm binaries are on PATH for non-login shells.
+# Export a shared COREPACK_HOME so all users (including the non-root remoteUser
+# in Codespaces and VS Code Dev Containers) find the package managers that were
+# prepared during feature install, without needing to re-download them.
+COREPACK_DIR="/usr/local/share/corepack"
+mkdir -p "$COREPACK_DIR"
 cat >/etc/profile.d/node.sh <<EOF
 export PATH="$NODE_DIR/bin:\$PATH"
+export COREPACK_HOME="$COREPACK_DIR"
 EOF
 chmod 0644 /etc/profile.d/node.sh
 
diff --git a/src/package-manager/devcontainer-feature.json b/src/package-manager/devcontainer-feature.json
index 46f5954..bb79670 100644
--- a/src/package-manager/devcontainer-feature.json
+++ b/src/package-manager/devcontainer-feature.json
@@ -1,6 +1,6 @@
 {
 	"id": "package-manager",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Package Manager (corepack)",
 	"description": "Installs and configures a Node.js package manager (pnpm, yarn, or npm) via corepack. Supports auto-detection from workspace package.json.",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/package-manager.md",
diff --git a/src/package-manager/install.sh b/src/package-manager/install.sh
old mode 100644
new mode 100755
index 54c7ecf..b754ed4
--- a/src/package-manager/install.sh
+++ b/src/package-manager/install.sh
@@ -52,6 +52,13 @@ if ! command -v corepack &>/dev/null; then
   exit 1
 fi
 
+# Use a shared COREPACK_HOME so all users (including the non-root remoteUser in
+# Codespaces and VS Code Dev Containers) can access the prepared package manager
+# without re-downloading it. The node feature creates this directory and exports
+# it via /etc/profile.d/node.sh; we honour the same path here.
+export COREPACK_HOME="${COREPACK_HOME:-/usr/local/share/corepack}"
+mkdir -p "$COREPACK_HOME"
+
 # ── Resolve the package manager spec ──────────────────────────────────────────
 
 PM_SPEC=""
diff --git a/src/rust/devcontainer-feature.json b/src/rust/devcontainer-feature.json
index 3568837..33c6ad6 100644
--- a/src/rust/devcontainer-feature.json
+++ b/src/rust/devcontainer-feature.json
@@ -1,6 +1,6 @@
 {
 	"id": "rust",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Rust Toolchain (Global)",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/rust.md",
 	"description": "Installs the Rust toolchain globally using rustup. Supports toolchain selection, component install, and validation.",
diff --git a/src/rust/install.sh b/src/rust/install.sh
index 83011b3..a928021 100755
--- a/src/rust/install.sh
+++ b/src/rust/install.sh
@@ -49,4 +49,13 @@ fi
 rustc --version
 cargo --version
 
+# Transfer ownership of toolchain directories to the remote user so they can
+# run `cargo install` and `rustup` without elevated privileges in Codespaces
+# and VS Code Dev Containers.
+REMOTE_USER="${_REMOTE_USER:-}"
+if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]] && id -u "$REMOTE_USER" &>/dev/null; then
+  chown -R "${REMOTE_USER}" "${RUSTUP_HOME}" "${CARGO_HOME}"
+  echo "[INFO] Transferred toolchain ownership to ${REMOTE_USER}."
+fi
+
 echo "[SUCCESS] Rust toolchain ($TOOLCHAIN) and components installed."
diff --git a/src/zig/devcontainer-feature.json b/src/zig/devcontainer-feature.json
index e031844..a51cd80 100644
--- a/src/zig/devcontainer-feature.json
+++ b/src/zig/devcontainer-feature.json
@@ -1,6 +1,6 @@
 {
 	"id": "zig",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Zig Compiler",
 	"description": "Installs the Zig programming language (https://ziglang.org/) globally.",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/zig.md",
diff --git a/src/zig/install.sh b/src/zig/install.sh
index 7b985f7..bee5a09 100755
--- a/src/zig/install.sh
+++ b/src/zig/install.sh
@@ -56,11 +56,11 @@ tar -C "$TMPDIR" -xf "$TMPDIR/zig.tar.xz"
 # Find extracted dir
 ZIG_EXTRACTED=$(find "$TMPDIR" -maxdepth 1 -type d -name "zig-*" | head -n 1)
 
-# Install
-sudo rm -rf "$ZIG_ROOT"
-sudo mkdir -p "$ZIG_ROOT"
-sudo cp -r "$ZIG_EXTRACTED"/* "$ZIG_ROOT"/
-sudo ln -sf "$ZIG_BIN" /usr/local/bin/zig
+# Install (feature scripts run as root; sudo is not needed)
+rm -rf "$ZIG_ROOT"
+mkdir -p "$ZIG_ROOT"
+cp -r "$ZIG_EXTRACTED"/* "$ZIG_ROOT"/
+ln -sf "$ZIG_BIN" /usr/local/bin/zig
 
 # Validate
 zig version
diff --git a/test/homebrew/test.sh b/test/homebrew/test.sh
index e040886..230dad1 100755
--- a/test/homebrew/test.sh
+++ b/test/homebrew/test.sh
@@ -2,7 +2,7 @@
 set -euo pipefail
 
 # Test: Homebrew global feature
-# Homebrew refuses to run as root; verify via the linuxbrew user
+# Homebrew refuses to run as root; verify via the install user
 
 BREW_PREFIX="/home/linuxbrew/.linuxbrew"
 
@@ -11,8 +11,15 @@ if [[ ! -x "$BREW_PREFIX/bin/brew" ]]; then
   exit 1
 fi
 
-# Run brew as the linuxbrew user (brew refuses to run as root)
-su - linuxbrew -s /bin/bash -c "$BREW_PREFIX/bin/brew --version" \
+# Mirror the install.sh user selection: prefer _REMOTE_USER when set and
+# non-root, otherwise fall back to the dedicated linuxbrew account.
+BREW_USER="${_REMOTE_USER:-}"
+if [[ -z "$BREW_USER" || "$BREW_USER" == "root" ]]; then
+  BREW_USER="linuxbrew"
+fi
+
+# Run brew as the install user (brew refuses to run as root)
+su - "$BREW_USER" -s /bin/bash -c "$BREW_PREFIX/bin/brew --version" \
   | grep Homebrew \
   || { echo "[FAIL] brew --version did not output expected Homebrew version string" >&2; exit 1; }
 
diff --git a/test/node/test.sh b/test/node/test.sh
old mode 100644
new mode 100755
diff --git a/test/package-manager/test.sh b/test/package-manager/test.sh
old mode 100644
new mode 100755

From 9dc7218dc5dd166bf9851abe3835c3e9680b7545 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 19:49:45 +0000
Subject: [PATCH 02/18] docs: document executable-bit convention; revert
 accidental 100755 mode bits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Revert src/node/install.sh, src/package-manager/install.sh,
  test/node/test.sh, test/package-manager/test.sh from 100755 back to
  100644 — shell scripts are not stored with the execute bit in git
- CLAUDE.md: remove "← must be executable" annotation; add "Executable Bits"
  section explaining the Husky/CI convention and that agents must not chmod +x
- SHELL.instructions.md: add explicit "Executable Bits" rule for agents
- FEATURE.instructions.md: add execute-bit note to Five-File Completeness Rule
- validate-feature.sh: change executable-bit checks from hard [FAIL] to [INFO]
- devcontainer SKILL.md: replace "Missing execute permission" common mistake
  with the correct explanation of the Husky/CI convention
- devcontainer references/test-patterns.md: clarify executable bit is managed
  by Husky/CI, not committed to git
- debug-feature SKILL.md: remove "Missing execute permission" category;
  clarify chmod note refers to installed binaries, not source scripts
- debug-feature references/common-failure-modes.md: rewrite §4 to distinguish
  between installed-binary permissions and the source script convention
- new-feature SKILL.md: remove "marked executable" from checklist

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/aaec7de0-c396-4a94-b485-b78cdc2a69a7

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/instructions/FEATURE.instructions.md  |  5 ++++
 .github/instructions/SHELL.instructions.md    | 14 ++++++++++
 .github/skills/debug-feature/SKILL.md         | 11 ++++----
 .../references/common-failure-modes.md        | 27 ++++++++++++-------
 .github/skills/devcontainer/SKILL.md          |  8 ++++--
 .../devcontainer/references/test-patterns.md  |  5 ++--
 .github/skills/new-feature/SKILL.md           |  2 +-
 CLAUDE.md                                     | 18 ++++++++++++-
 scripts/validate-feature.sh                   |  8 ++++--
 9 files changed, 75 insertions(+), 23 deletions(-)

diff --git a/.github/instructions/FEATURE.instructions.md b/.github/instructions/FEATURE.instructions.md
index a0f05b7..65d3b1b 100644
--- a/.github/instructions/FEATURE.instructions.md
+++ b/.github/instructions/FEATURE.instructions.md
@@ -56,6 +56,11 @@ docs/features/<id>.md
 
 Run `pnpm run validate-feature <id>` to check completeness.
 
+**Note on executable bits:** scripts are stored as `100644` (non-executable)
+in git. The Husky `post-checkout`/`post-merge` hooks set the bits locally and
+CI workflows set them before running. Do **not** run `chmod +x` or
+`git update-index --chmod=+x` — the bits are intentionally absent in git.
+
 ## `documentationURL` Must Match Actual Doc File
 
 The `documentationURL` field in `devcontainer-feature.json` must always point
diff --git a/.github/instructions/SHELL.instructions.md b/.github/instructions/SHELL.instructions.md
index 6b5dde9..3f5f01e 100644
--- a/.github/instructions/SHELL.instructions.md
+++ b/.github/instructions/SHELL.instructions.md
@@ -94,6 +94,20 @@ fi
 For tools installed to a fixed path where overwriting is safe, no guard is
 needed.
 
+## Executable Bits
+
+Shell scripts are stored in git **without** the executable bit. Do **not**
+run `chmod +x` on any `.sh` file, and do **not** use
+`git update-index --chmod=+x`.
+
+Executable bits are managed outside of git:
+
+- **Local dev** — Husky `post-checkout`/`post-merge` hooks apply
+  `chmod +x` on all tracked `*.sh` files automatically.
+- **CI** — the test and publish workflows set the bits before invoking scripts.
+
+Agents must never treat a missing executable bit as a bug to fix.
+
 ## Linting
 
 After editing a shell script, run shellcheck if it is available:
diff --git a/.github/skills/debug-feature/SKILL.md b/.github/skills/debug-feature/SKILL.md
index 4b3bcc0..06a5ddd 100644
--- a/.github/skills/debug-feature/SKILL.md
+++ b/.github/skills/debug-feature/SKILL.md
@@ -55,12 +55,11 @@ The most common failure categories, in order of frequency:
 1. **Env var not injected** — option value is empty or unset
 2. **Architecture mismatch** — wrong binary for the platform
 3. **Broken download URL** — upstream URL pattern changed or version not found
-4. **Missing execute permission** — `install.sh` is not executable
-5. **Missing `set -euo pipefail`** — silent failures masked by `|| true`
-6. **Idempotency failure** — re-running the script breaks an existing install
-7. **Version assertion mismatch** — `test.sh` checks a different version than
+4. **Missing `set -euo pipefail`** — silent failures masked by `|| true`
+5. **Idempotency failure** — re-running the script breaks an existing install
+6. **Version assertion mismatch** — `test.sh` checks a different version than
    the default in `devcontainer-feature.json`
-8. **Missing `installsAfter`** — the feature depends on another feature
+7. **Missing `installsAfter`** — the feature depends on another feature
    (e.g. Node.js) being installed first but does not declare it
 
 ### Step 3 — Apply the fix
@@ -119,7 +118,7 @@ If the error is not immediately obvious, work through these questions:
 
 - Does the script end with `command -v <binary>` or `<binary> --version`?
 - If the binary is installed to a non-standard path, is that path on `$PATH`?
-- Is the binary installed with execute permission (`chmod +x`)?
+- Is the binary installed with execute permission (`chmod +x` on the installed binary in `/usr/local/bin`, not the `install.sh` source file)?
 
 **Idempotency:**
 
diff --git a/.github/skills/debug-feature/references/common-failure-modes.md b/.github/skills/debug-feature/references/common-failure-modes.md
index 3d96486..4325c4d 100644
--- a/.github/skills/debug-feature/references/common-failure-modes.md
+++ b/.github/skills/debug-feature/references/common-failure-modes.md
@@ -149,27 +149,36 @@ Always include an `else` branch that errors on unsupported architectures.
 
 ---
 
-## 4. Missing Execute Permission
+## 4. Execute Permission on Installed Binaries
 
 ### Detection
 
-- Error: `"Permission denied"` when running `install.sh`
-- `ls -la src/<id>/install.sh` shows `-rw-r--r--` (no `x` bit)
+- Error: `"Permission denied"` when running a binary the feature installed
+  (e.g. `/usr/local/bin/biome`)
+- `ls -la /usr/local/bin/<binary>` shows `-rw-r--r--` (no `x` bit)
 
 ### Why it happens
 
-Files created with a text editor or copied without preserving permissions may
-not have the execute bit set. The devcontainer CLI and CI workflows run
-`install.sh` directly.
+The feature's `install.sh` downloaded or copied a binary but did not mark it
+executable with `chmod +x`.
 
 ### Fix
 
+Add `chmod +x` or use `install -m 0755` in `install.sh` when placing the
+binary:
+
 ```bash
-chmod +x src/<id>/install.sh
+chmod +x "$BINARY_PATH"
+# or
+install -m 0755 "$TMP/binary" /usr/local/bin/binary
 ```
 
-The `validate-feature` script (`pnpm run validate-feature`) checks for this
-and reports it as an error.
+**Note:** this is about the *installed binary*, not `install.sh` itself.
+`install.sh` and all other `*.sh` files in the repository are stored **without**
+the executable bit in git (`100644`). The Husky `post-checkout`/`post-merge`
+hooks set the bit locally; CI workflows set it before running the scripts.
+Never run `chmod +x src/<id>/install.sh` or
+`git update-index --chmod=+x src/<id>/install.sh`.
 
 ---
 
diff --git a/.github/skills/devcontainer/SKILL.md b/.github/skills/devcontainer/SKILL.md
index 0d01808..e2c2947 100644
--- a/.github/skills/devcontainer/SKILL.md
+++ b/.github/skills/devcontainer/SKILL.md
@@ -173,8 +173,12 @@ looking for `test/<id>/test.sh` matching the feature's directory name.
 - **Env var not set** — the devcontainer CLI injects option values as env vars
   but they may be empty strings, not unset. Always use
   `VAR="${OPTION_VAR:-default}"` to handle both the unset and empty-string case.
-- **Missing execute permission** — `install.sh` must be executable
-  (`chmod +x`). The publish workflow runs it directly.
+- **Executable bits not committed** — shell scripts are stored in git without
+  the executable bit (`100644`). Do **not** run `chmod +x` or
+  `git update-index --chmod=+x`. Husky hooks set the bits on checkout/merge
+  locally; CI workflows set them before running scripts. The
+  `validate-feature` script may note missing bits — this is expected and safe
+  to ignore.
 - **Semver ranges** — option defaults like `">=20"` or `"^24"` are not
   reproducible. Always use an exact version string.
 - **Missing `documentationURL`** — all features must link to their doc page.
diff --git a/.github/skills/devcontainer/references/test-patterns.md b/.github/skills/devcontainer/references/test-patterns.md
index 72d5c87..c6fd4d0 100644
--- a/.github/skills/devcontainer/references/test-patterns.md
+++ b/.github/skills/devcontainer/references/test-patterns.md
@@ -11,7 +11,7 @@ directory structure:
 ```text
 test/
   <id>/
-    test.sh        # executable shell assertions
+    test.sh        # shell assertions (executable bit set by Husky/CI, not committed)
     scenarios.json # human-readable scenario descriptions
 ```
 
@@ -59,7 +59,8 @@ An array of scenario objects. Each object describes one logical test scenario.
 ## `test.sh`
 
 An executable Bash script that runs assertions after the feature is installed
-in the devcontainer.
+in the devcontainer. The executable bit is set by Husky (locally) and by CI
+workflows — scripts are stored in git without the bit (`100644`).
 
 ### Structure
 
diff --git a/.github/skills/new-feature/SKILL.md b/.github/skills/new-feature/SKILL.md
index 5a3a485..0f93b41 100644
--- a/.github/skills/new-feature/SKILL.md
+++ b/.github/skills/new-feature/SKILL.md
@@ -235,7 +235,7 @@ Rules:
 Before finishing, confirm every item:
 
 - [ ] `src/<id>/devcontainer-feature.json` created
-- [ ] `src/<id>/install.sh` created and marked executable
+- [ ] `src/<id>/install.sh` created (executable bit is **not** committed; Husky/CI handles it)
 - [ ] `test/<id>/test.sh` created
 - [ ] `test/<id>/scenarios.json` created
 - [ ] `docs/features/<id>.md` created
diff --git a/CLAUDE.md b/CLAUDE.md
index 26ee1ab..bd8631e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -81,7 +81,7 @@ Every feature must have exactly these files:
 
 ```text
 src/<id>/devcontainer-feature.json
-src/<id>/install.sh            ← must be executable
+src/<id>/install.sh
 test/<id>/test.sh
 test/<id>/scenarios.json
 docs/features/<id>.md
@@ -90,6 +90,22 @@ docs/features/<id>.md
 Run `pnpm run validate-feature <id>` to verify all five exist and pass
 structural checks before committing.
 
+## Executable Bits
+
+Shell scripts are stored in git **without** the executable bit (`100644`, not
+`100755`). Do **not** run `chmod +x` on scripts or use
+`git update-index --chmod=+x`. The bits are managed automatically:
+
+- **Local dev** — a Husky `post-checkout`/`post-merge` hook runs
+  `git ls-files -z '*.sh' | xargs -0 chmod +x` after every checkout and
+  merge, and `core.fileMode` is set to `false` so git ignores the local
+  mode change.
+- **CI** — the test and publish workflows set the bits before invoking any
+  script.
+
+Agents running `validate-feature` may see an informational note about
+executable bits; this is expected and safe to ignore.
+
 ## Version Bump Rule
 
 The publish workflow skips any feature whose `id:version` OCI image already
diff --git a/scripts/validate-feature.sh b/scripts/validate-feature.sh
index 0a4b87b..86e35d4 100755
--- a/scripts/validate-feature.sh
+++ b/scripts/validate-feature.sh
@@ -107,10 +107,13 @@ fi
 # ── install.sh structural checks ─────────────────────────────────────────────
 
 if [[ -f "$INSTALL_FILE" ]]; then
+  # Executable bits are not stored in git (100644). They are applied by the
+  # Husky post-checkout/post-merge hooks locally and by CI workflows before
+  # running scripts. Report as informational only — not a hard failure.
   if [[ -x "$INSTALL_FILE" ]]; then
     pass "install.sh is executable"
   else
-    fail "install.sh is not executable (run: chmod +x ${INSTALL_FILE})"
+    echo "[INFO] install.sh is not executable on disk (expected — bits are set by Husky/CI, not git)"
   fi
 
   FIRST_LINE=$(head -1 "$INSTALL_FILE")
@@ -176,10 +179,11 @@ fi
 # ── test.sh structural checks ─────────────────────────────────────────────────
 
 if [[ -f "$TEST_SH" ]]; then
+  # Executable bits are not stored in git (100644). See install.sh note above.
   if [[ -x "$TEST_SH" ]]; then
     pass "test.sh is executable"
   else
-    fail "test.sh is not executable (run: chmod +x ${TEST_SH})"
+    echo "[INFO] test.sh is not executable on disk (expected — bits are set by Husky/CI, not git)"
   fi
 
   FIRST_LINE=$(head -1 "$TEST_SH")

From 12d6acd19d3a32cf5e9010c8cec9c91ea299274e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 19:54:56 +0000
Subject: [PATCH 03/18] docs: document _REMOTE_USER/_CONTAINER_USER spec in
 feature-anatomy and SKILL.md

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/fd30aafa-d106-4810-8a11-6be9a7342c6d

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/skills/devcontainer/SKILL.md          |  4 +++
 .../references/feature-anatomy.md             | 33 +++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/.github/skills/devcontainer/SKILL.md b/.github/skills/devcontainer/SKILL.md
index e2c2947..5ea6fa9 100644
--- a/.github/skills/devcontainer/SKILL.md
+++ b/.github/skills/devcontainer/SKILL.md
@@ -126,6 +126,10 @@ docs/
 - End with a validation step: `command -v <binary>` or `<binary> --version`
 - Print `[ERROR]` to stderr and `exit 1` on unrecoverable failures
 - Print `[INFO]` for progress steps
+- Use `_REMOTE_USER` (not `_CONTAINER_USER`) to transfer directory ownership to
+  the devcontainer user after installing to user-writable paths. Always guard
+  for the unset and root cases — see `references/feature-anatomy.md` §User
+  Environment Variables for the canonical pattern
 
 ### Feature Bootstrap Checklist
 
diff --git a/.github/skills/devcontainer/references/feature-anatomy.md b/.github/skills/devcontainer/references/feature-anatomy.md
index 806378b..360746c 100644
--- a/.github/skills/devcontainer/references/feature-anatomy.md
+++ b/.github/skills/devcontainer/references/feature-anatomy.md
@@ -181,6 +181,39 @@ biome --version
 
 Errors go to stderr (`>&2`). Info and success go to stdout.
 
+### User Environment Variables
+
+Feature scripts run as root. The devcontainer CLI injects these variables so
+scripts can transfer ownership or run commands as the actual container user:
+
+| Variable | Value |
+| :------- | :---- |
+| `_REMOTE_USER` | The `remoteUser` setting in `devcontainer.json`. If `remoteUser` is not set, this equals `_CONTAINER_USER`. This is the user VS Code / Codespaces will run as. |
+| `_CONTAINER_USER` | The container's user (set via `USER` in the Dockerfile, `user:` in `docker-compose.yml`, or `containerUser` in `devcontainer.json`). |
+| `_REMOTE_USER_HOME` | Home directory of `_REMOTE_USER`. |
+| `_CONTAINER_USER_HOME` | Home directory of `_CONTAINER_USER`. |
+
+**Use `_REMOTE_USER`** whenever you need to transfer ownership of a directory
+so the devcontainer user can write to it (e.g. `RUSTUP_HOME`, `CARGO_HOME`).
+Always guard for the unset and root cases:
+
+```bash
+REMOTE_USER="${_REMOTE_USER:-}"
+if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]] && id -u "$REMOTE_USER" &>/dev/null; then
+  chown -R "$REMOTE_USER" /some/dir
+  echo "[INFO] Transferred ownership to $REMOTE_USER."
+fi
+```
+
+This guard handles three edge cases:
+
+- `_REMOTE_USER` is unset (container doesn't use feature user env vars)
+- `_REMOTE_USER` is `root` (no chown needed; root already owns everything)
+- The user account doesn't exist yet at install time (defensive `id -u` check)
+
+For tools that install to system-wide paths owned by root (e.g.
+`/usr/local/bin/biome`), no chown is needed — the binary is world-executable.
+
 ### Idempotency Guard
 
 When re-running the installer would break an existing installation, guard it:

From c50c2f74c9d25fa11f7c617535ba0d58fc274627 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 20:13:08 +0000
Subject: [PATCH 04/18] feat: adopt devcontainer features test CLI pattern for
 all features

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/ae5c9b02-609c-49d7-8118-3ef1bcac28b5

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/instructions/FEATURE.instructions.md  |  10 +-
 .../devcontainer/references/test-patterns.md  | 287 ++++++++++--------
 .github/workflows/publish.yml                 |  51 ++--
 .github/workflows/test-feature.yml            |  41 +--
 .github/workflows/test.yml                    | 144 ++++-----
 scripts/test-feature.sh                       |  48 +--
 scripts/validate-feature.sh                   |  39 ++-
 test/act/scenarios.json                       |   7 +-
 test/act/test.sh                              |  18 +-
 test/biome/install_custom_version.sh          |  12 +
 test/biome/scenarios.json                     |  14 +-
 test/biome/test.sh                            |  20 +-
 test/claude-code/scenarios.json               |  17 +-
 test/claude-code/test.sh                      |  18 +-
 test/homebrew/remote_user_vscode.sh           |  18 ++
 test/homebrew/scenarios.json                  |  17 +-
 test/homebrew/test.sh                         |  34 +--
 test/node/scenarios.json                      |  17 +-
 test/node/test.sh                             |  41 +--
 test/package-manager/explicit_pnpm.sh         |  12 +
 test/package-manager/explicit_yarn.sh         |  12 +
 test/package-manager/scenarios.json           |  35 +--
 test/package-manager/test.sh                  |  26 +-
 test/rust/scenarios.json                      |   7 +-
 test/rust/test.sh                             |  24 +-
 test/zig/explicit_version.sh                  |  12 +
 test/zig/scenarios.json                       |  20 +-
 test/zig/test.sh                              |  17 +-
 28 files changed, 540 insertions(+), 478 deletions(-)
 create mode 100644 test/biome/install_custom_version.sh
 create mode 100644 test/homebrew/remote_user_vscode.sh
 create mode 100644 test/package-manager/explicit_pnpm.sh
 create mode 100644 test/package-manager/explicit_yarn.sh
 create mode 100644 test/zig/explicit_version.sh

diff --git a/.github/instructions/FEATURE.instructions.md b/.github/instructions/FEATURE.instructions.md
index 65d3b1b..dde5e3a 100644
--- a/.github/instructions/FEATURE.instructions.md
+++ b/.github/instructions/FEATURE.instructions.md
@@ -36,14 +36,15 @@ affected files together in the same commit:
 1. `src/<id>/devcontainer-feature.json` — `"version"` field and
    option `"default"` value
 2. `test/<id>/test.sh` — `grep "<version>"` assertions
-3. `test/<id>/scenarios.json` — step descriptions mentioning the version
-4. `docs/features/<id>.md` — usage snippet and options default listing
+3. `test/<id>/scenarios.json` — scenario option values mentioning the version
+4. `test/<id>/<scenario_name>.sh` — `grep "<version>"` assertions in scenario scripts
+5. `docs/features/<id>.md` — usage snippet and options default listing
 
 Use the `bump-feature` skill for guided step-by-step assistance.
 
 ## Five-File Completeness Rule
 
-Every feature must have exactly five files. Before committing, verify all are
+Every feature must have at least these five files. Before committing, verify all are
 present:
 
 ```text
@@ -54,6 +55,9 @@ test/<id>/scenarios.json
 docs/features/<id>.md
 ```
 
+If `scenarios.json` is non-empty (contains scenario keys), each key also
+requires a matching `test/<id>/<scenario_name>.sh` assertion script.
+
 Run `pnpm run validate-feature <id>` to check completeness.
 
 **Note on executable bits:** scripts are stored as `100644` (non-executable)
diff --git a/.github/skills/devcontainer/references/test-patterns.md b/.github/skills/devcontainer/references/test-patterns.md
index c6fd4d0..5713c2a 100644
--- a/.github/skills/devcontainer/references/test-patterns.md
+++ b/.github/skills/devcontainer/references/test-patterns.md
@@ -1,7 +1,10 @@
 # Test Patterns
 
-Reference for the two-file test convention used in this repository:
-`test.sh` and `scenarios.json`.
+Reference for the three-file test convention used in this repository,
+following the official `devcontainer features test` CLI pattern:
+`test.sh`, `scenarios.json`, and per-scenario `<name>.sh` scripts.
+
+See also: [devcontainer features test CLI docs](https://github.com/devcontainers/cli/blob/main/docs/features/test.md)
 
 ## File Locations
 
@@ -11,191 +14,205 @@ directory structure:
 ```text
 test/
   <id>/
-    test.sh        # shell assertions (executable bit set by Husky/CI, not committed)
-    scenarios.json # human-readable scenario descriptions
+    test.sh                # auto-generated default test (default options)
+    scenarios.json         # map of scenario names → devcontainer.json fragments
+    <scenario_name>.sh     # one assertion script per entry in scenarios.json
 ```
 
-Both files are required. The CI publish workflow discovers tests by resolving
-`test/<id>/test.sh` from the feature id.
-
-## `scenarios.json`
+`test.sh` and `scenarios.json` are always required (five-file rule). Each key
+in `scenarios.json` requires a matching `<key>.sh` assertion script.
 
-An array of scenario objects. Each object describes one logical test scenario.
+## `test.sh` — Default (Auto-Generated) Test
 
-### Schema
+The auto-generated test builds a container that installs the feature with
+**default options** and then runs `test.sh` inside it. It must use
+`dev-container-features-test-lib` for `check` and `reportResults`.
 
-```json
-[
-  {
-    "name": "Human-readable scenario name",
-    "steps": [
-      "Step one description",
-      "Step two description"
-    ]
-  }
-]
-```
+### Structure
 
-### Rules
+```bash
+#!/usr/bin/env bash
+# Brief comment describing what this test verifies
+set -e
 
-- At least one scenario per feature
-- `name` — short, title-case, describes what the scenario verifies
-- `steps` — ordered list of what the test checks; mirrors the assertions in
-  `test.sh`
-- Not executed by CI — this file is documentation and a checklist for humans
-  reviewing the test
+# Import test library provided by the devcontainer CLI
+source dev-container-features-test-lib
 
-### Example
+check "binary is installed" <binary> --version
+check "version matches default" bash -c "<binary> --version | grep '<default-version>'"
 
-```json
-[
-  {
-    "name": "Biome global install",
-    "steps": ["Install feature", "Check Biome version is 2.4.12"]
-  }
-]
+reportResults
 ```
 
-## `test.sh`
+### Rules
 
-An executable Bash script that runs assertions after the feature is installed
-in the devcontainer. The executable bit is set by Husky (locally) and by CI
-workflows — scripts are stored in git without the bit (`100644`).
+- `#!/usr/bin/env bash` + `set -e` (not `set -euo pipefail` — the test lib
+  uses unset variables internally)
+- `source dev-container-features-test-lib` before any `check` calls
+- `check "<LABEL>" <cmd> [args...]` — runs the command; records pass/fail
+  based on exit code; always returns 0 so the script continues on failure
+- For output-content checks, wrap in `bash -c "cmd | grep 'pattern'"`
+- `reportResults` at the end — prints the summary and exits non-zero if any
+  `check` failed
+- Keep tests fast — no network calls, no compilation, no side effects
 
-### Structure
+### Example: Biome
 
 ```bash
 #!/usr/bin/env bash
-set -euo pipefail
+set -e
+source dev-container-features-test-lib
 
-# Assertion 1: binary is in PATH
-<binary> --version || { echo "[FAIL] <binary> not found" >&2; exit 1; }
+check "biome is installed" biome --version
+check "biome default version is 2.4.13" bash -c "biome --version | grep '2.4.13'"
 
-# Assertion 2: version matches the pinned default
-<binary> --version | grep "<expected-version>" \
-  || { echo "[FAIL] <binary> version mismatch" >&2; exit 1; }
-
-echo "[PASS] <Feature name> test passed."
+reportResults
 ```
 
-### Rules
+## `scenarios.json` — Scenario Definitions
 
-- `#!/usr/bin/env bash` + `set -euo pipefail` — same as `install.sh`
-- One assertion per binary or property to verify
-- Use `|| { echo "[FAIL] <message>" >&2; exit 1; }` to emit a clear failure
-  message before exiting
-- Print `[PASS]` at the end so CI logs show a clear success marker
-- Version assertions must use `grep` against the exact default version string
-  defined in `devcontainer-feature.json`
-- Keep tests fast — no network calls, no compilation, no side effects
+A JSON **object** (not array) where each key is a scenario name and the value
+is a `devcontainer.json` fragment. The scenario name also serves as the
+filename for the assertion script that runs inside the built container.
 
-### What to Test
+### Schema
 
-| Check | Example assertion |
-| :---- | :---------------- |
-| Binary exists in `$PATH` | `command -v biome` or `biome --version` |
-| Version matches pinned default | `biome --version \| grep "2.4.12"` |
-| Key subcommand available | `cargo --version`, `rustc --version` |
+```json
+{
+  "<scenario_name>": {
+    "image": "<base-image>",
+    "features": {
+      "<feature-id>": { "<option>": "<value>" }
+    },
+    "remoteUser": "<optional-non-root-user>"
+  }
+}
+```
 
-### What Not to Test
+### Rules
 
-- Full functional behavior (e.g. linting a real file, compiling code)
-- Network connectivity or registry access
-- Side effects of options other than the default
+- Keys are `snake_case` scenario names — they become assertion script filenames
+- Each scenario must have a matching `<scenario_name>.sh` assertion script
+- Use `"image": "mcr.microsoft.com/devcontainers/base:ubuntu"` as the default
+  base image (provides a `vscode` non-root user and common tools)
+- To test a feature with a non-root `remoteUser`, set `"remoteUser": "vscode"` —
+  the `_REMOTE_USER` env var will be `vscode` during install
+- To test a feature that depends on another local feature (e.g. `package-manager`
+  requires `node`), list both in `"features"` using short IDs (`"node"` maps to
+  `./src/node`)
+- Use `{}` when there are no meaningful option variants to test
 
-Functional tests belong in integration test suites, not in feature tests.
-Keep feature tests hermetic and fast.
+### Example: biome
 
-### Example: Biome
+```json
+{
+  "install_custom_version": {
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+      "biome": { "biomeVersion": "2.4.12" }
+    }
+  }
+}
+```
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
+### Example: package-manager (cross-feature dependency)
 
-# Test: Biome global install
-biome --version | grep "2.3.14" || { echo "[FAIL] Biome version mismatch" >&2; exit 1; }
-echo "[PASS] Biome global install test passed."
+```json
+{
+  "explicit_pnpm": {
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+      "node": {},
+      "package-manager": { "packageManager": "pnpm@10.20.0" }
+    }
+  }
+}
 ```
 
-### Example: Rust (multiple binaries)
+## `<scenario_name>.sh` — Scenario Assertion Scripts
+
+One script per key in `scenarios.json`. Same structure as `test.sh`, but
+assertions verify the scenario's specific options rather than defaults.
+
+### Example: `install_custom_version.sh`
 
 ```bash
 #!/usr/bin/env bash
-set -euo pipefail
+# Scenario: install a non-default biome version (biomeVersion=2.4.12)
+set -e
+source dev-container-features-test-lib
 
-# Test: Rust toolchain install
-rustc --version || { echo "[FAIL] rustc not found" >&2; exit 1; }
-cargo --version || { echo "[FAIL] cargo not found" >&2; exit 1; }
-echo "[PASS] Rust toolchain install test passed."
-```
+check "biome is installed" biome --version
+check "custom biome version is 2.4.12" bash -c "biome --version | grep '2.4.12'"
 
-## CI Integration
+reportResults
+```
 
-The `.github/workflows/publish.yml` workflow runs tests as follows:
+## Running Tests
 
-1. **`collect`** job — `collect-and-filter-features.js` builds a JSON matrix
-   of features not yet published at their current version
-2. **`test`** job — fan-out matrix job that runs
-   `test/<id>/test.sh` for each feature in the matrix
-3. Result is written to `/tmp/results/<id>.txt` as `success` or
-   `failure` and uploaded as an artifact named `test-result-<id>`
-4. **`summarize`** job — downloads all result artifacts, writes a Markdown
-   table to `$GITHUB_STEP_SUMMARY`, and fails (blocking publish) if any test
-   failed
+### `devcontainer features test` CLI modes
 
-### Implications for Test Authors
+| Mode | CLI flags | What it does |
+| :--- | :-------- | :----------- |
+| Auto-generated | (default) | Builds a container with the feature at default options; runs `test.sh` |
+| Scenarios | (default) | Builds one container per entry in `scenarios.json`; runs `<name>.sh` |
+| Skip auto-gen | `--skip-autogenerated` | Runs only scenario tests |
+| Skip scenarios | `--skip-scenarios` | Runs only the auto-generated test |
 
-- A non-zero exit code from `test.sh` is treated as a test failure
-- The test script runs inside the devcontainer that has the feature installed
-- There is no test framework — plain Bash assertions with `exit 1` on failure
-- The test must be self-contained; it cannot rely on files from the repo
-  unless they are copied in as part of the feature install
+`--skip-duplicated` is always passed to skip the duplicate-install stress test
+(no `duplicate.sh` files exist in this repo).
 
-## Local Testing with act
+### Local testing
 
-The repo provides a dedicated workflow and wrapper script for running a single
-feature's install + test cycle locally using
-[act](https://nektosact.com).
+```bash
+# Test a single feature (all modes: auto-generated + scenarios)
+pnpm run test:feature biome
 
-### Prerequisites
+# Runs:
+#   devcontainer features test -f biome \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu \
+#     --skip-duplicated .
+```
 
-- Docker running locally
-- `act` installed — add `ghcr.io/savvy-web/act:0.1.0` to your
-  `devcontainer.json`, or install via the
-  [act installation guide](https://nektosact.com/installation/index.html)
+Requires Docker and `@devcontainers/cli` (`npm install -g @devcontainers/cli`).
 
-### Running a single feature test
+### Features with local `installsAfter` dependencies
 
-```bash
-pnpm run test:feature biome
-pnpm run test:feature rust
-pnpm run test:feature package-manager
-```
+`package-manager` declares `"installsAfter": ["ghcr.io/savvy-web/node"]`.
+Because the auto-generated test only installs the tested feature, `corepack`
+would be missing. `scripts/test-feature.sh` and `test.yml` detect this by
+reading `installsAfter` and automatically add `--skip-autogenerated` for such
+features. Scenarios for these features explicitly list the required dependency
+in their `"features"` map.
 
-Running without arguments prints available features.
+## CI Integration
 
-### How it works
+`test.yml` (PR CI) runs `devcontainer features test` per feature:
 
-`scripts/test-feature.sh` calls `act workflow_dispatch` targeting
-`.github/workflows/test-feature.yml` — a minimal workflow that:
+1. **`discover`** job — scans `src/` and `test/` to build a dynamic matrix of
+   `[{ id, skipAutogenerated }]` entries; `skipAutogenerated` is `true` when
+   `installsAfter` references a local `ghcr.io/savvy-web/` feature
+2. **`test`** job — fan-out matrix; installs `@devcontainers/cli`; runs
+   `devcontainer features test -f <id> -i <base-image> [--skip-autogenerated] --skip-duplicated .`
+3. Output is collected per job with `::group::` for the test log and written
+   to `$GITHUB_STEP_SUMMARY` — each feature gets a `✅` or `❌` heading
 
-1. Checks out the repo (using the local bind-mount from `.actrc`)
-2. Runs `src/<id>/install.sh` inside a fresh ubuntu container
-3. Runs `test/<id>/test.sh` in the same container
+The `publish.yml` test job follows the same pattern before publishing to GHCR.
 
-The `.actrc` at the repo root configures act to:
+## What to Test
 
-- Use `catthehacker/ubuntu:act-latest` as the ubuntu-latest runner image
-- Bind-mount the local workspace (no network clone, much faster)
-- Remove the container after each run (`--rm`)
+| Check | Example assertion |
+| :---- | :---------------- |
+| Binary exists in `$PATH` | `check "binary is installed" <binary> --version` |
+| Version matches pinned default | `check "version is X" bash -c "<binary> --version \| grep 'X'"` |
+| Key subcommand available | `check "cargo is installed" cargo --version` |
+| File exists at expected path | `check "binary exists" test -x "/path/to/binary"` |
 
-### Debugging a failing test
+## What Not to Test
 
-If `test.sh` fails, re-run with act's verbose flag to see the full output:
+- Full functional behavior (e.g. linting a real file, compiling code)
+- Network connectivity or registry access after install
+- Side effects of options that are already tested by the default
 
-```bash
-act workflow_dispatch \
-  --input id=biome \
-  -W .github/workflows/test-feature.yml \
-  --verbose
-```
+Functional tests belong in integration test suites, not in feature tests.
+Keep feature tests hermetic and fast.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index d42b31c..6a28277 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -42,39 +42,34 @@ jobs:
       # - name: Setup Runtime
       #   id: runtime
       #   uses: savvy-web/workflow-runtime-action@main
-      - name: Install feature
-        id: install
-        timeout-minutes: 3
+      - name: Install devcontainer CLI
+        run: npm install -g @devcontainers/cli
+      - name: Test Feature
+        id: test
+        timeout-minutes: 15
         continue-on-error: true
         env:
           FEATURE_ID: ${{ matrix.id }}
         run: |
-          INSTALL_SCRIPT="src/${FEATURE_ID}/install.sh"
-          if [[ ! -f "$INSTALL_SCRIPT" ]]; then
-            echo "[ERROR] Install script not found: $INSTALL_SCRIPT" >&2
-            exit 1
+          FEATURE_JSON="src/${FEATURE_ID}/devcontainer-feature.json"
+          SKIP_AUTOGENERATED=$(node -e "
+            const j = JSON.parse(require('fs').readFileSync('${FEATURE_JSON}', 'utf8'));
+            const deps = j.installsAfter || [];
+            process.stdout.write(
+              deps.some(d => d.includes('ghcr.io/savvy-web/')) ? 'true' : 'false'
+            );
+          ")
+          BASE_IMAGE="mcr.microsoft.com/devcontainers/base:ubuntu"
+          ARGS=(-f "$FEATURE_ID" -i "$BASE_IMAGE" --skip-duplicated)
+          if [[ "$SKIP_AUTOGENERATED" == "true" ]]; then
+            ARGS+=(--skip-autogenerated)
           fi
-          chmod +x "$INSTALL_SCRIPT"
-          sudo bash "$INSTALL_SCRIPT" 2>&1 | tee /tmp/install.log
-      - name: Test Feature
-        id: test
-        timeout-minutes: 3
-        continue-on-error: true
-        run: |
-          chmod +x test/${{ matrix.id }}/test.sh
-          sudo bash test/${{ matrix.id }}/test.sh 2>&1 | tee /tmp/test.log
+          devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
       - name: Save result
         if: always()
         run: |
           mkdir -p /tmp/results
-          # Overall outcome: failure if either install or test failed
-          if [[ "${{ steps.install.outcome }}" == "failure" ]]; then
-            echo "failure" > /tmp/results/${{ matrix.id }}.txt
-          else
-            echo "${{ steps.test.outcome }}" > /tmp/results/${{ matrix.id }}.txt
-          fi
-          # Capture detailed logs for debugging
-          cp /tmp/install.log /tmp/results/${{ matrix.id }}-install.log 2>/dev/null || echo "No install log" > /tmp/results/${{ matrix.id }}-install.log
+          echo "${{ steps.test.outcome }}" > /tmp/results/${{ matrix.id }}.txt
           cp /tmp/test.log /tmp/results/${{ matrix.id }}-test.log 2>/dev/null || echo "No test log" > /tmp/results/${{ matrix.id }}-test.log
       - name: Upload result
         if: always()
@@ -134,14 +129,6 @@ jobs:
                 name=$(basename "$file" .txt)
                 result=$(cat "$file")
                 if [ "$result" != "success" ]; then
-                  echo "<details><summary><strong>${name}</strong> — install log</summary>"
-                  echo ""
-                  echo '```'
-                  cat "/tmp/results/${name}-install.log" 2>/dev/null || echo "Log not found"
-                  echo '```'
-                  echo ""
-                  echo "</details>"
-                  echo ""
                   echo "<details><summary><strong>${name}</strong> — test log</summary>"
                   echo ""
                   echo '```'
diff --git a/.github/workflows/test-feature.yml b/.github/workflows/test-feature.yml
index 2eacfbd..da994e1 100644
--- a/.github/workflows/test-feature.yml
+++ b/.github/workflows/test-feature.yml
@@ -15,28 +15,33 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Install feature
-        timeout-minutes: 3
+      - name: Install devcontainer CLI
+        run: npm install -g @devcontainers/cli
+
+      - name: Run feature tests
         env:
           FEATURE_ID: ${{ inputs.id }}
         run: |
-          INSTALL_SCRIPT="src/${FEATURE_ID}/install.sh"
-          if [[ ! -f "$INSTALL_SCRIPT" ]]; then
-            echo "[ERROR] Install script not found: $INSTALL_SCRIPT" >&2
+          FEATURE_JSON="src/${FEATURE_ID}/devcontainer-feature.json"
+          if [[ ! -f "$FEATURE_JSON" ]]; then
+            echo "[ERROR] Feature not found: src/${FEATURE_ID}" >&2
             exit 1
           fi
-          chmod +x "$INSTALL_SCRIPT"
-          sudo bash "$INSTALL_SCRIPT"
 
-      - name: Run tests
-        timeout-minutes: 3
-        env:
-          FEATURE_ID: ${{ inputs.id }}
-        run: |
-          TEST_SCRIPT="test/${FEATURE_ID}/test.sh"
-          if [[ ! -f "$TEST_SCRIPT" ]]; then
-            echo "[ERROR] Test script not found: $TEST_SCRIPT" >&2
-            exit 1
+          # Skip auto-generated test if the feature depends on another local
+          # savvy-web feature (those must be wired in via scenarios instead).
+          SKIP_AUTOGENERATED=$(node -e "
+            const j = JSON.parse(require('fs').readFileSync('${FEATURE_JSON}', 'utf8'));
+            const deps = j.installsAfter || [];
+            process.stdout.write(
+              deps.some(d => d.includes('ghcr.io/savvy-web/')) ? 'true' : 'false'
+            );
+          ")
+
+          BASE_IMAGE="mcr.microsoft.com/devcontainers/base:ubuntu"
+          ARGS=(-f "$FEATURE_ID" -i "$BASE_IMAGE" --skip-duplicated)
+          if [[ "$SKIP_AUTOGENERATED" == "true" ]]; then
+            ARGS+=(--skip-autogenerated)
           fi
-          chmod +x "$TEST_SCRIPT"
-          sudo bash "$TEST_SCRIPT"
+
+          devcontainer features test "${ARGS[@]}" .
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 9f44655..c23ef67 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -6,140 +6,102 @@ on:
     #   branches: [main]
 
 jobs:
-  collect:
+  discover:
     runs-on: ubuntu-latest
     permissions:
       contents: read
     outputs:
-      matrix: ${{ steps.tests.outputs.matrix }}
+      matrix: ${{ steps.features.outputs.matrix }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Discover test directories
-        id: tests
+      - name: Discover features
+        id: features
         run: |
-          # Discover all feature ids that have a test.sh under test/<id>/
           matrix=$(node -e "
             const fs = require('fs');
             const path = require('path');
+            const srcRoot = path.resolve('src');
             const testRoot = path.resolve('test');
-            if (!fs.existsSync(testRoot)) { process.stdout.write('[]'); process.exit(0); }
-            const entries = fs.readdirSync(testRoot)
-              .filter(f => fs.statSync(path.join(testRoot, f)).isDirectory())
-              .filter(f => fs.existsSync(path.join(testRoot, f, 'test.sh')))
-              .map(id => ({ id, testdir: 'test/' + id }));
+            if (!fs.existsSync(srcRoot)) { process.stdout.write('[]'); process.exit(0); }
+            const entries = fs.readdirSync(srcRoot)
+              .filter(f => {
+                const featureJson = path.join(srcRoot, f, 'devcontainer-feature.json');
+                const testSh = path.join(testRoot, f, 'test.sh');
+                return fs.existsSync(featureJson) && fs.existsSync(testSh);
+              })
+              .map(id => {
+                const featureJson = JSON.parse(
+                  fs.readFileSync(path.join(srcRoot, id, 'devcontainer-feature.json'), 'utf8')
+                );
+                const installsAfter = featureJson.installsAfter || [];
+                // Skip auto-generated test for features that depend on another
+                // local savvy-web feature (e.g. package-manager requires node).
+                const skipAutogenerated = installsAfter.some(dep =>
+                  dep.includes('ghcr.io/savvy-web/')
+                );
+                return { id, skipAutogenerated };
+              });
             process.stdout.write(JSON.stringify(entries));
           ")
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
 
-  test-features:
-    needs: collect
-    if: ${{ needs.collect.outputs.matrix != '[]' }}
+  test:
+    needs: discover
+    if: ${{ needs.discover.outputs.matrix != '[]' }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
     strategy:
       fail-fast: false
       matrix:
-        include: ${{ fromJson(needs.collect.outputs.matrix) }}
+        include: ${{ fromJson(needs.discover.outputs.matrix) }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      # - name: Setup Runtime
-      #   id: runtime
-      #   uses: savvy-web/workflow-runtime-action@main
+      - name: Install devcontainer CLI
+        run: npm install -g @devcontainers/cli
 
-      - name: Install feature
-        id: install
-        timeout-minutes: 3
-        continue-on-error: true
-        env:
-          FEATURE_ID: ${{ matrix.id }}
-        run: |
-          INSTALL_SCRIPT="src/${FEATURE_ID}/install.sh"
-          if [[ ! -f "$INSTALL_SCRIPT" ]]; then
-            echo "[ERROR] Install script not found: $INSTALL_SCRIPT" >&2
-            exit 1
-          fi
-          chmod +x "$INSTALL_SCRIPT"
-          sudo bash "$INSTALL_SCRIPT" 2>&1 | tee /tmp/install.log
-
-      - name: Run tests
+      - name: Run feature tests
         id: test
-        timeout-minutes: 3
         continue-on-error: true
-        if: steps.install.outcome == 'success'
+        timeout-minutes: 15
         env:
           FEATURE_ID: ${{ matrix.id }}
+          SKIP_AUTOGENERATED: ${{ matrix.skipAutogenerated }}
         run: |
-          TEST_SCRIPT="test/${FEATURE_ID}/test.sh"
-          if [[ ! -f "$TEST_SCRIPT" ]]; then
-            echo "[ERROR] Test script not found: $TEST_SCRIPT" >&2
-            exit 1
+          BASE_IMAGE="mcr.microsoft.com/devcontainers/base:ubuntu"
+          ARGS=(-f "$FEATURE_ID" -i "$BASE_IMAGE" --skip-duplicated)
+          if [[ "$SKIP_AUTOGENERATED" == "true" ]]; then
+            ARGS+=(--skip-autogenerated)
           fi
-          chmod +x "$TEST_SCRIPT"
-          sudo bash "$TEST_SCRIPT" 2>&1 | tee /tmp/test.log
+          echo "::group::devcontainer features test ${ARGS[*]} ."
+          devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          echo "::endgroup::"
 
       - name: Write step summary
         if: always()
         run: |
           {
-            echo "## ${{ matrix.id }}"
-            echo ""
-            if [[ "${{ steps.install.outcome }}" == "failure" ]]; then
-              echo "❌ **Install failed**"
-              echo ""
-              echo "<details><summary>Install log</summary>"
-              echo ""
-              echo '```'
-              cat /tmp/install.log 2>/dev/null || echo "No install log captured"
-              echo '```'
-              echo "</details>"
-            elif [[ "${{ steps.test.outcome }}" == "failure" ]]; then
-              echo "✅ Install succeeded — ❌ **Test failed**"
-              echo ""
-              echo "<details><summary>Install log</summary>"
-              echo ""
-              echo '```'
-              cat /tmp/install.log 2>/dev/null || echo "No install log captured"
-              echo '```'
-              echo "</details>"
-              echo ""
-              echo "<details><summary>Test log</summary>"
-              echo ""
-              echo '```'
-              cat /tmp/test.log 2>/dev/null || echo "No test log captured"
-              echo '```'
-              echo "</details>"
+            if [[ "${{ steps.test.outcome }}" == "success" ]]; then
+              echo "## ✅ ${{ matrix.id }}"
             else
-              echo "✅ Install and test passed"
-              echo ""
-              echo "<details><summary>Install log</summary>"
-              echo ""
-              echo '```'
-              cat /tmp/install.log 2>/dev/null || echo "No install log captured"
-              echo '```'
-              echo "</details>"
-              echo ""
-              echo "<details><summary>Test log</summary>"
-              echo ""
-              echo '```'
-              cat /tmp/test.log 2>/dev/null || echo "No test log captured"
-              echo '```'
-              echo "</details>"
+              echo "## ❌ ${{ matrix.id }}"
             fi
+            echo ""
+            echo "<details><summary>Test log</summary>"
+            echo ""
+            echo '```'
+            cat /tmp/test.log 2>/dev/null || echo "No log captured"
+            echo '```'
+            echo ""
+            echo "</details>"
           } >> "$GITHUB_STEP_SUMMARY"
 
-      - name: Fail if install failed
-        if: steps.install.outcome == 'failure'
-        run: |
-          echo "::error::Install failed for ${{ matrix.id }}. See step summary for details."
-          exit 1
-
-      - name: Fail if test failed
+      - name: Fail if tests failed
         if: steps.test.outcome == 'failure'
         run: |
-          echo "::error::Test failed for ${{ matrix.id }}. See step summary for details."
+          echo "::error::Tests failed for ${{ matrix.id }}. See step summary for details."
           exit 1
diff --git a/scripts/test-feature.sh b/scripts/test-feature.sh
index 73e69b0..6425e07 100755
--- a/scripts/test-feature.sh
+++ b/scripts/test-feature.sh
@@ -1,15 +1,21 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Test a single devcontainer feature locally using act.
+# Test a single devcontainer feature locally using the devcontainer CLI.
 #
 # Usage:
 #   pnpm run test:feature <id>
 #   pnpm run test:feature biome
 #   pnpm run test:feature package-manager
 #
-# Requires act: https://nektosact.com
-# Install with the act devcontainer feature or via: https://github.com/nektos/act
+# Requires:
+#   - Docker running locally
+#   - @devcontainers/cli: npm install -g @devcontainers/cli
+#
+# The devcontainer CLI builds a real container per scenario, runs the feature
+# install, and executes the assertion scripts (test.sh + any scenario .sh
+# files listed in scenarios.json). Output is per-scenario with clear
+# pass/fail markers.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
@@ -33,34 +39,38 @@ if [[ -z "$ID" ]]; then
   exit 1
 fi
 
-FEATURE_DIR="${REPO_ROOT}/src/${ID}"
-TEST_DIR="${REPO_ROOT}/test/${ID}"
+FEATURE_JSON="${REPO_ROOT}/src/${ID}/devcontainer-feature.json"
 
-if [[ ! -f "${FEATURE_DIR}/devcontainer-feature.json" ]]; then
+if [[ ! -f "$FEATURE_JSON" ]]; then
   echo "[ERROR] Feature not found: src/${ID}" >&2
   echo "        Run '$0' without arguments to see available features." >&2
   exit 1
 fi
 
-if [[ ! -f "${TEST_DIR}/test.sh" ]]; then
-  echo "[ERROR] Test script not found: test/${ID}/test.sh" >&2
+if ! command -v devcontainer &>/dev/null; then
+  echo "[ERROR] @devcontainers/cli is not installed." >&2
+  echo "        Install it with: npm install -g @devcontainers/cli" >&2
   exit 1
 fi
 
-if ! command -v act &>/dev/null; then
-  echo "[ERROR] act is not installed." >&2
-  echo "        Install it with: https://nektosact.com/installation/index.html" >&2
-  echo "        Or add the act devcontainer feature to your devcontainer.json:" >&2
-  echo "        \"ghcr.io/savvy-web/act:0.1.0\": {}" >&2
-  exit 1
+# Skip auto-generated test for features that depend on another local
+# savvy-web feature (corepack/node must be wired in via scenarios).
+SKIP_AUTOGENERATED=$(node -e "
+  const j = JSON.parse(require('fs').readFileSync('${FEATURE_JSON}', 'utf8'));
+  const deps = j.installsAfter || [];
+  process.stdout.write(
+    deps.some(d => d.includes('ghcr.io/savvy-web/')) ? 'true' : 'false'
+  );
+")
+
+BASE_IMAGE="mcr.microsoft.com/devcontainers/base:ubuntu"
+ARGS=(-f "$ID" -i "$BASE_IMAGE" --skip-duplicated)
+if [[ "$SKIP_AUTOGENERATED" == "true" ]]; then
+  ARGS+=(--skip-autogenerated)
 fi
 
 echo "[INFO] Testing feature: ${ID}"
 echo ""
 
 cd "${REPO_ROOT}"
-
-act workflow_dispatch \
-  --input id="${ID}" \
-  -W .github/workflows/test-feature.yml \
-  --rm
+devcontainer features test "${ARGS[@]}" .
diff --git a/scripts/validate-feature.sh b/scripts/validate-feature.sh
index 86e35d4..9b5f1e6 100755
--- a/scripts/validate-feature.sh
+++ b/scripts/validate-feature.sh
@@ -193,16 +193,22 @@ if [[ -f "$TEST_SH" ]]; then
     fail "test.sh first line must be '#!/usr/bin/env bash', got: ${FIRST_LINE}"
   fi
 
-  if grep -q "set -euo pipefail" "$TEST_SH"; then
-    pass "test.sh has 'set -euo pipefail'"
+  if grep -q "set -e" "$TEST_SH"; then
+    pass "test.sh has 'set -e'"
   else
-    fail "test.sh is missing 'set -euo pipefail'"
+    fail "test.sh is missing 'set -e'"
   fi
 
-  if grep -q "\[PASS\]" "$TEST_SH"; then
-    pass "test.sh has a [PASS] marker"
+  if grep -q "source dev-container-features-test-lib" "$TEST_SH"; then
+    pass "test.sh sources dev-container-features-test-lib"
   else
-    fail "test.sh is missing a [PASS] marker at the end"
+    fail "test.sh must source dev-container-features-test-lib"
+  fi
+
+  if grep -q "reportResults" "$TEST_SH"; then
+    pass "test.sh calls reportResults"
+  else
+    fail "test.sh is missing a reportResults call"
   fi
 fi
 
@@ -211,12 +217,27 @@ fi
 if [[ -f "$SCENARIOS_FILE" ]]; then
   if node -e "
     const j = JSON.parse(require('fs').readFileSync('${SCENARIOS_FILE}', 'utf8'));
-    if (!Array.isArray(j) || j.length === 0) process.exit(1);
+    if (Array.isArray(j)) process.exit(1);
   " 2>/dev/null; then
-    pass "scenarios.json is a non-empty array"
+    pass "scenarios.json is a valid object"
   else
-    fail "scenarios.json must be a non-empty JSON array"
+    fail "scenarios.json must be a JSON object (not an array) — keys are scenario names"
   fi
+
+  # Verify each scenario key has a matching .sh assertion script
+  SCENARIO_KEYS=$(node -e "
+    const j = JSON.parse(require('fs').readFileSync('${SCENARIOS_FILE}', 'utf8'));
+    process.stdout.write(Object.keys(j).join('\n'));
+  " 2>/dev/null)
+  while IFS= read -r key; do
+    [[ -z "$key" ]] && continue
+    SCENARIO_SH="${TEST_DIR}/${key}.sh"
+    if [[ -f "$SCENARIO_SH" ]]; then
+      pass "scenario '${key}' has assertion script: test/${ID}/${key}.sh"
+    else
+      fail "scenario '${key}' is missing assertion script: test/${ID}/${key}.sh"
+    fi
+  done <<< "$SCENARIO_KEYS"
 fi
 
 # ── Summary ───────────────────────────────────────────────────────────────────
diff --git a/test/act/scenarios.json b/test/act/scenarios.json
index 5d75fed..0967ef4 100644
--- a/test/act/scenarios.json
+++ b/test/act/scenarios.json
@@ -1,6 +1 @@
-[
-	{
-		"name": "act global install",
-		"steps": ["Install feature", "Check act version is 0.2.76"]
-	}
-]
+{}
diff --git a/test/act/test.sh b/test/act/test.sh
index 793287b..dd3b80b 100755
--- a/test/act/test.sh
+++ b/test/act/test.sh
@@ -1,6 +1,16 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'act' feature with default options (actVersion=0.2.76).
+#
+# Run with:
+#   devcontainer features test -f act --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-act --version || { echo "[FAIL] act not found in PATH" >&2; exit 1; }
-act --version | grep "0.2.76" || { echo "[FAIL] act version mismatch" >&2; exit 1; }
-echo "[PASS] act install test passed."
+set -e
+
+source dev-container-features-test-lib
+
+check "act is installed" act --version
+check "act default version is 0.2.76" bash -c "act --version | grep '0.2.76'"
+
+reportResults
diff --git a/test/biome/install_custom_version.sh b/test/biome/install_custom_version.sh
new file mode 100644
index 0000000..138c6f5
--- /dev/null
+++ b/test/biome/install_custom_version.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Scenario: install a non-default biome version (biomeVersion=2.4.12)
+# and verify the installed version matches the requested one.
+
+set -e
+
+source dev-container-features-test-lib
+
+check "biome is installed" biome --version
+check "custom biome version is 2.4.12" bash -c "biome --version | grep '2.4.12'"
+
+reportResults
diff --git a/test/biome/scenarios.json b/test/biome/scenarios.json
index b9cc12f..3574354 100644
--- a/test/biome/scenarios.json
+++ b/test/biome/scenarios.json
@@ -1,6 +1,10 @@
-[
-	{
-		"name": "Biome global install",
-		"steps": ["Install feature", "Check Biome version is 2.4.13"]
+{
+	"install_custom_version": {
+		"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+		"features": {
+			"biome": {
+				"biomeVersion": "2.4.12"
+			}
+		}
 	}
-]
+}
diff --git a/test/biome/test.sh b/test/biome/test.sh
index d705cfd..6a0aa91 100755
--- a/test/biome/test.sh
+++ b/test/biome/test.sh
@@ -1,6 +1,18 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'biome' feature with default options (biomeVersion=2.4.13).
+#
+# Run with:
+#   devcontainer features test -f biome --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test: Biome global install
-biome --version | grep "2.4.13" || { echo "[FAIL] Biome version mismatch" >&2; exit 1; }
-echo "[PASS] Biome global install test passed."
+set -e
+
+# Import test library provided by the devcontainer CLI
+# https://github.com/devcontainers/cli/blob/main/docs/features/test.md
+source dev-container-features-test-lib
+
+check "biome is installed" biome --version
+check "biome default version is 2.4.13" bash -c "biome --version | grep '2.4.13'"
+
+reportResults
diff --git a/test/claude-code/scenarios.json b/test/claude-code/scenarios.json
index c638e1c..0967ef4 100644
--- a/test/claude-code/scenarios.json
+++ b/test/claude-code/scenarios.json
@@ -1,16 +1 @@
-[
-	{
-		"name": "Default install",
-		"options": {},
-		"expect": {
-			"cli": "claude --version"
-		}
-	},
-	{
-		"name": "Install specific version",
-		"options": { "version": "0.1.0" },
-		"expect": {
-			"cli": "claude --version | grep 0.1.0"
-		}
-	}
-]
+{}
diff --git a/test/claude-code/test.sh b/test/claude-code/test.sh
index 6059b25..6f520f8 100755
--- a/test/claude-code/test.sh
+++ b/test/claude-code/test.sh
@@ -1,13 +1,15 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'claude-code' feature with default options (version=latest).
+#
+# Run with:
+#   devcontainer features test -f claude-code --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test Claude Code global feature
+set -e
 
-if ! command -v claude &>/dev/null; then
-  echo "[FAIL] claude CLI not found in PATH"
-  exit 1
-fi
+source dev-container-features-test-lib
 
-claude --version
+check "claude CLI is installed" claude --version
 
-echo "[PASS] Claude Code install test passed."
+reportResults
diff --git a/test/homebrew/remote_user_vscode.sh b/test/homebrew/remote_user_vscode.sh
new file mode 100644
index 0000000..e5395ef
--- /dev/null
+++ b/test/homebrew/remote_user_vscode.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Scenario: install Homebrew with remoteUser=vscode (_REMOTE_USER=vscode).
+# install.sh installs Homebrew as the vscode user under /home/linuxbrew/.linuxbrew
+# and adds it to PATH via /etc/profile.d/homebrew.sh. This test runs as the
+# vscode user and verifies brew is functional using the full binary path to
+# avoid relying on interactive-shell PATH setup.
+
+set -e
+
+source dev-container-features-test-lib
+
+BREW_BIN="/home/linuxbrew/.linuxbrew/bin/brew"
+
+check "brew binary exists" test -x "$BREW_BIN"
+check "brew is functional" "$BREW_BIN" --version
+check "brew version output includes Homebrew" bash -c "$BREW_BIN --version | grep Homebrew"
+
+reportResults
diff --git a/test/homebrew/scenarios.json b/test/homebrew/scenarios.json
index 5bf2a3a..29be34a 100644
--- a/test/homebrew/scenarios.json
+++ b/test/homebrew/scenarios.json
@@ -1,10 +1,9 @@
-[
-	{
-		"name": "Homebrew is installed if not present",
-		"steps": ["Install feature", "Check brew --version outputs 'Homebrew'"]
-	},
-	{
-		"name": "Homebrew is idempotent",
-		"steps": ["Install feature a second time", "Verify install.sh exits cleanly"]
+{
+	"remote_user_vscode": {
+		"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+		"features": {
+			"homebrew": {}
+		},
+		"remoteUser": "vscode"
 	}
-]
+}
diff --git a/test/homebrew/test.sh b/test/homebrew/test.sh
index 230dad1..ad085d8 100755
--- a/test/homebrew/test.sh
+++ b/test/homebrew/test.sh
@@ -1,26 +1,20 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'homebrew' feature as root (_REMOTE_USER=root). In that
+# case, install.sh creates a dedicated 'linuxbrew' account and installs
+# Homebrew under /home/linuxbrew/.linuxbrew.
+#
+# Run with:
+#   devcontainer features test -f homebrew --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test: Homebrew global feature
-# Homebrew refuses to run as root; verify via the install user
+set -e
 
-BREW_PREFIX="/home/linuxbrew/.linuxbrew"
+source dev-container-features-test-lib
 
-if [[ ! -x "$BREW_PREFIX/bin/brew" ]]; then
-  echo "[FAIL] brew binary not found at $BREW_PREFIX/bin/brew" >&2
-  exit 1
-fi
+BREW_BIN="/home/linuxbrew/.linuxbrew/bin/brew"
 
-# Mirror the install.sh user selection: prefer _REMOTE_USER when set and
-# non-root, otherwise fall back to the dedicated linuxbrew account.
-BREW_USER="${_REMOTE_USER:-}"
-if [[ -z "$BREW_USER" || "$BREW_USER" == "root" ]]; then
-  BREW_USER="linuxbrew"
-fi
+check "brew binary exists" test -x "$BREW_BIN"
+check "brew runs via linuxbrew user" bash -c "su - linuxbrew -s /bin/bash -c '/home/linuxbrew/.linuxbrew/bin/brew --version' | grep Homebrew"
 
-# Run brew as the install user (brew refuses to run as root)
-su - "$BREW_USER" -s /bin/bash -c "$BREW_PREFIX/bin/brew --version" \
-  | grep Homebrew \
-  || { echo "[FAIL] brew --version did not output expected Homebrew version string" >&2; exit 1; }
-
-echo "[PASS] Homebrew installed and working."
+reportResults
diff --git a/test/node/scenarios.json b/test/node/scenarios.json
index f60f1b3..0967ef4 100644
--- a/test/node/scenarios.json
+++ b/test/node/scenarios.json
@@ -1,16 +1 @@
-[
-	{
-		"name": "Default install",
-		"options": {},
-		"expect": {
-			"cli": "node --version | grep 24.11.0"
-		}
-	},
-	{
-		"name": "Install pinned version",
-		"options": { "nodeVersion": "24.11.0" },
-		"expect": {
-			"cli": "node --version | grep 24.11.0"
-		}
-	}
-]
+{}
diff --git a/test/node/test.sh b/test/node/test.sh
index 32aabb8..0deb5a0 100755
--- a/test/node/test.sh
+++ b/test/node/test.sh
@@ -1,32 +1,19 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'node' feature with default options (nodeVersion=24.11.0).
+#
+# Run with:
+#   devcontainer features test -f node --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test: Node.js global install
-if ! command -v node &>/dev/null; then
-  echo "[FAIL] node not found in PATH" >&2
-  exit 1
-fi
+set -e
 
-if ! command -v npm &>/dev/null; then
-  echo "[FAIL] npm not found in PATH" >&2
-  exit 1
-fi
+source dev-container-features-test-lib
 
-if ! command -v npx &>/dev/null; then
-  echo "[FAIL] npx not found in PATH" >&2
-  exit 1
-fi
+check "node is installed" node --version
+check "npm is installed" npm --version
+check "npx is installed" npx --version
+check "corepack is installed" corepack --version
+check "node default version is 24.11.0" bash -c "node -v | grep 'v24.11.0'"
 
-if ! command -v corepack &>/dev/null; then
-  echo "[FAIL] corepack not found in PATH" >&2
-  exit 1
-fi
-
-# Pinned default version from devcontainer-feature.json
-ACTUAL_VERSION="$(node -v)"
-if [[ "$ACTUAL_VERSION" != "v24.11.0" ]]; then
-  echo "[FAIL] Node.js version mismatch: expected v24.11.0, got $ACTUAL_VERSION" >&2
-  exit 1
-fi
-
-echo "[PASS] Node.js global install test passed."
+reportResults
diff --git a/test/package-manager/explicit_pnpm.sh b/test/package-manager/explicit_pnpm.sh
new file mode 100644
index 0000000..6a2688a
--- /dev/null
+++ b/test/package-manager/explicit_pnpm.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Scenario: install package-manager with an explicit pnpm version (pnpm@10.20.0).
+# node is installed first (declared in features) so corepack is available.
+
+set -e
+
+source dev-container-features-test-lib
+
+check "pnpm is installed" pnpm --version
+check "pnpm version is 10.20.0" bash -c "pnpm --version | grep '10.20.0'"
+
+reportResults
diff --git a/test/package-manager/explicit_yarn.sh b/test/package-manager/explicit_yarn.sh
new file mode 100644
index 0000000..e2d5e2e
--- /dev/null
+++ b/test/package-manager/explicit_yarn.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Scenario: install package-manager with an explicit yarn version (yarn@4.9.0).
+# node is installed first (declared in features) so corepack is available.
+
+set -e
+
+source dev-container-features-test-lib
+
+check "yarn is installed" yarn --version
+check "yarn version is 4.9.0" bash -c "yarn --version | grep '4.9.0'"
+
+reportResults
diff --git a/test/package-manager/scenarios.json b/test/package-manager/scenarios.json
index 6baf7e3..8762438 100644
--- a/test/package-manager/scenarios.json
+++ b/test/package-manager/scenarios.json
@@ -1,23 +1,20 @@
-[
-	{
-		"name": "Default auto-detect install",
-		"options": {},
-		"expect": {
-			"cli": "corepack --version"
+{
+	"explicit_pnpm": {
+		"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+		"features": {
+			"node": {},
+			"package-manager": {
+				"packageManager": "pnpm@10.20.0"
+			}
 		}
 	},
-	{
-		"name": "Explicit pnpm version",
-		"options": { "packageManager": "pnpm@10.20.0" },
-		"expect": {
-			"cli": "pnpm --version | grep 10.20.0"
-		}
-	},
-	{
-		"name": "Explicit yarn version",
-		"options": { "packageManager": "yarn@4.9.0" },
-		"expect": {
-			"cli": "yarn --version | grep 4.9.0"
+	"explicit_yarn": {
+		"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+		"features": {
+			"node": {},
+			"package-manager": {
+				"packageManager": "yarn@4.9.0"
+			}
 		}
 	}
-]
+}
diff --git a/test/package-manager/test.sh b/test/package-manager/test.sh
index 69116cb..0072e8e 100755
--- a/test/package-manager/test.sh
+++ b/test/package-manager/test.sh
@@ -1,16 +1,20 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'package-manager' feature with default options (packageManager=auto).
+#
+# NOTE: The auto-generated test is skipped for this feature in CI because
+# package-manager requires the 'node' feature to be installed first
+# (corepack is bundled with node). Use the scenarios in scenarios.json to
+# test the meaningful option variants, which wire in node explicitly.
+#
+# Run scenarios with:
+#   devcontainer features test -f package-manager --skip-autogenerated \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test: Package Manager (corepack) feature
+set -e
 
-if ! command -v corepack &>/dev/null; then
-  echo "[FAIL] corepack not found in PATH" >&2
-  exit 1
-fi
+source dev-container-features-test-lib
 
-# Default option is "auto" which may not resolve a spec in the test
-# environment (no package.json), so it only enables corepack shims.
-# Verify corepack itself is functional.
-corepack --version || { echo "[FAIL] corepack not functional" >&2; exit 1; }
+check "corepack is installed" corepack --version
 
-echo "[PASS] Package Manager (corepack) feature test passed."
+reportResults
diff --git a/test/rust/scenarios.json b/test/rust/scenarios.json
index dd0e40c..0967ef4 100644
--- a/test/rust/scenarios.json
+++ b/test/rust/scenarios.json
@@ -1,6 +1 @@
-[
-	{
-		"name": "Rust toolchain install",
-		"steps": ["Install feature", "Check rustc is available", "Check cargo is available"]
-	}
-]
+{}
diff --git a/test/rust/test.sh b/test/rust/test.sh
index 8c7f650..744f916 100755
--- a/test/rust/test.sh
+++ b/test/rust/test.sh
@@ -1,6 +1,20 @@
 #!/usr/bin/env bash
-set -euo pipefail
-# Test: Rust toolchain install
-rustc --version || { echo "[FAIL] rustc not found" >&2; exit 1; }
-cargo --version || { echo "[FAIL] cargo not found" >&2; exit 1; }
-echo "[PASS] Rust toolchain install test passed."
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'rust' feature with default options (toolchain=stable,
+# components=clippy rustfmt).
+#
+# Run with:
+#   devcontainer features test -f rust --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
+
+set -e
+
+source dev-container-features-test-lib
+
+check "rustc is installed" rustc --version
+check "cargo is installed" cargo --version
+check "rustup is installed" rustup --version
+check "clippy is available" cargo clippy --version
+check "rustfmt is available" rustfmt --version
+
+reportResults
diff --git a/test/zig/explicit_version.sh b/test/zig/explicit_version.sh
new file mode 100644
index 0000000..c37752b
--- /dev/null
+++ b/test/zig/explicit_version.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Scenario: install a non-default Zig version (zigVersion=0.13.0) and verify
+# the installed version matches the requested one.
+
+set -e
+
+source dev-container-features-test-lib
+
+check "zig is installed" zig version
+check "zig version is 0.13.0" bash -c "zig version | grep '0.13.0'"
+
+reportResults
diff --git a/test/zig/scenarios.json b/test/zig/scenarios.json
index aa57a9e..42de6fa 100644
--- a/test/zig/scenarios.json
+++ b/test/zig/scenarios.json
@@ -1,12 +1,10 @@
-[
-	{
-		"name": "Default install (0.12.0)",
-		"options": {},
-		"validate": ["zig version | grep 0.12.0"]
-	},
-	{
-		"name": "Install master build",
-		"options": { "zigVersion": "master" },
-		"validate": ["zig version"]
+{
+	"explicit_version": {
+		"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+		"features": {
+			"zig": {
+				"zigVersion": "0.13.0"
+			}
+		}
 	}
-]
+}
diff --git a/test/zig/test.sh b/test/zig/test.sh
index ec7b6a8..961eb2c 100755
--- a/test/zig/test.sh
+++ b/test/zig/test.sh
@@ -1,7 +1,16 @@
 #!/usr/bin/env bash
-set -euo pipefail
+# This test file is executed against an auto-generated devcontainer that
+# installs the 'zig' feature with default options (zigVersion=0.12.0).
+#
+# Run with:
+#   devcontainer features test -f zig --skip-scenarios \
+#     -i mcr.microsoft.com/devcontainers/base:ubuntu .
 
-# Test: Zig compiler install
-zig version | grep "0.12.0" || { echo "[FAIL] Zig version mismatch" >&2; exit 1; }
+set -e
 
-echo "[PASS] Zig install test passed."
+source dev-container-features-test-lib
+
+check "zig is installed" zig version
+check "zig default version is 0.12.0" bash -c "zig version | grep '0.12.0'"
+
+reportResults

From e592771c02610b054d1e814069efee63871290eb Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 20:19:47 +0000
Subject: [PATCH 05/18] chore: add .github/copilot-instructions.md with commit
 conventions

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/fc27ab37-26a0-46ab-960b-6762a2d3fbb7

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/copilot-instructions.md | 85 +++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..f5af1e4
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,85 @@
+# Copilot Instructions
+
+## Commit Conventions
+
+All commits in this repository are validated by `@savvy-web/commitlint` (Silk preset).
+
+### Format
+
+```text
+type(scope): subject
+
+Optional body — plain prose only, max 300 chars per line.
+
+Signed-off-by: Name <email@example.com>
+```
+
+### Allowed Types
+
+| Type | When to use |
+| :--- | :---------- |
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation-only change |
+| `style` | Formatting, whitespace — no logic change |
+| `refactor` | Code restructuring without behaviour change |
+| `perf` | Performance improvement |
+| `test` | Adding or updating tests |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD workflow changes |
+| `chore` | Maintenance tasks (version bumps, configs) |
+| `revert` | Reverts a previous commit |
+| `release` | Release preparation commit |
+| `ai` | AI-generated or AI-assisted change |
+
+### Rules
+
+- **Subject line**: imperative mood, no trailing period, max ~72 chars
+- **Body**: optional; plain prose only — no Markdown headers (`##`), no fenced
+  code blocks (` ``` `), no bare URLs, no numbered lists
+- **Body line length**: max 300 characters per line
+- **DCO sign-off**: required on every commit — a `Signed-off-by:` trailer must
+  be present because this repository has a `DCO` file and enforces the check in
+  CI via `dco.yml`
+
+### DCO Sign-Off
+
+The Developer Certificate of Origin (DCO) certifies that you have the right to
+submit your contribution. Add the trailer automatically with:
+
+```bash
+git commit -s -m "feat(biome): bump default version to 2.5.0"
+```
+
+Or configure git to add it by default:
+
+```bash
+git config --global trailer.sign.key "Signed-off-by"
+git config --global trailer.sign.ifmissing add
+git config --global trailer.sign.ifexists doNothing
+git config --global trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"'
+```
+
+### Examples
+
+```text
+feat(biome): bump default version to 2.5.0
+
+Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>
+```
+
+```text
+fix(package-manager): handle missing packageManager field in package.json
+
+When no packageManager field is present and the option is set to 'auto',
+the install script now exits cleanly instead of forwarding an empty spec
+to corepack.
+
+Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>
+```
+
+```text
+ci: switch feature tests to devcontainer features test CLI
+
+Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>
+```

From 3be3543e521dc0efd1022f027d49c9b52ac5fc71 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 20:35:22 +0000
Subject: [PATCH 06/18] =?UTF-8?q?fix:=20address=20review=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20zig=20env=20var,=20homebrew=20user=20guard,=20scena?=
 =?UTF-8?q?rio=20null=20check,=20CI=20failure=20detection?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The devcontainer CLI injects zigVersion as ZIGVERSION (no separator).
Read ZIGVERSION first with ZIG_VERSION as a fallback.

Guard _REMOTE_USER in homebrew install with id -u existence check
before assigning as BREW_USER; fall back to linuxbrew user with
a warning if the account is absent from the image.

Tighten scenarios.json structural check in validate-feature.sh to
reject null, numbers, and strings in addition to arrays.

Detect per-scenario failures in test.yml and publish.yml by grepping
the captured devcontainer features test output for the ❌ Failed:
marker emitted in the TEST REPORT, since the CLI exits 0 even when
individual scenarios fail.

Signed-off-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/45c46e47-d95b-4aac-a3c2-9555f010454b

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/workflows/publish.yml | 5 +++++
 .github/workflows/test.yml    | 5 +++++
 scripts/validate-feature.sh   | 4 ++--
 src/homebrew/install.sh       | 5 ++++-
 src/zig/install.sh            | 4 +++-
 5 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 6a28277..b0a8eae 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -65,6 +65,11 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          # devcontainer features test exits 0 even when individual scenarios
+          # fail. Detect scenario failures from the TEST REPORT in the output.
+          if grep -qF "❌ Failed:" /tmp/test.log 2>/dev/null; then
+            exit 1
+          fi
       - name: Save result
         if: always()
         run: |
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c23ef67..e4f802f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -80,6 +80,11 @@ jobs:
           echo "::group::devcontainer features test ${ARGS[*]} ."
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
           echo "::endgroup::"
+          # devcontainer features test exits 0 even when individual scenarios
+          # fail. Detect scenario failures from the TEST REPORT in the output.
+          if grep -qF "❌ Failed:" /tmp/test.log 2>/dev/null; then
+            exit 1
+          fi
 
       - name: Write step summary
         if: always()
diff --git a/scripts/validate-feature.sh b/scripts/validate-feature.sh
index 9b5f1e6..e264b64 100755
--- a/scripts/validate-feature.sh
+++ b/scripts/validate-feature.sh
@@ -217,11 +217,11 @@ fi
 if [[ -f "$SCENARIOS_FILE" ]]; then
   if node -e "
     const j = JSON.parse(require('fs').readFileSync('${SCENARIOS_FILE}', 'utf8'));
-    if (Array.isArray(j)) process.exit(1);
+    if (!j || typeof j !== 'object' || Array.isArray(j)) process.exit(1);
   " 2>/dev/null; then
     pass "scenarios.json is a valid object"
   else
-    fail "scenarios.json must be a JSON object (not an array) — keys are scenario names"
+    fail "scenarios.json must be a JSON object (not an array or primitive) — keys are scenario names"
   fi
 
   # Verify each scenario key has a matching .sh assertion script
diff --git a/src/homebrew/install.sh b/src/homebrew/install.sh
index 2cd235d..acdf38d 100755
--- a/src/homebrew/install.sh
+++ b/src/homebrew/install.sh
@@ -37,9 +37,12 @@ else
   # so the devcontainer user owns the Homebrew prefix and can run
   # `brew install` directly without switching users.
   REMOTE_USER="${_REMOTE_USER:-}"
-  if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]]; then
+  if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]] && id -u "$REMOTE_USER" >/dev/null 2>&1; then
     BREW_USER="$REMOTE_USER"
   else
+    if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]]; then
+      echo "[INFO] Remote user '${REMOTE_USER}' does not exist in the image; falling back to linuxbrew user." >&2
+    fi
     BREW_USER="linuxbrew"
     useradd -m -s /bin/bash "$BREW_USER" 2>/dev/null || true
   fi
diff --git a/src/zig/install.sh b/src/zig/install.sh
index bee5a09..ad2ab7a 100755
--- a/src/zig/install.sh
+++ b/src/zig/install.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ZIG_VERSION=${ZIG_VERSION:-0.12.0}
+# The devcontainer CLI injects feature options uppercased with no separator
+# (e.g. zigVersion -> ZIGVERSION). Accept both forms for flexibility.
+ZIG_VERSION="${ZIGVERSION:-${ZIG_VERSION:-0.12.0}}"
 ZIG_ROOT="/usr/local/zig"
 ZIG_BIN="$ZIG_ROOT/zig"
 

From 58c0ca8f8e183c8a193525948069ad6827b3a40a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 20:36:04 +0000
Subject: [PATCH 07/18] fix(homebrew): send [INFO] fallback message to stdout
 not stderr

Signed-off-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/45c46e47-d95b-4aac-a3c2-9555f010454b

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 src/homebrew/install.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/homebrew/install.sh b/src/homebrew/install.sh
index acdf38d..7ba3585 100755
--- a/src/homebrew/install.sh
+++ b/src/homebrew/install.sh
@@ -41,7 +41,7 @@ else
     BREW_USER="$REMOTE_USER"
   else
     if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]]; then
-      echo "[INFO] Remote user '${REMOTE_USER}' does not exist in the image; falling back to linuxbrew user." >&2
+      echo "[INFO] Remote user '${REMOTE_USER}' does not exist in the image; falling back to linuxbrew user."
     fi
     BREW_USER="linuxbrew"
     useradd -m -s /bin/bash "$BREW_USER" 2>/dev/null || true

From f116aa37bb84bda27291769b5667289f211e4bfd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 20:57:24 +0000
Subject: [PATCH 08/18] feat: extract test-result parsing to scripts,
 JSON-based failure detection, fix review issues

Add .github/scripts/parse-test-results.js (ESM) to parse the devcontainer
features test TEST REPORT into { passed, failed, total, allPassed } JSON.
Add .github/scripts/discover-features.js (ESM) to build the test matrix,
replacing a 25-line inline node block in test.yml.

All three workflow test steps and scripts/test-feature.sh now call the
script directly instead of embedding inline node -e parse logic. Simple
one-liner require() checks in node -e remain unchanged (node -e always
runs in CJS mode regardless of package.json type field).

Also applies review fixes:
- validate-feature.sh: tighten set -e check to reject set -euo pipefail;
  fix regex to not require trailing whitespace after pipefail; tighten
  scenarios.json structural check to reject null/primitive values
- test-feature.yml: add scenario failure detection via parse-test-results.js
- scripts/test-feature.sh: capture output, parse JSON results, propagate
  failures; fix fallback JSON to include total field
- publish.yml: fix fallback JSON in Save result step to include total field;
  expand summarize table to show per-scenario rows from results JSON
- src/zig/install.sh: read ZIGVERSION (CLI-injected) with ZIG_VERSION fallback
- src/homebrew/install.sh: guard _REMOTE_USER with id -u existence check

Signed-off-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/5f032a45-357b-4921-89c6-104e4436b192

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/scripts/discover-features.js  | 31 +++++++++++++++++
 .github/scripts/parse-test-results.js | 38 +++++++++++++++++++++
 .github/workflows/publish.yml         | 38 +++++++++++++++------
 .github/workflows/test-feature.yml    |  7 +++-
 .github/workflows/test.yml            | 48 ++++++++++-----------------
 scripts/test-feature.sh               | 30 ++++++++++++++++-
 scripts/validate-feature.sh           |  4 ++-
 7 files changed, 152 insertions(+), 44 deletions(-)
 create mode 100644 .github/scripts/discover-features.js
 create mode 100644 .github/scripts/parse-test-results.js

diff --git a/.github/scripts/discover-features.js b/.github/scripts/discover-features.js
new file mode 100644
index 0000000..60627a3
--- /dev/null
+++ b/.github/scripts/discover-features.js
@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Outputs a JSON matrix of { id, skipAutogenerated } entries for every
+// feature that has both a devcontainer-feature.json and a test/test.sh file.
+// Used by the "Discover features" step in test.yml.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const srcRoot = resolve("src");
+const testRoot = resolve("test");
+
+if (!existsSync(srcRoot)) {
+	process.stdout.write("[]");
+	process.exit(0);
+}
+
+const entries = readdirSync(srcRoot)
+	.filter((f) => {
+		const featureJson = join(srcRoot, f, "devcontainer-feature.json");
+		const testSh = join(testRoot, f, "test.sh");
+		return existsSync(featureJson) && existsSync(testSh);
+	})
+	.map((id) => {
+		const featureJson = JSON.parse(readFileSync(join(srcRoot, id, "devcontainer-feature.json"), "utf8"));
+		const installsAfter = featureJson.installsAfter || [];
+		// Skip auto-generated test for features that depend on another local
+		// savvy-web feature (e.g. package-manager requires node).
+		const skipAutogenerated = installsAfter.some((dep) => dep.includes("ghcr.io/savvy-web/"));
+		return { id, skipAutogenerated };
+	});
+
+process.stdout.write(JSON.stringify(entries));
diff --git a/.github/scripts/parse-test-results.js b/.github/scripts/parse-test-results.js
new file mode 100644
index 0000000..eb17ee1
--- /dev/null
+++ b/.github/scripts/parse-test-results.js
@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Parses the TEST REPORT section emitted by `devcontainer features test` and
+// writes a structured JSON results file.
+//
+// Usage:
+//   node parse-test-results.js [logPath] [outPath]
+//
+// Defaults:
+//   logPath  /tmp/test.log
+//   outPath  /tmp/test-results.json
+//
+// Output shape:
+//   { passed: string[], failed: string[], total: number, allPassed: boolean }
+import { readFileSync, writeFileSync } from "node:fs";
+
+const logPath = process.argv[2] ?? "/tmp/test.log";
+const outPath = process.argv[3] ?? "/tmp/test-results.json";
+
+let log = "";
+try {
+	log = readFileSync(logPath, "utf8");
+} catch {
+	// log file not yet written; treat as empty
+}
+
+const idx = log.indexOf("TEST REPORT");
+const section = idx >= 0 ? log.slice(idx) : log;
+const passed = [...section.matchAll(/Passed:\s+'([^']+)'/g)].map((m) => m[1]);
+const failed = [...section.matchAll(/Failed:\s+'([^']+)'/g)].map((m) => m[1]);
+
+const result = {
+	passed,
+	failed,
+	total: passed.length + failed.length,
+	allPassed: failed.length === 0,
+};
+
+writeFileSync(outPath, JSON.stringify(result, null, 2));
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index b0a8eae..06d73a7 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -65,16 +65,17 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
-          # devcontainer features test exits 0 even when individual scenarios
-          # fail. Detect scenario failures from the TEST REPORT in the output.
-          if grep -qF "❌ Failed:" /tmp/test.log 2>/dev/null; then
-            exit 1
-          fi
+          # Parse the TEST REPORT section into a structured JSON results file so
+          # that failure detection does not rely on grepping for emoji characters.
+          node .github/scripts/parse-test-results.js
+          # Exit non-zero if any scenario failed.
+          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
       - name: Save result
         if: always()
         run: |
           mkdir -p /tmp/results
           echo "${{ steps.test.outcome }}" > /tmp/results/${{ matrix.id }}.txt
+          cp /tmp/test-results.json /tmp/results/${{ matrix.id }}-results.json 2>/dev/null || echo '{"passed":[],"failed":[],"total":0,"allPassed":false}' > /tmp/results/${{ matrix.id }}-results.json
           cp /tmp/test.log /tmp/results/${{ matrix.id }}-test.log 2>/dev/null || echo "No test log" > /tmp/results/${{ matrix.id }}-test.log
       - name: Upload result
         if: always()
@@ -115,15 +116,32 @@ jobs:
               echo "⚠️ No test results found — all test jobs may have been cancelled."
               all_passed=false
             else
-              echo "| Feature | Result |"
-              echo "| ------- | ------ |"
+              echo "| Feature | Scenario | Result |"
+              echo "| ------- | -------- | ------ |"
               for file in "${result_files[@]}"; do
                 name=$(basename "$file" .txt)
                 result=$(cat "$file")
-                if [ "$result" = "success" ]; then
-                  echo "| \`$name\` | ✅ Pass |"
+                results_json="/tmp/results/${name}-results.json"
+                if node -e "
+                  try {
+                    const r = JSON.parse(require('fs').readFileSync('$results_json', 'utf8'));
+                    if (r.total > 0) {
+                      for (const s of r.passed) process.stdout.write('| \`' + '$name' + '\` | ' + s + ' | ✅ Pass |\n');
+                      for (const s of r.failed) process.stdout.write('| \`' + '$name' + '\` | ' + s + ' | ❌ Fail |\n');
+                      process.exit(0);
+                    }
+                  } catch {}
+                  process.exit(1);
+                " 2>/dev/null; then
+                  :
                 else
-                  echo "| \`$name\` | ❌ Fail |"
+                  if [ "$result" = "success" ]; then
+                    echo "| \`$name\` | — | ✅ Pass |"
+                  else
+                    echo "| \`$name\` | — | ❌ Fail |"
+                  fi
+                fi
+                if [ "$result" != "success" ]; then
                   all_passed=false
                 fi
               done
diff --git a/.github/workflows/test-feature.yml b/.github/workflows/test-feature.yml
index da994e1..07d87a5 100644
--- a/.github/workflows/test-feature.yml
+++ b/.github/workflows/test-feature.yml
@@ -44,4 +44,9 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
 
-          devcontainer features test "${ARGS[@]}" .
+          devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          # Parse the TEST REPORT section into a structured JSON results file so
+          # that failure detection does not rely on grepping for emoji characters.
+          node .github/scripts/parse-test-results.js
+          # Exit non-zero if any scenario failed.
+          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index e4f802f..2f1dbe1 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -19,32 +19,7 @@ jobs:
       - name: Discover features
         id: features
         run: |
-          matrix=$(node -e "
-            const fs = require('fs');
-            const path = require('path');
-            const srcRoot = path.resolve('src');
-            const testRoot = path.resolve('test');
-            if (!fs.existsSync(srcRoot)) { process.stdout.write('[]'); process.exit(0); }
-            const entries = fs.readdirSync(srcRoot)
-              .filter(f => {
-                const featureJson = path.join(srcRoot, f, 'devcontainer-feature.json');
-                const testSh = path.join(testRoot, f, 'test.sh');
-                return fs.existsSync(featureJson) && fs.existsSync(testSh);
-              })
-              .map(id => {
-                const featureJson = JSON.parse(
-                  fs.readFileSync(path.join(srcRoot, id, 'devcontainer-feature.json'), 'utf8')
-                );
-                const installsAfter = featureJson.installsAfter || [];
-                // Skip auto-generated test for features that depend on another
-                // local savvy-web feature (e.g. package-manager requires node).
-                const skipAutogenerated = installsAfter.some(dep =>
-                  dep.includes('ghcr.io/savvy-web/')
-                );
-                return { id, skipAutogenerated };
-              });
-            process.stdout.write(JSON.stringify(entries));
-          ")
+          matrix=$(node .github/scripts/discover-features.js)
           echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
 
   test:
@@ -80,11 +55,11 @@ jobs:
           echo "::group::devcontainer features test ${ARGS[*]} ."
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
           echo "::endgroup::"
-          # devcontainer features test exits 0 even when individual scenarios
-          # fail. Detect scenario failures from the TEST REPORT in the output.
-          if grep -qF "❌ Failed:" /tmp/test.log 2>/dev/null; then
-            exit 1
-          fi
+          # Parse the TEST REPORT section into a structured JSON results file so
+          # that failure detection does not rely on grepping for emoji characters.
+          node .github/scripts/parse-test-results.js
+          # Exit non-zero if any scenario failed.
+          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
 
       - name: Write step summary
         if: always()
@@ -96,6 +71,17 @@ jobs:
               echo "## ❌ ${{ matrix.id }}"
             fi
             echo ""
+            node -e "
+              try {
+                const r = JSON.parse(require('fs').readFileSync('/tmp/test-results.json', 'utf8'));
+                if (r.total > 0) {
+                  process.stdout.write('| Scenario | Result |\n| --- | --- |\n');
+                  for (const s of r.passed) process.stdout.write('| ' + s + ' | ✅ Pass |\n');
+                  for (const s of r.failed) process.stdout.write('| ' + s + ' | ❌ Fail |\n');
+                  process.stdout.write('\n');
+                }
+              } catch {}
+            " 2>/dev/null
             echo "<details><summary>Test log</summary>"
             echo ""
             echo '```'
diff --git a/scripts/test-feature.sh b/scripts/test-feature.sh
index 6425e07..e24233a 100755
--- a/scripts/test-feature.sh
+++ b/scripts/test-feature.sh
@@ -73,4 +73,32 @@ echo "[INFO] Testing feature: ${ID}"
 echo ""
 
 cd "${REPO_ROOT}"
-devcontainer features test "${ARGS[@]}" .
+TEST_LOG=$(mktemp)
+RESULTS_JSON=$(mktemp)
+trap 'rm -f "$TEST_LOG" "$RESULTS_JSON"' EXIT
+
+set +e
+devcontainer features test "${ARGS[@]}" . 2>&1 | tee "$TEST_LOG"
+CLI_EXIT=${PIPESTATUS[0]}
+set -e
+
+# Parse the TEST REPORT section into a structured JSON results file so that
+# failure detection does not rely on grepping for emoji characters.
+node "${REPO_ROOT}/.github/scripts/parse-test-results.js" "$TEST_LOG" "$RESULTS_JSON" \
+  2>/dev/null || echo '{"passed":[],"failed":[],"total":0,"allPassed":false}' > "$RESULTS_JSON"
+
+if [[ "$CLI_EXIT" -ne 0 ]]; then
+  exit "$CLI_EXIT"
+fi
+
+ALL_PASSED=$(node -e "
+  try {
+    const r = JSON.parse(require('fs').readFileSync('$RESULTS_JSON', 'utf8'));
+    process.stdout.write(String(r.allPassed));
+  } catch (e) { process.stdout.write('false'); }
+" 2>/dev/null || echo "false")
+
+if [[ "$ALL_PASSED" != "true" ]]; then
+  echo "[ERROR] devcontainer features test reported one or more failed scenarios." >&2
+  exit 1
+fi
diff --git a/scripts/validate-feature.sh b/scripts/validate-feature.sh
index e264b64..b06fcad 100755
--- a/scripts/validate-feature.sh
+++ b/scripts/validate-feature.sh
@@ -193,7 +193,9 @@ if [[ -f "$TEST_SH" ]]; then
     fail "test.sh first line must be '#!/usr/bin/env bash', got: ${FIRST_LINE}"
   fi
 
-  if grep -q "set -e" "$TEST_SH"; then
+  if grep -Eq '^[[:space:]]*set[[:space:]]+-euo[[:space:]]+pipefail' "$TEST_SH"; then
+    fail "test.sh must use 'set -e' specifically; found 'set -euo pipefail' which enables '-u' (the test lib uses unset variables internally)"
+  elif grep -Eq '^[[:space:]]*set[[:space:]]+-e[[:space:]]*$' "$TEST_SH"; then
     pass "test.sh has 'set -e'"
   else
     fail "test.sh is missing 'set -e'"

From bc764c4310eeb8c2398c784ec22a8571a26e5065 Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 17:11:49 -0400
Subject: [PATCH 09/18] fix: biome test

Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>
---
 src/biome/install.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/biome/install.sh b/src/biome/install.sh
index 01f4477..4195d04 100755
--- a/src/biome/install.sh
+++ b/src/biome/install.sh
@@ -4,7 +4,7 @@ set -euo pipefail
 # Biome global installer (official binary method)
 # Docs: https://biomejs.dev/guides/manual-installation/
 
-VERSION="${BIOME_VERSION:-2.4.13}"
+VERSION="${BIOMEVERSION:-2.4.13}"
 BIOME_BIN="/usr/local/bin/biome"
 
 if [[ "$VERSION" == "latest" ]]; then

From 60a4bdfa36f74b82e168aefeb0589bc19a5a13b2 Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 17:23:26 -0400
Subject: [PATCH 10/18] fix: update src/biome/install.sh

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: C. Spencer Beggs <spencer@beg.gs>
---
 src/biome/install.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/biome/install.sh b/src/biome/install.sh
index 4195d04..634f867 100755
--- a/src/biome/install.sh
+++ b/src/biome/install.sh
@@ -4,7 +4,7 @@ set -euo pipefail
 # Biome global installer (official binary method)
 # Docs: https://biomejs.dev/guides/manual-installation/
 
-VERSION="${BIOMEVERSION:-2.4.13}"
+VERSION="${BIOMEVERSION:-${BIOME_VERSION:-2.4.13}}"
 BIOME_BIN="/usr/local/bin/biome"
 
 if [[ "$VERSION" == "latest" ]]; then

From c0097a50dbbc3455f27e899941c71be8f4eb85d8 Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 17:23:46 -0400
Subject: [PATCH 11/18] fix: update .github/workflows/publish.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: C. Spencer Beggs <spencer@beg.gs>
---
 .github/workflows/publish.yml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 06d73a7..9a4ac3a 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -64,12 +64,15 @@ jobs:
           if [[ "$SKIP_AUTOGENERATED" == "true" ]]; then
             ARGS+=(--skip-autogenerated)
           fi
+          set +e
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          test_exit_code=$?
+          set -e
           # Parse the TEST REPORT section into a structured JSON results file so
           # that failure detection does not rely on grepping for emoji characters.
           node .github/scripts/parse-test-results.js
-          # Exit non-zero if any scenario failed.
-          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
+          # Exit non-zero if the CLI failed or any scenario failed.
+          node -e "const fs = require('fs'); const cliExit = Number(process.argv[1]); const results = JSON.parse(fs.readFileSync('/tmp/test-results.json','utf8')); process.exit(cliExit !== 0 || !results.allPassed ? 1 : 0)" "$test_exit_code"
       - name: Save result
         if: always()
         run: |

From cd9a67bd3d9b0c94538c7773d2eb85f02af6c424 Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 17:26:04 -0400
Subject: [PATCH 12/18] fix: update .github/workflows/test.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: C. Spencer Beggs <spencer@beg.gs>
---
 .github/workflows/test.yml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 2f1dbe1..f5b9c38 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -53,13 +53,16 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
           echo "::group::devcontainer features test ${ARGS[*]} ."
+          set +e
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          test_exit_code=${PIPESTATUS[0]}
+          set -e
           echo "::endgroup::"
           # Parse the TEST REPORT section into a structured JSON results file so
           # that failure detection does not rely on grepping for emoji characters.
           node .github/scripts/parse-test-results.js
-          # Exit non-zero if any scenario failed.
-          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
+          # Exit non-zero if the CLI failed or any scenario failed.
+          node -e "const results = JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')); process.exit((${test_exit_code} === 0 && results.allPassed) ? 0 : 1)"
 
       - name: Write step summary
         if: always()

From bbd702c7973a58d1a9e9d1fad64c94604db41b93 Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 17:28:06 -0400
Subject: [PATCH 13/18] fix: update .github/workflows/test-feature.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: C. Spencer Beggs <spencer@beg.gs>
---
 .github/workflows/test-feature.yml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test-feature.yml b/.github/workflows/test-feature.yml
index 07d87a5..1a17328 100644
--- a/.github/workflows/test-feature.yml
+++ b/.github/workflows/test-feature.yml
@@ -44,9 +44,13 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
 
+          set +e
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          TEST_EXIT_CODE=${PIPESTATUS[0]}
+          set -e
+
           # Parse the TEST REPORT section into a structured JSON results file so
           # that failure detection does not rely on grepping for emoji characters.
           node .github/scripts/parse-test-results.js
-          # Exit non-zero if any scenario failed.
-          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
+          # Exit non-zero if the CLI failed or any scenario failed.
+          node -e "const fs = require('fs'); const results = JSON.parse(fs.readFileSync('/tmp/test-results.json','utf8')); process.exit((${TEST_EXIT_CODE} === 0 && results.allPassed) ? 0 : 1)"

From 5d351667acb63e1b256f4fea94bd1261df3715d2 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 21:28:47 +0000
Subject: [PATCH 14/18] fix: set +e in test-feature.yml; treat missing TEST
 REPORT as failure

test-feature.yml: wrap the devcontainer CLI invocation with set +e /
set -e and capture PIPESTATUS so parse-test-results.js always runs even
when the CLI exits non-zero. The final exit is based on both the CLI
exit code and results.allPassed.

parse-test-results.js: when no TEST REPORT section is found in the log
(CLI crash, output format change) set allPassed to false instead of
silently returning an empty-but-passing result set.

Signed-off-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/b087a77e-2fc9-40e9-aa13-edf76ede352b

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 .github/scripts/parse-test-results.js | 7 +++++--
 .github/workflows/test-feature.yml    | 8 ++++++--
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/.github/scripts/parse-test-results.js b/.github/scripts/parse-test-results.js
index eb17ee1..48ab7d3 100644
--- a/.github/scripts/parse-test-results.js
+++ b/.github/scripts/parse-test-results.js
@@ -24,7 +24,10 @@ try {
 }
 
 const idx = log.indexOf("TEST REPORT");
-const section = idx >= 0 ? log.slice(idx) : log;
+// If the CLI crashed or changed output format, treat as a parse failure
+// rather than silently succeeding with an empty result set.
+const reportFound = idx >= 0;
+const section = reportFound ? log.slice(idx) : "";
 const passed = [...section.matchAll(/Passed:\s+'([^']+)'/g)].map((m) => m[1]);
 const failed = [...section.matchAll(/Failed:\s+'([^']+)'/g)].map((m) => m[1]);
 
@@ -32,7 +35,7 @@ const result = {
 	passed,
 	failed,
 	total: passed.length + failed.length,
-	allPassed: failed.length === 0,
+	allPassed: reportFound && failed.length === 0,
 };
 
 writeFileSync(outPath, JSON.stringify(result, null, 2));
diff --git a/.github/workflows/test-feature.yml b/.github/workflows/test-feature.yml
index 07d87a5..4077acc 100644
--- a/.github/workflows/test-feature.yml
+++ b/.github/workflows/test-feature.yml
@@ -44,9 +44,13 @@ jobs:
             ARGS+=(--skip-autogenerated)
           fi
 
+          set +e
           devcontainer features test "${ARGS[@]}" . 2>&1 | tee /tmp/test.log
+          TEST_EXIT_CODE=${PIPESTATUS[0]}
+          set -e
+
           # Parse the TEST REPORT section into a structured JSON results file so
           # that failure detection does not rely on grepping for emoji characters.
           node .github/scripts/parse-test-results.js
-          # Exit non-zero if any scenario failed.
-          node -e "process.exit(JSON.parse(require('fs').readFileSync('/tmp/test-results.json','utf8')).allPassed ? 0 : 1)"
+          # Exit non-zero if the CLI failed or any scenario failed.
+          node -e "const fs = require('fs'); const cliExit = Number(process.argv[1]); const results = JSON.parse(fs.readFileSync('/tmp/test-results.json','utf8')); process.exit(cliExit !== 0 || !results.allPassed ? 1 : 0)" "$TEST_EXIT_CODE"

From 9cf8e07004ff6859edb60a0e8353e65a7728c413 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 21:44:24 +0000
Subject: [PATCH 15/18] fix(claude-code): switch to native curl installer; fix
 homebrew autogen test

claude-code: Replace deprecated npm install with official native installer
(curl -fsSL https://claude.ai/install.sh | bash). Node.js/npm is no longer
required. The version option is removed since the native installer always
installs the latest release. The entrypoint field format is corrected from
the non-standard install.shell to entrypoint. Version bumped 0.1.0 -> 0.2.0.

homebrew: The autogenerated test assumed _REMOTE_USER=root and checked for a
linuxbrew user via su. The base image (mcr.microsoft.com/devcontainers/base:ubuntu)
always sets _REMOTE_USER=vscode, so the linuxbrew user is never created and
su - linuxbrew fails. Updated test.sh to use the full binary path directly,
matching the pattern already used in remote_user_vscode.sh.

Signed-off-by: Copilot <copilot@github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/b1a37736-11b0-45bc-819f-cee3aa03e0a9

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 docs/features/claude-code.md              | 18 ++++++++---
 src/claude-code/devcontainer-feature.json | 15 ++-------
 src/claude-code/install.sh                | 37 +++++++++++++++--------
 test/homebrew/test.sh                     | 12 +++++---
 4 files changed, 47 insertions(+), 35 deletions(-)

diff --git a/docs/features/claude-code.md b/docs/features/claude-code.md
index 3b766be..81f562c 100644
--- a/docs/features/claude-code.md
+++ b/docs/features/claude-code.md
@@ -1,11 +1,19 @@
 # Claude Code Agent (Global)
 
-Installs the Claude Code CLI agent globally using the official native installer.
+Installs the Claude Code CLI agent globally using the official native installer
+(`curl -fsSL https://claude.ai/install.sh | bash`). Does not require Node.js or
+npm — the pre-built binary is downloaded and placed on `PATH` for all users.
 
-## Options
+## Usage
 
-- `version`: Claude Code CLI version (use 'latest' for the newest release). Default: `latest`
+Add this feature to your `devcontainer.json`:
 
-## Usage
+```json
+{
+  "features": {
+    "ghcr.io/savvy-web/claude-code:0": {}
+  }
+}
+```
 
-Add this feature to your `devcontainer.json` to install the Claude Code agent globally.
+After the container starts, run `claude` to launch the agent.
diff --git a/src/claude-code/devcontainer-feature.json b/src/claude-code/devcontainer-feature.json
index 663334b..3e9caf7 100644
--- a/src/claude-code/devcontainer-feature.json
+++ b/src/claude-code/devcontainer-feature.json
@@ -1,20 +1,11 @@
 {
 	"id": "claude-code",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"name": "Claude Code Agent",
-	"description": "Installs the Claude Code CLI agent globally via the official npm package (@anthropic-ai/claude-code).",
+	"description": "Installs the Claude Code CLI agent globally via the official native installer (curl | bash). Does not require Node.js or npm.",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/claude-code.md",
-	"options": {
-		"version": {
-			"type": "string",
-			"default": "latest",
-			"description": "Claude Code CLI version (use 'latest' for the newest release)"
-		}
-	},
 	"installsAfter": [],
-	"install": {
-		"shell": "./install.sh"
-	},
+	"entrypoint": "/install.sh",
 	"platforms": ["linux", "darwin"],
 	"keywords": ["claude", "ai", "agent", "global"]
 }
diff --git a/src/claude-code/install.sh b/src/claude-code/install.sh
index ceeb8b0..40fcdf0 100755
--- a/src/claude-code/install.sh
+++ b/src/claude-code/install.sh
@@ -1,28 +1,39 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Claude Code CLI global installer (official npm package)
-# Docs: https://docs.anthropic.com/en/docs/claude-code/getting-started
+# Claude Code CLI — native installer
+# Docs: https://code.claude.com/docs/en/setup
+#
+# Installation via @anthropic-ai/claude-code on npm is deprecated.
+# This feature uses the official curl | bash installer instead.
 
-VERSION="${VERSION:-latest}"
-
-if ! command -v npm &>/dev/null; then
-  echo "[ERROR] npm is required but not found in PATH. Install Node.js before using this feature." >&2
-  exit 1
+if command -v claude &>/dev/null; then
+  echo "[INFO] Claude Code CLI already installed: $(claude --version)"
+  exit 0
 fi
 
-if [[ "$VERSION" == "latest" ]]; then
-  npm install -g @anthropic-ai/claude-code
-else
-  npm install -g "@anthropic-ai/claude-code@${VERSION}"
+echo "[INFO] Installing Claude Code CLI via native installer..."
+curl -fsSL https://claude.ai/install.sh | bash
+
+# The native installer may place the binary outside the calling shell's PATH
+# (e.g. ~/.local/bin). Search known locations and symlink into /usr/local/bin
+# when necessary so claude is available to all users.
+if ! command -v claude &>/dev/null; then
+  for candidate in \
+    "/root/.local/bin/claude" \
+    "/root/.anthropic/bin/claude" \
+    "/usr/local/bin/claude"; do
+    if [[ -x "$candidate" ]]; then
+      ln -sf "$candidate" /usr/local/bin/claude
+      break
+    fi
+  done
 fi
 
-# Validate install
 if ! command -v claude &>/dev/null; then
   echo "[ERROR] Claude Code CLI not found in PATH after install." >&2
   exit 1
 fi
 
-# Print version
 claude --version
 echo "[SUCCESS] Claude Code CLI installed."
diff --git a/test/homebrew/test.sh b/test/homebrew/test.sh
index ad085d8..97471be 100755
--- a/test/homebrew/test.sh
+++ b/test/homebrew/test.sh
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
-# This test file is executed against an auto-generated devcontainer that
-# installs the 'homebrew' feature as root (_REMOTE_USER=root). In that
-# case, install.sh creates a dedicated 'linuxbrew' account and installs
-# Homebrew under /home/linuxbrew/.linuxbrew.
+# Auto-generated scenario test for the 'homebrew' feature.
+# The base image (mcr.microsoft.com/devcontainers/base:ubuntu) sets
+# _REMOTE_USER=vscode, so install.sh runs the Homebrew installer as the
+# vscode user. Homebrew is always installed to /home/linuxbrew/.linuxbrew
+# on Linux regardless of which user runs the installer.
 #
 # Run with:
 #   devcontainer features test -f homebrew --skip-scenarios \
@@ -15,6 +16,7 @@ source dev-container-features-test-lib
 BREW_BIN="/home/linuxbrew/.linuxbrew/bin/brew"
 
 check "brew binary exists" test -x "$BREW_BIN"
-check "brew runs via linuxbrew user" bash -c "su - linuxbrew -s /bin/bash -c '/home/linuxbrew/.linuxbrew/bin/brew --version' | grep Homebrew"
+check "brew is functional" "$BREW_BIN" --version
+check "brew version output includes Homebrew" bash -c "$BREW_BIN --version | grep Homebrew"
 
 reportResults

From 4343930c7e7a22008ae0b32963898a44ae002518 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 21:45:32 +0000
Subject: [PATCH 16/18] fix(claude-code): use $HOME instead of hardcoded /root
 in path fallback

Signed-off-by: Copilot <copilot@github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/b1a37736-11b0-45bc-819f-cee3aa03e0a9

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 src/claude-code/install.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/claude-code/install.sh b/src/claude-code/install.sh
index 40fcdf0..40ec06f 100755
--- a/src/claude-code/install.sh
+++ b/src/claude-code/install.sh
@@ -20,8 +20,8 @@ curl -fsSL https://claude.ai/install.sh | bash
 # when necessary so claude is available to all users.
 if ! command -v claude &>/dev/null; then
   for candidate in \
-    "/root/.local/bin/claude" \
-    "/root/.anthropic/bin/claude" \
+    "${HOME}/.local/bin/claude" \
+    "${HOME}/.anthropic/bin/claude" \
     "/usr/local/bin/claude"; do
     if [[ -x "$candidate" ]]; then
       ln -sf "$candidate" /usr/local/bin/claude

From d08f8d37135a192342fb5d84227eb98d92b5c3bd Mon Sep 17 00:00:00 2001
From: "C. Spencer Beggs" <spencer@savvyweb.systems>
Date: Fri, 1 May 2026 18:17:26 -0400
Subject: [PATCH 17/18] chore: refactor repo structure

Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>
---
 .github/skills/debug-feature/SKILL.md               |  4 ++--
 .../references/common-failure-modes.md              |  2 +-
 .../skills/devcontainer/references/test-patterns.md |  4 ++--
 .github/skills/new-feature/SKILL.md                 |  2 +-
 .github/workflows/copilot-setup-steps.yml           |  6 +++---
 CLAUDE.md                                           | 12 ++++++------
 CONTRIBUTING.md                                     | 13 +++++++------
 README.md                                           | 10 +++++-----
 {scripts => lib/scripts}/test-feature.sh            |  8 ++++----
 {scripts => lib/scripts}/validate-feature.sh        |  0
 package.json                                        |  4 ++--
 src/claude-code/devcontainer-feature.json           |  1 -
 src/claude-code/install.sh                          |  1 +
 test/claude-code/test.sh                            |  2 +-
 14 files changed, 35 insertions(+), 34 deletions(-)
 rename {scripts => lib/scripts}/test-feature.sh (95%)
 mode change 100755 => 100644
 rename {scripts => lib/scripts}/validate-feature.sh (100%)
 mode change 100755 => 100644

diff --git a/.github/skills/debug-feature/SKILL.md b/.github/skills/debug-feature/SKILL.md
index 06a5ddd..ddff531 100644
--- a/.github/skills/debug-feature/SKILL.md
+++ b/.github/skills/debug-feature/SKILL.md
@@ -17,7 +17,7 @@ Systematic triage guide for diagnosing failing `install.sh` scripts,
 
 Use this skill when:
 
-- `install.sh` exits with a non-zero code during `pnpm run test:feature`
+- `install.sh` exits with a non-zero code during `pnpm run feature:test`
 - A `test.sh` assertion fails (`[FAIL]` in output or non-zero exit)
 - The publish workflow's `test` job fails
 - A feature installs successfully locally but fails in CI
@@ -74,7 +74,7 @@ After applying a fix:
 1. Run the feature locally with act:
 
    ```bash
-   pnpm run test:feature <id>
+   pnpm run feature:test <id>
    ```
 
 2. Run the validation script to catch any remaining structural issues:
diff --git a/.github/skills/debug-feature/references/common-failure-modes.md b/.github/skills/debug-feature/references/common-failure-modes.md
index 4325c4d..3c4b017 100644
--- a/.github/skills/debug-feature/references/common-failure-modes.md
+++ b/.github/skills/debug-feature/references/common-failure-modes.md
@@ -327,7 +327,7 @@ Then bump the feature version using the `bump-feature` skill, since
 
 ### Detection
 
-- `pnpm run test:feature` exits with `"act is not installed"`
+- `pnpm run feature:test` exits with `"act is not installed"`
 - `docker: command not found`
 
 ### Fix
diff --git a/.github/skills/devcontainer/references/test-patterns.md b/.github/skills/devcontainer/references/test-patterns.md
index 5713c2a..08a7069 100644
--- a/.github/skills/devcontainer/references/test-patterns.md
+++ b/.github/skills/devcontainer/references/test-patterns.md
@@ -166,7 +166,7 @@ reportResults
 
 ```bash
 # Test a single feature (all modes: auto-generated + scenarios)
-pnpm run test:feature biome
+pnpm run feature:test biome
 
 # Runs:
 #   devcontainer features test -f biome \
@@ -180,7 +180,7 @@ Requires Docker and `@devcontainers/cli` (`npm install -g @devcontainers/cli`).
 
 `package-manager` declares `"installsAfter": ["ghcr.io/savvy-web/node"]`.
 Because the auto-generated test only installs the tested feature, `corepack`
-would be missing. `scripts/test-feature.sh` and `test.yml` detect this by
+would be missing. `lib/scripts/test-feature.sh` and `test.yml` detect this by
 reading `installsAfter` and automatically add `--skip-autogenerated` for such
 features. Scenarios for these features explicitly list the required dependency
 in their `"features"` map.
diff --git a/.github/skills/new-feature/SKILL.md b/.github/skills/new-feature/SKILL.md
index 0f93b41..0ff6673 100644
--- a/.github/skills/new-feature/SKILL.md
+++ b/.github/skills/new-feature/SKILL.md
@@ -253,7 +253,7 @@ pnpm run validate-feature <id>
 And optionally test locally if `act` is installed:
 
 ```bash
-pnpm run test:feature <id>
+pnpm run feature:test <id>
 ```
 
 ## Reference Files
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
index 5f77df0..9825953 100644
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -2,17 +2,17 @@
 #
 # Prepares the environment for Copilot cloud agent sessions working on this
 # repository. Installs Node.js, pnpm, the devcontainer CLI, and shellcheck so
-# the agent can run scripts/validate-feature.sh and pnpm run lint without
+# the agent can run lib/scripts/validate-feature.sh and pnpm run lint without
 # manual setup.
 
 name: "Copilot Setup Steps"
 on:
   workflow_dispatch:
   push:
-    branches: [main]
+    branches: [main, copilot/*]
     paths: [.github/workflows/copilot-setup-steps.yml]
   pull_request:
-    branches: [main]
+    branches: [main, copilot/*]
     paths: [.github/workflows/copilot-setup-steps.yml]
 
 jobs:
diff --git a/CLAUDE.md b/CLAUDE.md
index bd8631e..31001a9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,22 +44,22 @@ test/
   <id>/                    # mirrors src/<id> — test.sh + scenarios.json per feature
     test.sh
     scenarios.json
+lib/                       # config files and repo-level helpers
+    scripts/
+      test-feature.sh          # Run one feature's install + test locally via act
+      validate-feature.sh      # Check five-file completeness and structural rules
 
 docs/
   features/                # one .md file per feature, named by feature id
     <id>.md
 
-scripts/
-  test-feature.sh          # Run one feature's install + test locally via act
-  validate-feature.sh      # Check five-file completeness and structural rules
-
 .github/
   scripts/
     collect-and-filter-features.js  # Builds publish matrix (skips existing versions)
   workflows/
     test.yml                  # PR CI — auto-discovers all features and tests them
     publish.yml               # Publish to ghcr.io (manual trigger)
-    test-feature.yml          # Single-feature test used by scripts/test-feature.sh
+    test-feature.yml          # Single-feature test used by lib/scripts/test-feature.sh
     copilot-setup-steps.yml   # Copilot agent environment (Node, pnpm, devcontainer CLI)
   skills/
     devcontainer/             # Devcontainer spec + repo conventions
@@ -121,7 +121,7 @@ in the same commit.
 pnpm run validate-feature biome
 
 # Full install + test via act (requires Docker)
-pnpm run test:feature biome
+pnpm run feature:test biome
 ```
 
 `scripts/test-feature.sh` calls `act workflow_dispatch` targeting
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b30076..c1880ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,13 +36,14 @@ src/
 test/
   <id>/     # Mirrors src/<id> — test.sh + scenarios.json
 
+lib/                       # config files and repo-level helpers
+    scripts/
+      test-feature.sh          # Run one feature's install + test locally via act
+      validate-feature.sh      # Check five-file completeness and structural rules
+
 docs/
   features/ # One .md doc per feature, named by feature id
 
-scripts/
-  test-feature.sh     # Run a single feature's install + test locally
-  validate-feature.sh # Validate a feature's five-file completeness
-
 .github/
   scripts/
     collect-and-filter-features.js  # Builds publish matrix (skips already-published versions)
@@ -85,7 +86,7 @@ And optionally run the full install + test cycle locally (requires Docker and
 `act`):
 
 ```bash
-pnpm run test:feature my-feature
+pnpm run feature:test my-feature
 ```
 
 ## Bumping a Feature Version
@@ -108,7 +109,7 @@ Use the `bump-feature` Copilot skill for a guided checklist.
 
 | Script | Description |
 | :----- | :---------- |
-| `pnpm run test:feature <id>` | Run install + test for one feature locally via act |
+| `pnpm run feature:test <id>` | Run install + test for one feature locally via act |
 | `pnpm run validate-feature <id>` | Check five-file completeness and structural correctness |
 | `pnpm run lint` | Lint JS/TS/JSON files with Biome |
 | `pnpm run lint:fix` | Auto-fix lint issues |
diff --git a/README.md b/README.md
index abaf594..7bac5fb 100644
--- a/README.md
+++ b/README.md
@@ -74,15 +74,15 @@ scripts locally without pushing to CI.
 feature to your own devcontainer).
 
 ```bash
-pnpm run test:feature biome
-pnpm run test:feature rust
-pnpm run test:feature package-manager
+pnpm run feature:test biome
+pnpm run feature:test rust
+pnpm run feature:test package-manager
 
 # No argument prints available features
-pnpm run test:feature
+pnpm run feature:test
 ```
 
-`scripts/test-feature.sh` calls `act workflow_dispatch` against
+`lib/scripts/test-feature.sh` calls `act workflow_dispatch` against
 `.github/workflows/test-feature.yml`, which installs the feature and
 runs its `test.sh` inside a fresh Ubuntu container. The `.actrc` at the
 repo root configures act to use a slim ubuntu image and bind-mount the
diff --git a/scripts/test-feature.sh b/lib/scripts/test-feature.sh
old mode 100755
new mode 100644
similarity index 95%
rename from scripts/test-feature.sh
rename to lib/scripts/test-feature.sh
index e24233a..4c1bee1
--- a/scripts/test-feature.sh
+++ b/lib/scripts/test-feature.sh
@@ -4,9 +4,9 @@ set -euo pipefail
 # Test a single devcontainer feature locally using the devcontainer CLI.
 #
 # Usage:
-#   pnpm run test:feature <id>
-#   pnpm run test:feature biome
-#   pnpm run test:feature package-manager
+#   pnpm run feature:test <id>
+#   pnpm run feature:test biome
+#   pnpm run feature:test package-manager
 #
 # Requires:
 #   - Docker running locally
@@ -18,7 +18,7 @@ set -euo pipefail
 # pass/fail markers.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 
 ID="${1:-}"
 
diff --git a/scripts/validate-feature.sh b/lib/scripts/validate-feature.sh
old mode 100755
new mode 100644
similarity index 100%
rename from scripts/validate-feature.sh
rename to lib/scripts/validate-feature.sh
diff --git a/package.json b/package.json
index 5555ce5..8feb26f 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,8 @@
 		"ci:version": "savvy-changesets version && biome format --write .",
 		"commit:check": "savvy-commit check",
 		"commit:init": "savvy-commit init",
+		"feature:test": "bash lib/scripts/test-feature.sh",
+		"feature:validate": "bash lib/scripts/validate-feature.sh",
 		"lint": "biome check --max-diagnostics=none",
 		"lint:fix": "biome check --write --max-diagnostics=none",
 		"lint:fix:unsafe": "biome check --write --unsafe --max-diagnostics=none",
@@ -35,8 +37,6 @@
 		"lint:md:fix": "markdownlint-cli2  --config './lib/configs/.markdownlint-cli2.jsonc' --fix",
 		"prepare": "husky",
 		"test": "vitest run --passWithNoTests",
-		"test:feature": "bash scripts/test-feature.sh",
-		"validate-feature": "bash scripts/validate-feature.sh",
 		"test:watch": "vitest --watch",
 		"typecheck": "turbo run types:check --log-prefix=none --log-order=grouped",
 		"types:check": "tsgo --noEmit"
diff --git a/src/claude-code/devcontainer-feature.json b/src/claude-code/devcontainer-feature.json
index 3e9caf7..708902c 100644
--- a/src/claude-code/devcontainer-feature.json
+++ b/src/claude-code/devcontainer-feature.json
@@ -5,7 +5,6 @@
 	"description": "Installs the Claude Code CLI agent globally via the official native installer (curl | bash). Does not require Node.js or npm.",
 	"documentationURL": "https://github.com/savvy-web/devcontainers/blob/main/docs/features/claude-code.md",
 	"installsAfter": [],
-	"entrypoint": "/install.sh",
 	"platforms": ["linux", "darwin"],
 	"keywords": ["claude", "ai", "agent", "global"]
 }
diff --git a/src/claude-code/install.sh b/src/claude-code/install.sh
index 40ec06f..163360f 100755
--- a/src/claude-code/install.sh
+++ b/src/claude-code/install.sh
@@ -35,5 +35,6 @@ if ! command -v claude &>/dev/null; then
   exit 1
 fi
 
+
 claude --version
 echo "[SUCCESS] Claude Code CLI installed."
diff --git a/test/claude-code/test.sh b/test/claude-code/test.sh
index 6f520f8..51c2f76 100755
--- a/test/claude-code/test.sh
+++ b/test/claude-code/test.sh
@@ -10,6 +10,6 @@ set -e
 
 source dev-container-features-test-lib
 
-check "claude CLI is installed" claude --version
+check "claude CLI is installed" bash -c "claude --version | grep 'Claude Code'"
 
 reportResults

From c05a5e7b91108daeea27589cae61b3f16057852d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 22:26:53 +0000
Subject: [PATCH 18/18] fix(claude-code): run native installer as _REMOTE_USER
 via su

The native installer writes the binary to $HOME/.local/bin/claude.
When running as root during the Docker build ($HOME=/root, mode 700),
the installed binary is inaccessible to non-root container users
(e.g. vscode) causing `claude: command not found` at test time.

Follow the same pattern as the homebrew feature: use _REMOTE_USER
when it is non-root and present in the image, running the installer
via `su - $INSTALL_USER` so the binary lands in that user's home
directory and is owned/accessible by them at runtime. Fall back to a
world-accessible shared prefix (/usr/local/lib/claude-code) with
chmod -R a+rX when no non-root remote user is available.

Signed-off-by: Copilot <copilot@github.com>

Agent-Logs-Url: https://github.com/savvy-web/devcontainers/sessions/4eba7a96-ba2b-4125-ade0-bd06444cd2c4

Co-authored-by: spencerbeggs <109114+spencerbeggs@users.noreply.github.com>
---
 src/claude-code/install.sh | 61 +++++++++++++++++++++++++-------------
 1 file changed, 41 insertions(+), 20 deletions(-)

diff --git a/src/claude-code/install.sh b/src/claude-code/install.sh
index 163360f..be0edb1 100755
--- a/src/claude-code/install.sh
+++ b/src/claude-code/install.sh
@@ -4,37 +4,58 @@ set -euo pipefail
 # Claude Code CLI — native installer
 # Docs: https://code.claude.com/docs/en/setup
 #
-# Installation via @anthropic-ai/claude-code on npm is deprecated.
-# This feature uses the official curl | bash installer instead.
+# The native installer writes files under $HOME (.local/bin, .anthropic/, etc.).
+# Feature installs always run as root, so we use _REMOTE_USER (e.g. vscode) to
+# run the installer as the devcontainer user — the same pattern used by the
+# homebrew feature. This ensures the binary is owned by and accessible to the
+# user that will be running claude at runtime.
+# A symlink in /usr/local/bin makes `claude` available to all users on PATH.
 
-if command -v claude &>/dev/null; then
-  echo "[INFO] Claude Code CLI already installed: $(claude --version)"
+REMOTE_USER="${_REMOTE_USER:-}"
+
+# Use _REMOTE_USER when it's non-root and exists in the image; otherwise fall
+# back to a system-wide shared prefix under /usr/local that is world-accessible.
+if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]] && id -u "$REMOTE_USER" >/dev/null 2>&1; then
+  INSTALL_USER="$REMOTE_USER"
+  INSTALL_HOME=$(getent passwd "$INSTALL_USER" | cut -d: -f6)
+else
+  if [[ -n "$REMOTE_USER" && "$REMOTE_USER" != "root" ]]; then
+    echo "[INFO] Remote user '${REMOTE_USER}' not found in image; installing to shared prefix."
+  fi
+  INSTALL_USER="root"
+  INSTALL_HOME="/usr/local/lib/claude-code"
+  mkdir -p "$INSTALL_HOME"
+fi
+
+CLAUDE_BIN="${INSTALL_HOME}/.local/bin/claude"
+
+if [[ -x "$CLAUDE_BIN" ]]; then
+  echo "[INFO] Claude Code CLI already installed at ${CLAUDE_BIN}."
+  ln -sf "$CLAUDE_BIN" /usr/local/bin/claude 2>/dev/null || true
   exit 0
 fi
 
-echo "[INFO] Installing Claude Code CLI via native installer..."
-curl -fsSL https://claude.ai/install.sh | bash
+echo "[INFO] Installing Claude Code CLI as user '${INSTALL_USER}'..."
 
-# The native installer may place the binary outside the calling shell's PATH
-# (e.g. ~/.local/bin). Search known locations and symlink into /usr/local/bin
-# when necessary so claude is available to all users.
-if ! command -v claude &>/dev/null; then
-  for candidate in \
-    "${HOME}/.local/bin/claude" \
-    "${HOME}/.anthropic/bin/claude" \
-    "/usr/local/bin/claude"; do
-    if [[ -x "$candidate" ]]; then
-      ln -sf "$candidate" /usr/local/bin/claude
-      break
-    fi
-  done
+if [[ "$INSTALL_USER" == "root" ]]; then
+  HOME="$INSTALL_HOME" curl -fsSL https://claude.ai/install.sh | bash
+  # Make all installed files world-readable/executable so non-root users can run claude.
+  chmod -R a+rX "$INSTALL_HOME"
+else
+  su - "$INSTALL_USER" -s /bin/bash -c 'curl -fsSL https://claude.ai/install.sh | bash'
 fi
 
+if [[ ! -x "$CLAUDE_BIN" ]]; then
+  echo "[ERROR] Claude Code binary not found at ${CLAUDE_BIN} after install." >&2
+  exit 1
+fi
+
+ln -sf "$CLAUDE_BIN" /usr/local/bin/claude
+
 if ! command -v claude &>/dev/null; then
   echo "[ERROR] Claude Code CLI not found in PATH after install." >&2
   exit 1
 fi
 
-
 claude --version
 echo "[SUCCESS] Claude Code CLI installed."