afterburn-cli 1.0.0

package/dist/analysis/source-mapper.js

@@ -0,0 +1,329 @@
+// Cross-references browser errors with TypeScript/JavaScript source code using AST analysis
+import { Project, SyntaxKind } from 'ts-morph';
+import path from 'path';
+import fs from 'fs-extra';
+/**
+ * Extract search terms from error messages to find relevant code locations
+ */
+function extractSearchTerms(errorMessage) {
+    // Strip common error prefixes
+    let cleaned = errorMessage
+        .replace(/^(Error|TypeError|ReferenceError|SyntaxError|RangeError):\s*/i, '')
+        .trim();
+    const terms = new Set();
+    // Extract quoted strings (between ', ", or `)
+    const quotedRegex = /['"`]([^'"`]+)['"`]/g;
+    let match;
+    while ((match = quotedRegex.exec(cleaned)) !== null) {
+        terms.add(match[1]);
+    }
+    // Extract identifiers after "Cannot read property" / "Cannot read properties of"
+    const propertyMatch = cleaned.match(/Cannot read propert(?:y|ies)(?: of)? ['"`]?(\w+)['"`]?/i);
+    if (propertyMatch) {
+        terms.add(propertyMatch[1]);
+    }
+    // Extract identifiers before "is not a function" / "is not defined"
+    const functionMatch = cleaned.match(/(\w+)\s+is not (?:a function|defined)/i);
+    if (functionMatch) {
+        terms.add(functionMatch[1]);
+    }
+    // Extract URL path segments that look like route handlers
+    const pathMatch = cleaned.match(/\/([a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*)/gi);
+    if (pathMatch) {
+        pathMatch.forEach(p => {
+            const segments = p.split('/').filter(s => s && s.length > 2);
+            segments.forEach(seg => terms.add(seg));
+        });
+    }
+    // Extract camelCase and PascalCase identifiers
+    const identifierRegex = /\b([a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*|[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)*)\b/g;
+    while ((match = identifierRegex.exec(cleaned)) !== null) {
+        terms.add(match[1]);
+    }
+    // Filter out common words and noise
+    const stopWords = new Set(['undefined', 'null', 'object', 'string', 'number', 'the', 'of', 'is', 'at', 'in', 'on', 'to', 'a', 'an']);
+    const filtered = Array.from(terms).filter(term => term.length > 2 && !stopWords.has(term.toLowerCase()));
+    // Sort by length (longer = more specific = search first)
+    return filtered.sort((a, b) => b.length - a.length);
+}
+/**
+ * Map a single error message to source code location
+ * Returns null if source path invalid, timeout occurs, or no match found
+ *
+ * Uses a cancelled flag so that when the timeout fires, the ts-morph scanning
+ * loop exits early and the Project reference is released for GC. Without this,
+ * Promise.race would leave the AST work running and consuming CPU/memory
+ * indefinitely on large codebases.
+ */
+export async function mapErrorToSource(errorMessage, sourcePath) {
+    let cancelled = false;
+    let projectRef = null;
+    // 10-second timeout protection — sets cancellation flag and releases ts-morph Project
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => {
+            cancelled = true;
+            projectRef = null; // Release for GC
+            resolve(null);
+        }, 10000);
+    });
+    const searchPromise = async () => {
+        try {
+            // Validate source path exists
+            if (!await fs.pathExists(sourcePath)) {
+                console.warn(`[source-mapper] Source path does not exist: ${sourcePath}`);
+                return null;
+            }
+            // Initialize ts-morph project
+            projectRef = new Project({
+                skipAddingFilesFromTsConfig: true,
+            });
+            // Try to load from tsconfig.json
+            const tsconfigPath = path.join(sourcePath, 'tsconfig.json');
+            if (await fs.pathExists(tsconfigPath)) {
+                projectRef.addSourceFilesFromTsConfig(tsconfigPath);
+            }
+            else {
+                // Fallback: manually add .ts/.tsx/.js/.jsx files
+                const patterns = [
+                    path.join(sourcePath, '**/*.ts'),
+                    path.join(sourcePath, '**/*.tsx'),
+                    path.join(sourcePath, '**/*.js'),
+                    path.join(sourcePath, '**/*.jsx'),
+                ];
+                projectRef.addSourceFilesAtPaths(patterns);
+            }
+            if (cancelled)
+                return null;
+            const sourceFiles = projectRef.getSourceFiles();
+            if (sourceFiles.length === 0) {
+                console.warn(`[source-mapper] No source files found in: ${sourcePath}`);
+                return null;
+            }
+            // Extract search terms from error message
+            const searchTerms = extractSearchTerms(errorMessage);
+            if (searchTerms.length === 0) {
+                return null;
+            }
+            const matches = [];
+            for (const sourceFile of sourceFiles) {
+                // Check cancellation between files to avoid wasted CPU on timeout
+                if (cancelled)
+                    return null;
+                const filePath = sourceFile.getFilePath();
+                // Search function declarations and arrow functions
+                sourceFile.getFunctions().forEach(fn => {
+                    const name = fn.getName();
+                    if (name && searchTerms.some(term => name.includes(term))) {
+                        const score = searchTerms.some(term => name === term) ? 10 : 5;
+                        matches.push({
+                            file: filePath,
+                            line: fn.getStartLineNumber(),
+                            context: fn.getText().slice(0, 200),
+                            score,
+                        });
+                    }
+                });
+                // Search arrow functions in variable declarations
+                sourceFile.getVariableDeclarations().forEach(varDecl => {
+                    const name = varDecl.getName();
+                    const initializer = varDecl.getInitializer();
+                    if (initializer?.getKind() === SyntaxKind.ArrowFunction) {
+                        if (searchTerms.some(term => name.includes(term))) {
+                            const score = searchTerms.some(term => name === term) ? 10 : 5;
+                            matches.push({
+                                file: filePath,
+                                line: varDecl.getStartLineNumber(),
+                                context: varDecl.getText().slice(0, 200),
+                                score,
+                            });
+                        }
+                    }
+                });
+                // Search class declarations
+                sourceFile.getClasses().forEach(cls => {
+                    const name = cls.getName();
+                    if (name && searchTerms.some(term => name.includes(term))) {
+                        const score = searchTerms.some(term => name === term) ? 10 : 5;
+                        matches.push({
+                            file: filePath,
+                            line: cls.getStartLineNumber(),
+                            context: cls.getText().slice(0, 200),
+                            score,
+                        });
+                    }
+                });
+                // Search string literals
+                sourceFile.getDescendantsOfKind(SyntaxKind.StringLiteral).forEach(str => {
+                    const text = str.getLiteralText();
+                    if (searchTerms.some(term => text.includes(term))) {
+                        matches.push({
+                            file: filePath,
+                            line: str.getStartLineNumber(),
+                            context: str.getParent()?.getText().slice(0, 200) || text,
+                            score: 3,
+                        });
+                    }
+                });
+            }
+            // Return highest-scoring match
+            if (matches.length === 0) {
+                return null;
+            }
+            matches.sort((a, b) => b.score - a.score);
+            const best = matches[0];
+            return {
+                file: path.relative(sourcePath, best.file),
+                line: best.line,
+                context: best.context,
+            };
+        }
+        catch (error) {
+            // Graceful degradation on any ts-morph errors
+            console.warn(`[source-mapper] Failed to analyze source:`, error);
+            return null;
+        }
+        finally {
+            projectRef = null; // Ensure GC can collect ts-morph resources
+        }
+    };
+    // Race between search and timeout
+    return Promise.race([searchPromise(), timeoutPromise]);
+}
+/**
+ * Map multiple errors to source locations in a single batch.
+ * Shares 10-second timeout across all searches for efficiency.
+ * Uses cancellation flag to stop work when timeout fires (same pattern as mapErrorToSource).
+ */
+export async function mapMultipleErrors(errors, sourcePath) {
+    const results = new Map();
+    let cancelled = false;
+    let projectRef = null;
+    // 10-second timeout for entire batch — cancels ongoing work and frees ts-morph memory
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => {
+            cancelled = true;
+            projectRef = null;
+            resolve();
+        }, 10000);
+    });
+    const batchSearchPromise = async () => {
+        try {
+            // Validate source path exists
+            if (!await fs.pathExists(sourcePath)) {
+                console.warn(`[source-mapper] Source path does not exist: ${sourcePath}`);
+                return;
+            }
+            // Initialize ts-morph project ONCE
+            projectRef = new Project({
+                skipAddingFilesFromTsConfig: true,
+            });
+            const tsconfigPath = path.join(sourcePath, 'tsconfig.json');
+            if (await fs.pathExists(tsconfigPath)) {
+                projectRef.addSourceFilesFromTsConfig(tsconfigPath);
+            }
+            else {
+                const patterns = [
+                    path.join(sourcePath, '**/*.ts'),
+                    path.join(sourcePath, '**/*.tsx'),
+                    path.join(sourcePath, '**/*.js'),
+                    path.join(sourcePath, '**/*.jsx'),
+                ];
+                projectRef.addSourceFilesAtPaths(patterns);
+            }
+            if (cancelled)
+                return;
+            const sourceFiles = projectRef.getSourceFiles();
+            if (sourceFiles.length === 0) {
+                return;
+            }
+            // Search for each error
+            for (const error of errors) {
+                if (cancelled)
+                    return;
+                const searchTerms = extractSearchTerms(error.message);
+                if (searchTerms.length === 0)
+                    continue;
+                const matches = [];
+                for (const sourceFile of sourceFiles) {
+                    if (cancelled)
+                        return;
+                    const filePath = sourceFile.getFilePath();
+                    // Search functions
+                    sourceFile.getFunctions().forEach(fn => {
+                        const name = fn.getName();
+                        if (name && searchTerms.some(term => name.includes(term))) {
+                            const score = searchTerms.some(term => name === term) ? 10 : 5;
+                            matches.push({
+                                file: filePath,
+                                line: fn.getStartLineNumber(),
+                                context: fn.getText().slice(0, 200),
+                                score,
+                            });
+                        }
+                    });
+                    // Search arrow functions
+                    sourceFile.getVariableDeclarations().forEach(varDecl => {
+                        const name = varDecl.getName();
+                        const initializer = varDecl.getInitializer();
+                        if (initializer?.getKind() === SyntaxKind.ArrowFunction) {
+                            if (searchTerms.some(term => name.includes(term))) {
+                                const score = searchTerms.some(term => name === term) ? 10 : 5;
+                                matches.push({
+                                    file: filePath,
+                                    line: varDecl.getStartLineNumber(),
+                                    context: varDecl.getText().slice(0, 200),
+                                    score,
+                                });
+                            }
+                        }
+                    });
+                    // Search classes
+                    sourceFile.getClasses().forEach(cls => {
+                        const name = cls.getName();
+                        if (name && searchTerms.some(term => name.includes(term))) {
+                            const score = searchTerms.some(term => name === term) ? 10 : 5;
+                            matches.push({
+                                file: filePath,
+                                line: cls.getStartLineNumber(),
+                                context: cls.getText().slice(0, 200),
+                                score,
+                            });
+                        }
+                    });
+                    // Search string literals
+                    sourceFile.getDescendantsOfKind(SyntaxKind.StringLiteral).forEach(str => {
+                        const text = str.getLiteralText();
+                        if (searchTerms.some(term => text.includes(term))) {
+                            matches.push({
+                                file: filePath,
+                                line: str.getStartLineNumber(),
+                                context: str.getParent()?.getText().slice(0, 200) || text,
+                                score: 3,
+                            });
+                        }
+                    });
+                }
+                // Store best match
+                if (matches.length > 0) {
+                    matches.sort((a, b) => b.score - a.score);
+                    const best = matches[0];
+                    results.set(error.message, {
+                        file: path.relative(sourcePath, best.file),
+                        line: best.line,
+                        context: best.context,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`[source-mapper] Batch analysis failed:`, error);
+        }
+        finally {
+            projectRef = null; // Ensure GC can collect ts-morph resources
+        }
+    };
+    // Race between batch search and timeout
+    await Promise.race([batchSearchPromise(), timeoutPromise]);
+    return results;
+}
+//# sourceMappingURL=source-mapper.js.map

package/dist/analysis/source-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-mapper.js","sourceRoot":"","sources":["../../src/analysis/source-mapper.ts"],"names":[],"mappings":"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"}

package/dist/analysis/ui-auditor.d.ts

@@ -0,0 +1,9 @@
+import { ExecutionArtifact } from '../types/execution.js';
+import { UIAuditResult } from './diagnosis-schema.js';
+/**
+ * Main export: Audit UI/UX issues from screenshots in execution artifact
+ */
+export declare function auditUI(artifact: ExecutionArtifact, options?: {
+    apiKey?: string;
+    aiEnabled?: boolean;
+}): Promise<UIAuditResult[]>;

package/dist/analysis/ui-auditor.js

@@ -0,0 +1,104 @@
+// Vision LLM-powered UI/UX auditor for screenshot analysis
+import { GeminiClient } from '../ai/gemini-client.js';
+import { UIAuditSchema } from './diagnosis-schema.js';
+import { redactSensitiveUrl } from '../utils/sanitizer.js';
+import fs from 'node:fs';
+/**
+ * Main export: Audit UI/UX issues from screenshots in execution artifact
+ */
+export async function auditUI(artifact, options) {
+    const apiKey = options?.apiKey || process.env.GEMINI_API_KEY;
+    const aiEnabled = options?.aiEnabled ?? (apiKey ? true : false);
+    if (!apiKey || !aiEnabled) {
+        console.warn('UI auditing requires GEMINI_API_KEY and AI to be enabled. Skipping visual analysis.');
+        return [];
+    }
+    // Extract screenshots from execution artifact
+    const screenshots = extractScreenshots(artifact);
+    if (screenshots.length === 0) {
+        return [];
+    }
+    // Initialize Gemini client
+    const gemini = new GeminiClient(apiKey);
+    // Audit each screenshot
+    const auditResults = [];
+    for (const screenshot of screenshots) {
+        try {
+            const audit = await auditScreenshot(screenshot.pngPath, screenshot.url, gemini);
+            auditResults.push(audit);
+        }
+        catch (error) {
+            console.warn(`Failed to audit screenshot ${screenshot.pngPath}:`, error);
+            // Continue with other screenshots
+        }
+    }
+    return auditResults;
+}
+/**
+ * Extract screenshots from execution artifact
+ * Collects from workflowResults[].stepResults[].evidence?.screenshotRef
+ */
+function extractScreenshots(artifact) {
+    const screenshotMap = new Map(); // pngPath -> url (deduplicate by path)
+    for (const workflow of artifact.workflowResults) {
+        for (const step of workflow.stepResults) {
+            if (step.evidence?.screenshotRef) {
+                const { pngPath } = step.evidence.screenshotRef;
+                const { pageUrl } = step.evidence;
+                // Deduplicate by path, verify file exists
+                if (!screenshotMap.has(pngPath) && fs.existsSync(pngPath)) {
+                    screenshotMap.set(pngPath, pageUrl);
+                }
+            }
+        }
+    }
+    // Convert map to array
+    return Array.from(screenshotMap.entries()).map(([pngPath, url]) => ({
+        url,
+        pngPath,
+    }));
+}
+/**
+ * Audit a single screenshot using Gemini Vision LLM
+ */
+async function auditScreenshot(pngPath, pageUrl, gemini) {
+    // Redact sensitive URL before sending to Gemini
+    const safeUrl = redactSensitiveUrl(pageUrl);
+    const prompt = buildVisionPrompt(safeUrl);
+    // Call Gemini Vision API with structured output
+    const audit = await gemini.generateStructuredWithImage(prompt, UIAuditSchema, pngPath);
+    return {
+        ...audit,
+        pageUrl: safeUrl,
+        screenshotRef: pngPath,
+    };
+}
+/**
+ * Build vision LLM prompt for UI auditing
+ */
+function buildVisionPrompt(pageUrl) {
+    const safeUrl = redactSensitiveUrl(pageUrl);
+    return `You are a UI/UX expert reviewing a web page screenshot. Analyze it for visual issues.
+
+Page URL: ${safeUrl}
+
+Look for these specific issues:
+
+1. LAYOUT ISSUES: Elements overlapping, cramped spacing, content cut off at edges,
+   misaligned sections, inconsistent margins/padding, elements pushed off-screen
+
+2. CONTRAST & READABILITY: Text hard to read against background, insufficient color
+   contrast (WCAG AA requires 4.5:1 for normal text), tiny font sizes, light gray
+   text on white background
+
+3. FORMATTING ISSUES: Text truncated with "...", buttons too small to tap on mobile,
+   inconsistent font sizes, broken grid layouts, images stretched or squished
+
+4. IMPROVEMENT SUGGESTIONS: What would make this page better for users?
+   Write suggestions in plain English as if explaining to someone who built this
+   with AI tools and doesn't know CSS deeply.
+
+Be specific about WHERE on the page each issue appears (top, bottom, left sidebar, etc).
+Only report issues you are confident about. If the page looks fine, say so.`;
+}
+//# sourceMappingURL=ui-auditor.js.map

package/dist/analysis/ui-auditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-auditor.js","sourceRoot":"","sources":["../../src/analysis/ui-auditor.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAiB,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,QAA2B,EAC3B,OAAkD;IAElD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC7D,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAEhE,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,qFAAqF,CAAC,CAAC;QACpG,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,8CAA8C;IAC9C,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAEjD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAExC,wBAAwB;IACxB,MAAM,YAAY,GAAoB,EAAE,CAAC;IAEzC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAChF,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,8BAA8B,UAAU,CAAC,OAAO,GAAG,EAAE,KAAK,CAAC,CAAC;YACzE,kCAAkC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,QAA2B;IACrD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,uCAAuC;IAExF,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,eAAe,EAAE,CAAC;QAChD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;gBACjC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAChD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAElC,0CAA0C;gBAC1C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC1D,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,OAAO,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;QAClE,GAAG;QACH,OAAO;KACR,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,eAAe,CAC5B,OAAe,EACf,OAAe,EACf,MAAoB;IAEpB,gDAAgD;IAChD,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE1C,gDAAgD;IAChD,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;IAEvF,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,OAAO;QAChB,aAAa,EAAE,OAAO;KACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,OAAe;IACxC,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO;;YAEG,OAAO;;;;;;;;;;;;;;;;;;;4EAmByD,CAAC;AAC7E,CAAC"}

package/dist/artifacts/artifact-storage.d.ts

@@ -0,0 +1,44 @@
+import type { ArtifactMetadata } from '../types/artifacts.js';
+/**
+ * Manages JSON artifact storage with save/load/cleanup operations
+ */
+export declare class ArtifactStorage {
+    private readonly baseDir;
+    private currentSessionId?;
+    constructor(baseDir?: string);
+    private buildFilename;
+    /**
+     * Saves an artifact as a versioned JSON file
+     * @param artifact - Artifact with metadata
+     * @returns Filepath where artifact was saved
+     */
+    save<T extends ArtifactMetadata>(artifact: T): Promise<string>;
+    /**
+     * Loads an artifact from storage
+     * @param stage - Pipeline stage name
+     * @param sessionId - Session UUID
+     * @returns Parsed artifact
+     * @throws Error if artifact not found
+     */
+    load<T extends ArtifactMetadata>(stage: string, sessionId: string): Promise<T>;
+    /**
+     * Checks if an artifact exists
+     * @param stage - Pipeline stage name
+     * @param sessionId - Session UUID
+     * @returns True if artifact file exists
+     */
+    exists(stage: string, sessionId: string): Promise<boolean>;
+    /**
+     * Lists all artifact files, optionally filtered by stage
+     * @param stage - Optional stage prefix to filter by
+     * @returns Array of artifact filenames
+     */
+    list(stage?: string): Promise<string[]>;
+    /**
+     * Removes artifacts older than specified days based on file modification time.
+     * Excludes artifacts from the current session.
+     * @param olderThanDays - Age threshold in days (default: 7). Set to 0 to clean all old artifacts.
+     * @returns Count of deleted files
+     */
+    cleanup(olderThanDays?: number): Promise<number>;
+}

package/dist/artifacts/artifact-storage.js

@@ -0,0 +1,99 @@
+// JSON file persistence for pipeline artifacts with versioning and cleanup
+import { join } from 'node:path';
+import fs from 'fs-extra';
+import { sanitizeSessionId } from '../core/validation.js';
+/**
+ * Manages JSON artifact storage with save/load/cleanup operations
+ */
+export class ArtifactStorage {
+    baseDir;
+    currentSessionId;
+    constructor(baseDir = '.afterburn/artifacts') {
+        this.baseDir = baseDir;
+        fs.ensureDirSync(this.baseDir);
+    }
+    buildFilename(stage, sessionId) {
+        const safeStage = stage.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const safeSessionId = sanitizeSessionId(sessionId);
+        return `${safeStage}-${safeSessionId}.json`;
+    }
+    /**
+     * Saves an artifact as a versioned JSON file
+     * @param artifact - Artifact with metadata
+     * @returns Filepath where artifact was saved
+     */
+    async save(artifact) {
+        const filename = this.buildFilename(artifact.stage, artifact.sessionId);
+        const filepath = join(this.baseDir, filename);
+        await fs.writeJson(filepath, artifact, { spaces: 2 });
+        // Track current session for cleanup
+        this.currentSessionId = sanitizeSessionId(artifact.sessionId);
+        return filepath;
+    }
+    /**
+     * Loads an artifact from storage
+     * @param stage - Pipeline stage name
+     * @param sessionId - Session UUID
+     * @returns Parsed artifact
+     * @throws Error if artifact not found
+     */
+    async load(stage, sessionId) {
+        const filename = this.buildFilename(stage, sessionId);
+        const filepath = join(this.baseDir, filename);
+        if (!(await fs.pathExists(filepath))) {
+            throw new Error(`Artifact not found: ${stage}-${sessionId}`);
+        }
+        return fs.readJson(filepath);
+    }
+    /**
+     * Checks if an artifact exists
+     * @param stage - Pipeline stage name
+     * @param sessionId - Session UUID
+     * @returns True if artifact file exists
+     */
+    async exists(stage, sessionId) {
+        const filename = this.buildFilename(stage, sessionId);
+        const filepath = join(this.baseDir, filename);
+        return fs.pathExists(filepath);
+    }
+    /**
+     * Lists all artifact files, optionally filtered by stage
+     * @param stage - Optional stage prefix to filter by
+     * @returns Array of artifact filenames
+     */
+    async list(stage) {
+        const files = await fs.readdir(this.baseDir);
+        const jsonFiles = files.filter((f) => f.endsWith('.json'));
+        if (!stage) {
+            return jsonFiles;
+        }
+        return jsonFiles.filter((f) => f.startsWith(`${stage}-`));
+    }
+    /**
+     * Removes artifacts older than specified days based on file modification time.
+     * Excludes artifacts from the current session.
+     * @param olderThanDays - Age threshold in days (default: 7). Set to 0 to clean all old artifacts.
+     * @returns Count of deleted files
+     */
+    async cleanup(olderThanDays = 7) {
+        const files = await this.list();
+        const now = Date.now();
+        const threshold = olderThanDays * 24 * 60 * 60 * 1000; // Convert days to milliseconds
+        let deletedCount = 0;
+        for (const file of files) {
+            // Skip artifacts from current session
+            if (this.currentSessionId && file.includes(this.currentSessionId)) {
+                continue;
+            }
+            const filepath = join(this.baseDir, file);
+            const stats = await fs.stat(filepath);
+            const age = now - stats.mtimeMs;
+            if (age > threshold) {
+                await fs.unlink(filepath);
+                deletedCount++;
+            }
+        }
+        return deletedCount;
+    }
+}
+//# sourceMappingURL=artifact-storage.js.map

package/dist/artifacts/artifact-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-storage.js","sourceRoot":"","sources":["../../src/artifacts/artifact-storage.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/index.d.ts

@@ -0,0 +1 @@
+export { ArtifactStorage } from './artifact-storage.js';

package/dist/artifacts/index.js

@@ -0,0 +1,3 @@
+// Barrel export for artifacts module
+export { ArtifactStorage } from './artifact-storage.js';
+//# sourceMappingURL=index.js.map

package/dist/artifacts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}