vibe-splain 3.5.0 → 4.0.0

package/dist/mcp/SessionScope.d.ts

@@ -1,26 +0,0 @@
-import type { WorkOrderRow, ProofDescriptor } from '../store/PointerStore.js';
-export interface ScopePolicy {
-    workOrderId: string;
-    allowedFiles: string[];
-    allowedGlobs: string[];
-    deniedGlobs: string[];
-    requiredProof: ProofDescriptor[];
-}
-export declare class ScopeViolation extends Error {
-    readonly path: string;
-    readonly workOrderId: string;
-    constructor(path: string, workOrderId: string, reason: string);
-}
-export declare const SessionScope: {
-    set(policy: ScopePolicy): void;
-    clear(): void;
-    get(): ScopePolicy | null;
-    /**
-     * Enforce scope for a file path.
-     * Throws ScopeViolation if:
-     *  - a scope is active AND the path is not allowed
-     * If no scope is active, all paths are permitted.
-     */
-    enforce(filePath: string): void;
-    fromWorkOrderRow(row: WorkOrderRow): ScopePolicy;
-};

package/dist/mcp/SessionScope.js

@@ -1,56 +0,0 @@
-import { minimatch } from 'minimatch';
-export class ScopeViolation extends Error {
-    path;
-    workOrderId;
-    constructor(path, workOrderId, reason) {
-        super(`ScopeViolation [${workOrderId}]: ${reason} — path: ${path}`);
-        this.path = path;
-        this.workOrderId = workOrderId;
-        this.name = 'ScopeViolation';
-    }
-}
-let activeScope = null;
-export const SessionScope = {
-    set(policy) {
-        activeScope = policy;
-    },
-    clear() {
-        activeScope = null;
-    },
-    get() {
-        return activeScope;
-    },
-    /**
-     * Enforce scope for a file path.
-     * Throws ScopeViolation if:
-     *  - a scope is active AND the path is not allowed
-     * If no scope is active, all paths are permitted.
-     */
-    enforce(filePath) {
-        if (!activeScope)
-            return;
-        const { workOrderId, allowedFiles, allowedGlobs, deniedGlobs } = activeScope;
-        // Explicit file list match (exact suffix or relative path)
-        const inAllowedFiles = allowedFiles.some(f => filePath === f || filePath.endsWith('/' + f) || filePath.endsWith(f));
-        // Glob match
-        const inAllowedGlobs = allowedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
-        if (!inAllowedFiles && !inAllowedGlobs) {
-            throw new ScopeViolation(filePath, workOrderId, 'path not in allowedFiles or allowedGlobs');
-        }
-        // Deny globs have priority over allow
-        const isDenied = deniedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
-        if (isDenied) {
-            throw new ScopeViolation(filePath, workOrderId, 'path matches deniedGlobs');
-        }
-    },
-    fromWorkOrderRow(row) {
-        return {
-            workOrderId: row.workOrderId,
-            allowedFiles: JSON.parse(row.allowedFiles),
-            allowedGlobs: JSON.parse(row.allowedGlobs),
-            deniedGlobs: JSON.parse(row.deniedGlobs),
-            requiredProof: JSON.parse(row.requiredProof),
-        };
-    },
-};
-//# sourceMappingURL=SessionScope.js.map

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

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

package/dist/mcp/tools/get_file_skeleton.js

