@vibgrate/cli 2026.717.1 → 2026.720.1

package/dist/{chunk-L42NVMD6.js → chunk-VQLOVQZP.js}

@@ -1,5 +1,5 @@
 import { hashString, langById, shortId, canonicalize, grammarSetVersion, hashBytes, langForExtension, setGrammarsOverride, parseSource } from './chunk-VFO5UDAT.js';
-import { writeTextFile, pathExists, readJsonFile, loadConfig, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem, VERSION } from './chunk-M62BGJMK.js';
+import { writeTextFile, pathExists, readJsonFile, loadConfig, computeUpgradeImpact, getChangelogSignals, gitHistoryAvailable, buildVersionTimelines, findPackageTimeline, severityRank, projectTypeToVulnEcosystem, VERSION } from './chunk-AJDUMRVI.js';
 import * as fs19 from 'fs';
 import { spawnSync, execFileSync } from 'child_process';
 import * as path19 from 'path';
@@ -3445,6 +3445,7 @@ function readUsage(root, days, now) {
   const byTool = /* @__PURE__ */ new Map();
   const bySource = /* @__PURE__ */ new Map();
   const byClient = /* @__PURE__ */ new Map();
+  const msByTool = /* @__PURE__ */ new Map();
   const bump2 = (m, key, outcome) => {
     const row = m.get(key) ?? { complete: 0, partial: 0, miss: 0 };
     row[outcome]++;
@@ -3460,18 +3461,28 @@ function readUsage(root, days, now) {
         bump2(byTool, e.tool, outcome);
         bump2(bySource, e.source ?? "mcp", outcome);
         bump2(byClient, e.client ?? "unknown", outcome);
+        if (typeof e.ms === "number" && e.ms >= 0) {
+          const timing = msByTool.get(e.tool) ?? { sum: 0, n: 0 };
+          timing.sum += e.ms;
+          timing.n++;
+          msByTool.set(e.tool, timing);
+        }
       } catch {
       }
     }
   }
