vibe-splain 3.1.0 → 3.2.1

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

@@ -0,0 +1,29 @@
+export declare const yieldForScopeExpansionTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            requestedPaths: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            reason: {
+                type: string;
+                description: string;
+            };
+            evidencePointers: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleYieldForScopeExpansion(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/yield_for_scope_expansion.js

@@ -0,0 +1,59 @@
+import { SessionScope } from '../SessionScope.js';
+export const yieldForScopeExpansionTool = {
+    name: 'yield_for_scope_expansion',
+    description: 'Worker signals that it needs to access files outside its current scope. Immediately terminates the active scope and returns a Blocked receipt. The Manager must evaluate the evidence and decide whether to spawn a new Worker with expanded scope.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            requestedPaths: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Paths the worker needs but cannot access under current scope',
+            },
+            reason: {
+                type: 'string',
+                description: 'Why these paths are needed — root cause found in out-of-scope file',
+            },
+            evidencePointers: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Pointer IDs for artifacts that justify the expansion request',
+            },
+        },
+        required: ['requestedPaths', 'reason'],
+    },
+};
+export async function handleYieldForScopeExpansion(args) {
+    const requestedPaths = args.requestedPaths ?? [];
+    const reason = args.reason;
+    const evidencePointers = args.evidencePointers ?? [];
+    if (!requestedPaths.length || !reason) {
+        throw new Error('requestedPaths and reason are required');
+    }
+    const currentScope = SessionScope.get();
+    const workOrderId = currentScope?.workOrderId ?? 'unknown';
+    // Immediately clear the active scope — Worker is now blocked
+    SessionScope.clear();
+    // Return strict Blocked status per ADR-033
+    return {
+        status: 'blocked',
+        workOrderId,
+        requestedPaths,
+        reason,
+        evidencePointers,
+        receipt: {
+            workOrderId,
+            status: 'blocked',
+            proofPointers: [],
+            changedFiles: [],
+            summary: `Worker blocked: scope expansion required. Reason: ${reason}`,
+        },
+        managerInstructions: [
+            'Worker has been terminated. Active session scope has been cleared.',
+            'Evaluate the evidence pointers and reason.',
+            'If expansion is warranted, create a new Work Order with the expanded allowedFiles and spawn a new Worker.',
+            'If expansion is NOT warranted, the task is failed — do not retry with same scope.',
+        ],
+    };
+}
+//# sourceMappingURL=yield_for_scope_expansion.js.map

package/dist/store/BlobStore.d.ts

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

package/dist/store/BlobStore.js

