@veewo/gitnexus 1.3.4

package/dist/cli/analyze.js

@@ -0,0 +1,384 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .gitnexus/
+ */
+import path from 'path';
+import { execFileSync } from 'child_process';
+import v8 from 'v8';
+import cliProgress from 'cli-progress';
+import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
+import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex, loadCachedEmbeddings } from '../core/kuzu/kuzu-adapter.js';
+// Embedding imports are lazy (dynamic import) so onnxruntime-node is never
+// loaded when embeddings are not requested. This avoids crashes on Node
+// versions whose ABI is not yet supported by the native binary (#89).
+// disposeEmbedder intentionally not called — ONNX Runtime segfaults on cleanup (see #38)
+import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
+import { generateAIContextFiles } from './ai-context.js';
+import fs from 'fs/promises';
+import { registerClaudeHook } from './claude-hooks.js';
+import { normalizeRepoAlias, parseExtensionList, resolveAnalyzeScopeRules } from './analyze-options.js';
+const HEAP_MB = 8192;
+const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+/** Re-exec the process with an 8GB heap if we're currently below that. */
+function ensureHeap() {
+    const nodeOpts = process.env.NODE_OPTIONS || '';
+    if (nodeOpts.includes('--max-old-space-size'))
+        return false;
+    const v8Heap = v8.getHeapStatistics().heap_size_limit;
+    if (v8Heap >= HEAP_MB * 1024 * 1024 * 0.9)
+        return false;
+    try {
+        execFileSync(process.execPath, [HEAP_FLAG, ...process.argv.slice(1)], {
+            stdio: 'inherit',
+            env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
+        });
+    }
+    catch (e) {
+        process.exitCode = e.status ?? 1;
+    }
+    return true;
+}
+/** Threshold: auto-skip embeddings for repos with more nodes than this */
+const EMBEDDING_NODE_LIMIT = 50_000;
+const PHASE_LABELS = {
+    extracting: 'Scanning files',
+    structure: 'Building structure',
+    parsing: 'Parsing code',
+    imports: 'Resolving imports',
+    calls: 'Tracing calls',
+    heritage: 'Extracting inheritance',
+    communities: 'Detecting communities',
+    processes: 'Detecting processes',
+    complete: 'Pipeline complete',
+    kuzu: 'Loading into KuzuDB',
+    fts: 'Creating search indexes',
+    embeddings: 'Generating embeddings',
+    done: 'Done',
+};
+export const analyzeCommand = async (inputPath, options) => {
+    if (ensureHeap())
+        return;
+    console.log('\n  GitNexus Analyzer\n');
+    let includeExtensions = [];
+    let scopeRules = [];
+    let repoAlias;
+    try {
+        includeExtensions = parseExtensionList(options?.extensions);
+        scopeRules = await resolveAnalyzeScopeRules({
+            scopeManifest: options?.scopeManifest,
+            scopePrefix: options?.scopePrefix,
+        });
+        repoAlias = normalizeRepoAlias(options?.repoAlias);
+    }
+    catch (error) {
+        console.log(`  ${error?.message || String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            console.log('  Not inside a git repository\n');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    if (!isGitRepo(repoPath)) {
+        console.log('  Not a git repository\n');
+        process.exitCode = 1;
+        return;
+    }
+    const { storagePath, kuzuPath } = getStoragePaths(repoPath);
+    const currentCommit = getCurrentCommit(repoPath);
+    const existingMeta = await loadMeta(storagePath);
+    if (existingMeta &&
+        !options?.force &&
+        existingMeta.lastCommit === currentCommit &&
+        includeExtensions.length === 0 &&
+        scopeRules.length === 0 &&
+        !repoAlias) {
+        console.log('  Already up to date\n');
+        return;
+    }
+    // Single progress bar for entire pipeline
+    const bar = new cliProgress.SingleBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    }, cliProgress.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    // Graceful SIGINT handling — clean up resources and exit
+    let aborted = false;
+    const sigintHandler = () => {
+        if (aborted)
+            process.exit(1); // Second Ctrl-C: force exit
+        aborted = true;
+        bar.stop();
+        console.log('\n  Interrupted — cleaning up...');
+        closeKuzu().catch(() => { }).finally(() => process.exit(130));
+    };
+    process.on('SIGINT', sigintHandler);
+    // Route all console output through bar.log() so the bar doesn't stamp itself
+    // multiple times when other code writes to stdout/stderr mid-render.
+    const origLog = console.log.bind(console);
+    const origWarn = console.warn.bind(console);
+    const origError = console.error.bind(console);
+    const barLog = (...args) => {
+        // Clear the bar line, print the message, then let the next bar.update redraw
+        process.stdout.write('\x1b[2K\r');
+        origLog(args.map(a => (typeof a === 'string' ? a : String(a))).join(' '));
+    };
+    console.log = barLog;
+    console.warn = barLog;
+    console.error = barLog;
+    // Track elapsed time per phase — both updateBar and the interval use the
+    // same format so they don't flicker against each other.
+    let lastPhaseLabel = 'Initializing...';
+    let phaseStart = Date.now();
+    /** Update bar with phase label + elapsed seconds (shown after 3s). */
+    const updateBar = (value, phaseLabel) => {
+        if (phaseLabel !== lastPhaseLabel) {
+            lastPhaseLabel = phaseLabel;
+            phaseStart = Date.now();
+        }
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        const display = elapsed >= 3 ? `${phaseLabel} (${elapsed}s)` : phaseLabel;
+        bar.update(value, { phase: display });
+    };
+    // Tick elapsed seconds for phases with infrequent progress callbacks
+    // (e.g. CSV streaming, FTS indexing). Uses the same display format as
+    // updateBar so there's no flickering.
+    const elapsedTimer = setInterval(() => {
+        const elapsed = Math.round((Date.now() - phaseStart) / 1000);
+        if (elapsed >= 3) {
+            bar.update({ phase: `${lastPhaseLabel} (${elapsed}s)` });
+        }
+    }, 1000);
+    const t0Global = Date.now();
+    // ── Cache embeddings from existing index before rebuild ────────────
+    let cachedEmbeddingNodeIds = new Set();
+    let cachedEmbeddings = [];
+    if (options?.embeddings && existingMeta && !options?.force) {
+        try {
+            updateBar(0, 'Caching embeddings...');
+            await initKuzu(kuzuPath);
+            const cached = await loadCachedEmbeddings();
+            cachedEmbeddingNodeIds = cached.embeddingNodeIds;
+            cachedEmbeddings = cached.embeddings;
+            await closeKuzu();
+        }
+        catch {
+            try {
+                await closeKuzu();
+            }
+            catch { }
+        }
+    }
+    // ── Phase 1: Full Pipeline (0–60%) ─────────────────────────────────
+    let pipelineResult;
+    try {
+        pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
+            const phaseLabel = PHASE_LABELS[progress.phase] || progress.phase;
+            const scaled = Math.round(progress.percent * 0.6);
+            updateBar(scaled, phaseLabel);
+        }, { includeExtensions, scopeRules });
+    }
+    catch (error) {
+        clearInterval(elapsedTimer);
+        process.removeListener('SIGINT', sigintHandler);
+        console.log = origLog;
+        console.warn = origWarn;
+        console.error = origError;
+        bar.stop();
+        console.log(`\n  ${error?.message || String(error)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // ── Phase 2: KuzuDB (60–85%) ──────────────────────────────────────
+    updateBar(60, 'Loading into KuzuDB...');
+    await closeKuzu();
+    const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
+    for (const f of kuzuFiles) {
+        try {
+            await fs.rm(f, { recursive: true, force: true });
+        }
+        catch { }
+    }
+    const t0Kuzu = Date.now();
+    await initKuzu(kuzuPath);
+    let kuzuMsgCount = 0;
+    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
+        kuzuMsgCount++;
+        const progress = Math.min(84, 60 + Math.round((kuzuMsgCount / (kuzuMsgCount + 10)) * 24));
+        updateBar(progress, msg);
+    });
+    const kuzuTime = ((Date.now() - t0Kuzu) / 1000).toFixed(1);
+    const kuzuWarnings = kuzuResult.warnings;
+    // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
+    updateBar(85, 'Creating search indexes...');
+    const t0Fts = Date.now();
+    try {
+        await createFTSIndex('File', 'file_fts', ['name', 'content']);
+        await createFTSIndex('Function', 'function_fts', ['name', 'content']);
+        await createFTSIndex('Class', 'class_fts', ['name', 'content']);
+        await createFTSIndex('Method', 'method_fts', ['name', 'content']);
+        await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
+    }
+    catch (e) {
+        // Non-fatal — FTS is best-effort
+    }
+    const ftsTime = ((Date.now() - t0Fts) / 1000).toFixed(1);
+    // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
+    if (cachedEmbeddings.length > 0) {
+        updateBar(88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
+        const EMBED_BATCH = 200;
+        for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
+            const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+            const paramsList = batch.map(e => ({ nodeId: e.nodeId, embedding: e.embedding }));
+            try {
+                await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+            }
+            catch { /* some may fail if node was removed, that's fine */ }
+        }
+    }
+    // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
+    const stats = await getKuzuStats();
+    let embeddingTime = '0.0';
+    let embeddingSkipped = true;
+    let embeddingSkipReason = 'off (use --embeddings to enable)';
+    if (options?.embeddings) {
+        if (stats.nodes > EMBEDDING_NODE_LIMIT) {
+            embeddingSkipReason = `skipped (${stats.nodes.toLocaleString()} nodes > ${EMBEDDING_NODE_LIMIT.toLocaleString()} limit)`;
+        }
+        else {
+            embeddingSkipped = false;
+        }
+    }
+    if (!embeddingSkipped) {
+        updateBar(90, 'Loading embedding model...');
+        const t0Emb = Date.now();
+        const { runEmbeddingPipeline } = await import('../core/embeddings/embedding-pipeline.js');
+        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
+            const scaled = 90 + Math.round((progress.percent / 100) * 8);
+            const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
+            updateBar(scaled, label);
+        }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
+        embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
+    }
+    // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
+    updateBar(98, 'Saving metadata...');
+    const meta = {
+        repoPath,
+        lastCommit: currentCommit,
+        indexedAt: new Date().toISOString(),
+        stats: {
+            files: pipelineResult.totalFileCount,
+            nodes: stats.nodes,
+            edges: stats.edges,
+            communities: pipelineResult.communityResult?.stats.totalCommunities,
+            processes: pipelineResult.processResult?.stats.totalProcesses,
+        },
+    };
+    await saveMeta(storagePath, meta);
+    const registeredRepo = await registerRepo(repoPath, meta, { repoAlias });
+    await addToGitignore(repoPath);
+    const hookResult = await registerClaudeHook();
+    const projectName = path.basename(repoPath);
+    let aggregatedClusterCount = 0;
+    if (pipelineResult.communityResult?.communities) {
+        const groups = new Map();
+        for (const c of pipelineResult.communityResult.communities) {
+            const label = c.heuristicLabel || c.label || 'Unknown';
+            groups.set(label, (groups.get(label) || 0) + c.symbolCount);
+        }
+        aggregatedClusterCount = Array.from(groups.values()).filter(count => count >= 5).length;
+    }
+    const aiContext = await generateAIContextFiles(repoPath, storagePath, projectName, {
+        files: pipelineResult.totalFileCount,
+        nodes: stats.nodes,
+        edges: stats.edges,
+        communities: pipelineResult.communityResult?.stats.totalCommunities,
+        clusters: aggregatedClusterCount,
+        processes: pipelineResult.processResult?.stats.totalProcesses,
+    });
+    await closeKuzu();
+    // Note: we intentionally do NOT call disposeEmbedder() here.
+    // ONNX Runtime's native cleanup segfaults on macOS and some Linux configs.
+    // Since the process exits immediately after, Node.js reclaims everything.
+    const totalTime = ((Date.now() - t0Global) / 1000).toFixed(1);
+    clearInterval(elapsedTimer);
+    process.removeListener('SIGINT', sigintHandler);
+    console.log = origLog;
+    console.warn = origWarn;
+    console.error = origError;
+    bar.update(100, { phase: 'Done' });
+    bar.stop();
+    // ── Summary ───────────────────────────────────────────────────────
+    const embeddingsCached = cachedEmbeddings.length > 0;
+    console.log(`\n  Repository indexed successfully (${totalTime}s)${embeddingsCached ? ` [${cachedEmbeddings.length} embeddings cached]` : ''}\n`);
+    console.log(`  Repo Name: ${registeredRepo.name}`);
+    console.log(`  Repo Alias: ${registeredRepo.alias || 'none'}`);
+    console.log(`  Scope Rules: ${scopeRules.length}`);
+    console.log(`  Scoped Files: ${pipelineResult.totalFileCount}`);
+    if (scopeRules.length > 0 && pipelineResult.scopeDiagnostics) {
+        const diagnostics = pipelineResult.scopeDiagnostics;
+        console.log(`  Scope Overlap Files: ${diagnostics.overlapFiles} (${diagnostics.dedupedMatchCount} duplicate matches removed)`);
+        if (diagnostics.normalizedCollisions.length === 0) {
+            console.log('  Scope Collisions: none');
+        }
+        else {
+            console.warn(`  Scope Collisions: ${diagnostics.normalizedCollisions.length} normalized path conflict(s) detected`);
+            diagnostics.normalizedCollisions.slice(0, 5).forEach((collision) => {
+                console.warn(`    - ${collision.normalizedPath} <= ${collision.paths.join(' | ')}`);
+            });
+            if (diagnostics.normalizedCollisions.length > 5) {
+                console.warn(`    ... ${diagnostics.normalizedCollisions.length - 5} more`);
+            }
+        }
+    }
+    console.log(`  ${stats.nodes.toLocaleString()} nodes | ${stats.edges.toLocaleString()} edges | ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters | ${pipelineResult.processResult?.stats.totalProcesses || 0} flows`);
+    console.log(`  KuzuDB ${kuzuTime}s | FTS ${ftsTime}s | Embeddings ${embeddingSkipped ? embeddingSkipReason : embeddingTime + 's'}`);
+    if (includeExtensions.length > 0) {
+        console.log(`  File filter: ${includeExtensions.join(', ')}`);
+    }
+    console.log(`  ${repoPath}`);
+    if (aiContext.files.length > 0) {
+        console.log(`  Context: ${aiContext.files.join(', ')}`);
+    }
+    if (hookResult.registered) {
+        console.log(`  Hooks: ${hookResult.message}`);
+    }
+    // Show a quiet summary if some edge types needed fallback insertion
+    if (kuzuWarnings.length > 0) {
+        const totalFallback = kuzuWarnings.reduce((sum, w) => {
+            const m = w.match(/\((\d+) edges\)/);
+            return sum + (m ? parseInt(m[1]) : 0);
+        }, 0);
+        console.log(`  Note: ${totalFallback} edges across ${kuzuWarnings.length} types inserted via fallback (schema will be updated in next release)`);
+    }
+    try {
+        await fs.access(getGlobalRegistryPath());
+    }
+    catch {
+        console.log('\n  Tip: Run `gitnexus setup` to configure MCP for your editor.');
+    }
+    console.log('');
+    // ONNX Runtime registers native atexit hooks that segfault during process
+    // shutdown on macOS (#38) and some Linux configs (#40). Force-exit to
+    // bypass them when embeddings were loaded.
+    if (!embeddingSkipped) {
+        process.exit(0);
+    }
+};

