vibe-splain 2.5.0 → 2.6.0

package/dist/commands/install.js

@@ -13,8 +13,9 @@ function expandPath(p) {
     return p;
 }
 const AGENT_CONFIGS = [
-    { name: 'Claude Code', path: '~/.claude/claude_desktop_config.json', format: 'claude' },
-    { name: 'Claude Code (Windows)', path: '%APPDATA%/Claude/claude_desktop_config.json', format: 'claude' },
+    { name: 'Claude Code CLI', path: '~/.claude/settings.json', format: 'claude' },
+    { name: 'Claude Desktop', path: '~/.claude/claude_desktop_config.json', format: 'claude' },
+    { name: 'Claude Desktop (Windows)', path: '%APPDATA%/Claude/claude_desktop_config.json', format: 'claude' },
     { name: 'Gemini CLI', path: '~/.gemini/settings.json', format: 'gemini' },
     { name: 'Cursor', path: '~/.cursor/mcp.json', format: 'cursor' },
     { name: 'Windsurf', path: '~/.codeium/windsurf/mcp_config.json', format: 'cursor' },

package/dist/index.js

@@ -19,8 +19,9 @@ function expandPath(p) {
   return p;
 }
 var AGENT_CONFIGS = [
-  { name: "Claude Code", path: "~/.claude/claude_desktop_config.json", format: "claude" },
-  { name: "Claude Code (Windows)", path: "%APPDATA%/Claude/claude_desktop_config.json", format: "claude" },
+  { name: "Claude Code CLI", path: "~/.claude/settings.json", format: "claude" },
+  { name: "Claude Desktop", path: "~/.claude/claude_desktop_config.json", format: "claude" },
+  { name: "Claude Desktop (Windows)", path: "%APPDATA%/Claude/claude_desktop_config.json", format: "claude" },
   { name: "Gemini CLI", path: "~/.gemini/settings.json", format: "gemini" },
   { name: "Cursor", path: "~/.cursor/mcp.json", format: "cursor" },
   { name: "Windsurf", path: "~/.codeium/windsurf/mcp_config.json", format: "cursor" }
@@ -88,7 +89,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema
 
 // ../brain/dist/scanner.js
 import { extname as extname4 } from "path";
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 
 // ../brain/dist/pipeline/orchestrator.js
 import { join as join8 } from "path";
@@ -989,11 +990,12 @@ function analyzeAst(source, lang, tree) {
   }
   scored.sort((a, b) => b.score - a.score);
   const hotSpans = scored.slice(0, 3).filter((s) => s.bodyLOC >= 4).map((s) => {
-    const raw = source.split("\n").slice(s.node.startPosition.row, s.node.endPosition.row + 1).join("\n");
-    const snippet = stripLeadingComments(raw).slice(0, 2e3);
+    const rawExcerpt = source.split("\n").slice(s.node.startPosition.row, s.node.endPosition.row + 1).join("\n");
+    const snippet = stripLeadingComments(rawExcerpt).slice(0, 2e3);
     return {
       startLine: s.node.startPosition.row + 1,
       endLine: s.node.endPosition.row + 1,
+      rawExcerpt,
       snippet,
       reason: `high complexity: ${s.decisions} decision branches across ${s.bodyLOC} lines`
     };
@@ -2051,7 +2053,7 @@ async function runClassification(projectRoot, inv, res) {
 
 // ../brain/dist/pipeline/scoring.js
 import { join as join7 } from "path";
-import { writeFile as writeFile7, mkdir as mkdir6 } from "fs/promises";
+import { writeFile as writeFile7, mkdir as mkdir6, readFile as readFile6 } from "fs/promises";
 import { createHash } from "crypto";
 function computeSeverity(sideEffectProfile, productDomain, gravity, heat, maxNesting, hasLongFunctions, swallowedCatches, runtimeEntrypoints) {
   let score = 0;
@@ -2113,6 +2115,11 @@ function applyCorrections(file) {
   }
   if (file.canonicalSeverity === 5)
     file.canonicalLoadBearing = true;
+  if (file.riskTypes.includes("registry_bottleneck")) {
+    if (file.canonicalSeverity < 4)
+      file.canonicalSeverity = 4;
+    file.canonicalLoadBearing = true;
+  }
 }
 function inferObservableOutputs(frameworkRole, productDomain, sideEffectProfile) {
   const outputs = [];
@@ -2141,6 +2148,9 @@ function inferObservableOutputs(frameworkRole, productDomain, sideEffectProfile)
     outputs.push("sdk_event_name");
   if (frameworkRole === "hook" || frameworkRole === "store")
     outputs.push("ui_state_transition");
+  if (productDomain === "data_table" && frameworkRole === "provider") {
+    outputs.push("ui_state_transition", "filter_state", "selected_segment");
+  }
   return [...new Set(outputs)];
 }
 function inferPatchRisk(productDomain, riskTypes, sideEffectProfile, importedByCount, loadBearingScore) {
@@ -2157,9 +2167,21 @@ function inferPatchRisk(productDomain, riskTypes, sideEffectProfile, importedByC
       reason: `${productDomain} writes to external state (${external.join(", ") || "database"}). Changes require integration testing.`
     };
   }
+  if (riskTypes.includes("registry_bottleneck")) {
+    return {
+      level: "high",
+      reason: "registry_bottleneck: central dispatch point \u2014 blast radius not measurable by fan-in alone."
+    };
+  }
   if (loadBearingScore >= 5 || importedByCount >= 5) {
     return { level: "medium", reason: `Imported by ${importedByCount} files. Interface changes will cascade.` };
   }
+  if (productDomain === "data_table" && riskTypes.includes("state_machine")) {
+    return {
+      level: "medium",
+      reason: "data_table state machine: controls user-visible workflow state (filters, segments, pagination) \u2014 regression risk not captured by mutation scoring."
+    };
+  }
   return { level: "low", reason: "Locally contained \u2014 limited blast radius." };
 }
 function inferSafePatchStrategy(riskTypes, sideEffectProfile) {
@@ -2306,8 +2328,15 @@ async function runScoring(projectRoot, cr) {
       file: pf.relativePath,
       startLine: span.startLine,
       endLine: span.endLine,
-      rawSourceExcerpt: span.snippet,
-      evidenceHash: createHash("sha256").update(span.snippet).digest("hex").slice(0, 12)
+      rawSourceExcerpt: span.rawExcerpt,
+      evidenceHash: createHash("sha256").update(span.rawExcerpt).digest("hex").slice(0, 12)
+    }));
+    const displayEvidence = pf.hotSpans.map((span) => ({
+      file: pf.relativePath,
+      startLine: span.startLine,
+      endLine: span.endLine,
+      excerpt: span.snippet,
+      isTruncated: span.rawExcerpt.length > 2e3
     }));
     return {
       path: pf.relativePath,
@@ -2332,6 +2361,7 @@ async function runScoring(projectRoot, cr) {
       doNotTouch: inferDoNotTouch(pf.sideEffectProfile, pf.productDomain),
       testProbes: inferTestProbes(pf.writeIntents, observableOutputs),
       rawEvidence,
+      displayEvidence,
       analysisAnnotation: `${pf.frameworkRole} in ${pf.productDomain} domain. fanIn=${pf.gravitySignals.fanIn} cyclomatic=${pf.gravitySignals.cyclomatic} loc=${pf.gravitySignals.loc}`,
       hashes: { fileHash, evidenceHash: rawEvidence.map((e) => e.evidenceHash).join("-") }
     };
@@ -2341,7 +2371,7 @@ async function runScoring(projectRoot, cr) {
   await writeFile7(tmp, JSON.stringify(deltaTargets, null, 2), "utf8");
   const { rename } = await import("fs/promises");
   await rename(tmp, dest);
-  const validationReport = buildValidationReport(store, deltaTargets);
+  const validationReport = await buildValidationReport(store, deltaTargets, projectRoot);
   await writeFile7(join7(dir, "validation_report.json"), JSON.stringify(validationReport, null, 2), "utf8");
   for (const e of validationReport.errors) {
     console.error(`[vibe-splain] VALIDATION ERROR [${e.rule}] ${e.file}: ${e.detail}`);
@@ -2351,7 +2381,7 @@ async function runScoring(projectRoot, cr) {
   }
   return { store, deltaTargets, validationReport };
 }
-function buildValidationReport(store, deltaTargets) {
+async function buildValidationReport(store, deltaTargets, projectRoot) {
   const errors = [];
   const warnings = [];
   let passCount = 0;
@@ -2421,8 +2451,109 @@ function buildValidationReport(store, deltaTargets) {
         detail: `Entrypoints found but domain surface mismatch for ${pf.productDomain}. Found: ${foundPaths}`
       });
     }
+    if (pf.riskTypes.includes("registry_bottleneck")) {
+      if (pf.canonicalSeverity < 4)
+        errors.push({
+          file: pf.relativePath,
+          rule: "registry_bottleneck_severity",
+          detail: "registry_bottleneck file must have severity >= 4",
+          expected: ">=4",
+          actual: String(pf.canonicalSeverity)
+        });
+      if (!pf.canonicalLoadBearing)
+        errors.push({
+          file: pf.relativePath,
+          rule: "registry_bottleneck_load_bearing",
+          detail: "registry_bottleneck file must be load-bearing",
+          expected: "true",
+          actual: "false"
+        });
+      if (delta && delta.patchRisk.level !== "high" && delta.patchRisk.level !== "critical")
+        errors.push({
+          file: pf.relativePath,
+          rule: "registry_bottleneck_patch_risk",
+          detail: "registry_bottleneck file must have patch risk high or critical",
+          expected: "high|critical",
+          actual: delta?.patchRisk.level ?? "unknown"
+        });
+    }
+    if (pf.productDomain === "data_table" && pf.riskTypes.includes("state_machine") && delta?.patchRisk.level === "low") {
+      warnings.push({
+        file: pf.relativePath,
+        rule: "data_table_state_machine_risk",
+        detail: "data_table state machine should have at least medium patch risk"
+      });
+    }
     passCount++;
   }
+  const PAYMENT_PROVIDER_PATH_TERMS = ["stripe", "paypal", "btcpay", "btcpayserver", "alby", "hitpay", "payment"];
+  const PAYMENT_CONTENT_TERMS = [
+    "constructEvent",
+    "checkoutSession",
+    "paymentIntent",
+    "stripe-signature",
+    "webhook-signature",
+    "payment_mutation",
+    "paymentStatus",
+    "invoicePaid",
+    "chargeSucceeded"
+  ];
+  for (const [rel, pf] of Object.entries(store.files)) {
+    if (!pf.isRealSource)
+      continue;
+    const pathLower = rel.toLowerCase();
+    if (!pathLower.includes("webhook"))
+      continue;
+    const primaryTrigger = PAYMENT_PROVIDER_PATH_TERMS.some((t) => pathLower.includes(t));
+    let secondaryTrigger = false;
+    if (!primaryTrigger && pf.productDomain !== "payments_webhooks") {
+      try {
+        const src = await readFile6(join7(projectRoot, rel), "utf8");
+        secondaryTrigger = PAYMENT_CONTENT_TERMS.some((t) => src.includes(t));
+      } catch {
+      }
+    }
+    if (!primaryTrigger && !secondaryTrigger)
+      continue;
+    const delta = deltaByPath.get(rel);
+    const triggerLabel = primaryTrigger ? "path" : "content";
+    const webhookChecks = [
+      [
+        pf.productDomain !== "payments_webhooks",
+        "webhook_domain",
+        `Payment webhook (${triggerLabel} trigger) not classified as payments_webhooks`
+      ],
+      [
+        !pf.sideEffectProfile.includes("webhook_ingress"),
+        "webhook_ingress_missing",
+        `Payment webhook (${triggerLabel} trigger) missing webhook_ingress side effect`
+      ],
+      [
+        !pf.sideEffectProfile.includes("payment_mutation"),
+        "webhook_payment_mutation_missing",
+        `Payment webhook (${triggerLabel} trigger) missing payment_mutation side effect`
+      ],
+      [
+        !pf.writeIntents.includes("handle_payment_webhook"),
+        "webhook_write_intent_missing",
+        `Payment webhook (${triggerLabel} trigger) missing handle_payment_webhook write intent`
+      ],
+      [
+        !!delta && delta.patchRisk.level !== "high" && delta.patchRisk.level !== "critical",
+        "webhook_patch_risk",
+        `Payment webhook (${triggerLabel} trigger) patchRisk must be high or critical`
+      ],
+      [
+        !pf.canonicalLoadBearing,
+        "webhook_load_bearing",
+        `Payment webhook (${triggerLabel} trigger) must be load-bearing`
+      ]
+    ];
+    for (const [condition, rule, detail] of webhookChecks) {
+      if (condition)
+        errors.push({ file: rel, rule, detail });
+    }
+  }
   return {
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
     passed: errors.length === 0,
@@ -2505,7 +2636,7 @@ async function getFileAnalysis(absPath) {
     return null;
   let source;
   try {
-    source = await readFile6(absPath, "utf8");
+    source = await readFile7(absPath, "utf8");
   } catch {
     return null;
   }
@@ -2546,14 +2677,14 @@ async function getFileAnalysis(absPath) {
 import { Mutex } from "async-mutex";
 import { join as join9, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { readFile as readFile7, writeFile as writeFile8, mkdir as mkdir7 } from "fs/promises";
+import { readFile as readFile8, writeFile as writeFile8, mkdir as mkdir7 } from "fs/promises";
 import { existsSync as existsSync4, cpSync } from "fs";
 var __dirname2 = dirname3(fileURLToPath2(import.meta.url));
 var dossierMutex = new Mutex();
 async function readDossier(projectRoot) {
   const dossierPath = join9(projectRoot, ".vibe-splainer", "dossier.json");
   try {
-    const raw = await readFile7(dossierPath, "utf8");
+    const raw = await readFile8(dossierPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -2587,7 +2718,7 @@ async function regenerateUI(projectRoot, dossier) {
     return;
   }
   cpSync(templateDir, uiDir, { recursive: true });
-  let html = await readFile7(join9(templateDir, "index.html"), "utf8");
+  let html = await readFile8(join9(templateDir, "index.html"), "utf8");
   const injection = `<script>window.__VIBE_DOSSIER__ = ${JSON.stringify(dossier)};</script>`;
   html = html.replace("<!-- VIBE_DOSSIER_INJECTION_POINT -->", injection);
   await writeFile8(join9(uiDir, "index.html"), html, "utf8");
@@ -2611,7 +2742,7 @@ function validateMermaidNodeCount(diagram) {
 // ../brain/dist/watcher.js
 import chokidar from "chokidar";
 import { createHash as createHash2 } from "crypto";
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 import { join as join10 } from "path";
 function startWatcher(projectRoot, watchedPaths) {
   const watcher = chokidar.watch(watchedPaths.length > 0 ? watchedPaths : projectRoot, {
@@ -2624,7 +2755,7 @@ function startWatcher(projectRoot, watchedPaths) {
       const dossier = await readDossier(projectRoot);
       if (!dossier)
         return;
-      const content = await readFile8(filepath, "utf8");
+      const content = await readFile9(filepath, "utf8");
       const newHash = createHash2("sha256").update(content).digest("hex");
       let mutated = false;
       for (const pillar of dossier.pillars) {
@@ -2801,7 +2932,7 @@ async function handleSetProjectBrief(args) {
 }
 
 // dist/mcp/tools/get_file_context.js
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { join as join11, relative as relative3, isAbsolute } from "path";
 var getFileContextTool = {
   name: "get_file_context",
@@ -2847,7 +2978,7 @@ async function handleGetFileContext(args) {
     smellSpans: evidence.smellSpans
   };
   if (full) {
-    result.source = await readFile9(fullPath, "utf8");
+    result.source = await readFile10(fullPath, "utf8");
   }
   return result;
 }
@@ -2855,7 +2986,7 @@ async function handleGetFileContext(args) {
 // dist/mcp/tools/write_decision_card.js
 import { v4 as uuidv4 } from "uuid";
 import { createHash as createHash3 } from "crypto";
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { join as join12 } from "path";
 var CATEGORIES = ["Bottleneck", "Hack", "Smart-Move", "Risk", "Convention", "Dead-Weight"];
 function normalizeSnippet(s) {
@@ -2948,7 +3079,7 @@ async function handleWriteDecisionCard(args) {
   const heat = persisted ? Math.round(persisted.heat) : void 0;
   let primaryContent = "";
   try {
-    primaryContent = await readFile10(join12(projectRoot, primaryFile), "utf8");
+    primaryContent = await readFile11(join12(projectRoot, primaryFile), "utf8");
   } catch {
   }
   const hash = createHash3("sha256").update(primaryContent).digest("hex");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-splain",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Architectural dossier engine for vibe-coded TypeScript/JavaScript projects. Runs as an MCP server inside your coding agent.",
   "type": "module",
   "license": "MIT",