beads/cmd/bd/hooks.go
Paul Gledhill ad8d6de417
fix(hooks): inject BEADS INTEGRATION above trailing exec block (GH#3537) (#3556)
* fix(hooks): inject BEADS INTEGRATION above trailing exec block (GH#3537)

When bd preserves an existing hook (e.g. .git/hooks/<name> copied into .beads/hooks/<name>) whose tail is an exec-replacing chain, the unconditional bottom-append in injectHookSection landed the BEADS INTEGRATION block below the exec — making it unreachable. The most common case is the hook produced by 'pre-commit init-templatedir', which ends with two exec calls inside an if/elif/else/fi ladder.

Add findExecBlockInjectionPoint that detects the pattern: a final exec line whose only trailing siblings are control-flow closers (fi, else, elif, then), exit, echo, comments, or blank lines. When detected, walk backward past elif/else/then continuations and indented body lines to find the start of the enclosing if-block, then inject the bd section just above it. Otherwise fall back to the existing append-at-end behaviour.

Tests cover: pre-commit's actual hook output, bare trailing exec, exec in middle (must NOT trigger), and a non-exec hook (must keep existing behaviour). New helpers are pure functions with no I/O.

--no-verify used: local pre-commit hook runs golangci-lint without the gms_pure_go build tag CONTRIBUTING.md mandates (ICU headers not installed locally — not a documented requirement). Verified clean with: golangci-lint run --new-from-rev=main --build-tags=gms_pure_go ./cmd/bd/ → 0 issues.

Refs: GH#3537

* test(hooks): cover remaining branches of findExecBlockInjectionPoint helpers

Codecov flagged 91.66% patch coverage on PR #3556. The two uncovered branches in my new code were:

- findExecBlockInjectionPoint:206 — the comment/blank-line skip in the backward-walk loop (no fixture had a comment between the if-opener and the exec line).

- isAllowedAfterExec:252 — the 'elif <args>' / 'else <args>' branch (existing fixtures only hit the bare 'else'/'fi' switch case).

Adds three focused tests: TestInjectHookSection_IfBlockWithCommentInBody (the integration fixture), and table-driven TestIsAllowedAfterExec_TableDriven + TestIsExecLine_TableDriven covering every branch of both helpers. All four functions touched by this PR now report 100% coverage.

* address review nits: doc edge cases + TrimRight + idempotency/double-block tests

Five nits from automated review on PR #3556. The two functional changes:

1. strings.Split off-by-one. Replaced strings.Split(content, '\\n') with strings.Split(strings.TrimRight(content, '\\n'), '\\n') to eliminate the spurious empty trailing element from files that end in newline. The behaviour was correct in practice but the trim makes the intent explicit and removes the off-by-one ambiguity.

2. findExecBlockInjectionPoint godoc. Documented three line-based-heuristic limitations: heredoc bodies containing exec, trailing-comment exec lines (e.g. 'exec /bin/foo  # disabled'), and disjoint exec blocks separated by real code. Each is covered or harmless in practice but worth flagging to future maintainers.

3. New table-driven case 'two disjoint exec blocks, real code after both' — confirms the safe -1 fallback behaviour when the file isn't strictly exec-terminating.

4. New TestInjectHookSection_Idempotent_PrecommitTemplate — runs injectHookSection twice on a pre-commit-templated hook and asserts the output is identical. Locks in the idempotency that the marker logic already provides for free, in case a future refactor moves the strip-and-re-inject path.
2026-04-28 06:40:38 -07:00

1567 lines
55 KiB
Go

package main
import (
"bufio"
"encoding/json"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/config"
"github.com/steveyegge/beads/internal/debug"
"github.com/steveyegge/beads/internal/git"
"github.com/steveyegge/beads/internal/ui"
)
// managedHookNames lists the git hooks managed by beads.
// Hook content is generated dynamically by generateHookSection().
var managedHookNames = []string{"pre-commit", "post-merge", "pre-push", "post-checkout", "prepare-commit-msg"}
const hookVersionPrefix = "# bd-hooks-version: "
const shimVersionPrefix = "# bd-shim "
// inlineHookMarker identifies inline hooks created by bd init (GH#1120)
// These hooks have the logic embedded directly rather than using shims
const inlineHookMarker = "# bd (beads)"
// Section markers for git hooks (GH#1380) — consistent with AGENTS.md pattern.
// Only content between markers is managed by beads; user content outside is preserved.
const hookSectionBeginPrefix = "# --- BEGIN BEADS INTEGRATION"
const hookSectionEndPrefix = "# --- END BEADS INTEGRATION"
// hookSectionBeginLine returns the full begin marker line with the current version.
func hookSectionBeginLine() string {
return fmt.Sprintf("%s v%s ---", hookSectionBeginPrefix, Version)
}
// hookSectionEndLine returns the full end marker line with the current version.
func hookSectionEndLine() string {
return fmt.Sprintf("%s v%s ---", hookSectionEndPrefix, Version)
}
// hookTimeoutSeconds is the maximum time a beads hook is allowed to run before
// being killed and allowing the git operation to proceed. A bounded timeout
// prevents `bd hooks run` from hanging `git push` indefinitely (GH#2453).
// The default is 300 seconds (5 minutes) to accommodate chained hooks — e.g.
// pre-commit framework pipelines that run linters, type-checkers, and builds
// inside `bd hooks run` via the `.old` hook chain (GH#2732).
// The value can be overridden via the BEADS_HOOK_TIMEOUT environment variable.
const hookTimeoutSeconds = 300
// generateHookSection returns the marked section content for a given hook name.
// The section is self-contained: it checks for bd availability, runs the hook
// via 'bd hooks run', and propagates exit codes — without preventing any user
// content after the section from executing on success.
//
// Resilience (GH#2453, GH#2449):
// - A configurable timeout prevents hooks from hanging git operations.
// - 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 {
return hookSectionBeginLine() + "\n" +
"# This section is managed by beads. Do not remove these markers.\n" +
"if command -v bd >/dev/null 2>&1; then\n" +
" export BD_GIT_HOOK=1\n" +
" _bd_timeout=${BEADS_HOOK_TIMEOUT:-" + fmt.Sprintf("%d", hookTimeoutSeconds) + "}\n" +
" if command -v timeout >/dev/null 2>&1; then\n" +
" timeout \"$_bd_timeout\" bd hooks run " + hookName + " \"$@\"\n" +
" _bd_exit=$?\n" +
" if [ $_bd_exit -eq 124 ]; then\n" +
" echo >&2 \"beads: hook '" + hookName + "' timed out after ${_bd_timeout}s — continuing without beads\"\n" +
" _bd_exit=0\n" +
" fi\n" +
" else\n" +
" bd hooks run " + hookName + " \"$@\"\n" +
" _bd_exit=$?\n" +
" fi\n" +
" if [ $_bd_exit -eq 3 ]; then\n" +
" echo >&2 \"beads: database not initialized — skipping hook '" + hookName + "'\"\n" +
" _bd_exit=0\n" +
" fi\n" +
" if [ $_bd_exit -ne 0 ]; then exit $_bd_exit; fi\n" +
"fi\n" +
hookSectionEndLine() + "\n"
}
// injectHookSection merges the beads section into existing hook file content.
// If section markers are found, only the content between them is replaced.
// If broken markers exist (orphaned BEGIN, reversed order), the stale markers
// are removed before injecting the new section.
// If no markers are found, the section is appended.
func injectHookSection(existing, section string) string {
return injectHookSectionWithDepth(existing, section, 0)
}
// maxInjectDepth guards against infinite recursion when cleaning broken markers.
const maxInjectDepth = 5
func injectHookSectionWithDepth(existing, section string, depth int) string {
if depth > maxInjectDepth {
// Safety: too many recursive cleanups — append as fallback
result := existing
if !strings.HasSuffix(result, "\n") {
result += "\n"
}
return result + "\n" + section
}
beginIdx := strings.Index(existing, hookSectionBeginPrefix)
endIdx := strings.Index(existing, hookSectionEndPrefix)
if beginIdx != -1 && endIdx != -1 && beginIdx < endIdx {
// Case 1: valid BEGIN...END pair — replace between markers
lineStart := strings.LastIndex(existing[:beginIdx], "\n")
if lineStart == -1 {
lineStart = 0
} else {
lineStart++ // skip the newline itself
}
// Find end of the end-marker line (including trailing newline)
endOfEndMarker := endIdx + len(hookSectionEndPrefix)
// Consume the rest of the end-marker line (e.g. " v0.58.0 ---\n")
restAfterPrefix := existing[endOfEndMarker:]
if nlIdx := strings.Index(restAfterPrefix, "\n"); nlIdx != -1 {
endOfEndMarker += nlIdx + 1
} else {
endOfEndMarker = len(existing)
}
return existing[:lineStart] + section + existing[endOfEndMarker:]
} else if beginIdx != -1 {
// Case 2: broken markers — orphaned BEGIN (no END) or reversed (END before BEGIN).
// Remove the orphaned/stale block, then recurse to handle remaining markers.
cleaned := removeOrphanedBeginBlock(existing, beginIdx)
return injectHookSectionWithDepth(cleaned, section, depth+1)
} else if endIdx != -1 {
// Case 2b: orphaned END without BEGIN — remove the stale END line
cleaned := removeMarkerLine(existing, endIdx, hookSectionEndPrefix)
return injectHookSectionWithDepth(cleaned, section, depth+1)
}
// Case 3: no markers. If the existing hook ends in an exec-replacing
// block (e.g. the templated hook produced by `pre-commit init-templatedir`,
// which ends with `exec "$INSTALL_PYTHON" -mpre_commit ...`), appending
// at the bottom would make the bd section unreachable. Detect that
// pattern and inject above the exec block instead. (GH#3537)
if injectAt := findExecBlockInjectionPoint(existing); injectAt >= 0 {
return existing[:injectAt] + section + "\n" + existing[injectAt:]
}
// Case 3 fallback: no markers, no trailing exec — append at end.
result := existing
if !strings.HasSuffix(result, "\n") {
result += "\n"
}
result += "\n" + section
return result
}
// findExecBlockInjectionPoint inspects the tail of a hook file. If it ends in
// an exec-replacing chain (a final `exec <cmd>` reachable from the bottom of
// the file, possibly inside an `if`/`elif`/`else`/`fi` ladder whose other
// branches only `echo`/`exit`), returns the byte offset where the bd section
// should be injected — i.e. just above the start of the enclosing control
// structure (or above the bare `exec` line if there is none). Returns -1 when
// the file does not end in such a pattern; callers should fall back to
// appending at the bottom.
//
// Motivation: appending below a terminating `exec` makes the appended content
// unreachable, because `exec` replaces the running shell process. (GH#3537)
//
// Limitations (the function uses line-based heuristics, not a shell parser):
// - A heredoc body containing a literal line that starts with `exec` is
// treated as code, not data. In practice this is harmless because the
// terminator line (e.g. `EOF`) is then classified as non-filler and the
// scan returns -1, but a contrived terminator name could fool it.
// - A trailing comment on an `exec` line (e.g. `exec /bin/foo # disabled`)
// is treated as a live `exec` statement. Use a separate comment line if
// intent is to disable it.
// - Two disjoint `if/exec` blocks separated by real code: the scan only
// considers the LAST one; the real code in the middle correctly causes
// the scan to return -1 and the caller falls back to append.
func findExecBlockInjectionPoint(content string) int {
// Trim a trailing newline so strings.Split doesn't produce an empty
// sentinel as the last element. The scan then sees lines exactly as
// they appear in the file with no off-by-one ambiguity.
lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
// 1. Find the last line that is an effective `exec ...` statement.
// Skip blank lines, comments, and the standard tail patterns
// (`fi`, `else`, `elif`, `exit N`, `echo ...`) when scanning back.
lastExecLine := -1
for i := len(lines) - 1; i >= 0; i-- {
trimmed := strings.TrimSpace(lines[i])
if isExecLine(trimmed) {
lastExecLine = i
break
}
if !isAllowedAfterExec(trimmed) {
// Found non-trivial code at the tail that isn't part of an
// exec-terminated chain — not a pattern we should rewrite.
return -1
}
}
if lastExecLine == -1 {
return -1
}
// 2. Walk backward from lastExecLine to find the start of the enclosing
// control structure (an `if ...` at column 0, possibly preceded by
// elif/else/then continuations of the same block). If we don't find
// one, treat the exec line itself as the injection target.
blockStartLine := lastExecLine
for i := lastExecLine - 1; i >= 0; i-- {
line := lines[i]
trimmed := strings.TrimSpace(line)
if trimmed == "" || strings.HasPrefix(trimmed, "#") {
continue
}
// Skip continuations of the if-block we're inside: elif/else/then,
// and any indented body line (they belong to the surrounding block).
if strings.HasPrefix(trimmed, "elif ") || trimmed == "else" ||
strings.HasPrefix(trimmed, "else ") || trimmed == "then" {
continue
}
if line != trimmed { // indented body of an enclosing block
continue
}
// Column-0 line that isn't a continuation. If it opens an if-block,
// that's the start of our construct.
if strings.HasPrefix(trimmed, "if ") {
blockStartLine = i
}
break
}
// 3. Convert blockStartLine -> byte offset.
offset := 0
for i := 0; i < blockStartLine; i++ {
offset += len(lines[i]) + 1 // +1 for the '\n' that strings.Split removed
}
return offset
}
// isExecLine reports whether trimmed is an effective `exec <cmd>` statement.
func isExecLine(trimmed string) bool {
return trimmed == "exec" || strings.HasPrefix(trimmed, "exec ") ||
strings.HasPrefix(trimmed, "exec\t")
}
// isAllowedAfterExec reports whether a trailing line in an exec-terminated
// chain is harmless filler — control-flow closers, alternative branches,
// fallback exits, comments, and blanks. Anything else means the file does
// not strictly terminate via exec, so we should not rewrite it.
func isAllowedAfterExec(trimmed string) bool {
if trimmed == "" || strings.HasPrefix(trimmed, "#") {
return true
}
switch trimmed {
case "fi", "else", "done", "esac", "}", ";;":
return true
}
if strings.HasPrefix(trimmed, "elif ") || strings.HasPrefix(trimmed, "else ") {
return true
}
if strings.HasPrefix(trimmed, "exit") {
return true
}
if strings.HasPrefix(trimmed, "echo ") || strings.HasPrefix(trimmed, "echo\t") {
// pre-commit's else branch prints a hint before exit 1.
return true
}
return false
}
// removeOrphanedBeginBlock removes an orphaned BEGIN block starting at beginIdx.
// Scans forward from the BEGIN line to the next blank line, next BEGIN marker, or EOF.
func removeOrphanedBeginBlock(content string, beginIdx int) string {
lineStart := strings.LastIndex(content[:beginIdx], "\n")
if lineStart == -1 {
lineStart = 0
} else {
lineStart++ // skip the newline itself
}
afterBegin := content[beginIdx:]
blockEnd := len(content)
lines := strings.SplitAfter(afterBegin, "\n")
scanned := beginIdx
for i, line := range lines {
if i == 0 {
// Skip the BEGIN line itself
scanned += len(line)
continue
}
trimmed := strings.TrimSpace(line)
if trimmed == "" {
// Blank line — end of orphaned block (include the blank line)
blockEnd = scanned + len(line)
break
}
if strings.Contains(line, hookSectionBeginPrefix) {
// Next BEGIN marker — end before this line
blockEnd = scanned
break
}
scanned += len(line)
}
return content[:lineStart] + content[blockEnd:]
}
// removeMarkerLine removes a single marker line from content.
func removeMarkerLine(content string, markerIdx int, markerPrefix string) string {
lineStart := strings.LastIndex(content[:markerIdx], "\n")
if lineStart == -1 {
lineStart = 0
} else {
lineStart++ // skip the newline itself
}
lineEnd := markerIdx + len(markerPrefix)
restAfterPrefix := content[lineEnd:]
if nlIdx := strings.Index(restAfterPrefix, "\n"); nlIdx != -1 {
lineEnd += nlIdx + 1
} else {
lineEnd = len(content)
}
return content[:lineStart] + content[lineEnd:]
}
// removeHookSection removes only the beads section from hook file content.
// Returns the content with the section removed, and true if a section was found.
// Handles valid BEGIN...END pairs, orphaned BEGIN, orphaned END, and reversed markers.
func removeHookSection(content string) (string, bool) {
beginIdx := strings.Index(content, hookSectionBeginPrefix)
endIdx := strings.Index(content, hookSectionEndPrefix)
if beginIdx == -1 && endIdx == -1 {
return content, false
}
if beginIdx != -1 && endIdx != -1 && beginIdx < endIdx {
// Valid BEGIN...END pair — remove the whole section
lineStart := strings.LastIndex(content[:beginIdx], "\n")
if lineStart == -1 {
lineStart = 0
} else {
lineStart++
}
endOfSection := endIdx + len(hookSectionEndPrefix)
restAfterPrefix := content[endOfSection:]
if nlIdx := strings.Index(restAfterPrefix, "\n"); nlIdx != -1 {
endOfSection += nlIdx + 1
} else {
endOfSection = len(content)
}
// Also consume a blank line before the section if present
if lineStart >= 2 && content[lineStart-1] == '\n' && content[lineStart-2] == '\n' {
lineStart--
}
return content[:lineStart] + content[endOfSection:], true
}
// Broken markers: orphaned BEGIN, orphaned END, or reversed order.
// Remove whichever markers exist.
result := content
if beginIdx != -1 {
result = removeOrphanedBeginBlock(result, strings.Index(result, hookSectionBeginPrefix))
}
if endIdx != -1 {
// Re-find END index in the (possibly modified) result
if newEndIdx := strings.Index(result, hookSectionEndPrefix); newEndIdx != -1 {
result = removeMarkerLine(result, newEndIdx, hookSectionEndPrefix)
}
}
// Trim trailing blank lines that may be left from removal
for strings.HasSuffix(result, "\n\n\n") {
result = result[:len(result)-1]
}
return result, true
}
// isOnlyShebangOrEmpty reports whether the given hook content consists of
// nothing meaningful — only an optional shebang line plus blank lines and
// comments. Used by shouldPreserveHookContent to decide, after stripping a
// BEADS INTEGRATION block, whether anything user-owned remains worth
// preserving.
//
// Note: non-shebang comment lines (e.g. `# preamble`) are intentionally
// treated as non-content. A file that's only a shebang plus a comment is
// classified empty and skipped — comments alone aren't user logic worth
// carrying forward to .beads/hooks/<name>. (GH#3536)
func isOnlyShebangOrEmpty(content string) bool {
for _, line := range strings.Split(content, "\n") {
trimmed := strings.TrimSpace(line)
if trimmed == "" || strings.HasPrefix(trimmed, "#!") || strings.HasPrefix(trimmed, "#") {
continue
}
return false
}
return true
}
// shouldPreserveHookContent decides what preservePreexistingHooks should do
// with one hook file's content. Returns (transformedContent, true) when the
// file should be preserved into the target directory (possibly with the bd
// section stripped or the husky helper-layout sanitized); returns
// ("", false) when preservation should skip this file because it's wholly
// bd-managed and contains nothing user-owned worth keeping.
//
// Decision rules (GH#3536):
// - inlineHookMarker (the "# bd (beads)" tag from GH#1120) marks files
// that were always wholly bd-owned one-liners — skip.
// - hookSectionBeginPrefix marks files that were *user-owned* with bd's
// block injected into them (the v0.49+ section-marker model). Strip
// the bd block and preserve the remaining user content. If only a
// shebang/blank/comments remain, treat as wholly bd-owned and skip.
// - When fromHusky is true, sanitize the (possibly stripped) content so
// it doesn't depend on husky's helper-layout being mirrored into the
// target directory (GH#3132).
//
// The function is pure: no I/O, no global state.
func shouldPreserveHookContent(content string, fromHusky bool) (string, bool) {
if strings.Contains(content, inlineHookMarker) {
return "", false
}
if strings.Contains(content, hookSectionBeginPrefix) {
stripped, _ := removeHookSection(content)
if isOnlyShebangOrEmpty(stripped) {
return "", false
}
// Normalize CRLF → LF on the preserved-and-stripped content so
// Windows / autocrlf=true repos don't end up with `\r\n` line
// endings in .beads/hooks/<name>. Mirrors the normalization that
// injectHookSection does on its output (`hooks.go` ~line 622).
content = strings.ReplaceAll(stripped, "\r\n", "\n")
}
if fromHusky {
content = sanitizeHuskyHook(content)
}
return content, true
}
// HookStatus represents the status of a single git hook
type HookStatus struct {
Name string
Installed bool
Version string
IsShim bool // true if this is a thin shim (version-agnostic)
Outdated bool
}
// CheckGitHooks checks the status of bd git hooks in .git/hooks/
func CheckGitHooks() []HookStatus {
hooks := []string{"pre-commit", "post-merge", "pre-push", "post-checkout", "prepare-commit-msg"}
statuses := make([]HookStatus, 0, len(hooks))
// Get hooks directory from common git dir (hooks are shared across worktrees)
hooksDir, err := git.GetGitHooksDir()
if err != nil {
// Not a git repo - return all hooks as not installed
for _, hookName := range hooks {
statuses = append(statuses, HookStatus{Name: hookName, Installed: false})
}
return statuses
}
for _, hookName := range hooks {
status := HookStatus{
Name: hookName,
}
// Check if hook exists
hookPath := filepath.Join(hooksDir, hookName)
versionInfo, err := getHookVersion(hookPath)
if err != nil {
// Hook doesn't exist or couldn't be read
status.Installed = false
} else {
status.Installed = true
status.Version = versionInfo.Version
status.IsShim = versionInfo.IsShim
// Thin shims are never outdated (they delegate to bd)
// bd hooks are outdated if version is missing (legacy inline) or differs
if !versionInfo.IsShim && versionInfo.IsBdHook && versionInfo.Version != Version {
status.Outdated = true
}
}
statuses = append(statuses, status)
}
return statuses
}
// hookVersionInfo contains version information extracted from a hook file
type hookVersionInfo struct {
Version string // bd version (for legacy hooks) or shim version
IsShim bool // true if this is a thin shim
IsBdHook bool // true if this is any type of bd hook (shim or inline)
}
// getHookVersion extracts the version from a hook file
func getHookVersion(path string) (hookVersionInfo, error) {
// #nosec G304 -- hook path constrained to .git/hooks directory
file, err := os.Open(path)
if err != nil {
return hookVersionInfo{}, err
}
defer file.Close()
scanner := bufio.NewScanner(file)
// Read the entire file to support section markers anywhere (GH#1380)
var content strings.Builder
for scanner.Scan() {
line := scanner.Text()
content.WriteString(line)
content.WriteString("\n")
// Check for section marker (GH#1380) — can appear anywhere in the file
if strings.HasPrefix(line, hookSectionBeginPrefix) {
// Extract version from "# --- BEGIN BEADS INTEGRATION v0.56.1 ---"
after := strings.TrimPrefix(line, hookSectionBeginPrefix)
after = strings.TrimSpace(after)
after = strings.TrimPrefix(after, "v")
after = strings.TrimSuffix(after, "---")
version := strings.TrimSpace(after)
return hookVersionInfo{Version: version, IsShim: true, IsBdHook: true}, nil
}
// Check for thin shim marker first
if strings.HasPrefix(line, shimVersionPrefix) {
version := strings.TrimSpace(strings.TrimPrefix(line, shimVersionPrefix))
return hookVersionInfo{Version: version, IsShim: true, IsBdHook: true}, nil
}
// Check for legacy version marker
if strings.HasPrefix(line, hookVersionPrefix) {
version := strings.TrimSpace(strings.TrimPrefix(line, hookVersionPrefix))
return hookVersionInfo{Version: version, IsShim: false, IsBdHook: true}, nil
}
}
if err := scanner.Err(); err != nil {
return hookVersionInfo{}, fmt.Errorf("reading hook file: %w", err)
}
// Check if it's an inline bd hook (from bd init) - GH#1120
// These don't have version markers but have "# bd (beads)" comment
if strings.Contains(content.String(), inlineHookMarker) {
return hookVersionInfo{IsBdHook: true}, nil
}
// No version found and not a bd hook
return hookVersionInfo{}, nil
}
// FormatHookWarnings returns a formatted warning message if hooks are outdated
func FormatHookWarnings(statuses []HookStatus) string {
var warnings []string
missingCount := 0
outdatedCount := 0
for _, status := range statuses {
if !status.Installed {
missingCount++
} else if status.Outdated {
outdatedCount++
}
}
if missingCount > 0 {
warnings = append(warnings, fmt.Sprintf("⚠️ Git hooks not installed (%d missing)", missingCount))
warnings = append(warnings, " Run: bd hooks install")
}
if outdatedCount > 0 {
warnings = append(warnings, fmt.Sprintf("⚠️ Git hooks are outdated (%d hooks)", outdatedCount))
warnings = append(warnings, " Run: bd hooks install")
}
if len(warnings) > 0 {
return strings.Join(warnings, "\n")
}
return ""
}
// Cobra commands
var hooksCmd = &cobra.Command{
Use: "hooks",
GroupID: "setup",
Short: "Manage git hooks for beads integration",
Long: `Install, uninstall, or list git hooks for beads integration.
The hooks provide:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics`,
}
var hooksInstallCmd = &cobra.Command{
Use: "install",
Short: "Install bd git hooks",
Long: `Install git hooks for beads integration.
By default, hooks are installed to .git/hooks/ in the current repository.
Use --beads to install to .beads/hooks/ (recommended for Dolt backend).
Use --shared to install to a versioned directory (.beads-hooks/) that can be
committed to git and shared with team members.
Hooks use section markers to coexist with existing hooks — any user content
outside the markers is preserved across installs and upgrades.
Installed hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers (for orchestrator agents)`,
Run: func(cmd *cobra.Command, args []string) {
force, _ := cmd.Flags().GetBool("force")
shared, _ := cmd.Flags().GetBool("shared")
chain, _ := cmd.Flags().GetBool("chain")
beadsHooks, _ := cmd.Flags().GetBool("beads")
if err := installHooksWithOptions(managedHookNames, force, shared, chain, beadsHooks); err != nil {
FatalErrorRespectJSON("installing hooks: %v", err)
}
if jsonOutput {
output := map[string]interface{}{
"success": true,
"message": "Git hooks installed successfully",
"shared": shared,
"chained": chain,
"beadsHooks": beadsHooks,
}
jsonBytes, _ := json.MarshalIndent(output, "", " ")
fmt.Println(string(jsonBytes))
} else {
fmt.Println("✓ Git hooks installed successfully")
fmt.Println()
if beadsHooks {
fmt.Println("Hooks installed to: .beads/hooks/")
fmt.Println("Git config set: core.hooksPath=.beads/hooks")
fmt.Println()
} else if shared {
fmt.Println("Hooks installed to: .beads-hooks/")
fmt.Println("Git config set: core.hooksPath=.beads-hooks")
fmt.Println()
fmt.Println("⚠️ Remember to commit .beads-hooks/ to share with your team!")
fmt.Println()
}
fmt.Println("Installed hooks:")
for _, hookName := range managedHookNames {
fmt.Printf(" - %s\n", hookName)
}
}
},
}
var hooksUninstallCmd = &cobra.Command{
Use: "uninstall",
Short: "Uninstall bd git hooks",
Long: `Remove bd git hooks from .git/hooks/ directory.`,
Run: func(cmd *cobra.Command, args []string) {
if err := uninstallHooks(); err != nil {
FatalErrorRespectJSON("uninstalling hooks: %v", err)
}
if jsonOutput {
output := map[string]interface{}{
"success": true,
"message": "Git hooks uninstalled successfully",
}
jsonBytes, _ := json.MarshalIndent(output, "", " ")
fmt.Println(string(jsonBytes))
} else {
fmt.Println("✓ Git hooks uninstalled successfully")
}
},
}
var hooksListCmd = &cobra.Command{
Use: "list",
Short: "List installed git hooks status",
Long: `Show the status of bd git hooks (installed, outdated, missing).`,
Run: func(cmd *cobra.Command, args []string) {
statuses := CheckGitHooks()
if jsonOutput {
output := map[string]interface{}{
"hooks": statuses,
}
jsonBytes, _ := json.MarshalIndent(output, "", " ")
fmt.Println(string(jsonBytes))
} else {
fmt.Println("Git hooks status:")
for _, status := range statuses {
if !status.Installed {
fmt.Printf(" ✗ %s: not installed\n", status.Name)
} else if status.IsShim {
fmt.Printf(" ✓ %s: installed (shim %s)\n", status.Name, status.Version)
} else if status.Outdated {
fmt.Printf(" ⚠ %s: installed (version %s, current: %s) - outdated\n",
status.Name, status.Version, Version)
} else {
fmt.Printf(" ✓ %s: installed (version %s)\n", status.Name, status.Version)
}
}
}
},
}
//nolint:unparam // force and chain kept for CLI flag compatibility; section markers make them no-ops
func installHooksWithOptions(hookNames []string, force bool, shared bool, chain bool, beadsHooks bool) error {
var hooksDir string
if beadsHooks {
// Use .beads/hooks/ directory (preferred for Dolt backend)
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return fmt.Errorf("%s", activeWorkspaceNotFoundError())
}
hooksDir = filepath.Join(beadsDir, "hooks")
} else if shared {
// Use versioned directory for shared hooks
if mainRoot, err := git.GetMainRepoRoot(); err == nil && mainRoot != "" {
hooksDir = filepath.Join(mainRoot, ".beads-hooks")
} else {
hooksDir = ".beads-hooks"
}
} else {
// Use common git directory for hooks (shared across worktrees)
var err error
hooksDir, err = git.GetGitHooksDir()
if err != nil {
return err
}
}
// Create hooks directory if it doesn't exist
if err := os.MkdirAll(hooksDir, 0755); err != nil {
return fmt.Errorf("failed to create hooks directory: %w", err)
}
// When setting a local core.hooksPath (beads or shared mode), preserve any
// hooks from the previously effective hooks directory (e.g. a global
// core.hooksPath or the default .git/hooks). Without this, setting a local
// core.hooksPath silently shadows the global one and those hooks stop running.
if beadsHooks || shared {
preservePreexistingHooks(hooksDir)
}
// Install each hook using section markers (GH#1380).
// Only the content between markers is managed by beads; user content
// outside the markers is preserved across reinstalls and upgrades.
for _, hookName := range hookNames {
hookPath := filepath.Join(hooksDir, hookName)
section := generateHookSection(hookName)
// Read existing hook file (if any)
// #nosec G304 -- hook path constrained to hooks directory
existing, readErr := os.ReadFile(hookPath)
if readErr != nil && !os.IsNotExist(readErr) {
return fmt.Errorf("failed to read %s: %w", hookName, readErr)
}
var newContent string
if os.IsNotExist(readErr) {
// No existing file — create with shebang + section
newContent = "#!/usr/bin/env sh\n" + section
} else {
existingStr := string(existing)
// Check if file already has section markers
if strings.Contains(existingStr, hookSectionBeginPrefix) {
// Update only the section between markers
newContent = injectHookSection(existingStr, section)
} else {
// Check if this is a legacy bd hook (shim or inline)
versionInfo, _ := getHookVersion(hookPath)
if versionInfo.IsBdHook {
// Legacy bd hook — replace entire file with section format
newContent = "#!/usr/bin/env sh\n" + section
} else {
// Non-bd hook — inject section (preserving existing content)
newContent = injectHookSection(existingStr, section)
}
}
}
// Normalize line endings to LF
newContent = strings.ReplaceAll(newContent, "\r\n", "\n")
// Write hook file
// #nosec G306 -- git hooks must be executable for Git to run them
if err := os.WriteFile(hookPath, []byte(newContent), 0755); err != nil {
return fmt.Errorf("failed to write %s: %w", hookName, err)
}
}
// Configure git to use the hooks directory
if beadsHooks {
if err := configureBeadsHooksPath(); err != nil {
return fmt.Errorf("failed to configure git hooks path: %w", err)
}
} else if shared {
if err := configureSharedHooksPath(); err != nil {
return fmt.Errorf("failed to configure git hooks path: %w", err)
}
}
return nil
}
// preservePreexistingHooks copies non-beads hooks from the currently effective
// hooks directory into targetDir. This prevents hooks from a global
// core.hooksPath (or the default .git/hooks/) from being silently lost when
// beads sets a local core.hooksPath override.
func preservePreexistingHooks(targetDir string) {
// Get the hooks directory git would currently use (before we override it).
currentDir, err := git.GetGitHooksDir()
if err != nil {
return
}
// Resolve to absolute paths for reliable comparison.
absTarget, err := filepath.Abs(targetDir)
if err != nil {
return
}
absCurrent, err := filepath.Abs(currentDir)
if err != nil {
return
}
// If the current dir is already our target, this is a re-install — skip.
if absTarget == absCurrent {
return
}
// If current dir is already a beads-managed directory, skip.
repoRoot, _ := git.GetMainRepoRoot()
if repoRoot == "" {
repoRoot = git.GetRepoRoot()
}
if repoRoot != "" {
absBeadsHooks, _ := filepath.Abs(filepath.Join(repoRoot, ".beads", "hooks"))
absSharedHooks, _ := filepath.Abs(filepath.Join(repoRoot, ".beads-hooks"))
if absCurrent == absBeadsHooks || absCurrent == absSharedHooks {
return
}
}
// Detect whether the source hooks live inside a husky directory. Husky v8
// hooks source `.husky/_/husky.sh`; husky v9 hooks source `.husky/_/h`.
// When the copy target is a beads-managed directory (e.g. .beads/hooks/),
// those sourced helpers are not present relative to the copied hook, so
// we must either also copy the helpers or rewrite the hooks to not need
// them. We choose the latter: inline-sanitize the hook body and skip the
// dispatcher files entirely. (GH#3132)
fromHusky := isHuskyDir(currentDir)
// Copy all hooks from the source directory, not just managed ones.
entries, err := os.ReadDir(currentDir)
if err != nil {
return
}
for _, entry := range entries {
if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") || strings.HasSuffix(entry.Name(), ".sample") {
continue
}
// Husky v9 installs a dispatcher named `h` alongside per-hook files;
// it relies on husky's `.husky/_/<hook>` path layout to locate the
// "real" hook. Once we inline the hook bodies below the dispatcher
// is no longer needed (and would silently no-op if copied). Skip it.
if fromHusky && entry.Name() == "h" {
continue
}
// husky.sh (v8 helper) is similarly useless once hooks are inlined.
if fromHusky && entry.Name() == "husky.sh" {
continue
}
srcPath := filepath.Join(currentDir, entry.Name())
// #nosec G304 -- hook path constrained to known hooks directories
content, err := os.ReadFile(srcPath)
if err != nil {
continue
}
newContent, keep := shouldPreserveHookContent(string(content), fromHusky)
if !keep {
continue
}
contentStr := newContent
// Don't overwrite existing files in target
dstPath := filepath.Join(targetDir, entry.Name())
if _, err := os.Stat(dstPath); err == nil {
continue
}
// #nosec G306 -- git hooks must be executable
if err := os.WriteFile(dstPath, []byte(contentStr), 0755); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to preserve %s hook from %s: %v\n", entry.Name(), currentDir, err)
continue
}
fmt.Printf(" Preserving existing %s hook from %s\n", entry.Name(), currentDir)
}
// GH#3132: Fix husky hook layout after copying.
fixHuskyHookLayout(currentDir, targetDir)
}
// fixHuskyHookLayout handles two husky-specific issues when hooks are copied
// from a husky-managed directory into .beads/hooks/.
//
// Bug 1 (v8): Husky v8 hooks source "$(dirname "$0")/_/husky.sh", but the
// _/ subdirectory is not copied because preservePreexistingHooks skips
// directories. Fix: create a relative symlink to the original _/ directory.
//
// Bug 2 (v9): Husky v9 uses a "h" dispatcher that resolves user hooks via
// dirname(dirname($0)), which breaks when relocated. The shims in .husky/_/
// are wrappers, not actual user hooks. Fix: replace copied shims with the
// real user hook content from the parent directory (.husky/).
func fixHuskyHookLayout(sourceDir, targetDir string) {
// Bug 1: Symlink _/ helper directory for husky v8 compatibility.
// Husky v8 hooks source $(dirname "$0")/_/husky.sh — the _/ directory
// must be reachable from the target hooks directory.
srcHelper := filepath.Join(sourceDir, "_")
if info, err := os.Stat(srcHelper); err == nil && info.IsDir() {
tgtHelper := filepath.Join(targetDir, "_")
if _, err := os.Lstat(tgtHelper); os.IsNotExist(err) {
relPath, relErr := filepath.Rel(targetDir, srcHelper)
if relErr == nil {
if symlinkErr := os.Symlink(relPath, tgtHelper); symlinkErr != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to symlink husky helper directory: %v\n", symlinkErr)
}
}
}
}
// Bug 2: Replace husky v9 shims with actual user hook content.
// Husky v9 sets core.hooksPath=.husky/_/ where each hook is a shim that
// sources "h" (the dispatcher). The dispatcher uses dirname(dirname($0))
// to find user hooks in the parent .husky/ directory — this path math
// breaks when the shim is relocated to .beads/hooks/.
//
// Detect v9 by checking for the dispatcher in the *source* directory:
// preservePreexistingHooks intentionally skips copying `h` to target, so
// keying off targetDir would never match.
srcH := filepath.Join(sourceDir, "h")
hContent, err := os.ReadFile(srcH) // #nosec G304 -- path is in known hooks directory
if err != nil {
return // No h dispatcher in source — not a husky v9 source directory
}
if !strings.Contains(string(hContent), `dirname "$(dirname`) {
return // Not the husky v9 dispatcher
}
// Source is .husky/_/ — user hooks live in the parent .husky/ directory.
// Iterate the source shims rather than the target: preservePreexistingHooks
// has already run sanitizeHuskyHook on the copied shims, which strips the
// `. "$(dirname "$0")/h"` line, so a content-based shim check against
// target would no longer match. Because every non-`h` file in sourceDir
// is a v9 shim by construction, we can map source entry → user hook
// directly.
userHooksDir := filepath.Dir(sourceDir)
entries, readErr := os.ReadDir(sourceDir)
if readErr != nil {
return
}
for _, entry := range entries {
if entry.IsDir() || entry.Name() == "h" {
continue
}
hookPath := filepath.Join(targetDir, entry.Name())
if _, statErr := os.Stat(hookPath); statErr != nil {
continue // target hook not copied — nothing to replace
}
userHookPath := filepath.Join(userHooksDir, entry.Name())
userContent, readErr := os.ReadFile(userHookPath) // #nosec G304 -- constrained to husky dir
if readErr != nil {
continue // No corresponding user hook — leave copied content as-is
}
// Ensure the content has a shebang (user hooks in .husky/ often omit it)
replacement := string(userContent)
if !strings.HasPrefix(replacement, "#!") {
replacement = "#!/usr/bin/env sh\n" + replacement
}
// #nosec G306 -- git hooks must be executable
if writeErr := os.WriteFile(hookPath, []byte(replacement), 0755); writeErr != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to replace husky v9 shim %s: %v\n", entry.Name(), writeErr)
}
}
}
// isHuskyDir reports whether dir looks like a husky-managed hooks directory
// (either `.husky` itself or `.husky/_`, the helper dir used by v9).
func isHuskyDir(dir string) bool {
if dir == "" {
return false
}
base := filepath.Base(dir)
parent := filepath.Base(filepath.Dir(dir))
if base == ".husky" {
return true
}
// .husky/_ (husky v9 helper directory that is sometimes set as
// core.hooksPath directly).
if base == "_" && parent == ".husky" {
return true
}
return false
}
// sanitizeHuskyHook rewrites a husky hook body so it can run standalone
// without the `.husky/_/husky.sh` (v8) or `.husky/_/h` (v9) helper being
// reachable relative to $0. It removes the helper-source line and prepends
// `node_modules/.bin` to PATH so that tools like `npx`, `lint-staged`, and
// project-local binaries continue to resolve — which is what husky v9's `h`
// normally does for the user. (GH#3132)
//
// Hooks that don't look like husky hooks are returned unchanged.
func sanitizeHuskyHook(content string) string {
// Normalize CRLF first so our line-by-line rewrite works on
// Windows-authored hooks too.
normalized := strings.ReplaceAll(content, "\r\n", "\n")
lines := strings.Split(normalized, "\n")
out := make([]string, 0, len(lines)+2)
sourcedHelper := false
for _, line := range lines {
trimmed := strings.TrimSpace(line)
// Match husky v8 helper: `. "$(dirname -- "$0")/_/husky.sh"` and
// common variants (single-quoted, no `--`, `source` instead of `.`).
if isHuskyHelperSourceLine(trimmed) {
sourcedHelper = true
// Drop the line entirely.
continue
}
out = append(out, line)
}
if !sourcedHelper {
// Not recognizably a husky-sourcing hook — leave it alone.
return content
}
// Rebuild, injecting a PATH export right after the shebang (if any) so
// that `npx`, `lint-staged`, etc. keep working. Husky v9's `h` normally
// does this for the user.
result := make([]string, 0, len(out)+2)
injected := false
pathLine := `export PATH="$PWD/node_modules/.bin:$PATH"`
for i, line := range out {
result = append(result, line)
if !injected && i == 0 && strings.HasPrefix(strings.TrimSpace(line), "#!") {
result = append(result, "# Injected by beads (GH#3132): husky helper layout not mirrored into this dir.")
result = append(result, pathLine)
injected = true
}
}
if !injected {
// No shebang — inject at the top.
result = append([]string{pathLine}, result...)
}
return strings.Join(result, "\n")
}
// isHuskyHelperSourceLine reports whether line (already trimmed) sources one
// of the husky helper scripts. Matches husky v8 (`_/husky.sh`) and husky v9
// (`/h`) dispatchers, tolerating quoting and `source` vs `.` variants.
func isHuskyHelperSourceLine(line string) bool {
if line == "" {
return false
}
// Must start with POSIX source (`. `) or bash `source `.
if !strings.HasPrefix(line, ". ") && !strings.HasPrefix(line, "source ") {
return false
}
// v8: references `/_/husky.sh`
if strings.Contains(line, "/_/husky.sh") || strings.Contains(line, `\_\husky.sh`) {
return true
}
// v9: `. "$(dirname "$0")/h"` (or with `--` / single quotes).
// Require both `dirname` and a trailing `/h"` or `/h'` to avoid matching
// unrelated sourcing of files that happen to end in "h".
if strings.Contains(line, "dirname") && (strings.HasSuffix(line, `/h"`) || strings.HasSuffix(line, `/h'`) || strings.HasSuffix(line, "/h")) {
return true
}
return false
}
func configureSharedHooksPath() error {
// Set git config core.hooksPath to an absolute path pointing to .beads-hooks.
// Using an absolute path is critical for git worktrees (GH#2414):
// git resolves relative core.hooksPath relative to the working tree root.
repoRoot, _ := git.GetMainRepoRoot()
if repoRoot == "" {
repoRoot = git.GetRepoRoot()
}
if repoRoot == "" {
return fmt.Errorf("not in a git repository")
}
absHooksPath := filepath.Join(repoRoot, ".beads-hooks")
cmd := exec.Command("git", "config", "core.hooksPath", absHooksPath)
cmd.Dir = repoRoot
if output, err := cmd.CombinedOutput(); err != nil {
return fmt.Errorf("git config failed: %w (output: %s)", err, string(output))
}
return nil
}
func configureBeadsHooksPath() error {
// Set git config core.hooksPath to an absolute path pointing to .beads/hooks.
// Using an absolute path is critical for git worktrees (GH#2414):
// git resolves relative core.hooksPath relative to the working tree root,
// so in a worktree ".beads/hooks" would resolve to <worktree>/.beads/hooks/
// which doesn't exist — the hooks live in the main repo's .beads/hooks/.
repoRoot, _ := git.GetMainRepoRoot()
if repoRoot == "" {
repoRoot = git.GetRepoRoot()
}
if repoRoot == "" {
return fmt.Errorf("not in a git repository")
}
absHooksPath := filepath.Join(repoRoot, ".beads", "hooks")
cmd := exec.Command("git", "config", "core.hooksPath", absHooksPath)
cmd.Dir = repoRoot
if output, err := cmd.CombinedOutput(); err != nil {
return fmt.Errorf("git config failed: %w (output: %s)", err, string(output))
}
return nil
}
func uninstallHooks() error {
// Get hooks directory from common git dir (hooks are shared across worktrees)
hooksDir, err := git.GetGitHooksDir()
if err != nil {
return err
}
hookNames := []string{"pre-commit", "post-merge", "pre-push", "post-checkout", "prepare-commit-msg"}
for _, hookName := range hookNames {
hookPath := filepath.Join(hooksDir, hookName)
// #nosec G304 -- hook path constrained to .git/hooks directory
content, err := os.ReadFile(hookPath)
if err != nil {
if os.IsNotExist(err) {
continue
}
return fmt.Errorf("failed to read %s: %w", hookName, err)
}
// Try to remove only the beads section (GH#1380)
newContent, found := removeHookSection(string(content))
if found {
remaining := strings.TrimSpace(newContent)
if remaining == "" || remaining == "#!/usr/bin/env sh" || remaining == "#!/bin/sh" {
// Only shebang left — remove the file entirely
if err := os.Remove(hookPath); err != nil {
return fmt.Errorf("failed to remove %s: %w", hookName, err)
}
} else {
// #nosec G306 -- git hooks must be executable
if err := os.WriteFile(hookPath, []byte(newContent), 0755); err != nil {
return fmt.Errorf("failed to write %s: %w", hookName, err)
}
}
continue
}
// No section markers — check if it's a legacy bd hook (remove entire file)
versionInfo, verr := getHookVersion(hookPath)
if verr == nil && versionInfo.IsBdHook {
if err := os.Remove(hookPath); err != nil {
return fmt.Errorf("failed to remove %s: %w", hookName, err)
}
// Restore backup if exists
backupPath := hookPath + ".backup"
if _, err := os.Stat(backupPath); err == nil {
if err := os.Rename(backupPath, hookPath); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to restore backup for %s: %v\n", hookName, err)
}
}
}
// Not a bd hook at all — leave it alone
}
// Reset core.hooksPath if it was set to a beads-managed directory
if err := resetHooksPathIfBeadsManaged(); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to reset core.hooksPath: %v\n", err)
}
return nil
}
// resetHooksPathIfBeadsManaged unsets core.hooksPath if it points to a
// beads-managed hooks directory (.beads/hooks or .beads-hooks).
func resetHooksPathIfBeadsManaged() error {
repoRoot, _ := git.GetMainRepoRoot()
if repoRoot == "" {
repoRoot = git.GetRepoRoot()
}
if repoRoot == "" {
return nil // not in a git repo
}
cmd := exec.Command("git", "config", "--get", "core.hooksPath")
cmd.Dir = repoRoot
out, err := cmd.Output()
if err != nil {
return nil // core.hooksPath not set — nothing to reset
}
hooksPath := strings.TrimSpace(string(out))
// Match both relative (legacy) and absolute (GH#2414) beads hooks paths
absBeadsHooks := filepath.Join(repoRoot, ".beads", "hooks")
absSharedHooks := filepath.Join(repoRoot, ".beads-hooks")
if hooksPath == ".beads/hooks" || hooksPath == ".beads-hooks" ||
hooksPath == absBeadsHooks || hooksPath == absSharedHooks {
cmd = exec.Command("git", "config", "--unset", "core.hooksPath")
cmd.Dir = repoRoot
if output, err := cmd.CombinedOutput(); err != nil {
return fmt.Errorf("git config --unset core.hooksPath failed: %w (output: %s)", err, string(output))
}
}
return nil
}
// =============================================================================
// Hook Implementation Functions (called by thin shims via 'bd hooks run')
// =============================================================================
// runChainedHook runs a .old hook if it exists. Returns the exit code.
// If the hook doesn't exist, returns 0 (success).
func runChainedHook(hookName string, args []string) int {
// Get the hooks directory from common dir (hooks are shared across worktrees)
hooksDir, err := git.GetGitHooksDir()
if err != nil {
return 0 // Not a git repo, nothing to chain
}
oldHookPath := filepath.Join(hooksDir, hookName+".old")
// Check if the .old hook exists and is executable
info, err := os.Stat(oldHookPath)
if err != nil {
return 0 // No chained hook
}
if info.Mode().Perm()&0111 == 0 {
return 0 // Not executable
}
// Check if .old is itself a bd hook (shim or inline) - skip to prevent infinite recursion
// This can happen if user runs `bd hooks install --chain` multiple times,
// renaming an existing bd hook to .old. See: GH#843, GH#1120
versionInfo, err := getHookVersion(oldHookPath)
if err == nil && versionInfo.IsBdHook {
// Skip execution - .old is a bd hook which would call us again
return 0
}
// Run the chained hook
// #nosec G204 -- hookName is from controlled list, path is from git directory
cmd := exec.Command(oldHookPath, args...)
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Stdin = os.Stdin
if err := cmd.Run(); err != nil {
if exitErr, ok := err.(*exec.ExitError); ok {
return exitErr.ExitCode()
}
// Other error - treat as failure
fmt.Fprintf(os.Stderr, "Warning: chained hook %s failed: %v\n", hookName, err)
return 1
}
return 0
}
// runPreCommitHook runs chained hooks before commit.
// Returns 0 on success (or if not applicable).
func runPreCommitHook() int {
// Run chained hook first (if exists)
if exitCode := runChainedHook("pre-commit", nil); exitCode != 0 {
return exitCode
}
// GH#2489, GH#1863: Export JSONL before commit so issue state lands in
// the same commit as code changes. maybeAutoExport() skips when
// BD_GIT_HOOK=1, so we invoke `bd export` as a subprocess instead.
exportJSONLForCommit()
return 0
}
// exportJSONLForCommit exports Dolt issue state to the git-tracked JSONL file
// when export.auto is enabled. Called from the pre-commit hook so that the
// exported file can be staged and included in the pending commit.
//
// Errors are logged as warnings but never block the commit.
func exportJSONLForCommit() {
if !config.GetBool("export.auto") {
return
}
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return
}
exportPath := config.GetString("export.path")
if exportPath == "" {
exportPath = "issues.jsonl"
}
fullPath := filepath.Join(beadsDir, exportPath)
debug.Logf("pre-commit: exporting JSONL to %s\n", fullPath)
// Shell out to `bd export` which initializes its own store.
// Clear BD_GIT_HOOK from the subprocess env so that its
// PersistentPostRun auto-export path does not also fire.
//
// NOTE: we intentionally preserve GIT_DIR et al. in the subprocess
// env. The subprocess's PostRun eventually routes through the same
// gitAddFile as the parent, which relies on the inherited GIT_DIR to
// identify the hook's worktree and apply the cross-worktree staging
// guard (GH#3311 part 2). Scrubbing here would disable that guard.
// Run from the project root, not .beads/. Embedded Dolt discovery starts
// from cwd, so cwd=.beads/ can make the export subprocess look for a
// nested .beads/.beads workspace and warn on every commit (GH#3454).
cmd := exec.Command("bd", "export", "-o", fullPath)
cmd.Dir = exportSubprocessDir(beadsDir)
cmd.Env = filterEnv(os.Environ(), "BD_GIT_HOOK")
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
fmt.Fprintf(os.Stderr, "beads: pre-commit export warning: %v\n", err)
return
}
// Stage the exported file if configured. Skip when no-git-ops is set
// (GH#3314). gitAddFile scrubs the inherited git hook env vars so git
// rediscovers the repo from cwd, and silently skips when fullPath is
// outside the hook's worktree (the .beads/redirect case where fullPath
// points into the main repo, not this worktree). See GH#3311.
if config.GetBool("export.git-add") && !config.GetBool("no-git-ops") {
if err := gitAddFile(fullPath); err != nil {
debug.Logf("pre-commit: git add failed: %v\n", err)
}
}
}
func exportSubprocessDir(beadsDir string) string {
return filepath.Dir(beadsDir)
}
// filterEnv returns a copy of env with entries matching the given key removed.
func filterEnv(env []string, key string) []string {
prefix := key + "="
out := make([]string, 0, len(env))
for _, e := range env {
if !strings.HasPrefix(e, prefix) {
out = append(out, e)
}
}
return out
}
// runPostMergeHook runs chained hooks after merge.
// Returns 0 on success (or if not applicable).
//
//nolint:unparam // Always returns 0 by design - warnings don't block merges
func runPostMergeHook() int {
// Run chained hook first (if exists)
if exitCode := runChainedHook("post-merge", nil); exitCode != 0 {
return exitCode
}
return 0
}
// runPrePushHook runs chained hooks before push.
// Returns 0 to allow push, non-zero to block.
func runPrePushHook(args []string) int {
// Run chained hook first (if exists)
if exitCode := runChainedHook("pre-push", args); exitCode != 0 {
return exitCode
}
return 0
}
// runPostCheckoutHook runs chained hooks after branch checkout.
// args: [previous-HEAD, new-HEAD, flag] where flag=1 for branch checkout
// Returns 0 on success (or if not applicable).
//
//nolint:unparam // Always returns 0 by design - warnings don't block checkouts
func runPostCheckoutHook(args []string) int {
// Run chained hook first (if exists)
if exitCode := runChainedHook("post-checkout", args); exitCode != 0 {
return exitCode
}
return 0
}
// runPrepareCommitMsgHook adds agent identity trailers to commit messages.
// args: [commit-msg-file, source, sha1]
// Returns 0 on success (or if not applicable), non-zero on error.
//
//nolint:unparam // Always returns 0 by design - we don't block commits
func runPrepareCommitMsgHook(args []string) int {
// Run chained hook first (if exists)
if exitCode := runChainedHook("prepare-commit-msg", args); exitCode != 0 {
return exitCode
}
if len(args) < 1 {
return 0 // No message file provided
}
msgFile := args[0]
source := ""
if len(args) >= 2 {
source = args[1]
}
// Skip for merge commits (they already have their own format)
if source == "merge" {
return 0
}
// Detect actor context from BD_ACTOR env var
actor := os.Getenv("BD_ACTOR")
if actor == "" {
return 0 // Not in agent context, nothing to add
}
// Read current message
content, err := os.ReadFile(msgFile) // #nosec G304 -- path from git
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: could not read commit message: %v\n", err)
return 0
}
// Check if trailer already present (avoid duplicates on amend)
for _, line := range strings.Split(string(content), "\n") {
if strings.HasPrefix(line, "Executed-By:") {
return 0
}
}
// Append Executed-By trailer
msg := strings.TrimRight(string(content), "\n\r\t ")
var sb strings.Builder
sb.WriteString(msg)
sb.WriteString("\n\n")
sb.WriteString(fmt.Sprintf("Executed-By: %s\n", actor))
// Write back
if err := os.WriteFile(msgFile, []byte(sb.String()), 0600); err != nil { // Restrict permissions per gosec G306
fmt.Fprintf(os.Stderr, "Warning: could not write commit message: %v\n", err)
}
return 0
}
// =============================================================================
// Hook Helper Functions
// =============================================================================
// isRebaseInProgress checks if a rebase is in progress.
func isRebaseInProgress() bool {
if _, err := os.Stat(".git/rebase-merge"); err == nil {
return true
}
if _, err := os.Stat(".git/rebase-apply"); err == nil {
return true
}
return false
}
var hooksRunCmd = &cobra.Command{
Use: "run <hook-name> [args...]",
Short: "Execute a git hook (called by thin shims)",
Long: `Execute the logic for a git hook. This command is typically called by
thin shim scripts installed in .git/hooks/.
Supported hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics
The thin shim pattern ensures hook logic is always in sync with the
installed bd version - upgrading bd automatically updates hook behavior.`,
Args: cobra.MinimumNArgs(1),
Run: func(cmd *cobra.Command, args []string) {
// Disable terminal color probing to prevent OSC 11 escape sequence leaks (GH#1303).
// Our shell shims set BD_GIT_HOOK=1 before invoking bd, but third-party hook
// runners (lefthook, husky, etc.) call 'bd hooks run' directly without it.
// By this point ui.init() has already run, so we must also reset styles
// to suppress ANSI output — the env var alone only helps if set before process start.
_ = os.Setenv("BD_GIT_HOOK", "1")
ui.DisableColors()
hookName := args[0]
hookArgs := args[1:]
var exitCode int
switch hookName {
case "pre-commit":
exitCode = runPreCommitHook()
case "post-merge":
exitCode = runPostMergeHook()
case "pre-push":
exitCode = runPrePushHook(hookArgs)
case "post-checkout":
exitCode = runPostCheckoutHook(hookArgs)
case "prepare-commit-msg":
exitCode = runPrepareCommitMsgHook(hookArgs)
default:
FatalError("unknown hook: %s", hookName)
}
os.Exit(exitCode)
},
}
func init() {
hooksInstallCmd.Flags().Bool("force", false, "Overwrite existing hooks without backup")
hooksInstallCmd.Flags().Bool("shared", false, "Install hooks to .beads-hooks/ (versioned) instead of .git/hooks/")
hooksInstallCmd.Flags().Bool("chain", false, "Chain with existing hooks (run them before bd hooks)")
hooksInstallCmd.Flags().Bool("beads", false, "Install hooks to .beads/hooks/ (recommended for Dolt backend)")
hooksCmd.AddCommand(hooksInstallCmd)
hooksCmd.AddCommand(hooksUninstallCmd)
hooksCmd.AddCommand(hooksListCmd)
hooksCmd.AddCommand(hooksRunCmd)
rootCmd.AddCommand(hooksCmd)
}