beads/cmd/bd/hooks.go
matt wilkie 3be9f0001d
fix(hooks): auto-import .beads/issues.jsonl after pull/checkout (GH#3729) (#3730)
bd export auto-fires on every pre-commit, but until now there was no
symmetric bd import after git pull. For projects syncing via committed
JSONL (no Dolt remote), this asymmetry silently drops issues created on
other machines: the local Dolt never sees them, so the next auto-export
overwrites the JSONL with our depleted view.

Concrete reproducer: maphew/mybd@7190c78 erased 65 issues that existed
on origin/main but had never entered this machine's local Dolt; recovery
required manual bd import of HEAD~1's JSONL.

This change adds importJSONLForSync, called from runPostMergeHook and
runPostCheckoutHook (when flag=1, branch checkout). Symmetric to
exportJSONLForCommit:

- gated by a new import.auto config key (default true)
- shells out to bd import --quiet via the same subprocess pattern
  exportJSONLForCommit uses
- tolerates "Error 1105: nothing to commit" from Dolt as a no-op
  success (jsonl already matches Dolt)
- guard-clauses for missing/empty .beads dir, missing/empty jsonl,
  short args (legacy git versions), file-mode checkouts (flag=0)

The existing maybeAutoImportJSONL upgrade-recovery path (GH#2994,
empty-DB only) is unchanged. This new path complements it for the
ongoing-sync case.

Tests cover the early-return guards (no-beads-dir, import.auto=false,
empty jsonl, file-mode checkout). The shell-out path itself is left to
integration testing — same coverage shape exportJSONLForCommit has.

Closes GH#3729.

Co-authored-by: CI Bot <ci@beads.test>
2026-05-05 20:16:51 -07:00

1637 lines
57 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.
// Directories inside .beads/ use BeadsDirPerm (0700); git-managed hook
// dirs (.git/hooks, .beads-hooks) use 0755 so git can execute them.
hooksDirPerm := os.FileMode(0755)
if beadsHooks {
hooksDirPerm = config.BeadsDirPerm
}
if err := os.MkdirAll(hooksDir, hooksDirPerm); 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)
}
// importJSONLForSync imports .beads/issues.jsonl into Dolt after a git
// pull/merge/branch-checkout, so issues created on other machines enter
// the local database before the next auto-export overwrites the JSONL
// with our (possibly stale) view. Symmetric to exportJSONLForCommit.
//
// Errors are logged as warnings but never block the merge/checkout. The
// import is upsert; running it on an unchanged JSONL is a no-op (bd
// import returns "Error 1105: nothing to commit", which we tolerate).
//
// See GH#3729.
func importJSONLForSync(reason string) {
if !config.GetBool("import.auto") {
return
}
beadsDir := beads.FindBeadsDir()
if beadsDir == "" {
return
}
exportPath := config.GetString("export.path")
if exportPath == "" {
exportPath = "issues.jsonl"
}
fullPath := filepath.Join(beadsDir, exportPath)
if info, err := os.Stat(fullPath); err != nil || info.Size() == 0 {
return
}
debug.Logf("%s: importing JSONL from %s\n", reason, fullPath)
// Shell out to `bd import` — same pattern as exportJSONLForCommit.
// Clear BD_GIT_HOOK so the subprocess's own hook-detection logic
// doesn't suppress its work.
cmd := exec.Command("bd", "import", "--quiet", fullPath)
cmd.Dir = exportSubprocessDir(beadsDir)
cmd.Env = filterEnv(os.Environ(), "BD_GIT_HOOK")
out, err := cmd.CombinedOutput()
if err == nil {
return
}
// Tolerate the no-op case: when JSONL matches Dolt exactly, bd import
// produces "nothing to commit" from the underlying Dolt commit. That
// is success for our purposes.
if strings.Contains(string(out), "nothing to commit") {
return
}
fmt.Fprintf(os.Stderr, "beads: %s import warning: %v\n%s", reason, err, out)
}
// 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, then auto-imports
// .beads/issues.jsonl into Dolt so issues created on other machines (and
// just landed via git pull) enter the local database before the next
// auto-export overwrites the JSONL with our stale view. See GH#3729.
//
// 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
}
importJSONLForSync("post-merge")
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, then
// auto-imports .beads/issues.jsonl into Dolt when the checkout was a
// branch switch (flag=1). File-mode checkouts (flag=0) are skipped to
// avoid spurious imports on `git checkout -- <file>`. See GH#3729.
//
// 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
}
if len(args) >= 3 && args[2] == "1" {
importJSONLForSync("post-checkout")
}
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)
}