From b74707ec8839950e19b35556ec8c7df2705ffcbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:20:51 -0500 Subject: [PATCH 1/4] feat(repo): A commit with unformatted Rust is refused before it leaves the machine A tracked pre-commit hook in .githooks/ checks the staged copy of each Rust file with rustfmt and each staged JavaScript file with ESLint. It runs no build, no test and no network call; CI keeps those. A Claude session installs it at start by setting core.hooksPath, which covers every worktree of the clone. docs/develop.md says how to install it without Claude. Refs #31 Co-Authored-By: Claude Opus 5.5 --- .claude/settings.json | 12 +++ .githooks/pre-commit | 84 +++++++++++++++ .github/workflows/ci.yml | 3 + docs/develop.md | 16 +++ scripts/install-git-hooks.sh | 22 ++++ scripts/test_git_hooks.py | 194 +++++++++++++++++++++++++++++++++++ 6 files changed, 331 insertions(+) create mode 100755 .githooks/pre-commit create mode 100755 scripts/install-git-hooks.sh create mode 100644 scripts/test_git_hooks.py diff --git a/.claude/settings.json b/.claude/settings.json index 696cea6..6b85023 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,5 +3,17 @@ "foresight@foresight-vendored": true, "superpowers@foresight-vendored": false, "mattpocock-skills@foresight-vendored": false + }, + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install-git-hooks.sh" + } + ] + } + ] } } diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000..415ab7a --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +# Fast checks on the staged change only: rustfmt on staged Rust files and +# ESLint on staged JavaScript. No build, no test suite and no network call; +# CI runs those (docs/develop.md, "Run the checks"). +# Written for bash 3.2, the bash macOS ships. +set -uo pipefail + +cd "$(git rev-parse --show-toplevel)" || exit 1 +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +status=0 + +staged() { + git diff --cached --name-only -z --diff-filter=ACMR -- "$@" +} + +# rustfmt reads each staged blob on stdin, so a file whose working copy differs +# from what is staged is judged by what will be committed. `rustup run` never +# installs a missing toolchain, where the plain proxy would download it. +rustfmt_staged() { + if command -v rustup >/dev/null 2>&1; then + local channel + channel=$(sed -n 's/^channel *= *"\(.*\)"/\1/p' rust-toolchain.toml) + rustup run "$channel" rustfmt "$@" + else + rustfmt "$@" + fi +} + +edition=$(sed -n 's/^edition *= *"\(.*\)"/\1/p' Cargo.toml | head -n 1) +unformatted=() +while IFS= read -r -d '' file; do + git show ":$file" >"$tmp/in" + if ! rustfmt_staged --edition "$edition" --emit stdout <"$tmp/in" >"$tmp/out" 2>"$tmp/err"; then + echo "pre-commit: rustfmt could not check $file:" >&2 + cat "$tmp/err" >&2 + status=1 + elif ! cmp -s "$tmp/in" "$tmp/out"; then + unformatted+=("$file") + fi +done < <(staged '*.rs') + +if [ ${#unformatted[@]} -gt 0 ]; then + echo "pre-commit: these staged Rust files are not formatted:" >&2 + printf ' %s\n' "${unformatted[@]}" >&2 + echo "Run 'cargo fmt --all', then 'git add' them again." >&2 + status=1 +fi + +# ESLint lints files whose working copy matches the index in one run, and each +# partly staged file from its staged blob on stdin. +whole=() +partial=() +while IFS= read -r -d '' file; do + if git diff --quiet -- "$file"; then + whole+=("$file") + else + partial+=("$file") + fi +done < <(staged '*.js' '*.mjs' '*.cjs') + +if [ $((${#whole[@]} + ${#partial[@]})) -gt 0 ]; then + eslint=node_modules/.bin/eslint + if [ ! -x "$eslint" ]; then + echo "pre-commit: ESLint skipped, no node_modules here; run 'pnpm install' to lint staged JavaScript. CI runs 'pnpm lint'." >&2 + else + lint=0 + if [ ${#whole[@]} -gt 0 ]; then + "$eslint" --no-warn-ignored -- "${whole[@]}" >&2 || lint=1 + fi + for file in ${partial[@]+"${partial[@]}"}; do + git show ":$file" | "$eslint" --no-warn-ignored --stdin --stdin-filename "$file" >&2 || lint=1 + done + if [ $lint -ne 0 ]; then + status=1 + echo "Fix what ESLint reports ('pnpm lint' lints everything), then 'git add' the files again." >&2 + fi + fi +fi + +if [ $status -ne 0 ]; then + echo "pre-commit: commit refused. 'git commit --no-verify' skips this hook." >&2 +fi +exit $status diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b00851c..c9090fe 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,6 +27,9 @@ jobs: - run: pnpm lint - run: pnpm test - run: rustup show + - name: Pre-commit hook tests + if: runner.os == 'Linux' + run: python3 -m unittest discover -s scripts -p 'test_git_hooks.py' - if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y bubblewrap - run: cargo fmt --all -- --check diff --git a/docs/develop.md b/docs/develop.md index 439455a..f22ebe3 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -25,6 +25,22 @@ pnpm lint pnpm test ``` +### The pre-commit hook + +A tracked pre-commit hook, `.githooks/pre-commit`, runs fast checks on what you stage. It refuses a commit when a staged Rust file is not formatted as `cargo fmt` would format it, and when a staged JavaScript file (`.js`, `.mjs`, `.cjs`) fails ESLint. It checks the staged copy of each file, not the one in your working tree. When `node_modules` is missing it skips ESLint and says so. It finishes in well under a second. It runs no build, no test suite and no network call. Clippy, the test suites and the runtime test run in CI, as listed above. + +A Claude session installs the hook when it starts, through the `SessionStart` hook in `.claude/settings.json`. Without Claude, install it once per clone from the checkout root: + +```sh +scripts/install-git-hooks.sh +``` + +The script sets `core.hooksPath` to `.githooks`. That setting covers every worktree of the clone, and each worktree runs its own tracked copy of the hook. If `core.hooksPath` already points elsewhere, the script leaves it as it is and says so. To skip the hook for one commit, run `git commit --no-verify`. Its tests are in `scripts/test_git_hooks.py`: + +```sh +python3 -m unittest discover -s scripts -p 'test_git_hooks.py' +``` + To run the Gateway's tests under the filter sandbox on a host that refuses namespaces, run `scripts/filter-sandbox-container.sh`, which needs Docker. It runs the containment test and the runtime test in a container under Docker's default security profile, as the end-to-end workflow's `gateway-filter-sandbox` job does. Its two last steps use a profile with one quirk each: where the host refuses the allow-list, the filter sandbox has to fail at startup by name, and where the kernel has no `close_range`, a grant worker still has to start with no descriptor of the supervisor's. That container has the CI runner's kernel. To run the same two tests on real ECS Fargate 1.4.0, x86-64 and arm64, use the qualification harness, `qualification/fargate/run.sh`. It needs our AWS account, and its [README](https://github.com/zeroae/countersign/blob/main/qualification/fargate/README.md) says how to deploy, run and tear it down. Run it for every release that touches the grant worker. diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh new file mode 100755 index 0000000..49cb278 --- /dev/null +++ b/scripts/install-git-hooks.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# Points this clone at the tracked hooks in .githooks/. core.hooksPath lives in +# the clone's shared config, so one run covers every worktree, and a relative +# path makes each worktree run its own tracked copy of the hooks. +# A Claude session runs this at start (.claude/settings.json). It prints nothing +# when the hooks are already installed, and never replaces another hooks path. +set -euo pipefail + +cd "$(dirname "$0")/.." +git rev-parse --git-dir >/dev/null 2>&1 || exit 0 + +current=$(git config --get core.hooksPath || true) +case "$current" in + .githooks) ;; + "") + git config core.hooksPath .githooks + echo "Installed the pre-commit hook: core.hooksPath is now .githooks." + ;; + *) + echo "core.hooksPath is already '$current', so the pre-commit hook in .githooks/ is not installed. To use it: git config core.hooksPath .githooks" >&2 + ;; +esac diff --git a/scripts/test_git_hooks.py b/scripts/test_git_hooks.py new file mode 100644 index 0000000..42c6c8b --- /dev/null +++ b/scripts/test_git_hooks.py @@ -0,0 +1,194 @@ +"""The tracked pre-commit hook and the session-start command that installs it. + +Each test copies the hook's files into a throwaway repository, so nothing here +touches the checkout's own Git configuration. +""" + +import json +import os +import shutil +import subprocess +import tempfile +import time +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +FILES = [ + ".githooks/pre-commit", + "scripts/install-git-hooks.sh", + ".claude/settings.json", + "rust-toolchain.toml", + "Cargo.toml", + "eslint.config.mjs", +] +UNFORMATTED = "fn main(){let x=1;}\n" +FORMATTED = "fn main() {\n let x = 1;\n}\n" + + +def git_env(extra=None): + env = dict(os.environ) + for key in list(env): + if key.startswith("GIT_"): + del env[key] + env.update( + GIT_CONFIG_GLOBAL=os.devnull, + GIT_CONFIG_NOSYSTEM="1", + GIT_AUTHOR_NAME="Test", + GIT_AUTHOR_EMAIL="test@example.invalid", + GIT_COMMITTER_NAME="Test", + GIT_COMMITTER_EMAIL="test@example.invalid", + ) + env.update(extra or {}) + return env + + +def run(args, cwd, env=None, check=True): + result = subprocess.run( + args, cwd=cwd, env=env or git_env(), capture_output=True, text=True, timeout=60 + ) + if check and result.returncode != 0: + raise AssertionError(f"{args} failed:\n{result.stdout}\n{result.stderr}") + return result + + +def session_start_commands(): + settings = json.loads((ROOT / ".claude/settings.json").read_text()) + return [ + hook["command"] + for entry in settings["hooks"]["SessionStart"] + for hook in entry["hooks"] + if hook["type"] == "command" + ] + + +class GitHooksTests(unittest.TestCase): + def setUp(self): + self.tmp = Path(tempfile.mkdtemp()) + self.addCleanup(shutil.rmtree, self.tmp, ignore_errors=True) + self.main = self.tmp / "main" + self.main.mkdir() + run(["git", "init", "-q", "-b", "main"], self.main) + for name in FILES: + target = self.main / name + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(ROOT / name, target) + run(["git", "add", "-A"], self.main) + run(["git", "commit", "-q", "-m", "init"], self.main) + self.worktree = self.tmp / "fresh" + run(["git", "worktree", "add", "-q", "--detach", str(self.worktree)], self.main) + + def start_session(self, directory): + outputs = [] + for command in session_start_commands(): + result = run( + ["bash", "-c", command], + directory, + env=git_env({"CLAUDE_PROJECT_DIR": str(directory)}), + ) + outputs.append(result.stdout + result.stderr) + return "".join(outputs) + + def commit(self, files, env=None): + for name, text in files.items(): + path = self.worktree / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + run(["git", "add", "--", *files], self.worktree) + return run(["git", "commit", "-q", "-m", "change"], self.worktree, env=env, check=False) + + def test_fresh_worktree_refuses_unformatted_rust_after_session_start(self): + self.start_session(self.worktree) + result = self.commit({"src/lib.rs": UNFORMATTED}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("src/lib.rs", result.stderr) + self.assertIn("cargo fmt", result.stderr) + + def test_hook_checks_the_staged_copy_not_the_working_tree(self): + self.start_session(self.worktree) + (self.worktree / "src").mkdir() + (self.worktree / "src/lib.rs").write_text(UNFORMATTED) + run(["git", "add", "src/lib.rs"], self.worktree) + (self.worktree / "src/lib.rs").write_text(FORMATTED) + result = run(["git", "commit", "-q", "-m", "change"], self.worktree, check=False) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + + def link_node_modules(self): + node_modules = ROOT / "node_modules" + if not (node_modules / ".bin/eslint").exists(): + common = run(["git", "rev-parse", "--path-format=absolute", "--git-common-dir"], ROOT) + node_modules = Path(common.stdout.strip()).parent / "node_modules" + if not (node_modules / ".bin/eslint").exists(): + self.fail("ESLint is not installed: run 'pnpm install' in this checkout") + (self.worktree / "node_modules").symlink_to(node_modules) + + def test_hook_refuses_javascript_that_fails_eslint(self): + self.start_session(self.worktree) + self.link_node_modules() + result = self.commit({"scripts/bad.mjs": "undefinedName();\n"}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("no-undef", result.stderr) + run(["git", "rm", "-q", "--cached", "scripts/bad.mjs"], self.worktree) + self.assertEqual(self.commit({"scripts/good.mjs": "export const x = 1;\n"}).returncode, 0) + + def test_hook_without_node_modules_skips_eslint_and_says_so(self): + self.start_session(self.worktree) + result = self.commit({"scripts/bad.mjs": "undefinedName();\n"}) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("ESLint skipped", result.stderr) + + def test_one_rust_and_one_markdown_file_commit_in_under_five_seconds(self): + self.start_session(self.worktree) + started = time.monotonic() + result = self.commit({"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n\nText.\n"}) + elapsed = time.monotonic() - started + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + print(f"\npre-commit: one .rs and one .md file committed in {elapsed:.2f} s") + self.assertLess(elapsed, 5.0) + + def test_session_start_is_a_no_op_when_already_installed(self): + self.start_session(self.worktree) + config = (self.main / ".git/config").read_text() + self.assertEqual(self.start_session(self.worktree), "") + self.assertEqual((self.main / ".git/config").read_text(), config) + + def test_session_start_leaves_another_hooks_path_alone(self): + run(["git", "config", "core.hooksPath", "/elsewhere"], self.main) + output = self.start_session(self.worktree) + self.assertIn("/elsewhere", output) + hooks_path = run(["git", "config", "core.hooksPath"], self.main).stdout.strip() + self.assertEqual(hooks_path, "/elsewhere") + + def test_hook_runs_no_build_no_test_and_no_network(self): + self.start_session(self.worktree) + shims = self.tmp / "shims" + shims.mkdir() + log = self.tmp / "forbidden.log" + for name in ["cargo", "pnpm", "npm", "npx", "curl", "wget", "python3"]: + shim = shims / name + shim.write_text(f'#!/bin/sh\necho "{name} $*" >> "{log}"\nexit 1\n') + shim.chmod(0o755) + env = git_env({"PATH": f"{shims}{os.pathsep}{os.environ['PATH']}"}) + trace = self.tmp / "trace" + files = {"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n"} + for name, text in files.items(): + path = self.worktree / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + run(["git", "add", "--", *files], self.worktree) + args = ["git", "commit", "-q", "-m", "change"] + if shutil.which("strace"): + args = ["strace", "-f", "-qq", "-e", "trace=connect", "-o", str(trace), *args] + result = run(args, self.worktree, env=env, check=False) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertFalse(log.exists(), log.read_text() if log.exists() else "") + if trace.exists(): + network = [ + line for line in trace.read_text().splitlines() + if "AF_INET" in line + ] + self.assertEqual(network, []) + + +if __name__ == "__main__": + unittest.main() From ac201f25fafa87b75c48ba10e252b1128f487d43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:30:25 -0500 Subject: [PATCH 2/4] fix(repo): The pre-commit hook lints only what pnpm lint lints and hides no existing hook ESLint in the hook now takes the paths the packages' lint scripts give it, so a commit touching tracked JavaScript that pnpm lint never checks is not refused for lint debt CI accepts. The installer leaves core.hooksPath unset when the clone's hooks folder holds hooks of its own, which the setting would stop running. The hook finds the pinned rustfmt once, and names the toolchain to install when it is missing. Refs #31 Co-Authored-By: Claude Opus 5.5 --- .githooks/pre-commit | 97 ++++++++++++++++++++++-------------- docs/develop.md | 4 +- scripts/install-git-hooks.sh | 10 +++- scripts/test_git_hooks.py | 57 +++++++++++++++------ 4 files changed, 112 insertions(+), 56 deletions(-) diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 415ab7a..7a66487 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -1,7 +1,8 @@ #!/usr/bin/env bash # Fast checks on the staged change only: rustfmt on staged Rust files and -# ESLint on staged JavaScript. No build, no test suite and no network call; -# CI runs those (docs/develop.md, "Run the checks"). +# ESLint on the staged JavaScript that `pnpm lint` covers. No build, no test +# suite and no network call: the CI workflow (.github/workflows/ci.yml) runs +# those. # Written for bash 3.2, the bash macOS ships. set -uo pipefail @@ -14,66 +15,86 @@ staged() { git diff --cached --name-only -z --diff-filter=ACMR -- "$@" } -# rustfmt reads each staged blob on stdin, so a file whose working copy differs -# from what is staged is judged by what will be committed. `rustup run` never -# installs a missing toolchain, where the plain proxy would download it. -rustfmt_staged() { +# The rustfmt of the toolchain rust-toolchain.toml pins, found once. `rustup +# which` fails on a toolchain that is not installed, where the rustfmt proxy +# would download it. +find_rustfmt() { if command -v rustup >/dev/null 2>&1; then local channel channel=$(sed -n 's/^channel *= *"\(.*\)"/\1/p' rust-toolchain.toml) - rustup run "$channel" rustfmt "$@" + if ! rustup which --toolchain "$channel" rustfmt 2>/dev/null; then + echo "pre-commit: rustfmt of the pinned toolchain $channel is not installed. Run 'rustup show' in the checkout, which installs it, then commit again." >&2 + return 1 + fi else - rustfmt "$@" + command -v rustfmt || { echo "pre-commit: rustfmt is not installed." >&2; return 1; } fi } -edition=$(sed -n 's/^edition *= *"\(.*\)"/\1/p' Cargo.toml | head -n 1) -unformatted=() +# rustfmt reads each staged blob on stdin, so a file whose working copy differs +# from what is staged is judged by what will be committed. +rust_files=() while IFS= read -r -d '' file; do - git show ":$file" >"$tmp/in" - if ! rustfmt_staged --edition "$edition" --emit stdout <"$tmp/in" >"$tmp/out" 2>"$tmp/err"; then - echo "pre-commit: rustfmt could not check $file:" >&2 - cat "$tmp/err" >&2 - status=1 - elif ! cmp -s "$tmp/in" "$tmp/out"; then - unformatted+=("$file") - fi + rust_files+=("$file") done < <(staged '*.rs') -if [ ${#unformatted[@]} -gt 0 ]; then - echo "pre-commit: these staged Rust files are not formatted:" >&2 - printf ' %s\n' "${unformatted[@]}" >&2 - echo "Run 'cargo fmt --all', then 'git add' them again." >&2 - status=1 +if [ ${#rust_files[@]} -gt 0 ]; then + if ! rustfmt=$(find_rustfmt); then + status=1 + else + edition=$(sed -n 's/^edition *= *"\(.*\)"/\1/p' Cargo.toml | head -n 1) + unformatted=() + for file in "${rust_files[@]}"; do + git show ":$file" >"$tmp/in" + if ! "$rustfmt" --edition "$edition" --emit stdout <"$tmp/in" >"$tmp/out" 2>"$tmp/err"; then + echo "pre-commit: rustfmt could not check $file:" >&2 + cat "$tmp/err" >&2 + status=1 + elif ! cmp -s "$tmp/in" "$tmp/out"; then + unformatted+=("$file") + fi + done + if [ ${#unformatted[@]} -gt 0 ]; then + echo "pre-commit: these staged Rust files are not formatted:" >&2 + printf ' %s\n' "${unformatted[@]}" >&2 + echo "Run 'cargo fmt --all', then 'git add' them again." >&2 + status=1 + fi + fi fi -# ESLint lints files whose working copy matches the index in one run, and each -# partly staged file from its staged blob on stdin. -whole=() -partial=() +# The paths the packages' lint scripts give ESLint, which `pnpm lint` runs. +# Other tracked JavaScript is not lint-clean, so the hook leaves it alone too. +# A file whose working copy matches the index is linted in one run; a partly +# staged file is linted from its staged blob on stdin. +js_whole=() +js_partial=() while IFS= read -r -d '' file; do if git diff --quiet -- "$file"; then - whole+=("$file") + js_whole+=("$file") else - partial+=("$file") + js_partial+=("$file") fi -done < <(staged '*.js' '*.mjs' '*.cjs') +done < <(staged \ + ':(glob)packages/*/src/**/*.js' ':(glob)packages/*/src/**/*.mjs' ':(glob)packages/*/src/**/*.cjs' \ + ':(glob)packages/*/test/**/*.js' ':(glob)packages/*/test/**/*.mjs' ':(glob)packages/*/test/**/*.cjs' \ + ':(glob)examples/demo-integrator/*.js' ':(glob)examples/demo-integrator/site/*.js') -if [ $((${#whole[@]} + ${#partial[@]})) -gt 0 ]; then +if [ $((${#js_whole[@]} + ${#js_partial[@]})) -gt 0 ]; then eslint=node_modules/.bin/eslint if [ ! -x "$eslint" ]; then echo "pre-commit: ESLint skipped, no node_modules here; run 'pnpm install' to lint staged JavaScript. CI runs 'pnpm lint'." >&2 else - lint=0 - if [ ${#whole[@]} -gt 0 ]; then - "$eslint" --no-warn-ignored -- "${whole[@]}" >&2 || lint=1 + eslint_failed=0 + if [ ${#js_whole[@]} -gt 0 ]; then + "$eslint" --no-warn-ignored -- "${js_whole[@]}" >&2 || eslint_failed=1 fi - for file in ${partial[@]+"${partial[@]}"}; do - git show ":$file" | "$eslint" --no-warn-ignored --stdin --stdin-filename "$file" >&2 || lint=1 + for file in ${js_partial[@]+"${js_partial[@]}"}; do + git show ":$file" | "$eslint" --no-warn-ignored --stdin --stdin-filename "$file" >&2 || eslint_failed=1 done - if [ $lint -ne 0 ]; then + if [ $eslint_failed -ne 0 ]; then status=1 - echo "Fix what ESLint reports ('pnpm lint' lints everything), then 'git add' the files again." >&2 + echo "Fix what ESLint reports ('pnpm lint' lints the same files), then 'git add' them again." >&2 fi fi fi diff --git a/docs/develop.md b/docs/develop.md index f22ebe3..324f8a8 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -27,7 +27,7 @@ pnpm test ### The pre-commit hook -A tracked pre-commit hook, `.githooks/pre-commit`, runs fast checks on what you stage. It refuses a commit when a staged Rust file is not formatted as `cargo fmt` would format it, and when a staged JavaScript file (`.js`, `.mjs`, `.cjs`) fails ESLint. It checks the staged copy of each file, not the one in your working tree. When `node_modules` is missing it skips ESLint and says so. It finishes in well under a second. It runs no build, no test suite and no network call. Clippy, the test suites and the runtime test run in CI, as listed above. +A tracked pre-commit hook, `.githooks/pre-commit`, runs fast checks on what you stage. It refuses a commit when a staged Rust file is not formatted as `cargo fmt` would format it, and when a staged JavaScript file that `pnpm lint` covers fails ESLint: the packages' `src` and `test` folders and the demo Integrator. It checks the staged copy of each file, not the one in your working tree. When `node_modules` is missing it skips ESLint and says so. It finishes in well under a second. It runs no build, no test suite and no network call. Clippy, the test suites and the Gateway's runtime test run in the [CI workflow](https://github.com/zeroae/countersign/blob/main/.github/workflows/ci.yml) and the end-to-end workflow. A Claude session installs the hook when it starts, through the `SessionStart` hook in `.claude/settings.json`. Without Claude, install it once per clone from the checkout root: @@ -35,7 +35,7 @@ A Claude session installs the hook when it starts, through the `SessionStart` ho scripts/install-git-hooks.sh ``` -The script sets `core.hooksPath` to `.githooks`. That setting covers every worktree of the clone, and each worktree runs its own tracked copy of the hook. If `core.hooksPath` already points elsewhere, the script leaves it as it is and says so. To skip the hook for one commit, run `git commit --no-verify`. Its tests are in `scripts/test_git_hooks.py`: +The script sets `core.hooksPath` to `.githooks`. That setting covers every worktree of the clone, and each worktree runs its own tracked copy of the hook. If `core.hooksPath` already points elsewhere, or the clone's `.git/hooks` folder holds hooks of its own, which `core.hooksPath` would stop running, the script changes nothing and says so. To skip the hook for one commit, run `git commit --no-verify`. The tests for the hook and the script are in `scripts/test_git_hooks.py`: ```sh python3 -m unittest discover -s scripts -p 'test_git_hooks.py' diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh index 49cb278..d6930b5 100755 --- a/scripts/install-git-hooks.sh +++ b/scripts/install-git-hooks.sh @@ -3,7 +3,9 @@ # the clone's shared config, so one run covers every worktree, and a relative # path makes each worktree run its own tracked copy of the hooks. # A Claude session runs this at start (.claude/settings.json). It prints nothing -# when the hooks are already installed, and never replaces another hooks path. +# when the hooks are already installed. It never replaces another hooks path, +# and never hides hooks already in the clone's hooks folder, which core.hooksPath +# would stop running. set -euo pipefail cd "$(dirname "$0")/.." @@ -13,6 +15,12 @@ current=$(git config --get core.hooksPath || true) case "$current" in .githooks) ;; "") + hooks=$(git rev-parse --path-format=absolute --git-common-dir)/hooks + existing=$(find "$hooks" -maxdepth 1 -type f ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') + if [ -n "$existing" ]; then + echo "$hooks holds hooks (${existing% }) that core.hooksPath would stop running, so the pre-commit hook in .githooks/ is not installed. Move them into .githooks/ or elsewhere, then run scripts/install-git-hooks.sh." >&2 + exit 0 + fi git config core.hooksPath .githooks echo "Installed the pre-commit hook: core.hooksPath is now .githooks." ;; diff --git a/scripts/test_git_hooks.py b/scripts/test_git_hooks.py index 42c6c8b..5f86af2 100644 --- a/scripts/test_git_hooks.py +++ b/scripts/test_git_hooks.py @@ -89,13 +89,17 @@ def start_session(self, directory): outputs.append(result.stdout + result.stderr) return "".join(outputs) - def commit(self, files, env=None): + def stage(self, files): for name, text in files.items(): path = self.worktree / name path.parent.mkdir(parents=True, exist_ok=True) path.write_text(text) run(["git", "add", "--", *files], self.worktree) - return run(["git", "commit", "-q", "-m", "change"], self.worktree, env=env, check=False) + + def commit(self, files, env=None, prefix=()): + self.stage(files) + args = [*prefix, "git", "commit", "-q", "-m", "change"] + return run(args, self.worktree, env=env, check=False) def test_fresh_worktree_refuses_unformatted_rust_after_session_start(self): self.start_session(self.worktree) @@ -125,18 +129,37 @@ def link_node_modules(self): def test_hook_refuses_javascript_that_fails_eslint(self): self.start_session(self.worktree) self.link_node_modules() - result = self.commit({"scripts/bad.mjs": "undefinedName();\n"}) + result = self.commit({"packages/widget/src/bad.js": "undefinedName();\n"}) self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) self.assertIn("no-undef", result.stderr) - run(["git", "rm", "-q", "--cached", "scripts/bad.mjs"], self.worktree) - self.assertEqual(self.commit({"scripts/good.mjs": "export const x = 1;\n"}).returncode, 0) + run(["git", "rm", "-q", "--cached", "packages/widget/src/bad.js"], self.worktree) + good = self.commit({"packages/widget/src/good.js": "export const x = 1;\n"}) + self.assertEqual(good.returncode, 0, good.stdout + good.stderr) + + def test_hook_lints_only_what_pnpm_lint_lints(self): + self.start_session(self.worktree) + self.link_node_modules() + for name in ["distribution/npm/launch.cjs", "scripts/tool.mjs", "crates/x/tests/addon.cjs"]: + with self.subTest(name=name): + result = self.commit({name: "undefinedName();\n"}) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) def test_hook_without_node_modules_skips_eslint_and_says_so(self): self.start_session(self.worktree) - result = self.commit({"scripts/bad.mjs": "undefinedName();\n"}) + result = self.commit({"packages/widget/src/bad.js": "undefinedName();\n"}) self.assertEqual(result.returncode, 0, result.stdout + result.stderr) self.assertIn("ESLint skipped", result.stderr) + def test_hook_names_a_pinned_toolchain_that_is_not_installed(self): + toolchain = self.worktree / "rust-toolchain.toml" + toolchain.write_text(toolchain.read_text().replace("1.99.0", "0.0.1")) + run(["git", "commit", "-q", "-am", "pin a missing toolchain"], self.worktree) + self.start_session(self.worktree) + result = self.commit({"src/lib.rs": FORMATTED}) + self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn("0.0.1", result.stderr) + self.assertIn("rustup show", result.stderr) + def test_one_rust_and_one_markdown_file_commit_in_under_five_seconds(self): self.start_session(self.worktree) started = time.monotonic() @@ -159,6 +182,15 @@ def test_session_start_leaves_another_hooks_path_alone(self): hooks_path = run(["git", "config", "core.hooksPath"], self.main).stdout.strip() self.assertEqual(hooks_path, "/elsewhere") + def test_session_start_leaves_hooks_in_the_hooks_folder_alone(self): + hook = self.main / ".git/hooks/pre-push" + hook.write_text("#!/bin/sh\nexit 0\n") + hook.chmod(0o755) + output = self.start_session(self.worktree) + self.assertIn("pre-push", output) + unset = run(["git", "config", "core.hooksPath"], self.main, check=False) + self.assertEqual(unset.stdout, "") + def test_hook_runs_no_build_no_test_and_no_network(self): self.start_session(self.worktree) shims = self.tmp / "shims" @@ -170,16 +202,11 @@ def test_hook_runs_no_build_no_test_and_no_network(self): shim.chmod(0o755) env = git_env({"PATH": f"{shims}{os.pathsep}{os.environ['PATH']}"}) trace = self.tmp / "trace" - files = {"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n"} - for name, text in files.items(): - path = self.worktree / name - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(text) - run(["git", "add", "--", *files], self.worktree) - args = ["git", "commit", "-q", "-m", "change"] + prefix = () if shutil.which("strace"): - args = ["strace", "-f", "-qq", "-e", "trace=connect", "-o", str(trace), *args] - result = run(args, self.worktree, env=env, check=False) + prefix = ("strace", "-f", "-qq", "-e", "trace=connect", "-o", str(trace)) + files = {"src/lib.rs": FORMATTED, "NOTES.md": "# Notes\n"} + result = self.commit(files, env=env, prefix=prefix) self.assertEqual(result.returncode, 0, result.stdout + result.stderr) self.assertFalse(log.exists(), log.read_text() if log.exists() else "") if trace.exists(): From 5aa85a01e8fc63e0e3cc4e818b457323f7832953 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:32:38 -0500 Subject: [PATCH 3/4] fix(repo): The hook installer also leaves a symlinked hook in the hooks folder running Hook managers often install a hook in .git/hooks as a symlink. The installer's check looked only for regular files, so it set core.hooksPath and stopped such a hook running. Refs #31 Co-Authored-By: Claude Opus 5.5 --- scripts/install-git-hooks.sh | 2 +- scripts/test_git_hooks.py | 22 +++++++++++++++------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh index d6930b5..1ea907a 100755 --- a/scripts/install-git-hooks.sh +++ b/scripts/install-git-hooks.sh @@ -16,7 +16,7 @@ case "$current" in .githooks) ;; "") hooks=$(git rev-parse --path-format=absolute --git-common-dir)/hooks - existing=$(find "$hooks" -maxdepth 1 -type f ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') + existing=$(find "$hooks" -maxdepth 1 ! -type d ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') if [ -n "$existing" ]; then echo "$hooks holds hooks (${existing% }) that core.hooksPath would stop running, so the pre-commit hook in .githooks/ is not installed. Move them into .githooks/ or elsewhere, then run scripts/install-git-hooks.sh." >&2 exit 0 diff --git a/scripts/test_git_hooks.py b/scripts/test_git_hooks.py index 5f86af2..68b98c2 100644 --- a/scripts/test_git_hooks.py +++ b/scripts/test_git_hooks.py @@ -183,13 +183,21 @@ def test_session_start_leaves_another_hooks_path_alone(self): self.assertEqual(hooks_path, "/elsewhere") def test_session_start_leaves_hooks_in_the_hooks_folder_alone(self): - hook = self.main / ".git/hooks/pre-push" - hook.write_text("#!/bin/sh\nexit 0\n") - hook.chmod(0o755) - output = self.start_session(self.worktree) - self.assertIn("pre-push", output) - unset = run(["git", "config", "core.hooksPath"], self.main, check=False) - self.assertEqual(unset.stdout, "") + target = self.tmp / "managed-hook" + target.write_text("#!/bin/sh\nexit 0\n") + target.chmod(0o755) + for kind in ["file", "symlink"]: + with self.subTest(kind=kind): + hook = self.main / ".git/hooks/pre-push" + hook.unlink(missing_ok=True) + if kind == "file": + shutil.copy2(target, hook) + else: + hook.symlink_to(target) + output = self.start_session(self.worktree) + self.assertIn("pre-push", output) + unset = run(["git", "config", "core.hooksPath"], self.main, check=False) + self.assertEqual(unset.stdout, "") def test_hook_runs_no_build_no_test_and_no_network(self): self.start_session(self.worktree) From d57cbefcd7cef0ff0973e4c2d23367653acf1163 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Patrick=20Sodr=C3=A9?= Date: Fri, 20 Nov 2026 02:34:09 -0500 Subject: [PATCH 4/4] fix(repo): The hook installer installs in a clone whose hooks folder is a symlink find does not follow a symlink given as its starting point, so a symlinked .git/hooks was itself reported as a hook and the installer refused. A trailing slash makes find list the folder's contents. Refs #31 Co-Authored-By: Claude Opus 5.5 --- scripts/install-git-hooks.sh | 2 +- scripts/test_git_hooks.py | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/scripts/install-git-hooks.sh b/scripts/install-git-hooks.sh index 1ea907a..489be7a 100755 --- a/scripts/install-git-hooks.sh +++ b/scripts/install-git-hooks.sh @@ -16,7 +16,7 @@ case "$current" in .githooks) ;; "") hooks=$(git rev-parse --path-format=absolute --git-common-dir)/hooks - existing=$(find "$hooks" -maxdepth 1 ! -type d ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') + existing=$(find "$hooks/" -maxdepth 1 ! -type d ! -name '*.sample' -exec basename {} \; 2>/dev/null | sort | tr '\n' ' ') if [ -n "$existing" ]; then echo "$hooks holds hooks (${existing% }) that core.hooksPath would stop running, so the pre-commit hook in .githooks/ is not installed. Move them into .githooks/ or elsewhere, then run scripts/install-git-hooks.sh." >&2 exit 0 diff --git a/scripts/test_git_hooks.py b/scripts/test_git_hooks.py index 68b98c2..19b0c09 100644 --- a/scripts/test_git_hooks.py +++ b/scripts/test_git_hooks.py @@ -199,6 +199,15 @@ def test_session_start_leaves_hooks_in_the_hooks_folder_alone(self): unset = run(["git", "config", "core.hooksPath"], self.main, check=False) self.assertEqual(unset.stdout, "") + def test_session_start_installs_when_the_hooks_folder_is_a_symlink(self): + hooks = self.main / ".git/hooks" + moved = self.tmp / "hooks-folder" + shutil.move(hooks, moved) + hooks.symlink_to(moved) + self.start_session(self.worktree) + hooks_path = run(["git", "config", "core.hooksPath"], self.main).stdout.strip() + self.assertEqual(hooks_path, ".githooks") + def test_hook_runs_no_build_no_test_and_no_network(self): self.start_session(self.worktree) shims = self.tmp / "shims"