gitnexus 1.3.10 → 1.3.11

package/dist/cli/ai-context.js

@@ -96,6 +96,24 @@ Before completing any code modification task, verify:
 3. \`gitnexus_detect_changes()\` confirms changes match expected scope
 4. All d=1 (WILL BREAK) dependents were updated
 
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+\`\`\`bash
+npx gitnexus analyze
+\`\`\`
+
+If the index previously included embeddings, preserve them by adding \`--embeddings\`:
+
+\`\`\`bash
+npx gitnexus analyze --embeddings
+\`\`\`
+
+To check whether embeddings exist, inspect \`.gitnexus/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
+
 ## CLI
 
 - Re-index: \`npx gitnexus analyze\`

package/dist/cli/analyze.js

@@ -242,6 +242,13 @@ export const analyzeCommand = async (inputPath, options) => {
     }
     // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
     updateBar(98, 'Saving metadata...');
+    // Count embeddings in the index (cached + newly generated)
+    let embeddingCount = 0;
+    try {
+        const embResult = await executeQuery(`MATCH (e:CodeEmbedding) RETURN count(e) AS cnt`);
+        embeddingCount = embResult?.[0]?.cnt ?? 0;
+    }
+    catch { /* table may not exist if embeddings never ran */ }
     const meta = {
         repoPath,
         lastCommit: currentCommit,
@@ -252,6 +259,7 @@ export const analyzeCommand = async (inputPath, options) => {
             edges: stats.edges,
             communities: pipelineResult.communityResult?.stats.totalCommunities,
             processes: pipelineResult.processResult?.stats.totalProcesses,
+            embeddings: embeddingCount,
         },
     };
     await saveMeta(storagePath, meta);

package/dist/cli/setup.js

@@ -147,36 +147,34 @@ async function installClaudeCodeHooks(result) {
             // even when it's no longer inside the npm package tree
             const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
             const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
-            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = '${normalizedCli}';`);
+            const jsonCli = JSON.stringify(normalizedCli);
+            content = content.replace("let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');", `let cliPath = ${jsonCli};`);
             await fs.writeFile(dest, content, 'utf-8');
         }
         catch {
             // Script not found in source — skip
         }
-        const hookCmd = `node "${path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/')}"`;
+        const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
+        const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
         // Merge hook config into ~/.claude/settings.json
         const existing = await readJsonFile(settingsPath) || {};
         if (!existing.hooks)
             existing.hooks = {};
