From 33bed587e0d10a165b7298e4e14616ad390d1c83 Mon Sep 17 00:00:00 2001 From: Tomasz Feliksik <32515150+tomasz-feliksik@users.noreply.github.com> Date: Sun, 27 Sep 2026 12:38:45 +0200 Subject: [PATCH] Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Accept uutils coreutils timeout in generated hooks The generated hook selects a timeout helper only when its --version banner starts with "timeout (GNU coreutils) ". uutils coreutils reports "timeout (uutils coreutils) " with the same command line and the same exit 124 on expiry, so hosts that ship it (Ubuntu 25.10+, NixOS with uutils-coreutils-noprefix) silently fell through to the Perl alarm, or to the unbounded direct run when Perl is absent. Follow-up from #5522, tracked in #5541. - Widen the identity allowlist to uutils; the match stays by banner so Windows timeout.exe is still never probed (#5503). - Add a backend-selection case using the GNU stub with the uutils banner: fails on the old shim (selects gtimeout), passes with the widening. - Regenerate the managed sections in the tracked .githooks/* so TestTrackedManagedHookSectionsMatchGenerator stays green. - Update the hook-timeout passages in docs/reference/git-integration.md and troubleshooting.md, which described the probe as GNU-only. Verified on NixOS with uutils 0.10.0 as /run/current-system/sw/bin/timeout: with Perl removed from PATH and a bd that hangs, the old shim runs "without timeout" for the full duration; the new shim expires at BEADS_HOOK_TIMEOUT and continues. Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik * Regenerate tracked .githooks managed sections with make githooks-regen TestTrackedManagedHookSectionsMatchGenerator holds the managed section in each tracked .githooks/* byte-equal to the cmd/bd/hooks.go generator, but nothing regenerated them: after a generator change a contributor had to splice the new section in by hand, and the failure only dumped both texts. The v1.2.0 bump reddened main this way (ce20a64bb), and #6561 shipped its first revision with the five hooks stale. - BD_UPDATE_GOLDEN=1 makes the test rewrite the section in place, keeping everything around the markers (the project's own hook logic) untouched. Same switch the package's events golden already uses. - `make githooks-regen` wraps it, next to `corpus-regen`. - The drift failure now names that command. - The exactly-one-section check runs before any rewrite. Verified: drifting one byte inside .githooks/pre-push fails the test with the hint; `make githooks-regen` restores the file to the same blob SHA; the test is green again. Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik * Check the tracked hook shims against real timeout implementations The Go tests pin the shim's helper selection with scripted stand-ins, so they can only encode what the author believes each real `timeout` does. That is where the last two defects lived: uutils prints a banner the allowlist did not know (#5541), and busybox — which #5541 suggests adding — exits 143 on expiry rather than 124, so allowlisting it would turn every deadline into a failed hook and a blocked push. checks.nix adds a flake check that runs the tracked .githooks/* managed sections (held equal to the generator by TestTrackedManagedHookSectionsMatchGenerator) against the binaries themselves: GNU coreutils, uutils, busybox and toybox `timeout`, each with and without perl, under dash, bash and busybox ash, for all five hooks — 150 cases. Expectations come from a model of the contract (the allowlist as data), so widening it is one line here and the binaries either agree or they do not. A fake bd on the shim's restricted PATH blocks on a held-open fifo until a helper kills it, records the signal and re-raises it, so each case asserts the backend that ran (TERM from timeout, ALRM from perl's alarm) and not merely that the shim finished. No clock: a helper that fails to kill the fake trips the harness's own `timeout 10`. Every case asserts exit 0, since anything else blocks the user's push. Reading .githooks/* instead of building bd keeps it at ~1 s and off the Go build's critical path; CI's test-nix job runs it after its existing help-text smoke test. Mutation-checked: restoring main's GNU-only sections fails all 30 uutils cases (15 unbounded, 15 on the perl backend); allowlisting busybox with a loosened probe fails all 30 busybox cases with hook exit 143. Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of Tomasz Feliksik * Run the hook-timeout check under the gtimeout candidate name too The shim probes `timeout` and then `gtimeout`, but the matrix only ever put a binary named `timeout` on PATH, so the second candidate was never run against a real implementation. Whether a helper is accepted under that name depends on what its banner does with argv[0]. Measured: the uutils multicall dispatches on the argv[0] SUFFIX (src/bin/coreutils.rs, `binary_as_util.ends_with(util)`) and then prints the canonical utility name — invoked as gtimeout it reports "timeout (uutils coreutils) 0.8.0" (this flake's nixos-25.11 pin; 0.11.0 identical), which the allowlist accepts. busybox and toybox know no gtimeout applet and fail the probe outright, rejected as before. GNU is immune by construction: Homebrew's gtimeout is a separate binary whose banner is the fixed "timeout (GNU coreutils) 9.11"; nixpkgs' coreutils is a single-binary multicall that refuses a foreign name ("unknown program 'gtimeout'"), so it gets no variant here. Each multicall is now also installed on a case PATH as `gtimeout` ALONE (`installs`, derived from `implementations`; `backendFor` stays keyed on the implementation, so the model's claim is "uutils is allowlisted whatever it is called"). 240 cases on Linux, 80 on darwin (no busybox or toybox there, and no busybox-ash shell). The shadowed `out=` inside run_case is `case_out` now: it only survived because every case is a backgrounded subshell, and a de-backgrounded case would have died on the final `touch "$out"`. Mutation-checked: installing the variant as `xtimeout` (a name the shim never probes) fails exactly the 30 uutils-as-gtimeout cases — 15 with nothing killing the fake bd, 15 on the perl backend (ALRM) instead of coreutils; restored, 240 of 240 pass. The busybox/toybox variants cannot distinguish (their expectation is rejection either way); their weight is that the probe does not blow up on a foreign name. * Run the flake checks on main too, by nix flake check; docs wording pr-risk.yml's test-nix job ran the hook-timeout check on PRs only; the byte-identical job in main.yml never got the step, so post-merge main never ran it. Both jobs now run `nix flake check -L`: no hardcoded `x86_64-linux` (the step beside it, `nix run .#default`, was already system-agnostic), and a check added to checks.nix runs without a workflow edit. checks.aarch64-darwin and .x86_64-darwin evaluate. Measured on ubuntu-latest with a cold Nix store (fork run 35700791032, this tree, 240 cases): `nix flake check -L` 3.6 s including substitution of uutils, busybox, toybox, dash and perl; 0.08 s warm — beside the 4 min 9 s the existing `nix run .#default` step spends building bd in the same job. The 10-minute timeout is not in question. git-integration.md: on Git for Windows the preferred deadline backend is "a coreutils timeout (GNU or uutils)", not GNU alone, since both now qualify. troubleshooting.md: reflow a ragged paragraph. * review: close the duplicated contracts around the uutils timeout accept Maintainer review fixes for #6561. No change to the shim's behavior or to the generated/tracked hook sections. - cmd/bd/hooks_timeout_process_test.go: the uutils fixture was built with strings.Replace, which returns its input unchanged when the pattern is absent, so a later edit to the GNU stub's banner would silently degenerate the uutils case into a second copy of the GNU one — still green, no longer testing the new accept. Hoist the derivation and fail loudly when the banner no longer matches. - cmd/bd/hooks_timeout_process_test.go: findHookProcessGNUTimeout held a second, un-widened copy of the identity allowlist, so on exactly the hosts this PR exists for (uutils timeout, no gtimeout) the only Go test that drives a real timeout binary skipped with a reason the fix had just made false. Widen the probe's case, rename it findHookProcessCoreutilsTimeout, and reword the skip and the subtest. Measured against stub PATHs: uutils goes rc=1 -> rc=0, GNU stays rc=0, a busybox banner stays rc=1. - cmd/bd/init_hooks_test.go: TestGenerateHookSection_Timeout asserted only the GNU alternative, so deleting the new uutils one from the generator left the structural contract green (verified: it passes under that mutation before this change, and reports "section missing uutils coreutils identity check" after). Add the companion assertion. - cmd/bd/init_hooks_test.go, Makefile: the regen arm rewrites tracked source files, so give it its own BD_UPDATE_HOOKS_GOLDEN rather than the package's shared BD_UPDATE_GOLDEN — an unscoped `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/` used to turn genuine hook drift into a silent working-tree rewrite that reported PASS. - cmd/bd/init_hooks_test.go: locate the managed section by marker prefix instead of the versioned marker line. Tracked hooks drift both from generator content and from the release version stamp; the exact-line lookup made the second class fatal ("tracked hook missing ...") before the regen arm was reachable, so `make githooks-regen` failed at exactly the moment a release engineer reaches for it. The versioned markers are still verified — they are part of the byte compare. - checks.nix: the `rc -eq 124` safety-net verdict discarded both $case_out and the already-captured $signal, so the one failure mode that is intermittent and not locally reproducible was also the only one with no diagnostics. Report them like the `rc -ne 0` branch below it. - docs/reference/troubleshooting.md, docs/reference/git-integration.md: mirror the coreutils wording across both docs this PR touches, and generalize the re-install guidance in both. Managed sections are never reported Outdated (getHookVersion returns IsShim for them and computeHookStatuses gates on !IsShim), so nothing tells an existing install it is stale; the sentence was still scoped to the older name-only check (#5503). - CHANGELOG.md: add the [Unreleased] entry for #5541, worded to the actual scope — with Perl installed the shim still reached the Perl alarm arm, so the lost deadline bit uutils hosts without Perl — say that existing installs must run `bd hooks install` once, and drop the claim that stock NixOS ships uutils (this PR's own checks.nix takes GNU from pkgs.coreutils). Co-authored-by: Claude Opus 5 --------- Co-authored-by: Julian Knutsen Co-authored-by: Claude Opus 5 --- .githooks/post-checkout | 2 +- .githooks/post-merge | 2 +- .githooks/pre-commit | 2 +- .githooks/pre-push | 2 +- .githooks/prepare-commit-msg | 2 +- .github/workflows/main.yml | 7 + .github/workflows/pr-risk.yml | 7 + CHANGELOG.md | 16 ++ Makefile | 11 +- checks.nix | 262 +++++++++++++++++++++++++++ cmd/bd/hooks.go | 10 +- cmd/bd/hooks_timeout_process_test.go | 35 +++- cmd/bd/init_hooks_test.go | 57 ++++-- docs/reference/git-integration.md | 25 +-- docs/reference/troubleshooting.md | 22 ++- engdocs/TESTING.md | 1 + flake.nix | 2 + 17 files changed, 417 insertions(+), 48 deletions(-) create mode 100644 checks.nix diff --git a/.githooks/post-checkout b/.githooks/post-checkout index 19d309b87..8806ec466 100755 --- a/.githooks/post-checkout +++ b/.githooks/post-checkout @@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then case "$_bd_timeout_version" in - "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; esac fi fi diff --git a/.githooks/post-merge b/.githooks/post-merge index 4d315045b..f46a0b142 100755 --- a/.githooks/post-merge +++ b/.githooks/post-merge @@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then case "$_bd_timeout_version" in - "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; esac fi fi diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 46e710a33..4cc0d8586 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -60,7 +60,7 @@ if command -v bd >/dev/null 2>&1; then if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then case "$_bd_timeout_version" in - "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; esac fi fi diff --git a/.githooks/pre-push b/.githooks/pre-push index 8bcc2483b..e454f0628 100755 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -59,7 +59,7 @@ if command -v bd >/dev/null 2>&1; then if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then case "$_bd_timeout_version" in - "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; esac fi fi diff --git a/.githooks/prepare-commit-msg b/.githooks/prepare-commit-msg index bf8cfb8ff..2afb7c19c 100755 --- a/.githooks/prepare-commit-msg +++ b/.githooks/prepare-commit-msg @@ -19,7 +19,7 @@ if command -v bd >/dev/null 2>&1; then if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then case "$_bd_timeout_version" in - "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;; esac fi fi diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f2085abad..68181e7ad 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1226,6 +1226,13 @@ jobs: id: nix_help run: | nix run .#default -- --help > help.txt + # Every flake check for the runner's own system (today: hook-timeout- + # backends, checks.nix). `nix flake check` rather than a spelled-out + # `.#checks.x86_64-linux.`: no hardcoded system, and a check added + # to checks.nix is run without a workflow edit. + - name: Run the flake checks + run: | + nix flake check -L - name: Verify help text if: steps.nix_help.outcome == 'success' run: | diff --git a/.github/workflows/pr-risk.yml b/.github/workflows/pr-risk.yml index 4344f7663..778e02920 100644 --- a/.github/workflows/pr-risk.yml +++ b/.github/workflows/pr-risk.yml @@ -431,6 +431,13 @@ jobs: id: nix_help run: | nix run .#default -- --help > help.txt + # Every flake check for the runner's own system (today: hook-timeout- + # backends, checks.nix). `nix flake check` rather than a spelled-out + # `.#checks.x86_64-linux.`: no hardcoded system, and a check added + # to checks.nix is run without a workflow edit. + - name: Run the flake checks + run: | + nix flake check -L - name: Verify help text if: steps.nix_help.outcome == 'success' run: | diff --git a/CHANGELOG.md b/CHANGELOG.md index 81fc50a2a..a90fd937b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 up, but it can flip auto-backup on or off for `-C` invocations whose launch directory and target differ in remote configuration. +- **Generated git hooks accept uutils coreutils `timeout` as a deadline helper** + ([#5541](https://github.com/gastownhall/beads/issues/5541)). The managed hook + section probes `timeout` and `gtimeout` with `--version` and accepted only the + GNU coreutils banner, so a host whose `timeout` is uutils coreutils + (Ubuntu 25.10+, or a distribution configured with `uutils-coreutils` in place + of GNU) failed the probe and fell through. Where Perl was + installed the shim still got a deadline from the Perl `alarm` arm — which Git + for Windows Perl does not guarantee across `exec` — so the missing deadline + bit uutils hosts *without* Perl, which ran `bd hooks run` unbounded (with the + documented warning). The probe now also accepts the + `timeout (uutils coreutils) ` banner; native Windows `timeout.exe` stays + rejected ([#5503](https://github.com/gastownhall/beads/issues/5503)). The + widened probe ships in the generated hook section, which is rewritten only by + `bd hooks install` — hosts that already installed hooks must run it once to + pick up the fix. + - **`bd close` now exits non-zero when any issue in a batch fails to close** ([#6648](https://github.com/gastownhall/beads/issues/6648)). A batch with one refused id used to exit 0 as long as another id closed, so scripts could not diff --git a/Makefile b/Makefile index d08de7468..6ea33d12d 100644 --- a/Makefile +++ b/Makefile @@ -43,7 +43,7 @@ export PATH := $(GIT_WINDOWS_ROOT)/usr/bin;$(PATH) endif endif -.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short +.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen githooks-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short .PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-complexity ci-complexity-diff ci-complexity-check ci-package-mcp ci-package-npm .PHONY: api-gen api-check @@ -288,6 +288,15 @@ corpus-regen: @echo "Regenerating contract corpus..." go test -tags "$(BUILD_TAGS)" ./cmd/bd/protocol -run TestCorpusGolden -corpus.update -count=1 +# The tracked .githooks/* carry the managed section cmd/bd/hooks.go generates; +# TestTrackedManagedHookSectionsMatchGenerator holds them byte-equal. Run this +# after changing the generator or after bumping Version in cmd/bd/version.go +# (the section markers carry the version), then commit the regenerated hooks +# alongside it. +githooks-regen: + @echo "Regenerating managed sections in .githooks/*..." + BD_UPDATE_HOOKS_GOLDEN=1 go test -tags "$(BUILD_TAGS)" ./cmd/bd -run TestTrackedManagedHookSectionsMatchGenerator -count=1 + # Run performance benchmarks against Dolt storage backend # Requires CGO and Dolt; generates CPU profile files diff --git a/checks.nix b/checks.nix new file mode 100644 index 000000000..dac064270 --- /dev/null +++ b/checks.nix @@ -0,0 +1,262 @@ +# Flake checks. Run all with `nix flake check`; one with +# `nix build .#checks.. -L`. +pkgs: +let + inherit (pkgs) lib; + + # hook-timeout-backends: run the tracked hook shims against REAL timeout + # implementations. + # + # cmd/bd/hooks_timeout_process_test.go pins the shim's selection logic with + # scripted helpers, and TestTrackedManagedHookSectionsMatchGenerator holds + # the tracked .githooks/* byte-equal to the generator. This check closes the + # remaining gap — what the helpers on real hosts actually do — by running the + # tracked sections against the binaries themselves. That is where the + # surprises live: uutils prints a different banner (GH#5541); busybox exits + # 143 on expiry, not 124, so allowlisting it as-is would turn every timeout + # into a failed hook; toybox exits 125 from --version. + # + # The matrix is derived from a model of the contract, so a change to the + # allowlist is one line here and the binaries either agree or they do not. + # Reading .githooks/* rather than building bd keeps this at about one + # deadline of wall time and independent of the Go build. + # + # Each case: one hook, one shell (the `sh`s a `#!/usr/bin/env sh` hook meets + # in the wild), a PATH of exactly one timeout implementation — under the + # name `timeout`, or for the multicall ones also under `gtimeout` alone — + # plus optionally perl, BEADS_HOOK_TIMEOUT=1, and a fake `bd` that blocks on a held-open fifo + # until a helper kills it. The fake records the signal that killed it, which + # is how the check asserts the backend and not just "it finished": + # coreutils backend → TERM from timeout, shim reports the deadline, exit 0 + # perl backend → ALRM from perl's alarm, same report, exit 0 + # no backend → the fake returns at once; shim warns it is running + # without a deadline, exit 0 + # A non-zero hook exit blocks the user's push, so every case asserts exit 0. + # No clock is involved: if nothing kills the fake, the harness's own + # `timeout 10` (on its full PATH, not the shim's) fails the case. + + # The identity allowlist in cmd/bd/hooks.go, as data. + allowlisted = [ + "gnu-coreutils" + "uutils-coreutils" + ]; + + implementations = { + gnu-coreutils = pkgs.coreutils; + uutils-coreutils = pkgs.uutils-coreutils-noprefix; + none = null; + } + // lib.optionalAttrs pkgs.stdenv.isLinux { + busybox = pkgs.busybox; + toybox = pkgs.toybox; + }; + + # The shim probes `timeout` first and `gtimeout` second (Homebrew's prefixed + # GNU coreutils on macOS). Whether a helper is accepted under the second name + # depends on what its banner does with argv[0]. The multicall implementations + # dispatch on it and then print the CANONICAL utility name: uutils' + # src/bin/coreutils.rs matches `argv[0].ends_with()`, so `gtimeout` + # (or `mytimeout`) is `timeout` to it and reports "timeout (uutils + # coreutils) " — accepted (measured on 0.8.0, this flake's + # nixos-25.11 pin, and on 0.11.0); busybox and toybox know no `gtimeout` + # applet and fail the probe outright — rejected either way. These variants put each multicall on PATH under the name `gtimeout` + # ONLY, so the second candidate is the one that runs. GNU has no variant: + # nixpkgs' coreutils is a single-binary multicall that refuses a name it does + # not know ("coreutils: unknown program 'gtimeout'"), while Homebrew's + # gtimeout is a separate binary whose banner is the fixed "timeout (GNU + # coreutils) 9.11" — GNU is immune by construction, not by measurement here. + asGtimeout = + impl: pkg: + pkgs.runCommand "${impl}-as-gtimeout" { } '' + mkdir -p "$out/bin" + ln -s ${pkg}/bin/timeout "$out/bin/gtimeout" + ''; + + # What goes on a case's PATH: every implementation as itself, and the + # multicalls once more under the other candidate name. `impl` is what the + # model reasons about; `label` is what the case is called. + installs = lib.concatLists ( + lib.mapAttrsToList ( + impl: pkg: + [ + { + inherit impl; + label = impl; + dirs = lib.optional (pkg != null) "${pkg}/bin"; + } + ] + ++ lib.optional (pkg != null && impl != "gnu-coreutils") { + inherit impl; + label = "${impl}-as-gtimeout"; + dirs = [ "${asGtimeout impl pkg}/bin" ]; + } + ) implementations + ); + + shells = { + dash = "${pkgs.dash}/bin/dash"; + bash = "${pkgs.bash}/bin/bash"; + } + // lib.optionalAttrs pkgs.stdenv.isLinux { + busybox-ash = "${pkgs.busybox}/bin/sh"; + }; + + hooks = [ + "pre-commit" + "post-merge" + "pre-push" + "post-checkout" + "prepare-commit-msg" + ]; + + backendFor = + impl: withPerl: + if lib.elem impl allowlisted then + "coreutils" + else if withPerl then + "perl" + else + "none"; + + # One `run_case` line per point in the matrix, all backgrounded. + cases = lib.concatMap ( + install: + lib.concatMap + ( + withPerl: + lib.concatLists ( + lib.mapAttrsToList ( + shellName: shell: + map (hook: { + name = "${hook}/${shellName}/${install.label}${lib.optionalString withPerl "+perl"}"; + inherit hook shell; + backend = backendFor install.impl withPerl; + path = install.dirs ++ lib.optional withPerl "${pkgs.perl}/bin"; + }) hooks + ) shells + ) + ) + [ + false + true + ] + ) installs; + + caseLine = + c: + "run_case ${ + lib.escapeShellArgs [ + c.name + c.hook + c.backend + c.shell + ] + } ${lib.escapeShellArgs c.path} &\n"; + + trackedHooks = lib.fileset.toSource { + root = ./.; + fileset = ./.githooks; + }; +in +{ + hook-timeout-backends = + pkgs.runCommand "bd-hook-timeout-backends" + { + # Only .githooks/* is an input: nothing else in the repo changes what + # this check measures. + githooks = "${trackedHooks}/.githooks"; + } + '' + # 1. Shims under test: the managed section of each tracked hook, as + # bd installs it into a fresh repo (shebang + section). + shims="$TMPDIR/shims" + mkdir -p "$shims" + for hook in ${lib.escapeShellArgs hooks}; do + { + echo '#!/usr/bin/env sh' + sed -n '/^# --- BEGIN BEADS INTEGRATION/,/^# --- END BEADS INTEGRATION/p' "$githooks/$hook" + } > "$shims/$hook" + grep -q 'bd hooks run' "$shims/$hook" || { echo "no managed section in .githooks/$hook"; exit 1; } + done + + # 2. The fake bd the shim will find on its restricted PATH. It blocks + # until killed and records the signal, re-raising it so it dies the + # way a real bd would (143 / 142), not by a made-up exit code. + fake="$TMPDIR/fakebin" + mkdir -p "$fake" + cat > "$fake/bd" <<'FAKE' + #!/bin/sh + trap 'echo TERM > "$FAKE_BD_SIGNAL"; trap - TERM; kill -TERM $$' TERM + trap 'echo ALRM > "$FAKE_BD_SIGNAL"; trap - ALRM; kill -ALRM $$' ALRM + [ -n "$FAKE_BD_BLOCK" ] && read -r _ + exit 0 + FAKE + chmod +x "$fake/bd" + mkfifo "$TMPDIR/hang" + exec 3<> "$TMPDIR/hang" + + # 3. The matrix. + results="$TMPDIR/results" + mkdir -p "$results" + run_case() { + name=$1 hook=$2 backend=$3 shell=$4 + shift 4 + case_dir="$TMPDIR/cases/$name" + mkdir -p "$case_dir/bin" + ln -s "$shell" "$case_dir/bin/sh" + path="$fake:$case_dir/bin" + for dir in "$@"; do path="$path:$dir"; done + block=1 + [ "$backend" = none ] && block= + signal_file="$case_dir/signal" + # `|| rc=$?`: the builder runs under set -e, and a bare assignment + # from a failing command would end this subshell before it reports. + rc=0 + case_out=$(timeout 10 env PATH="$path" BEADS_HOOK_TIMEOUT=1 \ + FAKE_BD_BLOCK="$block" FAKE_BD_SIGNAL="$signal_file" \ + "$case_dir/bin/sh" "$shims/$hook" origin https://example.invalid 2>&1 <&3) || rc=$? + signal=$(cat "$signal_file" 2>/dev/null || true) + verdict=ok + if [ "$rc" -eq 124 ]; then + # This is the one mode that is intermittent and not reproducible + # locally, so it needs the output most: report it like the branch + # below rather than as a bare string. + verdict="FAIL: nothing killed the fake bd (harness safety net fired), signal='$signal': $case_out" + elif [ "$rc" -ne 0 ]; then + verdict="FAIL: hook exit $rc (would block the push): $case_out" + else + case "$backend" in + coreutils) + case "$case_out" in *"timed out after 1s"*) ;; *) verdict="FAIL: no deadline report: $case_out" ;; esac + [ "$signal" = TERM ] || verdict="FAIL: expected coreutils timeout (TERM), fake saw '$signal'" + ;; + perl) + case "$case_out" in *"timed out after 1s"*) ;; *) verdict="FAIL: no deadline report: $case_out" ;; esac + [ "$signal" = ALRM ] || verdict="FAIL: expected perl alarm (ALRM), fake saw '$signal'" + ;; + none) + case "$case_out" in *"running without timeout"*) ;; *) verdict="FAIL: no unbounded warning: $case_out" ;; esac + ;; + esac + fi + printf '%-52s %-10s %s\n' "$name" "$backend" "$verdict" > "$results/$(echo "$name" | tr / _)" + } + + ${lib.concatMapStrings caseLine cases} + wait + + printf '%-52s %-10s %s\n' CASE BACKEND RESULT + sort "$results"/* + echo + reported=$(ls "$results" | wc -l) + echo "$reported of ${toString (lib.length cases)} cases reported, $(grep -l FAIL "$results"/* | wc -l) failed" + if [ "$reported" -ne ${toString (lib.length cases)} ]; then + echo "some cases never reported a verdict" + exit 1 + fi + if grep -q FAIL "$results"/*; then + exit 1 + fi + touch "$out" + ''; +} diff --git a/cmd/bd/hooks.go b/cmd/bd/hooks.go index be6ca1747..0d59c5cd7 100644 --- a/cmd/bd/hooks.go +++ b/cmd/bd/hooks.go @@ -68,8 +68,14 @@ const hookTimeoutSeconds = 300 // - Helper argv is separated with -- so user input cannot become an option. // - If no compatible helper exists, the direct fallback is explicitly // unbounded rather than silently pretending to enforce a deadline. -// - Only GNU coreutils timeout implementations are selected; Windows +// - Only GNU coreutils timeout and uutils coreutils timeout (same command +// line, same exit 124; GH#5541) are selected, by --version banner; Windows // timeout.exe has the same name but an incompatible command line (GH#5503). +// The banner match holds under the gtimeout candidate too: GNU prints a +// fixed program name (Homebrew's gtimeout reports "timeout (GNU +// coreutils) ..."), and the uutils multicall dispatches on the argv[0] +// suffix and then prints the canonical name ("timeout (uutils coreutils) +// ..." when invoked as gtimeout). checks.nix runs that case. // - If the beads database is not initialized (exit code 3), the hook exits // successfully with a warning so that git operations are not blocked. func generateHookSection(hookName string) string { @@ -93,7 +99,7 @@ func generateHookSection(hookName string) string { " if command -v \"$_bd_timeout_candidate\" >/dev/null 2>&1; then\n" + " if _bd_timeout_version=\"$(\"$_bd_timeout_candidate\" --version 2>/dev/null)\"; then\n" + " case \"$_bd_timeout_version\" in\n" + - " \"timeout (GNU coreutils) \"*) _bd_timeout_command=$_bd_timeout_candidate; break ;;\n" + + " \"timeout (GNU coreutils) \"*|\"timeout (uutils coreutils) \"*) _bd_timeout_command=$_bd_timeout_candidate; break ;;\n" + " esac\n" + " fi\n" + " fi\n" + diff --git a/cmd/bd/hooks_timeout_process_test.go b/cmd/bd/hooks_timeout_process_test.go index 7d636f080..741a8fe0c 100644 --- a/cmd/bd/hooks_timeout_process_test.go +++ b/cmd/bd/hooks_timeout_process_test.go @@ -128,12 +128,22 @@ func TestGeneratedHookTimeoutProcessBoundary(t *testing.T) { t.Run("shell options preserve argv and status", testHookProcessShellOptions) t.Run("POSIX sh preserves argv and status", testHookProcessPOSIXShell) t.Run("reserved statuses are backend scoped", testHookProcessReservedStatuses) - t.Run("real GNU timeout expires a responsive child", testHookProcessRealTimeoutExpiry) + t.Run("real coreutils timeout expires a responsive child", testHookProcessRealTimeoutExpiry) t.Run("real Perl alarm expires a responsive child", testHookProcessRealPerlExpiry) t.Run("Windows checkout rejects System32 timeout", testHookProcessWindowsSystemTimeoutCheckout) } func testHookProcessBackendSelection(t *testing.T) { + // Derive the uutils helper from the GNU stub so the two differ only in the + // banner, but fail loudly if that banner ever moves: strings.Replace returns + // its input unchanged when the pattern is absent, which would silently turn + // the uutils case into a second copy of the GNU one. + const hookProcessGNUTimeoutBanner = "(GNU coreutils) 9.99" + uutilsTimeoutStub := strings.Replace(hookProcessGNUTimeoutStub, hookProcessGNUTimeoutBanner, "(uutils coreutils) 0.10.0", 1) + if uutilsTimeoutStub == hookProcessGNUTimeoutStub { + t.Fatalf("uutils fixture is a copy of the GNU stub: %q not found in hookProcessGNUTimeoutStub", hookProcessGNUTimeoutBanner) + } + tests := []struct { name string fixtures []hookProcessFixture @@ -148,6 +158,14 @@ func testHookProcessBackendSelection(t *testing.T) { }, wantHelper: "helper=gtimeout", }, + { + name: "uutils coreutils timeout is selected like GNU", + fixtures: []hookProcessFixture{ + {name: "timeout", body: uutilsTimeoutStub}, + {name: "gtimeout", body: hookProcessGNUGtimeoutStub}, + }, + wantHelper: "helper=timeout", + }, { name: "nonzero GNU-looking probe yields to gtimeout", fixtures: []hookProcessFixture{ @@ -322,7 +340,7 @@ func testHookProcessReservedStatuses(t *testing.T) { } func testHookProcessRealTimeoutExpiry(t *testing.T) { - helperName, helperDir := findHookProcessGNUTimeout(t) + helperName, helperDir := findHookProcessCoreutilsTimeout(t) timeout := "1" result := runGeneratedHookProcess(t, hookProcessCase{ bdBody: hookProcessLongRunningBDStub, @@ -513,13 +531,18 @@ shift return hookProcessResult{output: string(output), exitCode: exitCode, elapsed: elapsed} } -func findHookProcessGNUTimeout(t *testing.T) (string, string) { +// findHookProcessCoreutilsTimeout mirrors the generated shim's identity +// allowlist (cmd/bd/hooks.go generateHookSection). Keep the `case` here in step +// with the one the generator emits: this is the second copy of that contract, +// and a narrower copy silently skips the only test that drives a real timeout +// binary on exactly the hosts the wider allowlist exists for. +func findHookProcessCoreutilsTimeout(t *testing.T) (string, string) { t.Helper() probe := `for _bd_test_candidate in timeout gtimeout; do if command -v "$_bd_test_candidate" >/dev/null 2>&1 && _bd_test_version="$("$_bd_test_candidate" --version 2>/dev/null)"; then case "$_bd_test_version" in - "timeout (GNU coreutils) "*) + "timeout (GNU coreutils) "*|"timeout (uutils coreutils) "*) _bd_test_path=$(command -v "$_bd_test_candidate") printf '%s\n%s\n' "$_bd_test_candidate" "${_bd_test_path%/*}" exit 0 @@ -533,11 +556,11 @@ exit 1 cmd.Env = hookProcessEnv() output, err := cmd.CombinedOutput() if err != nil { - t.Skipf("compatible GNU timeout is unavailable: %s", strings.TrimSpace(string(output))) + t.Skipf("no compatible coreutils timeout is available: %s", strings.TrimSpace(string(output))) } lines := strings.Split(strings.TrimSpace(string(output)), "\n") if len(lines) != 2 || lines[0] == "" || lines[1] == "" { - t.Fatalf("unexpected GNU timeout probe output: %q", string(output)) + t.Fatalf("unexpected coreutils timeout probe output: %q", string(output)) } return lines[0], lines[1] } diff --git a/cmd/bd/init_hooks_test.go b/cmd/bd/init_hooks_test.go index aec17ea10..c77e7b09b 100644 --- a/cmd/bd/init_hooks_test.go +++ b/cmd/bd/init_hooks_test.go @@ -226,6 +226,9 @@ func TestGenerateHookSection_Timeout(t *testing.T) { if !strings.Contains(section, `"timeout (GNU coreutils) "*`) { t.Error("section missing GNU coreutils identity check") } + if !strings.Contains(section, `"timeout (uutils coreutils) "*`) { + t.Error("section missing uutils coreutils identity check") + } if !strings.Contains(section, `"$_bd_timeout_command" -- "$_bd_timeout"`) { t.Error("section missing GNU timeout argv separator") } @@ -265,23 +268,49 @@ func TestTrackedManagedHookSectionsMatchGenerator(t *testing.T) { } tracked := string(content) - begin := strings.Index(tracked, hookSectionBeginLine()) - if begin < 0 { - t.Fatalf("tracked hook missing %q", hookSectionBeginLine()) - } - endMarker := hookSectionEndLine() + "\n" - relativeEnd := strings.Index(tracked[begin:], endMarker) - if relativeEnd < 0 { - t.Fatalf("tracked hook missing %q", hookSectionEndLine()) - } - end := begin + relativeEnd + len(endMarker) - - if got, want := tracked[begin:end], generateHookSection(hookName); got != want { - t.Fatalf("tracked managed section drifted from generator\nwant:\n%s\ngot:\n%s", want, got) - } if strings.Count(tracked, hookSectionBeginPrefix) != 1 || strings.Count(tracked, hookSectionEndPrefix) != 1 { t.Fatal("tracked hook must contain exactly one managed section") } + // Locate the section by marker PREFIX, not by the versioned marker + // line. Tracked hooks drift for two reasons — generator content and + // the release version stamp — and a prefix scan makes the second one + // ordinary drift that the byte compare below reports and the regen + // arm repairs. Matching hookSectionBeginLine() here would instead + // fail with "missing marker" after a Version bump, before the regen + // arm is reachable. The versioned markers are still verified: they + // are part of `want`. + begin := strings.Index(tracked, hookSectionBeginPrefix) + if begin < 0 { + t.Fatalf("tracked hook missing %q", hookSectionBeginPrefix) + } + relativeEnd := strings.Index(tracked[begin:], hookSectionEndPrefix) + if relativeEnd < 0 { + t.Fatalf("tracked hook missing %q", hookSectionEndPrefix) + } + end := begin + relativeEnd + newline := strings.IndexByte(tracked[end:], '\n') + if newline < 0 { + t.Fatalf("tracked hook %q line is not newline-terminated", hookSectionEndPrefix) + } + end += newline + 1 + got, want := tracked[begin:end], generateHookSection(hookName) + // A dedicated variable, not the package's shared BD_UPDATE_GOLDEN: + // this arm rewrites tracked SOURCE files, so an unscoped + // `BD_UPDATE_GOLDEN=1 go test ./cmd/bd/` must not silently convert + // real hook drift into a working-tree mutation that reports PASS. + if os.Getenv("BD_UPDATE_HOOKS_GOLDEN") == "1" { + if got == want { + return + } + if err := os.WriteFile(path, []byte(tracked[:begin]+want+tracked[end:]), 0o755); err != nil { + t.Fatalf("write tracked hook: %v", err) + } + t.Logf("regenerated managed section in %s", path) + return + } + if got != want { + t.Fatalf("tracked managed section drifted from generator (regenerate with `make githooks-regen`)\nwant:\n%s\ngot:\n%s", want, got) + } }) } } diff --git a/docs/reference/git-integration.md b/docs/reference/git-integration.md index 225bd29c7..9c0bcf70a 100644 --- a/docs/reference/git-integration.md +++ b/docs/reference/git-integration.md @@ -130,12 +130,13 @@ hooks { The hook shim applies a soft deadline to `bd hooks run` when a compatible helper is available. It -uses `timeout` or `gtimeout` only after a successful GNU coreutils identity -probe, avoiding the incompatible `timeout.exe` that native Windows can place -on `PATH`. GNU timeout sends `TERM` at the configured deadline. On POSIX hosts, +uses `timeout` or `gtimeout` only after a successful identity probe for GNU +coreutils or uutils coreutils (same command line, same exit status), avoiding +the incompatible `timeout.exe` that native Windows can place on `PATH`. The +coreutils helper sends `TERM` at the configured deadline. On POSIX hosts, the Perl fallback uses `SIGALRM` on the direct `bd` process at the deadline. -Git for Windows Perl does not guarantee that alarm across `exec`, so GNU -coreutils is the preferred deadline backend there. +Git for Windows Perl does not guarantee that alarm across `exec`, so a +coreutils `timeout` (GNU or uutils) is the preferred deadline backend there. The default deadline is **300 seconds** (5 minutes), which accommodates chained pre-commit pipelines (eslint, prettier, TypeScript compilation). Override it @@ -152,13 +153,15 @@ BEADS_HOOK_TIMEOUT=600 git commit -m "..." The value must be a positive whole number of seconds. Invalid values and zero produce a warning and use the 300-second default. These are soft process deadlines, not process-tree containment: TERM-resistant work or descendants -can outlive them. If neither GNU timeout nor Perl is available, the hook warns -and runs directly without a deadline; that last-resort path can hang until the -hook itself returns. +can outlive them. If neither a coreutils timeout nor Perl is available, the hook +warns and runs directly without a deadline; that last-resort path can hang until +the hook itself returns. -After upgrading from a release whose generated hooks used a name-only timeout -check, run `bd hooks install` once to refresh already-installed canonical hook -sections. Automatic generated-policy adoption is tracked separately. +Already-installed hook sections are not refreshed automatically. After upgrading +to a release that changed the generated timeout probe — the name-only check, or +the uutils coreutils banner — run `bd hooks install` once to refresh +already-installed canonical hook sections. Automatic generated-policy adoption is +tracked separately. When the timeout is reached, beads prints a warning and lets the git operation proceed — the commit or push is not blocked. diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 9308471fb..ae2d37120 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -535,16 +535,20 @@ export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds) The value must be a positive whole number of seconds. Invalid values and zero warn and fall back to 300 seconds. Beads accepts `timeout` or `gtimeout` only -when a successful version probe identifies GNU coreutils; native Windows -`timeout.exe` is not compatible. If neither GNU timeout nor Perl is available, -the hook warns that it is running directly without a deadline. +when a successful version probe identifies GNU coreutils or uutils coreutils; +native Windows `timeout.exe` is not compatible. If neither a coreutils timeout +nor Perl is available, the hook warns that it is running directly without a +deadline. -GNU timeout sends `TERM`; on POSIX hosts, Perl's alarm applies to the direct -`bd` process. Git for Windows Perl does not guarantee that alarm across -`exec`, so GNU coreutils is preferred there. TERM-resistant work and -descendant processes are not guaranteed to stop. After upgrading from a -version with the name-only timeout check, run `bd hooks install` once to -refresh existing canonical sections. +The coreutils helper sends `TERM`; on POSIX hosts, Perl's alarm applies to the +direct `bd` process. Git for Windows Perl does not guarantee that alarm across +`exec`, so a coreutils `timeout` (GNU or uutils) is preferred there. +TERM-resistant work and descendant processes are not guaranteed to stop. + +Already-installed hook sections are not refreshed automatically. After upgrading +to a version that changed the timeout probe — the name-only check, or the uutils +coreutils banner — run `bd hooks install` once to refresh existing canonical +sections. ### Permission denied on git hooks diff --git a/engdocs/TESTING.md b/engdocs/TESTING.md index d26675b14..aba1ea3b6 100644 --- a/engdocs/TESTING.md +++ b/engdocs/TESTING.md @@ -22,6 +22,7 @@ a unit test: use the real boundary when the defect could live there. | Affected-package confidence | `./scripts/test.sh ./path/to/package/...` | After the focused test passes; include directly affected neighbors when their contract changed. | | Final Go baseline | `make test` | Once after focused work on Go code is green. It applies the normal local build flags, coverage, and local skip handling. | | Named CI wrapper | `make ci-pr-core`, `make ci-pr-policy`, or `make ci-pr-lint` | Run the wrapper whose risk or surface is affected, or use it to reproduce that CI check. Do not run all three routinely for every edit. | +| Hook shims against real timeout implementations | `nix flake check -L` (or `nix build .#checks..hook-timeout-backends -L`) | After changing the hook generator in `cmd/bd/hooks.go` (then `make githooks-regen`) or anything under `.githooks/`. Runs the tracked managed sections against GNU coreutils, uutils, busybox and toybox `timeout` — the multicalls also installed as `gtimeout` alone — with and without Perl, under dash, bash and busybox ash. About one deadline of wall time; needs no Go build. | Do not replace the focused loop with repeated full-suite runs. Run the final `make test` once the affected Go tests are green. For docs-only changes, use diff --git a/flake.nix b/flake.nix index 6aa00b09b..60a965a66 100644 --- a/flake.nix +++ b/flake.nix @@ -38,6 +38,8 @@ packages = forAllSystems (import ./packages.nix); + checks = forAllSystems (import ./checks.nix); + apps = nixpkgs.lib.genAttrs systems ( system: rec {