firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/trial-state.js

@@ -0,0 +1,197 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { observedCellValue, stateChangeMatches } from '../../contracts/trial-state-contracts.js';
+import { checkpointReport, validateCheckpointReport } from './trial-checkpoints.js';
+const labels = { inserted: 'Added', updated: 'Updated', deleted: 'Removed' };
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const invalid = () => new CliError('trial_state_changed', 'The selected original state comparison could not be confirmed. Reopen the report.');
+export function validateTrialStateOptions(args, options) {
+    if (args[0] === 'checkpoints') {
+        validateCheckpointReport(args, options);
+        return;
+    }
+    const [comparison, action = 'changes', selected] = args;
+    if (args.length > 3 || comparison && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(comparison)
+        || !['changes', 'collections', 'events', 'causes'].includes(action) || !comparison && (args.length > 1 || options.search || options.status || options.evidenceKind)
+        || options.checkpoint !== undefined || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(options.search ?? '')
+        || options.status !== undefined && (action !== 'events' || !['completed', 'pending'].includes(options.status))
+        || options.evidenceKind !== undefined && (action !== 'changes' || selected !== undefined || !Object.hasOwn(labels, options.evidenceKind))
+        || selected !== undefined && (action === 'collections' || action === 'events' && !['before', 'after'].includes(selected)
+            || ['changes', 'causes'].includes(action) && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(selected))
+        || action === 'causes' && (!selected || options.search !== undefined)
+        || action === 'changes' && selected !== undefined && (options.page !== undefined || options.search !== undefined || options.status !== undefined || options.evidenceKind !== undefined))
+        throw new CliError('arguments_invalid', 'Use state [comparison], state <comparison> changes [change], causes <change>, collections, events [before|after], or state checkpoints. Search filters lists; --kind filters changes; --status filters events.', 2);
+}
+function boundaryLines(value, name) {
+    if (!value)
+        return [];
+    return [`${name}: ${value.snapshot_at ?? 'Snapshot time not recorded'}`,
+        ...(value.clock?.status === 'observed' ? [`SQL clock read: ${value.clock.read_at}; ${value.clock.mode === 'controlled'
+                ? `declared schedule offset ${value.clock.offset_ms}ms; ${value.clock.events_completed} completed and ${value.clock.events_pending} pending events`
+                : 'wall clock'}. This is not target time or time saved.`] : [])];
+}
+function summary(value) {
+    return [`Attempt ${value.attempt_number}: ${value.interval === 'whole_trial' ? 'Whole drill' : `Boundary ${value.before_sequence} to ${value.after_sequence}`} · ${value.state === 'queued' ? 'Comparison pending' : value.state === 'unavailable' ? 'Comparison unavailable' : 'Retained state comparison'}`,
+        ...(value.counts ? [`${value.counts.inserted.toLocaleString()} added; ${value.counts.updated.toLocaleString()} updated; ${value.counts.deleted.toLocaleString()} removed rows.`]
+            : ['Row changes have not been measured.']),
+        ...(value.collections_with_gaps ? [`${value.collections_with_gaps.toLocaleString()} collections could not be compared row by row.`] : []),
+        ...boundaryLines(value.boundaries?.before, 'Before'), ...boundaryLines(value.boundaries?.after, 'After')];
+}
+function shown(cell) {
+    const value = observedCellValue(cell);
+    const text = typeof value === 'string' ? value : JSON.stringify(value) ?? '';
+    return text.slice(0, 600) + (text.length > 600 || cell && 'truncated' in cell && cell.truncated ? '…' : '');
+}
+async function detail(prefix, change, scope, options, output, original) {
+    const parts = prefix.split('/');
+    const value = await api(`${prefix}/changes/${identifier(change)}`, { actor: scope.owner, workspace: scope.workspace,
+        signal: options.signal, maximumResponseBytes: 16 * 1024 ** 2 });
+    if (value.id !== change || original && !stateChangeMatches(value, original))
+        throw invalid();
+    output(value, [`${value.collection}: ${labels[value.kind]}`, ...value.changed_fields.slice(0, 40).map(name => `${name}\n  Before: ${shown(value.before?.[name])}\n  After: ${shown(value.after?.[name])}`),
+        ...(value.changed_fields.length > 40 ? [`Showing 40 of ${value.changed_fields.length} fields. Use --json for complete typed records.`] : []),
+        `Read each link's basis: confirmed controlled SQL/scheduled row writes differ from temporal operation associations. Read linked evidence: firedrill report ${parts.at(-5)} drill ${parts.at(-3)} state ${parts.at(-1)} causes ${change} --workspace ${scope.workspace}`].join('\n\n'));
+}
+export async function trialStateReport(args, path, scope, interactive, options, output) {
+    validateTrialStateOptions(args, options);
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const parts = path.split('/');
+    const command = `firedrill report ${identifier(parts.at(-3))} drill ${identifier(parts.at(-1))} state`;
+    if (args[0] === 'checkpoints') {
+        await checkpointReport(args, path, command, scope, interactive, options, output);
+        return;
+    }
+    let comparison = args[0], page = Number(options.page ?? 1), chosen = false;
+    if (!comparison) {
+        while (true) {
+            const data = await api(`${path}/state-comparisons?page=${page}`, auth);
+            output(data, [...data.results.map(row => [...summary(row), row.id,
+                    `Inspect: ${command} ${row.id} --workspace ${scope.workspace}`].join('\n')),
+                ...(!data.count ? ['No complete state interval is available. No empty state or zero change count is inferred.'] : []),
+                `Task checkpoints: ${command} checkpoints --workspace ${scope.workspace}`,
+                `${data.observations_retained.toLocaleString()} state observations retained. Page ${data.page}; ${data.count.toLocaleString()} comparisons.`,
+                ...(data.next ? [`Continue: ${command} --workspace ${scope.workspace} --page ${page + 1}${options.json ? ' --json' : ''}`] : [])].join('\n\n'));
+            if (!interactive)
+                return;
+            const choices = data.results.map(row => ({ value: row.id, label: `Attempt ${row.attempt_number}`, detail: summary(row).join(' ') }));
+            choices.push({ value: 'checkpoints', label: 'Task checkpoints and observed records', detail: 'Inspect actual boundary state without invoking the target' });
+            if (page > 1)
+                choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+            if (data.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            choices.push({ value: 'done', label: 'Done', detail: '' });
+            const value = await selectOne('State comparison', choices, options.signal);
+            if (value === 'done')
+                return;
+            if (value === 'checkpoints') {
+                await checkpointReport(['checkpoints'], path, command, scope, true, { ...options, page: undefined, search: undefined }, output);
+                return;
+            }
+            if (value === 'previous' || value === 'next') {
+                page += value === 'next' ? 1 : -1;
+                continue;
+            }
+            comparison = identifier(value);
+            chosen = true;
+            page = 1;
+            break;
+        }
+    }
+    const selectedComparison = identifier(comparison);
+    const mode = args[1] ?? (interactive && !options.search && !options.status && !options.evidenceKind ? await selectOne('Inspect state', [
+        { value: 'changes', label: 'Observed row changes' }, { value: 'collections', label: 'Collection coverage and gaps' },
+        { value: 'events', label: 'Scheduled changes at a boundary' }, { value: 'done', label: 'Done' }
+    ], options.signal) : 'changes');
+    if (mode === 'done')
+        return;
+    const prefix = `${path}/state-comparisons/${selectedComparison}`;
+    if (mode === 'causes') {
+        const change = identifier(args[2]);
+        while (true) {
+            const data = await api(`${prefix}/changes/${change}/causes?page=${page}`, auth);
+            output(data, [...data.results.map(row => `${row.producer_origin === 'customer_device' ? 'Device reported: ' : ''}${row.kind}: ${row.reference}\n${row.basis === 'committed_tool_transaction' ? 'Confirmed controlled SQL tool write' : row.basis === 'committed_schedule_transaction' ? 'Confirmed scheduled write in this linked interval' : 'Observed interval association, not proof of causality'}${row.transactions.length ? `\nNative transactions: ${row.transactions.join(', ')}` : ''}${row.relationship === 'row_history' ? `\nEarlier row mutation, not proof of contribution to the final value: ${command} ${row.source_comparison_id} --workspace ${scope.workspace}` : ''}${row.action_id ? `\nOperation: firedrill report ${parts.at(-3)} drill ${parts.at(-1)} actions ${row.action_id} --workspace ${scope.workspace}` : ''}`),
+                ...(!data.count ? ['No individual cause was established for this change.'] : []), `Page ${data.page}; ${data.count.toLocaleString()} linked references.`,
+                ...(data.next ? [`Continue: ${command} ${selectedComparison} causes ${change} --workspace ${scope.workspace} --page ${page + 1}${options.json ? ' --json' : ''}`] : [])].join('\n\n'));
+            if (!interactive)
+                return;
+            const choices = [{ value: 'done', label: 'Done' }];
+            if (page > 1)
+                choices.unshift({ value: 'previous', label: 'Previous page' });
+            if (data.next)
+                choices.unshift({ value: 'next', label: 'Next page' });
+            const value = await selectOne('Linked state evidence', choices, options.signal);
+            if (value === 'done')
+                return;
+            page += value === 'next' ? 1 : -1;
+        }
+    }
+    if (mode === 'changes' && args[2]) {
+        await detail(prefix, args[2], scope, options, output);
+        return;
+    }
+    const term = chosen ? '' : options.search ?? '', kind = options.evidenceKind ?? '', status = options.status ?? '', phase = args[2] ?? 'after';
+    const continuation = `${command} ${selectedComparison} ${mode}${mode === 'events' ? ' ' + phase : ''} --workspace ${scope.workspace}`
+        + (term ? ' --search ' + quote(term) : '') + (kind ? ' --kind ' + kind : '') + (status ? ' --status ' + status : '') + (options.json ? ' --json' : '');
+    while (true) {
+        const params = new URLSearchParams({ page: String(page), q: term });
+        if (mode === 'events') {
+            params.set('phase', phase);
+            params.set('status', status);
+        }
+        if (mode === 'changes')
+            params.set('kind', kind);
+        const route = mode === 'events' ? 'world-events' : mode;
+        let rows = [], count, next;
+        if (mode === 'changes') {
+            const data = await api(`${prefix}/${route}?${params}`, auth);
+            if (data.comparison.id !== selectedComparison)
+                throw invalid();
+            rows = data.results;
+            count = data.count;
+            next = data.next;
+            output(data, [...summary(data.comparison), ...rows.map(row => `${labels[row.kind]}: ${row.collection}\n${Object.entries(row.identity).map(([key, value]) => `${key}: ${shown(value)}`).join('; ')}\n${row.field_count} changed fields; ${row.id}\nRead: ${command} ${selectedComparison} changes ${row.id} --workspace ${scope.workspace}`),
+                ...(!count ? [data.comparison.state === 'queued' ? 'Comparing retained observations.' : data.comparison.counts === null
+                        ? 'Row changes could not be measured. Inspect collection coverage or original files.' : 'No matching observed row changes.'] : []),
+                `Page ${data.page}; ${count.toLocaleString()} matching changes.`, ...(next ? [`Continue: ${continuation} --page ${page + 1}`] : [])].join('\n\n'));
+        }
+        else if (mode === 'collections') {
+            const data = await api(`${prefix}/${route}?${params}`, auth);
+            count = data.count;
+            next = data.next;
+            output(data, [...data.results.map(row => `${row.name}: ${row.before_rows ?? 'Not present'} rows before; ${row.after_rows ?? 'Not present'} after.\n${row.comparable ? 'Rows compared' : row.gap === 'schema_changed' ? 'Schema changed' : 'Stable row key unavailable'}; collection ${row.collection_change}.`),
+                ...(!count ? ['No matching observed collections.'] : []), `Page ${data.page}; ${count.toLocaleString()} collections.`,
+                ...(next ? [`Continue: ${continuation} --page ${page + 1}`] : [])].join('\n\n'));
+        }
+        else {
+            const data = await api(`${prefix}/${route}?${params}`, auth);
+            count = data.count;
+            next = data.next;
+            output(data, [...boundaryLines(data.boundary, phase === 'before' ? 'Before' : 'After'),
+                ...data.results.map(row => `${row.id}: ${row.action} ${row.collection}; ${row.offset_ms}ms from declared world start; ${row.status}.`),
+                ...(!count ? ['No matching scheduled changes in this observation.'] : []), `Page ${data.page}; ${count.toLocaleString()} events.`,
+                ...(next ? [`Continue: ${continuation} --page ${page + 1}`] : [])].join('\n\n'));
+        }
+        if (!interactive)
+            return;
+        const choices = rows.map(row => ({ value: row.id, label: `${labels[row.kind]}: ${row.collection}`, detail: `${row.field_count} changed fields` }));
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+        if (next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        choices.push({ value: 'done', label: 'Done', detail: '' });
+        const value = await selectOne('State report', choices, options.signal);
+        if (value === 'done')
+            return;
+        if (value === 'previous' || value === 'next') {
+            page += value === 'next' ? 1 : -1;
+            continue;
+        }
+        const original = rows.find(row => row.id === value);
+        if (!original)
+            throw invalid();
+        await detail(prefix, value, scope, options, output, original);
+    }
+}

package/dist/cli/src/vault.js

@@ -0,0 +1,266 @@
+import { APP_ORIGIN } from './http.js';
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api, openBrowser } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { auth, choosePaged, interactive, line, query } from './configuration.js';
+import { readMetadata, record } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { secretLine, selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+const invalid = () => new CliError('vault_input_invalid', 'Use the exact Vault metadata and original request. Values belong in hidden input or --value-stdin, never JSON metadata or command arguments.', 2);
+const fields = (value, keys) => Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+const at = (value) => value === null || typeof value === 'string' && value.length <= 40
+    && /(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value));
+function checkedMetadata(value) {
+    if (!record(value) || !fields(value, ['name', 'secret', 'phase', 'purpose', 'expires_at', ...(value.replaces_id ? ['replaces_id', 'basis_version'] : [])])
+        || typeof value.name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value.name) || typeof value.secret !== 'boolean'
+        || !['build', 'runtime', 'both'].includes(String(value.phase)) || typeof value.purpose !== 'string' || value.purpose.length > 255 || !at(value.expires_at)
+        || value.replaces_id && (typeof value.replaces_id !== 'string' || !Number.isSafeInteger(value.basis_version) || Number(value.basis_version) < 1))
+        throw invalid();
+    if (value.replaces_id)
+        identifier(String(value.replaces_id));
+    return value;
+}
+const same = (a, b) => ['name', 'secret', 'phase', 'purpose', 'replaces_id', 'basis_version']
+    .every(key => a[key] === b[key])
+    && (a.expires_at === null ? b.expires_at === null : b.expires_at !== null && Date.parse(a.expires_at) === Date.parse(b.expires_at));
+const location = async (scope, key) => join(await privateDirectory(), `vault-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+async function retained(scope, key) {
+    const value = await readMetadata(await location(scope, key), true);
+    if (!fields(value, ['schema', 'actor', 'workspace', 'key', 'metadata']) || value.schema !== 'firedrill.local-vault-intent.v1'
+        || value.actor !== scope.owner || value.workspace !== scope.workspace || value.key !== identifier(key))
+        throw invalid();
+    checkedMetadata(value.metadata);
+    return value;
+}
+async function remember(scope, value) {
+    checkedMetadata(value.metadata);
+    try {
+        const file = await open(await location(scope, value.key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!record(error) || error.code !== 'EEXIST')
+            throw error;
+        if (!same((await retained(scope, value.key)).metadata, value.metadata))
+            throw invalid();
+    }
+}
+function checkedReceipt(value, scope, key, metadata) {
+    if (!value || value.schema !== 'firedrill.vault-request.v1' || value.actor_id !== scope.owner || value.workspace_id !== scope.workspace
+        || value.request_key !== key || !['accepted', 'not_received'].includes(value.state) || typeof value.requires_value !== 'boolean'
+        || value.state === 'not_received' && (value.entry !== null || value.metadata !== null || value.requires_value)
+        || value.state === 'accepted' && (!value.entry || !value.metadata || metadata && !same(checkedMetadata(value.metadata), metadata)))
+        throw invalid();
+    if (value.entry)
+        identifier(value.entry.id);
+    return value;
+}
+function summary(row) {
+    const expired = row.expires_at && Date.parse(row.expires_at) <= Date.now();
+    return `${row.name} · v${row.version} · ${row.phase} · ${row.state === 'revoked' ? 'Revoked' : expired ? 'Expired' : row.state === 'active' ? row.secret ? 'Secret saved' : row.empty ? 'Empty configuration' : 'Configuration saved' : 'Save pending'}\n${row.id}${row.expires_at ? '\nExpires: ' + row.expires_at : ''}${row.original_request_key ? '\nContinue: firedrill vault resume ' + identifier(row.original_request_key) : ''}`;
+}
+function show(value, output) {
+    output(value, [`Request: ${value.request_key}`, value.entry ? summary(value.entry) : 'Not confirmed. The original request may still arrive.'].map(terminalText).join('\n'));
+}
+async function approve(options, message) {
+    if (options.approve)
+        return;
+    if (!interactive(options) || !await selectOne(message, [{ value: false, label: 'Cancel' }, { value: true, label: 'Confirm change' }], options.signal))
+        throw new CliError('approval_required', 'Nothing was submitted. Review this change and pass --approve-change for automation.', 2);
+}
+export async function readPrivateValue(options) {
+    if (!options.valueStdin) {
+        if (!interactive(options))
+            throw new CliError('value_input_required', 'Pipe the exact UTF-8 value with --value-stdin for automation. Do not pass values in command arguments.', 2);
+        return secretLine('Value', options.signal);
+    }
+    if (process.stdin.isTTY)
+        throw new CliError('value_input_required', 'Pipe the exact UTF-8 value with --value-stdin, or omit the flag to use hidden input.', 2);
+    const chunks = [];
+    let count = 0;
+    const onAbort = () => process.stdin.destroy(new CliError('canceled', 'Value input canceled. No save was submitted.', 130));
+    options.signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        if (options.signal.aborted)
+            onAbort();
+        for await (const chunk of process.stdin) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            count += bytes.length;
+            if (count > 65536)
+                throw new CliError('value_capacity', 'The value exceeds secure-entry capacity. No save was submitted.', 2);
+            chunks.push(bytes);
+        }
+        const joined = Buffer.concat(chunks);
+        try {
+            return new TextDecoder('utf-8', { fatal: true }).decode(joined);
+        }
+        catch {
+            throw invalid();
+        }
+        finally {
+            joined.fill(0);
+        }
+    }
+    finally {
+        for (const chunk of chunks)
+            chunk.fill(0);
+        options.signal.removeEventListener('abort', onAbort);
+    }
+}
+async function expiryChoice(options) {
+    if (!await selectOne('Expiry', [{ value: false, label: 'No expiry' }, { value: true, label: 'Set an expiry date' }], options.signal))
+        return null;
+    const value = await line('Expiry (ISO date with timezone)', 40, options.signal);
+    if (!at(value))
+        throw invalid();
+    return new Date(value).toISOString();
+}
+async function submit(scope, intent, options, output) {
+    const base = `/api/workspaces/${scope.workspace}/vault`, access = auth(scope, options);
+    let saved = checkedReceipt(await api(`${base}/requests/${intent.key}`, access), scope, intent.key, intent.metadata);
+    if (saved.entry && ['active', 'revoked'].includes(saved.entry.state)) {
+        show(saved, output);
+        return;
+    }
+    await approve(options, intent.metadata.replaces_id ? `Replace ${terminalText(intent.metadata.name)} and revoke old grants after storage is confirmed? Review world and CI mappings afterward.` : `Save ${terminalText(intent.metadata.name)} for ${intent.metadata.phase}?`);
+    await remember(scope, intent);
+    output({ phase: 'request_prepared', request_key: intent.key, workspace_id: scope.workspace }, `Request: ${intent.key}\nRecovery: firedrill vault request ${intent.key} --workspace ${scope.workspace}\nContinue: firedrill vault resume ${intent.key} --workspace ${scope.workspace}`);
+    let value;
+    try {
+        if (saved.state === 'not_received' || saved.requires_value)
+            value = await readPrivateValue(options);
+        if (intent.metadata.secret && value === '')
+            throw new CliError('value_required', 'Enter a nonempty secret, or use a non-secret configuration value.', 2);
+        if (saved.state === 'not_received') {
+            const { replaces_id, basis_version, ...metadata } = intent.metadata;
+            if (value === undefined || replaces_id && basis_version === undefined)
+                throw invalid();
+            const body = replaces_id
+                ? { basis_version: basis_version, revoke_previous: true, expires_at: metadata.expires_at, value } : { ...metadata, value };
+            await api(replaces_id ? `${base}/${identifier(replaces_id)}/rotate` : base, { ...access, method: 'POST', idempotencyKey: intent.key, body });
+        }
+        else
+            await api(`${base}/requests/${intent.key}`, { ...access, method: 'POST', body: value === undefined ? {} : { value } });
+        saved = checkedReceipt(await api(`${base}/requests/${intent.key}`, access), scope, intent.key, intent.metadata);
+        show(saved, output);
+        if (!saved.entry || !['active', 'revoked'].includes(saved.entry.state))
+            throw new CliError('vault_write_pending', 'The original save is not complete. Use its request ID to inspect or continue it. No second save was created.');
+    }
+    finally {
+        value = undefined;
+    }
+}
+export async function vaultCommand(args, options, output) {
+    let action = args[0] ?? (interactive(options) ? '' : 'list');
+    if (!action)
+        action = await selectOne('Vault', [{ value: 'list', label: 'View saved values' }, { value: 'save', label: 'Save a value' },
+            { value: 'rotate', label: 'Rotate a value' }, { value: 'expiry', label: 'Change expiry' }, { value: 'remove', label: 'Remove a value' }, { value: 'open', label: 'Open Vault in the browser' }], options.signal);
+    if (!['list', 'show', 'save', 'rotate', 'expiry', 'remove', 'request', 'resume', 'open'].includes(action) || args.length > (['list', 'save', 'open'].includes(action) ? 1 : 2)
+        || options.file && !['save', 'rotate', 'expiry'].includes(action) || options.request && !['save', 'rotate'].includes(action)
+        || options.valueStdin && !['save', 'rotate', 'resume'].includes(action) || options.approve && !['save', 'rotate', 'expiry', 'remove', 'resume'].includes(action)
+        || (options.page || options.search || options.status) && action !== 'list')
+        throw invalid();
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) }), access = auth(scope, options), base = `/api/workspaces/${scope.workspace}/vault`;
+    if (action === 'open') {
+        const url = new URL('/vault', APP_ORIGIN);
+        url.searchParams.set('workspace', scope.workspace);
+        output({ url: url.href, workspace_id: scope.workspace }, url.href);
+        if (options.openBrowser && interactive(options))
+            await openBrowser(url.href);
+        return;
+    }
+    if (action === 'list') {
+        if (options.status && !['current', 'all', 'revoked', 'pending', 'expired'].includes(options.status))
+            throw invalid();
+        const rows = await api(`${base}?${query(options)}&status=${options.status ?? 'current'}`, access);
+        output(rows, [...rows.results.map(summary), ...(!rows.count ? ['No matching values.'] : []), `Page ${rows.page}; ${rows.count.toLocaleString()} values.`,
+            ...(rows.next ? ['Use --page ' + (rows.page + 1) + ' with the same filters to continue.'] : [])].map(terminalText).join('\n\n'));
+        return;
+    }
+    if (action === 'request' || action === 'resume') {
+        const key = identifier(args[1] ?? ''), value = checkedReceipt(await api(`${base}/requests/${key}`, access), scope, key);
+        if (action === 'request') {
+            show(value, output);
+            return;
+        }
+        const intent = value.metadata ? { schema: 'firedrill.local-vault-intent.v1', actor: scope.owner, workspace: scope.workspace, key, metadata: checkedMetadata(value.metadata) } : await retained(scope, key);
+        await submit(scope, intent, options, output);
+        return;
+    }
+    let entry = null;
+    if (!['save'].includes(action)) {
+        const id = args[1] ?? (interactive(options) ? (await choosePaged('Value', base, scope, options, row => ({ label: row.name, detail: `v${row.version} · ${row.phase} · ${row.state}` })))?.id : undefined);
+        if (!id)
+            throw new CliError('vault_entry_required', 'Choose an entry with firedrill vault list.', 2);
+        entry = await api(`${base}/${identifier(id)}`, access);
+        if (!entry || entry.id !== id)
+            throw invalid();
+        if (action === 'show') {
+            output(entry, terminalText(summary(entry)));
+            return;
+        }
+        if (action === 'remove') {
+            await approve(options, `Remove ${terminalText(entry.name)}? Existing grants will stop resolving. This does not revoke the original provider credential.`);
+            const value = await api(`${base}/${entry.id}`, { ...access, method: 'DELETE' });
+            if (!value || value.state !== 'revoked')
+                throw invalid();
+            output(value, 'Value removed.');
+            return;
+        }
+    }
+    if (action === 'expiry') {
+        const body = options.file ? await readMetadata(options.file) : interactive(options) ? { basis_revision: entry.metadata_revision, expires_at: await expiryChoice(options) } : null;
+        if (!body || !fields(body, ['basis_revision', 'expires_at']) || !Number.isSafeInteger(body.basis_revision) || Number(body.basis_revision) < 1 || !at(body.expires_at))
+            throw invalid();
+        await approve(options, `Change the expiry for ${terminalText(entry.name)}?`);
+        const expiresAt = body.expires_at;
+        const change = { basis_revision: Number(body.basis_revision), expires_at: expiresAt };
+        const value = await api(`${base}/${entry.id}`, { ...access, method: 'PATCH', body: change });
+        if (!value || value.id !== entry.id || value.version !== entry.version || value.state !== 'active'
+            || !Number.isSafeInteger(value.metadata_revision) || value.metadata_revision < entry.metadata_revision
+            || (value.expires_at === null) !== (expiresAt === null)
+            || expiresAt !== null && Date.parse(value.expires_at) !== Date.parse(expiresAt))
+            throw invalid();
+        output(value, terminalText(summary(value)));
+        return;
+    }
+    let metadata;
+    if (options.file) {
+        const body = await readMetadata(options.file);
+        if (action === 'rotate') {
+            if (!fields(body, ['expires_at']) || !at(body.expires_at))
+                throw invalid();
+            metadata = { name: entry.name, secret: entry.secret, phase: entry.phase, purpose: entry.purpose,
+                expires_at: body.expires_at, replaces_id: entry.id, basis_version: entry.version };
+        }
+        else
+            metadata = checkedMetadata(body);
+    }
+    else {
+        if (!interactive(options))
+            throw new CliError('vault_metadata_required', 'Pass --file with metadata only. Use hidden input or --value-stdin for the value. Run interactively for guided setup.', 2);
+        metadata = action === 'rotate' ? { name: entry.name, secret: entry.secret, phase: entry.phase, purpose: entry.purpose,
+            expires_at: await expiryChoice(options), replaces_id: entry.id, basis_version: entry.version } : {
+            name: await line('Name', 128, options.signal), secret: await selectOne('Value type', [{ value: true, label: 'Secret' }, { value: false, label: 'Configuration' }], options.signal),
+            phase: await selectOne('Available during', [{ value: 'runtime', label: 'Runtime' }, { value: 'build', label: 'Build time' }, { value: 'both', label: 'Build and runtime' }], options.signal),
+            purpose: await line('Purpose (optional)', 255, options.signal), expires_at: await expiryChoice(options)
+        };
+    }
+    checkedMetadata(metadata);
+    // Normalize request metadata once, before persistence or provider submission.
+    metadata.expires_at = metadata.expires_at ? new Date(metadata.expires_at).toISOString() : null;
+    if (action === 'save' && metadata.replaces_id)
+        throw invalid();
+    await submit(scope, { schema: 'firedrill.local-vault-intent.v1', actor: scope.owner, workspace: scope.workspace,
+        key: options.request ? identifier(options.request) : randomUUID(), metadata }, options, output);
+}