@@ -0,0 +1,96 @@
+import { createHash } from 'crypto';
+import { mkdir, writeFile, open, rename, stat } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+export class BlobStore {
+    blobsDir;
+    tmpDir;
+    constructor(projectRoot) {
+        this.blobsDir = join(projectRoot, '.vibe-splainer', 'blobs');
+        this.tmpDir = join(projectRoot, '.vibe-splainer', 'tmp');
+    }
+    async ensureDirs() {
+        await mkdir(this.blobsDir, { recursive: true });
+        await mkdir(this.tmpDir, { recursive: true });
+    }
+    async writeAtomic(payload) {
+        await this.ensureDirs();
+        const buf = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+        const hex = createHash('sha256').update(buf).digest('hex');
+        const contentHash = `sha256:${hex}`;
+        const blobPath = join(this.blobsDir, `sha256_${hex}`);
+        if (existsSync(blobPath)) {
+            return { contentHash, blobPath };
+        }
+        const tmpPath = join(this.tmpDir, `tmp_${hex}_${Date.now()}`);
+        await writeFile(tmpPath, buf);
+        // fsync the file before rename
+        const fh = await open(tmpPath, 'r');
+        try {
+            await fh.datasync();
+        }
+        finally {
+            await fh.close();
+        }
+        await rename(tmpPath, blobPath);
+        return { contentHash, blobPath };
+    }
+    async readBlob(blobPath) {
+        const { readFile } = await import('fs/promises');
+        return readFile(blobPath);
+    }
+    async blobExists(contentHash) {
+        const hex = contentHash.replace('sha256:', '');
+        const blobPath = join(this.blobsDir, `sha256_${hex}`);
+        return existsSync(blobPath);
+    }
+    blobPathForHash(contentHash) {
+        const hex = contentHash.replace('sha256:', '');
+        return join(this.blobsDir, `sha256_${hex}`);
+    }
+    async verifyIntegrity(blobPath, expectedHash) {
+        try {
+            const { readFile } = await import('fs/promises');
+            const buf = await readFile(blobPath);
+            const hex = createHash('sha256').update(buf).digest('hex');
+            return `sha256:${hex}` === expectedHash;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** List all blob paths for GC reference counting */
+    async listBlobPaths() {
+        try {
+            const { readdir } = await import('fs/promises');
+            const files = await readdir(this.blobsDir);
+            return files
+                .filter(f => f.startsWith('sha256_'))
+                .map(f => join(this.blobsDir, f));
+        }
+        catch {
+            return [];
+        }
+    }
+    async getBlobSize(blobPath) {
+        try {
+            const info = await stat(blobPath);
+            return info.size;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+/** Hash a string or buffer without writing it */
+export function computeHash(payload) {
+    const buf = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+    return `sha256:${createHash('sha256').update(buf).digest('hex')}`;
+}
+/** Hash a file on disk */
+export async function hashFile(filePath) {
+    const { readFile } = await import('fs/promises');
+    const buf = await readFile(filePath);
+    return `sha256:${createHash('sha256').update(buf).digest('hex')}`;
+}
+//# sourceMappingURL=BlobStore.js.map

package/dist/store/PointerStore.d.ts

@@ -0,0 +1,52 @@
+export interface PointerRow {
+    pointerId: string;
+    scanId: string;
+    artifactName: string;
+    contentHash: string;
+    blobPath: string;
+    schemaVersion: string;
+    createdAt: number;
+    expiresAt: number | null;
+}
+export interface WorkOrderRow {
+    workOrderId: string;
+    intent: string;
+    allowedFiles: string;
+    allowedGlobs: string;
+    deniedGlobs: string;
+    requiredProof: string;
+    status: 'pending' | 'active' | 'completed' | 'failed' | 'blocked';
+    createdAt: number;
+}
+export interface ProofDescriptor {
+    proofId: string;
+    schemaName: string;
+    description: string;
+}
+export declare class PointerStore {
+    private db;
+    private writeMutex;
+    constructor(projectRoot: string);
+    static open(projectRoot: string): PointerStore;
+    static reset(): void;
+    private _migrate;
+    insertPointer(row: PointerRow): Promise<void>;
+    getPointer(pointerId: string): PointerRow | null;
+    listPointersByScan(scanId: string): PointerRow[];
+    insertWorkOrder(row: WorkOrderRow): Promise<void>;
+    getWorkOrder(workOrderId: string): WorkOrderRow | null;
+    updateWorkOrderStatus(workOrderId: string, status: WorkOrderRow['status']): Promise<void>;
+    insertReceipt(receipt: {
+        receiptId: string;
+        workOrderId: string;
+        status: string;
+        proofPointers: unknown[];
+        changedFiles: unknown[];
+        summary: string;
+    }): Promise<void>;
+    /** GC: delete pointers older than cutoffMs and not pinned, return deleted count */
+    gcScanPointers(keepScanIds: string[]): Promise<number>;
+    listAllScanIds(): string[];
+    countPointers(): number;
+    close(): void;
+}

package/dist/store/PointerStore.js

@@ -0,0 +1,138 @@
+import Database from 'better-sqlite3';
+import { join } from 'path';
+import { mkdirSync } from 'fs';
+import { Mutex } from 'async-mutex';
+let instance = null;
+export class PointerStore {
+    db;
+    writeMutex = new Mutex();
+    constructor(projectRoot) {
+        const dir = join(projectRoot, '.vibe-splainer');
+        mkdirSync(dir, { recursive: true });
+        this.db = new Database(join(dir, 'pointer_store.db'));
+        // busy_timeout must be set first — it governs the WAL switch itself
+        this.db.pragma('busy_timeout = 5000');
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('foreign_keys = ON');
+        this._migrate();
+    }
+    static open(projectRoot) {
+        if (!instance)
+            instance = new PointerStore(projectRoot);
+        return instance;
+    }
+    static reset() {
+        instance = null;
+    }
+    _migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pointers (
+        pointerId     TEXT PRIMARY KEY,
+        scanId        TEXT NOT NULL,
+        artifactName  TEXT NOT NULL,
+        contentHash   TEXT NOT NULL,
+        blobPath      TEXT NOT NULL,
+        schemaVersion TEXT NOT NULL DEFAULT '1.0.0',
+        createdAt     INTEGER NOT NULL,
+        expiresAt     INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_pointers_scan ON pointers(scanId);
+      CREATE INDEX IF NOT EXISTS idx_pointers_hash ON pointers(contentHash);
+
+      CREATE TABLE IF NOT EXISTS work_orders (
+        workOrderId   TEXT PRIMARY KEY,
+        intent        TEXT NOT NULL,
+        allowedFiles  TEXT NOT NULL DEFAULT '[]',
+        allowedGlobs  TEXT NOT NULL DEFAULT '[]',
+        deniedGlobs   TEXT NOT NULL DEFAULT '[]',
+        requiredProof TEXT NOT NULL DEFAULT '[]',
+        status        TEXT NOT NULL DEFAULT 'pending',
+        createdAt     INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS receipts (
+        receiptId     TEXT PRIMARY KEY,
+        workOrderId   TEXT NOT NULL REFERENCES work_orders(workOrderId),
+        status        TEXT NOT NULL,
+        proofPointers TEXT NOT NULL DEFAULT '[]',
+        changedFiles  TEXT NOT NULL DEFAULT '[]',
+        summary       TEXT NOT NULL DEFAULT '',
+        createdAt     INTEGER NOT NULL,
+        FOREIGN KEY (workOrderId) REFERENCES work_orders(workOrderId)
+      );
+    `);
+    }
+    async insertPointer(row) {
+        await this.writeMutex.runExclusive(() => {
+            this.db.prepare(`
+        INSERT OR REPLACE INTO pointers
+          (pointerId, scanId, artifactName, contentHash, blobPath, schemaVersion, createdAt, expiresAt)
+        VALUES
+          (@pointerId, @scanId, @artifactName, @contentHash, @blobPath, @schemaVersion, @createdAt, @expiresAt)
+      `).run(row);
+        });
+    }
+    getPointer(pointerId) {
+        return this.db.prepare('SELECT * FROM pointers WHERE pointerId = ?').get(pointerId) ?? null;
+    }
+    listPointersByScan(scanId) {
+        return this.db.prepare('SELECT * FROM pointers WHERE scanId = ?').all(scanId);
+    }
+    async insertWorkOrder(row) {
+        await this.writeMutex.runExclusive(() => {
+            this.db.prepare(`
+        INSERT OR REPLACE INTO work_orders
+          (workOrderId, intent, allowedFiles, allowedGlobs, deniedGlobs, requiredProof, status, createdAt)
+        VALUES
+          (@workOrderId, @intent, @allowedFiles, @allowedGlobs, @deniedGlobs, @requiredProof, @status, @createdAt)
+      `).run(row);
+        });
+    }
+    getWorkOrder(workOrderId) {
+        return this.db.prepare('SELECT * FROM work_orders WHERE workOrderId = ?').get(workOrderId) ?? null;
+    }
+    async updateWorkOrderStatus(workOrderId, status) {
+        await this.writeMutex.runExclusive(() => {
+            this.db.prepare('UPDATE work_orders SET status = ? WHERE workOrderId = ?').run(status, workOrderId);
+        });
+    }
+    async insertReceipt(receipt) {
+        await this.writeMutex.runExclusive(() => {
+            this.db.prepare(`
+        INSERT OR REPLACE INTO receipts
+          (receiptId, workOrderId, status, proofPointers, changedFiles, summary, createdAt)
+        VALUES
+          (@receiptId, @workOrderId, @status, @proofPointers, @changedFiles, @summary, @createdAt)
+      `).run({
+                ...receipt,
+                proofPointers: JSON.stringify(receipt.proofPointers),
+                changedFiles: JSON.stringify(receipt.changedFiles),
+                createdAt: Date.now(),
+            });
+        });
+    }
+    /** GC: delete pointers older than cutoffMs and not pinned, return deleted count */
+    async gcScanPointers(keepScanIds) {
+        return await this.writeMutex.runExclusive(() => {
+            const placeholders = keepScanIds.map(() => '?').join(',');
+            const whereClause = keepScanIds.length > 0
+                ? `WHERE scanId NOT IN (${placeholders})`
+                : '';
+            const result = this.db.prepare(`DELETE FROM pointers ${whereClause}`).run(...keepScanIds);
+            return result.changes;
+        });
+    }
+    listAllScanIds() {
+        const rows = this.db.prepare('SELECT DISTINCT scanId FROM pointers').all();
+        return rows.map(r => r.scanId);
+    }
+    countPointers() {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM pointers').get();
+        return row.cnt;
+    }
+    close() {
+        this.db.close();
+        instance = null;
+    }
+}
+//# sourceMappingURL=PointerStore.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-splain",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Architectural mapping and behavioral call-chain engine. Built on a language-agnostic foundation with specialized optimization for TypeScript/JavaScript projects.",
   "type": "module",
   "license": "MIT",
@@ -38,17 +38,24 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "async-mutex": "^0.5.0",
+    "better-sqlite3": "^12.10.0",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.0.0",
+    "tar": "^7.5.16",
     "tree-sitter-wasms": "^0.1.11",
     "uuid": "^9.0.0",
     "web-tree-sitter": "^0.22.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/fs-extra": "^11.0.0",
+    "@types/minimatch": "^5.1.2",
+    "@types/tar": "^6.1.13",
     "@types/uuid": "^9.0.0",
     "esbuild": "^0.28.0",
+    "minimatch": "^10.2.5",
+    "tsx": "^4.22.4",
     "typescript": "^5.4.0"
   },
   "files": [