@vibgrate/cli 2026.703.7 → 2026.704.3

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { resolveDsn, resolveIngestHost, dashHostForIngestHost, resolveCliInvocation, availableRegionIds, createWorkspaceDsn, writeStoredCredentials, credentialsPath, findGitRoot, ensureGitignored, gitignoreEntryForCredentials, clearStoredCredentials, inventory, uploadScanArtifact, dsnCommand, pushCommand, ExitCode, CliError, NPX_INVOCATION, verifyDeterminism, refreshIfStale, driftCount, embeddingsCached, resolveEmbedModel, loadEmbedder, getNodeEmbeddings, queryGraphSemantic, queryGraph, unavailableMessage, countPending, resolveOne, GraphIndex, shortestPath, renderReport, impactOf, testsToRun, detectRunner, defaultGraphPath, serveStdio, ASSISTANTS, usageError, loadGraph, detectServeLaunch, installAssistant, uninstallAssistant, buildGraph, serializeGraph, coveringTests, FREE_PACK, readScanArtifact, enrichOnline, ECOSYSTEMS, discoverModels, readSavings, exportGraph, catalogPath, libDir, stableStringify, writeArtifacts, writeSnapshot, UsageError, cacheDir, probeFreshness, discover, vibgrateDir, modelCacheInfo, clearModelCache, GraphSource, createServer, assistantById, loadCatalog, driftFor, addLibrary, parseDsn as parseDsn$1, publishPrivateLibrary, resolveLib, libId, resolveVersion, readDoc, localPackageDocs, localApiSurface, assessDocQuality, symbolsFromApi, fetchHostedDocs, selectForBudget, formatForExt, renderHtml, isModelReady } from './chunk-WGXDYBAN.js';
+import { resolveDsn, resolveIngestHost, dashHostForIngestHost, resolveCliInvocation, availableRegionIds, createWorkspaceDsn, writeStoredCredentials, credentialsPath, findGitRoot, ensureGitignored, gitignoreEntryForCredentials, clearStoredCredentials, inventory, uploadScanArtifact, dsnCommand, pushCommand, ExitCode, CliError, NPX_INVOCATION, verifyDeterminism, refreshIfStale, driftCount, embeddingsCached, resolveEmbedModel, loadEmbedder, getNodeEmbeddings, queryGraphSemantic, queryGraph, unavailableMessage, countPending, resolveOne, GraphIndex, shortestPath, renderReport, impactOf, testsToRun, detectRunner, defaultGraphPath, serveStdio, ASSISTANTS, usageError, loadGraph, detectServeLaunch, installAssistant, writeNavigationConfig, uninstallAssistant, coveringTests, FREE_PACK, readScanArtifact, enrichOnline, ECOSYSTEMS, discoverModels, readSavings, exportGraph, catalogPath, libDir, stableStringify, buildGraph, writeArtifacts, writeSnapshot, UsageError, ResourceLimitError, cacheDir, probeFreshness, discover, vibgrateDir, modelCacheInfo, clearModelCache, GraphSource, createServer, assistantById, serializeGraph, resolveLimits, loadCatalog, driftFor, addLibrary, parseDsn as parseDsn$1, publishPrivateLibrary, resolveLib, libId, resolveVersion, readDoc, localPackageDocs, localApiSurface, assessDocQuality, symbolsFromApi, fetchHostedDocs, selectForBudget, formatForExt, renderHtml, isModelReady } from './chunk-JL7FIC6W.js';
 import { resolvedGrammarFiles, grammarSetVersion } from './chunk-X5YT263H.js';
