@zalosai/zalos-cli 0.2.15 → 0.2.16

package/PUBLISHING.md

@@ -61,6 +61,9 @@ Do not publish with uncommitted package changes or reuse an existing version.
 
 Version 0.2.15 bundles the `zl-ops` production-operations skill and adds offline `zl skills`
 commands to list, read, and install it into Codex or Claude skill roots.
+Version 0.2.16 adds `zl execution replay export`, which materializes a SHA-256-verified local
+bundle of immutable execution inputs and outputs through the authenticated product API. Deploy
+the replay-bundle route before publishing this version.
 Version 0.2.14 moves publishing to npm Trusted Publishing through the
 `publish-zalos-cli.yml` GitHub Actions workflow, so releases no longer rely on a stored npm token.
 Version 0.2.13 adds revision-safe Markdown import and export for team Pages. It converts common

package/README.md

@@ -46,6 +46,12 @@ zl --environment eu-prod auth login
 ```
 
 `auth login` opens the existing browser sign-in and stores the scoped human session.
+If the browser cannot reach the CLI's local listener, choose **Use a code** in the
+browser and enter the code printed by the CLI, then confirm the team. For a CLI
+running on another machine or in a container, run `zl --environment <name> auth login --device`.
+Open the verification page printed by the CLI on a browser machine, enter its six-digit code,
+and confirm the team. The CLI waits up to five minutes and receives the token
+encrypted to the CLI session key.
 It never changes access-group membership. Database access remains an optional,
 separately distributed developer capability:
 
@@ -76,6 +82,25 @@ When AWS access expires, rerun `zalos-db login --environment <name>`; this does
 your Mesh token. Database reader groups are `zalos-db-staging-readers`,
 `zalos-db-us-prod-readers`, and `zalos-db-eu-prod-readers`.
 
+## Data Tables
+
+Define columns, types, write owners, and an optional text business key in a local
+JSON schema. Initial rows may be a JSON array or `.jsonl` file.
+
+```bash
+zl data-table validate --schema /tmp/table.json --rows /tmp/rows.jsonl
+zl --environment staging data-table create --schema /tmp/table.json --rows /tmp/rows.jsonl
+# Review the preview, then run its applyCommand unchanged.
+zl --environment staging data-table list
+zl --environment staging data-table view <table-id>
+zl --environment staging data-table grant-writer <table-id> <workflow-id> --apply
+zl --environment staging data-table revoke-writer <table-id> <workflow-id> --apply
+```
+
+Creation requires team owner access. The preview provides a stable operation key,
+checksum, and destination origin for apply. Import accepts at most 1,000 rows and
+a 1 MB request. Workflow writer grants are separate and preview by default.
+
 ## Product operations
 
 ```bash
@@ -89,6 +114,7 @@ zl execution list --limit 1
 zl execution view <id>
 zl execution summary <id>
 zl execution artifact download <artifact-id> --output /tmp/artifact
+zl execution replay export <execution-id> --output .zalosai/replays/<execution-id>
 zl page list --fields id,title,updatedAt
 zl page export <page-id> --output /tmp/month-end-close.md
 zl page create --input /tmp/month-end-close.md --apply
@@ -141,6 +167,11 @@ Downloads request a short-lived URL through the authenticated API and write to a
 file; they do not require direct S3 access. File moves remain scoped to the selected team profile.
 Execution artifact downloads use the same private-file and no-overwrite guarantees. Select the
 artifact's team before downloading; the immutable artifact API enforces that team boundary.
+`execution replay export` packages the selected team's ready immutable input and output artifacts
+with their recorded SHA-256 hashes. It verifies every downloaded byte, writes a new private local
+directory, and never prints signed URLs. Run the bundle locally with
+`uv run zalosai run --replay-bundle <directory>` from Agent Studio; this does not use database,
+SSM, or direct S3 credentials.
 `page export` writes a Markdown process document with a non-rendered revision marker. Edit the
 Markdown, then use `page update --apply`; it refuses an update when the Page changed after export.
 `page create` and `page update` both preview by default and preserve common Tiptap process-document

package/dist/commands/auth.js

@@ -1,7 +1,7 @@
 import { client } from '../client.js';
 import { clearProfile, readProfile, writeProfile } from '../credentials.js';
 import { currentEnvironment } from '../environments.js';