package/dist/cli/augment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+export declare function augmentCommand(pattern: string): Promise<void>;

package/dist/cli/augment.js

@@ -0,0 +1,33 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+import { augment } from '../core/augmentation/engine.js';
+export async function augmentCommand(pattern) {
+    if (!pattern || pattern.length < 3) {
+        process.exit(0);
+    }
+    try {
+        const result = await augment(pattern, process.cwd());
+        if (result) {
+            // IMPORTANT: Write to stderr, NOT stdout.
+            // KuzuDB's native module captures stdout fd at OS level during init,
+            // which makes stdout permanently broken in subprocess contexts.
+            // stderr is never captured, so it works reliably everywhere.
+            // The hook reads from the subprocess's stderr.
+            process.stderr.write(result + '\n');
+        }
+    }
+    catch {
+        // Graceful failure — never break the calling hook
+        process.exit(0);
+    }
+}

package/dist/cli/benchmark-agent-context.d.ts

@@ -0,0 +1,29 @@
+import { runAnalyze } from '../benchmark/analyze-runner.js';
+import { writeAgentContextReports } from '../benchmark/agent-context/report.js';
+import { runAgentContextBenchmark } from '../benchmark/agent-context/runner.js';
+import type { AgentContextDataset } from '../benchmark/agent-context/types.js';
+export declare function resolveAgentContextProfile(profile: string): {
+    maxScenarios: number;
+};
+export declare function resolveAgentContextRepoName(options: {
+    repo?: string;
+    repoAlias?: string;
+    targetPath?: string;
+}): string | undefined;
+export declare function benchmarkAgentContextCommand(dataset: string, options: {
+    profile?: string;
+    repo?: string;
+    repoAlias?: string;
+    targetPath?: string;
+    reportDir?: string;
+    extensions?: string;
+    scopeManifest?: string;
+    scopePrefix?: string[];
+    skipAnalyze?: boolean;
+}, deps?: {
+    loadDataset?: (root: string) => Promise<AgentContextDataset>;
+    runBenchmark?: typeof runAgentContextBenchmark;
+    writeReports?: typeof writeAgentContextReports;
+    writeLine?: (line: string) => void;
+    analyze?: typeof runAnalyze;
+}): Promise<import("../benchmark/agent-context/runner.js").AgentContextBenchmarkResult>;