-import { loadAdvancedScanHook, baselineCommand } from './chunk-ZNVLRKWK.js';
-import { ensureDir, pathExists, writeDefaultConfig, parseDsn, detectVcs, computeRepoFingerprint, resolveRepositoryName, fetchScanPreflight, runCoreScan, VERSION, readJsonFile, writeTextFile, prepareCompressedUpload, titleBox, driftBar, gitHistoryAvailable, buildVersionTimelines, findPackageAnyEcosystem, normalizeConstraint, findVersionCrossings, versionSatisfies, brandProgressBar } from './chunk-QWS7M7DG.js';
+import { loadAdvancedScanHook, baselineCommand } from './chunk-WHQRV66O.js';
+import { ensureDir, pathExists, writeDefaultConfig, parseDsn, detectVcs, computeRepoFingerprint, resolveRepositoryName, fetchScanPreflight, runCoreScan, VERSION, readJsonFile, writeTextFile, prepareCompressedUpload, titleBox, driftBar, gitHistoryAvailable, buildVersionTimelines, findPackageAnyEcosystem, normalizeConstraint, findVersionCrossings, versionSatisfies, brandProgressBar } from './chunk-YN5OGRWU.js';
 import './chunk-RXP66R2E.js';
-import { pathExists as pathExists$1, parseExcludePatterns } from './chunk-UPPWLMVD.js';
+import { pathExists as pathExists$1, parseExcludePatterns } from './chunk-GI6W53LM.js';
 import * as fs4 from 'fs';
 import fs4__default, { realpathSync } from 'fs';
 import * as path9 from 'path';
@@ -156,6 +156,7 @@ async function runBuild(paths, opts, global) {
   } catch (err) {
     bar?.done();
     if (err instanceof UsageError) throw usageError(err.message);
+    if (err instanceof ResourceLimitError) throw new CliError(err.message, ExitCode.ERROR);
     throw err;
   }
   bar?.done();
@@ -192,7 +193,8 @@ async function runBuild(paths, opts, global) {
       scip: result.scip,
       artifacts: written,
       corpusHash: result.graph.provenance.corpusHash,
-      timingMs: result.timing.totalMs
+      timingMs: result.timing.totalMs,
+      warnings: result.warnings
     });
     return;
   }
