@codragraph/cli 2.1.1 → 2.1.5

package/dist/cli/setup.js

@@ -23,7 +23,7 @@ const pkg = require('../../package.json');
 const CLI_PACKAGE_SPEC = `@codragraph/cli@${pkg.version}`;
 /**
  * Resolve the absolute path to the `codragraph` binary if it's installed
- * globally (or via npm -g / yarn global). Returns null when not found.
+ * globally (or via npm -g / bun -g / yarn global). Returns null when not found.
  *
  * Note: the npm package is `@codragraph/cli`, but the executable it installs
  * is `codragraph` (see package.json `bin`). PATH lookup must use the bin name.
@@ -49,7 +49,7 @@ function resolveCodragraphBin() {
             .filter(Boolean);
         if (process.platform === 'win32') {
             // Prefer a Windows-executable shim. If none is on PATH, return null so
-            // the caller falls through to the `cmd /c npx -y @codragraph/cli` path.
+            // the caller falls through to the package-runner fallback.
             const exe = lines.find((l) => /\.(cmd|exe|bat)$/i.test(l));
             return exe ?? null;
         }
@@ -63,28 +63,40 @@ function resolveCodragraphBin() {
  * The MCP server entry for all editors.
  *
  * Prefers the globally-installed `codragraph` binary (starts in ~1 s) over
- * `npx -y @codragraph/cli@<version>` (cold-cache install of native deps can take
+ * `npx` / `bunx` package execution (cold-cache install of native deps can take
  * >60 s, exceeding Claude Code's 30 s MCP connection timeout).
  *
- * Falls back to npx when the binary isn't on PATH — e.g. first-time
- * users who ran `npx @codragraph/cli analyze` but haven't done `npm i -g`.
+ * Falls back to the package runner that invoked setup when the binary isn't on
+ * PATH — e.g. first-time `npx @codragraph/cli` or `bunx @codragraph/cli` users.
  *
  * Windows note: even when the bin is on PATH, we launch via `cmd /c codragraph
  * mcp` rather than writing the resolved path. Reason: `where codragraph`
  * returns the extensionless Unix shim before `codragraph.cmd`, and Node's
  * spawn/execFile cannot launch the extensionless shim on Windows. Letting
  * cmd resolve via PATHEXT is the only reliable path that works for npm-,
- * pnpm-, and yarn-installed shims alike.
+ * bun-, pnpm-, and yarn-installed shims alike.
  */
