@codragraph/cli 2.1.5 → 2.1.6

package/README.md

@@ -25,12 +25,15 @@ 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.
+Smart analyze now patches the existing graph for normal day-to-day changes:
+source edits, renames, large diffs, and topology-only files replace only the
+affected file-scoped rows, then recompute communities, execution flows, and
+FeatureCluster packs. Package/config or ignore-rule inputs refresh all
+file-scoped rows without falling back to a full cold rebuild. 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.
 
@@ -62,16 +65,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.5 mcp
+claude mcp add codragraph -- npx -y @codragraph/cli@2.1.6 mcp
 
 # Windows
-claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.5 mcp
+claude mcp add codragraph -- cmd /c npx -y @codragraph/cli@2.1.6 mcp
 ```
 
 ### Codex (full support — MCP + skills)
 
 ```bash
-codex mcp add codragraph -- npx -y @codragraph/cli@2.1.5 mcp
+codex mcp add codragraph -- npx -y @codragraph/cli@2.1.6 mcp
 ```
 
 ### Cursor / Windsurf
@@ -83,7 +86,7 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
   "mcpServers": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.5", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.6", "mcp"]
     }
   }
 }
@@ -98,7 +101,7 @@ Add to `~/.config/opencode/config.json`:
   "mcp": {
     "codragraph": {
       "command": "npx",
-      "args": ["-y", "@codragraph/cli@2.1.5", "mcp"]
+      "args": ["-y", "@codragraph/cli@2.1.6", "mcp"]
     }
   }
 }
@@ -184,6 +187,8 @@ 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
+codragraph detect-changes --scope unstaged  # Map working-tree diff to symbols/processes
+codragraph detect-changes --scope all       # Include staged + unstaged changes
 codragraph clean                   # Delete index for current repo
 codragraph clean --all --force     # Delete all indexes
 codragraph wiki [path]             # Generate LLM-powered docs from knowledge graph
@@ -304,9 +309,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.5 analyze          # no global install
+npx @codragraph/cli@2.1.6 analyze          # no global install
 # or
-npm install -g @codragraph/cli@2.1.5       # upgrade a global install
+npm install -g @codragraph/cli@2.1.6       # upgrade a global install
 ```
 
 If you still hit npm install issues after upgrading, these generic workarounds

package/dist/cli/analyze.d.ts

@@ -7,9 +7,14 @@
  * This CLI wrapper handles: heap management, progress bar, SIGINT,
  * skill generation (--skills), summary output, and process.exit().
  */
