vibe-splain 3.0.0 → 3.2.0

package/dist/commands/bundle.d.ts

@@ -0,0 +1,4 @@
+export declare function bundleCommand(scanId: string, opts?: {
+    output?: string;
+    projectRoot?: string;
+}): Promise<void>;

package/dist/commands/bundle.js

@@ -0,0 +1,68 @@
+import { join } from 'path';
+import { writeFile, mkdir, copyFile, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as tar from 'tar';
+import { PointerStore } from '../store/PointerStore.js';
+import { BlobStore } from '../store/BlobStore.js';
+export async function bundleCommand(scanId, opts = {}) {
+    const root = opts.projectRoot ?? process.cwd();
+    const outputPath = opts.output ?? join(root, `vibe-bundle-${scanId}.tar.gz`);
+    console.error(`[vibe-splain bundle] Bundling scan ${scanId} from ${root}`);
+    const pointerStore = PointerStore.open(root);
+    const blobStore = new BlobStore(root);
+    const pointers = pointerStore.listPointersByScan(scanId);
+    if (pointers.length === 0) {
+        throw new Error(`No pointers found for scanId "${scanId}"`);
+    }
+    // Stage bundle into a temp directory with predictable layout
+    const stagingDir = join(root, '.vibe-splainer', 'tmp', `bundle-stage-${scanId}`);
+    const blobsStageDir = join(stagingDir, 'blobs');
+    await mkdir(blobsStageDir, { recursive: true });
+    try {
+        // Build manifest for the bundle
+        const bundleManifest = {
+            schemaVersion: '1.0.0',
+            scanId,
+            exportedAt: new Date().toISOString(),
+            projectRoot: root,
+            pointers: pointers.map(p => ({
+                pointerId: p.pointerId,
+                scanId: p.scanId,
+                artifactName: p.artifactName,
+                contentHash: p.contentHash,
+                blobFile: `blobs/${p.contentHash.replace('sha256:', 'sha256_')}`,
+                schemaVersion: p.schemaVersion,
+                createdAt: p.createdAt,
+                expiresAt: p.expiresAt,
+            })),
+        };
+        await writeFile(join(stagingDir, 'bundle-manifest.json'), JSON.stringify(bundleManifest, null, 2), 'utf8');
+        // Copy blobs (deduplicated by contentHash)
+        const seen = new Set();
+        for (const p of pointers) {
+            const hex = p.contentHash.replace('sha256:', '');
+            if (seen.has(hex))
+                continue;
+            seen.add(hex);
+            const srcPath = p.blobPath;
+            if (!existsSync(srcPath)) {
+                console.error(`[vibe-splain bundle] Warning: blob missing for ${p.pointerId}: ${srcPath}`);
+                continue;
+            }
+            await copyFile(srcPath, join(blobsStageDir, `sha256_${hex}`));
+        }
+        // Create tarball from staging directory
+        await tar.create({
+            gzip: true,
+            file: outputPath,
+            cwd: stagingDir,
+            portable: true,
+        }, ['.']);
+        console.error(`[vibe-splain bundle] Bundle written: ${outputPath}`);
+        console.error(`[vibe-splain bundle] ${pointers.length} pointers, ${seen.size} blobs`);
+    }
+    finally {
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=bundle.js.map

package/dist/commands/gc.d.ts

@@ -0,0 +1,3 @@
+export declare function gcCommand(projectRoot?: string, opts?: {
+    keepScans?: number;
+}): Promise<void>;

package/dist/commands/gc.js

@@ -0,0 +1,59 @@
+import { join } from 'path';
+import { rm, readdir } from 'fs/promises';
+import { PointerStore } from '../store/PointerStore.js';
+import { BlobStore } from '../store/BlobStore.js';
+const DEFAULT_KEEP_SCANS = 3;
+export async function gcCommand(projectRoot, opts = {}) {
+    const root = projectRoot ?? process.cwd();
+    const keepScans = opts.keepScans ?? DEFAULT_KEEP_SCANS;
+    console.error(`[vibe-splain gc] Running GC on ${root} (keeping last ${keepScans} scans)`);
+    const pointerStore = PointerStore.open(root);
+    const blobStore = new BlobStore(root);
+    // 1. Get all scan IDs ordered by createdAt desc
+    const allScanIds = pointerStore.listAllScanIds();
+    console.error(`[vibe-splain gc] Found ${allScanIds.length} scans`);
+    // Keep the N most recent by taking last N from sorted list
+    // Scan IDs contain timestamps, sort lexicographically descending
+    const sorted = [...allScanIds].sort().reverse();
+    const keepIds = sorted.slice(0, keepScans);
+    const deleteIds = sorted.slice(keepScans);
+    if (deleteIds.length === 0) {
+        console.error('[vibe-splain gc] Nothing to collect');
+        return;
+    }
+    // 2. Collect all blob paths still referenced by kept pointers before deletion
+    const keptPointers = keepIds.flatMap(id => pointerStore.listPointersByScan(id));
+    const referencedBlobs = new Set(keptPointers.map(p => p.blobPath));
+    // 3. Delete old scan pointers
+    const deleted = await pointerStore.gcScanPointers(keepIds);
+    console.error(`[vibe-splain gc] Deleted ${deleted} pointer rows`);
+    // 4. Delete unreferenced blobs (reference count = 0)
+    const allBlobs = await blobStore.listBlobPaths();
+    let blobsDeleted = 0;
+    for (const blobPath of allBlobs) {
+        if (!referencedBlobs.has(blobPath)) {
+            try {
+                await rm(blobPath);
+                blobsDeleted++;
+            }
+            catch {
+                // ignore — may have already been deleted
+            }
+        }
+    }
+    console.error(`[vibe-splain gc] Deleted ${blobsDeleted} unreferenced blobs`);
+    // 5. Clean up tmp dir
+    const tmpDir = join(root, '.vibe-splainer', 'tmp');
+    try {
+        const tmpFiles = await readdir(tmpDir);
+        for (const f of tmpFiles) {
+            await rm(join(tmpDir, f), { force: true });
+        }
+        console.error(`[vibe-splain gc] Cleaned ${tmpFiles.length} tmp files`);
+    }
+    catch {
+        // tmp dir may not exist
+    }
+    console.error('[vibe-splain gc] Done');
+}
+//# sourceMappingURL=gc.js.map

package/dist/commands/importBundle.d.ts

@@ -0,0 +1,4 @@
+export declare function importBundleCommand(tarballPath: string, opts?: {
+    projectRoot?: string;
+    namespace?: string;
+}): Promise<void>;

package/dist/commands/importBundle.js

@@ -0,0 +1,80 @@
+import { join } from 'path';
+import { readFile, mkdir, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as tar from 'tar';
+import { createHash } from 'crypto';
+import { BlobStore } from '../store/BlobStore.js';
+import { PointerStore } from '../store/PointerStore.js';
+export async function importBundleCommand(tarballPath, opts = {}) {
+    const root = opts.projectRoot ?? process.cwd();
+    const namespace = opts.namespace ?? `imported_${Date.now()}`;
+    console.error(`[vibe-splain import] Importing ${tarballPath} into ${root} (namespace: ${namespace})`);
+    if (!existsSync(tarballPath)) {
+        throw new Error(`Tarball not found: ${tarballPath}`);
+    }
+    // Extract to a temp directory
+    const extractDir = join(root, '.vibe-splainer', 'tmp', `import-${namespace}`);
+    await mkdir(extractDir, { recursive: true });
+    try {
+        await tar.extract({
+            file: tarballPath,
+            cwd: extractDir,
+        });
+        // Read bundle manifest
+        const manifestPath = join(extractDir, 'bundle-manifest.json');
+        if (!existsSync(manifestPath)) {
+            throw new Error('Invalid bundle: missing bundle-manifest.json');
+        }
+        const manifestRaw = await readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(manifestRaw);
+        if (manifest.schemaVersion !== '1.0.0') {
+            throw new Error(`Unsupported bundle schema version: ${manifest.schemaVersion}`);
+        }
+        const blobStore = new BlobStore(root);
+        const pointerStore = PointerStore.open(root);
+        await blobStore.ensureDirs();
+        let imported = 0;
+        let hashErrors = 0;
+        for (const entry of manifest.pointers) {
+            const blobSrcPath = join(extractDir, entry.blobFile);
+            if (!existsSync(blobSrcPath)) {
+                console.error(`[vibe-splain import] Missing blob for pointer ${entry.pointerId}: ${entry.blobFile}`);
+                hashErrors++;
+                continue;
+            }
+            // Verify hash before importing
+            const content = await readFile(blobSrcPath);
+            const actualHash = `sha256:${createHash('sha256').update(content).digest('hex')}`;
+            if (actualHash !== entry.contentHash) {
+                console.error(`[vibe-splain import] Hash mismatch for ${entry.pointerId}: expected ${entry.contentHash}, got ${actualHash}`);
+                hashErrors++;
+                continue;
+            }
+            // Write blob to local store (atomic)
+            const { blobPath } = await blobStore.writeAtomic(content);
+            // Insert pointer under bundle namespace alias
+            const namespacedPointerId = `${namespace}::${entry.pointerId}`;
+            const namespacedScanId = `${namespace}::${entry.scanId}`;
+            await pointerStore.insertPointer({
+                pointerId: namespacedPointerId,
+                scanId: namespacedScanId,
+                artifactName: entry.artifactName,
+                contentHash: entry.contentHash,
+                blobPath,
+                schemaVersion: entry.schemaVersion,
+                createdAt: entry.createdAt,
+                expiresAt: entry.expiresAt,
+            });
+            imported++;
+        }
+        if (hashErrors > 0) {
+            console.error(`[vibe-splain import] Warning: ${hashErrors} blobs failed hash verification and were skipped`);
+        }
+        console.error(`[vibe-splain import] Imported ${imported}/${manifest.pointers.length} pointers under namespace "${namespace}"`);
+        console.error(`[vibe-splain import] Original scanId: ${manifest.scanId} → namespaced as: ${namespace}::${manifest.scanId}`);
+    }
+    finally {
+        await rm(extractDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=importBundle.js.map

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.d.ts

@@ -4,9 +4,27 @@ export interface ExportOptions {
     budget?: number;
     scope?: string;
 }
+export interface ManifestArtifactEntry {
+    name: string;
+    pointer: string;
+    contentHash: string;
+    sizeBytes: number;
+    indexes?: Record<string, string>;
+    hydrators?: string[];
+}
+export interface ScanManifest {
+    schemaVersion: '2.0.0';
+    scanId: string;
+    generatedAt: string;
+    projectRoot: string;
+    artifacts: ManifestArtifactEntry[];
+}
 export declare class ExportOrchestrator {
     private projectRoot;
     constructor(projectRoot: string);
-    writeBundle(dossier: Dossier, options?: ExportOptions, store?: AnalysisStore, graph?: ImportGraph): Promise<void>;
+    writeBundle(dossier: Dossier, options?: ExportOptions, store?: AnalysisStore, graph?: ImportGraph, scanId?: string): Promise<{
+        scanId: string;
+        manifestPointer: string;
+    }>;
     private buildViewModel;
 }

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';
@@ -7,16 +7,20 @@ import { AgentMarkdownRenderer } from './renderers/AgentMarkdownRenderer.js';
 import { ValidationRenderer } from './renderers/ValidationRenderer.js';
 import { RawAnalysisRenderer } from './renderers/RawAnalysisRenderer.js';
 import { GraphRenderer } from './renderers/GraphRenderer.js';
+import { BlobStore } from '../store/BlobStore.js';
+import { PointerStore } from '../store/PointerStore.js';
+import { v4 as uuidv4 } from 'uuid';
 export class ExportOrchestrator {
     projectRoot;
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
-    async writeBundle(dossier, options = {}, store, graph) {
+    async writeBundle(dossier, options = {}, store, graph, scanId) {
         const finalStore = store || await readAnalysis(this.projectRoot);
         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,10 +46,93 @@ 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);
+        // Register artifacts in BlobStore + PointerStore and build manifest
+        const effectiveScanId = scanId ?? `scan_${Date.now()}`;
+        const blobStore = new BlobStore(this.projectRoot);
+        const pointerStore = PointerStore.open(this.projectRoot);
+        const now = Date.now();
+        const manifestEntries = [];
+        for (const artifact of artifacts) {
+            const content = typeof artifact.content === 'string'
+                ? Buffer.from(artifact.content, 'utf8')
+                : artifact.content;
+            const { contentHash, blobPath } = await blobStore.writeAtomic(content);
+            const pointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+            await pointerStore.insertPointer({
+                pointerId,
+                scanId: effectiveScanId,
+                artifactName: artifact.type,
+                contentHash,
+                blobPath,
+                schemaVersion: '1.0.0',
+                createdAt: now,
+                expiresAt: null,
+            });
+            const entry = {
+                name: artifact.type,
+                pointer: pointerId,
+                contentHash,
+                sizeBytes: content.length,
+            };
+            // Attach hydrator hints for the large analysis artifact
+            if (artifact.type === 'analysis') {
+                entry.hydrators = ['get_project_summary', 'get_start_here'];
+                // Generate analysis.index.json (Start-Here + Top-Heat)
+                const analysisIndex = {
+                    schemaVersion: '1.0.0',
+                    scanId: effectiveScanId,
+                    startHere: dossier.map.topGravity.slice(0, 12),
+                    topHeat: dossier.map.topHeat.slice(0, 12),
+                    pillarSummary: dossier.map.pillars.map(p => ({
+                        name: p.name,
+                        fileCount: p.memberFiles?.length ?? 0,
+                    })),
+                    totalFiles: Object.keys(finalStore.files).length,
+                    realSourceFiles: Object.values(finalStore.files).filter(f => f.isRealSource).length,
+                };
+                const indexContent = Buffer.from(JSON.stringify(analysisIndex, null, 2), 'utf8');
+                const indexWrite = await blobStore.writeAtomic(indexContent);
+                const indexPointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+                await pointerStore.insertPointer({
+                    pointerId: indexPointerId,
+                    scanId: effectiveScanId,
+                    artifactName: 'analysis.index',
+                    contentHash: indexWrite.contentHash,
+                    blobPath: indexWrite.blobPath,
+                    schemaVersion: '1.0.0',
+                    createdAt: now,
+                    expiresAt: null,
+                });
+                entry.indexes = { startHere: indexPointerId };
+            }
+            manifestEntries.push(entry);
+        }
+        // Write and register the scan manifest itself
+        const manifest = {
+            schemaVersion: '2.0.0',
+            scanId: effectiveScanId,
+            generatedAt: new Date(now).toISOString(),
+            projectRoot: this.projectRoot,
+            artifacts: manifestEntries,
+        };
+        const manifestContent = Buffer.from(JSON.stringify(manifest, null, 2), 'utf8');
+        const manifestWrite = await blobStore.writeAtomic(manifestContent);
+        const manifestPointerId = `ptr_manifest_${effectiveScanId}`;
+        await pointerStore.insertPointer({
+            pointerId: manifestPointerId,
+            scanId: effectiveScanId,
+            artifactName: 'artifact_manifest',
+            contentHash: manifestWrite.contentHash,
+            blobPath: manifestWrite.blobPath,
+            schemaVersion: '2.0.0',
+            createdAt: now,
+            expiresAt: null,
+        });
+        return { scanId: effectiveScanId, manifestPointer: manifestPointerId };
     }
     buildViewModel(dossier, store) {
         const recommendations = {};

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 = [];