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/