-function getMcpEntry() {
-    const bin = resolveCodragraphBin();
-    if (bin) {
+function isRunningUnderBun() {
+    const userAgent = (process.env.npm_config_user_agent ?? '').toLowerCase();
+    const rawExecPath = process.env.npm_execpath ?? '';
+    const execPath = process.platform === 'win32'
+        ? path.win32.basename(rawExecPath).toLowerCase()
+        : path.basename(rawExecPath).toLowerCase();
+    return userAgent.startsWith('bun/') || execPath === 'bun' || execPath === 'bun.exe';
+}
+function getPackageRunnerMcpEntry() {
+    if (isRunningUnderBun()) {
         if (process.platform === 'win32') {
-            return { command: 'cmd', args: ['/c', 'codragraph', 'mcp'] };
+            return {
+                command: 'cmd',
+                args: ['/c', 'bunx', CLI_PACKAGE_SPEC, 'mcp'],
+            };
         }
-        return { command: bin, args: ['mcp'] };
+        return {
+            command: 'bunx',
+            args: [CLI_PACKAGE_SPEC, 'mcp'],
+        };
     }
-    // Fallback: npx (works without a global install, but slow cold-start)
     if (process.platform === 'win32') {
         return {
             command: 'cmd',
@@ -96,6 +108,16 @@ function getMcpEntry() {
         args: ['-y', CLI_PACKAGE_SPEC, 'mcp'],
     };
 }
+function getMcpEntry() {
+    const bin = resolveCodragraphBin();
+    if (bin) {
+        if (process.platform === 'win32') {
+            return { command: 'cmd', args: ['/c', 'codragraph', 'mcp'] };
+        }
+        return { command: bin, args: ['mcp'] };
+    }
+    return getPackageRunnerMcpEntry();
+}
 /**
  * OpenCode uses a different MCP format: { type: "local", command: [...] }
  * where command is a flat array (command + args combined).
@@ -108,13 +130,8 @@ function getOpenCodeMcpEntry() {
         }
         return { type: 'local', command: [bin, 'mcp'] };
     }
-    if (process.platform === 'win32') {
-        return {
-            type: 'local',
-            command: ['cmd', '/c', 'npx', '-y', CLI_PACKAGE_SPEC, 'mcp'],
-        };
-    }
-    return { type: 'local', command: ['npx', '-y', CLI_PACKAGE_SPEC, 'mcp'] };
+    const entry = getPackageRunnerMcpEntry();
+    return { type: 'local', command: [entry.command, ...entry.args] };
 }
 /**
  * Merge codragraph entry into an existing MCP config JSON object.

package/dist/cli/status.d.ts

@@ -3,4 +3,17 @@
  *
  * Shows the indexing status of the current repository.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
+export declare const LARGE_INDEX_WARNING_BYTES: number;
+export interface IndexStorageSummary {
+    path: string;
+    bytes: number;
+    fileCount: number;
+    unreadableEntries: number;
+}
+export declare const formatBytes: (bytes: number) => string;
+export declare const summarizeIndexStorage: (storagePath: string) => Promise<IndexStorageSummary | null>;
+export declare const formatIndexStatusLines: (summary: IndexStorageSummary | null, meta: Pick<RepoMeta, "stats" | "compress">, options?: {
+    largeIndexWarningBytes?: number;
+}) => string[];
 export declare const statusCommand: () => Promise<void>;

package/dist/cli/status.js

@@ -3,8 +3,99 @@
  *
  * Shows the indexing status of the current repository.
  */
+import fs from 'fs/promises';
+import path from 'path';
 import { findRepo, getStoragePaths, hasKuzuIndex } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
+export const LARGE_INDEX_WARNING_BYTES = 500 * 1024 * 1024;
+const STORAGE_SCAN_BATCH_SIZE = 64;
+export const formatBytes = (bytes) => {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    if (unitIndex === 0)
+        return `${Math.round(value)} ${units[unitIndex]}`;
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+};
+export const summarizeIndexStorage = async (storagePath) => {
+    let rootStat;
+    try {
+        rootStat = await fs.lstat(storagePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        return { path: storagePath, bytes: 0, fileCount: 0, unreadableEntries: 1 };
+    }
+    if (!rootStat.isDirectory()) {
+        return { path: storagePath, bytes: rootStat.size, fileCount: 1, unreadableEntries: 0 };
+    }
+    const stack = [storagePath];
+    let bytes = 0;
+    let fileCount = 0;
+    let unreadableEntries = 0;
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = await fs.readdir(current, { withFileTypes: true });
+        }
+        catch {
+            unreadableEntries += 1;
+            continue;
+        }
+        for (let i = 0; i < entries.length; i += STORAGE_SCAN_BATCH_SIZE) {
+            const batch = entries.slice(i, i + STORAGE_SCAN_BATCH_SIZE);
+            const stats = await Promise.all(batch.map(async (entry) => {
+                const entryPath = path.join(current, entry.name);
+                try {
+                    return { entryPath, stat: await fs.lstat(entryPath) };
+                }
+                catch {
+                    return { entryPath, stat: null };
+                }
+            }));
+            for (const { entryPath, stat } of stats) {
+                if (!stat) {
+                    unreadableEntries += 1;
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    stack.push(entryPath);
+                    continue;
+                }
+                bytes += stat.size;
+                fileCount += 1;
+            }
+        }
+    }
+    return { path: storagePath, bytes, fileCount, unreadableEntries };
+};
+export const formatIndexStatusLines = (summary, meta, options = {}) => {
+    const lines = [];
+    const threshold = options.largeIndexWarningBytes ?? LARGE_INDEX_WARNING_BYTES;
+    if (summary) {
+        const fileLabel = summary.fileCount === 1 ? 'file' : 'files';
+        lines.push(`Index size: ${formatBytes(summary.bytes)} (${summary.fileCount.toLocaleString('en-US')} ${fileLabel} under .codragraph)`);
+        if (summary.unreadableEntries > 0) {
+            const entryLabel = summary.unreadableEntries === 1 ? 'entry' : 'entries';
+            lines.push(`Index size note: ${summary.unreadableEntries.toLocaleString('en-US')} ${entryLabel} could not be read.`);
+        }
+        if (summary.bytes >= threshold) {
+            lines.push(`Storage warning: .codragraph is ${formatBytes(summary.bytes)} (>= ${formatBytes(threshold)}). Consider codragraph analyze --compress brotli (or zstd on Node >=22.15) and only use --embeddings when vectors are needed.`);
+        }
+    }
+    const embeddings = meta.stats?.embeddings;
+    lines.push(`Embeddings: ${typeof embeddings === 'number' ? embeddings.toLocaleString('en-US') : 'unknown'}`);
+    lines.push(`Compression: ${meta.compress ?? 'none'}`);
+    return lines;
+};
 export const statusCommand = async () => {
     const cwd = process.cwd();
     if (!isGitRepo(cwd)) {
@@ -16,6 +107,7 @@ export const statusCommand = async () => {
         // Check if there's a stale KuzuDB index that needs migration
         const repoRoot = getGitRoot(cwd) ?? cwd;
         const { storagePath } = getStoragePaths(repoRoot);
+        const storageSummary = await summarizeIndexStorage(storagePath);
         if (await hasKuzuIndex(storagePath)) {
             console.log('Repository has a stale KuzuDB index from a previous version.');
             console.log('Run: codragraph analyze   (rebuilds the index with LadybugDB)');
@@ -24,13 +116,20 @@ export const statusCommand = async () => {
             console.log('Repository not indexed.');
             console.log('Run: codragraph analyze');
         }
+        if (storageSummary) {
+            for (const line of formatIndexStatusLines(storageSummary, {}))
+                console.log(line);
+        }
         return;
     }
     const currentCommit = getCurrentCommit(repo.repoPath);
     const isUpToDate = currentCommit === repo.meta.lastCommit;
+    const storageSummary = await summarizeIndexStorage(repo.storagePath);
     console.log(`Repository: ${repo.repoPath}`);
     console.log(`Indexed: ${new Date(repo.meta.indexedAt).toLocaleString()}`);
     console.log(`Indexed commit: ${repo.meta.lastCommit?.slice(0, 7)}`);
     console.log(`Current commit: ${currentCommit?.slice(0, 7)}`);
+    for (const line of formatIndexStatusLines(storageSummary, repo.meta))
+        console.log(line);
     console.log(`Status: ${isUpToDate ? '✅ up-to-date' : '⚠️ stale (re-run codragraph analyze)'}`);
 };

package/dist/cli/tool.js

@@ -17,6 +17,7 @@
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { emitTokenStats } from './compress-stats.js';
+import { findRepo } from '../storage/repo-manager.js';
 let _backend = null;
 async function getBackend() {
     if (_backend)
@@ -29,6 +30,21 @@ async function getBackend() {
     }
     return _backend;
 }
+async function callToolOnce(toolName, params) {
+    const backend = await getBackend();
+    return backend.callTool(toolName, params);
+}
+async function resolveCliRepoParam(repoParam) {
+    if (repoParam)
+        return repoParam;
+    const currentRepo = await findRepo(process.cwd());
+    if (currentRepo)
+        return currentRepo.repoPath;
+    output(`Error: Current repository is not indexed: ${process.cwd()}\n` +
+        'Run: npx @codragraph/cli analyze');
+    process.exitCode = 1;
+    return null;
+}
 /**
  * Write tool output to stdout using low-level fd write.
  *
@@ -59,14 +75,16 @@ export async function queryCommand(queryText, options) {
         console.error('Usage: codragraph query <search_query>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('query', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('query', {
         query: queryText,
         task_context: options?.context,
         goal: options?.goal,
         limit: options?.limit ? parseInt(options.limit) : undefined,
         include_content: options?.content ?? false,
-        repo: options?.repo,
+        repo,
     });
     output(result);
     emitTokenStats(result);
@@ -76,13 +94,15 @@ export async function contextCommand(name, options) {
         console.error('Usage: codragraph context <symbol_name> [--uid <uid>] [--file <path>]');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('context', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('context', {
         name: name || undefined,
         uid: options?.uid,
         file_path: options?.file,
         include_content: options?.content ?? false,
-        repo: options?.repo,
+        repo,
     });
     output(result);
     emitTokenStats(result);
@@ -93,13 +113,15 @@ export async function impactCommand(target, options) {
         process.exit(1);
     }
     try {
-        const backend = await getBackend();
-        const result = await backend.callTool('impact', {
+        const repo = await resolveCliRepoParam(options?.repo);
+        if (!repo)
+            return;
+        const result = await callToolOnce('impact', {
             target,
             direction: options?.direction || 'upstream',
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
-            repo: options?.repo,
+            repo,
         });
         output(result);
         emitTokenStats(result);
@@ -121,26 +143,32 @@ export async function cypherCommand(query, options) {
         console.error('Usage: codragraph cypher <cypher_query>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('cypher', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('cypher', {
         query,
-        repo: options?.repo,
+        repo,
     });
     output(result);
 }
 export async function featureClustersCommand(options) {
-    const backend = await getBackend();
-    const result = await backend.callTool('feature_clusters', {
-        repo: options?.repo,
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('feature_clusters', {
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
 }
 export async function clusterQueryCommand(query, options) {
-    const backend = await getBackend();
-    const result = await backend.callTool('cluster_query', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('cluster_query', {
         query,
-        repo: options?.repo,
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
@@ -150,10 +178,12 @@ export async function featureContextCommand(name, options) {
         console.error('Usage: codragraph feature-context <name>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('feature_context', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('feature_context', {
         name,
-        repo: options?.repo,
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
@@ -164,10 +194,12 @@ export async function clusterContextCommand(name, options) {
         console.error('Usage: codragraph cluster-context <name>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('cluster_context', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('cluster_context', {
         name,
-        repo: options?.repo,
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
@@ -178,10 +210,12 @@ export async function contextPackCommand(name, options) {
         console.error('Usage: codragraph context-pack <name>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('context_pack', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('context_pack', {
         name,
-        repo: options?.repo,
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
@@ -192,11 +226,13 @@ export async function clusterImpactCommand(name, options) {
         console.error('Usage: codragraph cluster-impact <name>');
         process.exit(1);
     }
-    const backend = await getBackend();
-    const result = await backend.callTool('cluster_impact', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('cluster_impact', {
         name,
         direction: options?.direction,
-        repo: options?.repo,
+        repo,
         limit: options?.limit ? parseInt(options.limit, 10) : undefined,
     });
     output(result);
@@ -236,11 +272,15 @@ function formatDetectChangesResult(result) {
     return lines.join('\n').trim();
 }
 export async function detectChangesCommand(options) {
-    const backend = await getBackend();
-    const result = await backend.callTool('detect_changes', {
+    const repo = await resolveCliRepoParam(options?.repo);
+    if (!repo)
+        return;
+    const result = await callToolOnce('detect_changes', {
         scope: options?.scope || 'unstaged',
         base_ref: options?.baseRef,
-        repo: options?.repo,
+        repo,
     });
     output(formatDetectChangesResult(result));
+    if (result?.error)
+        process.exitCode = 1;
 }

package/dist/config/ignore-service.js

@@ -4,6 +4,7 @@ import nodePath from 'path';
 const DEFAULT_IGNORE_LIST = new Set([
     // Version Control
     '.git',
+    '.codragraph',
     '.svn',
     '.hg',
     '.bzr',
@@ -212,6 +213,8 @@ const IGNORED_EXTENSIONS = new Set([
 // Files to ignore by exact name
 const IGNORED_FILES = new Set([
     'package-lock.json',
+    'bun.lock',
+    'bun.lockb',
     'yarn.lock',
     'pnpm-lock.yaml',
     'composer.lock',

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

@@ -16,7 +16,49 @@
  */
 import fs from 'fs/promises';
 import cgdb from '@ladybugdb/core';
+import { NODE_TABLES } from './schema.js';
 const pool = new Map();
+const SIMPLE_LABELLESS_MATCH_RE = /^MATCH\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/i;
+const CYPHER_LIMIT_RE = /\bLIMIT\s+(\d+)\s*;?\s*$/i;
+const CYPHER_RELATION_RE = /--|-\[|\]-|->|<-/;
+const NATIVE_UNSAFE_NODE_LABELS = new Set(['Union']);
+function quoteKnownNodeLabels(query) {
+    return query;
+}
+function getNativeUnsafeNodeLabel(query) {
+    const labelRe = /\(\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*`?([A-Za-z_][A-Za-z0-9_]*)`?(?=[\s){])/g;
+    for (const match of query.matchAll(labelRe)) {
+        const label = match[1];
+        if (NATIVE_UNSAFE_NODE_LABELS.has(label))
+            return label;
+    }
+    return null;
+}
+function getSimpleLabellessNodeAlias(query) {
+    const trimmed = query.trim();
+    const match = SIMPLE_LABELLESS_MATCH_RE.exec(trimmed);
+    if (!match)
+        return null;
+    if (CYPHER_RELATION_RE.test(trimmed))
+        return null;
+    if (/\bMATCH\b/i.test(trimmed.slice(match[0].length)))
+        return null;
+    return match[1];
+}
+function getCypherLimit(query) {
+    const match = CYPHER_LIMIT_RE.exec(query);
+    if (!match)
+        return null;
+    const limit = Number.parseInt(match[1], 10);
+    return Number.isFinite(limit) && limit > 0 ? limit : null;
+}
+function withCypherLimit(query, limit) {
+    const safeLimit = Math.max(1, Math.trunc(limit));
+    if (CYPHER_LIMIT_RE.test(query)) {
+        return query.replace(CYPHER_LIMIT_RE, `LIMIT ${safeLimit}`);
+    }
+    return `${query.replace(/;\s*$/, '')} LIMIT ${safeLimit}`;
+}
 const poolCloseListeners = new Set();
 /**
  * Subscribe to pool-close events. Returns a disposer that removes the
@@ -463,15 +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 initCgdb first.`);
-    }
-    if (isWriteQuery(cypher)) {
-        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
-    }
-    entry.lastUsed = Date.now();
+async function runQueryOnEntry(entry, cypher) {
     const conn = await checkout(entry);
     silenceStdout();
     activeQueryCount++;
@@ -486,17 +520,8 @@ export const executeQuery = async (repoId, cypher) => {
         restoreStdout();
         checkin(entry, conn);
     }
-};
-/**
- * Execute a parameterized query on a specific repo's connection pool.
- * Uses prepare/execute pattern to prevent Cypher injection.
- */
-export const executeParameterized = async (repoId, cypher, params) => {
-    const entry = pool.get(repoId);
-    if (!entry) {
-        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initCgdb first.`);
-    }
-    entry.lastUsed = Date.now();
+}
+async function runParameterizedOnEntry(entry, cypher, params) {
     const conn = await checkout(entry);
     silenceStdout();
     activeQueryCount++;
@@ -516,6 +541,91 @@ export const executeParameterized = async (repoId, cypher, params) => {
         restoreStdout();
         checkin(entry, conn);
     }
+}
+async function runLabellessNodeScan(query, alias, runner) {
+    const limit = getCypherLimit(query) ?? 100;
+    const rows = [];
+    let lastError = null;
+    for (const label of NODE_TABLES) {
+        if (NATIVE_UNSAFE_NODE_LABELS.has(label))
+            continue;
+        if (rows.length >= limit)
+            break;
+        const labelQuery = withCypherLimit(query.replace(SIMPLE_LABELLESS_MATCH_RE, `MATCH (${alias}:\`${label}\`)`), limit - rows.length);
+        try {
+            const labelRows = await runner(labelQuery);
+            rows.push(...decorateLabellessRows(labelRows, label));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (!isBenignLabelScanError(error)) {
+                lastError = error;
+            }
+        }
+    }
+    if (rows.length === 0 && lastError) {
+        throw lastError;
+    }
+    return rows.slice(0, limit);
+}
+function decorateLabellessRows(rows, label) {
+    return rows.map((row) => {
+        if (!row || typeof row !== 'object' || Array.isArray(row))
+            return row;
+        const decorated = { ...row, __cgLabel: label };
+        for (const key of ['type', 'kind', 'label']) {
+            const value = decorated[key];
+            if (value === '' || value === null || value === undefined) {
+                decorated[key] = label;
+            }
+        }
+        return decorated;
+    });
+}
+function isBenignLabelScanError(error) {
+    const message = error.message.toLowerCase();
+    return (message.includes('cannot find property') ||
+        message.includes('does not have property') ||
+        message.includes('property') && message.includes('not found'));
+}
+export const executeQuery = async (repoId, cypher) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initCgdb first.`);
+    }
+    const safeCypher = quoteKnownNodeLabels(cypher);
+    if (isWriteQuery(safeCypher)) {
+        throw new Error('Write operations are not allowed. The pool adapter is read-only.');
+    }
+    if (getNativeUnsafeNodeLabel(safeCypher)) {
+        return [];
+    }
+    entry.lastUsed = Date.now();
+    const labellessAlias = getSimpleLabellessNodeAlias(safeCypher);
+    if (labellessAlias) {
+        return runLabellessNodeScan(safeCypher, labellessAlias, (labelQuery) => runQueryOnEntry(entry, labelQuery));
+    }
+    return runQueryOnEntry(entry, safeCypher);
+};
+/**
+ * Execute a parameterized query on a specific repo's connection pool.
+ * Uses prepare/execute pattern to prevent Cypher injection.
+ */
+export const executeParameterized = async (repoId, cypher, params) => {
+    const entry = pool.get(repoId);
+    if (!entry) {
+        throw new Error(`LadybugDB not initialized for repo "${repoId}". Call initCgdb first.`);
+    }
+    entry.lastUsed = Date.now();
+    const safeCypher = quoteKnownNodeLabels(cypher);
+    if (getNativeUnsafeNodeLabel(safeCypher)) {
+        return [];
+    }
+    const labellessAlias = getSimpleLabellessNodeAlias(safeCypher);
+    if (labellessAlias) {
+        return runLabellessNodeScan(safeCypher, labellessAlias, (labelQuery) => runParameterizedOnEntry(entry, labelQuery, params));
+    }
+    return runParameterizedOnEntry(entry, safeCypher, params);
 };
 /**
  * Close one or all repo pools.

package/dist/core/graphstore/cgdb-row-source.js

@@ -26,7 +26,7 @@ export const createCgdbRowSource = (opts = {}) => {
             // `core/search/bm25-index.ts` for FTS results. Tables that do not
             // exist on disk for a given repo throw here — we treat that as
             // "no rows" via the onSkip callback rather than a hard failure.
-            rows = await executeQuery(`MATCH (n:${tableName}) RETURN n`);
+            rows = await executeQuery(`MATCH (n:${quoteCypherIdentifier(tableName)}) RETURN n`);
         }
         catch (err) {
             onSkip(tableName, err);
@@ -55,7 +55,7 @@ export const createCgdbRowSource = (opts = {}) => {
             // `rel`. Scalars give us a deterministic edge id even if the rel
             // payload's shape changes; `rel` carries any extra properties for
             // hashing.
-            rows = await executeQuery(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
+            rows = await executeQuery(`MATCH (a)-[r:${quoteCypherIdentifier(REL_TABLE_NAME)}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
         }
         catch (err) {
             onSkip(REL_TABLE_NAME, err);
@@ -100,6 +100,7 @@ const pickField = (row, named, positional) => {
     return row[named] ?? row[positional];
 };
 const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const quoteCypherIdentifier = (identifier) => `\`${identifier.replace(/`/g, '``')}\``;
 /**
  * Sanitize a node row for canonical hashing:
  *   - Drop LadybugDB-specific internal fields (`_id`, `_label`) that are