gitnexus 1.1.9 → 1.2.0

package/README.md

@@ -18,31 +18,37 @@ AI coding tools don't understand your codebase structure. They edit a function w
 ## Quick Start
 
 ```bash
-# Install
-npm install -g gitnexus
+# Index your repo (run from repo root)
+npx gitnexus analyze
+```
 
-# One-time: configure MCP for your editors
-gitnexus setup
+That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-# Index your repository (run from repo root)
-gitnexus analyze
+To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-# Done! Open your editor — MCP connects automatically.
-```
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
 
-Or without installing globally:
+### Editor Support
 
-```bash
-npx gitnexus setup       # one-time
-npx gitnexus analyze     # per repo
-```
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Windsurf** | Yes | — | — | MCP |
+| **OpenCode** | Yes | Yes | — | MCP + Skills |
 
-The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
 
 ## MCP Setup (manual)
 
 If you prefer to configure manually instead of using `gitnexus setup`:
 
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -58,12 +64,6 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 }
 ```
 
-### Claude Code
-
-```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
-```
-
 ### OpenCode
 
 Add to `~/.config/opencode/config.json`:
@@ -100,68 +100,59 @@ Your AI agent gets these tools automatically:
 | Tool | What It Does | `repo` Param |
 |------|-------------|--------------|
 | `list_repos` | Discover all indexed repositories | — |
-| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
-| `overview` | List all clusters and processes | Optional |
-| `explore` | Deep dive on a symbol, cluster, or process | Optional |
-| `impact` | Blast radius analysis | Optional |
+| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional |
+| `context` | 360-degree symbol view — categorized refs, process participation | Optional |
+| `impact` | Blast radius analysis with depth grouping and confidence | Optional |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional |
+| `rename` | Multi-file coordinated rename with graph + text search | Optional |
 | `cypher` | Raw Cypher graph queries | Optional |
-| `analyze` | Index or re-index a repository | Optional |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
 
 ## MCP Resources
 
 | Resource | Purpose |
 |----------|---------|
 | `gitnexus://repos` | List all indexed repositories (read first) |
-| `gitnexus://repo/{name}/context` | Codebase stats and overview |
-| `gitnexus://repo/{name}/clusters` | All functional clusters |
+| `gitnexus://repo/{name}/context` | Codebase stats, staleness check, and available tools |
+| `gitnexus://repo/{name}/clusters` | All functional clusters with cohesion scores |
 | `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
 | `gitnexus://repo/{name}/processes` | All execution flows |
-| `gitnexus://repo/{name}/process/{name}` | Full process trace |
+| `gitnexus://repo/{name}/process/{name}` | Full process trace with steps |
 | `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
 
+## MCP Prompts
+
+| Prompt | What It Does |
+|--------|-------------|
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level |
+| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams |
+
 ## CLI Commands
 
 ```bash
