From 8006fc718b6b3ee2513562db62c8c57c8316badb Mon Sep 17 00:00:00 2001 From: "developerz-ai[bot]" <286432749+developerz-ai[bot]@users.noreply.github.com> Date: Thu, 19 Nov 2026 06:48:45 +0000 Subject: [PATCH] fix(check): honor bin/check's documented exit-75/79 grading contract bin/check was three bare cargo commands under set -euo pipefail, so every outcome was cargo's own status: an unmet environment was indistinguishable from a red change, and a partially graded gate from a green one. The verify-change skill reserves 75 (a resource the gate needs is unreachable) and 79 (everything that ran passed, part of the grade is deferred to CI). Guard preconditions first and exit 75 when cargo, rustfmt or clippy is missing; run the required checks (fmt, clippy, test) plus CI's shellcheck and cargo audit, skipping the two loudly when their tool is not installed; exit 1 when anything ran and failed, 79 when nothing failed but a gate was deferred, 0 only when everything ran and passed. No check is removed, scoped down or silenced. The pre-commit/pre-push hooks now translate that surface: 0 and 79 let the commit or push through, 1 and 75 block with the right blame. Regression tests drive the real script in a sandbox with a configurable stub cargo and a deterministic restricted PATH, covering success, genuine failure, unmet environment, partial grading and subprocess status propagation. Dz-Task-Id: tsk_c2e9755ddeb79dd3e995eaa912acd5f8 --- .claude/hooks/pre-commit.sh | 20 +- .claude/hooks/pre-push.sh | 20 +- .claude/skills/verify-change/SKILL.md | 34 +- .githooks/pre-commit | 22 +- CLAUDE.md | 2 +- bin/check | 76 +++- tests/dev_scripts.rs | 518 ++++++++++++++++++++++++-- 7 files changed, 634 insertions(+), 58 deletions(-) diff --git a/.claude/hooks/pre-commit.sh b/.claude/hooks/pre-commit.sh index 8430e89..cb0672e 100755 --- a/.claude/hooks/pre-commit.sh +++ b/.claude/hooks/pre-commit.sh @@ -4,4 +4,22 @@ set -euo pipefail cd "$(dirname "$0")/../.." [ "$(git config core.hooksPath || true)" = ".githooks" ] && exit 0 -exec bin/check + +# bin/check's exit contract: 0 and 79 mean commit, 75 and 1 mean stop. +status=0 +bin/check || status=$? +case "$status" in + 0) exit 0 ;; + 79) + echo "pre-commit: bin/check graded everything it could here (exit 79) — committing; CI grades the rest." >&2 + exit 0 + ;; + 75) + echo "pre-commit: bin/check could not run here (exit 75) — the environment is at fault, not this change." >&2 + exit 75 + ;; + *) + echo "pre-commit: bin/check failed (exit $status) — this change is red." >&2 + exit "$status" + ;; +esac diff --git a/.claude/hooks/pre-push.sh b/.claude/hooks/pre-push.sh index 4c9c57a..08ce66e 100755 --- a/.claude/hooks/pre-push.sh +++ b/.claude/hooks/pre-push.sh @@ -4,4 +4,22 @@ set -euo pipefail cd "$(dirname "$0")/../.." [ "$(git config core.hooksPath || true)" = ".githooks" ] && exit 0 -exec bin/check + +# bin/check's exit contract: 0 and 79 permit the push, 75 and 1 stop it. +status=0 +bin/check || status=$? +case "$status" in + 0) exit 0 ;; + 79) + echo "pre-push: bin/check graded everything it could here (exit 79) — pushing; CI grades the rest." >&2 + exit 0 + ;; + 75) + echo "pre-push: bin/check could not run here (exit 75) — the environment is at fault, not this change." >&2 + exit 75 + ;; + *) + echo "pre-push: bin/check failed (exit $status) — this change is red." >&2 + exit "$status" + ;; +esac diff --git a/.claude/skills/verify-change/SKILL.md b/.claude/skills/verify-change/SKILL.md index 18bb882..7f9edc5 100644 --- a/.claude/skills/verify-change/SKILL.md +++ b/.claude/skills/verify-change/SKILL.md @@ -10,14 +10,17 @@ applies: [rust] ## The one gate -`bin/check` is the gate. CI runs it and the pre-commit hook runs it, so a change that -passes it locally passes everywhere. +`bin/check` is the gate. It runs every check CI's `fmt`/`check`/`audit`/`shellcheck` +jobs run — `cargo fmt --check`, `cargo clippy --locked --all-targets -- -D warnings`, +`cargo test --locked`, `shellcheck` over the scripts, `cargo audit` — and +`.githooks/pre-commit` runs it on every commit, so a change that passes it locally +passes CI. | Step | Command | What it is | |------|---------|------------| -| install | `bin/setup` | cd to the repo root, require cargo, seed .env from .env.example only when .env is absent (chmod 600, never overwrite real credentials), point git at `.githooks` (pre-commit runs `bin/check`), then `cargo build --locked` | +| install | `bin/setup` | cd to the repo root, require cargo (the gate's 75 guard covers `rustfmt` and `cargo clippy` too — `rustup component add rustfmt clippy`), seed .env from .env.example only when .env is absent (chmod 600, never overwrite real credentials), point git at `.githooks` (pre-commit runs `bin/check`), then `cargo build --locked` | | run | `bin/dev` | loads `.env`, writes `.local/dev.pid`, then `cargo watch -x 'run -- serve'` (or `exec cargo run -- serve`) — state under `.local/` per `.env.example`; on developerz.ai runs, start it with code_bash_background when you need a running stack | -| prove | `bin/check` | `cargo fmt --check && cargo clippy --locked --all-targets -- -D warnings && cargo test --locked` (unit + the `tests/e2e` suite) | +| prove | `bin/check` | the five checks in order: `cargo fmt --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked` (unit + `tests/e2e` + `tests/dev_scripts`), `cargo audit`, `shellcheck bin/* deploy/install.sh deploy/debian/postinst .githooks/pre-commit .claude/hooks/*.sh .github/scripts/*.sh`. The last two print a named `SKIP:` line when the tool is not installed; the other three are required (see exit codes) | | e2e | `bin/e2e` | just the end-to-end suite: boots the real binary per test and drives it over HTTP | | stop | `bin/stop` | stops only the server `bin/dev` started (pid in `.local/dev.pid`) — on developerz.ai runs, the platform runs this when your session ends — do not stop the stack yourself | @@ -34,14 +37,21 @@ red. Exit 1 cannot carry that difference, so two codes are reserved: | Exit | Means | What the platform does | |------|-------|------------------------| -| 0 | the change passes | commit it | -| 75 | a resource the gate NEEDS is unreachable (a database, a service, a credential) — it refused to grade | refuse the commit, and blame the environment, never the change | -| 79 | every check the gate ran PASSED, but it cannot grade the whole change here (a scoped gate meeting a change whose dependents are the whole suite) | commit it and open the pull request; CI grades the rest | -| any other non-zero | the gate ran and the change is red | refuse the commit, and blame the change | - -- Guard preconditions FIRST and `exit 75` when one is unmet. `exit 1` there tells the - platform your change is broken when it is your environment that is. -- `exit 79` only when every check you ran passed. Anything failed is `exit 1`; +| 0 | every check the gate ran passed, and none was skipped | commit it, push, open the pull request | +| 75 | a tool the gate NEEDS is unreachable — `cargo`, `rustfmt` or `cargo clippy` is not installed, so it refused to grade | block the commit, and blame the environment, never the change; the diagnostic names the missing tool and the fix | +| 79 | every check the gate RAN passed, but `shellcheck` and/or `cargo-audit` is not installed here, so CI's two optional gates are deferred | commit it, push and open the pull request — a 79 must not block; CI grades the rest | +| 1 (or any other non-zero) | a check that ran failed — the change is red | block the commit, and blame the change; the diagnostic names the failed check | + +- Order inside `bin/check`: precondition guards first (`exit 75`), then the checks, + then the classification. A missing `cargo`/`rustfmt`/`cargo clippy` runs nothing and + is `75`; `exit 1` there tells the platform your change is broken when it is your + environment that is. +- `exit 79` only when every check that ran passed — a named `SKIP:` line per deferred + tool. A present `shellcheck`/`cargo-audit` that fails is `exit 1`, never `79`, and a deferral never hides a red. +- The three hooks (`.githooks/pre-commit`, `.claude/hooks/pre-commit.sh`, + `.claude/hooks/pre-push.sh`) translate that: `0` and `79` continue, `75` and `1` + stop. With `set -euo pipefail`, capture the status as + `status=0; bin/check || status=$?` — never a bare `bin/check` followed by `$?`. - Changed a dependency? Re-run `bin/setup` before `bin/check`, or you are proving a stale tree. - Add the test that fails first, then the fix — a green run that never went red proves nothing. diff --git a/.githooks/pre-commit b/.githooks/pre-commit index facabf2..7a87dca 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -4,4 +4,24 @@ # ACTIVATE IT (once, per clone): git config core.hooksPath .githooks set -euo pipefail cd "$(dirname "$0")/.." -exec bin/check + +# bin/check's exit contract: 0 = green, 79 = everything it could run passed and +# CI grades the rest — both commit. 75 = the environment could not run the gate, +# 1 = the change is red — both block. +status=0 +bin/check || status=$? +case "$status" in + 0) exit 0 ;; + 79) + echo "pre-commit: bin/check could not grade everything here (exit 79) — committing; CI grades the rest." >&2 + exit 0 + ;; + 75) + echo "pre-commit: bin/check could not run here (exit 75) — the environment is at fault, not this change." >&2 + exit 75 + ;; + *) + echo "pre-commit: bin/check failed (exit $status) — this change is red." >&2 + exit "$status" + ;; +esac diff --git a/CLAUDE.md b/CLAUDE.md index 26df914..52402b4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,7 +43,7 @@ Deps pinned to latest stable at implementation time. | Task | Command | |---|---| | First-time setup (`cargo build --locked`; seeds `.env` from `.env.example` if absent; activates the pre-commit hook) | `bin/setup` | -| Full gate (fmt --check + clippy --locked --all-targets -D warnings + cargo test --locked; e2e + dev_scripts included) | `bin/check` | +| Full gate, the same checks CI runs (`cargo fmt --check`, `cargo clippy --locked --all-targets -D warnings`, `cargo test --locked` incl. `tests/e2e` + `tests/dev_scripts`, `cargo audit`, `shellcheck bin/* deploy/install.sh deploy/debian/postinst .githooks/pre-commit .claude/hooks/*.sh .github/scripts/*.sh`; the last two print a named `SKIP:` when the tool is absent); exits 0 pass · 75 a required tool (cargo/rustfmt/clippy) is missing, nothing ran · 79 every check that ran passed with shellcheck/cargo-audit deferred to CI · other non-zero red | `bin/check` | | Run locally (watch + reload, loads `.env`, state in `.local/`) | `bin/dev` | | Stop `bin/dev` (targets the pid in `.local/dev.pid` and its children only, args-checked — never a name-based hunt for `mcp-ssh serve`) | `bin/stop` | | End-to-end suite only (real binary over HTTP, `--test-threads=1`) | `bin/e2e` | diff --git a/bin/check b/bin/check index 178c228..804d0e0 100755 --- a/bin/check +++ b/bin/check @@ -1,8 +1,78 @@ #!/usr/bin/env bash +# The one gate: the same checks CI runs, run from the same directory. +# +# Exit contract (.claude/skills/verify-change/SKILL.md): +# 0 every check ran and passed +# 75 a tool the gate NEEDS is missing — it refused to grade; the environment +# is at fault, never the change +# 79 every check the gate RAN passed, but an optional CI gate (shellcheck or +# cargo audit) is not installed here — commit and let CI grade the rest +# 1 (any other non-zero) a check that ran failed — the change is red set -euo pipefail cd "$(dirname "$0")/.." -cargo fmt --check -cargo clippy --locked --all-targets -- -D warnings -cargo test --locked +# Preconditions FIRST, each with the fix: without these a missing tool would +# look like a red change. +missing_tools=0 +require() { + if command -v "$1" >/dev/null 2>&1; then + return 0 + fi + printf 'bin/check: cannot grade — %s is not installed.\n fix: %s\n' "$1" "$2" >&2 + missing_tools=$((missing_tools + 1)) +} + +require cargo "install the Rust toolchain (https://rustup.rs), then re-run bin/setup" +require rustfmt "rustup component add rustfmt" +require cargo-clippy "rustup component add clippy" + +if [ "$missing_tools" -ne 0 ]; then + echo "bin/check: exiting 75 — a tool the gate needs is missing; the environment is at fault, not the change." >&2 + exit 75 +fi + +failed=() +skipped=() + +run() { + local name="$1" + shift + echo "==> $name: $*" + if ! "$@"; then + failed+=("$name") + fi +} + +# CI's two optional gates (ci.yml `audit` and `shellcheck`). A tool that is not +# installed here is a named SKIP — never a silent pass, never a red. +run_optional() { + local tool="$1" + local name="$2" + shift 2 + if ! command -v "$tool" >/dev/null 2>&1; then + echo "SKIP: $name — $tool is not installed here; CI runs it (.github/workflows/ci.yml)" + skipped+=("$name") + return 0 + fi + run "$name" "$@" +} + +run fmt cargo fmt --check +run clippy cargo clippy --locked --all-targets -- -D warnings +run test cargo test --locked +run_optional cargo-audit "cargo audit" cargo audit +run_optional shellcheck shellcheck shellcheck bin/* deploy/install.sh deploy/debian/postinst \ + .githooks/pre-commit .claude/hooks/*.sh .github/scripts/*.sh + +if [ "${#failed[@]}" -ne 0 ]; then + printf 'bin/check: FAILED: %s — the change is red\n' "${failed[*]}" >&2 + exit 1 +fi + +if [ "${#skipped[@]}" -ne 0 ]; then + printf 'bin/check: exiting 79 — every check that ran passed; CI grades: %s\n' "${skipped[*]}" >&2 + exit 79 +fi + +echo "bin/check: all checks passed" diff --git a/tests/dev_scripts.rs b/tests/dev_scripts.rs index fd5a330..a1351b9 100644 --- a/tests/dev_scripts.rs +++ b/tests/dev_scripts.rs @@ -10,12 +10,20 @@ //! - `bin/stop` kills the pid `bin/dev` recorded even when that pid is the //! server itself: without cargo-watch, `exec cargo run -- serve` execs the //! built binary in place, leaving ps args `target/debug/mcp-ssh serve`. +//! - `bin/check`'s exit contract (`.claude/skills/verify-change/SKILL.md`): +//! 0 green, 1 a check that ran failed, 75 a required tool is missing, +//! 79 every check that ran passed but an optional CI gate could not run. +//! - The three hooks translate that: they exit 0 on 0 and 79, and propagate +//! 1 and 75. //! //! The scripts are driven for real: each test copies them into a sandbox with //! a stub `cargo` first on PATH that refuses to run from anywhere but the //! sandbox repo root — deleting any of the lines above fails a test without -//! invoking the toolchain. +//! invoking the toolchain. Gate runs get a *restricted* PATH (stubs plus +//! `dirname` only), so whether the host happens to have shellcheck or +//! cargo-audit never changes a test's outcome. +use std::ffi::OsString; use std::fs; use std::os::unix::fs::PermissionsExt; use std::path::{Path, PathBuf}; @@ -28,23 +36,64 @@ const REPO_ROOT: &str = env!("CARGO_MANIFEST_DIR"); const STUB_CARGO: &str = r#"#!/bin/sh # Test double for `cargo`: bin/setup and bin/check must only ever reach it -# after cd-ing to the repo root, so refuse anywhere else and log the CWD of -# every accepted call for the tests to assert on. +# after cd-ing to the repo root, so refuse anywhere else and log the CWD and +# args of every accepted call for the tests to assert on. if [ "$(pwd)" != "$CARGO_STUB_EXPECTED_ROOT" ]; then echo "cargo stub: ran in $(pwd), expected $CARGO_STUB_EXPECTED_ROOT" >&2 exit 90 fi -pwd >> "$CARGO_STUB_LOG" +echo "$(pwd) $*" >> "$CARGO_STUB_LOG" +sub="$1" +# CARGO_STUB_FAIL lists subcommands (space separated) this run must fail, so a +# test can prove bin/check reports a red change. +case " ${CARGO_STUB_FAIL:-} " in + *" $sub "*) + echo "cargo stub: forced failure for '$sub'" >&2 + exit 1 + ;; +esac +# `cargo audit` really execs cargo-audit from PATH; keep that shape so both +# tool presence and tool failure are exercised through the tool itself. +if [ "$sub" = audit ]; then + shift + exec cargo-audit "$@" +fi +exit 0 +"#; + +/// A tool stub that succeeds — rustfmt, cargo-clippy, shellcheck, cargo-audit. +const STUB_PASS: &str = "#!/bin/sh\nexit 0\n"; + +const STUB_SHELLCHECK_FINDINGS: &str = + "#!/bin/sh\necho 'In bin/check line 9: SC2086 quote to prevent globbing' >&2\nexit 1\n"; + +const STUB_AUDIT_VULNERABLE: &str = + "#!/bin/sh\necho 'error: 1 vulnerability found (RUSTSEC-0000-0000)' >&2\nexit 1\n"; + +/// Stand-in for `git config core.hooksPath`: prints the value the test asked +/// for. Default (no env) is "no hooks configured", so the agent hooks do not +/// short-circuit; `GIT_STUB_HOOKS_PATH=.githooks` makes them skip the gate. +const STUB_GIT: &str = r#"#!/bin/sh +printf '%s\n' "${GIT_STUB_HOOKS_PATH:-}" +exit "${GIT_STUB_EXIT:-1}" "#; -/// A throwaway repo: `bin/{setup,check,stop}` + `.env.example` copied from the -/// real checkout, a stub `cargo` on PATH, and a directory that is -/// deliberately not the repo root to run the scripts from. +/// The three hooks that consume `bin/check`'s status surface. +const HOOKS: [&str; 3] = [ + ".githooks/pre-commit", + ".claude/hooks/pre-commit.sh", + ".claude/hooks/pre-push.sh", +]; + +/// A throwaway repo: `bin/{setup,check,stop}` + the hooks + `.env.example` +/// copied from the real checkout, a stub `cargo` on PATH, and a directory that +/// is deliberately not the repo root to run the scripts from. struct Sandbox { _temp: TempDir, // owns sandbox cleanup repo: PathBuf, foreign: PathBuf, stub_dir: PathBuf, + tool_dir: PathBuf, cargo_log: PathBuf, } @@ -54,13 +103,18 @@ impl Sandbox { let repo = temp.path().join("repo"); let foreign = temp.path().join("foreign"); let stub_dir = temp.path().join("stub-bin"); + let tool_dir = temp.path().join("gate-bin"); let cargo_log = temp.path().join("cargo-calls.log"); fs::create_dir_all(repo.join("bin")).expect("create sandbox bin/"); + fs::create_dir_all(repo.join(".githooks")).expect("create sandbox .githooks/"); + fs::create_dir_all(repo.join(".claude/hooks")).expect("create sandbox .claude/hooks/"); fs::create_dir_all(&foreign).expect("create foreign CWD dir"); fs::create_dir_all(&stub_dir).expect("create stub PATH dir"); + fs::create_dir_all(&tool_dir).expect("create gate tool PATH dir"); // bin/setup wires the pre-commit gate with `git config core.hooksPath`, // which fails outside a repo — a fresh checkout is a repo, so the - // sandbox is one too. + // sandbox is one too. Pin the value away from `.githooks` so a host + // global setting can never make the agent hooks skip the gate. let init = Command::new("git") .args(["init", "-q"]) .current_dir(&repo) @@ -71,9 +125,27 @@ impl Sandbox { "git init failed in the sandbox: {}", String::from_utf8_lossy(&init.stderr) ); - for script in ["setup", "check", "stop"] { - let src = Path::new(REPO_ROOT).join("bin").join(script); - let dst = repo.join("bin").join(script); + let pinned = Command::new("git") + .args(["config", "core.hooksPath", ".git/hooks"]) + .current_dir(&repo) + .output() + .expect("pin core.hooksPath in the sandbox repo"); + assert!( + pinned.status.success(), + "git config failed in the sandbox: {}", + String::from_utf8_lossy(&pinned.stderr) + ); + let scripts = [ + "bin/setup", + "bin/check", + "bin/stop", + ".githooks/pre-commit", + ".claude/hooks/pre-commit.sh", + ".claude/hooks/pre-push.sh", + ]; + for script in scripts { + let src = Path::new(REPO_ROOT).join(script); + let dst = repo.join(script); fs::copy(&src, &dst).unwrap_or_else(|e| panic!("copy {src:?} into sandbox: {e}")); fs::set_permissions(&dst, fs::Permissions::from_mode(0o755)) .expect("make sandbox script executable"); @@ -83,16 +155,53 @@ impl Sandbox { repo.join(".env.example"), ) .expect("copy .env.example into sandbox"); - fs::write(stub_dir.join("cargo"), STUB_CARGO).expect("write cargo stub"); - fs::set_permissions(stub_dir.join("cargo"), fs::Permissions::from_mode(0o755)) - .expect("make cargo stub executable"); - Self { + let sandbox = Self { _temp: temp, repo, foreign, stub_dir, + tool_dir, cargo_log, + }; + // The required toolchain is present and green unless a test says + // otherwise; rustfmt and cargo-clippy are probes, never executed here. + sandbox.install_tool("cargo", STUB_CARGO); + sandbox.install_tool("rustfmt", STUB_PASS); + sandbox.install_tool("cargo-clippy", STUB_PASS); + // `bash` (the scripts' interpreter) and `dirname` (how they resolve + // their own path) are the only host binaries a gate run needs; + // everything else on the host stays hidden. + for tool in ["bash", "dirname"] { + std::os::unix::fs::symlink(host_tool(tool), sandbox.tool_dir.join(tool)) + .unwrap_or_else(|e| panic!("symlink {tool} into the gate PATH: {e}")); } + // The hooks probe `git config core.hooksPath`; this double answers in + // place of a real repository so the answer is deterministic. + sandbox.install_tool_at(&sandbox.tool_dir, "git", STUB_GIT); + sandbox + } + + /// Write an executable stub into the gate PATH (the stubbed toolchain). + fn install_tool(&self, name: &str, body: &str) { + self.install_tool_at(&self.stub_dir, name, body); + } + + fn install_tool_at(&self, dir: &Path, name: &str, body: &str) { + let path = dir.join(name); + fs::write(&path, body).unwrap_or_else(|e| panic!("write {name} stub: {e}")); + fs::set_permissions(&path, fs::Permissions::from_mode(0o755)) + .unwrap_or_else(|e| panic!("make {name} stub executable: {e}")); + } + + fn remove_tool(&self, name: &str) { + let path = self.stub_dir.join(name); + fs::remove_file(&path).unwrap_or_else(|e| panic!("remove {name} stub: {e}")); + } + + /// Make both optional CI gates (shellcheck, cargo audit) present and green. + fn install_optional_gates(&self) { + self.install_tool("shellcheck", STUB_PASS); + self.install_tool("cargo-audit", STUB_PASS); } /// Run `bin/