vibe-splain 2.7.3 → 3.0.0

package/dist/commands/export.d.ts

@@ -0,0 +1 @@
+export declare function exportCommand(projectRoot: string, options: any): Promise<void>;

package/dist/commands/export.js

@@ -0,0 +1,19 @@
+import { readDossier } from '@vibe-splain/brain';
+import { ExportOrchestrator } from '../export/ExportOrchestrator.js';
+export async function exportCommand(projectRoot, options) {
+    const root = projectRoot || process.cwd();
+    console.error(`[vibe-splain] Exporting dossier for ${root}`);
+    const dossier = await readDossier(root);
+    if (!dossier) {
+        console.error('[vibe-splain] Dossier not found. Run scan first.');
+        process.exit(1);
+    }
+    const orchestrator = new ExportOrchestrator(root);
+    await orchestrator.writeBundle(dossier, {
+        format: options.format,
+        budget: options.budget ? parseInt(options.budget, 10) : undefined,
+        scope: options.scope,
+    });
+    console.error('[vibe-splain] Export complete.');
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/serve.d.ts

@@ -1 +1 @@
-export declare function serveCommand(): Promise<void>;
+export declare function serveCommand(options?: any): Promise<void>;

package/dist/commands/serve.js

@@ -1,7 +1,7 @@
 import { startMCPServer } from '../mcp/server.js';
-export async function serveCommand() {
+export async function serveCommand(options) {
     console.error('[vibe-splain] Starting MCP server...');
-    await startMCPServer();
+    await startMCPServer(options);
     // Process stays alive — do NOT call process.exit() here
 }
 //# sourceMappingURL=serve.js.map

package/dist/export/ArtifactBundleWriter.d.ts

@@ -0,0 +1,22 @@
+export interface Artifact {
+    type: string;
+    path: string;
+    content: string | Buffer;
+}
+export interface ManifestArtifact {
+    type: string;
+    path: string;
+    checksum: string;
+    sizeBytes: number;
+}
+export interface ArtifactManifest {
+    schemaVersion: string;
+    generatedAt: string;
+    projectRoot: string;
+    artifacts: ManifestArtifact[];
+}
+export declare class ArtifactBundleWriter {
+    private projectRoot;
+    constructor(projectRoot: string);
+    writeBundle(artifacts: Artifact[]): Promise<void>;
+}

package/dist/export/ArtifactBundleWriter.js

@@ -0,0 +1,56 @@
+import { join } from 'path';
+import { writeFile, mkdir, rm, rename } from 'fs/promises';
+import { createHash } from 'crypto';
+export class ArtifactBundleWriter {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    async writeBundle(artifacts) {
+        const outputDir = join(this.projectRoot, '.vibe-splainer');
+        const stagingDir = join(this.projectRoot, '.vibe-splainer.tmp');
+        try {
+            await rm(stagingDir, { recursive: true, force: true });
+            const { existsSync } = await import('fs');
+            const { cp } = await import('fs/promises');
+            if (existsSync(outputDir)) {
+                await cp(outputDir, stagingDir, { recursive: true });
+            }
+            else {
+                await mkdir(stagingDir, { recursive: true });
+            }
+            const manifestArtifacts = [];
+            for (const artifact of artifacts) {
+                const destPath = join(stagingDir, artifact.path);
+                await mkdir(join(destPath, '..'), { recursive: true });
+                await writeFile(destPath, artifact.content);
+                const contentStr = artifact.content;
+                const buffer = typeof contentStr === 'string' ? Buffer.from(contentStr, 'utf-8') : contentStr;
+                manifestArtifacts.push({
+                    type: artifact.type,
+                    path: artifact.path,
+                    checksum: 'sha256:' + createHash('sha256').update(buffer).digest('hex'),
+                    sizeBytes: buffer.length,
+                });
+            }
+            const manifest = {
+                schemaVersion: '1.0.0',
+                generatedAt: new Date().toISOString(),
+                projectRoot: this.projectRoot,
+                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);
+        }
+        catch (err) {
+            await rm(stagingDir, { recursive: true, force: true });
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=ArtifactBundleWriter.js.map

package/dist/export/ExportOrchestrator.d.ts

@@ -0,0 +1,12 @@
+import type { Dossier, AnalysisStore, ImportGraph } from '@vibe-splain/brain';
+export interface ExportOptions {
+    format?: 'json' | 'html' | 'markdown' | 'delta';
+    budget?: number;
+    scope?: string;
+}
+export declare class ExportOrchestrator {
+    private projectRoot;
+    constructor(projectRoot: string);
+    writeBundle(dossier: Dossier, options?: ExportOptions, store?: AnalysisStore, graph?: ImportGraph): Promise<void>;
+    private buildViewModel;
+}

package/dist/export/ExportOrchestrator.js

@@ -0,0 +1,72 @@
+import { readAnalysis, RecommendationEngine } from '@vibe-splain/brain';
+import { ArtifactBundleWriter } from './ArtifactBundleWriter.js';
+import { JsonRenderer } from './renderers/JsonRenderer.js';
+import { HtmlRenderer } from './renderers/HtmlRenderer.js';
+import { DeltaRenderer } from './renderers/DeltaRenderer.js';
+import { AgentMarkdownRenderer } from './renderers/AgentMarkdownRenderer.js';
+import { ValidationRenderer } from './renderers/ValidationRenderer.js';
+import { RawAnalysisRenderer } from './renderers/RawAnalysisRenderer.js';
+import { GraphRenderer } from './renderers/GraphRenderer.js';
+export class ExportOrchestrator {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    async writeBundle(dossier, options = {}, store, graph) {
+        const finalStore = store || await readAnalysis(this.projectRoot);
+        if (!finalStore) {
+            throw new Error('Analysis store not found. Scan the project first.');
+        }
+        // Aggressive Boilerplate Culling
+        for (const p of dossier.pillars) {
+            p.decisions = p.decisions.filter(c => !(c.severity === 1 && c.category === 'Convention'));
+            p.cardCount = p.decisions.length;
+        }
+        const viewModel = this.buildViewModel(dossier, finalStore);
+        // Always render JSON, Delta, Validation, and Raw Analysis.
+        const artifacts = [];
+        artifacts.push(...await new JsonRenderer().render(viewModel, finalStore));
+        artifacts.push(...await new DeltaRenderer().render(viewModel, finalStore));
+        artifacts.push(...await new ValidationRenderer().render(viewModel, finalStore));
+        artifacts.push(...await new RawAnalysisRenderer().render(viewModel, finalStore));
+        if (graph) {
+            artifacts.push(...await new GraphRenderer(graph).render(viewModel, finalStore));
+        }
+        // Determine additional formats
+        const formats = ['html', 'markdown']; // default
+        if (options.format && options.format !== 'json' && options.format !== 'delta') {
+            formats.length = 0;
+            formats.push(options.format);
+        }
+        if (formats.includes('html')) {
+            artifacts.push(...await new HtmlRenderer().render(viewModel, finalStore));
+        }
+        if (formats.includes('markdown')) {
+            artifacts.push(...await new AgentMarkdownRenderer(options.budget).render(viewModel, finalStore));
+        }
+        const writer = new ArtifactBundleWriter(this.projectRoot);
+        await writer.writeBundle(artifacts);
+    }
+    buildViewModel(dossier, store) {
+        const recommendations = {};
+        for (const file of dossier.map.topGravity) {
+            const persisted = store.files[file];
+            if (persisted) {
+                recommendations[file] = RecommendationEngine.generateRecommendations(persisted);
+            }
+        }
+        for (const file of dossier.map.topHeat) {
+            if (!recommendations[file]) {
+                const persisted = store.files[file];
+                if (persisted) {
+                    recommendations[file] = RecommendationEngine.generateRecommendations(persisted);
+                }
+            }
+        }
+        return {
+            ...dossier,
+            recommendations,
+        };
+    }
+}
+//# sourceMappingURL=ExportOrchestrator.js.map

package/dist/export/Watcher.d.ts

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

package/dist/export/Watcher.js

@@ -0,0 +1,47 @@
+import chokidar from 'chokidar';
+import { createHash } from 'crypto';
+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 watcher = chokidar.watch(watchedPaths.length > 0 ? watchedPaths : projectRoot, {
+        ignoreInitial: true,
+        ignored: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.vibe-splainer/**'],
+        persistent: true,
+    });
+    watcher.on('change', async (filepath) => {
+        try {
+            const dossier = await readDossier(projectRoot);
+            if (!dossier)
+                return;
+            const content = await readFile(filepath, 'utf8');
+            const newHash = createHash('sha256').update(content).digest('hex');
+            let mutated = false;
+            for (const pillar of dossier.pillars) {
+                for (const card of pillar.decisions) {
+                    if (!card.primaryFile)
+                        continue;
+                    const absMatch = filepath === join(projectRoot, card.primaryFile) || filepath.endsWith('/' + card.primaryFile);
+                    if (absMatch && card.lastScannedHash !== newHash) {
+                        card.status = 'stale';
+                        const rel = card.primaryFile;
+                        if (!dossier.stalePaths.includes(rel))
+                            dossier.stalePaths.push(rel);
+                        mutated = true;
+                    }
+                }
+            }
+            if (mutated) {
+                const orchestrator = new ExportOrchestrator(projectRoot);
+                await orchestrator.writeBundle(dossier);
+                console.error(`[vibe-splain] File changed: ${filepath}. Dossier artifacts updated.`);
+            }
+        }
+        catch (err) {
+            console.error('[vibe-splain] Watcher error:', err);
+        }
+    });
+    console.error('[vibe-splain] File watcher started');
+}
+//# sourceMappingURL=Watcher.js.map

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

@@ -0,0 +1,8 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class AgentMarkdownRenderer implements Renderer {
+    private budget;
+    constructor(budget?: number);
+    render(viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/AgentMarkdownRenderer.js

@@ -0,0 +1,90 @@
+export class AgentMarkdownRenderer {
+    budget;
+    constructor(budget = 8000) {
+        this.budget = budget;
+    }
+    render(viewModel, store) {
+        let md = `# Architectural Dossier: ${viewModel.projectRoot}\n\n`;
+        if (viewModel.map.brief) {
+            md += `## Project Brief\n${viewModel.map.brief}\n\n`;
+        }
+        md += `## Stack & Entrypoints\n`;
+        md += `- Stack: ${viewModel.map.stack.join(', ')}\n`;
+        md += `- Entrypoints: ${viewModel.map.entrypoints.join(', ')}\n\n`;
+        // Flatten decisions
+        const allDecisions = viewModel.pillars.flatMap(p => p.decisions).concat(viewModel.wildDiscoveries);
+        const uniqueDecisions = new Map();
+        for (const d of allDecisions) {
+            if (d.primaryFile && !uniqueDecisions.has(d.primaryFile)) {
+                uniqueDecisions.set(d.primaryFile, d);
+            }
+        }
+        const tier1 = [];
+        const tier2 = [];
+        const tier3 = [];
+        // Sort files by gravity
+        const sortedFiles = Object.values(store.files)
+            .filter(f => f.isRealSource)
+            .sort((a, b) => b.gravity - a.gravity);
+        for (const f of sortedFiles) {
+            const card = uniqueDecisions.get(f.relativePath);
+            const isCritical = card && card.severity >= 4;
+            if (f.gravity >= 70 || isCritical) {
+                tier1.push(f.relativePath);
+            }
+            else if (f.gravity >= 40 || card) {
+                tier2.push(f.relativePath);
+            }
+            else {
+                tier3.push(f.relativePath);
+            }
+        }
+        md += `## Tier 1: Critical Files & Risks\n\n`;
+        for (const path of tier1) {
+            const f = store.files[path];
+            const card = uniqueDecisions.get(path);
+            const recs = viewModel.recommendations[path] || [];
+            md += `### ${path}\n`;
+            md += `- Gravity: ${Math.round(f.gravity)} | Heat: ${Math.round(f.heat)}\n`;
+            md += `- Domain: ${f.productDomain} | Role: ${f.frameworkRole}\n`;
+            if (card) {
+                md += `\n**Verdict**: ${card.thesis}\n`;
+                md += `**Severity**: ${card.severity} | **Category**: ${card.category}\n`;
+                md += `**Narrative**: ${card.narrative}\n`;
+            }
+            if (recs.length > 0) {
+                md += `\n**Safe Patch Strategies**:\n`;
+                for (const r of recs) {
+                    md += `- **${r.strategy}**: ${r.description}\n`;
+                }
+            }
+            md += `\n---\n\n`;
+        }
+        md += `## Tier 2: Important Files\n\n`;
+        for (const path of tier2) {
+            const f = store.files[path];
+            const card = uniqueDecisions.get(path);
+            md += `- **${path}** (Gravity: ${Math.round(f.gravity)})`;
+            if (card) {
+                md += ` — ${card.thesis}`;
+            }
+            md += `\n`;
+        }
+        md += `\n`;
+        md += `## Tier 3: Index\n\n`;
+        for (const path of tier3) {
+            const f = store.files[path];
+            md += `- ${path} (Gravity: ${Math.round(f.gravity)})\n`;
+        }
+        // In a real robust implementation, we would truncate tiers starting from Tier 3 to fit the budget.
+        // Given the simplicity, we'll return the full markdown. 
+        return [
+            {
+                type: 'markdown',
+                path: 'dossier.agent.md',
+                content: md,
+            }
+        ];
+    }
+}
+//# sourceMappingURL=AgentMarkdownRenderer.js.map

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

@@ -0,0 +1,6 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class DeltaRenderer implements Renderer {
+    render(_viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/DeltaRenderer.js

@@ -0,0 +1,22 @@
+export class DeltaRenderer {
+    render(_viewModel, store) {
+        const deltaTargets = Object.values(store.files)
+            .filter(pf => pf.isRealSource)
+            .sort((a, b) => b.gravity - a.gravity)
+            .map(pf => ({
+            path: pf.relativePath,
+            gravity: Math.round(pf.gravity),
+            isLoadBearing: pf.canonicalLoadBearing,
+            blastRadius: pf.importedBy,
+            pillarHint: pf.pillarHint,
+        }));
+        return [
+            {
+                type: 'delta',
+                path: 'delta_targets.json',
+                content: JSON.stringify(deltaTargets, null, 2),
+            }
+        ];
+    }
+}
+//# sourceMappingURL=DeltaRenderer.js.map

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

@@ -0,0 +1,9 @@
+import { type ImportGraph } from '@vibe-splain/brain';
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class GraphRenderer implements Renderer {
+    private graph?;
+    constructor(graph?: ImportGraph | undefined);
+    render(_viewModel: DossierViewModel, _store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/GraphRenderer.js

@@ -0,0 +1,18 @@
+export class GraphRenderer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    render(_viewModel, _store) {
+        if (!this.graph)
+            return [];
+        return [
+            {
+                type: 'graph',
+                path: 'graph.json',
+                content: JSON.stringify(this.graph, null, 2),
+            }
+        ];
+    }
+}
+//# sourceMappingURL=GraphRenderer.js.map

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

@@ -0,0 +1,6 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class HtmlRenderer implements Renderer {
+    render(viewModel: DossierViewModel, _store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/HtmlRenderer.js

@@ -0,0 +1,54 @@
+import { join, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getAllFiles(dirPath, arrayOfFiles = []) {
+    const files = readdirSync(dirPath);
+    files.forEach(function (file) {
+        const fullPath = join(dirPath, file);
+        if (statSync(fullPath).isDirectory()) {
+            arrayOfFiles = getAllFiles(fullPath, arrayOfFiles);
+        }
+        else {
+            arrayOfFiles.push(fullPath);
+        }
+    });
+    return 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');
+        }
+        if (!existsSync(templateDir)) {
+            console.error('[vibe-splain] UI template not found at', templateDir, '- skipping UI regeneration');
+            return [];
+        }
+        const artifacts = [];
+        const allFiles = getAllFiles(templateDir);
+        for (const file of allFiles) {
+            const relPath = relative(templateDir, file);
+            if (relPath === 'index.html') {
+                const templateHtml = readFileSync(file, 'utf8');
+                const injection = `<script>window.__VIBE_DOSSIER__ = ${JSON.stringify(viewModel)};</script>`;
+                const bakedHtml = templateHtml.replace('<!-- VIBE_DOSSIER_INJECTION_POINT -->', injection);
+                artifacts.push({
+                    type: 'html',
+                    path: join('ui', relPath),
+                    content: bakedHtml,
+                });
+            }
+            else {
+                artifacts.push({
+                    type: 'asset',
+                    path: join('ui', relPath),
+                    content: readFileSync(file),
+                });
+            }
+        }
+        return artifacts;
+    }
+}
+//# sourceMappingURL=HtmlRenderer.js.map

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

@@ -0,0 +1,6 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class JsonRenderer implements Renderer {
+    render(viewModel: DossierViewModel, _store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/JsonRenderer.js

@@ -0,0 +1,12 @@
+export class JsonRenderer {
+    render(viewModel, _store) {
+        return [
+            {
+                type: 'dossier',
+                path: 'dossier.json',
+                content: JSON.stringify(viewModel, null, 2),
+            }
+        ];
+    }
+}
+//# sourceMappingURL=JsonRenderer.js.map

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

@@ -0,0 +1,6 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class RawAnalysisRenderer implements Renderer {
+    render(_viewModel: DossierViewModel, store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/RawAnalysisRenderer.js

@@ -0,0 +1,12 @@
+export class RawAnalysisRenderer {
+    render(_viewModel, store) {
+        return [
+            {
+                type: 'analysis',
+                path: 'analysis.json',
+                content: JSON.stringify(store, null, 2),
+            }
+        ];
+    }
+}
+//# sourceMappingURL=RawAnalysisRenderer.js.map

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

@@ -0,0 +1,5 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export interface Renderer {
+    render(viewModel: DossierViewModel, store: AnalysisStore): Promise<Artifact[]> | Artifact[];
+}

package/dist/export/renderers/Renderer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Renderer.js.map

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

@@ -0,0 +1,6 @@
+import type { DossierViewModel, AnalysisStore } from '@vibe-splain/brain';
+import type { Renderer } from './Renderer.js';
+import type { Artifact } from '../ArtifactBundleWriter.js';
+export declare class ValidationRenderer implements Renderer {
+    render(viewModel: DossierViewModel, _store: AnalysisStore): Artifact[];
+}

package/dist/export/renderers/ValidationRenderer.js

@@ -0,0 +1,14 @@
+export class ValidationRenderer {
+    render(viewModel, _store) {
+        if (!viewModel.map.validation)
+            return [];
+        return [
+            {
+                type: 'validation',
+                path: 'validation_report.json',
+                content: JSON.stringify(viewModel.map.validation, null, 2),
+            }
+        ];
+    }
+}
+//# sourceMappingURL=ValidationRenderer.js.map