@codragraph/cli 1.6.3 → 2.0.0

package/README.md

@@ -18,12 +18,12 @@ AI coding tools don't understand your codebase structure. They edit a function w
 
 ```bash
 # Index your repo (run from repo root)
-npx codragraph analyze
+npx @codragraph/cli analyze
 ```
 
 That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-To configure MCP for your editor, run `npx codragraph setup` once — or set it up manually below.
+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.
 
@@ -53,16 +53,16 @@ If you prefer to configure manually instead of using `codragraph setup`:
 
 ```bash
 # macOS / Linux
-claude mcp add codragraph -- npx -y codragraph@latest mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@latest mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y codragraph@latest mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@latest mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y codragraph@latest mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@latest mcp
 ```
 
 ### Cursor / Windsurf
@@ -74,7 +74,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "codragraph@latest", "mcp"]
+      "args": ["-y", "@codragraph/cli@latest", "mcp"]
     }
   }
 }
@@ -89,7 +89,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "codragraph@latest", "mcp"]
+      "args": ["-y", "@codragraph/cli@latest", "mcp"]
     }
   }
 }
@@ -155,6 +155,9 @@ codragraph analyze --embeddings    # Enable embedding generation (slower, better
 codragraph analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md codragraph section edits
 codragraph analyze --verbose       # Log skipped files when parsers are unavailable
 codragraph analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
+codragraph analyze --compress brotli  # Per-row body compression. Also: zstd, none.
+codragraph profile-heap [path]     # Run analyze with v8 heap-snapshot instrumentation
+codragraph profile-heap --no-summary  # Same, but skip the post-run RSS / heapUsed table
 codragraph mcp                     # Start MCP server (stdio) — serves all indexed repos
 codragraph serve                   # Start local HTTP server (multi-repo) for web UI
 codragraph index                   # Register an existing .codragraph/ folder into the global registry
@@ -244,9 +247,9 @@ merges are skipped.)
 
 ```bash
 # Try the latest release candidate (pre-stable — may change at any time)
-npm install -g codragraph@rc
+npm install -g @codragraph/cli@rc
 # — or —
-npx codragraph@rc analyze
+npx @codragraph/cli@rc analyze
 ```
 
 Release-candidate versions follow the standard semver prerelease format
