vibe-splain 3.4.1 → 3.4.2

package/dist/hook/preToolUse.js

@@ -0,0 +1,81 @@
+// PreToolUse hook decision logic — the deterministic gate.
+//
+// Pure: given the agent's intended tool call and the scan artifact, decide
+// whether to escalate and how. No stdin/stdout, no filesystem — the CLI command
+// wraps this with I/O. This separation is what makes the gate testable against
+// real scanned stores.
+import { buildEscalationContext } from '@vibe-splain/brain/dist/network/escalation.js';
+const DEFER = { action: 'defer' };
+// Only file-editing tools can have a blast radius. Anything else defers.
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+export function decidePreToolUse(input, gateIndex, sessionState) {
+    if (!EDIT_TOOLS.has(input.tool_name ?? ''))
+        return DEFER;
+    if (!gateIndex) {
+        if (sessionState && !sessionState.warningShown) {
+            const warnMsg = "vibe-splain: .vibe-splainer/gate.json is missing. Please run 'vibe-splain scan' to generate the scan architecture and enable tool guarding.";
+            return {
+                action: 'emit',
+                output: {
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'allow',
+                        additionalContext: warnMsg,
+                        systemMessage: warnMsg,
+                    },
+                },
+            };
+        }
+        return DEFER;
+    }
+    const filePath = input.tool_input?.file_path;
+    if (!filePath)
+        return DEFER;
+    const ctx = buildEscalationContext(filePath, gateIndex);
+    if (!ctx || ctx.blastRadius === 'low')
+        return DEFER;
+    const block = formatEscalation(ctx);
+    // high → stop-and-reconsider (human gate). medium → non-blocking awareness:
+    // the agent sees the context on its next request without being interrupted.
+    if (ctx.blastRadius === 'high') {
+        return {
+            action: 'emit',
+            output: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'ask',
+                    permissionDecisionReason: block,
+                    additionalContext: block,
+                },
+            },
+        };
+    }
+    return {
+        action: 'emit',
+        output: {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'allow',
+                additionalContext: block,
+            },
+        },
+    };
+}
+export function formatEscalation(ctx) {
+    const lines = [];
+    lines.push(`vibe-splain: ${ctx.blastRadius} blast radius — ${ctx.targetFile} (gravity ${ctx.gravity}).`);
+    if (ctx.dependentCount > 0) {
+        const shown = ctx.dependents.slice(0, 8);
+        const more = ctx.dependentCount - shown.length;
+        lines.push(`${ctx.dependentCount} file(s) depend on it:`);
+        for (const d of shown)
+            lines.push(`  - ${d}`);
+        if (more > 0)
+            lines.push(`  … (+${more} more)`);
+    }
+    for (const w of ctx.riskWarnings)
+        lines.push(`[${w.level}] ${w.message}`);
+    lines.push(ctx.smallestSafeChange.summary);
+    return lines.join('\n');
+}
+//# sourceMappingURL=preToolUse.js.map

package/dist/hook-entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hook-entry.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Lean entrypoint for the PreToolUse hook. Bundled separately from the main CLI
+// so it pulls in ONLY the gate-index reader + decision logic — no Tree-Sitter
+// WASM, no MCP SDK, no chokidar. Keeps per-edit startup near the bare-Node floor
+// (~40–60ms) instead of loading the full scanner bundle (~260ms+).
+import { hookPreToolUseCommand } from './commands/hook.js';
+hookPreToolUseCommand();
+//# sourceMappingURL=hook-entry.js.map

package/dist/hook.d.ts

@@ -0,0 +1 @@
+export declare function findProjectRoot(start: string | undefined): string | null;

