@codragraph/cli 1.6.4 → 2.0.0

package/dist/core/run-analyze.js

@@ -10,9 +10,11 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import * as fsSync from 'node:fs';
+import * as v8 from 'node:v8';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, } from './lbug/lbug-adapter.js';
-import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, } from '../storage/repo-manager.js';
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, INDEX_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
 import { recordAnalysisSnapshot } from './graphstore/index.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
@@ -51,7 +53,70 @@ export const PHASE_LABELS = {
  */
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
-    const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
+    // RFC 0002 Phase 1 — optional heap-profile instrumentation. Set
+    // CODRAGRAPH_HEAP_PROFILE=1 (or run `codragraph profile-heap`) to write a
+    // v8 heap snapshot at every phase boundary, plus a `profile-summary.jsonl`
+    // log of `process.memoryUsage()` at the same boundaries. Snapshots land in
+    // `<repo>/.codragraph/heap-profiles/`. Open snapshots in Chrome DevTools
+    // (Memory → Load) to find which constructors dominate retained set; the
+    // JSONL is the cheap RSS / heapUsed timeline. Off by default — snapshot
+    // writes pause the event loop ~2-5s and consume ~100-500MB of disk each.
+    const heapProfileEnabled = process.env.CODRAGRAPH_HEAP_PROFILE === '1';
+    let heapProfileDir = '';
+    let heapProfileSummaryPath = '';
+    let lastProfilePhase = '';
+    if (heapProfileEnabled) {
+        heapProfileDir = path.join(repoPath, '.codragraph', 'heap-profiles');
+        heapProfileSummaryPath = path.join(heapProfileDir, 'profile-summary.jsonl');
+        try {
+            fsSync.mkdirSync(heapProfileDir, { recursive: true });
+            // Truncate any prior summary so a single run produces a clean log.
+            // We append crash-safely on each phase boundary below.
+            fsSync.writeFileSync(heapProfileSummaryPath, '');
+        }
+        catch {
+            /* permission issue — best-effort */
+        }
+    }
+    const progress = (phase, percent, message) => {
+        callbacks.onProgress(phase, percent, message);
+        // Only snapshot on phase transitions, not every tick. Phase strings come
+        // from runPipelineFromRepo / loadGraphToLbug and are stable.
+        if (heapProfileEnabled && phase && phase !== lastProfilePhase) {
+            lastProfilePhase = phase;
+            const ts = Date.now();
+            const safe = phase.replace(/[^a-zA-Z0-9]+/g, '_').slice(0, 60);
+            const file = path.join(heapProfileDir, `${ts}-${safe}.heapsnapshot`);
+            // Capture the cheap memoryUsage timeline FIRST — even if writeHeapSnapshot
+            // crashes (out of disk, permissions), we still have the RSS curve which
+            // is the more useful artifact for the heap-pressure RFC.
+            try {
+                const mu = process.memoryUsage();
+                const entry = JSON.stringify({
+                    ts,
+                    phase,
+                    percent,
+                    rss: mu.rss,
+                    heapUsed: mu.heapUsed,
+                    heapTotal: mu.heapTotal,
+                    external: mu.external,
+                    arrayBuffers: mu.arrayBuffers,
+                    snapshotFile: path.basename(file),
+                });
+                fsSync.appendFileSync(heapProfileSummaryPath, entry + '\n');
+            }
+            catch (err) {
+                log(`heap-profile: summary append failed (${err.message})`);
+            }
+            try {
+                v8.writeHeapSnapshot(file);
+                log(`heap-profile: wrote ${file}`);
+            }
+            catch (err) {
+                log(`heap-profile: write failed (${err.message})`);
+            }
+        }
+    };
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
     // Clean up stale KuzuDB files from before the LadybugDB migration.
     const kuzuResult = await cleanupOldKuzuFiles(storagePath);
@@ -62,7 +127,17 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
     const existingMeta = await loadMeta(storagePath);
     // ── Early-return: already up to date ──────────────────────────────
-    if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
+    // Schema-version mismatch forces a full re-analyze regardless of commit
+    // equality: existing 1.7.x indexes have no `schemaVersion` field at all,
+    // and 1.8+ readers expect every node table to carry a `contentEncoding`
+    // column (RFC 0001 Phase 2). LadybugDB ALTER on existing tables is not
+    // validated end-to-end yet, so the supported migration path is
+    // re-analyze → fresh CREATE NODE TABLE.
+    const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
+    if (existingMeta &&
+        schemaUpToDate &&
+        !options.force &&
+        existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
             return {
@@ -73,6 +148,11 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             };
         }
     }
