@codragraph/cli 2.1.1 → 2.1.4

package/README.md

@@ -55,16 +55,16 @@ If you prefer to configure manually instead of using `codragraph setup`:
 
 ```bash
 # macOS / Linux
-claude mcp add codragraph -- npx -y @codragraph/cli@2.1.1 mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@2.1.2 mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.1 mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.2 mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y @codragraph/cli@2.1.1 mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@2.1.2 mcp
 ```
 
 ### Cursor / Windsurf
@@ -76,7 +76,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.1", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
     }
   }
 }
@@ -91,7 +91,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.1", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
     }
   }
 }
@@ -172,7 +172,8 @@ codragraph feature-context Settings # Focus files, line ranges, flows, dependenc
 codragraph context-pack Settings    # Compact agent context pack for one feature
 codragraph cluster-impact Settings --direction both  # Feature-level blast radius
 codragraph mcp                     # Start MCP server (stdio) — serves all indexed repos
-codragraph serve                   # Start local HTTP server (multi-repo) for web UI
+codragraph serve                   # Start local HTTP API + bundled web UI
+codragraph serve --web hosted      # API only; connect from hosted web UI
 codragraph index                   # Register an existing .codragraph/ folder into the global registry
 codragraph list                    # List all indexed repositories
 codragraph status                  # Show index status for current repo
@@ -296,9 +297,9 @@ It is fixed in **codragraph v1.6.2+**. Upgrade to the current workspace
 version, or pin the version your team has validated:
 
 ```bash
-npx @codragraph/cli@2.1.1 analyze          # no global install
+npx @codragraph/cli@2.1.2 analyze          # no global install
 # or
-npm install -g @codragraph/cli@2.1.1       # upgrade a global install
+npm install -g @codragraph/cli@2.1.2       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds
@@ -402,7 +403,9 @@ Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling;
 
 CodraGraph also has a browser-based UI at [codragraph.vercel.app](https://codragraph.vercel.app) — 100% client-side, your code never leaves the browser.
 
-**Local Backend Mode:** Run `codragraph serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, feature clusters, dependency context, and full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+**Local Backend Mode:** Run `codragraph serve` and open `http://localhost:4747`. The installed CLI serves the bundled dashboard from `dist/web` and does not package `apps/web/node_modules`. It auto-detects the server and shows all your indexed repos, feature clusters, dependency context, and full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+
+**Hosted Dashboard Mode:** Run `codragraph serve --web hosted`, then open the hosted dashboard and connect it to `http://localhost:4747`. The UI is hosted, but project data still comes from your local API.
 
 ## License
 

package/dist/cli/ai-context.js