package/dist/cli/benchmark-agent-context.js

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import { runAnalyze } from '../benchmark/analyze-runner.js';
+import { loadAgentContextDataset } from '../benchmark/agent-context/io.js';
+import { writeAgentContextReports } from '../benchmark/agent-context/report.js';
+import { runAgentContextBenchmark } from '../benchmark/agent-context/runner.js';
+export function resolveAgentContextProfile(profile) {
+    if (profile === 'quick') {
+        return { maxScenarios: 1 };
+    }
+    return { maxScenarios: Number.MAX_SAFE_INTEGER };
+}
+export function resolveAgentContextRepoName(options) {
+    return options.repo || options.repoAlias || (options.targetPath ? path.basename(path.resolve(options.targetPath)) : undefined);
+}
+export async function benchmarkAgentContextCommand(dataset, options, deps) {
+    const loadDataset = deps?.loadDataset || loadAgentContextDataset;
+    const runBenchmark = deps?.runBenchmark || runAgentContextBenchmark;
+    const writeReports = deps?.writeReports || writeAgentContextReports;
+    const writeLine = deps?.writeLine || ((line) => process.stderr.write(`${line}\n`));
+    const analyze = deps?.analyze || runAnalyze;
+    const profile = options.profile || 'quick';
+    const profileConfig = resolveAgentContextProfile(profile);
+    const reportDir = path.resolve(options.reportDir || '.gitnexus/benchmark-agent-context');
+    if (!(options.skipAnalyze ?? false)) {
+        if (!options.targetPath) {
+            throw new Error('targetPath is required unless skipAnalyze is true');
+        }
+        const analyzePath = path.resolve(options.targetPath);
+        const analyzeOptions = {
+            extensions: options.extensions || '.cs',
+            repoAlias: options.repoAlias,
+            scopeManifest: options.scopeManifest,
+            scopePrefix: options.scopePrefix,
+        };
+        try {
+            await analyze(analyzePath, analyzeOptions);
+        }
+        catch (error) {
+            const message = String(error?.message || error);
+            if (!message.includes('analyze failed: null')) {
+                throw error;
+            }
+            // Retry once for transient child-process exits (observed as code=null).
+            await analyze(analyzePath, analyzeOptions);
+        }
+    }
+    const datasetRoot = path.resolve(dataset);
+    const ds = await loadDataset(datasetRoot);
+    const result = await runBenchmark(ds, {
+        repo: resolveAgentContextRepoName(options),
+        reportDir,
+        profile: profileConfig,
+    });
+    await writeReports(reportDir, result);
+    writeLine(`${result.pass ? 'PASS' : 'FAIL'}`);
+    writeLine(`Report: ${result.reportDir}`);
+    if (!result.pass) {
+        process.exitCode = 1;
+    }
+    return result;
+}

