vibe-splain 1.0.0

package/dist/commands/install.d.ts

@@ -0,0 +1 @@
+export declare function installCommand(): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,78 @@
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+function expandPath(p) {
+    if (p.startsWith('~')) {
+        return join(homedir(), p.slice(1));
+    }
+    if (p.startsWith('%APPDATA%')) {
+        const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+        return join(appData, p.slice('%APPDATA%'.length));
+    }
+    return p;
+}
+const AGENT_CONFIGS = [
+    { name: 'Claude Code', path: '~/.claude/claude_desktop_config.json', format: 'claude' },
+    { name: 'Claude Code (Windows)', path: '%APPDATA%/Claude/claude_desktop_config.json', format: 'claude' },
+    { name: 'Gemini CLI', path: '~/.gemini/settings.json', format: 'gemini' },
+    { name: 'Cursor', path: '~/.cursor/mcp.json', format: 'cursor' },
+    { name: 'Windsurf', path: '~/.codeium/windsurf/mcp_config.json', format: 'cursor' },
+];
+const MCP_ENTRY = {
+    command: 'npx',
+    args: ['-y', 'vibe-splain', 'serve'],
+};
+export async function installCommand() {
+    console.error('\n🔧 VIBE-SPLAIN Installer\n');
+    let patchedCount = 0;
+    for (const agent of AGENT_CONFIGS) {
+        const resolvedPath = expandPath(agent.path);
+        if (!existsSync(resolvedPath)) {
+            continue;
+        }
+        console.error(`  Found ${agent.name} config at ${resolvedPath}`);
+        try {
+            const raw = await readFile(resolvedPath, 'utf8');
+            let config;
+            try {
+                config = JSON.parse(raw);
+            }
+            catch {
+                console.error(`    ⚠ Could not parse JSON, skipping`);
+                continue;
+            }
+            // Check idempotency
+            if (config.mcpServers?.['vibe-splain']) {
+                console.error(`    ✓ Already configured, skipping`);
+                patchedCount++;
+                continue;
+            }
+            // Patch config
+            if (!config.mcpServers) {
+                config.mcpServers = {};
+            }
+            config.mcpServers['vibe-splain'] = MCP_ENTRY;
+            await writeFile(resolvedPath, JSON.stringify(config, null, 2), 'utf8');
+            console.error(`    ✅ Patched successfully`);
+            patchedCount++;
+        }
+        catch (err) {
+            console.error(`    ❌ Error patching: ${err}`);
+        }
+    }
+    if (patchedCount === 0) {
+        console.error(`\n⚠️  No supported coding agent config found.`);
+        console.error(`Add this manually to your agent's MCP config:\n`);
+        console.error(JSON.stringify({
+            mcpServers: {
+                'vibe-splain': MCP_ENTRY
+            }
+        }, null, 2));
+        process.exit(1);
+    }
+    else {
+        console.error(`\n✅ Patched ${patchedCount} agent config(s). Restart your coding agent to activate.\n`);
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/commands/serve.d.ts

@@ -0,0 +1 @@
+export declare function serveCommand(): Promise<void>;

package/dist/commands/serve.js

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { installCommand } from './commands/install.js';
+import { serveCommand } from './commands/serve.js';
+const program = new Command();
+program
+    .name('vibe-splain')
+    .description('Architectural dossier engine for vibe-coded projects')
+    .version('1.0.0');
+program
+    .command('install')
+    .description('Patch coding agent MCP config files to register vibe-splain')
+    .action(installCommand);
+program
+    .command('serve')
+    .description('Start the MCP server (called by the coding agent, not by you)')
+    .action(serveCommand);
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/mcp/server.d.ts

@@ -0,0 +1 @@
+export declare function startMCPServer(): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,72 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { initParser } from '@vibe-splain/brain';
+import { handleScanProject, scanProjectTool } from './tools/scan_project.js';
+import { handleGetFileContext, getFileContextTool } from './tools/get_file_context.js';
+import { handleWriteDecisionCard, writeDecisionCardTool } from './tools/write_decision_card.js';
+import { handleGetStrategicOverview, getStrategicOverviewTool } from './tools/get_strategic_overview.js';
+import { handleInspectPillar, inspectPillarTool } from './tools/inspect_pillar.js';
+import { handleGetWildDiscoveries, getWildDiscoveriesTool } from './tools/get_wild_discoveries.js';
+import { handleMarkStale, markStaleTool } from './tools/mark_stale.js';
+// ⚠️ CRITICAL: Never use console.log() anywhere in this codebase.
+// stdout is owned by the MCP SDK for protocol messages.
+// Use console.error() for all diagnostic output.
+const ALL_TOOLS = [
+    scanProjectTool,
+    getFileContextTool,
+    writeDecisionCardTool,
+    getStrategicOverviewTool,
+    inspectPillarTool,
+    getWildDiscoveriesTool,
+    markStaleTool,
+];
+const TOOL_HANDLERS = {
+    scan_project: handleScanProject,
+    get_file_context: handleGetFileContext,
+    write_decision_card: handleWriteDecisionCard,
+    get_strategic_overview: handleGetStrategicOverview,
+    inspect_pillar: handleInspectPillar,
+    get_wild_discoveries: handleGetWildDiscoveries,
+    mark_stale: handleMarkStale,
+};
+export async function startMCPServer() {
+    // Initialize Tree-Sitter WASM once at startup
+    await initParser();
+    console.error('[vibe-splain] Tree-Sitter parser initialized');
+    const server = new Server({ name: 'vibe-splain', version: '1.0.0' }, { capabilities: { tools: {} } });
+    // Register tool listing
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: ALL_TOOLS,
+    }));
+    // Register tool execution
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = TOOL_HANDLERS[name];
+        if (!handler) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await handler((args || {}));
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[vibe-splain] Tool ${name} error:`, message);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[vibe-splain] MCP server running on stdio');
+    // Process stays alive — do NOT call process.exit() here
+}
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1,19 @@
+export declare const getFileContextTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            filePath: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetFileContext(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_file_context.js

@@ -0,0 +1,48 @@
+import { readFile } from 'fs/promises';
+import { join, relative } from 'path';
+import { readGraph } from '@vibe-splain/brain';
+export const getFileContextTool = {
+    name: 'get_file_context',
+    description: 'Returns the full source code of a specific high-gravity file, its cognitive weight breakdown, and its import graph neighbors. Call this for each file you want to synthesize a Decision Card for. Use the source + neighbors to understand what the code does and WHY it was written that way.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root',
+            },
+            filePath: {
+                type: 'string',
+                description: 'Relative or absolute path to the file',
+            },
+        },
+        required: ['projectRoot', 'filePath'],
+    },
+};
+export async function handleGetFileContext(args) {
+    const projectRoot = args.projectRoot;
+    const filePath = args.filePath;
+    if (!projectRoot || !filePath)
+        throw new Error('projectRoot and filePath are required');
+    const fullPath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+    const relPath = relative(projectRoot, fullPath);
+    const source = await readFile(fullPath, 'utf8');
+    const graph = await readGraph(projectRoot);
+    // Find neighbors in import graph
+    const neighbors = [];
+    if (graph) {
+        for (const edge of graph.edges) {
+            if (edge.from === relPath)
+                neighbors.push(edge.to);
+            if (edge.to === relPath || edge.to.endsWith(relPath))
+                neighbors.push(edge.from);
+        }
+    }
+    return {
+        filePath: relPath,
+        source,
+        lineCount: source.split('\n').length,
+        neighbors: [...new Set(neighbors)],
+    };
+}
+//# sourceMappingURL=get_file_context.js.map

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

@@ -0,0 +1,15 @@
+export declare const getStrategicOverviewTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetStrategicOverview(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_strategic_overview.js

@@ -0,0 +1,45 @@
+import { readDossier } from '@vibe-splain/brain';
+export const getStrategicOverviewTool = {
+    name: 'get_strategic_overview',
+    description: 'Returns the current state of the dossier without evidence snippets (to save tokens). Use this to see what has already been analyzed and what is stale. Check stalePaths to know which files need re-analysis.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root',
+            },
+        },
+        required: ['projectRoot'],
+    },
+};
+export async function handleGetStrategicOverview(args) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier) {
+        return { error: 'No dossier found. Run scan_project first.' };
+    }
+    return {
+        version: dossier.version,
+        scannedAt: dossier.scannedAt,
+        projectRoot: dossier.projectRoot,
+        pillars: dossier.pillars.map(p => ({
+            name: p.name,
+            cardCount: p.cardCount,
+            decisions: p.decisions.map(d => ({
+                id: d.id,
+                title: d.title,
+                status: d.status,
+                pillar: d.pillar,
+                // Omit evidence snippets to save tokens
+                evidenceFileCount: d.evidence.length,
+                hasDiagram: !!d.diagram,
+            })),
+        })),
+        wildDiscoveriesCount: dossier.wildDiscoveries.length,
+        stalePaths: dossier.stalePaths,
+    };
+}
+//# sourceMappingURL=get_strategic_overview.js.map

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

@@ -0,0 +1,15 @@
+export declare const getWildDiscoveriesTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetWildDiscoveries(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_wild_discoveries.js

@@ -0,0 +1,29 @@
+import { readDossier } from '@vibe-splain/brain';
+export const getWildDiscoveriesTool = {
+    name: 'get_wild_discoveries',
+    description: 'Returns files with extremely high cognitive complexity (weight ≥ 25) that don\'t fit standard patterns. These are the most surprising and important parts of the codebase to understand.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root',
+            },
+        },
+        required: ['projectRoot'],
+    },
+};
+export async function handleGetWildDiscoveries(args) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier) {
+        return { error: 'No dossier found. Run scan_project first.' };
+    }
+    return {
+        wildDiscoveries: dossier.wildDiscoveries,
+        count: dossier.wildDiscoveries.length,
+    };
+}
+//# sourceMappingURL=get_wild_discoveries.js.map

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

@@ -0,0 +1,19 @@
+export declare const inspectPillarTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            pillarName: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleInspectPillar(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/inspect_pillar.js

@@ -0,0 +1,37 @@
+import { readDossier } from '@vibe-splain/brain';
+export const inspectPillarTool = {
+    name: 'inspect_pillar',
+    description: 'Returns all Decision Cards for a specific pillar including full evidence snippets. Use when you need deep detail on a specific area of the codebase.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root',
+            },
+            pillarName: {
+                type: 'string',
+                description: 'Name of the pillar to inspect',
+            },
+        },
+        required: ['projectRoot', 'pillarName'],
+    },
+};
+export async function handleInspectPillar(args) {
+    const projectRoot = args.projectRoot;
+    const pillarName = args.pillarName;
+    if (!projectRoot || !pillarName)
+        throw new Error('projectRoot and pillarName are required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier) {
+        return { error: 'No dossier found. Run scan_project first.' };
+    }
+    const pillar = dossier.pillars.find(p => p.name === pillarName);
+    if (!pillar) {
+        return {
+            error: `Pillar "${pillarName}" not found. Available pillars: ${dossier.pillars.map(p => p.name).join(', ')}`,
+        };
+    }
+    return pillar;
+}
+//# sourceMappingURL=inspect_pillar.js.map

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

@@ -0,0 +1,22 @@
+export declare const markStaleTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            filePaths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleMarkStale(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/mark_stale.js

@@ -0,0 +1,51 @@
+import { readDossier, writeDossier } from '@vibe-splain/brain';
+export const markStaleTool = {
+    name: 'mark_stale',
+    description: 'Manually marks Decision Cards as stale when you detect a file has changed. The file watcher does this automatically, but call this if you modify a file yourself during a session.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root',
+            },
+            filePaths: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Array of relative file paths to mark as stale',
+            },
+        },
+        required: ['projectRoot', 'filePaths'],
+    },
+};
+export async function handleMarkStale(args) {
+    const projectRoot = args.projectRoot;
+    const filePaths = args.filePaths;
+    if (!projectRoot || !filePaths)
+        throw new Error('projectRoot and filePaths are required');
+    const dossier = await readDossier(projectRoot);
+    if (!dossier) {
+        return { error: 'No dossier found. Run scan_project first.' };
+    }
+    let staleCount = 0;
+    for (const filePath of filePaths) {
+        for (const pillar of dossier.pillars) {
+            for (const card of pillar.decisions) {
+                if (card.evidence.some(e => e.file === filePath || filePath.endsWith(e.file))) {
+                    card.status = 'stale';
+                    staleCount++;
+                }
+            }
+        }
+        if (!dossier.stalePaths.includes(filePath)) {
+            dossier.stalePaths.push(filePath);
+        }
+    }
+    await writeDossier(projectRoot, dossier);
+    return {
+        success: true,
+        staleCardsMarked: staleCount,
+        totalStalePaths: dossier.stalePaths.length,
+    };
+}
+//# sourceMappingURL=mark_stale.js.map

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

@@ -0,0 +1,15 @@
+export declare const scanProjectTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleScanProject(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/scan_project.js

@@ -0,0 +1,66 @@
+import { scanProject, writeDossier, readDossier, startWatcher } from '@vibe-splain/brain';
+export const scanProjectTool = {
+    name: 'scan_project',
+    description: 'Scans a codebase and returns its structural analysis. CALL THIS FIRST before any other tool. Returns High-Gravity files grouped by pillar, plus wildCandidates for unusual high-complexity files. After calling this tool, call get_file_context for each file in highGravityFiles, synthesize a narrative explaining WHY that code exists, then call write_decision_card to persist it. The uiUrl in the response is a file:// link — share it with the user so they can open the Dossier UI in their browser.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: {
+                type: 'string',
+                description: 'Absolute path to the project root directory to scan',
+            },
+        },
+        required: ['projectRoot'],
+    },
+};
+export async function handleScanProject(args) {
+    const projectRoot = args.projectRoot;
+    if (!projectRoot)
+        throw new Error('projectRoot is required');
+    console.error(`[vibe-splain] Scanning project: ${projectRoot}`);
+    const result = await scanProject(projectRoot);
+    // Create initial dossier structure
+    const existingDossier = await readDossier(projectRoot);
+    const dossier = existingDossier || {
+        version: '1.0.0',
+        scannedAt: new Date().toISOString(),
+        projectRoot,
+        pillars: [],
+        wildDiscoveries: [],
+        stalePaths: [],
+    };
+    // Update scan timestamp
+    dossier.scannedAt = new Date().toISOString();
+    // Create pillar entries from scan results
+    for (const group of result.pillarGroups) {
+        const existingPillar = dossier.pillars.find(p => p.name === group.name);
+        if (!existingPillar) {
+            dossier.pillars.push({ name: group.name, cardCount: 0, decisions: [] });
+        }
+    }
+    await writeDossier(projectRoot, dossier);
+    // Start file watcher on high-gravity files
+    const watchPaths = result.highGravityFiles.map(f => f.path);
+    startWatcher(projectRoot, watchPaths);
+    console.error(`[vibe-splain] Scan complete. ${result.totalFilesScanned} files scanned, ${result.highGravityFiles.length} high-gravity files found.`);
+    return {
+        projectRoot: result.projectRoot,
+        totalFilesScanned: result.totalFilesScanned,
+        highGravityFiles: result.highGravityFiles.map(f => ({
+            relativePath: f.relativePath,
+            cognitiveWeight: f.cognitiveWeight,
+            pillars: f.pillars,
+        })),
+        pillarGroups: result.pillarGroups.map(g => ({
+            name: g.name,
+            fileCount: g.files.length,
+            files: g.files.map(f => f.relativePath),
+        })),
+        wildCandidates: result.wildCandidates.map(f => ({
+            relativePath: f.relativePath,
+            cognitiveWeight: f.cognitiveWeight,
+        })),
+        uiUrl: result.uiUrl,
+    };
+}
+//# sourceMappingURL=scan_project.js.map

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

@@ -0,0 +1,57 @@
+export declare const writeDecisionCardTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            pillar: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            narrative: {
+                type: string;
+                description: string;
+            };
+            evidence: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        file: {
+                            type: string;
+                            description: string;
+                        };
+                        startLine: {
+                            type: string;
+                            description: string;
+                        };
+                        endLine: {
+                            type: string;
+                            description: string;
+                        };
+                        snippet: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                description: string;
+            };
+            diagram: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleWriteDecisionCard(args: Record<string, unknown>): Promise<unknown>;