vibe-splain 3.0.0 → 3.1.0

package/dist/export/ArtifactBundleWriter.js

@@ -9,8 +9,10 @@ export class ArtifactBundleWriter {
     async writeBundle(artifacts) {
         const outputDir = join(this.projectRoot, '.vibe-splainer');
         const stagingDir = join(this.projectRoot, '.vibe-splainer.tmp');
+        const oldDir = join(this.projectRoot, '.vibe-splainer.old');
         try {
             await rm(stagingDir, { recursive: true, force: true });
+            await rm(oldDir, { recursive: true, force: true });
             const { existsSync } = await import('fs');
             const { cp } = await import('fs/promises');
             if (existsSync(outputDir)) {
@@ -40,12 +42,28 @@ export class ArtifactBundleWriter {
                 artifacts: manifestArtifacts,
             };
             await writeFile(join(stagingDir, 'artifact_manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
-            // Atomic rename.
-            // Rename fails if destination is a non-empty directory.
-            // So we first delete the existing outputDir.
-            // Since it's inside the project root, it's safe to do rm -rf .vibe-splainer
-            await rm(outputDir, { recursive: true, force: true });
-            await rename(stagingDir, outputDir);
+            // Atomic swap pattern:
+            // 1. Rename current -> old
+            // 2. Rename staging -> current
+            // 3. Remove old
+            let swapped = false;
+            if (existsSync(outputDir)) {
+                await rename(outputDir, oldDir);
+                swapped = true;
+            }
+            try {
+                await rename(stagingDir, outputDir);
+            }
+            catch (err) {
+                // Rollback if possible
+                if (swapped) {
+                    await rename(oldDir, outputDir);
+                }
+                throw err;
+            }
+            if (swapped) {
+                await rm(oldDir, { recursive: true, force: true });
+            }
         }
         catch (err) {
             await rm(stagingDir, { recursive: true, force: true });

package/dist/export/ExportOrchestrator.js

@@ -1,4 +1,4 @@
-import { readAnalysis, RecommendationEngine } from '@vibe-splain/brain';
+import { readAnalysis, readActionBindings, RecommendationEngine } from '@vibe-splain/brain';
 import { ArtifactBundleWriter } from './ArtifactBundleWriter.js';
 import { JsonRenderer } from './renderers/JsonRenderer.js';
 import { HtmlRenderer } from './renderers/HtmlRenderer.js';
@@ -17,6 +17,7 @@ export class ExportOrchestrator {
         if (!finalStore) {
             throw new Error('Analysis store not found. Scan the project first.');
         }
+        const bindings = await readActionBindings(this.projectRoot);
         // Aggressive Boilerplate Culling
         for (const p of dossier.pillars) {
             p.decisions = p.decisions.filter(c => !(c.severity === 1 && c.category === 'Convention'));
@@ -42,7 +43,7 @@ export class ExportOrchestrator {
             artifacts.push(...await new HtmlRenderer().render(viewModel, finalStore));
         }
         if (formats.includes('markdown')) {
-            artifacts.push(...await new AgentMarkdownRenderer(options.budget).render(viewModel, finalStore));
+            artifacts.push(...await new AgentMarkdownRenderer(options.budget, bindings).render(viewModel, finalStore));
         }
         const writer = new ArtifactBundleWriter(this.projectRoot);
         await writer.writeBundle(artifacts);

package/dist/export/Watcher.d.ts

@@ -1 +1 @@
-export declare function startWatcher(projectRoot: string, watchedPaths: string[]): void;
+export declare function startWatcher(projectRoot: string, watchedPaths: string[]): Promise<void>;

package/dist/export/Watcher.js

@@ -4,7 +4,14 @@ import { readFile } from 'fs/promises';
 import { join } from 'path';
 import { readDossier } from '@vibe-splain/brain';
 import { ExportOrchestrator } from './ExportOrchestrator.js';
-export function startWatcher(projectRoot, watchedPaths) {
+const activeWatchers = new Map();
+export async function startWatcher(projectRoot, watchedPaths) {
+    // Clean up existing watcher for this project to prevent resource leaks
+    const existing = activeWatchers.get(projectRoot);
+    if (existing) {
+        await existing.close();
+        activeWatchers.delete(projectRoot);
+    }
     const watcher = chokidar.watch(watchedPaths.length > 0 ? watchedPaths : projectRoot, {
         ignoreInitial: true,
         ignored: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.vibe-splainer/**'],
@@ -42,6 +49,7 @@ export function startWatcher(projectRoot, watchedPaths) {
             console.error('[vibe-splain] Watcher error:', err);
         }
     });
+    activeWatchers.set(projectRoot, watcher);
     console.error('[vibe-splain] File watcher started');
 }
 //# sourceMappingURL=Watcher.js.map

package/dist/export/renderers/AgentMarkdownRenderer.d.ts

@@ -3,6 +3,7 @@ import type { Renderer } from './Renderer.js';
 import type { Artifact } from '../ArtifactBundleWriter.js';
 export declare class AgentMarkdownRenderer implements Renderer {
     private budget;
-    constructor(budget?: number);
+    private bindings;
+    constructor(budget?: number, bindings?: any | null);
     render(viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
 }

package/dist/export/renderers/AgentMarkdownRenderer.js

@@ -1,7 +1,9 @@
 export class AgentMarkdownRenderer {
     budget;
-    constructor(budget = 8000) {
+    bindings;
+    constructor(budget = 8000, bindings = null) {
         this.budget = budget;
+        this.bindings = bindings;
     }
     render(viewModel, store) {
         let md = `# Architectural Dossier: ${viewModel.projectRoot}\n\n`;
@@ -52,6 +54,20 @@ export class AgentMarkdownRenderer {
                 md += `**Severity**: ${card.severity} | **Category**: ${card.category}\n`;
                 md += `**Narrative**: ${card.narrative}\n`;
             }
+            // Add Function-Level Action Bindings for Tier 1
+            if (this.bindings && this.bindings.files[path]) {
+                const fileBinding = this.bindings.files[path];
+                const criticalFunctions = fileBinding.functions.filter((fn) => fn.semanticActions.length > 0 || fn.isEntrypoint);
+                if (criticalFunctions.length > 0) {
+                    md += `\n**Critical Functions**:\n`;
+                    for (const fn of criticalFunctions) {
+                        md += `- \`${fn.displayName}\` (lines ${fn.startLine}-${fn.endLine})${fn.isEntrypoint ? ' [Entrypoint]' : ''}\n`;
+                        for (const action of fn.semanticActions) {
+                            md += `  - **${action.actionKind}**${action.targetModel ? ` on ${action.targetModel}` : ''}: \`${action.calleeText}\` (line ${action.sourceLine})\n`;
+                        }
+                    }
+                }
+            }
             if (recs.length > 0) {
                 md += `\n**Safe Patch Strategies**:\n`;
                 for (const r of recs) {

package/dist/export/renderers/HtmlRenderer.js

@@ -17,13 +17,36 @@ function getAllFiles(dirPath, arrayOfFiles = []) {
 }
 export class HtmlRenderer {
     render(viewModel, _store) {
-        let templateDir = join(__dirname, '..', '..', 'ui'); // from dist/export/renderers -> dist/ui
-        if (!existsSync(templateDir)) {
-            // Unbundled path (from cli/src/export/renderers -> cli/dist/ui)
-            templateDir = join(__dirname, '..', '..', '..', '..', 'dist', 'ui');
+        // Robust template resolution for bundled/unbundled environments
+        const candidatePaths = [
+            join(__dirname, 'ui'), // bundled: dist/index.js -> dist/ui
+            join(__dirname, '..', '..', 'ui'), // unbundled: dist/export/renderers -> dist/ui
+            join(__dirname, '..', 'ui'), // alt bundle
+            join(__dirname, '..', '..', '..', 'ui', 'dist'), // dev: packages/cli/src/export/renderers -> packages/ui/dist
+            join(__dirname, '..', '..', 'packages', 'ui', 'dist'), // repo root -> packages/ui/dist
+        ];
+        let templateDir = '';
+        for (const p of candidatePaths) {
+            if (existsSync(p) && existsSync(join(p, 'index.html'))) {
+                // Double check it's not the source packages/ui (which has vite.config.ts)
+                // We want the BUILT UI in the dist folder.
+                if (!existsSync(join(p, 'vite.config.ts')) || p.endsWith('dist')) {
+                    templateDir = p;
+                    break;
+                }
+            }
+        }
+        // Fallback to any 'ui' folder that has index.html as a last resort
+        if (!templateDir) {
+            for (const p of candidatePaths) {
+                if (existsSync(join(p, 'index.html'))) {
+                    templateDir = p;
+                    break;
+                }
+            }
         }
-        if (!existsSync(templateDir)) {
-            console.error('[vibe-splain] UI template not found at', templateDir, '- skipping UI regeneration');
+        if (!templateDir) {
+            console.error('[vibe-splain] UI template not found. Checked:', candidatePaths);
             return [];
         }
         const artifacts = [];

package/dist/index.js

@@ -2276,7 +2276,8 @@ async function runActionBinding(projectRoot, inv, res) {
       const startLine = node.startPosition.row + 1;
       const startCol = node.startPosition.column;
       const endLine = node.endPosition.row + 1;
-      const isDuplicate = functions.some((f) => f.startLine === startLine && f.endLine === endLine);
+      const endCol = node.endPosition.column;
+      const isDuplicate = functions.some((f) => f.startLine === startLine && f.startCol === startCol && f.endLine === endLine && f.functionKind === node.type);
       if (isDuplicate)
         continue;
       functionsExtracted++;
@@ -2538,13 +2539,30 @@ async function runActionBinding(projectRoot, inv, res) {
   for (const fileRec of Object.values(artifact.files)) {
     for (const fnRec of fileRec.functions) {
       for (const callRec of fnRec.calls) {
-        if (callRec.resolutionKind === "named_import_match" && callRec.resolvedFilePath) {
-          const targetFile = artifact.files[callRec.resolvedFilePath];
-          if (targetFile) {
-            const targetFn = targetFile.functions.find((f) => f.displayName === callRec.calleeRoot);
-            if (targetFn) {
-              callRec.resolvedTargetFunctionId = targetFn.functionId;
-            }
+        if (callRec.resolvedTargetFunctionId)
+          continue;
+        if (!callRec.resolvedFilePath)
+          continue;
+        const targetFile = artifact.files[callRec.resolvedFilePath];
+        if (!targetFile)
+          continue;
+        if (callRec.resolutionKind === "named_import_match") {
+          const targetFn = targetFile.functions.find((f) => f.displayName === callRec.calleeRoot && f.isExported);
+          if (targetFn) {
+            callRec.resolvedTargetFunctionId = targetFn.functionId;
+            callRec.confidence = "high";
+          }
+        } else if (callRec.resolutionKind === "namespace_import_property" && callRec.calleeProperty) {
+          const targetFn = targetFile.functions.find((f) => f.displayName === callRec.calleeProperty && f.isExported);
+          if (targetFn) {
+            callRec.resolvedTargetFunctionId = targetFn.functionId;
+            callRec.confidence = "high";
+          }
+        } else if (callRec.resolutionKind === "namespace_import_property" && !callRec.calleeProperty) {
+          const defaultFn = targetFile.functions.find((f) => f.displayName === "default");
+          if (defaultFn) {
+            callRec.resolvedTargetFunctionId = defaultFn.functionId;
+            callRec.confidence = "high";
           }
         }
       }
@@ -2591,14 +2609,15 @@ async function traverseCallChain(projectRoot, args) {
   const chain = [];
   const unresolvedEdges = [];
   const visited = /* @__PURE__ */ new Set();
-  const queue = seedFunctionIds.map((id) => ({ functionId: id, depth: 0 }));
+  const queue = seedFunctionIds.map((id) => ({ functionId: id, callerFunctionId: null, depth: 0 }));
   let targetReached = false;
   let truncatedAtDepth = false;
   while (queue.length > 0) {
-    const { functionId, depth } = queue.shift();
-    if (visited.has(functionId))
+    const { functionId, callerFunctionId, depth, callsite } = queue.shift();
+    const visitKey = `${callerFunctionId}->${functionId}`;
+    if (visited.has(visitKey))
       continue;
-    visited.add(functionId);
+    visited.add(visitKey);
     const indexEntry = artifact.functionIndex[functionId];
     if (!indexEntry)
       continue;
@@ -2610,63 +2629,42 @@ async function traverseCallChain(projectRoot, args) {
     const fnRec = fileRec.functions.find((f) => f.functionId === functionId);
     if (!fnRec)
       continue;
-    for (const call of fnRec.calls) {
-      if (call.resolutionKind === "semantic_action_only")
-        continue;
-      if (call.resolvedTargetFunctionId) {
-        if (depth < maxDepth) {
-          queue.push({ functionId: call.resolvedTargetFunctionId, depth: depth + 1 });
-          let isTarget = false;
-          if (targetFunctionName && call.calleeRoot === targetFunctionName)
-            isTarget = true;
-          if (isTarget)
-            targetReached = true;
-          chain.push({
-            functionId: call.resolvedTargetFunctionId,
-            displayName: call.calleeRoot,
-            filePath: call.resolvedFilePath || "unknown",
-            startLine: call.sourceLine,
-            edgeKind: "call_edge",
-            confidence: call.confidence,
-            evidenceText: call.evidenceText,
-            isTarget,
-            depth
-          });
-        } else {
-          unresolvedEdges.push({
-            fromFunctionId: functionId,
-            calleeText: call.calleeText,
-            sourceLine: call.sourceLine,
-            reason: "depth limit reached"
-          });
-          truncatedAtDepth = true;
-        }
-      } else {
-        unresolvedEdges.push({
-          fromFunctionId: functionId,
-          calleeText: call.calleeText,
-          sourceLine: call.sourceLine,
-          reason: call.resolutionKind
-        });
-      }
-    }
+    let isTarget = false;
+    if (targetFunctionName && fnRec.displayName === targetFunctionName)
+      isTarget = true;
+    if (isTarget)
+      targetReached = true;
+    chain.push({
+      functionId,
+      callerFunctionId,
+      displayName: fnRec.displayName,
+      filePath: fnRec.filePath,
+      startLine: fnRec.startLine,
+      edgeKind: "call_edge",
+      confidence: "high",
+      evidenceText: fnRec.evidenceText,
+      isTarget,
+      depth,
+      callsite
+    });
     for (const action of fnRec.semanticActions) {
-      let isTarget = false;
+      let isActionTarget = false;
       if (targetActionKind && action.actionKind === targetActionKind) {
-        isTarget = true;
+        isActionTarget = true;
         if (targetModel && action.targetModel !== targetModel)
-          isTarget = false;
+          isActionTarget = false;
         if (targetOperation && action.targetOperation !== targetOperation)
-          isTarget = false;
+          isActionTarget = false;
       } else if (targetModel && action.targetModel === targetModel) {
-        isTarget = true;
+        isActionTarget = true;
         if (targetOperation && action.targetOperation !== targetOperation)
-          isTarget = false;
+          isActionTarget = false;
       }
-      if (isTarget)
+      if (isActionTarget)
         targetReached = true;
       chain.push({
-        functionId: action.sourceFunctionId,
+        functionId: action.actionId,
+        callerFunctionId: functionId,
         displayName: action.calleeText,
         filePath: fileRec.filePath,
         startLine: action.sourceLine,
@@ -2676,10 +2674,35 @@ async function traverseCallChain(projectRoot, args) {
         targetOperation: action.targetOperation || void 0,
         confidence: action.confidence,
         evidenceText: action.evidenceText,
-        isTarget,
-        depth
+        isTarget: isActionTarget,
+        depth: depth + 1
       });
     }
+    if (depth < maxDepth) {
+      for (const call of fnRec.calls) {
+        if (call.resolvedTargetFunctionId) {
+          queue.push({
+            functionId: call.resolvedTargetFunctionId,
+            callerFunctionId: functionId,
+            depth: depth + 1,
+            callsite: {
+              file: fileRec.filePath,
+              line: call.sourceLine,
+              text: call.calleeText
+            }
+          });
+        } else {
+          unresolvedEdges.push({
+            fromFunctionId: functionId,
+            calleeText: call.calleeText,
+            sourceLine: call.sourceLine,
+            reason: call.resolutionKind
+          });
+        }
+      }
+    } else if (fnRec.calls.length > 0) {
+      truncatedAtDepth = true;
+    }
   }
   return {
     targetReached,
@@ -2895,33 +2918,13 @@ async function buildValidationReport(store, deltaTargets, projectRoot, cr) {
     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 readFile5(join6(projectRoot, rel), "utf8");
-        secondaryTrigger = PAYMENT_CONTENT_TERMS.some((t) => src.includes(t));
-      } catch {
-      }
-    }
-    if (!primaryTrigger && !secondaryTrigger)
+    const hasIntent = pf.writeIntents.includes("handle_payment_webhook");
+    const hasEffects = pf.sideEffectProfile.includes("webhook_ingress") || pf.sideEffectProfile.includes("payment_mutation");
+    const pathMentionsPayment = PAYMENT_PROVIDER_PATH_TERMS.some((t) => rel.toLowerCase().includes(t));
+    if (!hasIntent && !(hasEffects && pathMentionsPayment))
       continue;
     const webhookChecks = [
       [
@@ -3087,6 +3090,15 @@ async function readAnalysis(projectRoot) {
     return null;
   }
 }
+async function readActionBindings(projectRoot) {
+  const p = join8(projectRoot, ".vibe-splainer", "action_bindings.json");
+  try {
+    const raw = await readFile7(p, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 
 // ../brain/dist/dossier.js
 import { join as join9 } from "path";
@@ -3210,8 +3222,10 @@ var ArtifactBundleWriter = class {
   async writeBundle(artifacts) {
     const outputDir = join10(this.projectRoot, ".vibe-splainer");
     const stagingDir = join10(this.projectRoot, ".vibe-splainer.tmp");
+    const oldDir = join10(this.projectRoot, ".vibe-splainer.old");
     try {
       await rm(stagingDir, { recursive: true, force: true });
+      await rm(oldDir, { recursive: true, force: true });
       const { existsSync: existsSync5 } = await import("fs");
       const { cp } = await import("fs/promises");
       if (existsSync5(outputDir)) {
@@ -3240,8 +3254,22 @@ var ArtifactBundleWriter = class {
         artifacts: manifestArtifacts
       };
       await writeFile7(join10(stagingDir, "artifact_manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
-      await rm(outputDir, { recursive: true, force: true });
-      await rename(stagingDir, outputDir);
+      let swapped = false;
+      if (existsSync5(outputDir)) {
+        await rename(outputDir, oldDir);
+        swapped = true;
+      }
+      try {
+        await rename(stagingDir, outputDir);
+      } catch (err) {
+        if (swapped) {
+          await rename(oldDir, outputDir);
+        }
+        throw err;
+      }
+      if (swapped) {
+        await rm(oldDir, { recursive: true, force: true });
+      }
     } catch (err) {
       await rm(stagingDir, { recursive: true, force: true });
       throw err;
@@ -3281,12 +3309,37 @@ function getAllFiles(dirPath, arrayOfFiles = []) {
 }
 var HtmlRenderer = class {
   render(viewModel, _store) {
-    let templateDir = join11(__dirname2, "..", "..", "ui");
-    if (!existsSync4(templateDir)) {
-      templateDir = join11(__dirname2, "..", "..", "..", "..", "dist", "ui");
+    const candidatePaths = [
+      join11(__dirname2, "ui"),
+      // bundled: dist/index.js -> dist/ui
+      join11(__dirname2, "..", "..", "ui"),
+      // unbundled: dist/export/renderers -> dist/ui
+      join11(__dirname2, "..", "ui"),
+      // alt bundle
+      join11(__dirname2, "..", "..", "..", "ui", "dist"),
+      // dev: packages/cli/src/export/renderers -> packages/ui/dist
+      join11(__dirname2, "..", "..", "packages", "ui", "dist")
+      // repo root -> packages/ui/dist
+    ];
+    let templateDir = "";
+    for (const p of candidatePaths) {
+      if (existsSync4(p) && existsSync4(join11(p, "index.html"))) {
+        if (!existsSync4(join11(p, "vite.config.ts")) || p.endsWith("dist")) {
+          templateDir = p;
+          break;
+        }
+      }
+    }
+    if (!templateDir) {
+      for (const p of candidatePaths) {
+        if (existsSync4(join11(p, "index.html"))) {
+          templateDir = p;
+          break;
+        }
+      }
     }
-    if (!existsSync4(templateDir)) {
-      console.error("[vibe-splain] UI template not found at", templateDir, "- skipping UI regeneration");
+    if (!templateDir) {
+      console.error("[vibe-splain] UI template not found. Checked:", candidatePaths);
       return [];
     }
     const artifacts = [];
@@ -3337,8 +3390,10 @@ var DeltaRenderer = class {
 // dist/export/renderers/AgentMarkdownRenderer.js
 var AgentMarkdownRenderer = class {
   budget;
-  constructor(budget = 8e3) {
+  bindings;
+  constructor(budget = 8e3, bindings = null) {
     this.budget = budget;
+    this.bindings = bindings;
   }
   render(viewModel, store) {
     let md = `# Architectural Dossier: ${viewModel.projectRoot}
@@ -3401,6 +3456,23 @@ ${viewModel.map.brief}
         md += `**Narrative**: ${card.narrative}
 `;
       }
+      if (this.bindings && this.bindings.files[path]) {
+        const fileBinding = this.bindings.files[path];
+        const criticalFunctions = fileBinding.functions.filter((fn) => fn.semanticActions.length > 0 || fn.isEntrypoint);
+        if (criticalFunctions.length > 0) {
+          md += `
+**Critical Functions**:
+`;
+          for (const fn of criticalFunctions) {
+            md += `- \`${fn.displayName}\` (lines ${fn.startLine}-${fn.endLine})${fn.isEntrypoint ? " [Entrypoint]" : ""}
+`;
+            for (const action of fn.semanticActions) {
+              md += `  - **${action.actionKind}**${action.targetModel ? ` on ${action.targetModel}` : ""}: \`${action.calleeText}\` (line ${action.sourceLine})
+`;
+            }
+          }
+        }
+      }
       if (recs.length > 0) {
         md += `
 **Safe Patch Strategies**:
@@ -3506,6 +3578,7 @@ var ExportOrchestrator = class {
     if (!finalStore) {
       throw new Error("Analysis store not found. Scan the project first.");
     }
+    const bindings = await readActionBindings(this.projectRoot);
     for (const p of dossier.pillars) {
       p.decisions = p.decisions.filter((c) => !(c.severity === 1 && c.category === "Convention"));
       p.cardCount = p.decisions.length;
@@ -3528,7 +3601,7 @@ var ExportOrchestrator = class {
       artifacts.push(...await new HtmlRenderer().render(viewModel, finalStore));
     }
     if (formats.includes("markdown")) {
-      artifacts.push(...await new AgentMarkdownRenderer(options.budget).render(viewModel, finalStore));
+      artifacts.push(...await new AgentMarkdownRenderer(options.budget, bindings).render(viewModel, finalStore));
     }
     const writer = new ArtifactBundleWriter(this.projectRoot);
     await writer.writeBundle(artifacts);
@@ -3561,7 +3634,13 @@ import chokidar from "chokidar";
 import { createHash as createHash2 } from "crypto";
 import { readFile as readFile9 } from "fs/promises";
 import { join as join12 } from "path";
-function startWatcher(projectRoot, watchedPaths) {
+var activeWatchers = /* @__PURE__ */ new Map();
+async function startWatcher(projectRoot, watchedPaths) {
+  const existing = activeWatchers.get(projectRoot);
+  if (existing) {
+    await existing.close();
+    activeWatchers.delete(projectRoot);
+  }
   const watcher = chokidar.watch(watchedPaths.length > 0 ? watchedPaths : projectRoot, {
     ignoreInitial: true,
     ignored: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.vibe-splainer/**"],
@@ -3598,6 +3677,7 @@ function startWatcher(projectRoot, watchedPaths) {
       console.error("[vibe-splain] Watcher error:", err);
     }
   });
+  activeWatchers.set(projectRoot, watcher);
   console.error("[vibe-splain] File watcher started");
 }
 
@@ -3652,7 +3732,7 @@ async function handleScanProject(args, options = {}) {
     budget: options.budget ? parseInt(options.budget, 10) : void 0,
     scope: options.scope
   }, result.store, result.graph);
-  startWatcher(projectRoot, result.files.map((f) => f.path));
+  await startWatcher(projectRoot, result.files.map((f) => f.path));
   console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files, ${result.realSourceCount} real-source, ${result.wildCandidates.length} wild candidates.`);
   const validation = result.validation ?? { passed: true, errors: 0, warnings: 0, reportPath: ".vibe-splainer/validation_report.json" };
   let statusMsg = "Scan complete.";

package/dist/mcp/tools/scan_project.js

@@ -54,7 +54,7 @@ export async function handleScanProject(args, options = {}) {
         scope: options.scope,
     }, result.store, result.graph);
     // Watch the real-source files for staleness.
-    startWatcher(projectRoot, result.files.map(f => f.path));
+    await startWatcher(projectRoot, result.files.map(f => f.path));
     console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files, ${result.realSourceCount} real-source, ${result.wildCandidates.length} wild candidates.`);
     const validation = result.validation ?? { passed: true, errors: 0, warnings: 0, reportPath: '.vibe-splainer/validation_report.json' };
     let statusMsg = 'Scan complete.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-splain",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Architectural mapping and behavioral call-chain engine. Built on a language-agnostic foundation with specialized optimization for TypeScript/JavaScript projects.",
   "type": "module",
   "license": "MIT",