vibe-splain 3.4.2 → 4.0.0

package/dist/hook/preToolUse.d.ts

@@ -1,30 +0,0 @@
-import type { EscalationContext } from '@vibe-splain/brain/dist/network/escalation.js';
-import type { GateIndex } from '@vibe-splain/brain/dist/network/gateIndex.js';
-export interface PreToolUseInput {
-    tool_name?: string;
-    tool_input?: {
-        file_path?: string;
-        [k: string]: unknown;
-    };
-    cwd?: string;
-    session_id?: string;
-}
-export interface HookOutput {
-    hookSpecificOutput: {
-        hookEventName: 'PreToolUse';
-        permissionDecision: 'allow' | 'ask';
-        permissionDecisionReason?: string;
-        additionalContext?: string;
-        systemMessage?: string;
-    };
-}
-export type HookResult = {
-    action: 'defer';
-} | {
-    action: 'emit';
-    output: HookOutput;
-};
-export declare function decidePreToolUse(input: PreToolUseInput, gateIndex: GateIndex | null, sessionState?: {
-    warningShown?: boolean;
-}): HookResult;
-export declare function formatEscalation(ctx: EscalationContext): string;

package/dist/hook/preToolUse.js

@@ -1,81 +0,0 @@
-// 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

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

package/dist/hook-entry.js

@@ -1,8 +0,0 @@
-#!/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

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

package/dist/hook.js

@@ -1,337 +0,0 @@
-#!/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
-};

package/dist/mcp/BudgetGuard.d.ts

@@ -1,13 +0,0 @@
-export interface BudgetExceededResult {
-    pointerId: string;
-    contentHash: string;
-    sizeBytes: number;
-    summary: string;
-    hydrators: string[];
-}
-export declare function applyBudgetGuard(projectRoot: string, scanId: string, artifactName: string, output: unknown): Promise<unknown>;
-/** Verify a pointer exists, is unexpired, and its blob hash matches */
-export declare function hydratePointer(projectRoot: string, pointerId: string): Promise<{
-    content: Buffer;
-    row: import('../store/PointerStore.js').PointerRow;
-}>;

package/dist/mcp/BudgetGuard.js

@@ -1,55 +0,0 @@
-import { BlobStore } from '../store/BlobStore.js';
-import { PointerStore } from '../store/PointerStore.js';
-import { v4 as uuidv4 } from 'uuid';
-/** ~2000 tokens ≈ 8000 chars */
-const BUDGET_CHARS = 8000;
-export async function applyBudgetGuard(projectRoot, scanId, artifactName, output) {
-    const serialized = JSON.stringify(output, null, 2);
-    if (serialized.length <= BUDGET_CHARS)
-        return output;
-    const blobStore = new BlobStore(projectRoot);
-    const pointerStore = PointerStore.open(projectRoot);
-    const { contentHash, blobPath } = await blobStore.writeAtomic(serialized);
-    const pointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
-    await pointerStore.insertPointer({
-        pointerId,
-        scanId,
-        artifactName,
-        contentHash,
-        blobPath,
-        schemaVersion: '1.0.0',
-        createdAt: Date.now(),
-        expiresAt: null,
-    });
-    const result = {
-        pointerId,
-        contentHash,
-        sizeBytes: serialized.length,
-        summary: `Output exceeded context budget (${serialized.length} chars). Written to artifact blob.`,
-        hydrators: ['get_evidence_slice', 'get_start_here', 'get_project_summary'],
-    };
-    return result;
-}
-/** Verify a pointer exists, is unexpired, and its blob hash matches */
-export async function hydratePointer(projectRoot, pointerId) {
-    const pointerStore = PointerStore.open(projectRoot);
-    const row = pointerStore.getPointer(pointerId);
-    if (!row) {
-        throw new Error(`ArtifactNotFound: pointer ${pointerId} does not exist`);
-    }
-    if (row.expiresAt !== null && row.expiresAt < Date.now()) {
-        throw new Error(`ArtifactCollectedError: pointer ${pointerId} has expired`);
-    }
-    const SUPPORTED_VERSIONS = ['1.0.0', '2.0.0'];
-    if (!SUPPORTED_VERSIONS.includes(row.schemaVersion)) {
-        throw new Error(`UnsupportedSchema: pointer ${pointerId} has schema version ${row.schemaVersion}`);
-    }
-    const blobStore = new BlobStore(projectRoot);
-    const content = await blobStore.readBlob(row.blobPath);
-    const valid = await blobStore.verifyIntegrity(row.blobPath, row.contentHash);
-    if (!valid) {
-        throw new Error(`IntegrityError: blob for pointer ${pointerId} failed hash verification`);
-    }
-    return { content, row };
-}
-//# sourceMappingURL=BudgetGuard.js.map

