gitnexus 1.0.0 → 1.1.0

package/dist/cli/setup.js

@@ -0,0 +1,166 @@
+/**
+ * Setup Command
+ *
+ * One-time global MCP configuration writer.
+ * Detects installed AI editors and writes the appropriate MCP config
+ * so the GitNexus MCP server is available in all projects.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { getGlobalDir } from '../storage/repo-manager.js';
+/**
+ * The MCP server entry for all editors
+ */
+function getMcpEntry() {
+    return {
+        command: 'npx',
+        args: ['-y', 'gitnexus', 'mcp'],
+    };
+}
+/**
+ * Merge gitnexus entry into an existing MCP config JSON object.
+ * Returns the updated config.
+ */
+function mergeMcpConfig(existing) {
+    if (!existing || typeof existing !== 'object') {
+        existing = {};
+    }
+    if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
+        existing.mcpServers = {};
+    }
+    existing.mcpServers.gitnexus = getMcpEntry();
+    return existing;
+}
+/**
+ * Try to read a JSON file, returning null if it doesn't exist or is invalid.
+ */
+async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write JSON to a file, creating parent directories if needed.
+ */
+async function writeJsonFile(filePath, data) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Check if a directory exists
+ */
+async function dirExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Editor-specific setup ─────────────────────────────────────────
+async function setupCursor(result) {
+    const cursorDir = path.join(os.homedir(), '.cursor');
+    if (!(await dirExists(cursorDir))) {
+        result.skipped.push('Cursor (not installed)');
+        return;
+    }
+    const mcpPath = path.join(cursorDir, 'mcp.json');
+    try {
+        const existing = await readJsonFile(mcpPath);
+        const updated = mergeMcpConfig(existing);
+        await writeJsonFile(mcpPath, updated);
+        result.configured.push('Cursor');
+    }
+    catch (err) {
+        result.errors.push(`Cursor: ${err.message}`);
+    }
+}
+async function setupClaudeCode(result) {
+    // Claude Code uses `claude mcp add` — we just print the command
+    // Check for common Claude Code indicators
+    const claudeDir = path.join(os.homedir(), '.claude');
+    const hasClaude = await dirExists(claudeDir);
+    if (!hasClaude) {
+        result.skipped.push('Claude Code (not installed)');
+        return;
+    }
+    // Claude Code uses a JSON settings file at ~/.claude.json or claude mcp add
+    console.log('');
+    console.log('  Claude Code detected. Run this command to add GitNexus:');
+    console.log('');
+    console.log('    claude mcp add gitnexus -- npx -y gitnexus mcp');
+    console.log('');
+    result.configured.push('Claude Code (manual step printed)');
+}
+async function setupOpenCode(result) {
+    const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
+    if (!(await dirExists(opencodeDir))) {
+        result.skipped.push('OpenCode (not installed)');
+        return;
+    }
+    const configPath = path.join(opencodeDir, 'config.json');
+    try {
+        const existing = await readJsonFile(configPath);
+        const config = existing || {};
+        if (!config.mcp)
+            config.mcp = {};
+        config.mcp.gitnexus = getMcpEntry();
+        await writeJsonFile(configPath, config);
+        result.configured.push('OpenCode');
+    }
+    catch (err) {
+        result.errors.push(`OpenCode: ${err.message}`);
+    }
+}
+// ─── Main command ──────────────────────────────────────────────────
+export const setupCommand = async () => {
+    console.log('');
+    console.log('  GitNexus Setup');
+    console.log('  ==============');
+    console.log('');
+    // Ensure global directory exists
+    const globalDir = getGlobalDir();
+    await fs.mkdir(globalDir, { recursive: true });
+    const result = {
+        configured: [],
+        skipped: [],
+        errors: [],
+    };
+    // Detect and configure each editor
+    await setupCursor(result);
+    await setupClaudeCode(result);
+    await setupOpenCode(result);
+    // Print results
+    if (result.configured.length > 0) {
+        console.log('  Configured:');
+        for (const name of result.configured) {
+            console.log(`    + ${name}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log('');
+        console.log('  Skipped:');
+        for (const name of result.skipped) {
+            console.log(`    - ${name}`);
+        }
+    }
+    if (result.errors.length > 0) {
+        console.log('');
+        console.log('  Errors:');
+        for (const err of result.errors) {
+            console.log(`    ! ${err}`);
+        }
+    }
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    1. cd into any git repo');
+    console.log('    2. Run: gitnexus analyze');
+    console.log('    3. Open the repo in your editor — MCP is ready!');
+    console.log('');
+};

package/dist/core/search/bm25-index.d.ts

@@ -17,6 +17,7 @@ export interface BM25SearchResult {
  *
  * @param query - Search query string
  * @param limit - Maximum results
+ * @param repoId - If provided, queries will be routed via the MCP connection pool
  * @returns Ranked search results from FTS indexes
  */
-export declare const searchFTSFromKuzu: (query: string, limit?: number) => Promise<BM25SearchResult[]>;
+export declare const searchFTSFromKuzu: (query: string, limit?: number, repoId?: string) => Promise<BM25SearchResult[]>;

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

@@ -5,6 +5,33 @@
  * Always reads from the database (no cached state to drift).
  */
 import { queryFTS } from '../kuzu/kuzu-adapter.js';
+/**
+ * Execute a single FTS query via a custom executor (for MCP connection pool).
+ * Returns the same shape as core queryFTS.
+ */
+async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
+    const escapedQuery = query.replace(/'/g, "''");
+    const cypher = `
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := false)
+    RETURN node, score
+    ORDER BY score DESC
+    LIMIT ${limit}
+  `;
+    try {
+        const rows = await executor(cypher);
+        return rows.map((row) => {
+            const node = row.node || row[0] || {};
+            const score = row.score ?? row[1] ?? 0;
+            return {
+                filePath: node.filePath || '',
+                score: typeof score === 'number' ? score : parseFloat(score) || 0,
+            };
+        });
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Search using KuzuDB's built-in FTS (always fresh, reads from disk)
  *
@@ -13,16 +40,31 @@ import { queryFTS } from '../kuzu/kuzu-adapter.js';
  *
  * @param query - Search query string
  * @param limit - Maximum results
+ * @param repoId - If provided, queries will be routed via the MCP connection pool
  * @returns Ranked search results from FTS indexes
  */
-export const searchFTSFromKuzu = async (query, limit = 20) => {
-    // Search multiple tables with searchable content
-    const [fileResults, functionResults, classResults, methodResults] = await Promise.all([
-        queryFTS('File', 'file_fts', query, limit, false).catch(() => []),
-        queryFTS('Function', 'function_fts', query, limit, false).catch(() => []),
-        queryFTS('Class', 'class_fts', query, limit, false).catch(() => []),
-        queryFTS('Method', 'method_fts', query, limit, false).catch(() => []),
-    ]);
+export const searchFTSFromKuzu = async (query, limit = 20, repoId) => {
+    let fileResults, functionResults, classResults, methodResults;
+    if (repoId) {
+        // Use MCP connection pool via dynamic import
+        const { executeQuery } = await import('../../mcp/core/kuzu-adapter.js');
+        const executor = (cypher) => executeQuery(repoId, cypher);
+        [fileResults, functionResults, classResults, methodResults] = await Promise.all([
+            queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit),
+            queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit),
+            queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit),
+            queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit),
+        ]);
+    }
+    else {
+        // Use core kuzu adapter (CLI / pipeline context)
+        [fileResults, functionResults, classResults, methodResults] = await Promise.all([
+            queryFTS('File', 'file_fts', query, limit, false).catch(() => []),
+            queryFTS('Function', 'function_fts', query, limit, false).catch(() => []),
+            queryFTS('Class', 'class_fts', query, limit, false).catch(() => []),
+            queryFTS('Method', 'method_fts', query, limit, false).catch(() => []),
+        ]);
+    }
     // Merge results by filePath, summing scores for same file
     const merged = new Map();
     const addResults = (results) => {

package/dist/mcp/core/kuzu-adapter.d.ts

@@ -1,23 +1,25 @@
 /**
- * KuzuDB Adapter (Persistent Connection)
+ * KuzuDB Adapter (Connection Pool)
  *
- * Holds a single database connection for the lifetime of the MCP session.
- * This is safe since the watcher has been removed -- only one process
- * accesses the database at a time.
+ * Manages a pool of KuzuDB connections keyed by repoId.
+ * Connections are lazily opened on first query and evicted
+ * after idle timeout or when pool exceeds max size (LRU).
  */
 /**
- * Initialize with a persistent connection to the database
+ * Initialize (or reuse) a connection for a specific repo
  */
-export declare const initKuzu: (path: string) => Promise<void>;
+export declare const initKuzu: (repoId: string, dbPath: string) => Promise<void>;
 /**
- * Execute a query using the persistent connection
+ * Execute a query on a specific repo's connection
  */
-export declare const executeQuery: (cypher: string) => Promise<any[]>;
+export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
- * Close the persistent connection
+ * Close one or all connections.
+ * If repoId is provided, close only that connection.
+ * If omitted, close all connections in the pool.
  */
-export declare const closeKuzu: () => Promise<void>;
+export declare const closeKuzu: (repoId?: string) => Promise<void>;
 /**
- * Check if the database connection is active
+ * Check if a specific repo's connection is active
  */
-export declare const isKuzuReady: () => boolean;
+export declare const isKuzuReady: (repoId: string) => boolean;

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

@@ -1,62 +1,126 @@
 /**
- * KuzuDB Adapter (Persistent Connection)
+ * KuzuDB Adapter (Connection Pool)
  *
- * Holds a single database connection for the lifetime of the MCP session.
- * This is safe since the watcher has been removed -- only one process
- * accesses the database at a time.
+ * Manages a pool of KuzuDB connections keyed by repoId.
+ * Connections are lazily opened on first query and evicted
+ * after idle timeout or when pool exceeds max size (LRU).
  */
 import fs from 'fs/promises';
 import kuzu from 'kuzu';
-let db = null;
-let conn = null;
+const pool = new Map();
+const MAX_POOL_SIZE = 5;
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+let idleTimer = null;
 /**
- * Initialize with a persistent connection to the database
+ * Start the idle cleanup timer (runs every 60s)
  */
-export const initKuzu = async (path) => {
-    if (conn)
-        return; // Already initialized
+function ensureIdleTimer() {
+    if (idleTimer)
+        return;
+    idleTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [repoId, entry] of pool) {
+            if (now - entry.lastUsed > IDLE_TIMEOUT_MS) {
+                closeOne(repoId);
+            }
+        }
+    }, 60_000);
+    // Don't keep the process alive just for this timer
+    if (idleTimer && typeof idleTimer === 'object' && 'unref' in idleTimer) {
+        idleTimer.unref();
+    }
+}
+/**
+ * Evict the least-recently-used connection if pool is at capacity
+ */
+function evictLRU() {
+    if (pool.size < MAX_POOL_SIZE)
+        return;
+    let oldestId = null;
+    let oldestTime = Infinity;
+    for (const [id, entry] of pool) {
+        if (entry.lastUsed < oldestTime) {
+            oldestTime = entry.lastUsed;
+            oldestId = id;
+        }
+    }
+    if (oldestId) {
+        closeOne(oldestId);
+    }
+}
+/**
+ * Close a single pool entry
+ */
+function closeOne(repoId) {
+    const entry = pool.get(repoId);
+    if (!entry)
+        return;
+    try {
+        entry.conn.close();
+    }
+    catch { }
+    try {
+        entry.db.close();
+    }
+    catch { }
+    pool.delete(repoId);
+}
+/**
+ * Initialize (or reuse) a connection for a specific repo
+ */
+export const initKuzu = async (repoId, dbPath) => {
+    const existing = pool.get(repoId);
+    if (existing) {
+        existing.lastUsed = Date.now();
+        return;
+    }
     // Check if database exists
     try {
-        await fs.stat(path);
+        await fs.stat(dbPath);
     }
     catch {
-        throw new Error(`KuzuDB not found at ${path}. Run: gitnexus analyze`);
+        throw new Error(`KuzuDB not found at ${dbPath}. Run: gitnexus analyze`);
     }
-    db = new kuzu.Database(path);
-    conn = new kuzu.Connection(db);
+    evictLRU();
+    const db = new kuzu.Database(dbPath);
+    const conn = new kuzu.Connection(db);
+    pool.set(repoId, { db, conn, lastUsed: Date.now(), dbPath });
+    ensureIdleTimer();
 };
 /**
- * Execute a query using the persistent connection
+ * Execute a query on a specific repo's connection
  */
-export const executeQuery = async (cypher) => {
-    if (!conn) {
-        throw new Error('KuzuDB not initialized. Call initKuzu first.');
+export const executeQuery = async (repoId, cypher) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`KuzuDB not initialized for repo "${repoId}". Call initKuzu first.`);
     }
-    const queryResult = await conn.query(cypher);
+    entry.lastUsed = Date.now();
+    const queryResult = await entry.conn.query(cypher);
     const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
     const rows = await result.getAll();
     return rows;
 };
 /**
- * Close the persistent connection
+ * Close one or all connections.
+ * If repoId is provided, close only that connection.
+ * If omitted, close all connections in the pool.
  */
-export const closeKuzu = async () => {
-    if (conn) {
-        try {
-            await conn.close();
-        }
-        catch { }
-        conn = null;
+export const closeKuzu = async (repoId) => {
+    if (repoId) {
+        closeOne(repoId);
+        return;
     }
-    if (db) {
-        try {
-            await db.close();
-        }
-        catch { }
-        db = null;
+    // Close all
+    for (const id of [...pool.keys()]) {
+        closeOne(id);
+    }
+    if (idleTimer) {
+        clearInterval(idleTimer);
+        idleTimer = null;
     }
 };
 /**
- * Check if the database connection is active
+ * Check if a specific repo's connection is active
  */
-export const isKuzuReady = () => conn !== null && db !== null;
+export const isKuzuReady = (repoId) => pool.has(repoId);

package/dist/mcp/local/local-backend.d.ts

@@ -1,29 +1,11 @@
 /**
- * Local Backend
+ * Local Backend (Multi-Repo)
  *
- * Provides tool implementations using local .gitnexus/ index.
- * This enables MCP to work without the browser.
+ * Provides tool implementations using local .gitnexus/ indexes.
+ * Supports multiple indexed repositories via a global registry.
+ * KuzuDB connections are opened lazily per repo on first query.
  */
-export interface RepoMeta {
-    repoPath: string;
-    lastCommit: string;
-    indexedAt: string;
-    stats?: {
-        files?: number;
-        nodes?: number;
-        edges?: number;
-        communities?: number;
-        processes?: number;
-    };
-}
-export interface IndexedRepo {
-    repoPath: string;
-    storagePath: string;
-    kuzuPath: string;
-    metaPath: string;
-    meta: RepoMeta;
-}
-export declare function findRepo(startPath: string): Promise<IndexedRepo | null>;
+import { type RegistryEntry } from '../../storage/repo-manager.js';
 export interface CodebaseContext {
     projectName: string;
     stats: {
@@ -43,17 +25,66 @@ export interface CodebaseContext {
     }>;
     folderTree: string;
 }
+interface RepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    kuzuPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RegistryEntry['stats'];
+}
 export declare class LocalBackend {
-    private repo;
-    private _context;
-    private initialized;
-    init(cwd: string): Promise<boolean>;
+    private repos;
+    private contextCache;
+    private initializedRepos;
+    /**
+     * Initialize from the global registry.
+     * Returns true if at least one repo is available.
+     */
+    init(): Promise<boolean>;
+    /**
+     * Generate a stable repo ID from name + path.
+     * If names collide, append a hash of the path.
+     */
+    private repoId;
+    /**
+     * Resolve which repo to use.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If 0 or multiple without param, throw with helpful message
+     */
+    resolveRepo(repoParam?: string): RepoHandle;
     private ensureInitialized;
-    get context(): CodebaseContext | null;
     get isReady(): boolean;
+    /**
+     * Get context for a specific repo (or the single repo if only one).
+     */
+    getContext(repoId?: string): CodebaseContext | null;
+    /**
+     * Backwards-compatible getter — returns context of single repo or null.
+     */
+    get context(): CodebaseContext | null;
+    getRepoPath(repoId?: string): string | null;
     get repoPath(): string | null;
-    get storagePath(): string | null;
+    getMeta(repoId?: string): {
+        lastCommit: string;
+        indexedAt: string;
+        stats?: any;
+    } | null;
     get meta(): any;
+    get storagePath(): string | null;
+    /**
+     * List all registered repos with their metadata.
+     */
+    listRepos(): Array<{
+        name: string;
+        path: string;
+        indexedAt: string;
+        lastCommit: string;
+        stats?: any;
+    }>;
     callTool(method: string, params: any): Promise<any>;
     private search;
     /**
@@ -71,3 +102,4 @@ export declare class LocalBackend {
     private analyze;
     disconnect(): Promise<void>;
 }
+export {};