@@ -1,124 +0,0 @@
-import { readFile } from 'fs/promises';
-import { join } from 'path';
-import { SessionScope, ScopeViolation } from '../SessionScope.js';
-import { BlobStore, hashFile } from '../../store/BlobStore.js';
-import { PointerStore } from '../../store/PointerStore.js';
-import { applyBudgetGuard } from '../BudgetGuard.js';
-import { v4 as uuidv4 } from 'uuid';
-export const getFileSkeletonTool = {
-    name: 'get_file_skeleton',
-    description: 'Returns a content-addressed skeleton view of a source file (function signatures, class names, exported symbols). Enforces active workOrder scope. Results are content-addressed — repeated calls on unchanged files return cached pointers.',
-    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' },
-        },
-        required: ['projectRoot', 'filePath', 'scanId'],
-    },
-};
-export async function handleGetFileSkeleton(args) {
-    const projectRoot = args.projectRoot;
-    const filePath = args.filePath;
-    const scanId = args.scanId;
-    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. Compute preimage hash of source file
-    let currentHash;
-    try {
-        currentHash = await hashFile(absolutePath);
-    }
-    catch {
-        throw new Error(`FileNotFound: cannot read ${filePath}`);
-    }
-    // 3. Check cache: same hash + parser version = return existing pointer
-    const parserVersion = '1.0.0';
-    const cacheKey = `skeleton:${currentHash}:${parserVersion}`;
-    const pointerStore = PointerStore.open(projectRoot);
-    // Look up by contentHash in existing pointers for this scan
-    const existingPointers = pointerStore.listPointersByScan(scanId);
-    const cached = existingPointers.find(p => p.artifactName === 'file_skeleton' && p.contentHash === cacheKey);
-    if (cached) {
-        return {
-            pointerId: cached.pointerId,
-            contentHash: currentHash,
-            cached: true,
-            filePath,
-        };
-    }
-    // 4. Build skeleton
-    const source = await readFile(absolutePath, 'utf8');
-    const skeleton = extractSkeleton(source, filePath);
-    // 5. Record content hash
-    const skeletonPayload = {
-        filePath,
-        sourceHash: currentHash,
-        parserVersion,
-        skeleton,
-    };
-    // 6. Budget enforcement
-    const blobStore = new BlobStore(projectRoot);
-    const serialized = JSON.stringify(skeletonPayload, null, 2);
-    const { contentHash: skeletonHash, blobPath } = await blobStore.writeAtomic(serialized);
-    const pointerId = `ptr_skel_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
-    await pointerStore.insertPointer({
-        pointerId,
-        scanId,
-        artifactName: 'file_skeleton',
-        contentHash: cacheKey, // cache key encodes source hash + parser version
-        blobPath,
-        schemaVersion: '1.0.0',
-        createdAt: Date.now(),
-        expiresAt: null,
-    });
-    const result = {
-        filePath,
-        sourceHash: currentHash,
-        pointerId,
-        skeleton,
-    };
-    return await applyBudgetGuard(projectRoot, scanId, 'file_skeleton', result);
-}
-function extractSkeleton(source, filePath) {
-    const lines = source.split('\n');
-    const skeleton = [];
-    const ext = filePath.split('.').pop() ?? '';
-    const isTS = ['ts', 'tsx'].includes(ext);
-    const isJS = ['js', 'jsx', 'mjs', 'cjs'].includes(ext);
-    if (isTS || isJS) {
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i].trim();
-            // Exported declarations, function/class/interface/type/enum signatures
-            if (/^(export\s+)?(async\s+)?function\b/.test(line) ||
-                /^(export\s+)?(abstract\s+)?class\b/.test(line) ||
-                /^(export\s+)?interface\b/.test(line) ||
-                /^(export\s+)?type\s+\w+/.test(line) ||
-                /^(export\s+)?enum\b/.test(line) ||
-                /^(export\s+)?const\s+\w+\s*[:=(]/.test(line) ||
-                /^(export\s+)?let\s+\w+\s*[:=(]/.test(line) ||
-                /^(export\s+)?(default\s+)/.test(line) ||
-                /^\s*(public|private|protected|static|readonly|abstract)\s+/.test(line) ||
-                /^import\b/.test(line)) {
-                skeleton.push(`L${i + 1}: ${lines[i]}`);
-            }
-        }
-    }
-    else {
-        // Generic: return first 80 lines as skeleton for unsupported types
-        return lines.slice(0, 80).map((l, i) => `L${i + 1}: ${l}`);
-    }
-    return skeleton;
-}
-//# sourceMappingURL=get_file_skeleton.js.map

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

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

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

@@ -1,57 +0,0 @@
-import { hydratePointer, applyBudgetGuard } from '../../BudgetGuard.js';
-import { SessionScope } from '../../SessionScope.js';
-export const getEvidenceSliceTool = {
-    name: 'get_evidence_slice',
-    description: 'Raw fallback: returns a line-range slice from a blob artifact. Pointer must be valid and unexpired. Output is budgeted.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            projectRoot: { type: 'string', description: 'Absolute project root' },
-            pointerId: { type: 'string', description: 'Pointer ID for the target artifact' },
-            startLine: { type: 'number', description: 'Inclusive start line (1-based)' },
-            endLine: { type: 'number', description: 'Inclusive end line (1-based). Capped at startLine+200.' },
-            scanId: { type: 'string', description: 'Current scan ID for budget pointer registration' },
-        },
-        required: ['projectRoot', 'pointerId', 'startLine', 'endLine', 'scanId'],
-    },
-};
-export async function handleGetEvidenceSlice(args) {
-    const projectRoot = args.projectRoot;
-    const pointerId = args.pointerId;
-    const startLine = Number(args.startLine);
-    const endLine = Math.min(Number(args.endLine), startLine + 200);
-    const scanId = args.scanId;
-    if (!projectRoot || !pointerId || !scanId) {
-        throw new Error('projectRoot, pointerId, startLine, endLine, and scanId are required');
-    }
-    // 1. Verify pointer, lifetime, hash
-    const { content, row } = await hydratePointer(projectRoot, pointerId);
-    const rawText = content.toString('utf8');
-    // Scope enforcement: if a Worker scope is active, enforce it for file-type artifacts
-    const scope = SessionScope.get();
-    if (scope && (row.artifactName === 'file_read' || row.artifactName === 'file_skeleton')) {
-        try {
-            const parsed = JSON.parse(rawText);
-            if (parsed.filePath) {
-                SessionScope.enforce(parsed.filePath);
-            }
-        }
-        catch (e) {
-            if (e.name === 'ScopeViolation')
-                throw e;
-        }
-    }
-    const lines = rawText.split('\n');
-    const sliced = lines.slice(startLine - 1, endLine);
-    const result = {
-        pointerId,
-        artifactName: row.artifactName,
-        startLine,
-        endLine,
-        totalLines: lines.length,
-        slice: sliced,
-    };
-    // 2. Budget query result
-    return await applyBudgetGuard(projectRoot, scanId, 'evidence_slice', result);
-}
-//# sourceMappingURL=get_evidence_slice.js.map

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

@@ -1,23 +0,0 @@
-export declare const getProjectSummaryTool: {
-    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 handleGetProjectSummary(args: Record<string, unknown>): Promise<unknown>;

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

@@ -1,58 +0,0 @@
-import { hydratePointer, applyBudgetGuard } from '../../BudgetGuard.js';
-export const getProjectSummaryTool = {
-    name: 'get_project_summary',
-    description: 'Returns high-level project metrics from a scan manifest pointer: file counts, pillar summary, stack. Token-safe. 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' },
-            scanId: { type: 'string', description: 'Current scan ID for budget pointer registration' },
-        },
-        required: ['projectRoot', 'manifestPointer', 'scanId'],
-    },
-};
-export async function handleGetProjectSummary(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');
-    }
-    const { content, row } = await hydratePointer(projectRoot, manifestPointer);
-    const payload = JSON.parse(content.toString('utf8'));
-    if (row.artifactName === 'artifact_manifest') {
-        const manifest = payload;
-        const analysisEntry = manifest.artifacts.find(a => a.name === 'analysis' && a.indexes?.startHere);
-        let indexData = {};
-        if (analysisEntry?.indexes?.startHere) {
-            const { content: ic } = await hydratePointer(projectRoot, analysisEntry.indexes.startHere);
-            indexData = JSON.parse(ic.toString('utf8'));
-        }
-        const result = {
-            scanId: manifest.scanId,
-            generatedAt: manifest.generatedAt,
-            artifactCount: manifest.artifacts.length,
-            totalArtifactBytes: manifest.artifacts.reduce((s, a) => s + (a.sizeBytes ?? 0), 0),
-            startHere: indexData.startHere,
-            topHeat: indexData.topHeat,
-            pillarSummary: indexData.pillarSummary,
-            totalFiles: indexData.totalFiles,
-            realSourceFiles: indexData.realSourceFiles,
-        };
-        return await applyBudgetGuard(projectRoot, scanId, 'get_project_summary_result', result);
-    }
-    if (row.artifactName === 'analysis.index') {
-        const result = {
-            scanId: payload.scanId,
-            startHere: payload.startHere,
-            topHeat: payload.topHeat,
-            pillarSummary: payload.pillarSummary,
-            totalFiles: payload.totalFiles,
-            realSourceFiles: payload.realSourceFiles,
-        };
-        return await applyBudgetGuard(projectRoot, scanId, 'get_project_summary_result', result);
-    }
-    throw new Error(`Unsupported artifact type for get_project_summary: ${row.artifactName}`);
-}
-//# sourceMappingURL=get_project_summary.js.map

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

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

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

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

@@ -1,90 +0,0 @@
-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/store/BlobStore.d.ts

@@ -1,22 +0,0 @@
-export interface BlobWriteResult {
-    contentHash: string;
-    blobPath: string;
-}
-export declare class BlobStore {
-    private blobsDir;
-    private tmpDir;
-    constructor(projectRoot: string);
-    ensureDirs(): Promise<void>;
-    writeAtomic(payload: Buffer | string): Promise<BlobWriteResult>;
-    readBlob(blobPath: string): Promise<Buffer>;
-    blobExists(contentHash: string): Promise<boolean>;
-    blobPathForHash(contentHash: string): string;
-    verifyIntegrity(blobPath: string, expectedHash: string): Promise<boolean>;
-    /** List all blob paths for GC reference counting */
-    listBlobPaths(): Promise<string[]>;
-    getBlobSize(blobPath: string): Promise<number>;
-}
-/** Hash a string or buffer without writing it */
-export declare function computeHash(payload: Buffer | string): string;
-/** Hash a file on disk */
-export declare function hashFile(filePath: string): Promise<string>;