gitnexus 1.2.5 → 1.2.6

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

@@ -1,26 +1,34 @@
 /**
  * KuzuDB Adapter (Connection Pool)
  *
- * 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).
+ * 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.
  */
 /**
- * Initialize (or reuse) a connection for a specific repo.
+ * Initialize (or reuse) a Database + connection pool for a specific repo.
  * Retries on lock errors (e.g., when `gitnexus analyze` is running).
  */
 export declare const initKuzu: (repoId: string, dbPath: string) => Promise<void>;
 /**
- * Execute a query on a specific repo's connection
+ * Execute a query on a specific repo's connection pool.
+ * Automatically checks out a connection, runs the query, and returns it.
  */
 export declare const executeQuery: (repoId: string, cypher: string) => Promise<any[]>;
 /**
- * Close one or all connections.
- * If repoId is provided, close only that connection.
- * If omitted, close all connections in the pool.
+ * Close one or all repo pools.
+ * If repoId is provided, close only that repo's connections.
+ * If omitted, close all repos.
  */
 export declare const closeKuzu: (repoId?: string) => Promise<void>;
 /**
- * Check if a specific repo's connection is active
+ * Check if a specific repo's pool is active
  */
 export declare const isKuzuReady: (repoId: string) => boolean;

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

@@ -1,15 +1,28 @@
 /**
  * KuzuDB Adapter (Connection Pool)
  *
- * 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).
+ * 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)
@@ -25,13 +38,12 @@ function ensureIdleTimer() {
             }
         }
     }, 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
+ * Evict the least-recently-used repo if pool is at capacity
  */
 function evictLRU() {
     if (pool.size < MAX_POOL_SIZE)
@@ -49,26 +61,42 @@ function evictLRU() {
     }
 }
 /**
- * Close a single pool entry
+ * Close all connections for a repo and remove it from the pool
  */
 function closeOne(repoId) {
     const entry = pool.get(repoId);
     if (!entry)
         return;
-    try {
-        entry.conn.close();
+    for (const conn of entry.available) {
+        try {
+            conn.close();
+        }
+        catch { }
     }
-    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 connection for a specific repo.
+ * 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) => {
@@ -90,17 +118,19 @@ export const initKuzu = async (repoId, dbPath) => {
     // avoids lock conflicts when `gitnexus analyze` is writing.
     let lastError = null;
     for (let attempt = 1; attempt <= LOCK_RETRY_ATTEMPTS; attempt++) {
-        // Silence stdout during KuzuDB init — native module may write to stdout
-        // which corrupts the MCP stdio protocol.
         const origWrite = process.stdout.write;
         process.stdout.write = (() => true);
         try {
             const db = new kuzu.Database(dbPath, 0, // bufferManagerSize (default)
             false, // enableCompression (default)
             true);
-            const conn = new kuzu.Connection(db);
             process.stdout.write = origWrite;
-            pool.set(repoId, { db, conn, lastUsed: Date.now(), dbPath });
+            // 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;
         }
@@ -111,7 +141,6 @@ export const initKuzu = async (repoId, dbPath) => {
                 || lastError.message.includes('lock');
             if (!isLockError || attempt === LOCK_RETRY_ATTEMPTS)
                 break;
-            // Wait before retrying — analyze may be mid-rebuild
             await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_DELAY_MS * attempt));
         }
     }
@@ -119,7 +148,47 @@ export const initKuzu = async (repoId, dbPath) => {
         `Retry later. (${lastError?.message || 'unknown error'})`);
 };
 /**
- * Execute a query on a specific repo's connection
+ * 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);
@@ -127,22 +196,27 @@ export const executeQuery = async (repoId, cypher) => {
         throw new Error(`KuzuDB not initialized for repo "${repoId}". Call initKuzu first.`);
     }
     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;
+    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 connections.
- * If repoId is provided, close only that connection.
- * If omitted, close all connections in the pool.
+ * 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;
     }
-    // Close all
     for (const id of [...pool.keys()]) {
         closeOne(id);
     }
@@ -152,6 +226,6 @@ export const closeKuzu = async (repoId) => {
     }
 };
 /**
- * Check if a specific repo's connection is active
+ * Check if a specific repo's pool is active
  */
 export const isKuzuReady = (repoId) => pool.has(repoId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",