@showrun/core 0.1.0

package/dist/networkCapture.js

@@ -0,0 +1,390 @@
+/**
+ * Network capture for Playwright page sessions.
+ * Hooks request/response, maintains a rolling buffer with size limits.
+ * Full request headers kept in-memory for replay only; redacted everywhere else.
+ */
+import { gunzipSync } from 'zlib';
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'x-api-key',
+    'proxy-authorization',
+]);
+const POST_DATA_TRUNCATE = 64 * 1024; // 64KB
+const RESPONSE_BODY_MAX_STORE_BYTES = 5 * 1024 * 1024; // 5MB - full body stored when under this (for replay, extract, responseContains)
+const NETWORK_BUFFER_MAX_ENTRIES = 300;
+const NETWORK_BUFFER_MAX_BYTES = 50 * 1024 * 1024; // 50MB - rolling buffer cap so we can keep more large responses
+function redactHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        const lower = k.toLowerCase();
+        out[k] = SENSITIVE_HEADER_NAMES.has(lower) ? '[REDACTED]' : v;
+    }
+    return out;
+}
+function isTextOrJsonContentType(ct) {
+    if (!ct)
+        return false;
+    const lower = ct.toLowerCase();
+    return (lower.includes('application/json') ||
+        lower.includes('+json') ||
+        lower.includes('text/'));
+}
+const GZIP_MAGIC = Buffer.from([0x1f, 0x8b]);
+function isGzip(body) {
+    return body.length >= 2 && body[0] === GZIP_MAGIC[0] && body[1] === GZIP_MAGIC[1];
+}
+/** Decompress gzip if needed; returns body unchanged if not gzip */
+function maybeDecompress(body) {
+    if (isGzip(body)) {
+        try {
+            return gunzipSync(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    return body;
+}
+/** True if buffer looks like JSON (starts with { or [), for responses with missing Content-Type */
+function looksLikeJson(body) {
+    const len = body.length;
+    if (len === 0)
+        return false;
+    let i = 0;
+    while (i < len && (body[i] === 0x20 || body[i] === 0x0a || body[i] === 0x0d || body[i] === 0x09))
+        i++;
+    if (i >= len)
+        return false;
+    const first = body[i];
+    return first === 0x7b || first === 0x5b; // { or [
+}
+let idCounter = 0;
+function nextId() {
+    return `req-${++idCounter}-${Date.now()}`;
+}
+function truncatePostData(raw) {
+    if (raw == null || raw === '')
+        return undefined;
+    if (raw.length > POST_DATA_TRUNCATE) {
+        return raw.slice(0, POST_DATA_TRUNCATE) + '...[truncated]';
+    }
+    return raw;
+}
+/**
+ * Attach network capture to a Playwright page and return the capture API.
+ * Full request headers are kept in-memory only for replay; list/get return redacted summaries.
+ */
+export function attachNetworkCapture(page) {
+    const buffer = [];
+    const mapById = new Map();
+    let totalBytesEstimate = 0;
+    const requestToEntry = new Map();
+    function dropOldest() {
+        while ((buffer.length >= NETWORK_BUFFER_MAX_ENTRIES || totalBytesEstimate > NETWORK_BUFFER_MAX_BYTES) &&
+            buffer.length > 0) {
+            const removed = buffer.shift();
+            mapById.delete(removed.id);
+            totalBytesEstimate -= removed.bytesEstimate;
+        }
+    }
+    function entryToSummary(entry) {
+        const snippet = entry.responseBodyText != null
+            ? entry.responseBodyText.slice(0, 2048)
+            : entry.responseBodyBase64
+                ? '[binary]'
+                : undefined;
+        return {
+            id: entry.id,
+            ts: entry.ts,
+            method: entry.method,
+            url: entry.url,
+            resourceType: entry.resourceType,
+            requestHeaders: redactHeaders(entry.requestHeadersFull),
+            postData: entry.postData,
+            status: entry.status,
+            responseHeaders: entry.responseHeaders,
+            contentType: entry.contentType,
+            responseBodySnippet: snippet,
+            responseBodyAvailable: entry.responseBodyText != null || entry.responseBodyBase64 != null,
+        };
+    }
+    function matchesWhere(entry, where) {
+        if (where.urlIncludes != null && !entry.url.toLowerCase().includes(where.urlIncludes.toLowerCase()))
+            return false;
+        if (where.urlRegex != null) {
+            try {
+                const re = new RegExp(where.urlRegex);
+                if (!re.test(entry.url))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        if (where.method != null && entry.method !== where.method)
+            return false;
+        if (where.status != null && entry.status !== where.status)
+            return false;
+        if (where.contentTypeIncludes != null &&
+            (!entry.contentType || !entry.contentType.toLowerCase().includes(where.contentTypeIncludes.toLowerCase())))
+            return false;
+        if (where.responseContains != null) {
+            let bodyText = entry.responseBodyText ?? null;
+            if (bodyText == null && entry.responseBodyBase64 != null) {
+                try {
+                    const buf = Buffer.from(entry.responseBodyBase64, 'base64');
+                    const decompressed = maybeDecompress(buf);
+                    bodyText = decompressed.toString('utf8');
+                }
+                catch {
+                    bodyText = null;
+                }
+            }
+            if (bodyText == null)
+                return false;
+            if (!bodyText.toLowerCase().includes(where.responseContains.toLowerCase()))
+                return false;
+        }
+        return true;
+    }
+    page.on('request', (request) => {
+        const id = nextId();
+        const url = request.url();
+        const method = request.method();
+        const resourceType = request.resourceType();
+        const headers = request.headers();
+        const headersFull = {};
+        for (const [k, v] of Object.entries(headers)) {
+            headersFull[k] = v;
+        }
+        const postData = truncatePostData(request.postData() ?? undefined);
+        const entry = {
+            id,
+            ts: Date.now(),
+            method,
+            url,
+            resourceType,
+            requestHeaders: redactHeaders(headersFull),
+            requestHeadersFull: headersFull,
+            postData,
+            bytesEstimate: 0,
+        };
+        entry.bytesEstimate =
+            url.length +
+                JSON.stringify(entry.requestHeaders).length +
+                (postData?.length ?? 0) +
+                200;
+        requestToEntry.set(request, entry);
+        mapById.set(id, entry);
+        buffer.push(entry);
+        totalBytesEstimate += entry.bytesEstimate;
+        dropOldest();
+    });
+    page.on('response', async (response) => {
+        const req = response.request();
+        const entry = requestToEntry.get(req);
+        if (!entry)
+            return;
+        entry.status = response.status();
+        const respHeaders = {};
+        for (const [k, v] of Object.entries(response.headers())) {
+            respHeaders[k] = v;
+        }
+        entry.responseHeaders = redactHeaders(respHeaders);
+        const ct = respHeaders['content-type'] ?? respHeaders['Content-Type'];
+        entry.contentType = ct;
+        try {
+            let body = await response.body();
+            body = maybeDecompress(body);
+            const size = body.length;
+            const canStoreAsText = isTextOrJsonContentType(ct) || looksLikeJson(body);
+            if (size <= RESPONSE_BODY_MAX_STORE_BYTES && canStoreAsText) {
+                const text = body.toString('utf8');
+                entry.responseBodyText = text;
+                const added = Buffer.byteLength(text, 'utf8');
+                entry.bytesEstimate += added;
+                totalBytesEstimate += added;
+            }
+            else if (size <= RESPONSE_BODY_MAX_STORE_BYTES && body.length > 0) {
+                entry.responseBodyBase64 = body.toString('base64');
+                const added = Math.ceil((body.length * 4) / 3);
+                entry.bytesEstimate += added;
+                totalBytesEstimate += added;
+            }
+        }
+        catch {
+            // ignore body read errors
+        }
+        requestToEntry.delete(req);
+        dropOldest();
+    });
+    const api = {
+        list(limit = 50, filter = 'all') {
+            let list = buffer.slice(-limit);
+            if (filter === 'api' || filter === 'xhr') {
+                list = list.filter((e) => e.resourceType === 'xhr' ||
+                    e.resourceType === 'fetch' ||
+                    /\/api\//.test(e.url.toLowerCase()) ||
+                    /graphql/i.test(e.url));
+            }
+            return list.map(entryToSummary);
+        },
+        get(requestId) {
+            const entry = mapById.get(requestId);
+            return entry ? entryToSummary(entry) : null;
+        },
+        find(where, pick) {
+            const id = api.getRequestIdByIndex(where, pick);
+            return id ? api.get(id) : null;
+        },
+        getRequestIdByIndex(where, pick) {
+            const matches = [];
+            for (let i = buffer.length - 1; i >= 0; i--) {
+                if (matchesWhere(buffer[i], where))
+                    matches.push(buffer[i]);
+            }
+            if (pick === 'last') {
+                // last = most recent = first in our reversed list
+                return matches.length > 0 ? matches[0].id : null;
+            }
+            // first = oldest match
+            return matches.length > 0 ? matches[matches.length - 1].id : null;
+        },
+        async replay(requestId, overrides) {
+            const entry = mapById.get(requestId);
+            if (!entry) {
+                throw new Error(`Request not found: ${requestId}`);
+            }
+            if (overrides?.setHeaders) {
+                for (const k of Object.keys(overrides.setHeaders)) {
+                    if (SENSITIVE_HEADER_NAMES.has(k.toLowerCase())) {
+                        throw new Error(`Cannot set sensitive header: ${k}`);
+                    }
+                }
+            }
+            // Playwright: page.request is APIRequestContext sharing cookies with the browser context
+            const requestContext = page.request;
+            if (!requestContext || typeof requestContext.fetch !== 'function') {
+                throw new Error('Browser context does not support API request (replay). Playwright version may be too old.');
+            }
+            let url = entry.url;
+            if (overrides?.urlReplace) {
+                try {
+                    const re = new RegExp(overrides.urlReplace.find, 'g');
+                    url = url.replace(re, overrides.urlReplace.replace);
+                }
+                catch (e) {
+                    throw new Error(`overrides.urlReplace.find is not a valid regex: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (overrides?.url != null)
+                url = overrides.url;
+            let body = entry.postData ?? undefined;
+            if (body != null && overrides?.bodyReplace) {
+                try {
+                    const re = new RegExp(overrides.bodyReplace.find, 'g');
+                    body = body.replace(re, overrides.bodyReplace.replace);
+                }
+                catch (e) {
+                    throw new Error(`overrides.bodyReplace.find is not a valid regex: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+            if (overrides?.body != null)
+                body = overrides.body;
+            const method = entry.method;
+            const headers = { ...entry.requestHeadersFull };
+            if (overrides?.setHeaders) {
+                for (const [k, v] of Object.entries(overrides.setHeaders)) {
+                    if (SENSITIVE_HEADER_NAMES.has(k.toLowerCase()))
+                        continue;
+                    headers[k] = v;
+                }
+            }
+            if (overrides?.setQuery) {
+                const u = new URL(url);
+                for (const [k, v] of Object.entries(overrides.setQuery)) {
+                    u.searchParams.set(k, String(v));
+                }
+                url = u.toString();
+            }
+            const response = await requestContext.fetch(url, {
+                method,
+                headers,
+                data: body,
+            });
+            const respBody = await response.body();
+            const bodySize = respBody.length;
+            const contentType = response.headers()['content-type'] ?? response.headers()['Content-Type'];
+            const bodyText = bodySize <= RESPONSE_BODY_MAX_STORE_BYTES && isTextOrJsonContentType(contentType)
+                ? respBody.toString('utf8')
+                : respBody.toString('utf8').slice(0, 2048) + (bodySize > 2048 ? '...[truncated]' : '');
+            return {
+                status: response.status(),
+                contentType,
+                body: bodyText,
+                bodySize,
+            };
+        },
+        clear() {
+            buffer.length = 0;
+            mapById.clear();
+            totalBytesEstimate = 0;
+        },
+        exportEntry(requestId) {
+            const entry = mapById.get(requestId);
+            if (!entry)
+                return null;
+            return {
+                id: entry.id,
+                ts: entry.ts,
+                method: entry.method,
+                url: entry.url,
+                resourceType: entry.resourceType,
+                requestHeaders: entry.requestHeaders,
+                requestHeadersFull: entry.requestHeadersFull,
+                postData: entry.postData,
+                status: entry.status,
+                responseHeaders: entry.responseHeaders,
+                contentType: entry.contentType,
+                responseBodyText: entry.responseBodyText,
+                responseBodyBase64: entry.responseBodyBase64,
+            };
+        },
+        importEntry(entry) {
+            // Skip if entry already exists
+            if (mapById.has(entry.id))
+                return;
+            const internal = {
+                id: entry.id,
+                ts: entry.ts,
+                method: entry.method,
+                url: entry.url,
+                resourceType: entry.resourceType,
+                requestHeaders: entry.requestHeaders,
+                requestHeadersFull: entry.requestHeadersFull,
+                postData: entry.postData,
+                status: entry.status,
+                responseHeaders: entry.responseHeaders,
+                contentType: entry.contentType,
+                responseBodyText: entry.responseBodyText,
+                responseBodyBase64: entry.responseBodyBase64,
+                bytesEstimate: 0,
+            };
+            // Calculate bytes estimate
+            internal.bytesEstimate =
+                entry.url.length +
+                    JSON.stringify(entry.requestHeaders).length +
+                    (entry.postData?.length ?? 0) +
+                    (entry.responseBodyText ? Buffer.byteLength(entry.responseBodyText, 'utf8') : 0) +
+                    (entry.responseBodyBase64 ? Math.ceil((entry.responseBodyBase64.length * 3) / 4) : 0) +
+                    200;
+            mapById.set(entry.id, internal);
+            buffer.push(internal);
+            totalBytesEstimate += internal.bytesEstimate;
+            dropOldest();
+        },
+    };
+    return api;
+}

package/dist/packUtils.d.ts

@@ -0,0 +1,36 @@
+import type { TaskPackManifest, InputSchema, CollectibleDefinition } from './types.js';
+import type { DslStep } from './dsl/types.js';
+/**
+ * Sanitize a pack ID to be safe for use as a directory name
+ */
+export declare function sanitizePackId(packId: string): string;
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export declare function ensureDir(dirPath: string): void;
+/**
+ * Atomic write: write to temp file then rename
+ */
+export declare function atomicWrite(filePath: string, content: string): void;
+/**
+ * Validate that a path is within an allowed directory
+ */
+export declare function validatePathInAllowedDir(path: string, allowedDir: string): void;
+/**
+ * Read JSON file safely
+ */
+export declare function readJsonFile<T>(filePath: string): T;
+/**
+ * Write taskpack.json
+ */
+export declare function writeTaskPackManifest(packDir: string, manifest: TaskPackManifest): void;
+/**
+ * Write flow.json
+ * @param skipValidation If true, skip validation (useful for empty flows during pack creation)
+ */
+export declare function writeFlowJson(packDir: string, flowData: {
+    inputs?: InputSchema;
+    collectibles?: CollectibleDefinition[];
+    flow: DslStep[];
+}, skipValidation?: boolean): void;
+//# sourceMappingURL=packUtils.d.ts.map

package/dist/packUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packUtils.d.ts","sourceRoot":"","sources":["../src/packUtils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAgBnE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAO/E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAUnD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CAIN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IACR,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACvC,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB,EACD,cAAc,UAAQ,GACrB,IAAI,CAoBN"}

package/dist/packUtils.js

@@ -0,0 +1,97 @@
+/**
+ * Pack utilities for task pack file operations
+ */
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
+import { resolve, join } from 'path';
+import { validateJsonTaskPack } from './jsonPackValidator.js';
+/**
+ * Sanitize a pack ID to be safe for use as a directory name
+ */
+export function sanitizePackId(packId) {
+    // Replace dots with dashes (some MCP clients reject dots), then other invalid chars with underscores
+    return packId.replace(/\./g, '-').replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export function ensureDir(dirPath) {
+    mkdirSync(dirPath, { recursive: true });
+}
+/**
+ * Atomic write: write to temp file then rename
+ */
+export function atomicWrite(filePath, content) {
+    const tempPath = `${filePath}.tmp`;
+    try {
+        writeFileSync(tempPath, content, 'utf-8');
+        renameSync(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            if (existsSync(tempPath)) {
+                renameSync(tempPath, filePath);
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * Validate that a path is within an allowed directory
+ */
+export function validatePathInAllowedDir(path, allowedDir) {
+    const resolvedPath = resolve(path);
+    const resolvedAllowed = resolve(allowedDir);
+    if (!resolvedPath.startsWith(resolvedAllowed + '/') && resolvedPath !== resolvedAllowed) {
+        throw new Error(`Path ${resolvedPath} is outside allowed directory ${resolvedAllowed}`);
+    }
+}
+/**
+ * Read JSON file safely
+ */
+export function readJsonFile(filePath) {
+    if (!existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Write taskpack.json
+ */
+export function writeTaskPackManifest(packDir, manifest) {
+    const manifestPath = join(packDir, 'taskpack.json');
+    const content = JSON.stringify(manifest, null, 2) + '\n';
+    atomicWrite(manifestPath, content);
+}
+/**
+ * Write flow.json
+ * @param skipValidation If true, skip validation (useful for empty flows during pack creation)
+ */
+export function writeFlowJson(packDir, flowData, skipValidation = false) {
+    // Validate before writing (unless skipping for empty flows)
+    if (!skipValidation) {
+        const taskPack = {
+            metadata: {
+                id: 'temp',
+                name: 'temp',
+                version: '0.0.0',
+            },
+            inputs: flowData.inputs || {},
+            collectibles: flowData.collectibles || [],
+            flow: flowData.flow,
+        };
+        validateJsonTaskPack(taskPack);
+    }
+    const flowPath = join(packDir, 'flow.json');
+    const content = JSON.stringify(flowData, null, 2) + '\n';
+    atomicWrite(flowPath, content);
+}

package/dist/packVersioning.d.ts

@@ -0,0 +1,25 @@
+import type { FlowVersion } from './types.js';
+/**
+ * Save a version snapshot of the current flow.json and taskpack.json.
+ */
+export declare function saveVersion(packDir: string, opts: {
+    label?: string;
+    source: FlowVersion['source'];
+    conversationId?: string;
+}): FlowVersion;
+/**
+ * List all saved versions for a pack. Returns [] if no versions exist.
+ */
+export declare function listVersions(packDir: string): FlowVersion[];
+/**
+ * Read the versioned files without restoring them.
+ */
+export declare function getVersionFiles(packDir: string, versionNumber: number): {
+    flow: unknown;
+    taskpack: unknown;
+};
+/**
+ * Restore a previous version. Auto-saves the current state first.
+ */
+export declare function restoreVersion(packDir: string, versionNumber: number): void;
+//# sourceMappingURL=packVersioning.d.ts.map

package/dist/packVersioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packVersioning.d.ts","sourceRoot":"","sources":["../src/packVersioning.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,YAAY,CAAC;AAgCjF;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,WAAW,CAgDb;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAG3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CActC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,IAAI,CAgCN"}

package/dist/packVersioning.js

@@ -0,0 +1,137 @@
+/**
+ * Pack versioning: save, list, and restore snapshots of flow.json + taskpack.json
+ */
+import { join } from 'path';
+import { existsSync, copyFileSync, unlinkSync } from 'fs';
+import { ensureDir, readJsonFile, atomicWrite } from './packUtils.js';
+const VERSIONS_DIR = '.versions';
+const MANIFEST_FILE = 'manifest.json';
+const DEFAULT_MAX_VERSIONS = 50;
+function versionsDir(packDir) {
+    return join(packDir, VERSIONS_DIR);
+}
+function manifestPath(packDir) {
+    return join(versionsDir(packDir), MANIFEST_FILE);
+}
+function readManifest(packDir) {
+    const mPath = manifestPath(packDir);
+    if (!existsSync(mPath)) {
+        return { versions: [], maxVersions: DEFAULT_MAX_VERSIONS };
+    }
+    return readJsonFile(mPath);
+}
+function writeManifest(packDir, manifest) {
+    ensureDir(versionsDir(packDir));
+    atomicWrite(manifestPath(packDir), JSON.stringify(manifest, null, 2) + '\n');
+}
+function nextVersionNumber(manifest) {
+    if (manifest.versions.length === 0)
+        return 1;
+    return Math.max(...manifest.versions.map((v) => v.number)) + 1;
+}
+/**
+ * Save a version snapshot of the current flow.json and taskpack.json.
+ */
+export function saveVersion(packDir, opts) {
+    const flowPath = join(packDir, 'flow.json');
+    const taskpackPath = join(packDir, 'taskpack.json');
+    if (!existsSync(flowPath)) {
+        throw new Error(`flow.json not found in ${packDir}`);
+    }
+    if (!existsSync(taskpackPath)) {
+        throw new Error(`taskpack.json not found in ${packDir}`);
+    }
+    const manifest = readManifest(packDir);
+    const num = nextVersionNumber(manifest);
+    const vDir = versionsDir(packDir);
+    ensureDir(vDir);
+    // Read metadata.version from taskpack.json
+    const taskpackData = readJsonFile(taskpackPath);
+    const metadataVersion = taskpackData.version || '0.0.0';
+    // Copy current files to versioned copies
+    copyFileSync(flowPath, join(vDir, `${num}.flow.json`));
+    copyFileSync(taskpackPath, join(vDir, `${num}.taskpack.json`));
+    const version = {
+        number: num,
+        version: metadataVersion,
+        timestamp: new Date().toISOString(),
+        label: opts.label,
+        source: opts.source,
+        conversationId: opts.conversationId,
+    };
+    manifest.versions.push(version);
+    // Prune oldest versions if exceeding maxVersions
+    const max = manifest.maxVersions || DEFAULT_MAX_VERSIONS;
+    while (manifest.versions.length > max) {
+        const oldest = manifest.versions.shift();
+        // Remove old versioned files
+        const oldFlow = join(vDir, `${oldest.number}.flow.json`);
+        const oldTaskpack = join(vDir, `${oldest.number}.taskpack.json`);
+        try {
+            if (existsSync(oldFlow))
+                unlinkSync(oldFlow);
+        }
+        catch { /* ignore */ }
+        try {
+            if (existsSync(oldTaskpack))
+                unlinkSync(oldTaskpack);
+        }
+        catch { /* ignore */ }
+    }
+    writeManifest(packDir, manifest);
+    return version;
+}
+/**
+ * List all saved versions for a pack. Returns [] if no versions exist.
+ */
+export function listVersions(packDir) {
+    const manifest = readManifest(packDir);
+    return manifest.versions;
+}
+/**
+ * Read the versioned files without restoring them.
+ */
+export function getVersionFiles(packDir, versionNumber) {
+    const vDir = versionsDir(packDir);
+    const flowPath = join(vDir, `${versionNumber}.flow.json`);
+    const taskpackPath = join(vDir, `${versionNumber}.taskpack.json`);
+    if (!existsSync(flowPath)) {
+        throw new Error(`Version ${versionNumber} not found`);
+    }
+    const flow = readJsonFile(flowPath);
+    // taskpack.json may not exist in very old versions — handle gracefully
+    const taskpack = existsSync(taskpackPath) ? readJsonFile(taskpackPath) : null;
+    return { flow, taskpack };
+}
+/**
+ * Restore a previous version. Auto-saves the current state first.
+ */
+export function restoreVersion(packDir, versionNumber) {
+    // Verify the version exists before auto-saving
+    const manifest = readManifest(packDir);
+    const target = manifest.versions.find((v) => v.number === versionNumber);
+    if (!target) {
+        throw new Error(`Version ${versionNumber} not found`);
+    }
+    const vDir = versionsDir(packDir);
+    const versionedFlowPath = join(vDir, `${versionNumber}.flow.json`);
+    if (!existsSync(versionedFlowPath)) {
+        throw new Error(`Version ${versionNumber} files not found on disk`);
+    }
+    // Auto-save current state before restoring
+    const flowPath = join(packDir, 'flow.json');
+    if (existsSync(flowPath)) {
+        saveVersion(packDir, {
+            label: `Auto-saved before restoring version ${versionNumber}`,
+            source: 'dashboard',
+        });
+    }
+    // Restore flow.json
+    copyFileSync(versionedFlowPath, flowPath);
+    // Restore taskpack.json if the versioned copy exists
+    const versionedTaskpackPath = join(vDir, `${versionNumber}.taskpack.json`);
+    if (existsSync(versionedTaskpackPath)) {
+        const taskpackPath = join(packDir, 'taskpack.json');
+        copyFileSync(versionedTaskpackPath, taskpackPath);
+    }
+}