-        // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
-        // Session context is delivered via CLAUDE.md / skills instead.
-        // Add PreToolUse hook if not already present
-        if (!existing.hooks.PreToolUse)
-            existing.hooks.PreToolUse = [];
-        const hasPreToolHook = existing.hooks.PreToolUse.some((h) => h.hooks?.some((hh) => hh.command?.includes('gitnexus')));
-        if (!hasPreToolHook) {
-            existing.hooks.PreToolUse.push({
-                matcher: 'Grep|Glob|Bash',
-                hooks: [{
-                        type: 'command',
-                        command: hookCmd,
-                        timeout: 8000,
-                        statusMessage: 'Enriching with GitNexus graph context...',
-                    }],
-            });
+        function ensureHookEntry(eventName, matcher, timeout, statusMessage) {
+            if (!existing.hooks[eventName])
+                existing.hooks[eventName] = [];
+            const hasHook = existing.hooks[eventName].some((h) => h.hooks?.some(hh => hh.command?.includes('gitnexus-hook')));
+            if (!hasHook) {
+                existing.hooks[eventName].push({
+                    matcher,
+                    hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
+                });
+            }
         }
+        ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with GitNexus graph context...');
+        ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking GitNexus index freshness...');
         await writeJsonFile(settingsPath, existing);
-        result.configured.push('Claude Code hooks (PreToolUse)');
+        result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
     }
     catch (err) {
         result.errors.push(`Claude Code hooks: ${err.message}`);

package/dist/core/ingestion/pipeline.js

@@ -12,6 +12,9 @@ import { walkRepositoryPaths, readFileContents } from './filesystem-walker.js';
 import { getLanguageFromFilename } from './utils.js';
 import { isLanguageAvailable } from '../tree-sitter/parser-loader.js';
 import { createWorkerPool } from './workers/worker-pool.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 const isDev = process.env.NODE_ENV === 'development';
 /** Max bytes of source content to load per parse chunk. Each chunk's source +
  *  parsed ASTs + extracted records + worker serialization overhead all live in
@@ -124,11 +127,21 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
         // Create worker pool once, reuse across chunks
         let workerPool;
         try {
-            const workerUrl = new URL('./workers/parse-worker.js', import.meta.url);
+            let workerUrl = new URL('./workers/parse-worker.js', import.meta.url);
+            // When running under vitest, import.meta.url points to src/ where no .js exists.
+            // Fall back to the compiled dist/ worker so the pool can spawn real worker threads.
+            const thisDir = fileURLToPath(new URL('.', import.meta.url));
+            if (!fs.existsSync(fileURLToPath(workerUrl))) {
+                const distWorker = path.resolve(thisDir, '..', '..', '..', 'dist', 'core', 'ingestion', 'workers', 'parse-worker.js');
+                if (fs.existsSync(distWorker)) {
+                    workerUrl = pathToFileURL(distWorker);
+                }
+            }
             workerPool = createWorkerPool(workerUrl);
         }
         catch (err) {
-            // Worker pool creation failed — sequential fallback
+            if (isDev)
+                console.warn('Worker pool creation failed, using sequential fallback:', err.message);
         }
         let filesParsedSoFar = 0;
         // AST cache sized for one chunk (sequential fallback uses it for import/call/heritage)

package/dist/core/ingestion/workers/worker-pool.js

@@ -1,5 +1,7 @@
 import { Worker } from 'node:worker_threads';
 import os from 'node:os';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
 /**
  * Max files to send to a worker in a single postMessage.
  * Keeps structured-clone memory bounded per sub-batch.
@@ -12,6 +14,12 @@ const SUB_BATCH_TIMEOUT_MS = 30_000;
  * Create a pool of worker threads.
  */
 export const createWorkerPool = (workerUrl, poolSize) => {
+    // Validate worker script exists before spawning to prevent uncaught
+    // MODULE_NOT_FOUND crashes in worker threads (e.g. when running from src/ via vitest)
+    const workerPath = fileURLToPath(workerUrl);
+    if (!fs.existsSync(workerPath)) {
+        throw new Error(`Worker script not found: ${workerPath}`);
+    }
     const size = poolSize ?? Math.min(8, Math.max(1, os.cpus().length - 1));
     const workers = [];
     for (let i = 0; i < size; i++) {

package/dist/core/kuzu/kuzu-adapter.js

@@ -711,8 +711,8 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
     if (!conn) {
         throw new Error('KuzuDB not initialized. Call initKuzu first.');
     }
-    // Escape single quotes in query
-    const escapedQuery = query.replace(/'/g, "''");
+    // Escape backslashes and single quotes to prevent Cypher injection
+    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
     CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := ${conjunctive})
     RETURN node, score

package/dist/core/search/bm25-index.js

@@ -10,7 +10,8 @@ import { queryFTS } from '../kuzu/kuzu-adapter.js';
  * Returns the same shape as core queryFTS.
  */
 async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
-    const escapedQuery = query.replace(/'/g, "''");
+    // Escape single quotes and backslashes to prevent Cypher injection
+    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
     CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := false)
     RETURN node, score

package/dist/mcp/core/kuzu-adapter.js

@@ -64,26 +64,14 @@ function evictLRU() {
     }
 }
 /**
- * Close all connections for a repo and remove it from the pool
+ * Remove a repo from the pool without calling native close methods.
+ *
+ * KuzuDB's native .closeSync() triggers N-API destructor hooks that
+ * segfault on Linux/macOS.  Pool databases are opened read-only, so
+ * there is no WAL to flush — just deleting the pool entry and letting
+ * the GC (or process exit) reclaim native resources is safe.
  */
 function closeOne(repoId) {
-    const entry = pool.get(repoId);
-    if (!entry)
-        return;
-    for (const conn of entry.available) {
-        try {
-            conn.close();
-        }
-        catch (e) {
-            console.error('GitNexus [pool:close-conn]:', e instanceof Error ? e.message : e);
-        }
-    }
-    try {
-        entry.db.close();
-    }
-    catch (e) {
-        console.error('GitNexus [pool:close-db]:', e instanceof Error ? e.message : e);
-    }
     pool.delete(repoId);
 }
 /**

package/hooks/claude/gitnexus-hook.cjs

@@ -2,8 +2,10 @@
 /**
  * GitNexus Claude Code Hook
  *
- * PreToolUse handler — intercepts Grep/Glob/Bash searches
- * and augments with graph context from the GitNexus index.
+ * 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.
@@ -11,7 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
+const { spawnSync } = require('child_process');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -26,19 +28,19 @@ function readInput() {
 }
 
 /**
- * Check if a directory (or ancestor) has a .gitnexus index.
+ * Find the .gitnexus directory by walking up from startDir.
+ * Returns the path to .gitnexus/ or null if not found.
  */
-function findGitNexusIndex(startDir) {
+function findGitNexusDir(startDir) {
   let dir = startDir || process.cwd();
   for (let i = 0; i < 5; i++) {
-    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
-      return true;
-    }
+    const candidate = path.join(dir, '.gitnexus');
+    if (fs.existsSync(candidate)) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return false;
+  return null;
 }
 
 /**
@@ -83,72 +85,153 @@ function extractPattern(toolName, toolInput) {
   return null;
 }
 
-function main() {
-  try {
-    const input = readInput();
-    const hookEvent = input.hook_event_name || '';
-
-    if (hookEvent !== 'PreToolUse') return;
+/**
+ * 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() {
+  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;
+}
 
-    const cwd = input.cwd || process.cwd();
-    if (!findGitNexusIndex(cwd)) return;
+/**
+ * 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'] }
+  );
+}
 
-    const toolName = input.tool_name || '';
-    const toolInput = input.tool_input || {};
+/**
+ * PreToolUse handler — augment searches with graph context.
+ */
+function handlePreToolUse(input) {
+  const cwd = input.cwd || process.cwd();
+  if (!path.isAbsolute(cwd)) return;
+  if (!findGitNexusDir(cwd)) return;
 
-    if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
 
-    const pattern = extractPattern(toolName, toolInput);
-    if (!pattern || pattern.length < 3) return;
+  if (toolName !== 'Grep' && toolName !== 'Glob' && toolName !== 'Bash') return;
 
-    // Resolve CLI path — try multiple strategies:
-    // 1. Relative path (works when script is inside npm package)
-    // 2. require.resolve (works when gitnexus is globally installed)
-    // 3. Fall back to npx (works when neither is available)
-    let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');
-    if (!fs.existsSync(cliPath)) {
-      try {
-        cliPath = require.resolve('gitnexus/dist/cli/index.js');
-      } catch {
-        cliPath = ''; // will use npx fallback
-      }
-    }
+  const pattern = extractPattern(toolName, toolInput);
+  if (!pattern || pattern.length < 3) return;
 
-    // augment CLI writes result to stderr (KuzuDB's native module captures
-    // stdout fd at OS level, making it unusable in subprocess contexts).
-    const { spawnSync } = require('child_process');
-    let result = '';
-    try {
-      let child;
-      if (cliPath) {
-        child = spawnSync(
-          process.execPath,
-          [cliPath, 'augment', pattern],
-          { encoding: 'utf-8', timeout: 8000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
-        );
-      } else {
-        // npx fallback
-        const cmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-        child = spawnSync(
-          cmd,
-          ['-y', 'gitnexus', 'augment', pattern],
-          { encoding: 'utf-8', timeout: 15000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
-        );
-      }
+  const cliPath = resolveCliPath();
+  let result = '';
+  try {
+    const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
+    if (!child.error && child.status === 0) {
       result = child.stderr || '';
-    } catch { /* graceful failure */ }
-
-    if (result && result.trim()) {
-      console.log(JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          additionalContext: result.trim()
-        }
-      }));
     }
+  } catch { /* graceful failure */ }
+
+  if (result && result.trim()) {
+    sendHookResponse('PreToolUse', result.trim());
+  }
+}
+
+/**
+ * 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) {
-    // Graceful failure — log to stderr for debugging
-    console.error('GitNexus hook error:', err.message);
+    if (process.env.GITNEXUS_DEBUG) {
+      console.error('GitNexus hook error:', (err.message || '').slice(0, 200));
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-cli.md

@@ -22,7 +22,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | `--force`      | Force full re-index even if up to date                           |
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
 
-**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
 ### status — Check index freshness