@veewo/gitnexus 1.3.4

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

@@ -0,0 +1,231 @@
+/**
+ * KuzuDB Adapter (Connection Pool)
+ *
+ * Manages a pool of KuzuDB databases keyed by repoId, each with
+ * multiple Connection objects for safe concurrent query execution.
+ *
+ * KuzuDB Connections are NOT thread-safe — a single Connection
+ * segfaults if concurrent .query() calls hit it simultaneously.
+ * This adapter provides a checkout/return connection pool so each
+ * concurrent query gets its own Connection from the same Database.
+ *
+ * @see https://docs.kuzudb.com/concurrency — multiple Connections
+ * from the same Database is the officially supported concurrency pattern.
+ */
+import fs from 'fs/promises';
+import kuzu from 'kuzu';
+const pool = new Map();
+/** Max repos in the pool (LRU eviction) */
+const MAX_POOL_SIZE = 5;
+/** Idle timeout before closing a repo's connections */
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/** Max connections per repo (caps concurrent queries per repo) */
+const MAX_CONNS_PER_REPO = 8;
+/** Connections created eagerly on init */
+const INITIAL_CONNS_PER_REPO = 2;
+let idleTimer = null;
+/**
+ * Start the idle cleanup timer (runs every 60s)
+ */
+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);
+    if (idleTimer && typeof idleTimer === 'object' && 'unref' in idleTimer) {
+        idleTimer.unref();
+    }
+}
+/**
+ * Evict the least-recently-used repo 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 all connections for a repo and remove it from the pool
+ */
+function closeOne(repoId) {
+    const entry = pool.get(repoId);
+    if (!entry)
+        return;
+    for (const conn of entry.available) {
+        try {
+            conn.close();
+        }
+        catch { }
+    }
+    try {
+        entry.db.close();
+    }
+    catch { }
+    pool.delete(repoId);
+}
+/**
+ * Create a new Connection from a repo's Database.
+ * Silences stdout to prevent native module output from corrupting MCP stdio.
+ */
+function createConnection(db) {
+    const origWrite = process.stdout.write;
+    process.stdout.write = (() => true);
+    try {
+        return new kuzu.Connection(db);
+    }
+    finally {
+        process.stdout.write = origWrite;
+    }
+}
+const LOCK_RETRY_ATTEMPTS = 3;
+const LOCK_RETRY_DELAY_MS = 2000;
+/**
+ * Initialize (or reuse) a Database + connection pool for a specific repo.
+ * Retries on lock errors (e.g., when `gitnexus analyze` is running).
+ */
+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(dbPath);
+    }
+    catch {
+        throw new Error(`KuzuDB not found at ${dbPath}. Run: gitnexus analyze`);
+    }
+    evictLRU();
+    // Open in read-only mode — MCP server never writes to the database.
+    // This allows multiple MCP server instances to read concurrently, and
+    // avoids lock conflicts when `gitnexus analyze` is writing.
+    let lastError = null;
+    for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
+        const origWrite = process.stdout.write;
+        process.stdout.write = (() => true);
+        try {
+            const db = new kuzu.Database(dbPath, 0, // bufferManagerSize (default)
+            false, // enableCompression (default)
+            true);
+            process.stdout.write = origWrite;
+            // Pre-create a small pool of connections
+            const available = [];
+            for (let i = 0; i < INITIAL_CONNS_PER_REPO; i++) {
+                available.push(createConnection(db));
+            }
+            pool.set(repoId, { db, available, checkedOut: 0, waiters: [], lastUsed: Date.now(), dbPath });
+            ensureIdleTimer();
+            return;
+        }
+        catch (err) {
+            process.stdout.write = origWrite;
+            lastError = err instanceof Error ? err : new Error(String(err));
+            const isLockError = lastError.message.includes('Could not set lock')
+                || lastError.message.includes('lock');
+            if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
+                break;
+            await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_DELAY_MS * attempt));
+        }
+    }
+    throw new Error(`KuzuDB unavailable for ${repoId}. Another process may be rebuilding the index. ` +
+        `Retry later. (${lastError?.message || 'unknown error'})`);
+};
+/**
+ * Checkout a connection from the pool.
+ * Returns an available connection, or creates a new one if under the cap.
+ * If all connections are busy and at cap, queues the caller until one is returned.
+ */
+function checkout(entry) {
+    // Fast path: grab an available connection
+    if (entry.available.length > 0) {
+        entry.checkedOut++;
+        return Promise.resolve(entry.available.pop());
+    }
+    // Grow the pool if under the cap
+    const totalConns = entry.available.length + entry.checkedOut;
+    if (totalConns < MAX_CONNS_PER_REPO) {
+        entry.checkedOut++;
+        return Promise.resolve(createConnection(entry.db));
+    }
+    // At capacity — queue the caller. checkin() will resolve this when
+    // a connection is returned, handing it directly to the next waiter.
+    return new Promise(resolve => {
+        entry.waiters.push(resolve);
+    });
+}
+/**
+ * Return a connection to the pool after use.
+ * If there are queued waiters, hand the connection directly to the next one
+ * instead of putting it back in the available array (avoids race conditions).
+ */
+function checkin(entry, conn) {
+    if (entry.waiters.length > 0) {
+        // Hand directly to the next waiter — no intermediate available state
+        const waiter = entry.waiters.shift();
+        waiter(conn);
+    }
+    else {
+        entry.checkedOut--;
+        entry.available.push(conn);
+    }
+}
+/**
+ * Execute a query on a specific repo's connection pool.
+ * Automatically checks out a connection, runs the query, and returns it.
+ */
+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.`);
+    }
+    entry.lastUsed = Date.now();
+    const conn = await checkout(entry);
+    try {
+        const queryResult = await conn.query(cypher);
+        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
+        const rows = await result.getAll();
+        return rows;
+    }
+    finally {
+        checkin(entry, conn);
+    }
+};
+/**
+ * Close one or all repo pools.
+ * If repoId is provided, close only that repo's connections.
+ * If omitted, close all repos.
+ */
+export const closeKuzu = async (repoId) => {
+    if (repoId) {
+        closeOne(repoId);
+        return;
+    }
+    for (const id of [...pool.keys()]) {
+        closeOne(id);
+    }
+    if (idleTimer) {
+        clearInterval(idleTimer);
+        idleTimer = null;
+    }
+};
+/**
+ * Check if a specific repo's pool is active
+ */
+export const isKuzuReady = (repoId) => pool.has(repoId);

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

@@ -0,0 +1,160 @@
+/**
+ * Local Backend (Multi-Repo)
+ *
+ * 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.
+ */
+import { type RegistryEntry } from '../../storage/repo-manager.js';
+export interface CodebaseContext {
+    projectName: string;
+    stats: {
+        fileCount: number;
+        functionCount: number;
+        communityCount: number;
+        processCount: number;
+    };
+}
+interface RepoHandle {
+    id: string;
+    name: string;
+    repoPath: string;
+    storagePath: string;
+    kuzuPath: string;
+    indexedAt: string;
+    lastCommit: string;
+    stats?: RegistryEntry['stats'];
+}
+export declare class LocalBackend {
+    private repos;
+    private contextCache;
+    private initializedRepos;
+    /**
+     * Initialize from the global registry.
+     * Returns true if at least one repo is available.
+     */
+    init(): Promise<boolean>;
+    /**
+     * Re-read the global registry and update the in-memory repo map.
+     * New repos are added, existing repos are updated, removed repos are pruned.
+     * KuzuDB connections for removed repos are NOT closed (they idle-timeout naturally).
+     */
+    private refreshRepos;
+    /**
+     * 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
+     *
+     * On a miss, re-reads the registry once in case a new repo was indexed
+     * while the MCP server was running.
+     */
+    resolveRepo(repoParam?: string): Promise<RepoHandle>;
+    /**
+     * Try to resolve a repo from the in-memory cache. Returns null on miss.
+     */
+    private resolveRepoFromCache;
+    private ensureInitialized;
+    /**
+     * Get context for a specific repo (or the single repo if only one).
+     */
+    getContext(repoId?: string): CodebaseContext | null;
+    /**
+     * List all registered repos with their metadata.
+     * Re-reads the global registry so newly indexed repos are discovered
+     * without restarting the MCP server.
+     */
+    listRepos(): Promise<Array<{
+        name: string;
+        path: string;
+        indexedAt: string;
+        lastCommit: string;
+        stats?: any;
+    }>>;
+    callTool(method: string, params: any): Promise<any>;
+    /**
+     * Query tool — process-grouped search.
+     *
+     * 1. Hybrid search (BM25 + semantic) to find matching symbols
+     * 2. Trace each match to its process(es) via STEP_IN_PROCESS
+     * 3. Group by process, rank by aggregate relevance + internal cluster cohesion
+     * 4. Return: { processes, process_symbols, definitions }
+     */
+    private query;
+    /**
+     * BM25 keyword search helper - uses KuzuDB FTS for always-fresh results
+     */
+    private bm25Search;
+    /**
+     * Semantic vector search helper
+     */
+    private semanticSearch;
+    executeCypher(repoName: string, query: string): Promise<any>;
+    private cypher;
+    /**
+     * Format raw Cypher result rows as a markdown table for LLM readability.
+     * Falls back to raw result if rows aren't tabular objects.
+     */
+    private formatCypherAsMarkdown;
+    /**
+     * Aggregate same-named clusters: group by heuristicLabel, sum symbols,
+     * weighted-average cohesion, filter out tiny clusters (<5 symbols).
+     * Raw communities stay intact in KuzuDB for Cypher queries.
+     */
+    private aggregateClusters;
+    private overview;
+    /**
+     * Context tool — 360-degree symbol view with categorized refs.
+     * Disambiguation when multiple symbols share a name.
+     * UID-based direct lookup. No cluster in output.
+     */
+    private context;
+    /**
+     * Legacy explore — kept for backwards compatibility with resources.ts.
+     * Routes cluster/process types to direct graph queries.
+     */
+    private explore;
+    /**
+     * Detect changes — git-diff based impact analysis.
+     * Maps changed lines to indexed symbols, then finds affected processes.
+     */
+    private detectChanges;
+    /**
+     * Rename tool — multi-file coordinated rename using graph + text search.
+     * Graph refs are tagged "graph" (high confidence).
+     * Additional refs found via text search are tagged "text_search" (lower confidence).
+     */
+    private rename;
+    private impact;
+    /**
+     * Query clusters (communities) directly from graph.
+     * Used by getClustersResource — avoids legacy overview() dispatch.
+     */
+    queryClusters(repoName?: string, limit?: number): Promise<{
+        clusters: any[];
+    }>;
+    /**
+     * Query processes directly from graph.
+     * Used by getProcessesResource — avoids legacy overview() dispatch.
+     */
+    queryProcesses(repoName?: string, limit?: number): Promise<{
+        processes: any[];
+    }>;
+    /**
+     * Query cluster detail (members) directly from graph.
+     * Used by getClusterDetailResource.
+     */
+    queryClusterDetail(name: string, repoName?: string): Promise<any>;
+    /**
+     * Query process detail (steps) directly from graph.
+     * Used by getProcessDetailResource.
+     */
+    queryProcessDetail(name: string, repoName?: string): Promise<any>;
+    disconnect(): Promise<void>;
+}
+export {};