vibe-splain 3.0.0 → 3.2.0

package/dist/mcp/tools/hydration/get_start_here.d.ts

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

package/dist/mcp/tools/hydration/get_start_here.js

@@ -0,0 +1,52 @@
+import { hydratePointer, applyBudgetGuard } from '../../BudgetGuard.js';
+export const getStartHereTool = {
+    name: 'get_start_here',
+    description: 'Hydrates the start-here index for a scan manifest pointer. Returns the top 5 highest-gravity files. Pointer must be valid and unexpired.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            manifestPointer: { type: 'string', description: 'Pointer ID for the scan manifest or analysis.index artifact' },
+            scanId: { type: 'string', description: 'Current scan ID for budget pointer registration' },
+        },
+        required: ['projectRoot', 'manifestPointer', 'scanId'],
+    },
+};
+export async function handleGetStartHere(args) {
+    const projectRoot = args.projectRoot;
+    const manifestPointer = args.manifestPointer;
+    const scanId = args.scanId;
+    if (!projectRoot || !manifestPointer || !scanId) {
+        throw new Error('projectRoot, manifestPointer, and scanId are required');
+    }
+    // 1. Verify pointer exists, unexpired, hash matches blob
+    const { content, row } = await hydratePointer(projectRoot, manifestPointer);
+    const payload = JSON.parse(content.toString('utf8'));
+    // 2. If it's a manifest pointer, find the analysis.index pointer
+    if (row.artifactName === 'artifact_manifest') {
+        const manifest = payload;
+        const analysisEntry = manifest.artifacts.find(a => a.name === 'analysis' || a.name === 'analysis.index');
+        if (!analysisEntry?.indexes?.startHere) {
+            throw new Error('Manifest has no analysis.index entry — rescan to regenerate');
+        }
+        const { content: indexContent } = await hydratePointer(projectRoot, analysisEntry.indexes.startHere);
+        const index = JSON.parse(indexContent.toString('utf8'));
+        const result = {
+            startHere: index.startHere.slice(0, 5),
+            schemaVersion: index.schemaVersion,
+            scanId: index.scanId,
+        };
+        return await applyBudgetGuard(projectRoot, scanId, 'get_start_here_result', result);
+    }
+    // 3. If it's an analysis.index pointer directly
+    if (row.artifactName === 'analysis.index') {
+        const result = {
+            startHere: payload.startHere.slice(0, 5),
+            schemaVersion: payload.schemaVersion,
+            scanId: payload.scanId,
+        };
+        return await applyBudgetGuard(projectRoot, scanId, 'get_start_here_result', result);
+    }
+    throw new Error(`Unsupported artifact type for get_start_here: ${row.artifactName}`);
+}
+//# sourceMappingURL=get_start_here.js.map

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

