firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/evidence-bundles.js

@@ -0,0 +1,367 @@
+import { constants } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, opendir, realpath, link, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { access, api } from './auth.js';
+import { CliError, endpoint, responseError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { evidenceManifestMatches, driverEventMatches, timelineMatches } from '../../contracts/evidence-contracts.js';
+const invalid = () => new CliError('evidence_identity_changed', 'The selected evidence could not be confirmed. Nothing was invoked or regraded.');
+const filterKeys = ['kind', 'artifact', 'step', 'attempt', 'from_at', 'to_at'];
+function instant(value) {
+    if (value === undefined)
+        return null;
+    if (value.length > 64 || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+        || !Number.isFinite(Date.parse(value)))
+        throw new CliError('evidence_filter_invalid', 'Use an ISO date and time with seconds and Z or a UTC offset, such as 2026-11-08T18:30:00Z.', 2);
+    return value;
+}
+function selectionFor(options, artifact) {
+    const attempt = options.evidenceAttempt ?? null;
+    if (attempt !== null && (!/^[1-9][0-9]{0,9}$/.test(attempt) || Number(attempt) > 2147483647))
+        throw new CliError('evidence_filter_invalid', 'Choose an attempt number between 1 and 2147483647.', 2);
+    const from = instant(options.evidenceFrom), to = instant(options.evidenceTo);
+    if (from !== null && to !== null && Date.parse(from) > Date.parse(to))
+        throw new CliError('evidence_filter_invalid', 'The start time must be before or equal to the end time.', 2);
+    return { kind: options.evidenceKind ?? '', artifact, step: options.evidenceStep === undefined ? null : identifier(options.evidenceStep),
+        attempt, from_at: from, to_at: to };
+}
+function originalIntent(value, prefix, execution, scope, selection) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw invalid();
+    const row = value;
+    if (row.owner !== scope.owner || row.workspace !== scope.workspace || row.execution !== execution || row.prefix !== prefix
+        || typeof row.through_at !== 'string' || row.through_at.length > 64 || !Number.isFinite(Date.parse(row.through_at)))
+        throw invalid();
+    const common = ['schema', 'owner', 'workspace', 'execution', 'prefix', 'through_at'];
+    if (row.schema === 'firedrill.evidence-bundle.v1') {
+        // Recover only the original pre-filter selection. Do not rewrite the
+        // existing journal or let new filters relabel its already-saved pages.
+        const keys = [...common, 'kind', 'artifact'];
+        if (Object.keys(row).length !== keys.length || Object.keys(row).some(key => !keys.includes(key))
+            || row.kind !== selection.kind || row.artifact !== selection.artifact
+            || selection.step !== null || selection.attempt !== null || selection.from_at !== null || selection.to_at !== null)
+            throw invalid();
+    }
+    else if (row.schema === 'firedrill.evidence-bundle.v2') {
+        const keys = [...common, 'selection'];
+        const saved = row.selection;
+        if (Object.keys(row).length !== keys.length || Object.keys(row).some(key => !keys.includes(key))
+            || !saved || typeof saved !== 'object' || Array.isArray(saved)
+            || Object.keys(saved).length !== filterKeys.length || Object.keys(saved).some(key => !filterKeys.some(name => name === key))
+            || filterKeys.some(key => saved[key] !== selection[key]))
+            throw invalid();
+    }
+    else
+        throw invalid();
+    return { schema: 'firedrill.evidence-bundle.v2', ...scope, execution, prefix, through_at: row.through_at, selection };
+}
+function continuation(prefix, execution, scope, selection, page, json) {
+    const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+    const command = `firedrill report ${prefix.split('/')[5]} drill ${execution} evidence${selection.artifact ? ` ${selection.artifact}` : ''}`
+        + ` --workspace ${scope.workspace} --page ${page}${json ? ' --json' : ''}`;
+    return command + (selection.kind ? ` --kind ${quote(selection.kind)}` : '') + (selection.step ? ` --step ${selection.step}` : '')
+        + (selection.attempt ? ` --attempt ${selection.attempt}` : '')
+        + (selection.from_at ? ` --from-at ${quote(selection.from_at)}` : '') + (selection.to_at ? ` --to-at ${quote(selection.to_at)}` : '');
+}
+async function regular(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid()) {
+        await file.close();
+        throw new CliError('evidence_file_unsafe', 'Use private regular evidence files owned by this account. Symlinks and shared files are refused.');
+    }
+    return file;
+}
+async function readJSON(path, limit) {
+    const file = await regular(path);
+    try {
+        if ((await file.stat()).size > limit)
+            throw invalid();
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+async function writeNew(path, value) {
+    const temporary = join(dirname(path), `.evidence-${randomUUID()}.partial`);
+    const file = await open(temporary, 'wx', 0o600), stat = await file.stat();
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+        const current = await lstat(temporary);
+        if (!current.isFile() || current.ino !== stat.ino || current.dev !== stat.dev)
+            throw invalid();
+        await link(temporary, path); // Publish complete metadata; never overwrite.
+    }
+    finally {
+        await file.close();
+        const current = await lstat(temporary).catch(() => null);
+        if (current?.isFile() && current.ino === stat.ino && current.dev === stat.dev)
+            await unlink(temporary);
+    }
+}
+async function privateDirectory(path, create = true) {
+    if (create)
+        await mkdir(path, { mode: 0o700 }).catch(error => {
+            if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+                throw error;
+        });
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+        throw new CliError('evidence_directory_unsafe', 'Choose a private evidence directory owned by this account, not a symlink or shared folder.');
+}
+async function hashFile(file, maximum) {
+    const stat = await file.stat();
+    if (stat.size > maximum)
+        throw new CliError('evidence_checksum_mismatch', 'A partial file is larger than the original evidence. It was not replaced.');
+    const hash = createHash('sha256'), buffer = Buffer.alloc(1024 * 1024);
+    let position = 0;
+    while (position < stat.size) {
+        const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, stat.size - position), position);
+        if (!bytesRead)
+            throw invalid();
+        hash.update(buffer.subarray(0, bytesRead));
+        position += bytesRead;
+    }
+    return { hash, size: position };
+}
+async function download(row, directory, scope, options) {
+    if (row.state !== 'available' || !row.download_path || !row.sha256 || !row.generation)
+        throw invalid();
+    const destination = join(directory, row.filename), partial = join(directory, `.${row.id}.partial`);
+    const exists = await lstat(destination).catch(error => { if (error?.code !== 'ENOENT')
+        throw error; return null; });
+    if (exists) {
+        const interrupted = await lstat(partial).catch(error => {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+            return null;
+        });
+        if (exists.isFile() && exists.nlink === 2 && interrupted?.isFile() && interrupted.ino === exists.ino && interrupted.dev === exists.dev)
+            await unlink(partial); // Recover only our exact already-published inode.
+        const finished = await regular(destination);
+        try {
+            const current = await hashFile(finished, row.size);
+            if (current.size !== row.size || current.hash.digest('hex') !== row.sha256)
+                throw invalid();
+        }
+        finally {
+            await finished.close();
+        }
+        return;
+    }
+    let file;
+    try {
+        file = await open(partial, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+        file = await open(partial, constants.O_RDWR | constants.O_NOFOLLOW);
+    }
+    const original = await file.stat();
+    try {
+        if (!original.isFile() || original.nlink !== 1 || original.mode & 0o077 || process.getuid && original.uid !== process.getuid())
+            throw invalid();
+        const current = await hashFile(file, row.size);
+        let position = current.size;
+        const etag = `"${row.sha256}:${row.generation}"`;
+        if (position < row.size || row.size === 0)
+            await access(async (token) => {
+                const start = position;
+                const response = await fetch(endpoint(row.download_path), { redirect: 'error', credentials: 'omit',
+                    signal: AbortSignal.any([options.signal, AbortSignal.timeout(2 * 60 * 60 * 1000)]),
+                    headers: { Authorization: `Bearer ${token}`, 'X-Firedrill-Actor': scope.owner, 'X-Firedrill-Workspace': scope.workspace,
+                        'If-Match': etag, ...(start ? { Range: `bytes=${start}-` } : {}) } });
+                if (response.status !== (start ? 206 : 200)) {
+                    await response.body?.cancel();
+                    throw responseError(null, response.status);
+                }
+                if (response.headers.get('content-length') !== String(row.size - start) || response.headers.get('etag') !== etag
+                    || response.headers.get('x-content-sha256') !== row.sha256 || response.headers.get('x-evidence-generation') !== row.generation
+                    || response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== row.content_type.toLowerCase()
+                    || start && response.headers.get('content-range') !== `bytes ${start}-${row.size - 1}/${row.size}` || !response.body) {
+                    await response.body?.cancel();
+                    throw invalid();
+                }
+                const reader = response.body.getReader();
+                try {
+                    while (true) {
+                        const part = await reader.read();
+                        if (part.done)
+                            break;
+                        if (position + part.value.byteLength > row.size)
+                            throw invalid();
+                        let offset = 0;
+                        while (offset < part.value.byteLength) {
+                            const written = await file.write(part.value, offset, part.value.byteLength - offset, position);
+                            if (!written.bytesWritten)
+                                throw new CliError('evidence_disk_unavailable', 'The evidence file could not be written. Free disk space, then resume the same bundle.');
+                            current.hash.update(part.value.subarray(offset, offset + written.bytesWritten));
+                            offset += written.bytesWritten;
+                            position += written.bytesWritten;
+                        }
+                    }
+                }
+                finally {
+                    await reader.cancel().catch(() => undefined);
+                    reader.releaseLock();
+                }
+            });
+        if (position !== row.size || current.hash.digest('hex') !== row.sha256)
+            throw new CliError('evidence_checksum_mismatch', 'The evidence is incomplete or its checksum does not match. The partial file is preserved for inspection, not published as complete.');
+        await file.sync();
+        const latest = await lstat(partial);
+        if (!latest.isFile() || latest.ino !== original.ino || latest.dev !== original.dev || latest.size !== row.size)
+            throw invalid();
+        await link(partial, destination);
+        await unlink(partial);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function manifest(prefix, execution, scope, options, page, selection, boundary) {
+    const query = new URLSearchParams({ page: String(page), page_size: '100', kind: selection.kind });
+    if (boundary)
+        query.set('through_at', boundary);
+    for (const key of ['artifact', 'step', 'attempt', 'from_at', 'to_at']) {
+        const value = selection[key];
+        if (value !== null)
+            query.set(key, value);
+    }
+    const result = await api(`${prefix}/evidence?${query}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+    if (!evidenceManifestMatches(result, prefix, execution) || result.page !== page || boundary && result.through_at !== boundary)
+        throw invalid();
+    return result;
+}
+async function readOrDownload(prefix, execution, selection, scope, interactive, options, output) {
+    const artifact = selection ? identifier(selection) : null;
+    const selected = selectionFor(options, artifact);
+    if (artifact && options.page !== undefined && options.page !== '1')
+        throw new CliError('arguments_invalid', 'An individual evidence file has one manifest page. Omit --page or use --page 1.', 2);
+    if (!options.into) {
+        if (options.approveDownload)
+            throw new CliError('arguments_invalid', 'Choose --into <private-directory> before approving an evidence download.', 2);
+        const value = await manifest(prefix, execution, scope, options, Number(options.page ?? 1), selected);
+        output(value, [...value.results.map(row => `${row.id} · ${row.kind} · ${row.state} · ${row.size.toLocaleString()} bytes`),
+            `Page ${value.page}; ${value.count.toLocaleString()} files.`,
+            ...(value.next ? [`Next: ${continuation(prefix, execution, scope, selected, value.page + 1, options.json)}`] : []),
+            'Download with the same filters, omit --page and add --into <private-directory>. Repeat it to resume an interrupted bundle.'].join('\n'));
+        return;
+    }
+    if (options.page !== undefined)
+        throw new CliError('arguments_invalid', 'A bundle streams all selected manifest pages. Omit --page when downloading.', 2);
+    if (!['linux', 'darwin'].includes(process.platform) || !constants.O_NOFOLLOW)
+        throw new CliError('evidence_filesystem_unsupported', 'Private resumable evidence bundles currently require Linux or macOS file-isolation support. Individual authenticated downloads remain available in the portal.', 2);
+    if (!options.approveDownload && (!interactive || !await selectOne('Save private evidence on this device?', [
+        { value: false, label: 'Cancel' }, { value: true, label: 'Download evidence', detail: 'Selected conversations, captures, state and traces. Existing files are never replaced.' }
+    ], options.signal)))
+        throw new CliError('evidence_download_consent_required', 'Use --approve-download to save the selected private evidence in non-interactive mode.', 2);
+    const chosen = resolve(options.into), parent = await realpath(dirname(chosen)), directory = join(parent, basename(chosen));
+    await privateDirectory(directory);
+    const intentPath = join(directory, 'manifest.json');
+    let intent = null;
+    try {
+        intent = originalIntent(await readJSON(intentPath, 16384), prefix, execution, scope, selected);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    if (!intent) {
+        const entries = await opendir(directory);
+        try {
+            if (await entries.read())
+                throw new CliError('evidence_directory_not_empty', 'Choose an empty private directory or the original evidence bundle directory.', 2);
+        }
+        finally {
+            await entries.close();
+        }
+    }
+    let page = await manifest(prefix, execution, scope, options, 1, selected, intent?.through_at);
+    if (!intent) {
+        intent = { schema: 'firedrill.evidence-bundle.v2', ...scope, execution, prefix, through_at: page.through_at, selection: selected };
+        await writeNew(intentPath, intent);
+    }
+    await privateDirectory(join(directory, 'pages'));
+    await privateDirectory(join(directory, 'files'));
+    let completed = 0, unavailable = 0;
+    while (true) {
+        options.signal.throwIfAborted();
+        const pagePath = join(directory, 'pages', `page-${page.page}.json`);
+        const exists = await lstat(pagePath).catch(error => { if (error?.code !== 'ENOENT')
+            throw error; return null; });
+        if (exists) {
+            const retained = await readJSON(pagePath, 2 * 1024 ** 2);
+            if (!evidenceManifestMatches(retained, prefix, execution) || retained.page !== page.page || retained.through_at !== intent.through_at
+                || retained.results.length !== page.results.length || retained.results.some((old, index) => {
+                const current = page.results[index];
+                return old.id !== current.id || old.generation !== current.generation || old.sha256 !== current.sha256 || old.size !== current.size;
+            }))
+                throw invalid();
+        }
+        else
+            await writeNew(pagePath, page);
+        for (const row of page.results) {
+            if (row.state !== 'available') {
+                unavailable++;
+                continue;
+            }
+            process.stderr.write(`Evidence ${terminalText(row.id)} · ${row.size.toLocaleString()} bytes\n`);
+            await download(row, join(directory, 'files'), scope, options);
+            completed++;
+        }
+        if (!page.next)
+            break;
+        page = await manifest(prefix, execution, scope, options, page.page + 1, selected, intent.through_at);
+    }
+    output({ schema: 'firedrill.evidence-bundle-receipt.v1', execution_id: execution, completed_files: completed,
+        unavailable_files: unavailable, through_at: intent.through_at, directory }, `${completed.toLocaleString()} evidence files saved with verified SHA256.${unavailable ? ` ${unavailable.toLocaleString()} files are unavailable; their manifest entries are retained.` : ''}\n${directory}`);
+}
+export async function evidenceCommand(prefix, execution, selection, scope, interactive, options, output) {
+    try {
+        await readOrDownload(prefix, execution, selection, scope, interactive, options, output);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        if (options.signal.aborted)
+            throw new CliError('canceled', 'Evidence download stopped. Repeat the same command and directory to resume retained partial files.', 130);
+        if (error instanceof Error && 'code' in error && error.code === 'ENOSPC')
+            throw new CliError('evidence_disk_capacity', 'There is not enough disk space. Free space, then resume the same evidence bundle. No existing file was replaced.');
+        throw new CliError('evidence_download_interrupted', 'Evidence download could not finish. Partial files are preserved. Repeat the same command and directory after restoring access or connectivity.');
+    }
+}
+export async function timelineCommand(prefix, execution, event, scope, options, output) {
+    if (options.into || options.approveDownload)
+        throw new CliError('arguments_invalid', 'Use evidence --into <directory> to download original files.', 2);
+    if (options.evidenceStep !== undefined)
+        throw new CliError('arguments_invalid', 'Use --step with evidence files. Inspect a driver step with timeline <driver-step-id>.', 2);
+    const selected = selectionFor(options, null);
+    if (event) {
+        if (options.page !== undefined || options.evidenceKind !== undefined || selected.attempt !== null || selected.from_at !== null || selected.to_at !== null)
+            throw new CliError('arguments_invalid', 'A driver-step detail does not accept list filters. Omit its ID to filter the timeline.', 2);
+        const id = identifier(event), row = await api(`${prefix}/timeline/driver/${id}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        if (!driverEventMatches(row, prefix, execution, id))
+            throw invalid();
+        output(row, `${terminalText(row.summary)}\n${row.inline_available ? JSON.stringify(row.content, null, 2) : 'Download the original evidence file to inspect this large observation.'}`);
+        return;
+    }
+    const query = new URLSearchParams({ page: options.page ?? '1', category: options.evidenceKind ?? '' });
+    for (const key of ['attempt', 'from_at', 'to_at']) {
+        const value = selected[key];
+        if (value !== null)
+            query.set(key, value);
+    }
+    const value = await api(`${prefix}/timeline?${query}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+    if (!timelineMatches(value, prefix, execution))
+        throw invalid();
+    const campaign = identifier(prefix.split('/')[5]);
+    output(value, [...value.results.map(row => `${row.observed_at === null ? row.recorded_at + ' retained' : new Date(row.observed_at * 1000).toISOString()} · ${row.category === 'service' ? 'service request' : row.category}${row.origin === 'customer_device' ? ' · local device' : ''}\n${terminalText(row.label)}\n${row.id}`
+            + (row.category === 'service' ? `\nInspect original receipt: firedrill report ${campaign} drill ${execution} requests ${row.id} --workspace ${scope.workspace}` : '')),
+        `Page ${value.page}; ${value.count.toLocaleString()} observations.`].join('\n\n'));
+}

package/dist/cli/src/execution-proposals.js

@@ -0,0 +1,36 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { isExecutionProposal, executionPlanMatches } from '../../contracts/director-execution.js';
+export async function executionProposal(context, id, signal) {
+    const key = identifier(id);
+    const value = await api(`${context.prefix}/execution-proposals/${key}`, { actor: context.owner, workspace: context.workspace, signal });
+    if (!isExecutionProposal(value) || value.id !== key || value.actor_id !== context.owner
+        || value.world_id !== context.world || value.plan_request_key !== key
+        || value.plan && !executionPlanMatches(value, { ...value.plan, current: true })) {
+        throw new CliError('execution_proposal_unconfirmed', 'This execution proposal could not be confirmed for this account and world. No work was started.');
+    }
+    return value;
+}
+export function executableProposal(value) {
+    if (!value.available || !value.current || !value.can_execute)
+        throw new CliError('execution_proposal_changed', 'The proposed inputs or execution permission changed. Inspect the current world. No replacement run was created.', 2);
+}
+export function proposalBasis(value, world, setup) {
+    executableProposal(value);
+    if (value.source_id !== world.basis.source_id || value.world_revision !== world.basis.world_revision
+        || value.configuration_revision !== world.basis.config_revision
+        || setup && (value.world_revision !== setup.world_revision || value.configuration_revision !== setup.configuration_revision
+            || value.selection_revision !== setup.selection_revision || value.evaluation_revision !== setup.evaluation_revision
+            || (value.plan ? !executionPlanMatches(value, value.plan) : (setup.plan?.id ?? null) !== value.previous_plan_id))) {
+        throw new CliError('execution_proposal_changed', 'Source, preparation, configuration, scenarios, criteria or the saved plan changed. Review a new proposal before executing.', 2);
+    }
+}
+export function executionProposalText(value) {
+    return `${value.title}\n${value.action === 'validate' ? 'Startup validation' : `${value.scenario_count} scenarios, ${value.repetitions} repetitions, ${value.planned_trials} drills; up to ${value.parallelism} concurrent; ${value.trial_seconds}s per drill`}.\n`
+        + `World revision ${value.world_revision}, configuration revision ${value.configuration_revision}. `
+        + `${value.location === 'choose' ? 'Choose execution location during review.' : `Proposed location: ${value.location}.`}\n`
+        + (value.campaign ? `Original simulation ${value.campaign.id}: ${value.campaign.state}. No new admission will be created.`
+            : value.validation ? `Original validation ${value.validation.id}: ${value.validation.state}. It will not be restarted.`
+                : 'Proposal only. Execution, real-account access, evidence sharing and simulation funding still require review.');
+}