+    if (existingMeta && !schemaUpToDate) {
+        log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
+            `${INDEX_SCHEMA_VERSION} (RFC 0001 Phase 2 — adds contentEncoding column). ` +
+            `Re-analyzing.`);
+    }
     // ── Cache embeddings from existing index before rebuild ────────────
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
@@ -122,7 +202,12 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             lbugMsgCount++;
             const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
             progress('lbug', pct, msg);
-        });
+        }, 
+        // RFC 0001 Phase 2: when --compress is set, every content row goes
+        // through encodeContent before hitting the CSV. Default 'none' is
+        // a true passthrough, so the on-disk layout is byte-identical to
+        // pre-Phase-2 indexes when no compression flag is passed.
+        { compress: options.compress });
         // ── Phase 2.5: Versioned-graph snapshot (best-effort) ────────────
         // Phase 4 hook: snapshot the freshly-loaded graph into the
         // content-addressed `.codragraph/graphstore/`. Failures here do NOT
@@ -230,6 +315,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            compress: options.compress ?? 'none',
             // Captured here (not at registration) so it travels with the
             // on-disk meta.json — sibling-clone fingerprinting works for
             // out-of-tree consumers (group-status, future tooling) without

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

@@ -12,17 +12,56 @@
  */
 import { queryFTS, ensureFTSIndex, executeQuery as executeCoreQuery, } from '../lbug/lbug-adapter.js';
 /**
- * FTS schema served by `searchFTSFromLbug`. Centralised so that both the
- * CLI/pipeline path and the MCP pool path use identical (table, index,
- * properties) tuples and the lazy-create logic stays in one place.
+ * FTS table set served by `searchFTSFromLbug`. Centralised so that both
+ * the CLI/pipeline path and the MCP pool path stay in lockstep.
+ *
+ * The properties list is computed at FTS-create time via `ftsPropertiesFor`
+ * — for repos that were analysed with `--compress brotli|zstd`, the
+ * `content` column holds base64-of-encoded-bytes and would tokenise to
+ * useless tokens. Those repos get name-only FTS so search at least
+ * matches function/class names instead of returning random hits on
+ * base64 alphabet. Plain (compress='none' / unset) repos get the full
+ * `name + content` index for body-text matches. RFC 0001 Phase 2.5.
  */