@@ -226,18 +228,20 @@ async function runBuild(paths, opts, global) {
 function maybeWarmEmbeddings(root, graph, global, warm) {
   if (!warm || global.json || global.quiet || global.local) return;
   if (!process.stdout.isTTY && !process.stderr.isTTY) return;
-  const modelId = resolveEmbedModel();
-  if (!isModelReady(modelId)) return;
-  if (countPending(graph, root, modelId) === 0) return;
   const cli = process.argv[1];
   if (!cli) return;
+  const modelId = resolveEmbedModel();
+  const ready = isModelReady(modelId);
+  if (ready && countPending(graph, root, modelId) === 0) return;
+  const args = ready ? [cli, "embed", "-C", root, "--bg"] : [cli, "embed", "-C", root, "--bg", "--download"];
   try {
-    const child = spawn(process.execPath, [cli, "embed", "-C", root, "--bg"], {
-      detached: true,
-      stdio: "ignore"
-    });
+    const child = spawn(process.execPath, args, { detached: true, stdio: "ignore" });
     child.unref();
-    info(c.dim("  warming the semantic index in the background \u2014 `vg ask` will be instant"));
+    info(
+      c.dim(
+        ready ? "  warming the semantic index in the background \u2014 `vg ask` will be instant" : "  downloading the semantic model in the background (once) \u2014 `vg ask`/`vg serve` will be instant; disable with --no-warm"
+      )
+    );
   } catch {
   }
 }
@@ -454,7 +458,7 @@ function mb(bytes) {
   return `${Math.round(bytes / (1024 * 1024))} MB`;
 }
 function registerEmbed(program) {
-  const cmd = program.command("embed").description("precompute the semantic index for instant `vg ask` (or --where / --clear)").option("--where", "show where the model is cached, and its size").option("--clear", "remove the downloaded model from the shared cache").addOption(new Option("--bg").hideHelp()).action(async function(opts) {
+  const cmd = program.command("embed").description("precompute the semantic index for instant `vg ask` (or --where / --clear)").option("--where", "show where the model is cached, and its size").option("--clear", "remove the downloaded model from the shared cache").addOption(new Option("--bg").hideHelp()).addOption(new Option("--download").hideHelp()).action(async function(opts) {
     const global = readGlobal(this);
     const modelId = resolveEmbedModel();
     if (opts.where) return showWhere(rootOf(global), modelId, global.json);
@@ -475,8 +479,10 @@ function registerEmbed(program) {
     let reason;
     const embedder = await loadEmbedder({
       local: global.local,
-      noDownload: bg,
-      // background warm-up never downloads
+      // Background warm-ups skip the download unless explicitly asked to fetch
+      // (`--bg --download`, spawned by `vg build` so the model is ready by the
+      // time `vg serve`/`vg ask` needs it).
+      noDownload: bg && opts.download !== true,
       showDownloadProgress: !bg,
       onUnavailable: (r) => reason = r
     });
@@ -910,8 +916,9 @@ function registerInstall(program) {
     const smallRepo = graph !== null && fileCount > 0 && fileCount < SMALL_REPO_FILES;
     const launch = detectServeLaunch();
     const results = targets.map((a) => ({ id: a.id, ...installAssistant(a, { root, hook: opts.hook, smallRepo, launch }) }));
+    const navConfig = writeNavigationConfig(root);
     if (global.json) {
-      json({ root, smallRepo, launch: { command: launch.command, args: launch.args, note: launch.note ?? null }, results });
+      json({ root, smallRepo, navConfig, launch: { command: launch.command, args: launch.args, note: launch.note ?? null }, results });
       return;
     }
     for (const r of results) {
@@ -919,6 +926,7 @@ function registerInstall(program) {
     }
     if (launch.note && results.some((r) => r.note)) info(`${c.yellow("!")} ${launch.note}`);
     if (smallRepo) info(c.dim(`  note: small repo (${fileCount} files) \u2014 nudge says searching is fine; vg is still used for impact/tests`));
+    info(c.dim(`  wrote ${navConfig} \u2014 deferred-loading config for Claude-API agents (lower per-step token cost)`));
     info(c.dim("  run `vg serve` is wired via MCP; build the map with `vg` if you have not yet"));
   });
   applyGlobalOptions(install);
@@ -1059,52 +1067,103 @@ function escapeRe(s) {
 }
 var PIN = "2020-01-01T00:00:00.000Z";
 function registerBenchmark(program) {
-  const cmd = program.command("benchmark").description("reproducible build + token-reduction benchmark (honest estimates)").option("--budget <n>", "token budget for vg answers", "2000").action(async function(opts) {
+  const cmd = program.command("benchmark").description("reproducible build + memory + token-reduction benchmark (honest estimates)").option("--budget <n>", "token budget for vg answers", "2000").action(async function(opts) {
     const global = readGlobal(this);
     const root = rootOf(global);
     const budget = Number(opts.budget) || 2e3;
-    const t0 = now();
-    const cold = await buildGraph({ root, generatedAt: PIN, noCache: true });
-    const coldMs = now() - t0;
-    const t1 = now();
-    const warm = await buildGraph({ root, generatedAt: PIN });
-    const warmMs = now() - t1;
-    const a = serializeGraph(cold.graph);
-    const b = serializeGraph((await buildGraph({ root, generatedAt: PIN, noCache: true })).graph);
-    const deterministic = a === b;
-    const questions = deriveQuestions(cold.graph);
-    const fileSizes = fileSizeIndex(root);
-    const perQuestion = questions.map((q) => {
-      const vgTokens = queryGraph(cold.graph, q, { budget }).tokensEstimate;
-      const baseTokens = grepBaselineTokens(q, fileSizes);
-      return { question: q, vgTokens, baselineTokens: baseTokens, ratio: baseTokens > 0 ? round(baseTokens / Math.max(vgTokens, 1)) : 1 };
-    });
-    const totalVg = perQuestion.reduce((s, x) => s + x.vgTokens, 0);
-    const totalBase = perQuestion.reduce((s, x) => s + x.baselineTokens, 0);
-    const aggregateRatio = totalVg > 0 ? round(totalBase / totalVg) : 0;
-    const result = {
-      repo: { files: cold.totalFiles, nodes: cold.graph.meta.counts.nodes, edges: cold.graph.meta.counts.edges },
-      build: { coldMs: round(coldMs), incrementalMs: round(warmMs), reusedOnWarm: warm.reused },
-      determinism: { byteIdentical: deterministic },
-      tokenReduction: { questions: perQuestion, aggregateRatio, note: "estimates (~4 chars/token); scales with repo size" }
-    };
+    const result = await runBenchmarkSuite(root, budget);
     if (global.json) {
       json(result);
       return;
     }
-    info(`${c.cyan("vg benchmark")} \xB7 ${result.repo.files} files \xB7 ${result.repo.nodes} nodes`);
-    info(`  build   cold ${result.build.coldMs.toFixed(0)}ms \xB7 incremental ${result.build.incrementalMs.toFixed(0)}ms (reused ${warm.reused})`);
-    info(`  determinism  ${deterministic ? c.green("byte-identical \u2713") : c.red("NON-DETERMINISTIC \u2717")}`);
-    if (perQuestion.length) {
+    const { repo, build, throughput, memory, determinism, tokenReduction } = result;
+    info(`${c.cyan("vg benchmark")} \xB7 ${repo.files} files \xB7 ${repo.nodes} nodes`);
+    info(`  build   cold ${build.coldMs.toFixed(0)}ms \xB7 incremental ${build.incrementalMs.toFixed(0)}ms (reused ${build.reusedOnWarm})`);
+    info(`  speed   ${throughput.filesPerSec.toFixed(0)} files/s \xB7 ${throughput.mbPerSec.toFixed(1)} MB/s (cold, ${mb2(throughput.corpusBytes).toFixed(1)} MB corpus)`);
+    info(
+      `  memory  peak rss ${memory.peakRssMb.toFixed(0)} MB (baseline ${memory.baselineRssMb.toFixed(0)} MB) \xB7 peak heap ${memory.peakHeapMb.toFixed(0)} MB \xB7 graph retains ~${memory.retainedHeapMb.toFixed(0)} MB ${c.dim("(approximate)")}`
+    );
+    info(`  graph   ${mb2(memory.graphJsonBytes).toFixed(1)} MB serialized \xB7 ${memory.bytesPerNode.toFixed(0)} B/node`);
+    info(`  determinism  ${determinism.byteIdentical ? c.green("byte-identical \u2713") : c.red("NON-DETERMINISTIC \u2717")}`);
+    if (tokenReduction.questions.length) {
       info(`  token reduction vs grep/read baseline (${c.dim("estimates")}):`);
-      for (const q of perQuestion) {
+      for (const q of tokenReduction.questions) {
         info(`    ${pad2(`${q.ratio.toFixed(1)}\xD7`, 6)} ${c.dim(`vg ${q.vgTokens} vs ~${q.baselineTokens}`)}  "${q.question}"`);
       }
-      info(`  ${c.bold(`aggregate \u2248 ${aggregateRatio.toFixed(1)}\xD7 fewer tokens`)} ${c.dim("(honest estimate, scales with repo size)")}`);
+      info(`  ${c.bold(`aggregate \u2248 ${tokenReduction.aggregateRatio.toFixed(1)}\xD7 fewer tokens`)} ${c.dim("(honest estimate, scales with repo size)")}`);
     }
   });
   applyGlobalOptions(cmd);
 }
+async function runBenchmarkSuite(root, budget) {
+  const baseline = process.memoryUsage();
+  const sampler = startMemorySampler();
+  const t0 = now();
+  const cold = await buildGraph({ root, generatedAt: PIN, noCache: true });
+  const coldMs = now() - t0;
+  const t1 = now();
+  const warm = await buildGraph({ root, generatedAt: PIN });
+  const warmMs = now() - t1;
+  const a = serializeGraph(cold.graph);
+  const b = serializeGraph((await buildGraph({ root, generatedAt: PIN, noCache: true })).graph);
+  const peak = sampler.stop();
+  const deterministic = a === b;
+  const after = process.memoryUsage();
+  const corpusBytes = cold.fileStats.reduce((s, f) => s + f.size, 0);
+  const graphJsonBytes = Buffer.byteLength(a, "utf8");
+  const nodes = cold.graph.meta.counts.nodes;
+  const questions = deriveQuestions(cold.graph);
+  const fileSizes = fileSizeIndex(root);
+  const perQuestion = questions.map((q) => {
+    const vgTokens = queryGraph(cold.graph, q, { budget }).tokensEstimate;
+    const baseTokens = grepBaselineTokens(q, fileSizes);
+    return { question: q, vgTokens, baselineTokens: baseTokens, ratio: baseTokens > 0 ? round(baseTokens / Math.max(vgTokens, 1)) : 1 };
+  });
+  const totalVg = perQuestion.reduce((s, x) => s + x.vgTokens, 0);
+  const totalBase = perQuestion.reduce((s, x) => s + x.baselineTokens, 0);
+  const aggregateRatio = totalVg > 0 ? round(totalBase / totalVg) : 0;
+  return {
+    repo: { files: cold.totalFiles, nodes, edges: cold.graph.meta.counts.edges },
+    build: { coldMs: round(coldMs), incrementalMs: round(warmMs), reusedOnWarm: warm.reused },
+    throughput: {
+      corpusBytes,
+      filesPerSec: coldMs > 0 ? round(cold.totalFiles / coldMs * 1e3) : 0,
+      // 6-decimal precision: a small corpus at 3 decimals would round to 0.
+      mbPerSec: coldMs > 0 ? round6(mb2(corpusBytes) / coldMs * 1e3) : 0
+    },
+    memory: {
+      baselineRssMb: round(mb2(baseline.rss)),
+      peakRssMb: round(mb2(Math.max(peak.rss, baseline.rss))),
+      peakHeapMb: round(mb2(Math.max(peak.heapUsed, baseline.heapUsed))),
+      // Heap growth across the run ≈ what the loaded graphs + caches retain.
+      retainedHeapMb: round(Math.max(0, mb2(after.heapUsed - baseline.heapUsed))),
+      graphJsonBytes,
+      bytesPerNode: nodes > 0 ? round(graphJsonBytes / nodes) : 0,
+      note: "sampled at 25ms + phase boundaries; GC timing makes these approximate"
+    },
+    limits: resolveLimits(),
+    determinism: { byteIdentical: deterministic },
+    tokenReduction: { questions: perQuestion, aggregateRatio, note: "estimates (~4 chars/token); scales with repo size" }
+  };
+}
+function startMemorySampler() {
+  let rss = 0;
+  let heapUsed = 0;
+  const sample = () => {
+    const m = process.memoryUsage();
+    if (m.rss > rss) rss = m.rss;
+    if (m.heapUsed > heapUsed) heapUsed = m.heapUsed;
+  };
+  const timer = setInterval(sample, 25);
+  timer.unref?.();
+  return {
+    stop: () => {
+      clearInterval(timer);
+      sample();
+      return { rss, heapUsed };
+    }
+  };
+}
 function deriveQuestions(graph) {
   return graph.nodes.filter((n) => n.kind !== "file" && n.kind !== "external").sort((a, b) => b.importance - a.importance || a.qualifiedName.localeCompare(b.qualifiedName)).slice(0, 5).map((n) => n.name);
 }
@@ -1133,12 +1192,18 @@ function safeSize(abs) {
     return 0;
   }
 }
+function mb2(bytes) {
+  return bytes / (1024 * 1024);
+}
 function now() {
   return Number(process.hrtime.bigint() / 1000n) / 1e3;
 }
 function round(x) {
   return Math.round(x * 1e3) / 1e3;
 }
+function round6(x) {
+  return Math.round(x * 1e6) / 1e6;
+}
 function pad2(s, n) {
   return s.padStart(n, " ");
 }
@@ -1882,7 +1947,7 @@ var initCommand = new Command("init").description("Initialize vibgrate in a proj
     console.log(chalk5.green("\u2714") + ` Created ${chalk5.bold("vibgrate.config.ts")}`);
   }
   if (opts.baseline) {
-    const { runBaseline } = await import('./baseline-HBRBXJHJ.js');
+    const { runBaseline } = await import('./baseline-64EUPWUH.js');
     await runBaseline(rootDir);
   }
   console.log("");