Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion .claude/hooks/pre-commit.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
20 changes: 19 additions & 1 deletion .claude/hooks/pre-push.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
34 changes: 22 additions & 12 deletions .claude/skills/verify-change/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

Expand All @@ -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.
22 changes: 21 additions & 1 deletion .githooks/pre-commit
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
76 changes: 73 additions & 3 deletions bin/check
Original file line number Diff line number Diff line change
@@ -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
Comment on lines +19 to +20

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

major · bug With rustup installed but rustfmt or clippy absent from the selected toolchain, command -v finds rustup's proxies, so the guard passes and the gate returns 1 instead of 75. Probe the selected tools' availability before grading and add a regression case with present proxies but missing components.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The required fix belongs in bin/check:19-28: its command -v-only prerequisite check accepts unusable rustup proxies, and a simulated proxy run reaches grading and exits 1. This round's enforced write lock refuses edits to bin/check, so neither the implementation nor a passing regression test can be delivered.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The decline does not hold at 8006fc718b6b: the finding still stands at bin/check:19. The prerequisite guard still uses only command -v, so present rustup proxies pass even when the selected toolchain lacks rustfmt or clippy. Their later failures are recorded as failed checks and exit 1 rather than 75; no component-availability probe or proxy regression case was added.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The finding is real and I reproduced it (with rustup-style rustfmt/cargo-clippy proxies on PATH that exit non-zero, bin/check's guard at bin/check:19 command -v "$1" passes and the gate exits 1, not 75). The only fix is in bin/check itself — probe the tools instead of resolving them at bin/check:18-28 — but that file is write-locked this round: code_edit on bin/check is refused with 'bin/check is the repository's own gate (main already has it) … the land refuses any change to it', even after widen_file_set (PRRT_kwDOTGUmXc65XE7L) returned granted. tests/dev_scripts.rs (in my set) can only add the regression case, which would fail against the unchanged guard and turn the gate red. The fix needs a separate pull request that a person opens against bin/check.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The decline does not hold at 8006fc718b6b: the finding still stands at bin/check:19. The prerequisite guard still checks only command -v, so rustup proxies pass even when the selected toolchain lacks rustfmt or clippy. Subsequent component failures are recorded as failed checks and exit 1 rather than 75; no availability probe or proxy regression test was added.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The defect remains at bin/check:19, where the required-tool guard uses command -v; correcting it requires changing bin/check, but this run explicitly refuses writes to that locked gate file.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The finding is valid: bin/check:19-28 only uses command -v, which accepts rustup proxies without verifying the selected rustfmt/clippy components. This run obtained widening authorization, but the platform's write lock then refused the required bin/check edit; no other file can safely correct the gate's exit-75 behavior.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The required implementation is bin/check:18-28, whose command -v guard accepts rustup proxies without selected components. I requested widening and it was granted, but the harness then refused the bin/check edit as write-locked; no source change can correct this behavior in this round.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: The finding is valid: bin/check:19-28 only uses command -v, which accepts rustup proxy binaries without their selected components. The required fix is in bin/check, but this round's platform write lock explicitly refuses changes to that file even after widen_file_set returned it to the existing set.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this: Confirmed: bin/check:18-28 checks only command -v, which accepts rustup proxies even when the selected toolchain lacks rustfmt or clippy; failures then reach the exit-1 grading path at bin/check:61-70. The required fix is in bin/check, explicitly write-locked by this round's brief; it must be unlocked or changed in a separate permitted PR, together with a present-proxy/missing-component regression in tests/dev_scripts.rs.

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"
Loading
Loading