-const FTS_INDEXES = [
-    { table: 'File', indexName: 'file_fts', properties: ['name', 'content'] },
-    { table: 'Function', indexName: 'function_fts', properties: ['name', 'content'] },
-    { table: 'Class', indexName: 'class_fts', properties: ['name', 'content'] },
-    { table: 'Method', indexName: 'method_fts', properties: ['name', 'content'] },
-    { table: 'Interface', indexName: 'interface_fts', properties: ['name', 'content'] },
+const FTS_TABLES = [
+    { table: 'File', indexName: 'file_fts' },
+    { table: 'Function', indexName: 'function_fts' },
+    { table: 'Class', indexName: 'class_fts' },
+    { table: 'Method', indexName: 'method_fts' },
+    { table: 'Interface', indexName: 'interface_fts' },
 ];
+const ftsPropertiesFor = (compress) => !compress || compress === 'none' ? ['name', 'content'] : ['name'];
+/**
+ * Look up `meta.compress` for a repo. The MCP path passes `repoId`
+ * (registry-derived); the CLI path passes nothing and we walk up from
+ * cwd. Returns `'none'` whenever the lookup fails so the safe default
+ * (full FTS index) is used — the failure mode is reduced search
+ * quality, never wrong results.
+ */
+async function getCompressMode(repoId) {
+    try {
+        const repoMod = await import('../../storage/repo-manager.js');
+        if (repoId) {
+            // MCP path: registry name is the source of truth. The MCP
+            // backend's `repoId` is `entry.name.toLowerCase()` (or `${name}-${hash}`
+            // on collision); match conservatively against both forms.
+            const entries = await repoMod.listRegisteredRepos();
+            for (const entry of entries) {
+                const base = entry.name.toLowerCase();
+                if (base === repoId || repoId.startsWith(`${base}-`)) {
+                    const meta = await repoMod.loadMeta(entry.storagePath);
+                    return meta?.compress ?? 'none';
+                }
+            }
+            return 'none';
+        }
+        const repo = await repoMod.findRepo(process.cwd());
+        return repo?.meta?.compress ?? 'none';
+    }
+    catch {
+        return 'none';
+    }
+}
 const FALLBACK_SCAN_LIMIT = 50_000;
 const BOOLEAN_QUERY_TOKENS = new Set(['and', 'or', 'not']);
 const FALLBACK_FIELD_WEIGHTS = {
@@ -184,9 +223,13 @@ async function queryFallbackViaExecutor(executor, tableName, properties, query,
         return [];
     }
 }
-async function fallbackSearchAllTables(executor, query, limit) {
+async function fallbackSearchAllTables(executor, query, limit, 
+// Same compress-aware property selection as the FTS path. Default keeps
+// pre-Phase-2 behaviour (`['name', 'content']`) for callers that don't
+// pass a value.
+properties = ['name', 'content']) {
     const results = [];
-    for (const { table, properties } of FTS_INDEXES) {
+    for (const { table } of FTS_TABLES) {
         results.push(await queryFallbackViaExecutor(executor, table, properties, query, limit));
     }
     return results;
@@ -220,7 +263,12 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
         const executor = (cypher) => executeQuery(repoId, cypher);
         // Lazy-create FTS indexes on first query for this repo (analyze no longer
         // creates them up-front, so we ensure them here). Cached per-process.
-        for (const { table, indexName, properties } of FTS_INDEXES) {
+        // RFC 0001 Phase 2.5: drop `content` from FTS properties for repos
+        // analysed with --compress brotli|zstd — the column holds encoded
+        // bytes and would tokenise to garbage.
+        const compress = await getCompressMode(repoId);
+        const properties = ftsPropertiesFor(compress);
+        for (const { table, indexName } of FTS_TABLES) {
             await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
         }
         fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
@@ -235,13 +283,17 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
             interfaceResults.length ===
             0) {
             [fileResults, functionResults, classResults, methodResults, interfaceResults] =
-                await fallbackSearchAllTables(executor, query, limit);
+                await fallbackSearchAllTables(executor, query, limit, properties);
         }
     }
     else {
         // Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
         // Lazy-create FTS indexes on first query (analyze no longer does it).
-        for (const { table, indexName, properties } of FTS_INDEXES) {
+        // RFC 0001 Phase 2.5 — same `compress`-aware property selection as the MCP
+        // path; the CLI walks up from cwd to find the repo's meta.json.
+        const compress = await getCompressMode();
+        const properties = ftsPropertiesFor(compress);
+        for (const { table, indexName } of FTS_TABLES) {
             await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
         }
         fileResults = await queryFTS('File', 'file_fts', query, limit, false).catch(() => []);
@@ -256,7 +308,7 @@ export const searchFTSFromLbug = async (query, limit = 20, repoId) => {
             interfaceResults.length ===
             0) {
             [fileResults, functionResults, classResults, methodResults, interfaceResults] =
-                await fallbackSearchAllTables(executeCoreQuery, query, limit);
+                await fallbackSearchAllTables(executeCoreQuery, query, limit, properties);
         }
     }
     // Collect all node scores per filePath to track which nodes actually matched

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

@@ -19,6 +19,7 @@ import { GroupService } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { decodeContentField } from '../../core/lbug/content-read.js';
 import { PhaseTimer } from '../../core/search/phase-timer.js';
 import { checkStaleness, checkCwdMatch } from '../../core/git-staleness.js';
 // AI context generation is CLI-only (codragraph analyze)
@@ -835,10 +836,12 @@ export class LocalBackend {
                 try {
                     const contentRows = await executeParameterized(repo.id, `
             MATCH (n {id: $nodeId})
-            RETURN n.content AS content
+            RETURN n.content AS content, n.contentEncoding AS contentEncoding
           `, { nodeId: sym.nodeId });
                     if (contentRows.length > 0) {
-                        content = contentRows[0].content ?? contentRows[0][0];
+                        const raw = contentRows[0].content ?? contentRows[0][0];
+                        const enc = contentRows[0].contentEncoding ?? contentRows[0][1];
+                        content = decodeContentField(raw, enc);
                     }
                 }
                 catch (e) {
@@ -1330,7 +1333,13 @@ export class LocalBackend {
      */
     async resolveSymbolCandidates(repo, query, hints) {
         const { uid, name, include_content } = query;
-        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+        // RFC 0001 Phase 2: when fetching content, also fetch the per-row
+        // encoding tag so `decodeContentField` can pass it through unchanged
+        // (default 'none') or run brotli/zstd decode. Adding contentEncoding
+        // to the SELECT shifts the numeric-index fallback for content from
+        // r[6] to (still) r[6] — encoding lands at r[7] — but we read by name
+        // first which is the documented preferred path on LadybugDB.
+        const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content, n.contentEncoding AS contentEncoding' : ''}`;
         // Direct UID — zero-ambiguity path.
         if (uid) {
             const rows = await executeParameterized(repo.id, `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`, { uid });
@@ -1344,7 +1353,11 @@ export class LocalBackend {
                 filePath: (r.filePath ?? r[3]),
                 startLine: (r.startLine ?? r[4]),
                 endLine: (r.endLine ?? r[5]),
-                ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+                ...(include_content
+                    ? {
+                        content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                    }
+                    : {}),
             };
             // Same LadybugDB label-enrichment as the name-based path: a UID
             // pointing at a Class must still surface `type: 'Class'` so impact's
@@ -1380,7 +1393,11 @@ export class LocalBackend {
             filePath: (r.filePath ?? r[3]),
             startLine: (r.startLine ?? r[4]),
             endLine: (r.endLine ?? r[5]),
-            ...(include_content ? { content: (r.content ?? r[6]) } : {}),
+            ...(include_content
+                ? {
+                    content: decodeContentField(r.content ?? r[6], r.contentEncoding ?? r[7]),
+                }
+                : {}),
         }));
         // Enrich labels for any candidates where `labels(n)[0]` came back empty.
         // LadybugDB returns an empty string for that projection on certain node

package/dist/server/api.js

@@ -15,6 +15,7 @@ import { createRequire } from 'node:module';
 import { loadMeta, listRegisteredRepos, getStoragePath } from '../storage/repo-manager.js';
 import { executeQuery, executePrepared, executeWithReusedStatement, streamQuery, closeLbug, withLbugDb, } from '../core/lbug/lbug-adapter.js';
 import { isWriteQuery } from '../core/lbug/pool-adapter.js';
+import { decodeContentField } from '../core/lbug/content-read.js';
 import { NODE_TABLES } from '../_shared/index.js';
 import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
@@ -189,7 +190,7 @@ const getNodeQuery = (table, includeContent) => {
     const tableLabel = quoteNodeTable(table);
     if (table === 'File') {
         return includeContent
-            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content`
+            ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.content AS content, n.contentEncoding AS contentEncoding`
             : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath`;
     }
     if (table === 'Folder') {
@@ -208,7 +209,7 @@ const getNodeQuery = (table, includeContent) => {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
     }
     return includeContent
-        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content`
+        ? `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.content AS content, n.contentEncoding AS contentEncoding`
         : `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
 };
 const mapGraphNodeRow = (table, row, includeContent) => ({
@@ -219,7 +220,7 @@ const mapGraphNodeRow = (table, row, includeContent) => ({
         filePath: row.filePath ?? row[2],
         startLine: row.startLine,
         endLine: row.endLine,
-        content: includeContent ? row.content : undefined,
+        content: includeContent ? decodeContentField(row.content, row.contentEncoding) : undefined,
         responseKeys: row.responseKeys,
         errorKeys: row.errorKeys,
         middleware: row.middleware,

package/dist/storage/repo-manager.d.ts

@@ -36,10 +36,49 @@
  * so the registry stabilises over analyze/re-analyze cycles.
  */
 export declare const canonicalizePath: (p: string) => string;
+/**
+ * On-disk schema version for `.codragraph/lbug` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export declare const INDEX_SCHEMA_VERSION: 2;
 export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * On-disk schema version (see {@link INDEX_SCHEMA_VERSION}). Absent on
+     * indexes written by 1.7.x or earlier; `runFullAnalysis` treats those
+     * as needing a full re-analyze when they're loaded by a 1.8+ CLI.
+     */
+    schemaVersion?: number;
+    /**
+     * RFC 0001 Phase 2 — the per-row content encoding chosen at the last
+     * `analyze --compress` invocation. `'none'` (or absent) means rows
+     * carry plain text; `'brotli'` / `'zstd'` means rows are compressed
+     * and consumers must decode. Persisted so query-time tooling can
+     * detect the compressed mode without sampling rows.
+     *
+     * Phase 2.5 hooks: `core/search/bm25-index.ts` reads this field at
+     * FTS-create time and drops `content` from the FTS property list
+     * when set to a non-`'none'` value (full-text search falls back to
+     * symbol-name matches). Embeddings and graph queries are unaffected
+     * — they decode at the read boundary.
+     */
+    compress?: 'none' | 'brotli' | 'zstd';
     /**
      * Canonical `origin` remote URL captured at index time. Used to
      * fingerprint the same logical repo across multiple on-disk clones

package/dist/storage/repo-manager.js

@@ -49,6 +49,25 @@ export const canonicalizePath = (p) => {
         return resolved;
     }
 };
+/**
+ * On-disk schema version for `.codragraph/lbug` and `.codragraph/meta.json`.
+ *
+ *   1  — pre-RFC-0001-Phase-2 layout. Node tables have `content STRING`
+ *        but no `contentEncoding` column. Implicit/missing on existing
+ *        1.6.x and 1.7.x indexes (RepoMeta.schemaVersion was undefined).
+ *   2  — RFC 0001 Phase 2: every node table that has `content` also has
+ *        a `contentEncoding STRING DEFAULT 'none'` column. Writers may
+ *        opt into compression via `--compress brotli|zstd` (compression
+ *        is OFF by default, so existing readers keep working). Readers
+ *        decode based on the per-row encoding tag.
+ *
+ * Bumping this is the migration trigger: `runFullAnalysis` forces a
+ * full re-analyze when an existing index has a missing or older
+ * `schemaVersion` field, because adding a column to an existing
+ * LadybugDB table via ALTER is not validated end-to-end yet — fresh
+ * `CREATE NODE TABLE` is the supported path.
+ */
+export const INDEX_SCHEMA_VERSION = 2;
 const CODRAGRAPH_DIR = '.codragraph';
 // ─── Local Storage Helpers ─────────────────────────────────────────────
 /**

package/hooks/claude/codragraph-hook.cjs

@@ -12,8 +12,27 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawnSync, spawn } = require('child_process');
+
+/**
+ * Decide whether background auto-reindex is opted in. Two equivalent signals:
+ *   1. CODRAGRAPH_AUTO_REINDEX=1 in env (good for shells, CI)
+ *   2. `{ "autoReindex": true }` in ~/.codragraph/config.json (good for GUI
+ *      editor launches on Windows, where shell env doesn't propagate to
+ *      hook child processes reliably)
+ */
+function isAutoReindexEnabled() {
+  if (process.env.CODRAGRAPH_AUTO_REINDEX === '1') return true;
+  try {
+    const configPath = path.join(os.homedir(), '.codragraph', 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return config && config.autoReindex === true;
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Read JSON input from stdin synchronously.
@@ -250,10 +269,84 @@ function handlePostToolUse(input) {
   if (currentHead && currentHead === lastCommit) return;
 
   const analyzeCmd = `npx @codragraph/cli analyze${hadEmbeddings ? ' --embeddings' : ''}`;
+
+  // Opt-in background auto-reindex.
+  // Default stays as notification-only because spawning analyze while an MCP
+  // server holds LadybugDB will fail with a database-busy error — the
+  // notification path lets the agent reindex at a quiet moment instead.
+  // Power users who run MCP outside Claude Code's lifecycle can opt in via
+  // CODRAGRAPH_AUTO_REINDEX=1 or `{ "autoReindex": true }` in
+  // ~/.codragraph/config.json.
+  if (isAutoReindexEnabled()) {
+    // The "coalesce" file is a single-process gate: it exists only while a
+    // reindex is in flight. The spawned analyze removes it on exit (success or
+    // failure) via CODRAGRAPH_REINDEX_LOCK_PATH; the 10-min mtime fallback
+    // catches the rare crash that bypasses analyze's exit handler.
+    const coalescePath = path.join(gitNexusDir, '.reindex.coalesce');
+    const crashSafetyTtlMs = 10 * 60 * 1000;
+    let inFlight = false;
+    try {
+      const stat = fs.statSync(coalescePath);
+      if (Date.now() - stat.mtimeMs < crashSafetyTtlMs) inFlight = true;
+    } catch {
+      /* no coalesce file — no reindex in flight */
+    }
+
+    if (!inFlight) {
+      try {
+        fs.writeFileSync(coalescePath, String(process.pid));
+      } catch {
+        /* best-effort — gate is for coalescing, not correctness */
+      }
+
+      const cliPath = resolveCliPath();
+      const reindexArgs = hadEmbeddings
+        ? ['analyze', '--embeddings', '--no-setup']
+        : ['analyze', '--no-setup'];
+      const spawnEnv = { ...process.env, CODRAGRAPH_REINDEX_LOCK_PATH: coalescePath };
+      const spawnOpts = {
+        cwd,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env: spawnEnv,
+      };
+      try {
+        let child;
+        if (cliPath) {
+          child = spawn(process.execPath, [cliPath, ...reindexArgs], spawnOpts);
+        } else if (process.platform === 'win32') {
+          child = spawn('cmd', ['/c', 'npx', '-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        } else {
+          child = spawn('npx', ['-y', '@codragraph/cli', ...reindexArgs], spawnOpts);
+        }
+        child.unref();
+      } catch {
+        /* spawn failed — fall through to notification */
+      }
+
+      sendHookResponse(
+        'PostToolUse',
+        `CodraGraph: auto-reindex started in background ` +
+          `(HEAD ${lastCommit ? lastCommit.slice(0, 7) : 'never'} → ${currentHead.slice(0, 7)}). ` +
+          `If an MCP server is currently holding the database, the reindex will fail silently — ` +
+          `run \`${analyzeCmd}\` manually after closing the agent session.`,
+      );
+      return;
+    }
+
+    sendHookResponse(
+      'PostToolUse',
+      `CodraGraph: auto-reindex coalesced — another reindex is in flight (will pick up your latest commit when it finishes).`,
+    );
+    return;
+  }
+
   sendHookResponse(
     'PostToolUse',
     `CodraGraph index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-      `Run \`${analyzeCmd}\` to update the knowledge graph.`,
+      `Run \`${analyzeCmd}\` to update the knowledge graph. ` +
+      `Set CODRAGRAPH_AUTO_REINDEX=1 (or autoReindex: true in ~/.codragraph/config.json) for background auto-reindex.`,
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codragraph/cli",
-  "version": "1.6.4",
+  "version": "2.0.0",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": {
     "name": "Anit Chaudhary",
@@ -56,10 +56,10 @@
     "prepack": "node scripts/build.js"
   },
   "dependencies": {
+    "@codragraph/graphstore": "^1.0.0",
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@codragraph/graphstore": "^0.1.1",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
@@ -99,6 +99,7 @@
     "tree-sitter-swift": "^0.6.0"
   },
   "devDependencies": {
+    "@codragraph/shared": "file:../codragraph-shared",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
@@ -106,7 +107,6 @@
     "@types/node": "^25.6.0",
     "@types/uuid": "^11.0.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "@codragraph/shared": "file:../codragraph-shared",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.0.18"

package/scripts/build-tree-sitter-proto.cjs

@@ -34,14 +34,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const protoDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto');
+// Resolve tree-sitter-proto from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so the package-local path doesn't exist on a workspace
+// install. Same trap as patch-tree-sitter-swift.cjs — see that file for the
+// full failure mode.
+const protoCandidates = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-proto'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-proto'),
+];
+const protoDir = protoCandidates.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!protoDir) {
+  // tree-sitter-proto is an optionalDependency; absent when install
+  // skipped optional deps or the file: dep was not resolved.
+  process.exit(0);
+}
 const bindingGyp = path.join(protoDir, 'binding.gyp');
 const bindingNode = path.join(protoDir, 'build', 'Release', 'tree_sitter_proto_binding.node');
 
 try {
   if (!fs.existsSync(bindingGyp)) {
-    // tree-sitter-proto is an optionalDependency; absent when install
-    // skipped optional deps or the file: dep was not resolved.
     process.exit(0);
   }
 

package/scripts/patch-tree-sitter-swift.cjs

@@ -29,13 +29,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
+// Resolve tree-sitter-swift from BOTH the codragraph package itself AND any
+// monorepo root that hoisted the dep. npm workspaces hoist optional deps to
+// the workspace root, so `codragraph/node_modules/tree-sitter-swift` doesn't
+// exist when this script runs as the codragraph postinstall — checking only
+// that path silently no-ops, which is exactly the failure that left
+// Windows Node 22.14 users without a Swift parser.
+//
+// Order matters: the package-local dir takes precedence (standalone install),
+// then the parent monorepo root (workspace install).
+const candidateDirs = [
+  path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift'),
+  path.join(__dirname, '..', '..', 'node_modules', 'tree-sitter-swift'),
+];
+const swiftDir = candidateDirs.find((d) => fs.existsSync(path.join(d, 'binding.gyp')));
+if (!swiftDir) {
+  process.exit(0);
+}
 const bindingPath = path.join(swiftDir, 'binding.gyp');
 
 try {
-  if (!fs.existsSync(bindingPath)) {
-    process.exit(0);
-  }
 
   const content = fs.readFileSync(bindingPath, 'utf8');
   let needsRebuild = false;