@@ -265,9 +268,9 @@ certain npm/arborist versions ([npm/cli#8126](https://github.com/npm/cli/issues/
 It is fixed in **codragraph v1.6.2+**. Upgrade to the latest version:
 
 ```bash
-npx codragraph@latest analyze          # always uses the newest release
+npx @codragraph/cli@latest analyze          # always uses the newest release
 # — or —
-npm install -g codragraph@latest       # upgrade a global install
+npm install -g @codragraph/cli@latest       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds
@@ -282,7 +285,7 @@ npm cache clean --force              # clear a possibly corrupt cache
 
 Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, CodraGraph still works — those languages will be skipped.
 
-If `npm install -g codragraph` fails on native modules:
+If `npm install -g @codragraph/cli` fails on native modules:
 
 ```bash
 # Ensure build tools are available (Linux/macOS)
@@ -290,7 +293,7 @@ If `npm install -g codragraph` fails on native modules:
 # macOS: xcode-select --install
 
 # Retry installation
-npm install -g codragraph
+npm install -g @codragraph/cli
 ```
 
 ### Analysis runs out of memory
@@ -299,24 +302,55 @@ For very large repositories:
 
 ```bash
 # Increase Node.js heap size
-NODE_OPTIONS="--max-old-space-size=16384" npx codragraph analyze
+NODE_OPTIONS="--max-old-space-size=16384" npx @codragraph/cli analyze
 
 # Exclude large directories
 echo "vendor/" >> .codragraphignore
 echo "dist/" >> .codragraphignore
 ```
 
+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
+`process.memoryUsage()` and prints a per-phase RSS / `heapUsed` table:
+
+```bash
+codragraph profile-heap                       # writes .codragraph/heap-profiles/
+# → load any .heapsnapshot in Chrome DevTools → Memory → Load
+```
+
+Each snapshot is 100–500 MB, so the command is opt-in only. The JSONL
+timeline is small enough to share for triage even when the snapshots
+are too big.
+
+### Index size — opt-in per-row compression
+
+For repos where `.codragraph/lbug` itself has grown large:
+
+```bash
+codragraph analyze --compress brotli   # Node ≥ 18, brotli quality 6
+codragraph analyze --compress zstd     # Node ≥ 22.15, zstd level 3
+codragraph analyze --compress none     # explicit default
+```
+
+`--compress` routes every node-row content field through the matching
+encoder before it's written to the CSV / lbug; readers decode
+transparently via the per-row `contentEncoding` tag. With the flag
+unset, the on-disk layout is byte-identical to pre-1.8 indexes. Pre-1.8
+indexes auto-trigger a full re-analyze the first time a 1.8+ CLI runs
+against them (one-time cost, surfaced in the analyze log).
+
 ### Large files are being skipped
 
 By default the walker skips files larger than **512 KB** (see log line `Skipped N large files (>512KB)`). Raise the threshold via either the CLI flag or the environment variable — both accept a value in **KB**:
 
 ```bash
 # CLI flag (takes precedence over the env var)
-npx codragraph analyze --max-file-size 2048     # skip only files > 2 MB
+npx @codragraph/cli analyze --max-file-size 2048     # skip only files > 2 MB
 
 # Environment variable (persists across commands)
 export CODRAGRAPH_MAX_FILE_SIZE=2048
-npx codragraph analyze
+npx @codragraph/cli analyze
 ```
 
 Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `CODRAGRAPH_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).

package/dist/cli/ai-context.js

@@ -86,7 +86,7 @@ function generateCodraGraphContent(projectName, stats, generatedSkills, groupNam
 
 This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows)`}. Use the CodraGraph MCP tools to understand code, assess impact, and navigate safely.
 
-> If any CodraGraph tool warns the index is stale, run \`npx codragraph analyze\` in terminal first.
+> If any CodraGraph tool warns the index is stale, run \`npx @codragraph/cli analyze\` in terminal first.
 
 ## Always Do
 
@@ -115,7 +115,7 @@ This project is indexed by CodraGraph as **${projectName}**${noStats ? '' : ` ($
 ${groupNames && groupNames.length > 0
         ? `## Cross-Repo Groups
 
-This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}** (see \`~/.codragraph/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx codragraph group list\`, \`npx codragraph group sync <name>\`, \`npx codragraph group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under CodraGraph **group(s): ${groupNames.join(', ')}** (see \`~/.codragraph/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx @codragraph/cli group list\`, \`npx @codragraph/cli group sync <name>\`, \`npx @codragraph/cli group impact <name> --target <symbol> --repo <group-path>\`.
 
 `
         : ''}## CLI

package/dist/cli/analyze.d.ts

@@ -39,5 +39,27 @@ export interface AnalyzeOptions {
      * `CODRAGRAPH_MAX_FILE_SIZE` for the rest of the pipeline.
      */
     maxFileSize?: string;
+    /**
+     * First-run auto-setup gate. Default `true` (commander injects this from the
+     * `--no-setup` flag — see CLI registration). When `true`, `analyze` detects a
+     * missing `~/.codragraph/registry.json` and runs editor setup before indexing,
+     * making `npx @codragraph/cli analyze` a true zero-install entry. Pass
+     * `--no-setup` to opt out (CI, headless servers, automated pipelines).
+     */
+    setup?: boolean;
+    /**
+     * Comma-separated list of editor targets for `--skills` output. Valid values
+     * are `claude`, `cursor`, `opencode`, `codex`. Default: `claude` (matches
+     * pre-flag behavior). Unknown values are reported and ignored.
+     */
+    skillTargets?: string;
+    /**
+     * RFC 0001 Phase 2 — opt-in per-row content compression. Accepts
+     * `'none'` (default), `'brotli'` (Node ≥ 18), or `'zstd'` (Node ≥
+     * 22.15). Compressed indexes are still queryable via the standard
+     * read path; decode happens at every external-consumer boundary
+     * (MCP, HTTP API, embeddings, CLI tools).
+     */
+    compress?: 'none' | 'brotli' | 'zstd';
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -11,6 +11,7 @@ import path from 'path';
 import { execFileSync } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
+import * as fsSync from 'node:fs';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
@@ -52,9 +53,77 @@ export const analyzeCommand = async (inputPath, options) => {
     if (options?.verbose) {
         process.env.CODRAGRAPH_VERBOSE = '1';
     }
+    // RFC 0001 Phase 2 — validate --compress before doing any work. Catching
+    // a typo or an unsupported encoding here is much friendlier than failing
+    // mid-analyze with an opaque CSV-write error. Node-version gating for
+    // zstd lives in @codragraph/graphstore via isEncodingSupported, but we
+    // import the check here so the CLI can offer the brotli fallback hint.
+    if (options?.compress && options.compress !== 'none') {
+        if (options.compress !== 'brotli' && options.compress !== 'zstd') {
+            console.error(`  --compress must be one of: none, brotli, zstd (got: ${options.compress})`);
+            process.exitCode = 2;
+            return;
+        }
+        if (options.compress === 'zstd') {
+            const { isEncodingSupported } = await import('@codragraph/graphstore');
+            if (!isEncodingSupported('zstd')) {
+                console.error('  --compress zstd requires Node ≥ 22.15.0 (native node:zlib zstd).\n' +
+                    `  Detected Node ${process.version}. Use --compress brotli instead, or upgrade Node.`);
+                process.exitCode = 2;
+                return;
+            }
+        }
+        // RFC 0001 Phase 2.5 — BM25 / FTS now drops `content` from its
+        // property list when meta.compress is non-'none' (see
+        // `core/search/bm25-index.ts`), so search inside compressed bodies
+        // gracefully falls back to name-only matches instead of tokenising
+        // base64 garbage. Surface the trade-off so users know what they're
+        // opting into.
+        console.warn(`  Note: --compress ${options.compress} reduces .codragraph/lbug size.\n` +
+            `  BM25 search will index symbol names only (function bodies are not tokenised\n` +
+            `  when compressed); embeddings, graph queries, and \`context\` / \`impact\` are\n` +
+            `  unaffected. Run with --compress none if you rely on full-text search inside\n` +
+            `  source bodies.`);
+    }
     if (options?.maxFileSize) {
         process.env.CODRAGRAPH_MAX_FILE_SIZE = options.maxFileSize;
     }
+    // ── Auto-reindex coalesce-file cleanup ─────────────────────────────
+    // When the Claude Code PostToolUse hook spawns us in background mode, it
+    // passes the coalesce file path through this env var. We delete it on every
+    // exit path so the next commit immediately triggers a new reindex (rather
+    // than being blocked by a 10-min mtime TTL). The hook's TTL is just a
+    // crash safety net — this is the happy path.
+    const reindexLockPath = process.env.CODRAGRAPH_REINDEX_LOCK_PATH || '';
+    if (reindexLockPath) {
+        process.on('exit', () => {
+            try {
+                fsSync.unlinkSync(reindexLockPath);
+            }
+            catch {
+                /* already gone or unreadable — fine */
+            }
+        });
+    }
+    // ── First-run auto-setup ───────────────────────────────────────────
+    // Makes `npx @codragraph/cli analyze` a true one-command entry. We detect
+    // first-run by the absence of the global registry — analyze writes to it on
+    // every successful index, so it's a reliable "this user has never run us
+    // before" signal. Opt out with `--no-setup` for CI / headless contexts;
+    // commander maps `--no-setup` to `options.setup === false`.
+    if (options?.setup !== false) {
+        let registryExists = true;
+        try {
+            await fs.access(getGlobalRegistryPath());
+        }
+        catch {
+            registryExists = false;
+        }
+        if (!registryExists) {
+            const { runSetup } = await import('./setup.js');
+            await runSetup({ skipNextSteps: true, compactHeader: true });
+        }
+    }
     console.log('\n  CodraGraph Analyzer\n');
     let repoPath;
     if (inputPath) {
@@ -168,6 +237,9 @@ export const analyzeCommand = async (inputPath, options) => {
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options?.allowDuplicateName,
+            // RFC 0001 Phase 2 — pass through the per-row encoding choice.
+            // Default 'none' / undefined keeps the pre-Phase-2 wire layout.
+            compress: options?.compress,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -190,9 +262,23 @@ export const analyzeCommand = async (inputPath, options) => {
         if (options?.skills && result.pipelineResult) {
             updateBar(99, 'Generating skill files...');
             try {
-                const { generateSkillFiles } = await import('./skill-gen.js');
+                const { generateSkillFiles, SKILL_TARGETS } = await import('./skill-gen.js');
                 const { generateAIContextFiles } = await import('./ai-context.js');
-                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult);
+                // Parse --skill-targets CSV; default to ['claude'] when omitted.
+                // Unknown tokens are reported once and dropped — we don't fail the
+                // whole analyze for a typo here, but we do want the user to see it.
+                const requestedTargets = (options?.skillTargets || 'claude')
+                    .split(',')
+                    .map((s) => s.trim().toLowerCase())
+                    .filter(Boolean);
+                const validTargets = requestedTargets.filter((t) => SKILL_TARGETS.includes(t));
+                const invalidTargets = requestedTargets.filter((t) => !SKILL_TARGETS.includes(t));
+                if (invalidTargets.length > 0) {
+                    barLog(`  Skills: unknown target(s) ignored: ${invalidTargets.join(', ')} ` +
+                        `(valid: ${SKILL_TARGETS.join(', ')})`);
+                }
+                const targetsToUse = validTargets.length > 0 ? validTargets : ['claude'];
+                const skillResult = await generateSkillFiles(repoPath, result.repoName, result.pipelineResult, targetsToUse);
                 if (skillResult.skills.length > 0) {
                     barLog(`  Generated ${skillResult.skills.length} skill files`);
                     // Re-generate AI context files now that we have skill info
@@ -235,11 +321,28 @@ 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}`);
+        // 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.
         try {
-            await fs.access(getGlobalRegistryPath());
+            const { estimateTokens } = await import('./compress-stats.js');
+            const candidates = ['AGENTS.md', 'CLAUDE.md'];
+            const sizes = [];
+            for (const file of candidates) {
+                try {
+                    const content = await fs.readFile(path.join(repoPath, file), 'utf-8');
+                    sizes.push(`${file} ~${estimateTokens(content).toLocaleString()} tokens`);
+                }
+                catch {
+                    /* file not generated for this run — skip */
+                }
+            }
+            if (sizes.length > 0) {
+                console.log(`  @codragraph/compress: ${sizes.join(' | ')}`);
+            }
         }
         catch {
-            console.log('\n  Tip: Run `codragraph setup` to configure MCP for your editor.');
+            /* compress-stats import failed — non-fatal */
         }
         console.log('');
     }
@@ -289,8 +392,8 @@ export const analyzeCommand = async (inputPath, options) => {
             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 codragraph@latest');
-            console.error('    4. Or try npx directly:    npx codragraph@latest analyze');
+            console.error('    3. Reinstall codragraph:     npm install -g @codragraph/cli@latest');
+            console.error('    4. Or try npx directly:    npx @codragraph/cli@latest analyze');
             console.error('');
         }
         else if (msg.includes('MODULE_NOT_FOUND') ||
@@ -298,8 +401,8 @@ export const analyzeCommand = async (inputPath, options) => {
             msg.includes('ERR_MODULE_NOT_FOUND')) {
             console.error('  A required module could not be loaded. The installation may be corrupt.');
             console.error('  Suggestions:');
-            console.error('    1. Reinstall:   npm install -g codragraph@latest');
-            console.error('    2. Clear cache: npm cache clean --force && npx codragraph@latest analyze');
+            console.error('    1. Reinstall:   npm install -g @codragraph/cli@latest');
+            console.error('    2. Clear cache: npm cache clean --force && npx @codragraph/cli@latest analyze');
             console.error('');
         }
         process.exitCode = 1;

package/dist/cli/compress-stats.d.ts

@@ -0,0 +1,29 @@
+/** chars/4 token estimate. Matches @codragraph/compress's `estimateTokens`. */
+export declare function estimateTokens(text: string): number;
+/**
+ * Walk a result object and collect every file path we can find. Looks for
+ * `filePath`, `file_path`, and `file` keys at any depth. Used to estimate
+ * the raw-grep baseline (sum of source bytes the agent would have read
+ * without CodraGraph).
+ */
+export declare function collectFilePaths(obj: unknown, paths?: Set<string>): Set<string>;
+/**
+ * Estimate raw-grep-equivalent token count by summing on-disk byte sizes of
+ * the referenced files. Returns null if any file is missing or unreadable —
+ * in that case we silently skip the comparison rather than show a misleading
+ * number.
+ */
+export declare function estimateRawGrepTokens(filePaths: Iterable<string>): number | null;
+/**
+ * Format a one-line token-savings summary suitable for stderr display.
+ * If a raw baseline is provided AND it's larger than the structured response,
+ * the line includes the savings percentage. Otherwise it only reports
+ * the structured token count.
+ */
+export declare function formatTokenLine(structuredTokens: number, rawTokens?: number | null): string;
+/**
+ * Compute and print the token-savings line for a tool result. Best-effort:
+ * never throws, never blocks output. Goes to stderr so JSON consumers piping
+ * stdout to jq stay clean.
+ */
+export declare function emitTokenStats(result: unknown): void;

package/dist/cli/compress-stats.js

@@ -0,0 +1,97 @@
+/**
+ * Token-savings reporter for CLI output.
+ *
+ * Surfaces the @codragraph/compress value proposition on every `query`,
+ * `context`, `impact`, and `analyze` invocation: how many tokens of
+ * structured context did we return vs the equivalent raw-grep response.
+ *
+ * Uses the same chars/4 heuristic as @codragraph/compress's `estimateTokens`
+ * for cross-package consistency. Inlined rather than imported because pulling
+ * in @codragraph/compress as a runtime dep also pulls @codragraph/harness as a
+ * transitive — too heavy for what is logically a one-line approximation. When
+ * we add real LLM compression (`--compress` opt-in), the package import will
+ * follow.
+ */
+import * as fsSync from 'node:fs';
+/** chars/4 token estimate. Matches @codragraph/compress's `estimateTokens`. */
+export function estimateTokens(text) {
+    return Math.max(0, Math.floor(text.trim().length / 4));
+}
+/**
+ * Walk a result object and collect every file path we can find. Looks for
+ * `filePath`, `file_path`, and `file` keys at any depth. Used to estimate
+ * the raw-grep baseline (sum of source bytes the agent would have read
+ * without CodraGraph).
+ */
+export function collectFilePaths(obj, paths = new Set()) {
+    if (!obj || typeof obj !== 'object')
+        return paths;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            collectFilePaths(item, paths);
+        return paths;
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        if ((key === 'filePath' || key === 'file_path' || key === 'file') &&
+            typeof value === 'string' &&
+            value.length > 0) {
+            paths.add(value);
+        }
+        else if (typeof value === 'object') {
+            collectFilePaths(value, paths);
+        }
+    }
+    return paths;
+}
+/**
+ * Estimate raw-grep-equivalent token count by summing on-disk byte sizes of
+ * the referenced files. Returns null if any file is missing or unreadable —
+ * in that case we silently skip the comparison rather than show a misleading
+ * number.
+ */
+export function estimateRawGrepTokens(filePaths) {
+    let totalChars = 0;
+    for (const fp of filePaths) {
+        try {
+            const stat = fsSync.statSync(fp);
+            if (!stat.isFile())
+                return null;
+            totalChars += stat.size;
+        }
+        catch {
+            return null;
+        }
+    }
+    return Math.floor(totalChars / 4);
+}
+/**
+ * Format a one-line token-savings summary suitable for stderr display.
+ * If a raw baseline is provided AND it's larger than the structured response,
+ * the line includes the savings percentage. Otherwise it only reports
+ * the structured token count.
+ */
+export function formatTokenLine(structuredTokens, rawTokens) {
+    if (rawTokens && rawTokens > structuredTokens) {
+        const savings = Math.round((1 - structuredTokens / rawTokens) * 100);
+        return (`  @codragraph/compress: ~${structuredTokens.toLocaleString()} tokens of structured context ` +
+            `(vs ~${rawTokens.toLocaleString()} tokens of raw source — ${savings}% smaller).`);
+    }
+    return `  @codragraph/compress: ~${structuredTokens.toLocaleString()} tokens of structured context.`;
+}
+/**
+ * Compute and print the token-savings line for a tool result. Best-effort:
+ * never throws, never blocks output. Goes to stderr so JSON consumers piping
+ * stdout to jq stay clean.
+ */
+export function emitTokenStats(result) {
+    try {
+        const structured = typeof result === 'string' ? result : JSON.stringify(result);
+        const sTokens = estimateTokens(structured);
+        const files = collectFilePaths(result);
+        const rawTokens = files.size > 0 ? estimateRawGrepTokens(files) : null;
+        process.stderr.write('\n' + formatTokenLine(sTokens, rawTokens) + '\n');
+    }
+    catch {
+        /* never let stats break the actual output */
+    }
+}

package/dist/cli/graphstore.d.ts

@@ -12,7 +12,9 @@ export declare const logCommand: (opts?: {
     limit?: string;
 }) => Promise<void>;
 export declare const branchListCommand: () => Promise<void>;
-export declare const diffCommand: (from: string, to: string) => Promise<void>;
+export declare const diffCommand: (from: string, to: string, opts?: {
+    json?: boolean;
+}) => Promise<void>;
 export declare const commitCommand: (opts?: {
     message?: string;
 }) => Promise<void>;
@@ -36,5 +38,7 @@ export declare const mergeCommand: (target: string, opts?: {
 export declare const gcCommand: (opts?: {
     dryRun?: boolean;
 }) => Promise<void>;
-export declare const diffSemanticCommand: (from: string, to: string) => Promise<void>;
+export declare const diffSemanticCommand: (from: string, to: string, opts?: {
+    json?: boolean;
+}) => Promise<void>;
 export { DEFAULT_BRANCH };

package/dist/cli/graphstore.js

@@ -84,7 +84,7 @@ export const branchListCommand = async () => {
 // ──────────────────────────────────────────────────────────────────────
 // codragraph diff <from> <to>
 // ──────────────────────────────────────────────────────────────────────
-export const diffCommand = async (from, to) => {
+export const diffCommand = async (from, to, opts = {}) => {
     const ctx = await resolveGraphstore(process.cwd());
     const fromCommitId = await resolveCommitTarget(ctx, from);
     const toCommitId = await resolveCommitTarget(ctx, to);
@@ -95,6 +95,17 @@ export const diffCommand = async (from, to) => {
         from: fromCommit.snapshot,
         to: toCommit.snapshot,
     });
+    // --json: emit a machine-readable payload for downstream consumers
+    // (GitHub Action comment formatter, IDE plugins, etc). Keep human and
+    // JSON paths separate — never sneak JSON into the human path's stdout.
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            from: { commit: fromCommitId, message: fromCommit.message },
+            to: { commit: toCommitId, message: toCommit.message },
+            diff,
+        }, null, 2) + '\n');
+        return;
+    }
     process.stdout.write(`From: ${fromCommitId.slice(7, 7 + 12)}  ${fromCommit.message}\n`);
     process.stdout.write(`To:   ${toCommitId.slice(7, 7 + 12)}  ${toCommit.message}\n\n`);
     let totalAdded = 0;
@@ -581,7 +592,7 @@ const formatBytes = (n) => {
 // classified modifications, added/removed APIs, and process changes. We
 // expose it as a separate module-local helper so the CLI handler can
 // dispatch on the flag.
-export const diffSemanticCommand = async (from, to) => {
+export const diffSemanticCommand = async (from, to, opts = {}) => {
     const ctx = await resolveGraphstore(process.cwd());
     const fromCommit = await readCommit(ctx.cas, await resolveCommitTarget(ctx, from));
     const toCommit = await readCommit(ctx.cas, await resolveCommitTarget(ctx, to));
@@ -590,6 +601,17 @@ export const diffSemanticCommand = async (from, to) => {
         from: fromCommit.snapshot,
         to: toCommit.snapshot,
     });
+    // --json: same shape as diff (plain) but with the semantic payload. The
+    // PR-review GitHub Action consumes this directly to render the Markdown
+    // comment without parsing free-form text.
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({
+            from: { ref: from, message: fromCommit.message },
+            to: { ref: to, message: toCommit.message },
+            semantic: d,
+        }, null, 2) + '\n');
+        return;
+    }
     process.stdout.write(`From: ${from}  (${fromCommit.message})\n`);
     process.stdout.write(`To:   ${to}    (${toCommit.message})\n\n`);
     if (d.addedAPIs.length > 0) {

package/dist/cli/index.js

@@ -8,10 +8,7 @@ import { registerGroupCommands } from './group.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
 const program = new Command();
-program
-    .name('codragraph')
-    .description('CodraGraph local CLI and MCP server')
-    .version(pkg.version);
+program.name('codragraph').description('CodraGraph local CLI and MCP server').version(pkg.version);
 program
     .command('setup')
     .description('One-time setup: configure MCP for Cursor, Claude Code, OpenCode, Codex')
@@ -22,6 +19,7 @@ program
     .option('-f, --force', 'Force full re-index even if up to date')
     .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
     .option('--skills', 'Generate repo-specific skill files from detected communities')
+    .option('--skill-targets <list>', 'CSV of editor targets for --skills (claude, cursor, opencode, codex). Default: claude.')
     .option('--skip-agents-md', 'Skip updating the codragraph section in AGENTS.md and CLAUDE.md')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-git', 'Index a folder without requiring a .git directory')
@@ -31,12 +29,24 @@ program
     'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.')
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
+    .option('--no-setup', 'Skip the first-run editor setup (auto-runs once when ~/.codragraph/registry.json is missing)')
+    .option('--compress <encoding>', 'Compress per-row content (RFC 0001 Phase 2). One of: none (default), brotli, zstd. zstd requires Node ≥ 22.15.', 'none')
     .addHelpText('after', '\nEnvironment variables:\n' +
     '  CODRAGRAPH_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .codragraphignore)\n' +
     '  CODRAGRAPH_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '\nTip: `.codragraphignore` supports `.gitignore`-style negation. Add e.g.\n' +
     '     `!__tests__/` to index a directory that is auto-filtered by default (#771).')
     .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
+program
+    .command('profile-heap [path]')
+    .description('Run analyze with heap-profile instrumentation (RFC 0002 Phase 1). ' +
+    'Writes per-phase v8 heap snapshots + a JSONL RSS timeline under ' +
+    '.codragraph/heap-profiles/, then prints a summary table.')
+    .option('-f, --force', 'Force full re-index (analyze flag, passed through)')
+    .option('--skip-git', 'Index a folder without requiring a .git directory')
+    .option('--no-setup', 'Skip first-run editor setup')
+    .option('--no-summary', 'Skip the post-run summary table (raw artifacts only)')
+    .action(createLazyAction(() => import('./profile-heap.js'), 'profileHeapCommand'));
 program
     .command('index [path...]')
     .description('Register an existing .codragraph/ folder into the global registry (no re-analysis needed)')
@@ -195,12 +205,13 @@ program
     .command('diff <from> <to>')
     .description('Structural diff between two graph commits or branches')
     .option('--semantic', 'Use the semantic differ (added APIs, classified modifications, processes)')
+    .option('--json', 'Emit machine-readable JSON instead of human-readable text (for CI / GitHub Action consumers)')
     .action(async (from, to, opts) => {
     const mod = await import('./graphstore.js');
     if (opts.semantic)
-        await mod.diffSemanticCommand(from, to);
+        await mod.diffSemanticCommand(from, to, { json: opts.json });
     else
-        await mod.diffCommand(from, to);
+        await mod.diffCommand(from, to, { json: opts.json });
 });
 program
     .command('merge <branch>')