-import { createBrowserProofServer, fetchCliBrowserAuthorizationConfig, generateSession, openBrowser, pollForToken, } from '../utils/cli-auth.js';
+import { createBrowserProofServer, fetchCliBrowserAuthorizationConfig, generateSession, generateManualCode, generateDeviceCode, openBrowser, pollForToken, registerDeviceSession, } from '../utils/cli-auth.js';
 import { AuthError, handleError } from '../utils/errors.js';
 import { printJson } from '../utils/output.js';
 import { dataRow } from '../utils/product-api.js';
@@ -18,6 +18,21 @@ export async function requestBrowserAuthorization(options) {
             throw new AuthError(`Invalid API token scopes: ${invalidScopes.join(', ')}`);
     }
     const session = await generateSession();
+    if (options.device) {
+        if (!authConfig.capabilities.includes('device-authorization-v1'))
+            throw new AuthError('Selected environment does not support device authorization');
+        const deviceCode = generateDeviceCode();
+        await registerDeviceSession(environment.apiUrl, {
+            sessionId: session.sessionId,
+            publicKey: session.publicKey,
+            tokenName: options.tokenName,
+            environment: environment.name,
+            codeHash: deviceCode.hash,
+        });
+        process.stderr.write(`Open ${authConfig.uiOrigin}/cli-auth?device=1 in a browser and enter this code: ${deviceCode.code}\nWaiting for browser authorization...\n`);
+        return pollForToken(environment.apiUrl, session.sessionId, session.privateKey, 600000, 2000, 300000);
+    }
+    const manual = generateManualCode();
     const proofServer = await createBrowserProofServer(session.sessionId, authConfig.uiOrigin);
     const query = new URLSearchParams({
         session_id: session.sessionId,
@@ -26,6 +41,7 @@ export async function requestBrowserAuthorization(options) {
         environment: environment.name,
         proof_hash: proofServer.browserProofHash,
         callback_port: String(proofServer.callbackPort),
+        manual_code_hash: manual.hash,
     });
     if (options.scopes) {
         query.set('provision', 'api-token');
@@ -36,7 +52,7 @@ export async function requestBrowserAuthorization(options) {
     const url = `${environment.apiUrl}/api/auth/cli-login?${query}`;
     try {
         openBrowser(url);
-        process.stderr.write(`Open this URL to authorize: ${url}\nWaiting for browser authorization...\n`);
+        process.stderr.write(`Open this URL to authorize: ${url}\nIf the browser cannot reach this CLI, choose Use a code and enter: ${manual.code}\nWaiting for browser authorization...\n`);
         return await pollForToken(environment.apiUrl, session.sessionId, session.privateKey, 300000);
     }
     finally {
@@ -46,9 +62,9 @@ export async function requestBrowserAuthorization(options) {
 export async function whoamiAction() {
     printJson(await client.get('/user/profile'));
 }
-export async function loginAction(profileName = process.env.ZL_PROFILE ?? 'default') {
+export async function loginAction(profileName = process.env.ZL_PROFILE ?? 'default', device = false) {
     const environment = currentEnvironment();
-    const result = await requestBrowserAuthorization({ tokenName: 'zl-cli' });
+    const result = await requestBrowserAuthorization({ tokenName: 'zl-cli', device });
     if (result.environment !== environment.name)
         throw new AuthError('Login environment mismatch');
     writeProfile(profileName, {
@@ -144,9 +160,10 @@ export function registerAuthCommand(program) {
     auth
         .command('login')
         .description('Sign in through the browser for seven days')
-        .action(async () => {
+        .option('--device', 'Use a code in a browser on another machine')
+        .action(async (options) => {
         try {
-            await loginAction();
+            await loginAction(undefined, options.device === true);
             printJson({
                 message: 'Logged in',
                 profile: process.env.ZL_PROFILE ?? 'default',

package/dist/commands/custom-page.js

@@ -0,0 +1,215 @@
+import { readFile, writeFile, copyFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { client } from '../client.js';
+import { readProfile } from '../credentials.js';
+import { currentEnvironment } from '../environments.js';
+import { ValidationError } from '../utils/errors.js';
+import { action, dataRow, dataRows, resourceId } from '../utils/product-api.js';
+import { printJson } from '../utils/output.js';
+function revision(value) {
+    const parsed = Number(value);
+    if (!value || !Number.isSafeInteger(parsed) || parsed < 1)
+        throw new ValidationError('revision', 'A positive --revision is required');
+    return parsed;
+}
+async function htmlFile(path) {
+    let html;
+    try {
+        html = await readFile(path, 'utf8');
+    }
+    catch {
+        throw new ValidationError('html', `Unable to read HTML file: ${path}`);
+    }
+    if (Buffer.byteLength(html, 'utf8') > 1_000_000)
+        throw new ValidationError('html', 'HTML exceeds 1,000,000 UTF-8 bytes');
+    return html;
+}
+function visibility(value) {
+    if (value !== 'off' && value !== 'internal' && value !== 'everyone')
+        throw new ValidationError('visibility', 'Use off, internal, or everyone');
+    return value;
+}
+export async function listCustomPagesAction(options) {
+    printJson(dataRows(await client.get('/custom-pages', { manage: String(options.manage ?? false) })));
+}
+export async function getCustomPageAction(id) {
+    printJson(dataRow(await client.get(`/custom-pages/${resourceId(id)}`, { manage: 'true' })));
+}
+export async function exportCustomPageAction(id, options) {
+    const page = dataRow(await client.get(`/custom-pages/${resourceId(id)}`, { manage: 'true' }));
+    if (typeof page.html !== 'string' || typeof page.revision !== 'number')
+        throw new ValidationError('page', 'Invalid page response');
+    await writeFile(`${options.output}.html`, page.html, { flag: 'wx', mode: 0o600 });
+    const { html: _html, ...metadata } = page;
+    await writeFile(`${options.output}.json`, JSON.stringify(metadata, null, 2) + '\n', {
+        flag: 'wx',
+        mode: 0o600,
+    });
+    printJson({
+        html: `${options.output}.html`,
+        metadata: `${options.output}.json`,
+        id: page.id,
+        revision: page.revision,
+    });
+}
+export async function createCustomPageAction(options) {
+    const payload = {
+        name: options.name.trim(),
+        html: await htmlFile(options.html),
+        visibility: visibility(options.visibility ?? 'off'),
+    };
+    if (!payload.name || payload.name.length > 80)
+        throw new ValidationError('name', 'Name must be 1–80 characters');
+    if (!options.apply || options.dryRun) {
+        printJson({
+            dryRun: true,
+            method: 'POST',
+            path: '/custom-pages',
+            name: payload.name,
+            htmlBytes: Buffer.byteLength(payload.html),
+            visibility: payload.visibility,
+        });
+        return;
+    }
+    printJson(dataRow(await client.post('/custom-pages', payload)));
+}
+export async function updateCustomPageAction(id, options) {
+    const pageId = resourceId(id);
+    const expectedRevision = revision(options.revision);
+    const payload = { expectedRevision };
+    if (options.html !== undefined)
+        payload.html = await htmlFile(options.html);
+    if (options.name !== undefined) {
+        const name = options.name.trim();
+        if (!name || name.length > 80)
+            throw new ValidationError('name', 'Name must be 1–80 characters');
+        payload.name = name;
+    }
+    if (options.visibility !== undefined)
+        payload.visibility = visibility(options.visibility);
+    if (Object.keys(payload).length === 1)
+        throw new ValidationError('update', 'Provide --html, --name, or --visibility');
+    if (!options.apply || options.dryRun) {
+        printJson({
+            dryRun: true,
+            method: 'PATCH',
+            path: `/custom-pages/${pageId}`,
+            ...payload,
+            html: payload.html === undefined
+                ? undefined
+                : `<${Buffer.byteLength(payload.html)} bytes>`,
+        });
+        return;
+    }
+    printJson(dataRow(await client.patch(`/custom-pages/${pageId}`, payload)));
+}
+export async function deleteCustomPageAction(id, options) {
+    const pageId = resourceId(id), expectedRevision = revision(options.revision);
+    if (!options.apply) {
+        printJson({
+            dryRun: true,
+            method: 'DELETE',
+            path: `/custom-pages/${pageId}`,
+            expectedRevision,
+        });
+        return;
+    }
+    await client.delete(`/custom-pages/${pageId}?expectedRevision=${expectedRevision}`);
+    printJson({ deleted: pageId });
+}
+export function previewCustomPageAction(id) {
+    const profile = readProfile(process.env.ZL_PROFILE ?? 'default');
+    const teamId = profile?.team?.publicId;
+    if (!teamId)
+        throw new ValidationError('team', 'Select a team with `zl team switch` before previewing');
+    printJson({
+        url: `${currentEnvironment(profile.environment).apiUrl}/t/${encodeURIComponent(teamId)}/custom-pages/${resourceId(id)}`,
+    });
+}
+const kit = new URL('../../skills/custom-page-authoring/assets/', import.meta.url);
+export async function starterCustomPageAction(options) {
+    const example = options.example ?? 'starter';
+    if (!['starter', 'dashboard', 'report', 'table'].includes(example))
+        throw new ValidationError('example', 'Use starter, dashboard, report, or table');
+    await copyFile(fileURLToPath(new URL(`${example}.html`, kit)), options.output, constants.COPYFILE_EXCL);
+    printJson({ output: options.output, example });
+}
+export async function validateCustomPageAction(options) {
+    const html = await htmlFile(options.html);
+    const problems = [];
+    if (/<(?:script|link|img|iframe|source|form)\b[^>]*(?:src|href|action)\s*=\s*["']?(?:https?:)?\/\//i.test(html) ||
+        /(?:@import|url\()\s*(?:url\()?\s*["']?(?:https?:)?\/\//i.test(html))
+        problems.push('External assets are unsupported');
+    if (!/<h1\b/i.test(html))
+        problems.push('Add an h1 heading');
+    if (/<img\b(?![^>]*\balt\s*=)[^>]*>/i.test(html))
+        problems.push('Images need alt text');
+    for (const match of html.matchAll(/<input\b[^>]*>/gi)) {
+        const tag = match[0];
+        if (/\btype\s*=\s*["']?(?:hidden|file)\b/i.test(tag) ||
+            /\bclass\s*=\s*["'][^"']*\bhidden\b/i.test(tag))
+            continue;
+        if (!/\b(?:aria-label|aria-labelledby|id)\s*=/i.test(tag)) {
+            problems.push('Inputs need a label or accessible name');
+            break;
+        }
+    }
+    if (/\bmesh\.runWorkflow\s*\(/.test(html))
+        problems.push('mesh.runWorkflow is no longer supported; use mesh.navigate instead');
+    printJson({
+        valid: problems.length === 0,
+        problems,
+        htmlBytes: Buffer.byteLength(html),
+        staticAnalysisOnly: true,
+    });
+    if (problems.length)
+        throw new ValidationError('html', problems.join('; '));
+}
+export function registerCustomPageCommand(program) {
+    const page = program.command('custom-page').description('Manage team-scoped HTML Custom Pages');
+    page
+        .command('list')
+        .option('--manage', 'Include disabled pages (owner only)')
+        .action(async (options) => action(() => listCustomPagesAction(options)));
+    page
+        .command('get <id>')
+        .action(async (id) => action(() => getCustomPageAction(id)));
+    page
+        .command('export <id>')
+        .requiredOption('--output <base>', 'Output basename')
+        .action(async (id, options) => action(() => exportCustomPageAction(id, options)));
+    page
+        .command('create')
+        .requiredOption('--html <file>', 'HTML file')
+        .requiredOption('--name <name>', 'Page name')
+        .option('--visibility <level>', 'off, internal, everyone', 'off')
+        .option('--apply')
+        .option('--dry-run')
+        .action(async (options) => action(() => createCustomPageAction(options)));
+    page
+        .command('update <id>')
+        .requiredOption('--revision <n>', 'Expected revision')
+        .option('--html <file>')
+        .option('--name <name>')
+        .option('--visibility <level>')
+        .option('--apply')
+        .option('--dry-run')
+        .action(async (id, options) => action(() => updateCustomPageAction(id, options)));
+    page
+        .command('delete <id>')
+        .requiredOption('--revision <n>', 'Expected revision')
+        .option('--apply')
+        .action(async (id, options) => action(() => deleteCustomPageAction(id, options)));
+    page.command('preview <id>').action((id) => previewCustomPageAction(id));
+    page
+        .command('starter')
+        .requiredOption('--output <file>')
+        .option('--example <name>')
+        .action(async (options) => action(() => starterCustomPageAction(options)));
+    page
+        .command('validate')
+        .requiredOption('--html <file>')
+        .action(async (options) => action(() => validateCustomPageAction(options)));
+}
+//# sourceMappingURL=custom-page.js.map

package/dist/commands/data-table.js

@@ -0,0 +1,146 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { client } from '../client.js';
+import { readTableProvisionInput, MAX_PROVISION_BYTES } from '../data-table-input.js';
+import { currentEnvironment, ENVIRONMENTS } from '../environments.js';
+import { ValidationError } from '../utils/errors.js';
+import { dataRow, dataRows, fields, printPage, resourceId, action, } from '../utils/product-api.js';
+import { filterSingle, printJson } from '../utils/output.js';
+function quote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function responseData(value) {
+    return dataRow(value);
+}
+export async function validateTableAction(options) {
+    const input = await readTableProvisionInput(options.schema, options.rows);
+    printJson({
+        valid: true,
+        columns: input.definition.columns.length,
+        rows: input.rows.length,
+        remoteAuthorization: 'not checked',
+    });
+}
+export async function createTableAction(options) {
+    const input = await readTableProvisionInput(options.schema, options.rows);
+    if (!options.apply || options.dryRun) {
+        const preview = responseData(await client.post('/data-tables/provision/preview', { input }, { detailedAuthErrors: true }));
+        if (typeof preview.checksum !== 'string' ||
+            !/^[0-9a-f]{64}$/.test(preview.checksum) ||
+            typeof preview.teamId !== 'string')
+            throw new ValidationError('preview', 'Invalid server preview');
+        const environment = currentEnvironment();
+        const operationKey = randomUUID();
+        const command = [
+            'zl',
+            '--environment',
+            environment.name,
+            ...(environment.apiUrl !== ENVIRONMENTS[environment.name]
+                ? ['--api-url', quote(environment.apiUrl)]
+                : []),
+            ...(process.env.ZL_PROFILE ? ['--profile', quote(process.env.ZL_PROFILE)] : []),
+            'data-table',
+            'create',
+            '--schema',
+            quote(resolve(options.schema)),
+            ...(options.rows ? ['--rows', quote(resolve(options.rows))] : []),
+            '--operation-key',
+            quote(operationKey),
+            '--expected-checksum',
+            quote(preview.checksum),
+            '--expected-origin',
+            quote(environment.apiUrl),
+            '--apply',
+        ].join(' ');
+        printJson({
+            dryRun: true,
+            environment: environment.name,
+            teamId: preview.teamId,
+            label: input.definition.label,
+            columnCount: preview.columnCount,
+            rowCount: preview.rowCount,
+            checksum: preview.checksum,
+            origin: environment.apiUrl,
+            operationKey,
+            applyCommand: command,
+        });
+        return;
+    }
+    if (!options.operationKey || !options.expectedChecksum || !options.expectedOrigin)
+        throw new ValidationError('apply', 'Apply requires --operation-key, --expected-checksum and --expected-origin from the preview');
+    if (options.expectedOrigin !== currentEnvironment().apiUrl)
+        throw new ValidationError('expectedOrigin', 'Destination changed since preview');
+    if (!/^[A-Za-z0-9._:-]{8,200}$/.test(options.operationKey))
+        throw new ValidationError('operationKey', 'Expected 8 to 200 safe characters');
+    if (!/^[0-9a-f]{64}$/.test(options.expectedChecksum))
+        throw new ValidationError('expectedChecksum', 'Expected a SHA-256 checksum');
+    const body = {
+        input,
+        operationKey: options.operationKey,
+        expectedChecksum: options.expectedChecksum,
+    };
+    if (Buffer.byteLength(JSON.stringify(body)) > MAX_PROVISION_BYTES)
+        throw new ValidationError('input', 'Provision request exceeds 1,000,000 bytes');
+    printJson(responseData(await client.post('/data-tables/provision', body, { detailedAuthErrors: true })));
+}
+export async function listTablesAction(options) {
+    printPage(dataRows(await client.get('/data-tables')), options);
+}
+export async function viewTableAction(id, options) {
+    printJson(filterSingle(dataRow(await client.get(`/data-tables/${resourceId(id)}`)), options.fields));
+}
+export async function writerAction(tableId, workflowId, grant, options) {
+    const path = `/data-tables/${resourceId(tableId)}/writers${grant ? '' : `/${resourceId(workflowId)}`}`;
+    const method = grant ? 'POST' : 'DELETE';
+    if (!options.apply || options.dryRun) {
+        printJson({
+            dryRun: true,
+            method,
+            path,
+            ...(grant ? { workflowId: resourceId(workflowId) } : {}),
+        });
+        return;
+    }
+    if (grant)
+        await client.post(path, { workflowId: resourceId(workflowId) }, { detailedAuthErrors: true });
+    else
+        await client.delete(path);
+    printJson({ tableId, workflowId, granted: grant });
+}
+export function registerDataTableCommand(program) {
+    const cmd = program.command('data-table').description('Validate and provision Data Tables');
+    cmd
+        .command('validate')
+        .requiredOption('--schema <file>', 'Explicit table definition JSON')
+        .option('--rows <file>', 'Optional initial rows as JSON array or JSONL')
+        .action(async (options) => action(() => validateTableAction(options)));
+    cmd
+        .command('create')
+        .requiredOption('--schema <file>', 'Explicit table definition JSON')
+        .option('--rows <file>', 'Optional initial rows as JSON array or JSONL, maximum 1,000 rows and 1 MB request')
+        .option('--dry-run', 'Validate remotely and preview without writing (default)')
+        .option('--apply', 'Create the table and optional rows')
+        .option('--operation-key <key>', 'Stable retry key from the preview')
+        .option('--expected-checksum <sha256>', 'Destination-bound checksum from the preview')
+        .option('--expected-origin <url>', 'Exact API origin from the preview')
+        .action(async (options) => action(() => createTableAction(options)));
+    cmd
+        .command('list')
+        .option('--limit <n>', 'Maximum results', '100')
+        .option('--offset <n>', 'Result offset', '0')
+        .action(async (options) => action(() => listTablesAction({ ...options, ...fields(program) })));
+    cmd
+        .command('view <id>')
+        .action(async (id) => action(() => viewTableAction(id, fields(program))));
+    cmd
+        .command('grant-writer <table-id> <workflow-id>')
+        .option('--apply', 'Grant writer permission')
+        .option('--dry-run', 'Preview grant (default)')
+        .action(async (tableId, workflowId, options) => action(() => writerAction(tableId, workflowId, true, options)));
+    cmd
+        .command('revoke-writer <table-id> <workflow-id>')
+        .option('--apply', 'Revoke writer permission')
+        .option('--dry-run', 'Preview revocation (default)')
+        .action(async (tableId, workflowId, options) => action(() => writerAction(tableId, workflowId, false, options)));
+}
+//# sourceMappingURL=data-table.js.map

package/dist/commands/execution.js

@@ -1,10 +1,84 @@
 import { client } from '../client.js';
-import { writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { currentEnvironment } from '../environments.js';
 import { downloadToNewFile } from '../utils/download-file.js';
 import { ApiError, ValidationError } from '../utils/errors.js';
 import { filterFields, filterSingle, printJson } from '../utils/output.js';
 import { action, dataRow, fields, integer, isRow, resourceId, } from '../utils/product-api.js';
+function isReplayBundleArtifact(value) {
+    if (!isRow(value))
+        return false;
+    return (typeof value.artifactId === 'string' &&
+        typeof value.name === 'string' &&
+        typeof value.sha256 === 'string' &&
+        /^sha256:[a-f0-9]{64}$/.test(value.sha256) &&
+        typeof value.size === 'number' &&
+        Number.isSafeInteger(value.size) &&
+        value.size >= 0 &&
+        typeof value.mimeType === 'string');
+}
+function isReplayBundleInput(value) {
+    return (isReplayBundleArtifact(value) &&
+        isRow(value) &&
+        typeof value.fieldName === 'string' &&
+        value.fieldName.length > 0);
+}
+function replayBundlePlan(value) {
+    const plan = dataRow(value);
+    if (plan.schemaVersion !== 1 ||
+        typeof plan.executionId !== 'string' ||
+        !plan.executionId ||
+        typeof plan.agentRef !== 'string' ||
+        !isRow(plan.parameters) ||
+        !Object.values(plan.parameters).every((parameter) => typeof parameter === 'string') ||
+        !Array.isArray(plan.inputs) ||
+        !plan.inputs.every(isReplayBundleInput) ||
+        !Array.isArray(plan.outputs) ||
+        !plan.outputs.every(isReplayBundleArtifact))
+        throw new ApiError(502, 'Invalid execution replay bundle response');
+    return {
+        schemaVersion: 1,
+        executionId: plan.executionId,
+        agentRef: plan.agentRef,
+        parameters: Object.fromEntries(Object.entries(plan.parameters).map(([name, parameter]) => [name, String(parameter)])),
+        inputs: plan.inputs,
+        outputs: plan.outputs,
+    };
+}
+function replayBundleFileName(name, index) {
+    const safeName = name
+        // oxlint-disable-next-line no-control-regex -- artifact names cannot carry terminal controls
+        .replace(/[\\/\u0000-\u001f\u007f]/g, '_')
+        .replace(/^\.+$/, '')
+        .trim();
+    if (!safeName)
+        throw new ValidationError('artifact.name', 'Invalid replay bundle artifact name');
+    return `${String(index + 1).padStart(3, '0')}-${safeName}`;
+}
+async function sha256File(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return `sha256:${hash.digest('hex')}`;
+}
+async function downloadReplayBundleArtifact(artifact, output, allowDataUrl) {
+    const download = dataRow(await client.get(`/execution-artifacts/${artifact.artifactId}/download`));
+    if (typeof download.url !== 'string') {
+        throw new ValidationError('download', 'The execution artifact API response did not include a download URL');
+    }
+    await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+    await downloadToNewFile(download.url, output, { allowDataUrl });
+    const downloaded = await stat(output);
+    if (downloaded.size !== artifact.size) {
+        throw new ApiError(502, `Artifact ${artifact.artifactId} size does not match replay evidence`);
+    }
+    if ((await sha256File(output)) !== artifact.sha256) {
+        throw new ApiError(502, `Artifact ${artifact.artifactId} hash does not match replay evidence`);
+    }
+}
 export async function inspectRecoveryAction(id, options) {
     const executionId = resourceId(id);
     const bundle = dataRow(await client.get(`/executions/${executionId}/recovery/inspect`));
@@ -52,6 +126,36 @@ export async function downloadExecutionArtifactAction(artifactId, options) {
     });
     printJson({ artifactId: id, ...downloaded });
 }
+export async function exportExecutionReplayBundleAction(id, options) {
+    const executionId = resourceId(id);
+    const plan = replayBundlePlan(await client.get(`/executions/${executionId}/replay-bundle`));
+    await mkdir(dirname(options.output), { recursive: true, mode: 0o700 });
+    await mkdir(options.output, { mode: 0o700 });
+    try {
+        const inputs = plan.inputs.map((artifact, index) => ({
+            ...artifact,
+            path: join('inputs', replayBundleFileName(artifact.name, index)),
+        }));
+        const outputs = plan.outputs.map((artifact, index) => ({
+            ...artifact,
+            path: join('outputs', replayBundleFileName(artifact.name, index)),
+        }));
+        for (const artifact of [...inputs, ...outputs]) {
+            await downloadReplayBundleArtifact(artifact, join(options.output, artifact.path), options.allowDataUrl);
+        }
+        await writeFile(join(options.output, 'replay-bundle.json'), `${JSON.stringify({ ...plan, inputs, outputs }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        await rm(options.output, { recursive: true, force: true });
+        throw error;
+    }
+    printJson({
+        executionId: plan.executionId,
+        output: options.output,
+        inputs: plan.inputs.length,
+        outputs: plan.outputs.length,
+    });
+}
 export async function listExecutionsAction(options) {
     const filter = {};
     if (options.workflowId)
@@ -101,6 +205,19 @@ export function registerExecutionCommand(program) {
         cmd
             .command(`${verb} <id>`)
             .action(async (id) => action(() => viewExecutionAction(id, fields(program), verb === 'summary')));
+    cmd
+        .command('replay')
+        .description('Materialize verified local replay bundles')
+        .command('export <execution-id>')
+        .description('Download immutable replay inputs and outputs through the authenticated API')
+        .requiredOption('--output <path>', 'Write the replay bundle to a new directory')
+        .action(async (id, options) => action(() => {
+        const hostname = new URL(currentEnvironment().apiUrl).hostname;
+        return exportExecutionReplayBundleAction(id, {
+            ...options,
+            allowDataUrl: ['localhost', '127.0.0.1', '[::1]'].includes(hostname),
+        });
+    }));
     const artifact = cmd.command('artifact').description('Access immutable execution artifacts');
     artifact
         .command('download <artifact-id>')