@codragraph/cli 2.1.4 → 2.1.5

package/README.md

@@ -25,6 +25,13 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 The same CLI commands work in Windows PowerShell, macOS bash/zsh, and Linux shells. Use `npx @codragraph/cli ...` for no-install runs or `codragraph ...` after a global install.
 
+Smart analyze rebuilds when indexed source, Markdown/MDX graph docs, language
+config, schema, compression, or requested embedding settings changed. Generated
+agent context, lockfile-only, and ignored asset changes reuse the existing
+graph and advance metadata. Each pass refreshes `.codragraph/structure/`, a
+compact what/why/how/when/where markdown pack with branch/index state, bounded
+history, and SQLite seed SQL for external agent memory.
+
 To configure MCP for your editor, run `npx @codragraph/cli setup` once — or set it up manually below.
 
 `codragraph setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
@@ -55,16 +62,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.2 mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@2.1.5 mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.2 mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.5 mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y @codragraph/cli@2.1.2 mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@2.1.5 mcp
 ```
 
 ### Cursor / Windsurf
@@ -76,7 +83,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.5", "mcp"]
     }
   }
 }
@@ -91,7 +98,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.2", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.5", "mcp"]
     }
   }
 }
@@ -297,9 +304,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.2 analyze          # no global install
+npx @codragraph/cli@2.1.5 analyze          # no global install
 # or