@@ -122,7 +122,7 @@ This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}*
 `
         : ''}## CLI
 
-Commands are cross-platform: use \`npx @codragraph/cli ...\` or \`codragraph ...\` in Windows PowerShell, macOS bash/zsh, and Linux shells. Prefer package commands like \`npm --prefix packages/core test\` from repo root instead of shell-specific \`cd dir && ...\` chains.
+Commands are cross-platform: \`codragraph ...\`, \`npx @codragraph/cli ...\`, or \`bunx @codragraph/cli ...\`. Scripts: \`npm --prefix ...\` or \`bun run --filter ...\`.
 
 ${skillsTable}
 

package/dist/cli/analyze.js

@@ -19,6 +19,7 @@ import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import fs from 'fs/promises';
+import { formatBytes, LARGE_INDEX_WARNING_BYTES, summarizeIndexStorage } from './status.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
 const CLI_PACKAGE_SPEC = `@codragraph/cli@${pkg.version}`;
@@ -255,7 +256,7 @@ export const analyzeCommand = async (inputPath, options) => {
             console.warn = origWarn;
             console.error = origError;
             bar.stop();
-            console.log('  Already up to date\n');
+            console.log(`  ${result.reuseReason ?? 'Already up to date'}\n`);
             // Safe to return without process.exit(0) — the early-return path in
             // runFullAnalysis never opens LadybugDB, so no native handles prevent exit.
             return;
@@ -324,6 +325,20 @@ export const analyzeCommand = async (inputPath, options) => {
         console.log(`\n  Repository indexed successfully (${totalTime}s)\n`);
         console.log(`  ${(s.nodes ?? 0).toLocaleString()} nodes | ${(s.edges ?? 0).toLocaleString()} edges | ${s.communities ?? 0} clusters | ${s.processes ?? 0} flows`);
         console.log(`  ${repoPath}`);
+        try {
+            const { storagePath } = getStoragePaths(repoPath);
+            const storageSummary = await summarizeIndexStorage(storagePath);
+            if (storageSummary) {
+                console.log(`  .codragraph size: ${formatBytes(storageSummary.bytes)}`);
+                if (storageSummary.bytes >= LARGE_INDEX_WARNING_BYTES) {
+                    console.log(`  Storage warning: index is >= ${formatBytes(LARGE_INDEX_WARNING_BYTES)}. ` +
+                        `Use --compress brotli (or zstd on Node >=22.15) and reserve --embeddings for repos that need vector search.`);
+                }
+            }
+        }
+        catch {
+            /* size summary is best-effort */
+        }
         // Surface @codragraph/compress's value prop with concrete numbers: how
         // many tokens of distilled context did we generate. Best-effort — never
         // fail the analyze for a stat read.
@@ -391,12 +406,13 @@ export const analyzeCommand = async (inputPath, options) => {
             // 'node.target'" crash happens inside npm *before* codragraph code runs,
             // so it can't be caught here.  This branch handles dependency-resolution
             // errors that surface at runtime (e.g. dynamic require failures).
-            console.error('  This looks like an npm dependency resolution issue.');
+            console.error('  This looks like a package-manager dependency resolution issue.');
             console.error('  Suggestions:');
             console.error('    1. Clear the npm cache:    npm cache clean --force');
             console.error('    2. Update npm:             npm install -g npm@latest');
             console.error(`    3. Reinstall codragraph:     npm install -g ${CLI_PACKAGE_SPEC}`);
             console.error(`    4. Or try npx directly:    npx ${CLI_PACKAGE_SPEC} analyze`);
+            console.error(`    5. Bun alternative:        bunx ${CLI_PACKAGE_SPEC} analyze`);
             console.error('');
         }
         else if (msg.includes('MODULE_NOT_FOUND') ||
@@ -406,6 +422,7 @@ export const analyzeCommand = async (inputPath, options) => {
             console.error('  Suggestions:');
             console.error(`    1. Reinstall:   npm install -g ${CLI_PACKAGE_SPEC}`);
             console.error(`    2. Clear cache: npm cache clean --force && npx ${CLI_PACKAGE_SPEC} analyze`);
+            console.error(`    3. Bun cache:   bun pm cache rm && bunx ${CLI_PACKAGE_SPEC} analyze`);
             console.error('');
         }
         process.exitCode = 1;

package/dist/cli/index.js

@@ -55,9 +55,10 @@ program
     .action(createLazyAction(() => import('./index-repo.js'), 'indexCommand'));
 program
     .command('serve')
-    .description('Start local HTTP server for web UI connection')
+    .description('Start local HTTP API and web dashboard')
     .option('-p, --port <port>', 'Port number', '4747')
     .option('--host <host>', 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)')
+    .option('--web <mode>', 'Dashboard mode: local serves the bundled app, hosted prints hosted UI connection info, off serves API only', 'local')
     .action(createLazyAction(() => import('./serve.js'), 'serveCommand'));
 program
     .command('mcp')

package/dist/cli/serve.d.ts

@@ -1,4 +1,5 @@
 export declare const serveCommand: (options?: {
     port?: string;
     host?: string;
+    web?: string;
 }) => Promise<void>;

package/dist/cli/serve.js

@@ -1,4 +1,5 @@
 import { createServer } from '../server/api.js';
+import { normalizeWebDashboardMode } from '../server/web-dashboard.js';
 // Catch anything that would cause a silent exit
 process.on('uncaughtException', (err) => {
     console.error('\n[codragraph serve] Uncaught exception:', err.message);
@@ -19,7 +20,8 @@ export const serveCommand = async (options) => {
     // hosted frontend at codragraph.vercel.app connects to localhost.
     const host = options?.host ?? 'localhost';
     try {
-        await createServer(port, host);
+        const web = normalizeWebDashboardMode(options?.web);
+        await createServer(port, host, { web });
     }
     catch (err) {
         console.error(`\nFailed to start CodraGraph server:\n`);

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/config/ignore-service.js

@@ -212,6 +212,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/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

package/dist/core/group/bridge-db.js

@@ -74,7 +74,7 @@ export function findContractNode(index, repo, role, symbolUid, filePath, symbolN
 export async function openBridgeDb(dbPath) {
     const parentDir = path.dirname(dbPath);
     await fsp.mkdir(parentDir, { recursive: true });
-    const db = new cgdb.Database(dbPath, 0, false, false); // writable
+    const db = new cgdb.Database(dbPath, 0, false, false, BRIDGE_MAX_DB_SIZE_BYTES); // writable
     const conn = new cgdb.Connection(db);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
@@ -238,6 +238,25 @@ export async function retryRename(src, dst, attempts = 3) {
         }
     }
 }
+async function removeBridgeArtifacts(basePath) {
+    for (const candidate of [basePath, `${basePath}.wal`, `${basePath}.lock`]) {
+        try {
+            await fsp.rm(candidate, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function renameBridgeArtifactIfExists(src, dst) {
+    try {
+        await fsp.access(src);
+    }
+    catch {
+        return;
+    }
+    await retryRename(src, dst);
+}
 /* ------------------------------------------------------------------ */
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
@@ -261,6 +280,10 @@ export async function readBridgeMeta(groupDir) {
     }
 }
 const MAX_SAMPLE_ERRORS = 10;
+// LadybugDB defaults maxDBSize to an 8 TiB mmap window on some platforms.
+// Bridge databases are small contract registries, so cap the mapping to keep
+// CI and low-resource user machines from failing before the first query.
+const BRIDGE_MAX_DB_SIZE_BYTES = 512 * 1024 * 1024;
 function errMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -293,13 +316,9 @@ export async function writeBridge(groupDir, input) {
             report.sampleErrors.push({ kind, id, message: errMessage(err) });
         }
     };
-    // Clean up any leftover tmp
-    try {
-        await fsp.rm(tmpPath, { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    // Clean up any leftover tmp plus native sidecars. LadybugDB stores WAL/lock
+    // files next to the database path, not inside it.
+    await removeBridgeArtifacts(tmpPath);
     // 1. Create temp DB, insert all data.
     //
     // Everything after `openBridgeDb` must run inside a try/finally so that
@@ -440,16 +459,27 @@ export async function writeBridge(groupDir, input) {
         }
     }
     // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+    // Keep LadybugDB sidecars paired with the path rename. WAL files live next
+    // to the DB path, so renaming only the base path can hide fresh schema/data.
+    await removeBridgeArtifacts(bakPath);
     try {
         await fsp.access(finalPath);
         await retryRename(finalPath, bakPath);
+        await renameBridgeArtifactIfExists(`${finalPath}.wal`, `${bakPath}.wal`);
     }
     catch {
         /* no existing db */
     }
     await retryRename(tmpPath, finalPath);
+    await renameBridgeArtifactIfExists(`${tmpPath}.wal`, `${finalPath}.wal`);
+    try {
+        await fsp.rm(`${tmpPath}.lock`, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
     try {
-        await fsp.rm(bakPath, { recursive: true, force: true });
+        await removeBridgeArtifacts(bakPath);
     }
     catch {
         /* ignore */
@@ -480,6 +510,8 @@ export async function openBridgeDbReadOnly(groupDir) {
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
+            await renameBridgeArtifactIfExists(`${bakPath}.wal`, `${dbPath}.wal`);
+            await fsp.rm(`${bakPath}.lock`, { force: true });
         }
         catch {
             return null;
@@ -506,7 +538,7 @@ export async function openBridgeDbReadOnly(groupDir) {
         let db;
         let conn;
         try {
-            db = new cgdb.Database(dbPath, 0, false, true); // readOnly
+            db = new cgdb.Database(dbPath, 0, false, true, BRIDGE_MAX_DB_SIZE_BYTES); // readOnly
             conn = new cgdb.Connection(db);
             return { _db: db, _conn: conn, groupDir };
         }

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
 import type { ContentEncoding } from '@codragraph/graphstore';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
@@ -68,10 +69,29 @@ export interface AnalyzeResult {
         embeddings?: number;
     };
     alreadyUpToDate?: boolean;
+    /** User-facing explanation for a reused index fast path. */
+    reuseReason?: string;
+    /** True when the git commit advanced but indexed inputs did not. */
+    reusedExistingIndex?: boolean;
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
 }
+export interface AnalyzeChangedPath {
+    /** Git name-status token, e.g. M, A, D, R100. */
+    status: string;
+    /** Current path for additions/modifications, or deleted path for deletions. */
+    path: string;
+    /** Previous path for renames/copies. */
+    previousPath?: string;
+}
 export declare const PHASE_LABELS: Record<string, string>;
+export declare const parseGitNameStatus: (raw: string) => AnalyzeChangedPath[];
+export declare const listChangedPathsBetweenCommits: (repoPath: string, fromRef: string, toRef: string) => AnalyzeChangedPath[] | null;
+export declare const isGeneratedAgentContextPath: (filePath: string) => boolean;
+export declare const isGraphContentPath: (filePath: string) => boolean;
+export declare const changedPathAffectsGraph: (change: AnalyzeChangedPath) => boolean;
+export declare const getGraphRelevantChangedPaths: (changes: readonly AnalyzeChangedPath[]) => AnalyzeChangedPath[];
+export declare const getAnalyzeConfigRebuildReason: (existingMeta: Pick<RepoMeta, "compress" | "stats">, options: Pick<AnalyzeOptions, "compress" | "embeddings">) => string | null;
 /**
  * Run the full CodraGraph analysis pipeline.
  *