@zuvia-software-solutions/code-mapper 1.4.0

package/dist/cli/eval-server.js

@@ -0,0 +1,365 @@
+// code-mapper/src/cli/eval-server.ts
+/**
+ * @file eval-server.ts
+ * @description Lightweight HTTP server for SWE-bench evaluation. Keeps LadybugDB warm in
+ * memory so tool calls from the agent are near-instant. Returns LLM-friendly text (not raw
+ * JSON) and appends next-step hints for productive tool chaining (query -> context -> impact)
+ *
+ * Architecture: Agent bash cmd -> curl localhost:PORT/tool/query -> eval-server -> LocalBackend -> format -> text
+ *
+ * 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
+ */
+import http from 'http';
+import { LocalBackend } from '../mcp/local/local-backend.js';
+// Text Formatters — convert structured JSON results into compact, LLM-friendly text
+export function formatQueryResult(result) {
+    if (result.error)
+        return `Error: ${result.error}`;
+    const lines = [];
+    const processes = result.processes || [];
+    const symbols = result.process_symbols || [];
+    const defs = result.definitions || [];
+    if (processes.length === 0 && defs.length === 0) {
+        return 'No matching execution flows found. Try a different search term or use grep.';
+    }
+    lines.push(`Found ${processes.length} execution flow(s):\n`);
+    for (let i = 0; i < processes.length; i++) {
+        const p = processes[i];
+        lines.push(`${i + 1}. ${p.summary} (${p.step_count} steps, ${p.symbol_count} symbols)`);
+        // Show symbols belonging to this process
+        const procSymbols = symbols.filter((s) => s.process_id === p.id);
+        for (const s of procSymbols.slice(0, 6)) {
+            const loc = s.startLine ? `:${s.startLine}` : '';
+            lines.push(`   ${s.type} ${s.name} → ${s.filePath}${loc}`);
+        }
+        if (procSymbols.length > 6) {
+            lines.push(`   ... and ${procSymbols.length - 6} more`);
+        }
+        lines.push('');
+    }
+    if (defs.length > 0) {
+        lines.push(`Standalone definitions:`);
+        for (const d of defs.slice(0, 8)) {
+            lines.push(`  ${d.type || 'Symbol'} ${d.name} → ${d.filePath || '?'}`);
+        }
+        if (defs.length > 8)
+            lines.push(`  ... and ${defs.length - 8} more`);
+    }
+    return lines.join('\n').trim();
+}
+export function formatContextResult(result) {
+    if (result.error)
+        return `Error: ${result.error}`;
+    if (result.status === 'ambiguous') {
+        const lines = [`Multiple symbols named '${result.candidates?.[0]?.name || '?'}'. Disambiguate with file path:\n`];
+        for (const c of result.candidates || []) {
+            lines.push(`  ${c.kind} ${c.name} → ${c.filePath}:${c.line || '?'}  (uid: ${c.uid})`);
+        }
+        lines.push(`\nRe-run: code-mapper-context "${result.candidates?.[0]?.name}" "<file_path>"`);
+        return lines.join('\n');
+    }
+    const sym = result.symbol;
+    if (!sym)
+        return 'Symbol not found.';
+    const lines = [];
+    const loc = sym.startLine ? `:${sym.startLine}-${sym.endLine}` : '';
+    lines.push(`${sym.kind} ${sym.name} → ${sym.filePath}${loc}`);
+    lines.push('');
+    // Incoming refs (who calls/imports/extends this symbol)
+    const incoming = result.incoming || {};
+    const incomingCount = Object.values(incoming).reduce((sum, arr) => sum + arr.length, 0);
+    if (incomingCount > 0) {
+        lines.push(`Called/imported by (${incomingCount}):`);
+        for (const [relType, refs] of Object.entries(incoming)) {
+            for (const ref of refs.slice(0, 10)) {
+                lines.push(`  ← [${relType}] ${ref.kind} ${ref.name} → ${ref.filePath}`);
+            }
+        }
+        lines.push('');
+    }
+    // Outgoing refs (what this symbol calls/imports)
+    const outgoing = result.outgoing || {};
+    const outgoingCount = Object.values(outgoing).reduce((sum, arr) => sum + arr.length, 0);
+    if (outgoingCount > 0) {
+        lines.push(`Calls/imports (${outgoingCount}):`);
+        for (const [relType, refs] of Object.entries(outgoing)) {
+            for (const ref of refs.slice(0, 10)) {
+                lines.push(`  → [${relType}] ${ref.kind} ${ref.name} → ${ref.filePath}`);
+            }
+        }
+        lines.push('');
+    }
+    // Processes
+    const procs = result.processes || [];
+    if (procs.length > 0) {
+        lines.push(`Participates in ${procs.length} execution flow(s):`);
+        for (const p of procs) {
+            lines.push(`  • ${p.name} (step ${p.step_index}/${p.step_count})`);
+        }
+    }
+    if (sym.content) {
+        lines.push('');
+        lines.push(`Source:`);
+        lines.push(sym.content);
+    }
+    return lines.join('\n').trim();
+}
+export function formatImpactResult(result) {
+    if (result.error)
+        return `Error: ${result.error}`;
+    const target = result.target;
+    const direction = result.direction;
+    const byDepth = result.byDepth || {};
+    const total = result.impactedCount || 0;
+    if (total === 0) {
+        return `${target?.name || '?'}: No ${direction} dependencies found. This symbol appears isolated.`;
+    }
+    const lines = [];
+    const dirLabel = direction === 'upstream' ? 'depends on this (will break if changed)' : 'this depends on';
+    lines.push(`Blast radius for ${target?.kind || ''} ${target?.name} (${direction}): ${total} symbol(s) ${dirLabel}\n`);
+    const depthLabels = {
+        1: 'WILL BREAK (direct)',
+        2: 'LIKELY AFFECTED (indirect)',
+        3: 'MAY NEED TESTING (transitive)',
+    };
+    for (const depth of [1, 2, 3]) {
+        const items = byDepth[depth];
+        if (!items || items.length === 0)
+            continue;
+        lines.push(`d=${depth}: ${depthLabels[depth] || ''} (${items.length})`);
+        for (const item of items.slice(0, 12)) {
+            const conf = item.confidence < 1 ? ` (conf: ${item.confidence})` : '';
+            lines.push(`  ${item.type} ${item.name} → ${item.filePath} [${item.relationType}]${conf}`);
+        }
+        if (items.length > 12) {
+            lines.push(`  ... and ${items.length - 12} more`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+export function formatCypherResult(result) {
+    if (result.error)
+        return `Error: ${result.error}`;
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return 'Query returned 0 rows.';
+        // Format as a simple table
+        const keys = Object.keys(result[0]);
+        const lines = [`${result.length} row(s):\n`];
+        for (const row of result.slice(0, 30)) {
+            const parts = keys.map(k => `${k}: ${row[k]}`);
+            lines.push(`  ${parts.join(' | ')}`);
+        }
+        if (result.length > 30) {
+            lines.push(`  ... ${result.length - 30} more rows`);
+        }
+        return lines.join('\n');
+    }
+    return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+}
+export function formatDetectChangesResult(result) {
+    if (result.error)
+        return `Error: ${result.error}`;
+    const summary = result.summary || {};
+    const lines = [];
+    if (summary.changed_count === 0) {
+        return 'No changes detected.';
+    }
+    lines.push(`Changes: ${summary.changed_files || 0} files, ${summary.changed_count || 0} symbols`);
+    lines.push(`Affected processes: ${summary.affected_count || 0}`);
+    lines.push(`Risk level: ${summary.risk_level || 'unknown'}\n`);
+    const changed = result.changed_symbols || [];
+    if (changed.length > 0) {
+        lines.push(`Changed symbols:`);
+        for (const s of changed.slice(0, 15)) {
+            lines.push(`  ${s.type} ${s.name} → ${s.filePath}`);
+        }
+        if (changed.length > 15)
+            lines.push(`  ... and ${changed.length - 15} more`);
+        lines.push('');
+    }
+    const affected = result.affected_processes || [];
+    if (affected.length > 0) {
+        lines.push(`Affected execution flows:`);
+        for (const p of affected.slice(0, 10)) {
+            const steps = (p.changed_steps || []).map((s) => s.symbol).join(', ');
+            lines.push(`  • ${p.name} (${p.step_count} steps) — changed: ${steps}`);
+        }
+    }
+    return lines.join('\n').trim();
+}
+export function formatListReposResult(result) {
+    if (!Array.isArray(result) || result.length === 0) {
+        return 'No indexed repositories.';
+    }
+    const lines = ['Indexed repositories:\n'];
+    for (const r of result) {
+        const stats = r.stats || {};
+        lines.push(`  ${r.name} — ${stats.nodes || '?'} symbols, ${stats.edges || '?'} relationships, ${stats.processes || '?'} flows`);
+        lines.push(`    Path: ${r.path}`);
+        lines.push(`    Indexed: ${r.indexedAt}`);
+    }
+    return lines.join('\n');
+}
+/** Format a tool result as compact, LLM-friendly text */
+function formatToolResult(toolName, result) {
+    switch (toolName) {
+        case 'query': return formatQueryResult(result);
+        case 'context': return formatContextResult(result);
+        case 'impact': return formatImpactResult(result);
+        case 'cypher': return formatCypherResult(result);
+        case 'detect_changes': return formatDetectChangesResult(result);
+        case 'list_repos': return formatListReposResult(result);
+        default: return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    }
+}
+// Next-step hints — guide the agent to the logical next tool call
+// Critical for tool chaining: query -> context -> impact -> fix
+function getNextStepHint(toolName) {
+    switch (toolName) {
+        case 'query':
+            return '\n---\nNext: Pick a symbol above and run code-mapper-context "<name>" to see all its callers, callees, and execution flows.';
+        case 'context':
+            return '\n---\nNext: To check what breaks if you change this, run code-mapper-impact "<name>" upstream';
+        case 'impact':
+            return '\n---\nNext: Review d=1 items first (WILL BREAK). Read the source with cat to understand the code, then make your fix.';
+        case 'cypher':
+            return '\n---\nNext: To explore a result symbol in depth, run code-mapper-context "<name>"';
+        case 'detect_changes':
+            return '\n---\nNext: Run code-mapper-context "<symbol>" on high-risk changed symbols to check their callers.';
+        default:
+            return '';
+    }
+}
+// Server
+export async function evalServerCommand(options) {
+    const port = parseInt(options?.port || '4848');
+    const idleTimeoutSec = parseInt(options?.idleTimeout || '0');
+    const backend = new LocalBackend();
+    const ok = await backend.init();
+    if (!ok) {
+        console.error('Code Mapper eval-server: No indexed repositories found. Run: code-mapper analyze');
+        process.exit(1);
+    }
+    const repos = await backend.listRepos();
+    console.error(`Code Mapper eval-server: ${repos.length} repo(s) loaded: ${repos.map(r => r.name).join(', ')}`);
+    let idleTimer = null;
+    function resetIdleTimer() {
+        if (idleTimeoutSec <= 0)
+            return;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(async () => {
+            console.error('Code Mapper eval-server: Idle timeout reached, shutting down');
+            await backend.disconnect();
+            process.exit(0);
+        }, idleTimeoutSec * 1000);
+    }
+    const server = http.createServer(async (req, res) => {
+        resetIdleTimer();
+        try {
+            // GET /health
+            if (req.method === 'GET' && req.url === '/health') {
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(200);
+                res.end(JSON.stringify({ status: 'ok', repos: repos.map(r => r.name) }));
+                return;
+            }
+            // POST /shutdown
+            if (req.method === 'POST' && req.url === '/shutdown') {
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(200);
+                res.end(JSON.stringify({ status: 'shutting_down' }));
+                setTimeout(async () => {
+                    await backend.disconnect();
+                    server.close();
+                    process.exit(0);
+                }, 100);
+                return;
+            }
+            // POST /tool/:name
+            const toolMatch = req.url?.match(/^\/tool\/(\w+)$/);
+            if (req.method === 'POST' && toolMatch) {
+                const toolName = toolMatch[1];
+                const body = await readBody(req);
+                let args = {};
+                if (body.trim()) {
+                    try {
+                        args = JSON.parse(body);
+                    }
+                    catch {
+                        res.setHeader('Content-Type', 'text/plain');
+                        res.writeHead(400);
+                        res.end('Error: Invalid JSON body');
+                        return;
+                    }
+                }
+                // Call tool, format result as text, append next-step hint for chaining
+                const result = await backend.callTool(toolName, args);
+                const formatted = formatToolResult(toolName, result);
+                const hint = getNextStepHint(toolName);
+                res.setHeader('Content-Type', 'text/plain');
+                res.writeHead(200);
+                res.end(formatted + hint);
+                return;
+            }
+            // Not found
+            res.setHeader('Content-Type', 'text/plain');
+            res.writeHead(404);
+            res.end('Not found. Use POST /tool/:name or GET /health');
+        }
+        catch (err) {
+            res.setHeader('Content-Type', 'text/plain');
+            res.writeHead(500);
+            res.end(`Error: ${err.message || 'Internal error'}`);
+        }
+    });
+    server.listen(port, '127.0.0.1', () => {
+        console.error(`Code Mapper eval-server: listening on http://127.0.0.1:${port}`);
+        console.error(`  POST /tool/query    — search execution flows`);
+        console.error(`  POST /tool/context  — 360-degree symbol view`);
+        console.error(`  POST /tool/impact   — blast radius analysis`);
+        console.error(`  POST /tool/cypher   — raw Cypher query`);
+        console.error(`  GET  /health        — health check`);
+        console.error(`  POST /shutdown      — graceful shutdown`);
+        if (idleTimeoutSec > 0) {
+            console.error(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
+        }
+        try {
+            process.stdout.write(`CODE_MAPPER_EVAL_SERVER_READY:${port}\n`);
+        }
+        catch {
+            // stdout may be unavailable in some environments
+        }
+    });
+    resetIdleTimer();
+    const shutdown = async () => {
+        console.error('Code Mapper eval-server: shutting down...');
+        await backend.disconnect();
+        server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+export const MAX_BODY_SIZE = 1024 * 1024; // 1 MB
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                req.destroy(new Error('Request body too large (max 1MB)'));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        req.on('error', reject);
+    });
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * @file CLI entry point — registers all commands via Commander
+ * @description Heap re-spawn removed; only analyze.ts needs the 8GB heap via ensureHeap()
+ */
+export {};

package/dist/cli/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// code-mapper/src/cli/index.ts
+/**
+ * @file CLI entry point — registers all commands via Commander
+ * @description Heap re-spawn removed; only analyze.ts needs the 8GB heap via ensureHeap()
+ */
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+import { createLazyAction } from './lazy-action.js';
+const _require = createRequire(import.meta.url);
+const pkg = _require('../../package.json');
+const program = new Command();
+program
+    .name('code-mapper')
+    .description('Code Mapper local CLI and MCP server')
+    .version(pkg.version);
+program
+    .command('setup')
+    .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode')
+    .action(createLazyAction(() => import('./setup.js'), 'setupCommand'));
+program
+    .command('analyze [path]')
+    .description('Index a repository (full analysis)')
+    .option('-f, --force', 'Force full re-index even if up to date')
+    .option('--embeddings', 'Enable embedding generation for semantic search (on by default)', true)
+    .option('--no-embeddings', 'Skip embedding generation')
+    .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
+    .addHelpText('after', '\nEnvironment variables:\n  CODE_MAPPER_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .code-mapperignore)')
+    .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
+program
+    .command('serve')
+    .description('Start local HTTP server for web UI connection')
+    .option('-p, --port <port>', 'Port number', '4747')
+    .option('--host <host>', 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)')
+    .action(createLazyAction(() => import('./serve.js'), 'serveCommand'));
+program
+    .command('mcp')
+    .description('Start MCP server (stdio) — serves all indexed repos')
+    .option('--tsgo', 'Enable tsgo semantic resolution for confidence-1.0 call edges')
+    .action(createLazyAction(() => import('./mcp.js'), 'mcpCommand'));
+program
+    .command('list')
+    .description('List all indexed repositories')
+    .action(createLazyAction(() => import('./list.js'), 'listCommand'));
+program
+    .command('status')
+    .description('Show index status for current repo')
+    .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
+program
+    .command('clean')
+    .description('Delete Code Mapper index for current repo')
+    .option('-f, --force', 'Skip confirmation prompt')
+    .option('--all', 'Clean all indexed repos')
+    .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
+program
+    .command('refresh')
+    .description('Incremental re-index: only update files changed since last commit')
+    .option('-s, --scope <scope>', 'What to refresh: committed (default), staged, unstaged', 'committed')
+    .action(createLazyAction(() => import('./refresh.js'), 'refreshCommand'));
+program
+    .command('augment <pattern>')
+    .description('Augment a search pattern with knowledge graph context (used by hooks)')
+    .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
+// Direct tool commands — invoke LocalBackend directly (no MCP overhead)
+program
+    .command('query <search_query>')
+    .description('Search the knowledge graph for execution flows related to a concept')
+    .option('-r, --repo <name>', 'Target repository (omit if only one indexed)')
+    .option('-c, --context <text>', 'Task context to improve ranking')
+    .option('-g, --goal <text>', 'What you want to find')
+    .option('-l, --limit <n>', 'Max processes to return (default: 5)')
+    .option('--content', 'Include full symbol source code')
+    .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
+program
+    .command('context [name]')
+    .description('360-degree view of a code symbol: callers, callees, processes')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
+    .option('-f, --file <path>', 'File path to disambiguate common names')
+    .option('--content', 'Include full symbol source code')
+    .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
+program
+    .command('impact <target>')
+    .description('Blast radius analysis: what breaks if you change a symbol')
+    .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
+    .option('-r, --repo <name>', 'Target repository')
+    .option('--depth <n>', 'Max relationship depth (default: 3)')
+    .option('--include-tests', 'Include test files in results')
+    .action(createLazyAction(() => import('./tool.js'), 'impactCommand'));
+program
+    .command('cypher <query>')
+    .description('Execute raw Cypher query against the knowledge graph')
+    .option('-r, --repo <name>', 'Target repository')
+    .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
+// Eval server — persistent daemon for SWE-bench evaluation
+program
+    .command('eval-server')
+    .description('Start lightweight HTTP server for fast tool calls during evaluation')
+    .option('-p, --port <port>', 'Port number', '4848')
+    .option('--idle-timeout <seconds>', 'Auto-shutdown after N seconds idle (0 = disabled)', '0')
+    .action(createLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
+program.parse(process.argv);

package/dist/cli/lazy-action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file lazy-action.ts
+ * @description Creates a lazy-loaded CLI action that defers module import until invocation
+ * Generic constraints ensure the export name is a valid key of the module at compile time
+ */
+export declare function createLazyAction<TModule extends Record<string, unknown>, TKey extends string & keyof TModule>(loader: () => Promise<TModule>, exportName: TKey): (...args: unknown[]) => Promise<void>;

package/dist/cli/lazy-action.js

@@ -0,0 +1,19 @@
+// code-mapper/src/cli/lazy-action.ts
+/**
+ * @file lazy-action.ts
+ * @description Creates a lazy-loaded CLI action that defers module import until invocation
+ * Generic constraints ensure the export name is a valid key of the module at compile time
+ */
+function isCallable(value) {
+    return typeof value === 'function';
+}
+export function createLazyAction(loader, exportName) {
+    return async (...args) => {
+        const module = await loader();
+        const action = module[exportName];
+        if (!isCallable(action)) {
+            throw new Error(`Lazy action export not found: ${exportName}`);
+        }
+        await action(...args);
+    };
+}

package/dist/cli/list.d.ts

@@ -0,0 +1,2 @@
+/** @file list.ts @description Shows all indexed repositories from the global registry */
+export declare const listCommand: () => Promise<void>;

package/dist/cli/list.js

@@ -0,0 +1,27 @@
+// code-mapper/src/cli/list.ts
+/** @file list.ts @description Shows all indexed repositories from the global registry */
+import { listRegisteredRepos } from '../storage/repo-manager.js';
+export const listCommand = async () => {
+    const entries = await listRegisteredRepos({ validate: true });
+    if (entries.length === 0) {
+        console.log('No indexed repositories found.');
+        console.log('Run `code-mapper analyze` in a git repo to index it.');
+        return;
+    }
+    console.log(`\n  Indexed Repositories (${entries.length})\n`);
+    for (const entry of entries) {
+        const indexedDate = new Date(entry.indexedAt).toLocaleString();
+        const stats = entry.stats || {};
+        const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
+        console.log(`  ${entry.name}`);
+        console.log(`    Path:    ${entry.path}`);
+        console.log(`    Indexed: ${indexedDate}`);
+        console.log(`    Commit:  ${commitShort}`);
+        console.log(`    Stats:   ${stats.files ?? 0} files, ${stats.nodes ?? 0} symbols, ${stats.edges ?? 0} edges`);
+        if (stats.communities)
+            console.log(`    Clusters:   ${stats.communities}`);
+        if (stats.processes)
+            console.log(`    Processes:  ${stats.processes}`);
+        console.log('');
+    }
+};

package/dist/cli/mcp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file mcp.ts
+ * @description Starts the MCP server in standalone mode. Loads all indexed repos from the
+ * global registry — works from any directory
+ */
+export declare const mcpCommand: (opts?: {
+    tsgo?: boolean;
+}) => Promise<void>;

package/dist/cli/mcp.js

@@ -0,0 +1,35 @@
+// code-mapper/src/cli/mcp.ts
+/**
+ * @file mcp.ts
+ * @description Starts the MCP server in standalone mode. Loads all indexed repos from the
+ * global registry — works from any directory
+ */
+import { startMCPServer } from '../mcp/server.js';
+import { LocalBackend } from '../mcp/local/local-backend.js';
+export const mcpCommand = async (opts) => {
+    // Prevent unhandled errors from crashing the MCP server process
+    // LadybugDB lock conflicts and transient errors should degrade gracefully
+    process.on('uncaughtException', (err) => {
+        console.error(`Code Mapper MCP: uncaught exception — ${err.message}`);
+        // Process is in undefined state after uncaughtException — exit after flushing
+        setTimeout(() => process.exit(1), 100);
+    });
+    process.on('unhandledRejection', (reason) => {
+        const msg = reason instanceof Error ? reason.message : String(reason);
+        console.error(`Code Mapper MCP: unhandled rejection — ${msg}`);
+    });
+    // Initialize multi-repo backend from registry
+    // Starts even with 0 repos — tools call refreshRepos() lazily,
+    // so repos indexed after server start are discovered automatically
+    const backend = new LocalBackend();
+    await backend.init({ tsgo: opts?.tsgo });
+    const repos = await backend.listRepos();
+    if (repos.length === 0) {
+        console.error('Code Mapper: No indexed repos yet. Run `code-mapper analyze` in a git repo — the server will pick it up automatically.');
+    }
+    else {
+        console.error(`Code Mapper: MCP server starting with ${repos.length} repo(s): ${repos.map(r => r.name).join(', ')}`);
+    }
+    // Start MCP server (serves all repos, discovers new ones lazily)
+    await startMCPServer(backend);
+};

package/dist/cli/refresh.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file refresh.ts
+ * @description CLI command for incremental refresh — re-indexes only files
+ * changed since the last commit. Reuses the same RefreshCoordinator + child
+ * process architecture as the MCP server's auto-refresh.
+ *
+ * Usage: code-mapper refresh [--scope unstaged|staged|committed]
+ */
+export interface RefreshOptions {
+    scope?: 'unstaged' | 'staged' | 'committed';
+}
+export declare const refreshCommand: (options?: RefreshOptions) => Promise<void>;