-npm install -g @codragraph/cli@2.1.2       # upgrade a global install
+npm install -g @codragraph/cli@2.1.5       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds
@@ -342,6 +349,23 @@ echo "vendor/" >> .codragraphignore
 echo "dist/" >> .codragraphignore
 ```
 
+If the analyzer reports a worker sub-batch timeout or falls back to sequential
+parsing while files are still being processed, reduce worker batch memory and
+allow a longer idle window:
+
+```bash
+# macOS/Linux bash/zsh
+CODRAGRAPH_WORKER_SUB_BATCH_SIZE=100 CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS=180000 npx @codragraph/cli analyze
+
+# Windows PowerShell
+$env:CODRAGRAPH_WORKER_SUB_BATCH_SIZE = "100"
+$env:CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS = "180000"
+npx @codragraph/cli analyze
+```
+
+The worker timer is an idle guard. Parser progress resets it, so a slow repo
+should keep moving instead of paying the old 30-second wall-clock fallback.
+
 If you want to know **which phase** is dragging the heap up before
 deciding what to mitigate, run `codragraph profile-heap`. It writes a
 v8 heap snapshot at every phase boundary plus a JSONL timeline of

package/dist/cli/ai-context.js

@@ -8,11 +8,14 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { execFileSync } from 'node:child_process';
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const CODRAGRAPH_START_MARKER = '<!-- codragraph:start -->';
 const CODRAGRAPH_END_MARKER = '<!-- codragraph:end -->';
+const AGENT_STRUCTURE_DIR = 'structure';
+const AGENT_HISTORY_LIMIT = 20;
 /**
  * Find the index of a section marker that occupies its own line.
  * Unlike `indexOf`, this rejects inline prose references like
@@ -113,6 +116,7 @@ This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` ($
 | \`codragraph://repo/${projectName}/feature/{name}\` | Focused files, line ranges, flows, dependencies |
 | \`codragraph://repo/${projectName}/processes\` | All execution flows |
 | \`codragraph://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+| \`.codragraph/structure/README.md\` | Local what/why/how/when/where memory, branch state, and SQLite seed |
 
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
@@ -174,6 +178,292 @@ async function upsertCodraGraphSection(filePath, content) {
     await fs.writeFile(filePath, newContent, 'utf-8');
     return 'appended';
 }
+async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function gitValue(repoPath, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function statValue(value) {
+    return value === undefined || value === null || value === '' ? 'unknown' : String(value);
+}
+function shortCommit(value) {
+    return value ? value.slice(0, 12) : 'unknown';
+}
+function sqlString(value) {
+    return String(value ?? '').replace(/'/g, "''");
+}
+async function buildAgentStructureState(repoPath, storagePath, projectName, stats) {
+    const meta = await readJsonFile(path.join(storagePath, 'meta.json'));
+    const currentGitHead = gitValue(repoPath, ['rev-parse', 'HEAD']);
+    const currentBranch = gitValue(repoPath, ['branch', '--show-current']) ||
+        gitValue(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    return {
+        projectName,
+        repoPath,
+        storagePath,
+        generatedAt: new Date().toISOString(),
+        indexedAt: meta?.indexedAt,
+        currentBranch: currentBranch || undefined,
+        currentGitHead: currentGitHead || undefined,
+        indexedCommit: meta?.lastCommit || currentGitHead || undefined,
+        remoteUrl: meta?.remoteUrl,
+        schemaVersion: meta?.schemaVersion,
+        compress: meta?.compress,
+        graphstoreBranch: meta?.currentBranch,
+        graphstoreHeadCommit: meta?.headCommit,
+        stats: {
+            files: stats.files ?? meta?.stats?.files,
+            nodes: stats.nodes ?? meta?.stats?.nodes,
+            edges: stats.edges ?? meta?.stats?.edges,
+            communities: stats.communities ?? meta?.stats?.communities,
+            clusters: stats.clusters ?? meta?.stats?.featureClusters,
+            processes: stats.processes ?? meta?.stats?.processes,
+            embeddings: meta?.stats?.embeddings,
+        },
+    };
+}
+function buildStructureDocs(state) {
+    const statsTable = `| Metric | Value |
+|---|---|
+| Files | ${statValue(state.stats.files)} |
+| Symbols | ${statValue(state.stats.nodes)} |
+| Relationships | ${statValue(state.stats.edges)} |
+| Feature clusters | ${statValue(state.stats.clusters)} |
+| Execution flows | ${statValue(state.stats.processes)} |
+| Embeddings | ${statValue(state.stats.embeddings)} |
+| Compression | ${statValue(state.compress)} |
+| Schema version | ${statValue(state.schemaVersion)} |`;
+    const branchTable = `| Field | Value |
+|---|---|
+| Current git branch | ${statValue(state.currentBranch)} |
+| Current git HEAD | ${statValue(state.currentGitHead)} |
+| Indexed commit | ${statValue(state.indexedCommit)} |
+| Indexed at | ${statValue(state.indexedAt)} |
+| Graphstore branch | ${statValue(state.graphstoreBranch)} |
+| Graphstore head commit | ${statValue(state.graphstoreHeadCommit)} |
+| Remote | ${statValue(state.remoteUrl)} |`;
+    return {
+        'README.md': `# CodraGraph Agent Structure
+
+Generated: ${state.generatedAt}
+
+This folder is the small, pre-seeded context pack for AI agents. It is rebuilt
+by \`codragraph analyze\` so agents can read stable markdown instead of guessing
+from stale terminal output.
+
+Read order:
+
+1. [WHAT.md](WHAT.md) - what this index represents.
+2. [WHY.md](WHY.md) - why the agent should use graph context first.
+3. [HOW.md](HOW.md) - how to query, analyze, and recover safely.
+4. [WHEN.md](WHEN.md) - when to refresh, reuse, or clean the index.
+5. [WHERE.md](WHERE.md) - where local storage, MCP, HTTP, and docs live.
+6. [BRANCHES.md](BRANCHES.md) - branch, commit, and graphstore state.
+7. [SQLITE.md](SQLITE.md) - SQLite-compatible seed data for external agent memory.
+`,
+        'WHAT.md': `# What
+
+CodraGraph index name: **${state.projectName}**
+
+This index stores a local code graph for the repository at:
+
+\`${state.repoPath}\`
+
+The graph includes file structure, symbols, relationships, imports, execution
+flows, feature clusters, Markdown graph docs, and optional embeddings. Agents
+should use this pack as the first local orientation layer, then ask MCP/CLI for
+live graph details.
+
+${statsTable}
+`,
+        'WHY.md': `# Why
+
+AI agents should not rebuild project understanding from raw grep every time.
+This folder gives them a compact, reusable map of the current indexed state.
+
+Use it to avoid:
+
+- Querying the wrong registered repo.
+- Running multiple analyzers against the same .codragraph store.
+- Treating stale branch or commit context as fresh.
+- Enabling embeddings by default when BM25 and graph search are enough.
+- Deleting index files when a targeted analyze or clean command is safer.
+`,
+        'HOW.md': `# How
+
+Safe command flow for agents:
+
+1. Read this folder and \`AGENTS.md\` / \`CLAUDE.md\`.
+2. Run \`codragraph status\` or \`npx @codragraph/cli status\`.
+3. Use MCP \`query\`, \`context\`, \`impact\`, and \`detect_changes\` for graph work.
+4. Run \`codragraph analyze\` only when the index is missing or stale.
+5. Use \`--repo ${state.projectName}\` when running from outside this checkout.
+
+Do not run \`analyze\`, \`detect-changes\`, \`clean\`, or DB-writing commands from
+editor hooks. Hooks should stay bounded and read-only.
+`,
+        'WHEN.md': `# When
+
+Refresh with \`codragraph analyze\` when:
+
+- The repo was never indexed.
+- MCP or CLI reports stale graph context.
+- Source files, Markdown graph docs, language config, or path topology changed.
+- Schema, compression, or embedding settings changed.
+
+Reuse the existing graph when only generated agent context, lockfiles, or
+ignored assets changed. Use \`codragraph analyze --force\` when ignore rules
+changed or corruption is suspected. Ask before \`codragraph clean --force\`.
+`,
+        'WHERE.md': `# Where
+
+| Item | Location |
+|---|---|
+| Repository | \`${state.repoPath}\` |
+| Local index storage | \`${state.storagePath}\` |
+| Agent structure pack | \`${path.join(state.storagePath, AGENT_STRUCTURE_DIR)}\` |
+| Root agent instructions | \`AGENTS.md\`, \`CLAUDE.md\` |
+| Claude skills | \`.claude/skills/@codragraph/cli/\` |
+| HTTP API | \`http://127.0.0.1:4747/api/info\` after \`codragraph serve\` |
+| MCP tools | \`codragraph mcp\` |
+`,
+        'BRANCHES.md': `# Branches And Commits
+
+${branchTable}
+
+The indexed commit is the source-of-truth for whether graph answers are fresh.
+If \`Current git HEAD\` and \`Indexed commit\` differ, agents should say the graph
+is stale and run \`codragraph analyze\` before relying on impact, context, or
+detect-changes output.
+`,
+        'INDEX.md': `# Index Snapshot
+
+${statsTable}
+
+Storage notes:
+
+- BM25 and graph traversal work without embeddings.
+- Embeddings are optional and should be preserved with \`--embeddings\` only
+  when semantic/vector search is intentionally required.
+- Compression mode is recorded in \`.codragraph/meta.json\`.
+- This markdown pack is small and should not be embedded or vectorized.
+`,
+        'SQLITE.md': `# SQLite Seed
+
+\`agent-memory.sql\` is a SQLite-compatible seed file for external agent memory
+stores. CodraGraph writes it as plain SQL so installs stay light on Node 20 and
+do not pull native SQLite dependencies into the CLI hot path.
+
+Optional import:
+
+\`\`\`sh
+sqlite3 agent-memory.sqlite < agent-memory.sql
+\`\`\`
+
+The canonical live source remains \`.codragraph/meta.json\` plus the graph DB.
+`,
+    };
+}
+function buildSqlSeed(state) {
+    const rows = [
+        ['project_name', state.projectName],
+        ['repo_path', state.repoPath],
+        ['storage_path', state.storagePath],
+        ['generated_at', state.generatedAt],
+        ['indexed_at', state.indexedAt],
+        ['current_branch', state.currentBranch],
+        ['current_git_head', state.currentGitHead],
+        ['indexed_commit', state.indexedCommit],
+        ['remote_url', state.remoteUrl],
+        ['schema_version', state.schemaVersion],
+        ['compress', state.compress],
+        ['graphstore_branch', state.graphstoreBranch],
+        ['graphstore_head_commit', state.graphstoreHeadCommit],
+        ['stats_json', JSON.stringify(state.stats)],
+    ];
+    const values = rows
+        .map(([key, value]) => `('${sqlString(key)}', '${sqlString(value)}', '${sqlString(state.generatedAt)}')`)
+        .join(',\n');
+    return `BEGIN;
+CREATE TABLE IF NOT EXISTS codragraph_agent_context (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+DELETE FROM codragraph_agent_context;
+INSERT INTO codragraph_agent_context (key, value, updated_at) VALUES
+${values};
+COMMIT;
+`;
+}
+async function buildHistoryContent(historyPath, state) {
+    const entryId = (state.indexedCommit || 'no-git').replace(/[^a-zA-Z0-9._-]/g, '_');
+    const entry = `<!-- codragraph:history-entry:${entryId} -->
+## ${shortCommit(state.indexedCommit)} - ${state.generatedAt}
+
+- Branch: ${statValue(state.currentBranch)}
+- Indexed commit: ${statValue(state.indexedCommit)}
+- Git HEAD: ${statValue(state.currentGitHead)}
+- Graphstore: ${statValue(state.graphstoreBranch)} / ${statValue(state.graphstoreHeadCommit)}
+- Stats: ${statValue(state.stats.nodes)} symbols, ${statValue(state.stats.edges)} relationships, ${statValue(state.stats.processes)} flows
+<!-- /codragraph:history-entry -->`;
+    let existing = '';
+    try {
+        existing = await fs.readFile(historyPath, 'utf-8');
+    }
+    catch {
+        /* first run */
+    }
+    const blocks = [];
+    const regex = /<!-- codragraph:history-entry:([^ ]+) -->[\s\S]*?<!-- \/codragraph:history-entry -->/g;
+    let match;
+    while ((match = regex.exec(existing)) !== null) {
+        if (match[1] !== entryId)
+            blocks.push(match[0]);
+    }
+    return `# Analyze History
+
+Most recent CodraGraph analyze or smart-reuse events. Bounded to the latest
+${AGENT_HISTORY_LIMIT} entries so this file remains small.
+
+${[entry, ...blocks].slice(0, AGENT_HISTORY_LIMIT).join('\n\n')}
+`;
+}
+async function generateAgentStructurePack(repoPath, storagePath, projectName, stats) {
+    const structureDir = path.join(storagePath, AGENT_STRUCTURE_DIR);
+    await fs.mkdir(structureDir, { recursive: true });
+    const state = await buildAgentStructureState(repoPath, storagePath, projectName, stats);
+    const docs = buildStructureDocs(state);
+    const written = [];
+    for (const [fileName, content] of Object.entries(docs)) {
+        await fs.writeFile(path.join(structureDir, fileName), content.trim() + '\n', 'utf-8');
+        written.push(fileName);
+    }
+    await fs.writeFile(path.join(structureDir, 'state.json'), JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    written.push('state.json');
+    await fs.writeFile(path.join(structureDir, 'agent-memory.sql'), buildSqlSeed(state), 'utf-8');
+    written.push('agent-memory.sql');
+    const historyPath = path.join(structureDir, 'HISTORY.md');
+    await fs.writeFile(historyPath, await buildHistoryContent(historyPath, state), 'utf-8');
+    written.push('HISTORY.md');
+    return written;
+}
 /**
  * Install CodraGraph skills to .claude/skills/codragraph/
  * Works natively with Claude Code, Cursor, and GitHub Copilot
@@ -265,6 +555,13 @@ export async function generateAIContextFiles(repoPath, _storagePath, projectName
         createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
         createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
     }
+    try {
+        const structureFiles = await generateAgentStructurePack(repoPath, _storagePath, projectName, stats);
+        createdFiles.push(`.codragraph/structure/ (${structureFiles.length} files)`);
+    }
+    catch (err) {
+        console.warn('Warning: Could not generate .codragraph/structure agent pack:', err);
+    }
     // Install skills to .claude/skills/codragraph/
     const installedSkills = await installSkills(repoPath);
     if (installedSkills.length > 0) {

package/dist/cli/index.js

@@ -8,6 +8,26 @@ import { registerGroupCommands } from './group.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
+const exitOneShot = (code) => {
+    const reallyExit = process
+        .reallyExit;
+    if (typeof reallyExit === 'function') {
+        reallyExit(code);
+    }
+    process.exit(code);
+};
+const createOneShotLazyAction = (loader, exportName) => {
+    const action = createLazyAction(loader, exportName);
+    return async (...args) => {
+        await action(...args);
+        const code = typeof process.exitCode === 'number'
+            ? process.exitCode
+            : process.exitCode
+                ? Number(process.exitCode) || 1
+                : 0;
+        exitOneShot(code);
+    };
+};
 program.name('codragraph').description('CodraGraph local CLI and MCP server').version(pkg.version);
 program
     .command('setup')
@@ -114,7 +134,7 @@ program
     .option('-g, --goal <text>', 'What you want to find')
     .option('-l, --limit <n>', 'Max processes to return (default: 5)')
     .option('--content', 'Include full symbol source code')
-    .action(createLazyAction(() => import('./tool.js'), 'queryCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'queryCommand'));
 program
     .command('context [name]')
     .description('360-degree view of a code symbol: callers, callees, processes')
@@ -122,7 +142,7 @@ program
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
     .option('-f, --file <path>', 'File path to disambiguate common names')
     .option('--content', 'Include full symbol source code')
-    .action(createLazyAction(() => import('./tool.js'), 'contextCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
     .command('impact <target>')
     .description('Blast radius analysis: what breaks if you change a symbol')
@@ -130,49 +150,49 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('--depth <n>', 'Max relationship depth (default: 3)')
     .option('--include-tests', 'Include test files in results')
-    .action(createLazyAction(() => import('./tool.js'), 'impactCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'impactCommand'));
 program
     .command('cypher <query>')
     .description('Execute raw Cypher query against the knowledge graph')
     .option('-r, --repo <name>', 'Target repository')
-    .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'cypherCommand'));
 program
     .command('feature-clusters')
     .description('List human-facing feature clusters for targeted context building')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max feature clusters to return (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'featureClustersCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'featureClustersCommand'));
 program
     .command('cluster-query [query]')
     .description('Alias for feature-clusters: list product/domain clusters')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max feature clusters to return (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'clusterQueryCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'clusterQueryCommand'));
 program
     .command('feature-context <name>')
     .description('Show members, line ranges, and dependencies for a feature cluster')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max members to return (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'featureContextCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'featureContextCommand'));
 program
     .command('cluster-context <name>')
     .description('Alias for feature-context: show a feature cluster context pack')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max members to return (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'clusterContextCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'clusterContextCommand'));
 program
     .command('context-pack <name>')
     .description('Generate the compact agent context pack for a feature cluster')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max members to return (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'contextPackCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'contextPackCommand'));
 program
     .command('cluster-impact <name>')
     .description('Feature-level blast radius analysis for a cluster')
     .option('-d, --direction <dir>', 'upstream, downstream, or both', 'upstream')
     .option('-r, --repo <name>', 'Target repository')
     .option('-l, --limit <n>', 'Max context-pack members to include (default: 100)')
-    .action(createLazyAction(() => import('./tool.js'), 'clusterImpactCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'clusterImpactCommand'));
 program
     .command('detect-changes')
     .alias('detect_changes')
@@ -180,7 +200,7 @@ program
     .option('-s, --scope <scope>', 'What to analyze: unstaged, staged, all, or compare', 'unstaged')
     .option('-b, --base-ref <ref>', 'Branch/commit for compare scope (e.g. main)')
     .option('-r, --repo <name>', 'Target repository')
-    .action(createLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+    .action(createOneShotLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 program
     .command('eval-server')