-  const commands = toDimensionStats(byTool).map((d) => ({
-    tool: d.key,
-    calls: d.calls,
-    complete: d.complete,
-    partial: d.partial,
-    miss: d.miss,
-    successPct: d.successPct
-  }));
+  const commands = toDimensionStats(byTool).map((d) => {
+    const timing = msByTool.get(d.key);
+    return {
+      tool: d.key,
+      calls: d.calls,
+      complete: d.complete,
+      partial: d.partial,
+      miss: d.miss,
+      successPct: d.successPct,
+      avgMs: timing && timing.n > 0 ? Math.round(timing.sum / timing.n) : null
+    };
+  });
   const totals = commands.reduce(
     (t, c) => ({
       calls: t.calls + c.calls,
@@ -6596,11 +6607,14 @@ var TOOLS = [
   },
   {
     name: "resolve_library",
-    description: "Resolve a library to its canonical id and the version YOUR project uses (drift-annotated).",
+    description: "Resolve a library to its canonical id and the version YOUR project uses (drift-annotated). Call once per library and reuse the returned targetId for every library_docs follow-up \u2014 never guess an id.",
     // Canonical §4: `query` (+ optional `context_project`). `name` kept as a back-compat alias.
     inputSchema: obj(
       {
-        query: { type: "string", description: "library name or query" },
+        query: {
+          type: "string",
+          description: 'the package name as written in the dependency file. Good: "react-hook-form". Bad: "forms"'
+        },
         name: { type: "string" },
         context_project: { type: "string" }
       },
@@ -6645,17 +6659,22 @@ var TOOLS = [
   },
   {
     name: "library_docs",
-    description: "Version-correct usage docs for a library, sliced to a token budget.",
+    description: "Version-correct usage docs for a library, sliced to a token budget \u2014 official content matched to the version this project has installed, not web-search results. Ask a focused question via query; one call usually answers. After 2 calls without the section you need, stop and read the package source under node_modules instead of searching again.",
     // Canonical §4: `targetId`/`query`, `verbosity`, `max_tokens`. `name`/`tokens` kept as aliases.
     inputSchema: obj(
       {
-        targetId: { type: "string", description: "id from resolve_library" },
-        query: { type: "string", description: "library name or query" },
+        targetId: { type: "string", description: "id from resolve_library (preferred over query)" },
+        query: {
+          type: "string",
+          description: 'the library plus the specific need. Good: "zod refine custom error message". Bad: "zod" or "docs"'
+        },
         name: { type: "string" },
         context_project: { type: "string" },
         verbosity: { type: "string", enum: ["concise", "balanced", "exhaustive"] },
-        max_tokens: { type: "number", description: "token budget" },
-        tokens: { type: "number" },
+        // Tolerant on purpose: models often send budgets as strings — the
+        // handler coerces, so don't fail validation over "4000" vs 4000.
+        max_tokens: { type: ["number", "string"], description: "token budget (a numeric string is accepted)" },
+        tokens: { type: ["number", "string"] },
         enterprise_strict: { type: "boolean" },
         follow_up: { type: "boolean" }
       },
@@ -6870,7 +6889,7 @@ var GraphSource = class {
   }
 };
 function createServer(source, opts = {}) {
-  const { savings = false, shareStats = false, local = false, dedup = false } = opts;
+  const { savings = false, shareStats = false, local = false, dedup = false, stats } = opts;
   const record = savings || shareStats;
   const root = path19.dirname(path19.dirname(source.graphPath));
   const seen = /* @__PURE__ */ new Set();
@@ -6881,7 +6900,7 @@ function createServer(source, opts = {}) {
       // Routing guidance once at the server level (hosts that surface
       // `instructions` get it at zero per-step schema cost): the flashlight
       // vs the map.
-      instructions: 'vg is a code map. Use search_symbols to find a known name or literal string fast \u2014 a multi-word/quoted phrase runs a complete literal sweep and reports totalTextMatches, so reach for it instead of grep even for plain-string "find every occurrence" lookups. Use orient/query_graph for meaning: symptoms, relationships, and what-breaks-if. Responses are concise by default; pass response_format:"detailed" only when a node proves load-bearing. Navigate as little as possible: one good search/query usually locates the code. As soon as you have the file and line, read that file and make the edit \u2014 do not call further graph tools unless the edit fails or the match was wrong.'
+      instructions: 'vg is a code map. Use search_symbols to find a known name or literal string fast \u2014 a multi-word/quoted phrase runs a complete literal sweep and reports totalTextMatches, so reach for it instead of grep even for plain-string "find every occurrence" lookups. Use orient/query_graph for meaning: symptoms, relationships, and what-breaks-if. Responses are concise by default; pass response_format:"detailed" only when a node proves load-bearing. Navigate as little as possible: one good search/query usually locates the code. As soon as you have the file and line, read that file and make the edit \u2014 do not call further graph tools unless the edit fails or the match was wrong. For how-do-I-use-this-library questions call resolve_library once, then library_docs with the returned targetId and a focused query: the docs are official and matched to the version THIS project has installed (drift-annotated) \u2014 prefer them over web search or training-data recall when they conflict. Skip them for language built-ins or APIs already shown in context. If two library_docs calls have not surfaced the section you need, read the package source under node_modules instead of searching again.'
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -6905,12 +6924,23 @@ function createServer(source, opts = {}) {
         "no code map found. Run `vg` in the project to build .vibgrate/graph.json, then retry."
       );
     }
+    const startedAt = Date.now();
     try {
       const args = request.params.arguments ?? {};
       const result = await tool.handler(graph, args, { root, local, dedup, seen });
-      if (record) recordUsage(root, tool.name, result, detectClient(server));
+      const ms = Date.now() - startedAt;
+      stats?.record({ ...measureCall(tool.name, result), client: sanitizeClient(detectClient(server)), ms });
+      if (record) recordUsage(root, tool.name, result, detectClient(server), ms);
       return renderToolResult(result);
     } catch (err) {
+      stats?.record({
+        tool: tool.name,
+        client: sanitizeClient(detectClient(server)),
+        outcome: "miss",
+        ms: Date.now() - startedAt,
+        vgTokens: 0,
+        baselineTokens: 0
+      });
       return errorResult(`tool "${tool.name}" failed: ${err.message}`);
     }
   });
@@ -6928,7 +6958,14 @@ function sleep(ms) {
     timer.unref?.();
   });
 }
-function recordUsage(root, tool, result, client) {
+function recordUsage(root, tool, result, client, ms) {
+  recordSaving(
+    root,
+    { ...measureCall(tool, result), source: "mcp", client: sanitizeClient(client), ...ms !== void 0 ? { ms } : {} },
+    Date.now()
+  );
+}
+function measureCall(tool, result) {
   const outcome = classifyOutcome(result);
   let vgTokens = 0;
   let baselineTokens = 0;
@@ -6936,11 +6973,7 @@ function recordUsage(root, tool, result, client) {
     vgTokens = countTokens(renderedText(renderToolResult(result)));
     baselineTokens = referencedFiles(result).size * PER_FILE_TOKENS;
   }
-  recordSaving(
-    root,
-    { tool, outcome, vgTokens, baselineTokens, source: "mcp", client: sanitizeClient(client) },
-    Date.now()
-  );
+  return { tool, outcome, vgTokens, baselineTokens };
 }
 function detectClient(server) {
   try {
@@ -7043,6 +7076,21 @@ tools improved):
 - **Version-correct docs:** \`vg lib <name>\` returns drift-annotated, version-
   specific usage docs for a library \u2014 inject these instead of guessing an API.
 
+### Library-docs discipline
+
+When a task needs a library's API, use the docs tools before web search or
+training-data recall \u2014 they are official content matched to the version **this
+project has installed**, and they win when the two conflict.
+
+- **Workflow:** \`resolve_library\` once per library, then \`library_docs\` with the
+  returned \`targetId\` and a focused query (good: "zod refine custom error
+  message"; bad: "zod"). Never guess a targetId.
+- **Budget:** at most **3 docs calls per task**. If 2 \`library_docs\` calls have
+  not surfaced the section you need, read the package source under
+  \`node_modules\` instead of searching again.
+- **Skip the docs tools** for language built-ins, stable well-known syntax, or
+  an API already shown in the current context \u2014 they add nothing there.
+
 ## Keep it fresh
 
 The map keeps itself fresh: \`vg ask\` and the MCP tools detect changed files
@@ -7541,6 +7589,6 @@ function spdx(ctx) {
   return JSON.stringify(doc, null, 2) + "\n";
 }
 
-export { ASSISTANTS, CLI_TOOL_ALIASES, CliError, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, countTokens, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectAssistants, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, epistemicBreakdown, exportGraph, fetchHostedDocsCached, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, identifierParts, impactOf, indexFor, ingestHostForRegionId, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, readUsage, recordCliCall, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveLimits, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeNavigationConfig, writeSnapshot, writeStoredCredentials };
-//# sourceMappingURL=chunk-L42NVMD6.js.map
-//# sourceMappingURL=chunk-L42NVMD6.js.map
+export { ASSISTANTS, CLI_TOOL_ALIASES, CliError, DEFAULT_RATE_LABEL, DEFAULT_RATE_PER_M, ECOSYSTEMS, ExitCode, FREE_PACK, GraphIndex, GraphSource, NPX_INVOCATION, ResourceLimitError, SAVINGS_TOOLS, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, addLibrary, analyze, applyCoverage, applyStaticTestLinkage, assessDocQuality, assistantById, availableRegionIds, buildFacts, buildGraph, buildModuleResolver, cacheDir, catalogPath, clearModelCache, clearStoredCredentials, cosine, countPending, countTokens, coveringTests, createServer, createWorkspaceDsn, credentialsPath, dashHostForIngestHost, decodeScipIndex, defaultGraphPath, detectAssistants, detectRunner, detectServeLaunch, discover, discoverModels, driftCount, driftFor, dsnCommand, embeddingsCached, enrichOnline, ensureGitignored, epistemicBreakdown, exportGraph, fetchHostedDocsCached, findGitRoot, findNodes, formatForExt, getNodeEmbeddings, gitignoreEntryForCredentials, groundGraph, hasDrift, homeCredentialsPath, hostedBase, identifierParts, impactOf, indexFor, ingestHostForRegionId, installAssistant, inventory, isModelReady, isTestFile, libDir, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, localApiSurface, localPackageDocs, modelCacheInfo, nodeById, nodeEmbedText, parseDsn, parseGraph, parseJsonc, probeFreshness, projectCredentialsPath, publishPrivateLibrary, pushCommand, queryGraph, queryGraphSemantic, readDoc, readSavings, readScanArtifact, readStoredCredentials, readUsage, recordCliCall, recordSaving, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveCliInvocation, resolveDsn, resolveEmbedModel, resolveIngestHost, resolveLib, resolveLimits, resolveOne, resolveVersion, saveCatalog, savingsRecorded, scipEdges, selectForBudget, serializeGraph, serveStdio, shortestPath, stableStringify, symbolsFromApi, testsToRun, unavailableMessage, uninstallAssistant, uploadScanArtifact, usageError, verifyDeterminism, vibgrateDir, writeArtifacts, writeNavigationConfig, writeSnapshot, writeStoredCredentials };
+//# sourceMappingURL=chunk-VQLOVQZP.js.map
+//# sourceMappingURL=chunk-VQLOVQZP.js.map