-gitnexus setup                # Configure MCP for your editors (one-time)
-gitnexus analyze [path]       # Index a repository (or update stale index)
-gitnexus analyze --force      # Force full re-index
-gitnexus mcp                  # Start MCP server (stdio) — serves all indexed repos
-gitnexus serve                # Start HTTP server for web UI
-gitnexus list                 # List all indexed repositories
-gitnexus status               # Show index status for current repo
-gitnexus clean                # Delete index for current repo
-gitnexus clean --all          # Delete all indexes
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start HTTP server for web UI
+gitnexus list                    # List all indexed repositories
+gitnexus status                  # Show index status for current repo
+gitnexus clean                   # Delete index for current repo
+gitnexus clean --all --force     # Delete all indexes
+gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 ```
 
 ## Multi-Repo Support
 
-GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections (max 5 concurrent, evicted after 5 minutes idle).
 
 ## Supported Languages
 
 TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
 
-## How Impact Analysis Works
-
-```
-gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
-
-TARGET: Class UserService (src/services/user.ts)
-
-UPSTREAM (what depends on this):
-  Depth 1 (direct callers):
-    handleLogin [CALLS 90%] → src/api/auth.ts:45
-    handleRegister [CALLS 90%] → src/api/auth.ts:78
-  Depth 2:
-    authRouter [IMPORTS] → src/routes/auth.ts
-
-8 files affected, 3 clusters touched
-```
-
-Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
-
 ## Agent Skills
 
 GitNexus ships with skill files that teach AI agents how to use the tools effectively:
@@ -171,7 +162,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
 
-These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
 
 ## Requirements
 

package/dist/cli/analyze.js

@@ -6,14 +6,16 @@
 import path from 'path';
 import cliProgress from 'cli-progress';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
-import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex } from '../core/kuzu/kuzu-adapter.js';
+import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex, loadCachedEmbeddings } from '../core/kuzu/kuzu-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
 import { disposeEmbedder } from '../core/embeddings/embedder.js';
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath, getGlobalDir } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
 import { registerClaudeHook } from './claude-hooks.js';
+/** Threshold: auto-skip embeddings for repos with more nodes than this */
+const EMBEDDING_NODE_LIMIT = 50_000;
 const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -23,7 +25,11 @@ const PHASE_LABELS = {
     heritage: 'Extracting inheritance',
     communities: 'Detecting communities',
     processes: 'Detecting processes',
-    complete: 'Complete',
+    complete: 'Pipeline complete',
+    kuzu: 'Loading into KuzuDB',
+    fts: 'Creating search indexes',
+    embeddings: 'Generating embeddings',
+    done: 'Done',
 };
 export const analyzeCommand = async (inputPath, options) => {
     console.log('\n  GitNexus Analyzer\n');
@@ -34,14 +40,14 @@ export const analyzeCommand = async (inputPath, options) => {
     else {
         const gitRoot = getGitRoot(process.cwd());
         if (!gitRoot) {
-            console.log('  ✗ Not inside a git repository\n');
+            console.log('  Not inside a git repository\n');
             process.exitCode = 1;
             return;
         }
         repoPath = gitRoot;
     }
     if (!isGitRepo(repoPath)) {
-        console.log('  ✗ Not a git repository\n');
+        console.log('  Not a git repository\n');
         process.exitCode = 1;
         return;
     }
@@ -49,35 +55,70 @@ export const analyzeCommand = async (inputPath, options) => {
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
     if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit) {
-        console.log('  ✓ Repository already up to date\n');
+        console.log('  Already up to date\n');
         return;
     }
-    const multibar = new cliProgress.MultiBar({
+    // Single progress bar for entire pipeline
+    const bar = new cliProgress.SingleBar({
         format: '  {bar} {percentage}% | {phase}',
-        barCompleteChar: '█',
-        barIncompleteChar: '░',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
         hideCursor: true,
         barGlue: '',
         autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
     }, cliProgress.Presets.shades_grey);
-    const progressBar = multibar.create(100, 0, { phase: 'Initializing...' });
+    bar.start(100, 0, { phase: 'Initializing...' });
+    const t0Global = Date.now();
+    // ── Cache embeddings from existing index before rebuild ────────────
+    let cachedEmbeddingNodeIds = new Set();
+    let cachedEmbeddings = [];
+    if (existingMeta && !options?.force) {
+        try {
+            bar.update(0, { phase: 'Caching embeddings...' });
+            await initKuzu(kuzuPath);
+            const cached = await loadCachedEmbeddings();
+            cachedEmbeddingNodeIds = cached.embeddingNodeIds;
+            cachedEmbeddings = cached.embeddings;
+            await closeKuzu();
+        }
+        catch {
+            try {
+                await closeKuzu();
+            }
+            catch { }
+        }
+    }
+    // ── Phase 1: Full Pipeline (0–60%) ─────────────────────────────────
     const pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
         const phaseLabel = PHASE_LABELS[progress.phase] || progress.phase;
-        progressBar.update(progress.percent, { phase: phaseLabel });
+        const scaled = Math.round(progress.percent * 0.6);
+        bar.update(scaled, { phase: phaseLabel });
     });
-    progressBar.update(100, { phase: 'Loading graph into KuzuDB...' });
+    // ── Phase 2: KuzuDB (60–85%) ──────────────────────────────────────
+    bar.update(60, { phase: 'Loading into KuzuDB...' });
     await closeKuzu();
-    const fsClean = await import('fs/promises');
     const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
     for (const f of kuzuFiles) {
         try {
-            await fsClean.rm(f, { recursive: true, force: true });
+            await fs.rm(f, { recursive: true, force: true });
         }
-        catch { /* may not exist */ }
+        catch { }
     }
+    const t0Kuzu = Date.now();
     await initKuzu(kuzuPath);
-    await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath);
-    progressBar.update(100, { phase: 'Creating search indexes...' });
+    let kuzuMsgCount = 0;
+    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath, (msg) => {
+        kuzuMsgCount++;
+        const progress = Math.min(84, 60 + Math.round((kuzuMsgCount / (kuzuMsgCount + 10)) * 24));
+        bar.update(progress, { phase: msg });
+    });
+    const kuzuTime = ((Date.now() - t0Kuzu) / 1000).toFixed(1);
+    const kuzuWarnings = kuzuResult.warnings;
+    // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
+    bar.update(85, { phase: 'Creating search indexes...' });
+    const t0Fts = Date.now();
     try {
         await createFTSIndex('File', 'file_fts', ['name', 'content']);
         await createFTSIndex('Function', 'function_fts', ['name', 'content']);
@@ -86,15 +127,47 @@ export const analyzeCommand = async (inputPath, options) => {
         await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
     }
     catch (e) {
-        console.error('  Note: Some FTS indexes may not have been created:', e.message);
+        // Non-fatal — FTS is best-effort
     }
-    if (!options?.skipEmbeddings) {
-        progressBar.update(100, { phase: 'Generating embeddings...' });
-        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
-            progressBar.update(progress.percent, { phase: `Embeddings ${progress.percent}%` });
-        });
+    const ftsTime = ((Date.now() - t0Fts) / 1000).toFixed(1);
+    // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
+    if (cachedEmbeddings.length > 0) {
+        bar.update(88, { phase: `Restoring ${cachedEmbeddings.length} cached embeddings...` });
+        const EMBED_BATCH = 200;
+        for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
+            const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+            const paramsList = batch.map(e => ({ nodeId: e.nodeId, embedding: e.embedding }));
+            try {
+                await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+            }
+            catch { /* some may fail if node was removed, that's fine */ }
+        }
     }
+    // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
     const stats = await getKuzuStats();
+    let embeddingTime = '0.0';
+    let embeddingSkipped = false;
+    let embeddingSkipReason = '';
+    if (options?.skipEmbeddings) {
+        embeddingSkipped = true;
+        embeddingSkipReason = 'skipped (--skip-embeddings)';
+    }
+    else if (stats.nodes > EMBEDDING_NODE_LIMIT) {
+        embeddingSkipped = true;
+        embeddingSkipReason = `skipped (${stats.nodes.toLocaleString()} nodes > ${EMBEDDING_NODE_LIMIT.toLocaleString()} limit)`;
+    }
+    if (!embeddingSkipped) {
+        bar.update(90, { phase: 'Loading embedding model...' });
+        const t0Emb = Date.now();
+        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
+            const scaled = 90 + Math.round((progress.percent / 100) * 8);
+            const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
+            bar.update(scaled, { phase: label });
+        }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
+        embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
+    }
+    // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
+    bar.update(98, { phase: 'Saving metadata...' });
     const meta = {
         repoPath,
         lastCommit: currentCommit,
@@ -110,7 +183,6 @@ export const analyzeCommand = async (inputPath, options) => {
     await saveMeta(storagePath, meta);
     await registerRepo(repoPath, meta);
     await addToGitignore(repoPath);
-    // Auto-register Claude Code hook (idempotent)
     const hookResult = await registerClaudeHook();
     const projectName = path.basename(repoPath);
     let aggregatedClusterCount = 0;
@@ -132,17 +204,27 @@ export const analyzeCommand = async (inputPath, options) => {
     });
     await closeKuzu();
     await disposeEmbedder();
-    multibar.stop();
-    console.log('\n  ✓ Repository indexed successfully\n');
-    console.log(`  Path:     ${repoPath}`);
-    console.log(`  Storage:  ${storagePath}`);
-    console.log(`  Registry: ${getGlobalDir()}`);
-    console.log(`  Stats:    ${stats.nodes} nodes, ${stats.edges} edges, ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters, ${pipelineResult.processResult?.stats.totalProcesses || 0} processes`);
+    const totalTime = ((Date.now() - t0Global) / 1000).toFixed(1);
+    bar.update(100, { phase: 'Done' });
+    bar.stop();
+    // ── Summary ───────────────────────────────────────────────────────
+    const embeddingsCached = cachedEmbeddings.length > 0;
+    console.log(`\n  Repository indexed successfully (${totalTime}s)${embeddingsCached ? ` [${cachedEmbeddings.length} embeddings cached]` : ''}\n`);
+    console.log(`  ${stats.nodes.toLocaleString()} nodes | ${stats.edges.toLocaleString()} edges | ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters | ${pipelineResult.processResult?.stats.totalProcesses || 0} flows`);
+    console.log(`  KuzuDB ${kuzuTime}s | FTS ${ftsTime}s | Embeddings ${embeddingSkipped ? embeddingSkipReason : embeddingTime + 's'}`);
+    console.log(`  ${repoPath}`);
     if (aiContext.files.length > 0) {
-        console.log(`  Context:  ${aiContext.files.join(', ')}`);
+        console.log(`  Context: ${aiContext.files.join(', ')}`);
     }
     if (hookResult.registered) {
-        console.log(`  Hooks:    ${hookResult.message}`);
+        console.log(`  Hooks: ${hookResult.message}`);
+    }
+    // Show warnings (missing schema pairs, etc.) after the clean output
+    if (kuzuWarnings.length > 0) {
+        console.log(`\n  Warnings (${kuzuWarnings.length}):`);
+        for (const w of kuzuWarnings) {
+            console.log(`    ${w}`);
+        }
     }
     try {
         await fs.access(getGlobalRegistryPath());

package/dist/cli/eval-server.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Eval Server — Lightweight HTTP server for SWE-bench evaluation
+ *
+ * Keeps KuzuDB warm in memory so tool calls from the agent are near-instant.
+ * Designed to run inside Docker containers during SWE-bench evaluation.
+ *
+ * KEY DESIGN: Returns LLM-friendly text, not raw JSON.
+ * Raw JSON wastes tokens and is hard for models to parse. The text formatter
+ * converts structured results into compact, readable output that models
+ * can immediately act on. Next-step hints guide the agent through a
+ * productive tool-chaining workflow (query → context → impact → fix).
+ *
+ * Architecture:
+ *   Agent bash cmd → curl localhost:PORT/tool/query → eval-server → LocalBackend → format → text
+ *
+ * Usage:
+ *   gitnexus eval-server                    # default port 4848
+ *   gitnexus eval-server --port 4848        # explicit port
+ *   gitnexus eval-server --idle-timeout 300 # auto-shutdown after 300s idle
+ *
+ * API:
+ *   POST /tool/:name   — Call a tool. Body is JSON arguments. Returns formatted text.
+ *   GET  /health       — Health check. Returns {"status":"ok","repos":[...]}
+ *   POST /shutdown     — Graceful shutdown.
+ */
+export interface EvalServerOptions {
+    port?: string;
+    idleTimeout?: string;
+}
+export declare function evalServerCommand(options?: EvalServerOptions): Promise<void>;