gitnexus 1.6.6-rc.7 → 1.6.6-rc.8

package/dist/core/lbug/lbug-adapter.d.ts

@@ -66,7 +66,9 @@ export declare const initLbug: (dbPath: string) => Promise<{
  * database is busy (e.g. `gitnexus analyze` holds the write lock).
  * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
-export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>) => Promise<T>;
+export declare const withLbugDb: <T>(dbPath: string, operation: () => Promise<T>, options?: {
+    readOnly?: boolean;
+}) => Promise<T>;
 export type LbugProgressCallback = (message: string) => void;
 export declare const loadGraphToLbug: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: LbugProgressCallback) => Promise<{
     success: boolean;

package/dist/core/lbug/lbug-adapter.js

@@ -112,6 +112,7 @@ export const splitRelCsvByLabelPair = async (csvPath, csvDir, validTables, getNo
 let db = null;
 let conn = null;
 let currentDbPath = null;
+let currentDbReadOnly = false;
 let ftsLoaded = false;
 let vectorExtensionLoaded = false;
 /**
@@ -367,12 +368,13 @@ export const initLbug = async (dbPath) => {
  * database is busy (e.g. `gitnexus analyze` holds the write lock).
  * Each retry waits DB_LOCK_RETRY_DELAY_MS * attempt milliseconds.
  */
-export const withLbugDb = async (dbPath, operation) => {
+export const withLbugDb = async (dbPath, operation, options = {}) => {
     let lastError;
+    const readOnly = options.readOnly === true;
     for (let attempt = 1; attempt <= DB_LOCK_RETRY_ATTEMPTS; attempt++) {
         try {
             return await runWithSessionLock(async () => {
-                await ensureLbugInitialized(dbPath);
+                await ensureLbugInitialized(dbPath, readOnly);
                 return operation();
             });
         }
@@ -402,14 +404,14 @@ export const withLbugDb = async (dbPath, operation) => {
     // but TypeScript needs an explicit throw to satisfy the return type.
     throw lastError;
 };
-const ensureLbugInitialized = async (dbPath) => {
-    if (conn && currentDbPath === dbPath) {
+const ensureLbugInitialized = async (dbPath, readOnly = false) => {
+    if (conn && currentDbPath === dbPath && currentDbReadOnly === readOnly) {
         return { db, conn };
     }
-    await doInitLbug(dbPath);
+    await doInitLbug(dbPath, readOnly);
     return { db, conn };
 };
-const doInitLbug = async (dbPath) => {
+const doInitLbug = async (dbPath, readOnly = false) => {
     // Different database requested — close the old one first
     if (conn || db) {
         await safeClose();
@@ -486,9 +488,12 @@ const doInitLbug = async (dbPath) => {
         // Ensure parent directory exists
         const parentDir = path.dirname(dbPath);
         await fs.mkdir(parentDir, { recursive: true });
-        const opened = await openLbugConnection(lbug, dbPath);
+        const opened = readOnly
+            ? await openLbugConnection(lbug, dbPath, { readOnly: true })
+            : await openLbugConnection(lbug, dbPath);
         db = opened.db;
         conn = opened.conn;
+        currentDbReadOnly = readOnly;
     }
     finally {
         await releaseInitLock();
@@ -524,7 +529,7 @@ const doInitLbug = async (dbPath) => {
                 throw new Error(`LadybugDB WAL corruption detected at ${dbPath}. ${WAL_RECOVERY_SUGGESTION}\n` +
                     `  Original error: ${msg.slice(0, 200)}`);
             }
-            if (!msg.includes('already exists') && !isDbBusyError(err)) {
+            if (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {
                 logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
             }
         }
@@ -931,11 +936,7 @@ export const batchInsertNodesToLbug = async (nodes, dbPath) => {
     return { inserted, failed };
 };
 export const executeQuery = async (cypher) => {
-    if (!conn) {
-        throw new Error('LadybugDB not initialized. Call initLbug first.');
-    }
-    const queryResult = await conn.query(cypher);
-    return await readQueryRows(queryResult);
+    return await executePrepared(cypher, {});
 };
 export const streamQuery = async (cypher, onRow) => {
     if (!conn) {
@@ -1517,17 +1518,14 @@ export const queryFTS = async (tableName, indexName, query, limit = 20, conjunct
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initLbug first.');
     }
-    // Escape backslashes and single quotes to prevent Cypher injection
-    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
-    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := ${conjunctive})
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', $query, conjunctive := ${conjunctive})
     RETURN node, score
     ORDER BY score DESC
     LIMIT ${limit}
   `;
     try {
-        const queryResult = await conn.query(cypher);
-        const rows = await readQueryRows(queryResult);
+        const rows = await executePrepared(cypher, { query });
         return rows.map((row) => {
             const node = row.node || row[0] || {};
             const score = row.score ?? row[1] ?? 0;

package/dist/core/lbug/pool-adapter.d.ts

@@ -81,10 +81,3 @@ export declare const closeLbug: (repoId?: string) => Promise<void>;
  * Check if a specific repo's pool is active
  */
 export declare const isLbugReady: (repoId: string) => boolean;
-/** Regex to detect write operations in user-supplied Cypher queries.
- * Note: CALL is NOT blocked — it's used for read-only FTS (CALL QUERY_FTS_INDEX)
- * and vector search (CALL QUERY_VECTOR_INDEX). The database is opened in
- * read-only mode as defense-in-depth against write procedures. */
-export declare const CYPHER_WRITE_RE: RegExp;
-/** Check if a Cypher query contains write operations */
-export declare function isWriteQuery(query: string): boolean;

package/dist/core/lbug/pool-adapter.js

@@ -16,7 +16,7 @@
  */
 import fs from 'fs/promises';
 import lbug from '@ladybugdb/core';
-import { loadFTSExtension } from './lbug-adapter.js';
+import { isReadOnlyDbError, loadFTSExtension } from './lbug-adapter.js';
 import { createLbugDatabase, isWalCorruptionError, WAL_RECOVERY_SUGGESTION, } from './lbug-config.js';
 const pool = new Map();
 const poolCloseListeners = new Set();
@@ -505,28 +505,7 @@ function withTimeout(promise, ms, label) {
     return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 export const executeQuery = async (repoId, cypher) => {
-    const entry = pool.get(repoId);
-    if (!entry) {
-        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initLbug first.`);
-    }
-    if (isWriteQuery(cypher)) {
-        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
-    }
-    entry.lastUsed = Date.now();
-    const conn = await checkout(entry);
-    silenceStdout();
-    activeQueryCount++;
-    try {
-        const queryResult = await withTimeout(conn.query(cypher), QUERY_TIMEOUT_MS, 'Query');
-        const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
-        const rows = await result.getAll();
-        return rows;
-    }
-    finally {
-        activeQueryCount--;
-        restoreStdout();
-        checkin(entry, conn);
-    }
+    return await executeParameterized(repoId, cypher, {});
 };
 /**
  * Execute a parameterized query on a specific repo's connection pool.
@@ -552,6 +531,12 @@ export const executeParameterized = async (repoId, cypher, params) => {
         const rows = await result.getAll();
         return rows;
     }
+    catch (err) {
+        if (isReadOnlyDbError(err)) {
+            throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+        }
+        throw err;
+    }
     finally {
         activeQueryCount--;
         restoreStdout();
@@ -580,12 +565,3 @@ export const closeLbug = async (repoId) => {
  * Check if a specific repo's pool is active
  */
 export const isLbugReady = (repoId) => pool.has(repoId);
-/** Regex to detect write operations in user-supplied Cypher queries.
- * Note: CALL is NOT blocked — it's used for read-only FTS (CALL QUERY_FTS_INDEX)
- * and vector search (CALL QUERY_VECTOR_INDEX). The database is opened in
- * read-only mode as defense-in-depth against write procedures. */
-export const CYPHER_WRITE_RE = /(?<!:)\b(CREATE|DELETE|SET|MERGE|REMOVE|DROP|ALTER|COPY|DETACH|FOREACH|INSTALL|LOAD)\b/i;
-/** Check if a Cypher query contains write operations */
-export function isWriteQuery(query) {
-    return CYPHER_WRITE_RE.test(query);
-}

package/dist/core/lbug/query-params.d.ts

@@ -0,0 +1 @@
+export declare const isValidQueryParams: (value: unknown) => value is Record<string, unknown>;

package/dist/core/lbug/query-params.js

@@ -0,0 +1,21 @@
+/**
+ * Return true only for plain-object payloads that can be safely used as
+ * named parameter maps in prepared Cypher execution.
+ *
+ * Validation criteria:
+ * - must be a JavaScript object (`typeof value === 'object'`)
+ * - must not be `null`
+ * - must not be an array
+ * - must have a plain-object prototype
+ * - values must be scalar bindable values (string | number | boolean | null)
+ *
+ * Rationale: prepared-statement params are key/value maps; rejecting null/array
+ * and non-plain objects keeps binding behavior predictable and avoids passing
+ * complex host objects to Ladybug parameter binding.
+ */
+const isBindableScalar = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+export const isValidQueryParams = (value) => value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+    Object.values(value).every(isBindableScalar);

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

@@ -12,16 +12,14 @@ import { FTS_INDEXES } from './fts-schema.js';
  * caller can distinguish "zero matches" from "index missing".
  */
 async function queryFTSViaExecutor(executor, tableName, indexName, query, limit) {
-    // Escape single quotes and backslashes to prevent Cypher injection
-    const escapedQuery = query.replace(/\\/g, '\\\\').replace(/'/g, "''");
     const cypher = `
-    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', '${escapedQuery}', conjunctive := false)
+    CALL QUERY_FTS_INDEX('${tableName}', '${indexName}', $query, conjunctive := false)
     RETURN node, score
     ORDER BY score DESC
     LIMIT ${limit}
   `;
     try {
-        const rows = await executor(cypher);
+        const rows = await executor(cypher, { query });
         return rows.map((row) => {
             const node = row.node || row[0] || {};
             const score = row.score ?? row[1] ?? 0;
@@ -55,8 +53,8 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
         const poolMod = await import('../lbug/pool-adapter.js');
-        const { executeQuery } = poolMod;
-        const executor = (cypher) => executeQuery(repoId, cypher);
+        const { executeParameterized } = poolMod;
+        const executor = (cypher, params) => executeParameterized(repoId, cypher, params);
         for (const { table, indexName } of FTS_INDEXES) {
             const result = await queryFTSViaExecutor(executor, table, indexName, query, limit);
             if (result !== null) {

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

@@ -5,8 +5,6 @@
  * Supports multiple indexed repositories via a global registry.
  * LadybugDB connections are opened lazily per repo on first query.
  */
-import { isWriteQuery } from '../../core/lbug/pool-adapter.js';
-export { isWriteQuery };
 import { type RegistryEntry } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 /**
@@ -208,7 +206,7 @@ export declare class LocalBackend {
      * Semantic vector search helper
      */
     private semanticSearch;
-    executeCypher(repoName: string, query: string): Promise<any>;
+    executeCypher(repoName: string, query: string, params?: Record<string, unknown>): Promise<any>;
     private cypher;
     /**
      * Format raw Cypher result rows as a markdown table for LLM readability.
@@ -370,3 +368,4 @@ export declare class LocalBackend {
     queryProcessDetail(name: string, repoName?: string): Promise<any>;
     disconnect(): Promise<void>;
 }
+export {};

package/dist/mcp/local/local-backend.js

@@ -7,9 +7,9 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
-import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, isWriteQuery, } from '../../core/lbug/pool-adapter.js';
+import { initLbug, executeQuery, executeParameterized, closeLbug, isLbugReady, } from '../../core/lbug/pool-adapter.js';
+import { isValidQueryParams } from '../../core/lbug/query-params.js';
 import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
-export { isWriteQuery };
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
@@ -142,6 +142,7 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     logger.error({ context, err: msg }, 'GitNexus query failed');
 }
+const isReadOnlyDbError = (err) => /read-only database/i.test(err instanceof Error ? err.message : String(err));
 /**
  * Per-query latency telemetry for production aggregation (#553).
  *
@@ -1067,27 +1068,31 @@ export class LocalBackend {
             return [];
         }
     }
-    async executeCypher(repoName, query) {
+    async executeCypher(repoName, query, params = {}) {
         const repo = await this.resolveRepo(repoName);
-        return this.cypher(repo, { query });
+        return this.cypher(repo, { query, params });
     }
-    async cypher(repo, params) {
+    async cypher(repo, request) {
         await this.ensureInitialized(repo.id);
         if (!isLbugReady(repo.id)) {
             return { error: 'LadybugDB not ready. Index may be corrupted.' };
         }
-        // Block write operations (defense-in-depth — DB is already read-only)
-        if (isWriteQuery(params.query)) {
+        if (request.params !== undefined && !isValidQueryParams(request.params)) {
             return {
-                error: 'Write operations (CREATE, DELETE, SET, MERGE, REMOVE, DROP, ALTER, COPY, DETACH) are not allowed. The knowledge graph is read-only.',
+                error: '"params" must be a plain object with scalar values (string/number/boolean/null).',
             };
         }
         try {
-            const result = await executeQuery(repo.id, params.query);
+            const result = await executeParameterized(repo.id, request.query, request.params ?? {});
             return result;
         }
         catch (err) {
             const msg = err.message || 'Query failed';
+            if (isReadOnlyDbError(err)) {
+                return {
+                    error: 'Write operations (CREATE, DELETE, SET, MERGE, REMOVE, DROP, ALTER, COPY, DETACH) are not allowed. The knowledge graph is read-only.',
+                };
+            }
             if (isWalCorruptionError(err)) {
                 return {
                     error: msg,

package/dist/mcp/tools.js

@@ -155,6 +155,10 @@ TIPS:
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Cypher query to execute' },
+                params: {
+                    type: 'object',
+                    description: 'Optional query parameters for placeholders (e.g. $name) to execute via prepared statement binding.',
+                },
                 repo: {
                     type: 'string',
                     description: 'Repository name or path. Omit if only one repo is indexed.',

package/dist/server/api.d.ts

@@ -68,5 +68,8 @@ export declare const handleFileRequest: (req: {
     };
     json: (body: any) => void;
 }, repoPath: string) => Promise<void>;
+export declare const handleQueryRequest: (req: express.Request, res: express.Response, resolveRepo: (repoName?: string) => Promise<{
+    storagePath: string;
+} | undefined>) => Promise<void>;
 export declare const createServer: (port: number, host?: string) => Promise<void>;
 export {};

package/dist/server/api.js

@@ -13,8 +13,8 @@ import path from 'path';
 import fs from 'fs/promises';
 import { createRequire } from 'node:module';
 import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
-import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, flushWAL, closeLbug, withLbugDb, } from '../core/lbug/lbug-adapter.js';
-import { isWriteQuery } from '../core/lbug/pool-adapter.js';
+import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, flushWAL, closeLbug, withLbugDb, isReadOnlyDbError, } from '../core/lbug/lbug-adapter.js';
+import { isValidQueryParams } from '../core/lbug/query-params.js';
 import { NODE_TABLES } from '../_shared/index.js';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
@@ -533,6 +533,39 @@ export const handleFileRequest = async (req, res, repoPath) => {
         }
     }
 };
+export const handleQueryRequest = async (req, res, resolveRepo) => {
+    try {
+        const cypher = req.body.cypher;
+        if (!cypher) {
+            res.status(400).json({ error: 'Missing "cypher" in request body' });
+            return;
+        }
+        const queryParams = req.body.params;
+        if (queryParams !== undefined && !isValidQueryParams(queryParams)) {
+            res.status(400).json({
+                error: '"params" must be a plain object with scalar values (string/number/boolean/null)',
+            });
+            return;
+        }
+        const entry = await resolveRepo(requestedRepo(req));
+        if (!entry) {
+            res.status(404).json({ error: 'Repository not found' });
+            return;
+        }
+        const lbugPath = path.join(entry.storagePath, 'lbug');
+        const result = await withLbugDb(lbugPath, () => executePrepared(cypher, queryParams ?? {}), {
+            readOnly: true,
+        });
+        res.json({ result });
+    }
+    catch (err) {
+        if (isReadOnlyDbError(err)) {
+            res.status(403).json({ error: 'Write queries are not allowed via the HTTP API' });
+            return;
+        }
+        res.status(500).json({ error: err.message || 'Query failed' });
+    }
+};
 export const createServer = async (port, host = '127.0.0.1') => {
     const app = express();
     app.disable('x-powered-by');
@@ -892,28 +925,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     });
     // Execute Cypher query
     app.post('/api/query', async (req, res) => {
-        try {
-            const cypher = req.body.cypher;
-            if (!cypher) {
-                res.status(400).json({ error: 'Missing "cypher" in request body' });
-                return;
-            }
-            if (isWriteQuery(cypher)) {
-                res.status(403).json({ error: 'Write queries are not allowed via the HTTP API' });
-                return;
-            }
-            const entry = await resolveRepo(requestedRepo(req));
-            if (!entry) {
-                res.status(404).json({ error: 'Repository not found' });
-                return;
-            }
-            const lbugPath = path.join(entry.storagePath, 'lbug');
-            const result = await withLbugDb(lbugPath, () => executeQuery(cypher));
-            res.json({ result });
-        }
-        catch (err) {
-            res.status(500).json({ error: err.message || 'Query failed' });
-        }
+        await handleQueryRequest(req, res, resolveRepo);
     });
     // Search (supports mode: 'hybrid' | 'semantic' | 'bm25', and optional enrichment)
     app.post('/api/search', async (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.6-rc.7",
+  "version": "1.6.6-rc.8",
   "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",