@@ -0,0 +1,31 @@
+export declare const readFileTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            filePath: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+            startLine: {
+                type: string;
+                description: string;
+            };
+            endLine: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleReadFile(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/read_file.js

@@ -0,0 +1,90 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { SessionScope, ScopeViolation } from '../SessionScope.js';
+import { hashFile } from '../../store/BlobStore.js';
+import { BlobStore } from '../../store/BlobStore.js';
+import { PointerStore } from '../../store/PointerStore.js';
+import { applyBudgetGuard } from '../BudgetGuard.js';
+import { v4 as uuidv4 } from 'uuid';
+export const readFileTool = {
+    name: 'read_file',
+    description: 'Reads a file within the active workOrder scope. Enforces allowedFiles/allowedGlobs/deniedGlobs. Records content hash. Output is budgeted.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            filePath: { type: 'string', description: 'Path relative to projectRoot' },
+            scanId: { type: 'string', description: 'Current scan ID for pointer registration' },
+            startLine: { type: 'number', description: 'Optional: 1-based start line to return a slice' },
+            endLine: { type: 'number', description: 'Optional: 1-based end line (inclusive). Capped at startLine+500.' },
+        },
+        required: ['projectRoot', 'filePath', 'scanId'],
+    },
+};
+export async function handleReadFile(args) {
+    const projectRoot = args.projectRoot;
+    const filePath = args.filePath;
+    const scanId = args.scanId;
+    const startLine = args.startLine !== undefined ? Number(args.startLine) : undefined;
+    const endLine = args.endLine !== undefined
+        ? Math.min(Number(args.endLine), (startLine ?? 1) + 500)
+        : undefined;
+    if (!projectRoot || !filePath || !scanId) {
+        throw new Error('projectRoot, filePath, and scanId are required');
+    }
+    // 1. Scope enforcement
+    try {
+        SessionScope.enforce(filePath);
+    }
+    catch (e) {
+        if (e instanceof ScopeViolation)
+            throw e;
+        throw e;
+    }
+    const absolutePath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+    // 2. Read file
+    let content;
+    try {
+        content = await readFile(absolutePath, 'utf8');
+    }
+    catch {
+        throw new Error(`FileNotFound: cannot read ${filePath}`);
+    }
+    // 3. Content hash recording
+    const contentHash = await hashFile(absolutePath);
+    // 4. Apply line slice if requested
+    let output = content;
+    let sliceInfo;
+    if (startLine !== undefined) {
+        const lines = content.split('\n');
+        const end = endLine ?? lines.length;
+        output = lines.slice(startLine - 1, end).join('\n');
+        sliceInfo = { startLine, endLine: end, totalLines: lines.length };
+    }
+    // 5. Record content hash in pointer store
+    const blobStore = new BlobStore(projectRoot);
+    const pointerStore = PointerStore.open(projectRoot);
+    const { blobPath } = await blobStore.writeAtomic(content);
+    const pointerId = `ptr_file_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
+    await pointerStore.insertPointer({
+        pointerId,
+        scanId,
+        artifactName: 'file_read',
+        contentHash,
+        blobPath,
+        schemaVersion: '1.0.0',
+        createdAt: Date.now(),
+        expiresAt: null,
+    });
+    const result = {
+        filePath,
+        contentHash,
+        pointerId,
+        content: output,
+    };
+    if (sliceInfo)
+        result.slice = sliceInfo;
+    // 6. Budget enforcement
+    return await applyBudgetGuard(projectRoot, scanId, 'file_read', result);
+}
+//# sourceMappingURL=read_file.js.map

package/dist/mcp/tools/scan_project.js

@@ -47,14 +47,15 @@ export async function handleScanProject(args, options = {}) {
             dossier.pillars.push({ name: def.name, cardCount: 0, decisions: [] });
         }
     }
+    const scanId = `scan_${Date.now()}`;
     const orchestrator = new ExportOrchestrator(projectRoot);
-    await orchestrator.writeBundle(dossier, {
+    const { manifestPointer } = await orchestrator.writeBundle(dossier, {
         format: options.format,
         budget: options.budget ? parseInt(options.budget, 10) : undefined,
         scope: options.scope,
-    }, result.store, result.graph);
+    }, result.store, result.graph, scanId);
     // 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.';
@@ -64,6 +65,8 @@ export async function handleScanProject(args, options = {}) {
     return {
         ok: true,
         message: statusMsg,
+        scanId,
+        manifestPointer,
         validation: {
             passed: validation.passed,
             errors: validation.errors,

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

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

package/dist/mcp/tools/set_session_scope.js

@@ -0,0 +1,40 @@
+import { PointerStore } from '../../store/PointerStore.js';
+import { SessionScope } from '../SessionScope.js';
+export const setSessionScopeTool = {
+    name: 'set_session_scope',
+    description: 'Sets the active session scope from a Work Order. All subsequent file tools (read_file, get_file_skeleton, apply_patch) will enforce this scope until overwritten or the server restarts.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            workOrderId: { type: 'string', description: 'Work Order ID to load scope from' },
+        },
+        required: ['projectRoot', 'workOrderId'],
+    },
+};
+export async function handleSetSessionScope(args) {
+    const projectRoot = args.projectRoot;
+    const workOrderId = args.workOrderId;
+    if (!projectRoot || !workOrderId) {
+        throw new Error('projectRoot and workOrderId are required');
+    }
+    const pointerStore = PointerStore.open(projectRoot);
+    const row = pointerStore.getWorkOrder(workOrderId);
+    if (!row) {
+        throw new Error(`WorkOrderNotFound: ${workOrderId}`);
+    }
+    const policy = SessionScope.fromWorkOrderRow(row);
+    SessionScope.set(policy);
+    return {
+        ok: true,
+        workOrderId,
+        scope: {
+            allowedFiles: policy.allowedFiles,
+            allowedGlobs: policy.allowedGlobs,
+            deniedGlobs: policy.deniedGlobs,
+            requiredProofCount: policy.requiredProof.length,
+        },
+        message: `Session scope set from work order ${workOrderId}. All file tools will enforce this scope.`,
+    };
+}
+//# sourceMappingURL=set_session_scope.js.map

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

@@ -0,0 +1,68 @@
+export declare const submitReceiptTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            receipt: {
+                type: string;
+                description: string;
+                properties: {
+                    workOrderId: {
+                        type: string;
+                    };
+                    status: {
+                        type: string;
+                        enum: string[];
+                    };
+                    proofPointers: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                pointer: {
+                                    type: string;
+                                };
+                                schemaName: {
+                                    type: string;
+                                };
+                                contentHash: {
+                                    type: string;
+                                };
+                            };
+                            required: string[];
+                        };
+                    };
+                    changedFiles: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                path: {
+                                    type: string;
+                                };
+                                prePatchHash: {
+                                    type: string;
+                                };
+                                postPatchHash: {
+                                    type: string;
+                                };
+                            };
+                            required: string[];
+                        };
+                    };
+                    summary: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleSubmitReceipt(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/submit_receipt.js

@@ -0,0 +1,94 @@
+import { join } from 'path';
+import { PointerStore } from '../../store/PointerStore.js';
+import { ProofValidator } from '@vibe-splain/brain';
+import { minimatch } from 'minimatch';
+import { v4 as uuidv4 } from 'uuid';
+export const submitReceiptTool = {
+    name: 'submit_receipt',
+    description: 'Worker submits a WorkerReceipt for a completed Work Order. The ProofValidator checks all 8 proof conditions. Returns accept/reject with detailed errors.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            receipt: {
+                type: 'object',
+                description: 'WorkerReceipt object',
+                properties: {
+                    workOrderId: { type: 'string' },
+                    status: { type: 'string', enum: ['completed', 'failed', 'blocked'] },
+                    proofPointers: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                pointer: { type: 'string' },
+                                schemaName: { type: 'string' },
+                                contentHash: { type: 'string' },
+                            },
+                            required: ['pointer', 'schemaName', 'contentHash'],
+                        },
+                    },
+                    changedFiles: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                path: { type: 'string' },
+                                prePatchHash: { type: 'string' },
+                                postPatchHash: { type: 'string' },
+                            },
+                            required: ['path', 'prePatchHash', 'postPatchHash'],
+                        },
+                    },
+                    summary: { type: 'string' },
+                },
+                required: ['workOrderId', 'status', 'proofPointers', 'changedFiles', 'summary'],
+            },
+        },
+        required: ['projectRoot', 'receipt'],
+    },
+};
+export async function handleSubmitReceipt(args) {
+    const projectRoot = args.projectRoot;
+    const receipt = args.receipt;
+    if (!projectRoot || !receipt) {
+        throw new Error('projectRoot and receipt are required');
+    }
+    const pointerStore = PointerStore.open(projectRoot);
+    const workOrder = pointerStore.getWorkOrder(receipt.workOrderId);
+    if (!workOrder) {
+        throw new Error(`WorkOrderNotFound: ${receipt.workOrderId}`);
+    }
+    if (workOrder.status !== 'active') {
+        throw new Error(`WorkOrderNotActive: ${receipt.workOrderId} is "${workOrder.status}", expected "active"`);
+    }
+    const allowedFiles = JSON.parse(workOrder.allowedFiles);
+    const allowedGlobs = JSON.parse(workOrder.allowedGlobs);
+    const requiredProof = JSON.parse(workOrder.requiredProof);
+    const blobDir = join(projectRoot, '.vibe-splainer', 'blobs');
+    const isAllowedFile = (filePath) => {
+        const inExplicit = allowedFiles.some(f => filePath === f || filePath.endsWith('/' + f) || filePath.endsWith(f));
+        const inGlobs = allowedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
+        return inExplicit || inGlobs;
+    };
+    const validation = await ProofValidator.validate(receipt, requiredProof, isAllowedFile, blobDir);
+    const receiptId = `rcpt_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+    const finalStatus = validation.valid ? receipt.status : 'failed';
+    await pointerStore.insertReceipt({
+        receiptId,
+        workOrderId: receipt.workOrderId,
+        status: finalStatus,
+        proofPointers: receipt.proofPointers,
+        changedFiles: receipt.changedFiles,
+        summary: receipt.summary,
+    });
+    await pointerStore.updateWorkOrderStatus(receipt.workOrderId, validation.valid ? (receipt.status === 'completed' ? 'completed' : 'failed') : 'failed');
+    return {
+        receiptId,
+        accepted: validation.valid,
+        workOrderId: receipt.workOrderId,
+        validation,
+        finalStatus,
+    };
+}
+//# sourceMappingURL=submit_receipt.js.map

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

