vibe-splain 3.4.2 → 3.5.0

package/dist/mcp/tools/apply_patch.js

@@ -1,103 +0,0 @@
-import { writeFile, rename, mkdir } from 'fs/promises';
-import { join, dirname } from 'path';
-import { SessionScope, ScopeViolation } from '../SessionScope.js';
-import { hashFile, BlobStore } from '../../store/BlobStore.js';
-import { PointerStore } from '../../store/PointerStore.js';
-import { applyBudgetGuard } from '../BudgetGuard.js';
-import { v4 as uuidv4 } from 'uuid';
-export class StalePatchError extends Error {
-    filePath;
-    expectedHash;
-    actualHash;
-    constructor(filePath, expectedHash, actualHash) {
-        super(`StalePatchError: ${filePath} hash mismatch — expected ${expectedHash}, got ${actualHash}. ` +
-            'File was modified since the expectedPrePatchHash was computed. Re-read the file and regenerate the patch.');
-        this.filePath = filePath;
-        this.expectedHash = expectedHash;
-        this.actualHash = actualHash;
-        this.name = 'StalePatchError';
-    }
-}
-export const applyPatchTool = {
-    name: 'apply_patch',
-    description: 'Applies a text patch to a file within the active workOrder scope. Requires expectedPrePatchHash to prevent stale-patch corruption. Records pre- and post-patch hashes.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            projectRoot: { type: 'string', description: 'Absolute project root' },
-            filePath: { type: 'string', description: 'Path relative to projectRoot' },
-            newContent: { type: 'string', description: 'Full new content of the file after the patch' },
-            expectedPrePatchHash: {
-                type: 'string',
-                description: 'sha256:<hex> hash of the file BEFORE patching. Obtain via hashFile or the sourceHash from get_file_skeleton.',
-            },
-            scanId: { type: 'string', description: 'Current scan ID for pointer registration' },
-        },
-        required: ['projectRoot', 'filePath', 'newContent', 'expectedPrePatchHash', 'scanId'],
-    },
-};
-export async function handleApplyPatch(args) {
-    const projectRoot = args.projectRoot;
-    const filePath = args.filePath;
-    const newContent = args.newContent;
-    const expectedPrePatchHash = args.expectedPrePatchHash;
-    const scanId = args.scanId;
-    if (!projectRoot || !filePath || !newContent || !expectedPrePatchHash || !scanId) {
-        throw new Error('projectRoot, filePath, newContent, expectedPrePatchHash, and scanId are all 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. Preimage hash check
-    let actualPreHash;
-    try {
-        actualPreHash = await hashFile(absolutePath);
-    }
-    catch {
-        // File doesn't exist yet — for new files, expectedPrePatchHash must be 'sha256:new'
-        actualPreHash = 'sha256:new';
-    }
-    if (actualPreHash !== expectedPrePatchHash) {
-        throw new StalePatchError(filePath, expectedPrePatchHash, actualPreHash);
-    }
-    // 3. Atomic write
-    const dir = dirname(absolutePath);
-    await mkdir(dir, { recursive: true });
-    const tmpPath = absolutePath + `.tmp_${Date.now()}`;
-    await writeFile(tmpPath, newContent, 'utf8');
-    await rename(tmpPath, absolutePath);
-    // 4. Compute post-patch hash
-    const postPatchHash = await hashFile(absolutePath);
-    // 5. Record both hashes in blob store
-    const blobStore = new BlobStore(projectRoot);
-    const pointerStore = PointerStore.open(projectRoot);
-    const { blobPath } = await blobStore.writeAtomic(newContent);
-    const pointerId = `ptr_patch_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
-    await pointerStore.insertPointer({
-        pointerId,
-        scanId,
-        artifactName: 'patch_record',
-        contentHash: postPatchHash,
-        blobPath,
-        schemaVersion: '1.0.0',
-        createdAt: Date.now(),
-        expiresAt: null,
-    });
-    const result = {
-        ok: true,
-        filePath,
-        prePatchHash: actualPreHash,
-        postPatchHash,
-        pointerId,
-        message: `Patch applied to ${filePath}`,
-    };
-    return await applyBudgetGuard(projectRoot, scanId, 'patch_record', result);
-}
-//# sourceMappingURL=apply_patch.js.map

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

@@ -1,15 +0,0 @@
-export declare const explainSpecialistScopeTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            specialist_id: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handleExplainSpecialistScope(args: Record<string, unknown>, options?: any): Promise<unknown>;

package/dist/mcp/tools/explainSpecialistScope.js

@@ -1,30 +0,0 @@
-import { getSpecialistProfile, isSpecialistId } from '@vibe-splain/brain';
-export const explainSpecialistScopeTool = {
-    name: 'vibe_explain_specialist_scope',
-    description: 'Explains the jurisdiction scope card and profile definitions for a given specialist ID.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            specialist_id: {
-                type: 'string',
-                description: 'Specialist ID to explain (control_flow | data_transform | integration_contracts | generic_repo)',
-            }
-        },
-        required: ['specialist_id'],
-    },
-};
-export async function handleExplainSpecialistScope(args, options = {}) {
-    const specialistId = args.specialist_id;
-    if (!specialistId)
-        throw new Error('specialist_id is required');
-    if (!isSpecialistId(specialistId)) {
-        throw new Error(`Invalid specialist ID: "${specialistId}". Must be one of: control_flow, data_transform, integration_contracts, generic_repo.`);
-    }
-    console.error(`[vibe-splain] Fetching scope profile for specialist: "${specialistId}"`);
-    const profile = getSpecialistProfile(specialistId);
-    return {
-        ok: true,
-        profile
-    };
-}
-//# sourceMappingURL=explainSpecialistScope.js.map

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

@@ -1,42 +0,0 @@
-export declare const getCallChainTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            projectRoot: {
-                type: string;
-            };
-            entrypointPath: {
-                type: string;
-                description: string;
-            };
-            maxDepth: {
-                type: string;
-                description: string;
-            };
-            targetActionKind: {
-                type: string;
-                description: string;
-            };
-            targetModel: {
-                type: string;
-                description: string;
-            };
-            targetOperation: {
-                type: string;
-                description: string;
-            };
-            targetFunctionName: {
-                type: string;
-                description: string;
-            };
-            includeTests: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handleGetCallChain(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_call_chain.js

@@ -1,50 +0,0 @@
-import { traverseCallChain } from '@vibe-splain/brain';
-export const getCallChainTool = {
-    name: 'get_call_chain',
-    description: `Trace how behavior is reached from an entrypoint by following function call edges through the codebase. Returns a step-by-step chain with exact function names, file paths, line numbers, action kinds, and evidence text. Every edge has a confidence level; unresolved edges are listed explicitly.
-
-Use structured filters when you know the target:
-  targetModel + targetOperation: "where does Booking get created?"
-  targetActionKind: "where is auth enforced?"  
-  targetFunctionName: "how is function X reached?"
-No filter returns the full call tree up to maxDepth.
-
-Run scan_project first — this tool reads from the generated action_bindings.json.`,
-    inputSchema: {
-        type: 'object',
-        properties: {
-            projectRoot: { type: 'string' },
-            entrypointPath: { type: 'string', description: 'Relative path to the entrypoint file' },
-            maxDepth: { type: 'number', description: 'Max traversal depth. Default 6, max 12.' },
-            targetActionKind: { type: 'string', description: 'Stop at this semantic action kind.' },
-            targetModel: { type: 'string', description: 'Stop at functions touching this model.' },
-            targetOperation: { type: 'string', description: 'Narrow targetModel to this operation.' },
-            targetFunctionName: { type: 'string', description: 'Stop at a specific function name.' },
-            includeTests: { type: 'boolean', description: 'Include test files in traversal. Default false.' },
-        },
-        required: ['projectRoot', 'entrypointPath'],
-    },
-};
-export async function handleGetCallChain(args) {
-    const projectRoot = args.projectRoot;
-    const entrypointPath = args.entrypointPath;
-    if (!projectRoot || !entrypointPath)
-        throw new Error('projectRoot and entrypointPath are required');
-    const getCallChainArgs = {
-        entrypointPath,
-        maxDepth: typeof args.maxDepth === 'number' ? args.maxDepth : undefined,
-        targetActionKind: typeof args.targetActionKind === 'string' ? args.targetActionKind : undefined,
-        targetModel: typeof args.targetModel === 'string' ? args.targetModel : undefined,
-        targetOperation: typeof args.targetOperation === 'string' ? args.targetOperation : undefined,
-        targetFunctionName: typeof args.targetFunctionName === 'string' ? args.targetFunctionName : undefined,
-        includeTests: typeof args.includeTests === 'boolean' ? args.includeTests : undefined,
-    };
-    try {
-        const result = await traverseCallChain(projectRoot, getCallChainArgs);
-        return result;
-    }
-    catch (error) {
-        throw new Error(`get_call_chain failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-//# sourceMappingURL=get_call_chain.js.map

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

@@ -1,38 +0,0 @@
-export declare const prepareTaskContextTool: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            projectRoot: {
-                type: string;
-                description: string;
-            };
-            task: {
-                type: string;
-                description: string;
-            };
-            files: {
-                type: string;
-                items: {
-                    type: string;
-                };
-                description: string;
-            };
-            error_trace: {
-                type: string;
-                description: string;
-            };
-            intended_behavior: {
-                type: string;
-                description: string;
-            };
-            max_files: {
-                type: string;
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-export declare function handlePrepareTaskContext(args: Record<string, unknown>, options?: any): Promise<unknown>;

package/dist/mcp/tools/prepareTaskContext.js

@@ -1,93 +0,0 @@
-import { join } from 'path';
-import { readFile, writeFile, mkdir } from 'fs/promises';
-import { buildExpertNetworkPacket } from '@vibe-splain/brain';
-export const prepareTaskContextTool = {
-    name: 'vibe_prepare_task_context',
-    description: 'Prepares the ExpertNetworkPacket for a given task, selecting relevant files, routing to a specialist panel, analyzing risk warnings, and slicing scopes without running model inference.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            projectRoot: {
-                type: 'string',
-                description: 'Absolute path to the project root directory',
-            },
-            task: {
-                type: 'string',
-                description: 'Description of the task or issue to resolve',
-            },
-            files: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'Optional list of files to explicitly focus on',
-            },
-            error_trace: {
-                type: 'string',
-                description: 'Optional error stack trace or exception output',
-            },
-            intended_behavior: {
-                type: 'string',
-                description: 'Optional description of the intended behavior',
-            },
-            max_files: {
-                type: 'number',
-                description: 'Optional maximum files to select',
-            }
-        },
-        required: ['projectRoot', 'task'],
-    },
-};
-export async function handlePrepareTaskContext(args, options = {}) {
-    const projectRoot = args.projectRoot;
-    const task = args.task;
-    const files = args.files;
-    const errorTrace = args.error_trace;
-    const intendedBehavior = args.intended_behavior;
-    const maxFiles = args.max_files;
-    if (!projectRoot)
-        throw new Error('projectRoot is required');
-    if (!task)
-        throw new Error('task is required');
-    console.error(`[vibe-splain] Preparing task context for task: "${task}"`);
-    // Try to load scan artifact
-    let scanArtifact = null;
-    const artifactPath = join(projectRoot, '.vibe-splainer', 'analysis.json');
-    try {
-        const raw = await readFile(artifactPath, 'utf8');
-        scanArtifact = JSON.parse(raw);
-    }
-    catch (err) {
-        console.error(`[vibe-splain] No scan artifact found at ${artifactPath}, proceeding with fallback routing.`);
-    }
-    // Build the packet
-    const packet = buildExpertNetworkPacket({
-        task,
-        projectRoot,
-        scanArtifact,
-        files,
-        errorTrace,
-        intendedBehavior,
-        maxFiles
-    });
-    // Save network packet locally
-    const networkDir = join(projectRoot, '.vibe-splainer', 'network');
-    const packetsDir = join(networkDir, 'packets');
-    try {
-        await mkdir(packetsDir, { recursive: true });
-        // Save latest
-        const latestPath = join(networkDir, 'latest_packet.json');
-        await writeFile(latestPath, JSON.stringify(packet, null, 2), 'utf8');
-        // Save timestamped
-        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-        const timestampedPath = join(packetsDir, `${timestamp}.json`);
-        await writeFile(timestampedPath, JSON.stringify(packet, null, 2), 'utf8');
-        console.error(`[vibe-splain] Network packets saved under ${networkDir}`);
-    }
-    catch (err) {
-        console.error('[vibe-splain] Failed to save network packets locally:', err.message);
-    }
-    return {
-        ok: true,
-        packet
-    };
-}
-//# sourceMappingURL=prepareTaskContext.js.map

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

@@ -1,19 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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

@@ -1,79 +0,0 @@
-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>;