+import { type AnalyzeProfileOption, type CompressionOption, type EmbeddingMode } from '../core/adaptive-profile.js';
 export interface AnalyzeOptions {
     force?: boolean;
     embeddings?: boolean;
+    /** Adaptive runtime profile. `auto` detects CPU/RAM/heap and chooses lean/balanced/power. */
+    profile?: AnalyzeProfileOption;
+    /** Embedding policy. `--embeddings` is kept as a shortcut for `on`. */
+    embeddingMode?: EmbeddingMode;
     skills?: boolean;
     verbose?: boolean;
     /** Skip AGENTS.md and CLAUDE.md codragraph block updates. */
@@ -54,12 +59,12 @@ export interface AnalyzeOptions {
      */
     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
+     * RFC 0001 Phase 2 - per-row content compression. Accepts `'auto'`
+     * (default), `'none'`, `'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';
+    compress?: CompressionOption;
 }
 export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;

package/dist/cli/analyze.js

@@ -17,6 +17,7 @@ import { closeCgdb } from '../core/cgdb/cgdb-adapter.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { parseAnalyzeProfile, parseCompressionOption, parseEmbeddingMode, } from '../core/adaptive-profile.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';
@@ -28,10 +29,14 @@ const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
 const STACK_KB = 4096;
 const STACK_FLAG = `--stack-size=${STACK_KB}`;
+function hasNodeFlag(flagName, nodeOpts, execArgv) {
+    return (nodeOpts.includes(flagName) ||
+        execArgv.some((arg) => arg === flagName || arg.startsWith(`${flagName}=`)));
+}
 /** Re-exec the process with an 8GB heap and larger stack if we're currently below that. */
 function ensureHeap() {
     const nodeOpts = process.env.NODE_OPTIONS || '';
-    if (nodeOpts.includes('--max-old-space-size'))
+    if (hasNodeFlag('--max-old-space-size', nodeOpts, process.execArgv))
         return false;
     const v8Heap = v8.getHeapStatistics().heap_size_limit;
     if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
@@ -39,10 +44,14 @@ function ensureHeap() {
     // --stack-size is a V8 flag not allowed in NODE_OPTIONS on Node 24+,
     // so pass it only as a direct CLI argument, not via the environment.
     const cliFlags = [HEAP_FLAG];
-    if (!nodeOpts.includes('--stack-size'))
+    if (!hasNodeFlag('--stack-size', nodeOpts, process.execArgv))
         cliFlags.push(STACK_FLAG);
     try {
-        execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
+        // Preserve loader/debug flags from the outer process. This is required
+        // for source-mode invocations such as `tsx src/cli/index.ts analyze`;
+        // otherwise the child runs plain node against .ts files and cannot
+        // resolve the emitted .js import specifiers.
+        execFileSync(process.execPath, [...process.execArgv, ...cliFlags, ...process.argv.slice(1)], {
             stdio: 'inherit',
             env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
         });
@@ -58,18 +67,31 @@ 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
+    try {
+        parseAnalyzeProfile(options?.profile);
+        parseEmbeddingMode(options?.embeddingMode);
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exitCode = 2;
+        return;
+    }
+    // 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 requestedCompress = options?.compress ?? 'auto';
+    try {
+        parseCompressionOption(requestedCompress);
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (requestedCompress !== 'auto' && requestedCompress !== 'none') {
+        if (requestedCompress === 'zstd') {
             const { isEncodingSupported } = await import('@codragraph/graphstore');
             if (!isEncodingSupported('zstd')) {
                 console.error('  --compress zstd requires Node ≥ 22.15.0 (native node:zlib zstd).\n' +
@@ -84,7 +106,7 @@ export const analyzeCommand = async (inputPath, options) => {
         // 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/cgdb size.\n` +
+        console.warn(`  Note: --compress ${requestedCompress} reduces .codragraph/cgdb 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` +
@@ -241,8 +263,10 @@ export const analyzeCommand = async (inputPath, options) => {
             // 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.
+            // Default 'auto' lets the adaptive profile choose the storage tier.
             compress: options?.compress,
+            profile: options?.profile,
+            embeddingMode: options?.embeddingMode,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);

package/dist/cli/index.js

@@ -37,7 +37,9 @@ program
     .command('analyze [path]')
     .description('Index a repository (full analysis)')
     .option('-f, --force', 'Force full re-index even if up to date')
-    .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+    .option('--profile <mode>', 'Adaptive runtime profile: auto, lean, balanced, power', 'auto')
+    .option('--embedding-mode <mode>', 'Embedding policy: auto, off, on', 'auto')
+    .option('--embeddings', 'Enable embedding generation for semantic search (same as --embedding-mode on)')
     .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')
@@ -50,7 +52,7 @@ program
     .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')
+    .option('--compress <encoding>', 'Compress per-row content. One of: auto (default), none, brotli, zstd. zstd requires Node >= 22.15.', 'auto')
     .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' +
@@ -141,13 +143,17 @@ program
     .option('-r, --repo <name>', 'Target repository')
     .option('-u, --uid <uid>', 'Direct symbol UID (zero-ambiguity lookup)')
     .option('-f, --file <path>', 'File path to disambiguate common names')
+    .option('-k, --kind <kind>', 'Symbol kind to disambiguate common names')
     .option('--content', 'Include full symbol source code')
     .action(createOneShotLazyAction(() => import('./tool.js'), 'contextCommand'));
 program
-    .command('impact <target>')
+    .command('impact [target]')
     .description('Blast radius analysis: what breaks if you change a symbol')
     .option('-d, --direction <dir>', 'upstream (dependants) or downstream (dependencies)', 'upstream')
     .option('-r, --repo <name>', 'Target repository')
+    .option('-u, --uid <uid>', 'Direct target symbol UID (zero-ambiguity lookup)')
+    .option('-f, --file <path>', 'File path to disambiguate common names')
+    .option('-k, --kind <kind>', 'Symbol kind to disambiguate common names')
     .option('--depth <n>', 'Max relationship depth (default: 3)')
     .option('--include-tests', 'Include test files in results')
     .action(createOneShotLazyAction(() => import('./tool.js'), 'impactCommand'));

package/dist/cli/status.d.ts

@@ -13,7 +13,7 @@ export interface IndexStorageSummary {
 }
 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?: {
+export declare const formatIndexStatusLines: (summary: IndexStorageSummary | null, meta: Pick<RepoMeta, "stats" | "compress" | "adaptiveProfile">, options?: {
     largeIndexWarningBytes?: number;
 }) => string[];
 export declare const statusCommand: () => Promise<void>;

package/dist/cli/status.js

@@ -94,6 +94,14 @@ export const formatIndexStatusLines = (summary, meta, options = {}) => {
     const embeddings = meta.stats?.embeddings;
     lines.push(`Embeddings: ${typeof embeddings === 'number' ? embeddings.toLocaleString('en-US') : 'unknown'}`);
     lines.push(`Compression: ${meta.compress ?? 'none'}`);
+    if (meta.adaptiveProfile?.resolved) {
+        const profile = meta.adaptiveProfile;
+        const workerText = typeof profile.workerPoolSize === 'number' ? `, workers ${profile.workerPoolSize}` : '';
+        const embeddingText = profile.embeddingDecision
+            ? `, embeddings ${profile.embeddingDecision}`
+            : '';
+        lines.push(`Adaptive profile: ${profile.resolved}${workerText}${embeddingText}`);
+    }
     return lines;
 };
 export const statusCommand = async () => {

package/dist/cli/tool.d.ts

@@ -21,15 +21,23 @@ export declare function queryCommand(queryText: string, options?: {
     limit?: string;
     content?: boolean;
 }): Promise<void>;
-export declare function contextCommand(name: string, options?: {
+export declare function contextCommand(name: string | undefined | {
+    opts?: () => Record<string, unknown>;
+}, options?: {
     repo?: string;
     file?: string;
     uid?: string;
+    kind?: string;
     content?: boolean;
 }): Promise<void>;
-export declare function impactCommand(target: string, options?: {
+export declare function impactCommand(target: string | undefined | {
+    opts?: () => Record<string, unknown>;
+}, options?: {
     direction?: string;
     repo?: string;
+    uid?: string;
+    file?: string;
+    kind?: string;
     depth?: string;
     includeTests?: boolean;
 }): Promise<void>;

package/dist/cli/tool.js

@@ -45,6 +45,12 @@ async function resolveCliRepoParam(repoParam) {
     process.exitCode = 1;
     return null;
 }
+function unwrapCommanderOptions(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const maybeCommand = value;
+    return typeof maybeCommand.opts === 'function' ? maybeCommand.opts() : value;
+}
 /**
  * Write tool output to stdout using low-level fd write.
  *
@@ -90,7 +96,12 @@ export async function queryCommand(queryText, options) {
     emitTokenStats(result);
 }
 export async function contextCommand(name, options) {
-    if (!name?.trim() && !options?.uid) {
+    let symbolName = typeof name === 'string' ? name : undefined;
+    if (typeof name !== 'string' && name && !options) {
+        options = unwrapCommanderOptions(name);
+        symbolName = undefined;
+    }
+    if (!symbolName?.trim() && !options?.uid) {
         console.error('Usage: codragraph context <symbol_name> [--uid <uid>] [--file <path>]');
         process.exit(1);
     }
@@ -98,9 +109,10 @@ export async function contextCommand(name, options) {
     if (!repo)
         return;
     const result = await callToolOnce('context', {
-        name: name || undefined,
+        name: symbolName || undefined,
         uid: options?.uid,
         file_path: options?.file,
+        kind: options?.kind,
         include_content: options?.content ?? false,
         repo,
     });
@@ -108,8 +120,13 @@ export async function contextCommand(name, options) {
     emitTokenStats(result);
 }
 export async function impactCommand(target, options) {
-    if (!target?.trim()) {
-        console.error('Usage: codragraph impact <symbol_name> [--direction upstream|downstream]');
+    let targetName = typeof target === 'string' ? target : undefined;
+    if (typeof target !== 'string' && target && !options) {
+        options = unwrapCommanderOptions(target);
+        targetName = undefined;
+    }
+    if (!targetName?.trim() && !options?.uid) {
+        console.error('Usage: codragraph impact <symbol_name> [--uid <uid>] [--direction upstream|downstream]');
         process.exit(1);
     }
     try {
@@ -117,7 +134,10 @@ export async function impactCommand(target, options) {
         if (!repo)
             return;
         const result = await callToolOnce('impact', {
-            target,
+            target: targetName || undefined,
+            target_uid: options?.uid,
+            file_path: options?.file,
+            kind: options?.kind,
             direction: options?.direction || 'upstream',
             maxDepth: options?.depth ? parseInt(options.depth, 10) : undefined,
             includeTests: options?.includeTests ?? false,
@@ -131,7 +151,7 @@ export async function impactCommand(target, options) {
         // The backend's impact() already returns structured errors for graph query failures
         output({
             error: (err instanceof Error ? err.message : String(err)) || 'Impact analysis failed unexpectedly',
-            target: { name: target },
+            target: { name: targetName || options?.uid },
             direction: options?.direction || 'upstream',
             suggestion: 'Try reducing --depth or using codragraph context <symbol> as a fallback',
         });
@@ -272,6 +292,7 @@ function formatDetectChangesResult(result) {
     return lines.join('\n').trim();
 }
 export async function detectChangesCommand(options) {
+    options = unwrapCommanderOptions(options);
     const repo = await resolveCliRepoParam(options?.repo);
     if (!repo)
         return;

package/dist/core/adaptive-profile.d.ts

@@ -0,0 +1,52 @@
+import type { ContentEncoding } from '@codragraph/graphstore';
+import type { RepoMeta } from '../storage/repo-manager.js';
+export type AnalyzeProfileOption = 'auto' | 'lean' | 'balanced' | 'power';
+export type ResolvedAnalyzeProfile = Exclude<AnalyzeProfileOption, 'auto'>;
+export type EmbeddingMode = 'auto' | 'off' | 'on';
+export type CompressionOption = ContentEncoding | 'auto';
+export interface MachineSnapshot {
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    logicalCpus: number;
+    availableParallelism: number;
+    totalMemoryBytes: number;
+    freeMemoryBytes: number;
+    heapLimitBytes: number;
+    nodeVersion: string;
+    httpEmbeddingsConfigured: boolean;
+}
+export interface AdaptiveAnalyzePlan {
+    requestedProfile: AnalyzeProfileOption;
+    profile: ResolvedAnalyzeProfile;
+    machine: MachineSnapshot;
+    compress: ContentEncoding;
+    embeddingMode: EmbeddingMode;
+    embeddingNodeLimit: number;
+    workerPoolSize: number;
+    workerSubBatchSize: number;
+    reasons: string[];
+}
+export interface EmbeddingDecision {
+    enabled: boolean;
+    reason: string;
+    limit: number;
+}
+export declare const parseAnalyzeProfile: (value?: string) => AnalyzeProfileOption;
+export declare const parseEmbeddingMode: (value?: string) => EmbeddingMode;
+export declare const parseCompressionOption: (value?: string) => CompressionOption;
+export declare const detectMachineSnapshot: () => MachineSnapshot;
+export declare const resolveAnalyzeProfile: (requested: AnalyzeProfileOption, machine: MachineSnapshot) => ResolvedAnalyzeProfile;
+export declare const resolveEmbeddingMode: (embeddingsFlag: boolean | undefined, requestedMode: string | undefined) => EmbeddingMode;
+export declare const resolveCompression: (requested: CompressionOption, profile: ResolvedAnalyzeProfile, existingMeta?: Pick<RepoMeta, "compress"> | null) => ContentEncoding;
+export declare const embeddingLimitForProfile: (profile: ResolvedAnalyzeProfile, httpEmbeddingsConfigured: boolean) => number;
+export declare const workerPlanForProfile: (profile: ResolvedAnalyzeProfile, machine: Pick<MachineSnapshot, "availableParallelism">) => Pick<AdaptiveAnalyzePlan, "workerPoolSize" | "workerSubBatchSize">;
+export declare const resolveAdaptiveAnalyzePlan: (input: {
+    profile?: string;
+    embeddingMode?: string;
+    embeddings?: boolean;
+    compress?: string;
+    existingMeta?: Pick<RepoMeta, "compress"> | null;
+    machine?: MachineSnapshot;
+}) => AdaptiveAnalyzePlan;
+export declare const decideEmbeddingRun: (plan: Pick<AdaptiveAnalyzePlan, "embeddingMode" | "embeddingNodeLimit" | "profile" | "machine">, stats?: Pick<NonNullable<RepoMeta["stats"]>, "nodes" | "embeddings">) => EmbeddingDecision;
+export declare const formatAdaptiveAnalyzePlan: (plan: AdaptiveAnalyzePlan) => string;

package/dist/core/adaptive-profile.js

@@ -0,0 +1,180 @@
+import os from 'node:os';
+import v8 from 'node:v8';
+const GIB = 1024 * 1024 * 1024;
+const validProfiles = new Set(['auto', 'lean', 'balanced', 'power']);
+const validEmbeddingModes = new Set(['auto', 'off', 'on']);
+const validCompressionOptions = new Set(['auto', 'none', 'brotli', 'zstd']);
+const safeAvailableParallelism = () => {
+    const fn = os.availableParallelism;
+    if (typeof fn === 'function') {
+        try {
+            return Math.max(1, fn());
+        }
+        catch {
+            /* fall back to os.cpus */
+        }
+    }
+    return Math.max(1, os.cpus().length);
+};
+export const parseAnalyzeProfile = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validProfiles.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`profile must be one of: auto, lean, balanced, power (got: ${value})`);
+};
+export const parseEmbeddingMode = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validEmbeddingModes.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`embedding-mode must be one of: auto, off, on (got: ${value})`);
+};
+export const parseCompressionOption = (value) => {
+    const normalized = (value ?? 'auto').toLowerCase();
+    if (validCompressionOptions.has(normalized)) {
+        return normalized;
+    }
+    throw new Error(`compress must be one of: auto, none, brotli, zstd (got: ${value})`);
+};
+export const detectMachineSnapshot = () => ({
+    platform: process.platform,
+    arch: process.arch,
+    logicalCpus: Math.max(1, os.cpus().length),
+    availableParallelism: safeAvailableParallelism(),
+    totalMemoryBytes: os.totalmem(),
+    freeMemoryBytes: os.freemem(),
+    heapLimitBytes: v8.getHeapStatistics().heap_size_limit,
+    nodeVersion: process.version,
+    httpEmbeddingsConfigured: Boolean(process.env.CODRAGRAPH_EMBEDDING_URL && process.env.CODRAGRAPH_EMBEDDING_MODEL),
+});
+export const resolveAnalyzeProfile = (requested, machine) => {
+    if (requested !== 'auto')
+        return requested;
+    const memoryGiB = machine.totalMemoryBytes / GIB;
+    const heapGiB = machine.heapLimitBytes / GIB;
+    const parallelism = machine.availableParallelism;
+    if (parallelism >= 8 && memoryGiB >= 24 && heapGiB >= 6)
+        return 'power';
+    if (parallelism >= 4 && memoryGiB >= 8 && heapGiB >= 3)
+        return 'balanced';
+    return 'lean';
+};
+export const resolveEmbeddingMode = (embeddingsFlag, requestedMode) => {
+    if (embeddingsFlag === true)
+        return 'on';
+    return parseEmbeddingMode(requestedMode);
+};
+export const resolveCompression = (requested, profile, existingMeta) => {
+    if (requested !== 'auto')
+        return requested;
+    if (existingMeta)
+        return existingMeta.compress ?? 'none';
+    // Lean machines optimize for index footprint and lower read amplification.
+    // Balanced/power machines keep full body BM25 by default for maximum recall.
+    return profile === 'lean' ? 'brotli' : 'none';
+};
+export const embeddingLimitForProfile = (profile, httpEmbeddingsConfigured) => {
+    if (httpEmbeddingsConfigured)
+        return profile === 'lean' ? 25_000 : 150_000;
+    if (profile === 'power')
+        return 100_000;
+    if (profile === 'balanced')
+        return 35_000;
+    return 8_000;
+};
+export const workerPlanForProfile = (profile, machine) => {
+    const spare = Math.max(1, machine.availableParallelism - 1);
+    if (profile === 'power') {
+        return { workerPoolSize: Math.min(8, spare), workerSubBatchSize: 250 };
+    }
+    if (profile === 'balanced') {
+        return { workerPoolSize: Math.min(4, spare), workerSubBatchSize: 160 };
+    }
+    return { workerPoolSize: 1, workerSubBatchSize: 80 };
+};
+export const resolveAdaptiveAnalyzePlan = (input) => {
+    const machine = input.machine ?? detectMachineSnapshot();
+    const requestedProfile = parseAnalyzeProfile(input.profile);
+    const profile = resolveAnalyzeProfile(requestedProfile, machine);
+    const embeddingMode = resolveEmbeddingMode(input.embeddings, input.embeddingMode);
+    const compress = resolveCompression(parseCompressionOption(input.compress), profile, input.existingMeta);
+    const workerPlan = workerPlanForProfile(profile, machine);
+    const embeddingNodeLimit = embeddingLimitForProfile(profile, machine.httpEmbeddingsConfigured);
+    const reasons = [
+        `${machine.platform}/${machine.arch}`,
+        `${machine.availableParallelism} parallel slot(s)`,
+        `${(machine.totalMemoryBytes / GIB).toFixed(1)} GiB RAM`,
+        `${(machine.heapLimitBytes / GIB).toFixed(1)} GiB heap`,
+    ];
+    if (machine.httpEmbeddingsConfigured)
+        reasons.push('HTTP embeddings configured');
+    return {
+        requestedProfile,
+        profile,
+        machine,
+        compress,
+        embeddingMode,
+        embeddingNodeLimit,
+        workerPoolSize: workerPlan.workerPoolSize,
+        workerSubBatchSize: workerPlan.workerSubBatchSize,
+        reasons,
+    };
+};
+export const decideEmbeddingRun = (plan, stats) => {
+    const nodes = stats?.nodes;
+    const existingEmbeddings = stats?.embeddings ?? 0;
+    const overLimit = typeof nodes === 'number' && nodes > plan.embeddingNodeLimit;
+    if (plan.embeddingMode === 'off') {
+        return { enabled: false, reason: 'embedding-mode is off', limit: plan.embeddingNodeLimit };
+    }
+    if (overLimit) {
+        return {
+            enabled: false,
+            reason: `${nodes.toLocaleString('en-US')} nodes exceeds ${plan.profile} embedding limit ${plan.embeddingNodeLimit.toLocaleString('en-US')}`,
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.embeddingMode === 'on') {
+        return { enabled: true, reason: 'explicit embedding request', limit: plan.embeddingNodeLimit };
+    }
+    if (existingEmbeddings > 0) {
+        return {
+            enabled: true,
+            reason: 'preserving existing embeddings',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.machine.httpEmbeddingsConfigured) {
+        return {
+            enabled: true,
+            reason: 'HTTP embedding endpoint configured',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'power') {
+        return {
+            enabled: true,
+            reason: 'power profile can run local embeddings',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'balanced' && (nodes ?? Number.POSITIVE_INFINITY) <= 5_000) {
+        return {
+            enabled: true,
+            reason: 'small repo on balanced profile',
+            limit: plan.embeddingNodeLimit,
+        };
+    }
+    if (plan.profile === 'lean' && (nodes ?? Number.POSITIVE_INFINITY) <= 1_000) {
+        return { enabled: true, reason: 'small repo on lean profile', limit: plan.embeddingNodeLimit };
+    }
+    return {
+        enabled: false,
+        reason: 'auto mode skipped first-time local embeddings on this profile',
+        limit: plan.embeddingNodeLimit,
+    };
+};
+export const formatAdaptiveAnalyzePlan = (plan) => `Adaptive analyze: ${plan.profile} profile (${plan.reasons.join(', ')}); ` +
+    `workers=${plan.workerPoolSize}, subBatch=${plan.workerSubBatchSize}, ` +
+    `compress=${plan.compress}, embeddings=${plan.embeddingMode}.`;