@@ -0,0 +1,79 @@
+export declare const createWorkOrderTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            intent: {
+                type: string;
+                description: string;
+            };
+            allowedFiles: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            allowedGlobs: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            deniedGlobs: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            requiredProof: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        proofId: {
+                            type: string;
+                        };
+                        schemaName: {
+                            type: string;
+                            description: string;
+                        };
+                        description: {
+                            type: string;
+                        };
+                    };
+                    required: string[];
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleCreateWorkOrder(args: Record<string, unknown>): Promise<unknown>;
+export declare const spawnWorkerTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            workOrderId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleSpawnWorker(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/work_orders.js

@@ -0,0 +1,126 @@
+import { PointerStore } from '../../store/PointerStore.js';
+import { v4 as uuidv4 } from 'uuid';
+export const createWorkOrderTool = {
+    name: 'create_work_order',
+    description: 'Creates a new Work Order defining intent, allowed file scope, and required verifiable proof. Returns the workOrderId and a manifestPointer for use with spawn_worker.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            intent: { type: 'string', description: 'Plain-language description of what the worker should do' },
+            allowedFiles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Explicit file paths (relative to projectRoot) the worker may read/write',
+            },
+            allowedGlobs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Glob patterns for allowed files',
+            },
+            deniedGlobs: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Glob patterns that override allowedFiles/allowedGlobs',
+            },
+            requiredProof: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        proofId: { type: 'string' },
+                        schemaName: { type: 'string', description: 'e.g. test_report.v1, patch_hash' },
+                        description: { type: 'string' },
+                    },
+                    required: ['proofId', 'schemaName', 'description'],
+                },
+                description: 'Machine-verifiable evidence the worker must provide',
+            },
+        },
+        required: ['projectRoot', 'intent', 'allowedFiles'],
+    },
+};
+export async function handleCreateWorkOrder(args) {
+    const projectRoot = args.projectRoot;
+    const intent = args.intent;
+    const allowedFiles = args.allowedFiles ?? [];
+    const allowedGlobs = args.allowedGlobs ?? [];
+    const deniedGlobs = args.deniedGlobs ?? [];
+    const requiredProof = args.requiredProof ?? [];
+    if (!projectRoot || !intent) {
+        throw new Error('projectRoot and intent are required');
+    }
+    const workOrderId = `wo_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+    const pointerStore = PointerStore.open(projectRoot);
+    await pointerStore.insertWorkOrder({
+        workOrderId,
+        intent,
+        allowedFiles: JSON.stringify(allowedFiles),
+        allowedGlobs: JSON.stringify(allowedGlobs),
+        deniedGlobs: JSON.stringify(deniedGlobs),
+        requiredProof: JSON.stringify(requiredProof),
+        status: 'pending',
+        createdAt: Date.now(),
+    });
+    return {
+        ok: true,
+        workOrderId,
+        intent,
+        allowedFiles,
+        allowedGlobs,
+        deniedGlobs,
+        requiredProof,
+        nextStep: `Call spawn_worker with workOrderId "${workOrderId}" to generate a DelegationRequest`,
+    };
+}
+export const spawnWorkerTool = {
+    name: 'spawn_worker',
+    description: 'Generates a DelegationRequest from a Work Order. The Client Orchestrator uses this object to spawn an isolated Worker session. The MCP server does NOT spawn any subprocess.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            workOrderId: { type: 'string', description: 'ID returned by create_work_order' },
+        },
+        required: ['projectRoot', 'workOrderId'],
+    },
+};
+export async function handleSpawnWorker(args) {
+    const projectRoot = args.projectRoot;
+    const workOrderId = args.workOrderId;
+    if (!projectRoot || !workOrderId) {
+        throw new Error('projectRoot and workOrderId are required');
+    }
+    const pointerStore = PointerStore.open(projectRoot);
+    const row = pointerStore.getWorkOrder(workOrderId);
+    if (!row) {
+        throw new Error(`WorkOrderNotFound: ${workOrderId}`);
+    }
+    if (row.status === 'completed' || row.status === 'failed' || row.status === 'active') {
+        throw new Error(`WorkOrderClosed: ${workOrderId} is already ${row.status}`);
+    }
+    await pointerStore.updateWorkOrderStatus(workOrderId, 'active');
+    const delegationRequest = {
+        schemaVersion: '1.0.0',
+        workOrderId: row.workOrderId,
+        intent: row.intent,
+        sessionScope: {
+            allowedFiles: JSON.parse(row.allowedFiles),
+            allowedGlobs: JSON.parse(row.allowedGlobs),
+            deniedGlobs: JSON.parse(row.deniedGlobs),
+        },
+        requiredProof: JSON.parse(row.requiredProof),
+        instructions: [
+            `1. Call set_session_scope with workOrderId "${workOrderId}" before any file operations.`,
+            '2. Only read/write files within the sessionScope.',
+            '3. If you need a file outside scope, call yield_for_scope_expansion — do NOT proceed.',
+            '4. On completion, call submit_receipt with proof for every requiredProof entry.',
+        ],
+    };
+    return {
+        ok: true,
+        delegationRequest,
+        note: 'The Client Orchestrator must spawn the Worker session using this DelegationRequest. The MCP server does not spawn subprocesses.',
+    };
+}
+//# sourceMappingURL=work_orders.js.map