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 {