package/dist/cli/benchmark-agent-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/benchmark-agent-context.test.js

@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { benchmarkAgentContextCommand, resolveAgentContextProfile } from './benchmark-agent-context.js';
+test('benchmark-agent-context resolves profile and runs runner', async () => {
+    const quick = resolveAgentContextProfile('quick');
+    const full = resolveAgentContextProfile('full');
+    assert.equal(quick.maxScenarios, 1);
+    assert.equal(full.maxScenarios, Number.MAX_SAFE_INTEGER);
+    const calls = [];
+    const output = [];
+    await benchmarkAgentContextCommand('../benchmarks/agent-context/neonspark-refactor-v1', {
+        profile: 'quick',
+        repoAlias: 'neonspark-v1-subset',
+        reportDir: '.gitnexus/benchmark-agent-context-test',
+        skipAnalyze: true,
+    }, {
+        loadDataset: async () => ({
+            thresholds: {
+                coverage: { minPerScenario: 0.5, suiteAvgMin: 0.5 },
+                efficiency: { maxToolCallsPerScenario: 4, suiteAvgMax: 4 },
+            },
+            scenarios: [],
+        }),
+        runBenchmark: async (_dataset, options) => {
+            calls.push({ repo: options.repo, profile: options.profile });
+            return {
+                pass: true,
+                failures: [],
+                reportDir: options.reportDir || '.gitnexus/benchmark-agent-context-test',
+                metrics: { avgCoverage: 1, avgToolCalls: 1, mandatoryTargetPassRate: 1 },
+                scenarios: [],
+            };
+        },
+        writeReports: async () => { },
+        writeLine: (line) => output.push(line),
+        analyze: async () => ({ stdout: '', stderr: '' }),
+    });
+    assert.equal(calls[0].repo, 'neonspark-v1-subset');
+    assert.equal(calls[0].profile.maxScenarios, 1);
+    assert.ok(output.some((line) => line.includes('Report:')));
+});
+test('benchmark-agent-context retries analyze once on null exit failure', async () => {
+    let analyzeCalls = 0;
+    let runCalls = 0;
+    await benchmarkAgentContextCommand('../benchmarks/agent-context/neonspark-refactor-v1', {
+        profile: 'quick',
+        repoAlias: 'neonspark-v1-subset',
+        reportDir: '.gitnexus/benchmark-agent-context-test',
+        targetPath: '/tmp/neonspark',
+    }, {
+        loadDataset: async () => ({
+            thresholds: {
+                coverage: { minPerScenario: 0.5, suiteAvgMin: 0.5 },
+                efficiency: { maxToolCallsPerScenario: 4, suiteAvgMax: 4 },
+            },
+            scenarios: [],
+        }),
+        runBenchmark: async () => {
+            runCalls += 1;
+            return {
+                pass: true,
+                failures: [],
+                reportDir: '.gitnexus/benchmark-agent-context-test',
+                metrics: { avgCoverage: 1, avgToolCalls: 1, mandatoryTargetPassRate: 1 },
+                scenarios: [],
+            };
+        },
+        writeReports: async () => { },
+        writeLine: () => { },
+        analyze: async () => {
+            analyzeCalls += 1;
+            if (analyzeCalls === 1) {
+                throw new Error('analyze failed: null');
+            }
+            return { stdout: '', stderr: '' };
+        },
+    });
+    assert.equal(analyzeCalls, 2);
+    assert.equal(runCalls, 1);
+});

