gitnexus 1.3.9 → 1.3.10

package/dist/mcp/tools.js

@@ -7,14 +7,14 @@
 export const GITNEXUS_TOOLS = [
     {
         name: 'list_repos',
-        description: `List all indexed repositories available to GitNexus.
-
-Returns each repo's name, path, indexed date, last commit, and stats.
-
-WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
-AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
-
-When multiple repos are indexed, you MUST specify the "repo" parameter
+        description: `List all indexed repositories available to GitNexus.
+
+Returns each repo's name, path, indexed date, last commit, and stats.
+
+WHEN TO USE: First step when multiple repos are indexed, or to discover available repos.
+AFTER THIS: READ gitnexus://repo/{name}/context for the repo you want to work with.
+
+When multiple repos are indexed, you MUST specify the "repo" parameter
 on other tools (query, context, impact, etc.) to target the correct one.`,
         inputSchema: {
             type: 'object',
@@ -24,17 +24,17 @@ on other tools (query, context, impact, etc.) to target the correct one.`,
     },
     {
         name: 'query',
-        description: `Query the code knowledge graph for execution flows related to a concept.
-Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
-
-WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
-AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
-
-Returns results grouped by process (execution flow):
-- processes: ranked execution flows with relevance priority
-- process_symbols: all symbols in those flows with file locations and module (functional area)
-- definitions: standalone types/interfaces not in any process
-
+        description: `Query the code knowledge graph for execution flows related to a concept.
+Returns processes (call chains) ranked by relevance, each with its symbols and file locations.
+
+WHEN TO USE: Understanding how code works together. Use this when you need execution flows and relationships, not just file matches. Complements grep/IDE search.
+AFTER THIS: Use context() on a specific symbol for 360-degree view (callers, callees, categorized refs).
+
+Returns results grouped by process (execution flow):
+- processes: ranked execution flows with relevance priority
+- process_symbols: all symbols in those flows with file locations and module (functional area)
+- definitions: standalone types/interfaces not in any process
+
 Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank Fusion.`,
         inputSchema: {
             type: 'object',
@@ -52,34 +52,34 @@ Hybrid ranking: BM25 keyword + semantic vector search, ranked by Reciprocal Rank
     },
     {
         name: 'cypher',
-        description: `Execute Cypher query against the code knowledge graph.
-
-WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
-AFTER THIS: Use context() on result symbols for deeper context.
-
-SCHEMA:
-- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
-- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
-- All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
-- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
-
-EXAMPLES:
-• Find callers of a function:
-  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
-
-• Find community members:
-  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
-
-• Trace a process:
-  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
-
-OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
-
-TIPS:
-- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
-- Community = auto-detected functional area (Leiden algorithm)
-- Process = execution flow trace from entry point to terminal
+        description: `Execute Cypher query against the code knowledge graph.
+
+WHEN TO USE: Complex structural queries that search/explore can't answer. READ gitnexus://repo/{name}/schema first for the full schema.
+AFTER THIS: Use context() on result symbols for deeper context.
+
+SCHEMA:
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process
+- Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
+- All edges via single CodeRelation table with 'type' property
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS
+- Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
+
+EXAMPLES:
+• Find callers of a function:
+  MATCH (a)-[:CodeRelation {type: 'CALLS'}]->(b:Function {name: "validateUser"}) RETURN a.name, a.filePath
+
+• Find community members:
+  MATCH (f)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community) WHERE c.heuristicLabel = "Auth" RETURN f.name
+
+• Trace a process:
+  MATCH (s)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process) WHERE p.heuristicLabel = "UserLogin" RETURN s.name, r.step ORDER BY r.step
+
+OUTPUT: Returns { markdown, row_count } — results formatted as a Markdown table for easy reading.
+
+TIPS:
+- All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
+- Community = auto-detected functional area (Leiden algorithm)
+- Process = execution flow trace from entry point to terminal
 - Use heuristicLabel (not label) for human-readable community/process names`,
         inputSchema: {
             type: 'object',
@@ -92,12 +92,12 @@ TIPS:
     },
     {
         name: 'context',
-        description: `360-degree view of a single code symbol.
-Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
-
-WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
-AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
-
+        description: `360-degree view of a single code symbol.
+Shows categorized incoming/outgoing references (calls, imports, extends, implements), process participation, and file location.
+
+WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
+AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
+
 Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.`,
         inputSchema: {
             type: 'object',
@@ -113,12 +113,12 @@ Handles disambiguation: if multiple symbols share the same name, returns candida
     },
     {
         name: 'detect_changes',
-        description: `Analyze uncommitted git changes and find affected execution flows.
-Maps git diff hunks to indexed symbols, then traces which processes are impacted.
-
-WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
-AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
-
+        description: `Analyze uncommitted git changes and find affected execution flows.
+Maps git diff hunks to indexed symbols, then traces which processes are impacted.
+
+WHEN TO USE: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.
+AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.
+
 Returns: changed symbols, affected processes, and a risk summary.`,
         inputSchema: {
             type: 'object',
@@ -132,14 +132,14 @@ Returns: changed symbols, affected processes, and a risk summary.`,
     },
     {
         name: 'rename',
-        description: `Multi-file coordinated rename using the knowledge graph + text search.
-Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
-
-WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
-AFTER THIS: Run detect_changes() to verify no unexpected side effects.
-
-Each edit is tagged with confidence:
-- "graph": found via knowledge graph relationships (high confidence, safe to accept)
+        description: `Multi-file coordinated rename using the knowledge graph + text search.
+Finds all references via graph (high confidence) and regex text search (lower confidence). Preview by default.
+
+WHEN TO USE: Renaming a function, class, method, or variable across the codebase. Safer than find-and-replace.
+AFTER THIS: Run detect_changes() to verify no unexpected side effects.
+
+Each edit is tagged with confidence:
+- "graph": found via knowledge graph relationships (high confidence, safe to accept)
 - "text_search": found via regex text search (lower confidence, review carefully)`,
         inputSchema: {
             type: 'object',
@@ -156,25 +156,25 @@ Each edit is tagged with confidence:
     },
     {
         name: 'impact',
-        description: `Analyze the blast radius of changing a code symbol.
-Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
-
-WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
-AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
-
-Output includes:
-- risk: LOW / MEDIUM / HIGH / CRITICAL
-- summary: direct callers, processes affected, modules affected
-- affected_processes: which execution flows break and at which step
-- affected_modules: which functional areas are hit (direct vs indirect)
-- byDepth: all affected symbols grouped by traversal depth
-
-Depth groups:
-- d=1: WILL BREAK (direct callers/importers)
-- d=2: LIKELY AFFECTED (indirect)
-- d=3: MAY NEED TESTING (transitive)
-
-EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
+        description: `Analyze the blast radius of changing a code symbol.
+Returns affected symbols grouped by depth, plus risk assessment, affected execution flows, and affected modules.
+
+WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
+AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.
+
+Output includes:
+- risk: LOW / MEDIUM / HIGH / CRITICAL
+- summary: direct callers, processes affected, modules affected
+- affected_processes: which execution flows break and at which step
+- affected_modules: which functional areas are hit (direct vs indirect)
+- byDepth: all affected symbols grouped by traversal depth
+
+Depth groups:
+- d=1: WILL BREAK (direct callers/importers)
+- d=2: LIKELY AFFECTED (indirect)
+- d=3: MAY NEED TESTING (transitive)
+
+EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS
 Confidence: 1.0 = certain, <0.8 = fuzzy match`,
         inputSchema: {
             type: 'object',

package/hooks/claude/gitnexus-hook.cjs

@@ -1,155 +1,155 @@
-#!/usr/bin/env node
-/**
- * GitNexus Claude Code Hook
- *
- * PreToolUse handler — intercepts Grep/Glob/Bash searches
- * and augments with graph context from the GitNexus index.
- *
- * 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 { execFileSync } = require('child_process');
-
-/**
- * Read JSON input from stdin synchronously.
- */
-function readInput() {
-  try {
-    const data = fs.readFileSync(0, 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Check if a directory (or ancestor) has a .gitnexus index.
- */
-function findGitNexusIndex(startDir) {
-  let dir = startDir || process.cwd();
-  for (let i = 0; i < 5; i++) {
-    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
-      return true;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return false;
-}
-
-/**
- * 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;
-}
-
-function main() {
-  try {
-    const input = readInput();
-    const hookEvent = input.hook_event_name || '';
-
-    if (hookEvent !== 'PreToolUse') return;
-
-    const cwd = input.cwd || process.cwd();
-    if (!findGitNexusIndex(cwd)) 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;
-
-    // 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
-      }
-    }
-
-    // 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'] }
-        );
-      }
-      result = child.stderr || '';
-    } catch { /* graceful failure */ }
-
-    if (result && result.trim()) {
-      console.log(JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          additionalContext: result.trim()
-        }
-      }));
-    }
-  } catch (err) {
-    // Graceful failure — log to stderr for debugging
-    console.error('GitNexus hook error:', err.message);
-  }
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * GitNexus Claude Code Hook
+ *
+ * PreToolUse handler — intercepts Grep/Glob/Bash searches
+ * and augments with graph context from the GitNexus index.
+ *
+ * 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 { execFileSync } = require('child_process');
+
+/**
+ * Read JSON input from stdin synchronously.
+ */
+function readInput() {
+  try {
+    const data = fs.readFileSync(0, 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check if a directory (or ancestor) has a .gitnexus index.
+ */
+function findGitNexusIndex(startDir) {
+  let dir = startDir || process.cwd();
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(dir, '.gitnexus'))) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+/**
+ * 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;
+}
+
+function main() {
+  try {
+    const input = readInput();
+    const hookEvent = input.hook_event_name || '';
+
+    if (hookEvent !== 'PreToolUse') return;
+
+    const cwd = input.cwd || process.cwd();
+    if (!findGitNexusIndex(cwd)) 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;
+
+    // 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
+      }
+    }
+
+    // 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'] }
+        );
+      }
+      result = child.stderr || '';
+    } catch { /* graceful failure */ }
+
+    if (result && result.trim()) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: result.trim()
+        }
+      }));
+    }
+  } catch (err) {
+    // Graceful failure — log to stderr for debugging
+    console.error('GitNexus hook error:', err.message);
+  }
+}
+
+main();