@williamthorsen/nmr 0.30.0 → 0.32.0

package/dist/esm/runCli.js

@@ -1,14 +1,23 @@
 import path from 'node:path';
 import { readPackageVersion, reportError } from '@williamthorsen/nmr-core';
-import { computeCacheKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, formatSkipLine, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, resolveCacheableCommands, resolveTreeSnapshot, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { certifyRetention, computeCacheKey, computeRetentionKey, CURRENT_RUNTIME, encodeTreeSnapshot, findStaleBuildOutput, formatMisplacedNoCacheWarning, isCacheableCommand, NO_CACHE_ENV_VAR, readBuildOutputState, readCheckCacheEntry, recordTranscript, resolveRunId, resolveTreeSnapshot, RUN_ID_ENV_VAR, TREE_SNAPSHOT_ENV_VAR, writeCheckCacheEntry, writeDebugNote, } from "./check-cache.js";
+import { resolveConfigPath } from "./config.js";
 import { resolveContext } from "./context.js";
 import { generateHelp } from "./help.js";
+import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
 import { isHookName } from "./helpers/hook-name.js";
-import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
-import { runSteps } from "./runner.js";
-import { composeNmrStep, findShelledNmrStep, renderChain } from "./steps.js";
-import { COMMAND_VERBOSITY_ENV_VAR, resolveVerbosity } from "./verbosity.js";
+import { composeTranscript } from "./helpers/transcript.js";
+import { renderRecording, renderRefusal, resolveRecording } from "./recording.js";
+import { assembleReplay } from "./replay-assembly.js";
+import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
+import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, resolveScript, } from "./resolver.js";
+import { resolveChannel, runSteps } from "./runner.js";
+import { composeNmrStep, findNmrCrossing, renderChain } from "./steps.js";
+import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity } from "./verbosity.js";
+import { writeVerdict } from "./verdict.js";
 const VERSION = readPackageVersion(import.meta.url);
+const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
     const { args, cwd, env, stdout, stderr } = options;
