vibe-splain 3.1.0 → 3.2.0

package/dist/commands/bundle.d.ts

@@ -0,0 +1,4 @@
+export declare function bundleCommand(scanId: string, opts?: {
+    output?: string;
+    projectRoot?: string;
+}): Promise<void>;

package/dist/commands/bundle.js

@@ -0,0 +1,68 @@
+import { join } from 'path';
+import { writeFile, mkdir, copyFile, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as tar from 'tar';
+import { PointerStore } from '../store/PointerStore.js';
+import { BlobStore } from '../store/BlobStore.js';
+export async function bundleCommand(scanId, opts = {}) {
+    const root = opts.projectRoot ?? process.cwd();
+    const outputPath = opts.output ?? join(root, `vibe-bundle-${scanId}.tar.gz`);
+    console.error(`[vibe-splain bundle] Bundling scan ${scanId} from ${root}`);
+    const pointerStore = PointerStore.open(root);
+    const blobStore = new BlobStore(root);
+    const pointers = pointerStore.listPointersByScan(scanId);
+    if (pointers.length === 0) {
+        throw new Error(`No pointers found for scanId "${scanId}"`);
+    }
+    // Stage bundle into a temp directory with predictable layout
+    const stagingDir = join(root, '.vibe-splainer', 'tmp', `bundle-stage-${scanId}`);
+    const blobsStageDir = join(stagingDir, 'blobs');
+    await mkdir(blobsStageDir, { recursive: true });
+    try {
+        // Build manifest for the bundle
+        const bundleManifest = {
+            schemaVersion: '1.0.0',
+            scanId,
+            exportedAt: new Date().toISOString(),
+            projectRoot: root,
+            pointers: pointers.map(p => ({
+                pointerId: p.pointerId,
+                scanId: p.scanId,
+                artifactName: p.artifactName,
+                contentHash: p.contentHash,
+                blobFile: `blobs/${p.contentHash.replace('sha256:', 'sha256_')}`,
+                schemaVersion: p.schemaVersion,
+                createdAt: p.createdAt,
+                expiresAt: p.expiresAt,
+            })),
+        };
+        await writeFile(join(stagingDir, 'bundle-manifest.json'), JSON.stringify(bundleManifest, null, 2), 'utf8');
+        // Copy blobs (deduplicated by contentHash)
+        const seen = new Set();
+        for (const p of pointers) {
+            const hex = p.contentHash.replace('sha256:', '');
+            if (seen.has(hex))
+                continue;
+            seen.add(hex);
+            const srcPath = p.blobPath;
+            if (!existsSync(srcPath)) {
+                console.error(`[vibe-splain bundle] Warning: blob missing for ${p.pointerId}: ${srcPath}`);
+                continue;
+            }
+            await copyFile(srcPath, join(blobsStageDir, `sha256_${hex}`));
+        }
+        // Create tarball from staging directory
+        await tar.create({
+            gzip: true,
+            file: outputPath,
+            cwd: stagingDir,
+            portable: true,
+        }, ['.']);
+        console.error(`[vibe-splain bundle] Bundle written: ${outputPath}`);
+        console.error(`[vibe-splain bundle] ${pointers.length} pointers, ${seen.size} blobs`);
+    }
+    finally {
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=bundle.js.map

package/dist/commands/gc.d.ts

@@ -0,0 +1,3 @@
+export declare function gcCommand(projectRoot?: string, opts?: {
+    keepScans?: number;
+}): Promise<void>;

package/dist/commands/gc.js

@@ -0,0 +1,59 @@
+import { join } from 'path';
+import { rm, readdir } from 'fs/promises';
+import { PointerStore } from '../store/PointerStore.js';
+import { BlobStore } from '../store/BlobStore.js';
+const DEFAULT_KEEP_SCANS = 3;
+export async function gcCommand(projectRoot, opts = {}) {
+    const root = projectRoot ?? process.cwd();
+    const keepScans = opts.keepScans ?? DEFAULT_KEEP_SCANS;
+    console.error(`[vibe-splain gc] Running GC on ${root} (keeping last ${keepScans} scans)`);
+    const pointerStore = PointerStore.open(root);
+    const blobStore = new BlobStore(root);
+    // 1. Get all scan IDs ordered by createdAt desc
+    const allScanIds = pointerStore.listAllScanIds();
+    console.error(`[vibe-splain gc] Found ${allScanIds.length} scans`);
+    // Keep the N most recent by taking last N from sorted list
+    // Scan IDs contain timestamps, sort lexicographically descending
+    const sorted = [...allScanIds].sort().reverse();
+    const keepIds = sorted.slice(0, keepScans);
+    const deleteIds = sorted.slice(keepScans);
+    if (deleteIds.length === 0) {
+        console.error('[vibe-splain gc] Nothing to collect');
+        return;
+    }
+    // 2. Collect all blob paths still referenced by kept pointers before deletion
+    const keptPointers = keepIds.flatMap(id => pointerStore.listPointersByScan(id));
+    const referencedBlobs = new Set(keptPointers.map(p => p.blobPath));
+    // 3. Delete old scan pointers
+    const deleted = await pointerStore.gcScanPointers(keepIds);
+    console.error(`[vibe-splain gc] Deleted ${deleted} pointer rows`);
+    // 4. Delete unreferenced blobs (reference count = 0)
+    const allBlobs = await blobStore.listBlobPaths();
+    let blobsDeleted = 0;
+    for (const blobPath of allBlobs) {
+        if (!referencedBlobs.has(blobPath)) {
+            try {
+                await rm(blobPath);
+                blobsDeleted++;
+            }
+            catch {
+                // ignore — may have already been deleted
+            }
+        }
+    }
+    console.error(`[vibe-splain gc] Deleted ${blobsDeleted} unreferenced blobs`);
+    // 5. Clean up tmp dir
+    const tmpDir = join(root, '.vibe-splainer', 'tmp');
+    try {
+        const tmpFiles = await readdir(tmpDir);
+        for (const f of tmpFiles) {
+            await rm(join(tmpDir, f), { force: true });
+        }
+        console.error(`[vibe-splain gc] Cleaned ${tmpFiles.length} tmp files`);
+    }
+    catch {
+        // tmp dir may not exist
+    }
+    console.error('[vibe-splain gc] Done');
+}
+//# sourceMappingURL=gc.js.map

package/dist/commands/importBundle.d.ts

@@ -0,0 +1,4 @@
+export declare function importBundleCommand(tarballPath: string, opts?: {
+    projectRoot?: string;
+    namespace?: string;
+}): Promise<void>;

package/dist/commands/importBundle.js

@@ -0,0 +1,80 @@
+import { join } from 'path';
+import { readFile, mkdir, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import * as tar from 'tar';
+import { createHash } from 'crypto';
+import { BlobStore } from '../store/BlobStore.js';
+import { PointerStore } from '../store/PointerStore.js';
+export async function importBundleCommand(tarballPath, opts = {}) {
+    const root = opts.projectRoot ?? process.cwd();
+    const namespace = opts.namespace ?? `imported_${Date.now()}`;
+    console.error(`[vibe-splain import] Importing ${tarballPath} into ${root} (namespace: ${namespace})`);
+    if (!existsSync(tarballPath)) {
+        throw new Error(`Tarball not found: ${tarballPath}`);
+    }
+    // Extract to a temp directory
+    const extractDir = join(root, '.vibe-splainer', 'tmp', `import-${namespace}`);
+    await mkdir(extractDir, { recursive: true });
+    try {
+        await tar.extract({
+            file: tarballPath,
+            cwd: extractDir,
+        });
+        // Read bundle manifest
+        const manifestPath = join(extractDir, 'bundle-manifest.json');
+        if (!existsSync(manifestPath)) {
+            throw new Error('Invalid bundle: missing bundle-manifest.json');
+        }
+        const manifestRaw = await readFile(manifestPath, 'utf8');
+        const manifest = JSON.parse(manifestRaw);
+        if (manifest.schemaVersion !== '1.0.0') {
+            throw new Error(`Unsupported bundle schema version: ${manifest.schemaVersion}`);
+        }
+        const blobStore = new BlobStore(root);
+        const pointerStore = PointerStore.open(root);
+        await blobStore.ensureDirs();
+        let imported = 0;
+        let hashErrors = 0;
+        for (const entry of manifest.pointers) {
+            const blobSrcPath = join(extractDir, entry.blobFile);
+            if (!existsSync(blobSrcPath)) {
+                console.error(`[vibe-splain import] Missing blob for pointer ${entry.pointerId}: ${entry.blobFile}`);
+                hashErrors++;
+                continue;
+            }
+            // Verify hash before importing
+            const content = await readFile(blobSrcPath);
+            const actualHash = `sha256:${createHash('sha256').update(content).digest('hex')}`;
+            if (actualHash !== entry.contentHash) {
+                console.error(`[vibe-splain import] Hash mismatch for ${entry.pointerId}: expected ${entry.contentHash}, got ${actualHash}`);
+                hashErrors++;
+                continue;
+            }
+            // Write blob to local store (atomic)
+            const { blobPath } = await blobStore.writeAtomic(content);
+            // Insert pointer under bundle namespace alias
+            const namespacedPointerId = `${namespace}::${entry.pointerId}`;
+            const namespacedScanId = `${namespace}::${entry.scanId}`;
+            await pointerStore.insertPointer({
+                pointerId: namespacedPointerId,
+                scanId: namespacedScanId,
+                artifactName: entry.artifactName,
+                contentHash: entry.contentHash,
+                blobPath,
+                schemaVersion: entry.schemaVersion,
+                createdAt: entry.createdAt,
+                expiresAt: entry.expiresAt,
+            });
+            imported++;
+        }
+        if (hashErrors > 0) {
+            console.error(`[vibe-splain import] Warning: ${hashErrors} blobs failed hash verification and were skipped`);
+        }
+        console.error(`[vibe-splain import] Imported ${imported}/${manifest.pointers.length} pointers under namespace "${namespace}"`);
+        console.error(`[vibe-splain import] Original scanId: ${manifest.scanId} → namespaced as: ${namespace}::${manifest.scanId}`);
+    }
+    finally {
+        await rm(extractDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=importBundle.js.map

package/dist/export/ExportOrchestrator.d.ts

@@ -4,9 +4,27 @@ export interface ExportOptions {
     budget?: number;
     scope?: string;
 }
+export interface ManifestArtifactEntry {
+    name: string;
+    pointer: string;
+    contentHash: string;
+    sizeBytes: number;
+    indexes?: Record<string, string>;
+    hydrators?: string[];
+}
+export interface ScanManifest {
+    schemaVersion: '2.0.0';
+    scanId: string;
+    generatedAt: string;
+    projectRoot: string;
+    artifacts: ManifestArtifactEntry[];
+}
 export declare class ExportOrchestrator {
     private projectRoot;
     constructor(projectRoot: string);
-    writeBundle(dossier: Dossier, options?: ExportOptions, store?: AnalysisStore, graph?: ImportGraph): Promise<void>;
+    writeBundle(dossier: Dossier, options?: ExportOptions, store?: AnalysisStore, graph?: ImportGraph, scanId?: string): Promise<{
+        scanId: string;
+        manifestPointer: string;
+    }>;
     private buildViewModel;
 }

package/dist/export/ExportOrchestrator.js

@@ -7,12 +7,15 @@ import { AgentMarkdownRenderer } from './renderers/AgentMarkdownRenderer.js';
 import { ValidationRenderer } from './renderers/ValidationRenderer.js';
 import { RawAnalysisRenderer } from './renderers/RawAnalysisRenderer.js';
 import { GraphRenderer } from './renderers/GraphRenderer.js';
+import { BlobStore } from '../store/BlobStore.js';
+import { PointerStore } from '../store/PointerStore.js';
+import { v4 as uuidv4 } from 'uuid';
 export class ExportOrchestrator {
     projectRoot;
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
-    async writeBundle(dossier, options = {}, store, graph) {
+    async writeBundle(dossier, options = {}, store, graph, scanId) {
         const finalStore = store || await readAnalysis(this.projectRoot);
         if (!finalStore) {
             throw new Error('Analysis store not found. Scan the project first.');
@@ -47,6 +50,89 @@ export class ExportOrchestrator {
         }
         const writer = new ArtifactBundleWriter(this.projectRoot);
         await writer.writeBundle(artifacts);
+        // Register artifacts in BlobStore + PointerStore and build manifest
+        const effectiveScanId = scanId ?? `scan_${Date.now()}`;
+        const blobStore = new BlobStore(this.projectRoot);
+        const pointerStore = PointerStore.open(this.projectRoot);
+        const now = Date.now();
+        const manifestEntries = [];
+        for (const artifact of artifacts) {
+            const content = typeof artifact.content === 'string'
+                ? Buffer.from(artifact.content, 'utf8')
+                : artifact.content;
+            const { contentHash, blobPath } = await blobStore.writeAtomic(content);
+            const pointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+            await pointerStore.insertPointer({
+                pointerId,
+                scanId: effectiveScanId,
+                artifactName: artifact.type,
+                contentHash,
+                blobPath,
+                schemaVersion: '1.0.0',
+                createdAt: now,
+                expiresAt: null,
+            });
+            const entry = {
+                name: artifact.type,
+                pointer: pointerId,
+                contentHash,
+                sizeBytes: content.length,
+            };
+            // Attach hydrator hints for the large analysis artifact
+            if (artifact.type === 'analysis') {
+                entry.hydrators = ['get_project_summary', 'get_start_here'];
+                // Generate analysis.index.json (Start-Here + Top-Heat)
+                const analysisIndex = {
+                    schemaVersion: '1.0.0',
+                    scanId: effectiveScanId,
+                    startHere: dossier.map.topGravity.slice(0, 12),
+                    topHeat: dossier.map.topHeat.slice(0, 12),
+                    pillarSummary: dossier.map.pillars.map(p => ({
+                        name: p.name,
+                        fileCount: p.memberFiles?.length ?? 0,
+                    })),
+                    totalFiles: Object.keys(finalStore.files).length,
+                    realSourceFiles: Object.values(finalStore.files).filter(f => f.isRealSource).length,
+                };
+                const indexContent = Buffer.from(JSON.stringify(analysisIndex, null, 2), 'utf8');
+                const indexWrite = await blobStore.writeAtomic(indexContent);
+                const indexPointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+                await pointerStore.insertPointer({
+                    pointerId: indexPointerId,
+                    scanId: effectiveScanId,
+                    artifactName: 'analysis.index',
+                    contentHash: indexWrite.contentHash,
+                    blobPath: indexWrite.blobPath,
+                    schemaVersion: '1.0.0',
+                    createdAt: now,
+                    expiresAt: null,
+                });
+                entry.indexes = { startHere: indexPointerId };
+            }
+            manifestEntries.push(entry);
+        }
+        // Write and register the scan manifest itself
+        const manifest = {
+            schemaVersion: '2.0.0',
+            scanId: effectiveScanId,
+            generatedAt: new Date(now).toISOString(),
+            projectRoot: this.projectRoot,
+            artifacts: manifestEntries,
+        };
+        const manifestContent = Buffer.from(JSON.stringify(manifest, null, 2), 'utf8');
+        const manifestWrite = await blobStore.writeAtomic(manifestContent);
+        const manifestPointerId = `ptr_manifest_${effectiveScanId}`;
+        await pointerStore.insertPointer({
+            pointerId: manifestPointerId,
+            scanId: effectiveScanId,
+            artifactName: 'artifact_manifest',
+            contentHash: manifestWrite.contentHash,
+            blobPath: manifestWrite.blobPath,
+            schemaVersion: '2.0.0',
+            createdAt: now,
+            expiresAt: null,
+        });
+        return { scanId: effectiveScanId, manifestPointer: manifestPointerId };
     }
     buildViewModel(dossier, store) {
         const recommendations = {};