@williamthorsen/nmr 0.29.0 → 0.31.0

package/dist/esm/runCli.js

@@ -1,12 +1,24 @@
 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 { applyDevBin, buildRootRegistry, buildWorkspaceRegistry, resolveScript } from "./resolver.js";
-import { runCommand } from "./runner.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;
     const parseResult = parseArgs(args);
@@ -15,11 +27,25 @@ export async function runCli(options) {
         return { exitCode: 1 };
     }
     const { parsed } = parseResult;
+    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 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) {
@@ -27,7 +53,7 @@ export async function runCli(options) {
         return { exitCode: 0 };
     }
     const { command } = parsed;
-    const passthrough = parsed.passthrough.length > 0 ? ' ' + parsed.passthrough.map(shellQuote).join(' ') : '';
+    const scope = path.basename(anchorDir);
     const snapshot = openGate({
         command,
         config: context.config,
@@ -37,38 +63,64 @@ export async function runCli(options) {
         stderr,
     });
     const noCache = parsed.noCache || env[NO_CACHE_ENV_VAR] === '1';
-    const childEnv = buildChildEnv(env, snapshot, noCache);
-    const runOptions = { quiet: parsed.quiet, stdout, stderr, env: childEnv };
-    if (parsed.filter) {
-        const delegateCmd = `pnpm --filter ${shellQuote(parsed.filter)} exec nmr ${command}${passthrough}`;
-        const { exitCode } = await runCommand(delegateCmd, context.monorepoRoot, runOptions);
-        return { exitCode };
-    }
-    if (parsed.recursive) {
-        const delegateEnv = { ...childEnv, NMR_RUN_IF_PRESENT: '1' };
-        const delegateCmd = `pnpm --recursive exec nmr ${command}${passthrough}`;
-        const { exitCode } = await runCommand(delegateCmd, context.monorepoRoot, { ...runOptions, env: delegateEnv });
-        return { exitCode };
+    const runId = resolveRunId(env);
+    const childEnv = buildChildEnv({
+        env,
+        format,
+        noCache,
+        passthrough: parsed.passthrough,
+        runId,
+        snapshot,
+        verbosity,
+    });
+    const runOptions = {
+        quiet,
+        stdout,
+        stderr,
+        env: childEnv,
+    };
+    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);
     if (!resolved) {
-        if (env['NMR_RUN_IF_PRESENT'] === '1') {
+        if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
             return { exitCode: 0 };
         }
         reportError(`Unknown command: ${command}`, stderr);
         return { exitCode: 1 };
     }
-    const skipExitCode = handleSkipMessage(resolved.command, anchorDir, parsed.quiet, stdout);
-    if (skipExitCode !== undefined) {
-        return { exitCode: skipExitCode };
+    const resolvedCommand = renderChain(resolved.steps);
+    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 bound = bindPassthrough(substitutedSteps, parsed.passthrough, command);
+    if (!bound.ok) {
+        reportError(bound.error, stderr);
+        return { exitCode: 1 };
     }
-    const substitutedCommand = applyDevBin(resolved.command, context.config.devBin, context.monorepoRoot);
-    const mainCommand = substitutedCommand + passthrough;
+    const mainSteps = bound.steps;
     const isHookInvocation = isHookName(command);
-    const fullCommand = isHookInvocation
-        ? mainCommand
-        : wrapWithHooks(command, mainCommand, registry, anchorDir, parsed.workspaceRoot);
+    const fullSteps = isHookInvocation
+        ? mainSteps
+        : wrapWithHooks(command, mainSteps, registry, anchorDir, parsed.workspaceRoot);
+    const fullCommand = renderChain(fullSteps);
+    reportNmrCrossing({
+        config: context.config,
+        isReading: parsed.log,
+        monorepoRoot: context.monorepoRoot,
+        registry,
+        resolved,
+        stderr,
+        useRoot,
+        workspaceRoot: parsed.workspaceRoot,
+    });
     const key = resolveCacheKey({
         anchorDir,
         command,
@@ -77,52 +129,193 @@ export async function runCli(options) {
         monorepoRoot: context.monorepoRoot,
         snapshot,
         stderr,
-        substitution: substitutedCommand === resolved.command ? undefined : substitutedCommand,
+        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,
         config: context.config,
+        steps: fullSteps,
         env,
         key,
         monorepoRoot: context.monorepoRoot,
         noCache,
-        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, parsed.quiet),
-        quiet: parsed.quiet,
+        overrideNotice: formatOverrideNotice(resolved, registry, command, anchorDir, quiet),
+        ownSteps: mainSteps,
+        runId,
         runOptions,
         snapshot,
         stderr,
         stdout,
     });
+    reportVerdict({ command, scope, ...outcome }, stdout, format);
     return { exitCode };
 }
-function buildChildEnv(env, snapshot, noCache) {
+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 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 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: ${resolved.command}\n`;
+    return `📦 ${path.basename(anchorDir)}: Using override script: ${renderChain(resolved.steps)}\n`;
+}
+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;
 }
@@ -130,7 +323,8 @@ function hasRunnableHook(hookName, registry, anchorDir, workspaceRoot) {
     const resolved = resolveScript(hookName, registry, anchorDir, workspaceRoot);
     if (!resolved)
         return false;
-    return resolved.command !== '' && resolved.command !== ':';
+    const chain = renderChain(resolved.steps);
+    return chain !== '' && chain !== ':';
 }
 async function lookUpRecordedPass(options) {
     const { anchorDir, buildOutput, command, env, key, monorepoRoot, stderr } = options;
@@ -153,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 });
@@ -178,6 +375,8 @@ function openGate(options) {
 }
 function parseArgs(args) {
     const parsed = {
+        json: false,
+        log: false,
         noCache: false,
         quiet: false,
         recursive: false,
@@ -226,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++;
@@ -235,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;
@@ -259,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,
@@ -274,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) {
@@ -308,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 runCommand(commandString, 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,
@@ -340,28 +636,34 @@ 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 `'\''`) + "'";
 }
-function wrapWithHooks(command, mainCommand, registry, anchorDir, workspaceRoot) {
-    const segments = [];
-    const flag = workspaceRoot ? '-w ' : '';
+function wrapWithHooks(command, mainSteps, registry, anchorDir, workspaceRoot) {
+    const steps = [];
     if (hasRunnableHook(`${command}:pre`, registry, anchorDir, workspaceRoot)) {
-        segments.push(`nmr ${flag}${command}:pre`);
+        steps.push(composeNmrStep(`${command}:pre`, workspaceRoot));
     }
-    segments.push(mainCommand);
+    steps.push(...mainSteps);
     if (hasRunnableHook(`${command}:post`, registry, anchorDir, workspaceRoot)) {
-        segments.push(`nmr ${flag}${command}:post`);
+        steps.push(composeNmrStep(`${command}:post`, workspaceRoot));
     }
-    return segments.join(' && ');
+    return steps;
 }

package/dist/esm/runner.d.ts

@@ -1,10 +1,26 @@
 import type { Writable } from 'node:stream';
+import type { Step } from './steps.js';
+export type OutputChannel = number | 'pipe';
+export interface OutputChannels {
+    stderr: OutputChannel;
+    stdout: OutputChannel;
+}
 export interface RunCommandOptions {
+    channels: OutputChannels;
     quiet?: boolean;
     stdout?: Writable;
     stderr?: Writable;
     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;
@@ -21,5 +37,8 @@ export type RunCommandResult = CommandCompletion & {
     stdout: Buffer | undefined;
     stderr: Buffer | undefined;
 };
-export declare function runCommand(command: string, cwd?: string, options?: RunCommandOptions): Promise<RunCommandResult>;
+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<RunStepsResult>;
+export declare function runCommand(command: string, cwd: string | undefined, options: RunCommandOptions): Promise<RunCommandResult>;
 export {};