package/dist/hook.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+// dist/hook.js
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { tmpdir } from "os";
+
+// ../brain/dist/network/gateIndex.js
+function isDenoisedImporter(relPath) {
+  if (!relPath)
+    return false;
+  const norm = relPath.replace(/\\/g, "/");
+  const segs = norm.split("/");
+  const excludedDirs = /* @__PURE__ */ new Set([
+    "node_modules",
+    "vendor",
+    "vendored",
+    "site-packages",
+    "third_party",
+    "third-party",
+    ".yarn",
+    "bower_components",
+    "venv",
+    ".venv",
+    "env",
+    "virtualenv",
+    ".git",
+    ".vibe-splainer",
+    "dist",
+    "build",
+    "out",
+    "target",
+    ".next",
+    ".nuxt",
+    ".docusaurus",
+    "coverage",
+    ".nyc_output",
+    ".cache"
+  ]);
+  for (const s of segs) {
+    const sLower = s.toLowerCase();
+    if (excludedDirs.has(sLower)) {
+      return false;
+    }
+    if (sLower.endsWith(".venv")) {
+      return false;
+    }
+  }
+  const fileName = segs[segs.length - 1];
+  const fileNameLower = fileName.toLowerCase();
+  if (/\.min\.[a-z]+$/.test(fileNameLower) || fileNameLower.includes(".min.")) {
+    return false;
+  }
+  if (/\.generated\./.test(fileNameLower) || fileNameLower.includes("__generated__")) {
+    return false;
+  }
+  if (fileNameLower.endsWith(".lock")) {
+    return false;
+  }
+  if (norm.startsWith("virtual:") || norm.startsWith("__virtual:") || norm.startsWith("webpack:")) {
+    return false;
+  }
+  return true;
+}
+
+// ../brain/dist/network/escalation.js
+var SECURITY_PATH = /\b(auth|credential|secret|token|webhook|payment|password|oauth|session)\b/i;
+var SENSITIVE_EFFECTS = /* @__PURE__ */ new Set([
+  "database_write",
+  "server_action",
+  "trpc_mutation",
+  "email_send",
+  "external_api_call"
+]);
+var NOTABLE_RISKS = /* @__PURE__ */ new Set([
+  "state_machine",
+  "mutation_orchestration",
+  "side_effect_coupling",
+  "async_race_risk",
+  "registry_bottleneck",
+  "error_swallowing"
+]);
+function buildEscalationContext(targetFile, gateIndex) {
+  const file = lookupFile(targetFile, gateIndex);
+  if (!file)
+    return null;
+  const rel = file.relativePath;
+  const gravity = file.gravity;
+  const dependents = file.dependents;
+  const dependentsCount = dependents.length;
+  const sideEffects = file.sideEffects;
+  const riskTypes = file.riskTypes;
+  const severity = file.severity;
+  const gravity_tier = gravity > 70 ? "high" : gravity > 40 ? "medium" : "low";
+  const raw_substance_tier = file.hasBehavioralSubstance && dependentsCount >= 10 ? "high" : file.hasBehavioralSubstance && dependentsCount >= 4 ? "medium" : "low";
+  const tierOrder = { low: 1, medium: 2, high: 3 };
+  let blastRadius = tierOrder[gravity_tier] >= tierOrder[raw_substance_tier] ? gravity_tier : raw_substance_tier;
+  const isGeneratedOrVendored = !isDenoisedImporter(targetFile) || file.demoteReason !== null && file.demoteReason !== "no inbound references from application code";
+  if (isGeneratedOrVendored) {
+    blastRadius = "low";
+  }
+  const riskWarnings = buildRiskWarnings(rel, gravity, dependentsCount, severity, sideEffects, riskTypes);
+  return {
+    targetFile: rel,
+    gravity,
+    blastRadius,
+    dependents,
+    dependentCount: dependentsCount,
+    fanIn: file.fanIn,
+    fanOut: file.fanOut,
+    centrality: file.centrality,
+    severity,
+    sideEffects,
+    riskTypes,
+    riskWarnings,
+    smallestSafeChange: buildSafeChangePolicy(blastRadius)
+  };
+}
+function lookupFile(targetFile, gateIndex) {
+  const files = gateIndex?.files;
+  if (!files)
+    return null;
+  const norm = targetFile.replace(/\\/g, "/");
+  if (files[norm])
+    return files[norm];
+  const suffixHits = [];
+  for (const [key, rec] of Object.entries(files)) {
+    if (norm === key || norm.endsWith("/" + key) || key.endsWith("/" + norm)) {
+      suffixHits.push(rec);
+    }
+  }
+  return suffixHits.length === 1 ? suffixHits[0] : null;
+}
+function buildRiskWarnings(rel, gravity, dependentCount, severity, sideEffects, riskTypes) {
+  const warnings = [];
+  if (gravity > 70) {
+    warnings.push({
+      id: `rw_${rel}_blast_radius`,
+      level: "critical",
+      message: `Central file \u2014 editing it has a large blast radius. ${dependentCount} file(s) depend on it.`,
+      reason: `Gravity ${gravity}/100; fan-in ${dependentCount}.`
+    });
+  }
+  if (severity >= 4) {
+    warnings.push({
+      id: `rw_${rel}_severity`,
+      level: "warning",
+      message: "High-severity smells already present here. Avoid making them worse.",
+      reason: `Canonical severity ${severity}/5.`
+    });
+  }
+  if (SECURITY_PATH.test(rel)) {
+    warnings.push({
+      id: `rw_${rel}_security_path`,
+      level: "critical",
+      message: "Security-sensitive file (auth/credential/webhook/payment). Do not alter auth or credential handling unless that is the explicit task.",
+      reason: `Path matches security-sensitive pattern.`
+    });
+  }
+  const sensitive = sideEffects.filter((e) => SENSITIVE_EFFECTS.has(e));
+  if (sensitive.length > 0) {
+    warnings.push({
+      id: `rw_${rel}_side_effects`,
+      level: "warning",
+      message: `This file performs side effects (${sensitive.join(", ")}). Preserve existing behavior; do not drop or reorder them.`,
+      reason: `Side-effect profile: ${sensitive.join(", ")}.`
+    });
+  }
+  const notable = riskTypes.filter((r) => NOTABLE_RISKS.has(r));
+  if (notable.length > 0) {
+    warnings.push({
+      id: `rw_${rel}_risk_types`,
+      level: "info",
+      message: `Structural risk patterns detected (${notable.join(", ")}). Trace the affected paths before editing.`,
+      reason: `Risk types: ${notable.join(", ")}.`
+    });
+  }
+  return warnings;
+}
+function buildSafeChangePolicy(blastRadius) {
+  const rules = [
+    "Locate the exact failure site before editing.",
+    "Make the smallest localized change that addresses the task.",
+    "Do not perform general cleanup or refactoring.",
+    "Do not modify unrelated files, credentials, or auth configuration."
+  ];
+  if (blastRadius === "high") {
+    rules.push("This file is load-bearing: verify each dependent still type-checks against the changed surface.");
+  }
+  return {
+    summary: "Make the smallest localized change that addresses the requested task. Do not modify unrelated files, credentials, auth configuration, or neighboring modules unless the task explicitly requires it.",
+    rules,
+    forbiddenEditClasses: ["credentials", "auth_configuration", "global_refactoring"]
+  };
+}
+
+// dist/hook/preToolUse.js
+var DEFER = { action: "defer" };
+var EDIT_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "MultiEdit"]);
+function decidePreToolUse(input, gateIndex, sessionState) {
+  if (!EDIT_TOOLS.has(input.tool_name ?? ""))
+    return DEFER;
+  if (!gateIndex) {
+    if (sessionState && !sessionState.warningShown) {
+      const warnMsg = "vibe-splain: .vibe-splainer/gate.json is missing. Please run 'vibe-splain scan' to generate the scan architecture and enable tool guarding.";
+      return {
+        action: "emit",
+        output: {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            additionalContext: warnMsg,
+            systemMessage: warnMsg
+          }
+        }
+      };
+    }
+    return DEFER;
+  }
+  const filePath = input.tool_input?.file_path;
+  if (!filePath)
+    return DEFER;
+  const ctx = buildEscalationContext(filePath, gateIndex);
+  if (!ctx || ctx.blastRadius === "low")
+    return DEFER;
+  const block = formatEscalation(ctx);
+  if (ctx.blastRadius === "high") {
+    return {
+      action: "emit",
+      output: {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "ask",
+          permissionDecisionReason: block,
+          additionalContext: block
+        }
+      }
+    };
+  }
+  return {
+    action: "emit",
+    output: {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        additionalContext: block
+      }
+    }
+  };
+}
+function formatEscalation(ctx) {
+  const lines = [];
+  lines.push(`vibe-splain: ${ctx.blastRadius} blast radius \u2014 ${ctx.targetFile} (gravity ${ctx.gravity}).`);
+  if (ctx.dependentCount > 0) {
+    const shown = ctx.dependents.slice(0, 8);
+    const more = ctx.dependentCount - shown.length;
+    lines.push(`${ctx.dependentCount} file(s) depend on it:`);
+    for (const d of shown)
+      lines.push(`  - ${d}`);
+    if (more > 0)
+      lines.push(`  \u2026 (+${more} more)`);
+  }
+  for (const w of ctx.riskWarnings)
+    lines.push(`[${w.level}] ${w.message}`);
+  lines.push(ctx.smallestSafeChange.summary);
+  return lines.join("\n");
+}
+
+// dist/hook.js
+function findProjectRoot(start) {
+  let dir = start || process.cwd();
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(join(dir, ".vibe-splainer")))
+      return dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+async function main() {
+  const rawStdin = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(rawStdin);
+  } catch {
+    process.exit(0);
+  }
+  const root = findProjectRoot(input.cwd);
+  const gatePath = root ? join(root, ".vibe-splainer", "gate.json") : null;
+  const gateExists = gatePath ? existsSync(gatePath) : false;
+  let result;
+  if (!gateExists) {
+    const sessionId = input.session_id || "default";
+    const warnFile = join(tmpdir(), `vibe-splain-warn-${sessionId}`);
+    const warningShown = existsSync(warnFile);
+    result = decidePreToolUse(input, null, { warningShown });
+    if (result.action === "emit") {
+      try {
+        writeFileSync(warnFile, "1");
+      } catch {
+      }
+    }
+  } else {
+    let gateIndex = null;
+    try {
+      gateIndex = JSON.parse(readFileSync(gatePath, "utf8"));
+    } catch {
+    }
+    result = decidePreToolUse(input, gateIndex);
+  }
+  if (result.action === "emit") {
+    process.stdout.write(JSON.stringify(result.output));
+  }
+  process.exit(0);
+}
+main().catch(() => {
+  process.exit(0);
+});
+export {
+  findProjectRoot
+};