package/dist/mcp/SessionScope.d.ts

@@ -1,26 +0,0 @@
-import type { WorkOrderRow, ProofDescriptor } from '../store/PointerStore.js';
-export interface ScopePolicy {
-    workOrderId: string;
-    allowedFiles: string[];
-    allowedGlobs: string[];
-    deniedGlobs: string[];
-    requiredProof: ProofDescriptor[];
-}
-export declare class ScopeViolation extends Error {
-    readonly path: string;
-    readonly workOrderId: string;
-    constructor(path: string, workOrderId: string, reason: string);
-}
-export declare const SessionScope: {
-    set(policy: ScopePolicy): void;
-    clear(): void;
-    get(): ScopePolicy | null;
-    /**
-     * Enforce scope for a file path.
-     * Throws ScopeViolation if:
-     *  - a scope is active AND the path is not allowed
-     * If no scope is active, all paths are permitted.
-     */
-    enforce(filePath: string): void;
-    fromWorkOrderRow(row: WorkOrderRow): ScopePolicy;
-};

package/dist/mcp/SessionScope.js

@@ -1,56 +0,0 @@
-import { minimatch } from 'minimatch';
-export class ScopeViolation extends Error {
-    path;
-    workOrderId;
-    constructor(path, workOrderId, reason) {
-        super(`ScopeViolation [${workOrderId}]: ${reason} — path: ${path}`);
-        this.path = path;
-        this.workOrderId = workOrderId;
-        this.name = 'ScopeViolation';
-    }
-}
-let activeScope = null;
-export const SessionScope = {
-    set(policy) {
-        activeScope = policy;
-    },
-    clear() {
-        activeScope = null;
-    },
-    get() {
-        return activeScope;
-    },
-    /**
-     * Enforce scope for a file path.
-     * Throws ScopeViolation if:
-     *  - a scope is active AND the path is not allowed
-     * If no scope is active, all paths are permitted.
-     */
-    enforce(filePath) {
-        if (!activeScope)
-            return;
-        const { workOrderId, allowedFiles, allowedGlobs, deniedGlobs } = activeScope;
-        // Explicit file list match (exact suffix or relative path)
-        const inAllowedFiles = allowedFiles.some(f => filePath === f || filePath.endsWith('/' + f) || filePath.endsWith(f));
-        // Glob match
-        const inAllowedGlobs = allowedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
-        if (!inAllowedFiles && !inAllowedGlobs) {
-            throw new ScopeViolation(filePath, workOrderId, 'path not in allowedFiles or allowedGlobs');
-        }
-        // Deny globs have priority over allow
-        const isDenied = deniedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
-        if (isDenied) {
-            throw new ScopeViolation(filePath, workOrderId, 'path matches deniedGlobs');
-        }
-    },
-    fromWorkOrderRow(row) {
-        return {
-            workOrderId: row.workOrderId,
-            allowedFiles: JSON.parse(row.allowedFiles),
-            allowedGlobs: JSON.parse(row.allowedGlobs),
-            deniedGlobs: JSON.parse(row.deniedGlobs),
-            requiredProof: JSON.parse(row.requiredProof),
-        };
-    },
-};
-//# sourceMappingURL=SessionScope.js.map

package/dist/mcp/tools/apply_patch.d.ts

@@ -1,37 +0,0 @@
-export declare class StalePatchError extends Error {
-    readonly filePath: string;
-    readonly expectedHash: string;
-    readonly actualHash: string;
-    constructor(filePath: string, expectedHash: string, actualHash: string);
-}
-export declare const applyPatchTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            projectRoot: {
-                type: string;
-                description: string;
-            };
-            filePath: {
-                type: string;
-                description: string;
-            };
-            newContent: {
-                type: string;
-                description: string;
-            };
-            expectedPrePatchHash: {
-                type: string;
-                description: string;
-            };
-            scanId: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handleApplyPatch(args: Record<string, unknown>): Promise<unknown>;