package/dist/cli/benchmark-unity.d.ts

@@ -0,0 +1,15 @@
+export declare function resolveProfileConfig(profile: string): {
+    maxSymbols: number;
+    maxTasks: number;
+};
+export declare function benchmarkUnityCommand(dataset: string, options: {
+    profile?: string;
+    repo?: string;
+    repoAlias?: string;
+    targetPath?: string;
+    reportDir?: string;
+    extensions?: string;
+    scopeManifest?: string;
+    scopePrefix?: string[];
+    skipAnalyze?: boolean;
+}): Promise<void>;

package/dist/cli/benchmark-unity.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { loadBenchmarkDataset } from '../benchmark/io.js';
+import { runBenchmark } from '../benchmark/runner.js';
+export function resolveProfileConfig(profile) {
+    if (profile === 'quick') {
+        return { maxSymbols: 10, maxTasks: 5 };
+    }
+    return { maxSymbols: Number.MAX_SAFE_INTEGER, maxTasks: Number.MAX_SAFE_INTEGER };
+}
+export async function benchmarkUnityCommand(dataset, options) {
+    const profile = options.profile || 'quick';
+    const profileConfig = resolveProfileConfig(profile);
+    const datasetRoot = path.resolve(dataset);
+    const ds = await loadBenchmarkDataset(datasetRoot);
+    const result = await runBenchmark(ds, {
+        repo: options.repo,
+        repoAlias: options.repoAlias,
+        targetPath: options.targetPath,
+        profile: profileConfig,
+        reportDir: options.reportDir,
+        extensions: options.extensions || '.cs',
+        scopeManifest: options.scopeManifest,
+        scopePrefix: options.scopePrefix,
+        skipAnalyze: options.skipAnalyze ?? false,
+    });
+    process.stderr.write(`${result.pass ? 'PASS' : 'FAIL'}\n`);
+    process.stderr.write(`Report: ${result.reportDir}\n`);
+    if (!result.pass) {
+        process.exitCode = 1;
+    }
+}

package/dist/cli/benchmark-unity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/benchmark-unity.test.js

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import { resolveProfileConfig } from './benchmark-unity.js';
+test('quick profile uses reduced sample limits', () => {
+    const c = resolveProfileConfig('quick');
+    assert.equal(c.maxSymbols, 10);
+    assert.equal(c.maxTasks, 5);
+});
+test('package scripts include neonspark benchmark commands', async () => {
+    const raw = await fs.readFile('package.json', 'utf-8');
+    const pkg = JSON.parse(raw);
+    const scripts = pkg.scripts || {};
+    assert.ok(scripts['benchmark:neonspark:full']);
+    assert.ok(scripts['benchmark:neonspark:quick']);
+    assert.ok(scripts['benchmark:neonspark:v2:full']);
+    assert.ok(scripts['benchmark:neonspark:v2:quick']);
+});