#!/usr/bin/env node /** * GitNexus Claude Code Hook * * PreToolUse — intercepts Grep/Glob/Bash searches and augments * with graph context from the GitNexus index. * PostToolUse — detects stale index after git mutations and notifies * the agent to reindex. * * NOTE: SessionStart hooks are broken on Windows (Claude Code bug). * Session context is injected via CLAUDE.md / skills instead. */ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); const { acquireHookSlot } = require('./hook-lock.cjs'); const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs'); /** * Read JSON input from stdin synchronously. */ function readInput() { try { const data = fs.readFileSync(0, 'utf-8'); return JSON.parse(data); } catch { return {}; } } /** * Find the .gitnexus directory by walking up from startDir. * Returns the path to .gitnexus/ or null if not found. */ function isGlobalRegistryDir(candidate) { if (fs.existsSync(path.join(candidate, 'meta.json'))) return false; return ( fs.existsSync(path.join(candidate, 'registry.json')) || fs.existsSync(path.join(candidate, 'repos')) ); } /** * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder. * Returns the path to `.gitnexus/` or null if not found within 5 levels. */ function walkForGitNexusDir(startDir) { let dir = startDir; for (let i = 0; i < 5; i++) { const candidate = path.join(dir, '.gitnexus'); if (fs.existsSync(candidate)) { if (!isGlobalRegistryDir(candidate)) return candidate; } const parent = path.dirname(dir); if (parent === dir) break; dir = parent; } return null; } /** * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside * any git working tree — including a *linked* worktree created via * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the * upward walk from cwd alone misses the index. Returns null when `cwd` is * not inside a git repo or `git` is not available. * * Implementation: `git rev-parse --git-common-dir` resolves to the canonical * `.git/` directory (or `.git/worktrees/...` parent) that is shared across * all linked worktrees. The canonical repo root is its parent directory. */ function findCanonicalRepoRoot(cwd) { try { const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf-8', timeout: 2000, cwd, stdio: ['pipe', 'pipe', 'pipe'], }); if (result.error || result.status !== 0) return null; const commonDir = (result.stdout || '').trim(); if (!commonDir || !path.isAbsolute(commonDir)) return null; return path.dirname(commonDir); } catch { return null; } } function findGitNexusDir(startDir) { const cwd = startDir || process.cwd(); // Fast path: the cwd is inside the canonical repo (most common case). const fromCwd = walkForGitNexusDir(cwd); if (fromCwd) return fromCwd; // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/` // only lives in the canonical repo root. Resolve the shared git dir // and retry from there. const canonicalRoot = findCanonicalRepoRoot(cwd); if (canonicalRoot && canonicalRoot !== cwd) { return walkForGitNexusDir(canonicalRoot); } return null; } function hasGitNexusServerOwner(gitNexusDir) { return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid); } function extractAugmentContext(stderr) { const output = (stderr || '').trim(); const marker = output.indexOf('[GitNexus]'); const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true'; if (debug && output.length > 0) { // Emit the FULL discarded prefix (everything before the marker, or all of // it when no marker is present) so suppressed diagnostics — KuzuDB lock // warnings, parser errors, etc. — remain recoverable on the hook's own // stderr. The untruncated payload lets operators see exactly what was // filtered out instead of a 180-char JSON-quoted preview. const discarded = marker === -1 ? output : output.slice(0, marker).trim(); if (discarded.length > 0) { process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`); } } return marker === -1 ? '' : output.slice(marker).trim(); } /** * Extract search pattern from tool input. */ function extractPattern(toolName, toolInput) { if (toolName === 'Grep') { return toolInput.pattern || null; } if (toolName === 'Glob') { const raw = toolInput.pattern || ''; const match = raw.match(/[*\/]([a-zA-Z][a-zA-Z0-9_-]{2,})/); return match ? match[1] : null; } if (toolName === 'Bash') { const cmd = toolInput.command || ''; if (!/\brg\b|\bgrep\b/.test(cmd)) return null; const tokens = cmd.split(/\s+/); let foundCmd = false; let skipNext = false; const flagsWithValues = new Set([ '-e', '-f', '-m', '-A', '-B', '-C', '-g', '--glob', '-t', '--type', '--include', '--exclude', ]); for (const token of tokens) { if (skipNext) { skipNext = false; continue; } if (!foundCmd) { if (/\brg$|\bgrep$/.test(token)) foundCmd = true; continue; } if (token.startsWith('-')) { if (flagsWithValues.has(token)) skipNext = true; continue; } const cleaned = token.replace(/['"]/g, ''); return cleaned.length >= 3 ? cleaned : null; } return null; } return null; } /** * Resolve the gitnexus CLI path. * 1. Relative path (works when script is inside npm package) * 2. require.resolve (works when gitnexus is globally installed) * 3. Fall back to npx (returns empty string) */ function resolveCliPath() { const fromEnv = process.env.GITNEXUS_HOOK_CLI_PATH; if (fromEnv !== undefined && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) { return String(fromEnv); } let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js'); if (!fs.existsSync(cliPath)) { try { cliPath = require.resolve('gitnexus/dist/cli/index.js'); } catch { cliPath = ''; } } return cliPath; } /** * Spawn a gitnexus CLI command synchronously. * Returns the stderr output (KuzuDB captures stdout at OS level). */ function runGitNexusCli(cliPath, args, cwd, timeout) { const isWin = process.platform === 'win32'; if (cliPath) { return spawnSync(process.execPath, [cliPath, ...args], { encoding: 'utf-8', timeout, cwd, stdio: ['pipe', 'pipe', 'pipe'], }); } // On Windows, invoke npx.cmd directly (no shell needed) return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], { encoding: 'utf-8', timeout: timeout + 5000, cwd, stdio: ['pipe', 'pipe', 'pipe'], }); } /** * PreToolUse handler — augment searches with graph context. */ function handlePreToolUse(input) { const cwd = input.cwd || process.cwd(); if (!path.isAbsolute(cwd)) return; const gitNexusDir = findGitNexusDir(cwd); if (!gitNexusDir) return; const toolName = input.tool_name || ''; const toolInput = input.tool_input || {}; if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return; const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; if (hasGitNexusServerOwner(gitNexusDir)) { process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n'); return; } const release = acquireHookSlot(gitNexusDir); if (!release) return; const cliPath = resolveCliPath(); let result = ''; try { const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000); if (!child.error && child.status === 0) { result = extractAugmentContext(child.stderr || ''); } } catch { /* graceful failure */ } finally { release(); } if (result) { sendHookResponse('PreToolUse', result); } } /** * Emit a PostToolUse hook response with additional context for the agent. */ function sendHookResponse(hookEventName, message) { console.log( JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: message }, }), ); } /** * PostToolUse handler — detect index staleness after git mutations. * * Instead of spawning a full `gitnexus analyze` synchronously (which blocks * the agent for up to 120s and risks KuzuDB corruption on timeout), we do a * lightweight staleness check: compare `git rev-parse HEAD` against the * lastCommit stored in `.gitnexus/meta.json`. If they differ, notify the * agent so it can decide when to reindex. */ function handlePostToolUse(input) { const toolName = input.tool_name || ''; if (toolName !== 'Bash') return; const command = (input.tool_input || {}).command || ''; if (!/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) return; // Only proceed if the command succeeded const toolOutput = input.tool_output || {}; if (toolOutput.exit_code !== undefined && toolOutput.exit_code !== 0) return; const cwd = input.cwd || process.cwd(); if (!path.isAbsolute(cwd)) return; const gitNexusDir = findGitNexusDir(cwd); if (!gitNexusDir) return; // Compare HEAD against last indexed commit — skip if unchanged let currentHead = ''; try { const headResult = spawnSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf-8', timeout: 3000, cwd, stdio: ['pipe', 'pipe', 'pipe'], }); currentHead = (headResult.stdout || '').trim(); } catch { return; } if (!currentHead) return; let lastCommit = ''; let hadEmbeddings = false; try { const meta = JSON.parse(fs.readFileSync(path.join(gitNexusDir, 'meta.json'), 'utf-8')); lastCommit = meta.lastCommit || ''; hadEmbeddings = meta.stats && meta.stats.embeddings > 0; } catch { /* no meta — treat as stale */ } // If HEAD matches last indexed commit, no reindex needed if (currentHead && currentHead === lastCommit) return; const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`; sendHookResponse( 'PostToolUse', `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` + `Run \`${analyzeCmd}\` to update the knowledge graph.`, ); } // Dispatch map for hook events const handlers = { PreToolUse: handlePreToolUse, PostToolUse: handlePostToolUse, }; function main() { try { const input = readInput(); const handler = handlers[input.hook_event_name || '']; if (handler) handler(input); } catch (err) { if (process.env.GITNEXUS_DEBUG) { console.error('GitNexus hook error:', (err.message || '').slice(0, 200)); } } } main();