@@ -18,17 +27,25 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { parsed } = parseResult;
-    const verbosity = resolveVerbosity(env, parsed.quiet);
-    if (!verbosity.ok) {
-        reportError(verbosity.error, stderr);
+    const inherited = readPresentationEnv(env);
+    if (!inherited.ok) {
+        reportError(inherited.error, stderr);
         return { exitCode: 1 };
     }
     if (parsed.version) {
         stdout.write(`${VERSION}\n`);
         return { exitCode: 0 };
     }
-    const quiet = verbosity.verbosity === 'quiet';
     const context = await resolveContext(cwd);
+    const format = resolveReportFormat({ envFormat: inherited.format, jsonFlag: parsed.json });
+    const verbosity = resolveReportingVerbosity({
+        env,
+        envVerbosity: inherited.verbosity,
+        format,
+        output: context.config.output,
+        quietFlag: parsed.quiet,
+    });
+    const quiet = verbosity === 'quiet';
     const useRoot = parsed.workspaceRoot || context.isRoot;
     const anchorDir = useRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
     if (parsed.help || !parsed.command) {
@@ -36,6 +53,7 @@ export async function runCli(options) {
         return { exitCode: 0 };
     }
     const { command } = parsed;
+    const scope = path.basename(anchorDir);
     const snapshot = openGate({
         command,
         config: context.config,
@@ -45,21 +63,25 @@ export async function runCli(options) {
         stderr,
     });
     const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
-    const childEnv = buildChildEnv(env, snapshot, noCache, verbosity.verbosity);
+    const runId = resolveRunId(env);
+    const childEnv = buildChildEnv({
+        env,
+        format,
+        noCache,
+        passthrough: parsed.passthrough,
+        runId,
+        snapshot,
+        verbosity,
+    });
     const runOptions = {
         quiet,
         stdout,
         stderr,
         env: childEnv,
     };
-    if (parsed.filter) {
-        const delegate = composeDelegate(['--filter', parsed.filter], command, parsed.passthrough);
-        return runSteps([delegate], context.monorepoRoot, runOptions);
-    }
-    if (parsed.recursive) {
-        const delegateEnv = { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' };
-        const delegate = composeDelegate(['--recursive'], command, parsed.passthrough);
-        return runSteps([delegate], context.monorepoRoot, { ...runOptions, env: delegateEnv });
+    const delegation = composeDelegation({ childEnv, command, parsed });
+    if (delegation !== undefined) {
+        return runSteps([delegation.step], context.monorepoRoot, { ...runOptions, env: delegation.env });
     }
     const registry = useRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
     const resolved = resolveScript(command, registry, anchorDir, parsed.workspaceRoot);
@@ -71,22 +93,34 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const resolvedCommand = renderChain(resolved.steps);
-    const skipExitCode = handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout);
-    if (skipExitCode !== undefined) {
-        return { exitCode: skipExitCode };
+    const noOpReason = findNoOpReason(resolvedCommand);
+    if (noOpReason !== undefined && !parsed.log) {
+        reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format);
+        return { exitCode: 0 };
     }
     const substitutedSteps = applyDevBinToSteps(resolved.steps, context.config.devBin, context.monorepoRoot);
     const substitutedCommand = renderChain(substitutedSteps);
-    const mainSteps = appendPassthrough(substitutedSteps, parsed.passthrough);
+    const bound = bindPassthrough(substitutedSteps, parsed.passthrough, command);
+    if (!bound.ok) {
+        reportError(bound.error, stderr);
+        return { exitCode: 1 };
+    }
+    const mainSteps = bound.steps;
     const isHookInvocation = isHookName(command);
     const fullSteps = isHookInvocation
         ? mainSteps
         : wrapWithHooks(command, mainSteps, registry, anchorDir, parsed.workspaceRoot);
     const fullCommand = renderChain(fullSteps);
-    const shelledStep = findShelledNmrStep(fullSteps);
-    if (shelledStep !== undefined) {
-        stderr.write(`${formatShelledNmrWarning(command, shelledStep)}\n`);
-    }
+    reportNmrCrossing({
+        config: context.config,
+        isReading: parsed.log,
+        monorepoRoot: context.monorepoRoot,
+        registry,
+        resolved,
+        stderr,
+        useRoot,
+        workspaceRoot: parsed.workspaceRoot,
+    });
     const key = resolveCacheKey({
         anchorDir,
         command,
@@ -97,7 +131,22 @@ export async function runCli(options) {
         stderr,
         substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
-    const exitCode = await runGated({
+    if (parsed.log) {
+        return reportRecording({
+            anchorDir,
+            command,
+            commandString: fullCommand,
+            config: context.config,
+            env,
+            key,
+            monorepoRoot: context.monorepoRoot,
+            scope,
+            snapshot,
+            stderr,
+            stdout,
+        });
+    }
+    const { exitCode, outcome } = await runGated({
         anchorDir,
         command,
         commandString: fullCommand,
@@ -108,58 +157,165 @@ export async function runCli(options) {
         monorepoRoot: context.monorepoRoot,
         noCache,
         overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet),
-        quiet,
+        ownSteps: mainSteps,
+        runId,
         runOptions,
         snapshot,
         stderr,
         stdout,
     });
+    reportVerdict({ command, scope, ...outcome }, stdout, format);
     return { exitCode };
 }
-function buildChildEnv(env, snapshot, noCache, verbosity) {
+function buildChildEnv(options) {
+    const { env, format, noCache, passthrough, runId, snapshot, verbosity } = options;
+    const bypassesCache = noCache || passthrough.length > 0;
     return {
         ...env,
         ...(snapshot !== undefined && { [TREE_SNAPSHOT_ENV_VAR]: encodeTreeSnapshot(snapshot) }),
-        ...(noCache && { [NO_CACHE_ENV_VAR]: '1' }),
+        ...(bypassesCache && { [NO_CACHE_ENV_VAR]: '1' }),
         [COMMAND_VERBOSITY_ENV_VAR]: verbosity,
+        [REPORT_FORMAT_ENV_VAR]: format,
+        [RUN_ID_ENV_VAR]: runId,
     };
 }
-function appendPassthrough(steps, passthrough) {
-    const last = steps.at(-1);
-    if (passthrough.length === 0 || last === undefined) {
-        return steps;
-    }
-    const bound = last.kind === 'structural'
-        ? { kind: 'structural', argv: [...last.argv, ...passthrough] }
-        : { kind: 'opaque', command: `${last.command} ${passthrough.map(shellQuote).join(' ')}` };
-    return [...steps.slice(0, -1), bound];
+function acceptsArgs(step) {
+    return step.kind === 'opaque' || step.declinesArgs !== true;
+}
+function bindPassthrough(steps, passthrough, command) {
+    if (passthrough.length === 0) {
+        return { ok: true, steps };
+    }
+    if (!steps.some(acceptsArgs)) {
+        return { ok: false, error: formatUnroutableArgsError(command) };
+    }
+    const boundSteps = steps.map((step) => {
+        if (!acceptsArgs(step)) {
+            return step;
+        }
+        return step.kind === 'structural'
+            ? { ...step, argv: [...step.argv, ...passthrough] }
+            : { kind: 'opaque', command: `${step.command} ${passthrough.map(shellQuote).join(' ')}` };
+    });
+    return { ok: true, steps: boundSteps };
+}
+function formatUnroutableArgsError(command) {
+    return (`\`${command}\` takes no trailing arguments: every step of its chain declines them. ` +
+        'Running it unnarrowed is not what the arguments asked for, so nothing ran.');
+}
+function composeDelegation(options) {
+    const { childEnv, command, parsed } = options;
+    let scope;
+    let runIfPresent = parsed.log;
+    if (parsed.filter) {
+        scope = ['--filter', parsed.filter];
+    }
+    else if (parsed.recursive) {
+        scope = ['--recursive'];
+        runIfPresent = true;
+    }
+    if (scope === undefined) {
+        return undefined;
+    }
+    const flags = parsed.log ? ['--log'] : [];
+    return {
+        env: runIfPresent ? { ...childEnv, [RUN_IF_PRESENT_ENV_VAR]: '1' } : childEnv,
+        step: {
+            kind: 'structural',
+            argv: ['pnpm', ...scope, 'exec', 'nmr', ...flags, command, ...parsed.passthrough],
+        },
+    };
+}
+async function composeRetention(options) {
+    const { anchorDir, command, key, retained, runId } = options;
+    if (retained !== undefined) {
+        const excerpt = deriveExcerpt(retained.stdout.toString('utf8')) ?? deriveExcerpt(retained.stderr.toString('utf8'));
+        if (excerpt === undefined) {
+            return undefined;
+        }
+        return { key, replay: [{ command, excerpt, scope: path.basename(anchorDir) }], runId };
+    }
+    const replay = await assembleReplay({
+        anchorDir,
+        monorepoRoot: options.monorepoRoot,
+        runId,
+        steps: options.steps,
+        treeHash: options.treeHash,
+    });
+    return replay.length === 0 ? undefined : { key, replay, runId };
+}
+function describeCrossingRemedy(options) {
+    const { crossing, monorepoRoot, origin, registry, workspaceRoot } = options;
+    const configSite = path.relative(monorepoRoot, resolveConfigPath(monorepoRoot));
+    switch (origin.tier) {
+        case 'default':
+            return {
+                remedy: 'A built-in default reaching nmr through a shell is an nmr defect: please report it.',
+                subject: `nmr built-in \`${origin.key}\``,
+            };
+        case 'config':
+            return {
+                remedy: `Write the nmr steps as a step list, and move any others to a \`${origin.key}:pre\` or ` +
+                    `\`${origin.key}:post\` script.`,
+                subject: `${configSite}: \`${origin.field}.${origin.key}\``,
+            };
+        case 'package':
+            return {
+                remedy: formatPackageRemedy({ configSite, crossing, key: origin.key, registry, workspaceRoot }),
+                subject: `${path.relative(monorepoRoot, origin.file)}: \`scripts.${origin.key}\``,
+            };
+        default: {
+            const unhandled = origin;
+            throw new Error(`Unhandled script origin: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function describeOrigin(origin, config, useRoot) {
+    if (origin.tier === 'package') {
+        return origin;
+    }
+    const field = useRoot ? 'rootScripts' : 'workspaceScripts';
+    const configScripts = config[field];
+    return configScripts !== undefined && Object.hasOwn(configScripts, origin.key)
+        ? { tier: 'config', field, key: origin.key }
+        : { tier: 'default', key: origin.key };
 }
-function composeDelegate(scope, command, passthrough) {
-    return { kind: 'structural', argv: ['pnpm', ...scope, 'exec', 'nmr', command, ...passthrough] };
+function formatNmrCrossingWarning(options) {
+    const { remedy, subject } = describeCrossingRemedy(options);
+    return `⚠️ ${subject} reaches nmr through a shell (\`${options.crossing}\`), ${CROSSING_CONSEQUENCE} ${remedy}`;
 }
 function formatOverrideNotice(resolved, registry, command, anchorDir, quiet) {
     const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
-    if (quiet || resolved.source !== 'package' || registryEntry === undefined) {
+    if (quiet || resolved.origin.tier !== 'package' || registryEntry === undefined) {
         return undefined;
     }
     return `📦 ${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}\n`;
 }
-function formatShelledNmrWarning(command, step) {
-    return (`⚠️ ${command}: \`${step}\` runs nmr behind a shell, so nmr handles its output as a tool's rather than a ` +
-        `nested run's. A step list in \`.config/nmr.config.ts\` avoids it.`);
+function formatPackageRemedy(options) {
+    const { configSite, crossing, key, registry, workspaceRoot } = options;
+    const registryEntry = Object.hasOwn(registry, key) ? registry[key] : undefined;
+    if (registryEntry === undefined) {
+        return (`A \`package.json\` script holds no step list: define \`${key}\` in \`${configSite}\` and move the ` +
+            `package-specific steps to a \`${key}:pre\` or \`${key}:post\` script.`);
+    }
+    const registryChain = renderChain(expandScript(registryEntry, workspaceRoot));
+    if (registryChain === crossing) {
+        return `Delete the entry: nmr's own \`${key}\` already runs \`${registryChain}\`.`;
+    }
+    return `Delete the entry and move the steps it adds to a \`${key}:pre\` or \`${key}:post\` script.`;
+}
+function findArgError(parsed) {
+    if (parsed.log && parsed.command === undefined && !parsed.help && !parsed.version) {
+        return '--log requires a command name: `nmr --log <command>`';
+    }
+    return undefined;
 }
-function handleSkipMessage(resolvedCommand, anchorDir, quiet, stdout) {
+function findNoOpReason(resolvedCommand) {
     if (resolvedCommand === '') {
-        if (!quiet) {
-            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is defined but empty. Skipping.\n`);
-        }
-        return 0;
+        return 'empty-override';
     }
     if (resolvedCommand === ':') {
-        if (!quiet) {
-            stdout.write(`⛔ ${path.basename(anchorDir)}: Override script is a no-op. Skipping.\n`);
-        }
-        return 0;
+        return 'noop-override';
     }
     return undefined;
 }
@@ -191,20 +347,23 @@ async function lookUpRecordedPass(options) {
         writeDebugNote(`running ${command}: ${stale}'s build output came from a different tree`, env, stderr);
         return undefined;
     }
-    return formatSkipLine(command, entry, Date.now());
+    return {
+        ageMs: Math.max(0, Date.now() - Date.parse(entry.recordedAt)),
+        entry,
+        savedMs: entry.durationMs,
+        ...(entry.retention?.key === options.retentionKey && { replay: entry.retention.replay }),
+    };
 }
 function openGate(options) {
     const { command, config, env, monorepoRoot, passthrough, stderr } = options;
-    const covered = !isHookName(command) &&
-        config.checkCache?.enabled !== false &&
-        resolveCacheableCommands(config.checkCache).has(command);
-    if (!covered) {
+    if (!isCacheableCommand(config.checkCache, command)) {
         return undefined;
     }
     if (passthrough.includes('--no-cache')) {
         stderr.write(`${formatMisplacedNoCacheWarning(command)}\n`);
     }
     if (passthrough.length > 0) {
+        writeDebugNote(`gate disabled: ${command} was passed arguments`, env, stderr);
         return undefined;
     }
     const snapshot = resolveTreeSnapshot({ monorepoRoot, env });
@@ -216,6 +375,8 @@ function openGate(options) {
 }
 function parseArgs(args) {
     const parsed = {
+        json: false,
+        log: false,
         noCache: false,
         quiet: false,
         recursive: false,
@@ -264,6 +425,16 @@ function parseArgs(args) {
             i++;
             continue;
         }
+        if (arg === '--json') {
+            parsed.json = true;
+            i++;
+            continue;
+        }
+        if (arg === '--log') {
+            parsed.log = true;
+            i++;
+            continue;
+        }
         if (arg === '--no-cache') {
             parsed.noCache = true;
             i++;
@@ -273,7 +444,65 @@ function parseArgs(args) {
         parsed.passthrough = args.slice(i + 1);
         break;
     }
-    return { ok: true, parsed };
+    const error = findArgError(parsed);
+    return error === undefined ? { ok: true, parsed } : { ok: false, error };
+}
+async function reportRecording(options) {
+    const { command, config, scope } = options;
+    const lookup = await resolveRecording({
+        anchorDir: options.anchorDir,
+        command,
+        current: {
+            commandString: options.commandString,
+            nmrVersion: VERSION,
+            nodeVersion: CURRENT_RUNTIME.nodeVersion,
+            treeHash: options.snapshot?.hash,
+        },
+        isCacheable: isCacheableCommand(config.checkCache, command),
+        key: options.key,
+        monorepoRoot: options.monorepoRoot,
+    });
+    if (!lookup.ok) {
+        options.stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope })}\n`);
+        return { exitCode: options.env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
+    }
+    options.stdout.write(renderRecording({ command, recording: lookup.recording, scope }));
+    return { exitCode: 0 };
+}
+function readPresentationEnv(env) {
+    const verbosity = readVerbosityEnv(env);
+    if (!verbosity.ok) {
+        return verbosity;
+    }
+    const format = readReportFormatEnv(env);
+    if (!format.ok) {
+        return format;
+    }
+    return { ok: true, format: format.format, verbosity: verbosity.verbosity };
+}
+function reportNmrCrossing(options) {
+    const crossing = findNmrCrossing(options.resolved.steps);
+    if (options.isReading || crossing === undefined) {
+        return;
+    }
+    const warning = formatNmrCrossingWarning({
+        crossing,
+        monorepoRoot: options.monorepoRoot,
+        origin: describeOrigin(options.resolved.origin, options.config, options.useRoot),
+        registry: options.registry,
+        workspaceRoot: options.workspaceRoot,
+    });
+    options.stderr.write(`${warning}\n`);
+}
+function reportVerdict(verdict, stdout, format) {
+    if (isHookName(verdict.command)) {
+        return;
+    }
+    writeVerdict(verdict, stdout, format);
+}
+function resolveReportingVerbosity(options) {
+    const { format, ...ladder } = options;
+    return format === 'json' ? 'quiet' : resolveVerbosity(ladder);
 }
 async function recordPass(options) {
     const { anchorDir, command, env, monorepoRoot, snapshot, stderr } = options;
@@ -297,11 +526,22 @@ async function recordPass(options) {
         writeDebugNote(`not recording ${command}: ${changed}'s build output changed while it ran`, env, stderr);
         return;
     }
+    const retention = await composeRetention({
+        anchorDir,
+        command,
+        key: options.retentionKey,
+        monorepoRoot,
+        retained: options.retained,
+        runId: options.runId,
+        steps: options.ownSteps,
+        treeHash: snapshot.hash,
+    });
+    const ref = { anchorDir, command, monorepoRoot };
+    const transcript = options.retained === undefined ? undefined : composeTranscript(options.retained);
     try {
+        await recordTranscript(ref, transcript);
         await writeCheckCacheEntry({
-            anchorDir,
-            command,
-            monorepoRoot,
+            ...ref,
             entry: {
                 key: options.key,
                 treeHash: snapshot.hash,
@@ -312,12 +552,17 @@ async function recordPass(options) {
                 durationMs: options.durationMs,
                 recordedAt: new Date().toISOString(),
                 buildDigests: output.digests,
+                ...(retention !== undefined && { retention }),
             },
         });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        writeDebugNote(`could not record ${command}: ${message}`, env, stderr);
+        try {
+            await recordTranscript(ref, undefined);
+        }
+        catch {
+        }
+        writeDebugNote(`could not record ${command}: ${describeError(error)}`, env, stderr);
     }
 }
 function resolveCacheKey(options) {
@@ -346,31 +591,44 @@ function resolveCacheKey(options) {
 }
 async function runGated(options) {
     const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
+    const quiet = options.runOptions.quiet === true;
     const gate = key !== undefined && snapshot !== undefined
-        ? { buildOutputBefore: await readBuildOutputState(monorepoRoot, options.config), key, snapshot }
+        ? {
+            buildOutputBefore: await readBuildOutputState(monorepoRoot, options.config),
+            key,
+            retentionKey: computeRetentionKey({
+                channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
+                env,
+                passKey: key,
+            }),
+            snapshot,
+        }
         : undefined;
     if (gate !== undefined && !options.noCache) {
-        const skipLine = await lookUpRecordedPass({
+        const recalled = await lookUpRecordedPass({
             anchorDir,
             buildOutput: gate.buildOutputBefore,
             command,
             env,
             key: gate.key,
             monorepoRoot,
+            retentionKey: gate.retentionKey,
             stderr,
         });
-        if (skipLine !== undefined) {
-            if (!options.quiet) {
-                stdout.write(`${skipLine}\n`);
+        if (recalled !== undefined) {
+            const { entry, ...recall } = recalled;
+            if (recall.replay !== undefined) {
+                await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: options.runId, stderr });
             }
-            return 0;
+            return { exitCode: 0, outcome: { outcome: 'recalled', ...recall } };
         }
     }
     if (options.overrideNotice !== undefined) {
         stdout.write(options.overrideNotice);
     }
     const startedAt = Date.now();
-    const { exitCode } = await runSteps(options.steps, anchorDir, options.runOptions);
+    const { exitCode, retained } = await runSteps(options.steps, anchorDir, options.runOptions);
+    const durationMs = Date.now() - startedAt;
     if (exitCode === 0 && gate !== undefined) {
         await recordPass({
             anchorDir,
@@ -378,15 +636,22 @@ async function runGated(options) {
             command,
             commandString,
             config: options.config,
-            durationMs: Date.now() - startedAt,
+            durationMs,
             env,
             key: gate.key,
             monorepoRoot,
+            ownSteps: options.ownSteps,
+            retained,
+            retentionKey: gate.retentionKey,
+            runId: options.runId,
             snapshot: gate.snapshot,
             stderr,
         });
     }
-    return exitCode;
+    return {
+        exitCode,
+        outcome: exitCode === 0 ? { outcome: 'passed', durationMs } : { outcome: 'failed', durationMs, exitCode },
+    };
 }
 function shellQuote(arg) {
     return "'" + arg.replace(/'/g, String.raw `'\''`) + "'";

package/dist/esm/runner.d.ts

@@ -13,6 +13,14 @@ export interface RunCommandOptions {
     env?: NodeJS.ProcessEnv;
 }
 export type RunStepsOptions = Omit<RunCommandOptions, 'channels'>;
+export interface RetainedOutput {
+    stderr: Buffer;
+    stdout: Buffer;
+}
+export interface RunStepsResult {
+    exitCode: number;
+    retained?: RetainedOutput;
+}
 type CommandCompletion = {
     outcome: 'exited';
     exitCode: number;
@@ -31,8 +39,6 @@ export type RunCommandResult = CommandCompletion & {
 };
 export declare function resolveChannel(stream: Writable, quiet: boolean): OutputChannel;
 export declare function resolveInheritedChannel(stream: Writable): OutputChannel;
-export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<{
-    exitCode: number;
-}>;
+export declare function runSteps(steps: readonly Step[], cwd: string | undefined, options: RunStepsOptions): Promise<RunStepsResult>;
 export declare function runCommand(command: string, cwd: string | undefined, options: RunCommandOptions): Promise<RunCommandResult>;
 export {};

package/dist/esm/runner.js

@@ -20,13 +20,23 @@ export async function runSteps(steps, cwd, options) {
         stdout: options.stdout ?? process.stdout,
         stderr: options.stderr ?? process.stderr,
     };
+    const parts = [];
+    let isCaptureWhole = true;
     for (const step of steps) {
-        const { exitCode } = await runStep(step, cwd, resolved);
-        if (exitCode !== 0) {
-            return { exitCode };
+        const result = await runStep(step, cwd, resolved);
+        if (step.kind === 'opaque') {
+            if (result.stderr === undefined || result.stdout === undefined) {
+                isCaptureWhole = false;
+            }
+            else {
+                parts.push({ stderr: result.stderr, stdout: result.stdout });
+            }
+        }
+        if (result.exitCode !== 0) {
+            return { exitCode: result.exitCode, ...composeRetainedOutput(parts, isCaptureWhole) };
         }
     }
-    return { exitCode: 0 };
+    return { exitCode: 0, ...composeRetainedOutput(parts, isCaptureWhole) };
 }
 export async function runCommand(command, cwd, options) {
     return runSpawned({ args: [], file: command, useShell: true }, cwd, options);
@@ -80,6 +90,17 @@ function runStep(step, cwd, options) {
         channels: { stderr: resolveInheritedChannel(stderr), stdout: resolveInheritedChannel(stdout) },
     });
 }
+function composeRetainedOutput(parts, isCaptureWhole) {
+    if (!isCaptureWhole || parts.length === 0) {
+        return {};
+    }
+    return {
+        retained: {
+            stderr: Buffer.concat(parts.map((part) => part.stderr)),
+            stdout: Buffer.concat(parts.map((part) => part.stdout)),
+        },
+    };
+}
 function captureStream(source, destination) {
     const retained = createBoundedBuffer();
     let isComplete = true;

package/dist/esm/scripts.d.ts

@@ -1,2 +1,2 @@
-export type { ScriptRegistry, ScriptValue } from './default-scripts.js';
+export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
 export { getDefaultRootScripts, getDefaultWorkspaceScripts } from './resolve-scripts.js';