@williamthorsen/nmr 0.43.0 → 0.45.0

package/dist/esm/runCli.js

@@ -1,12 +1,14 @@
 import path from 'node:path';
-import { describeInvalidOutputStyle, formatGlyphLine, readPackageVersion, reportError, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
+import { describeInvalidOutputStyle, formatGlyphLine, reportError, resolveSelfVersion, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
 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 { resolveContext } from "./context.js";
+import { enterChain } from "./entry-chain.js";
 import { NMR_GLYPHS } from "./glyphs.js";
 import { generateHelp } from "./help.js";
 import { resolveConfigPath } from "./helpers/config-path.js";
 import { deriveExcerpt } from "./helpers/deriveExcerpt.js";
+import { escapeControlCharacters } from "./helpers/escapeControlCharacters.js";
 import { readFilterSelection } from "./helpers/filter-selection.js";
 import { findClosestName } from "./helpers/findClosestName.js";
 import { isHookName } from "./helpers/hook-name.js";
@@ -18,27 +20,38 @@ import { assembleReplay } from "./replay-assembly.js";
 import { readReportFormatEnv, REPORT_FORMAT_ENV_VAR, resolveReportFormat } from "./report-format.js";
 import { applyDevBinToSteps, buildRootRegistry, buildWorkspaceRegistry, expandScript, findChainedSelfReference, readPackageJsonScripts, resolveScript, } from "./resolver.js";
 import { resolveChannel, runSteps } from "./runner.js";
-import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, renderChain } from "./steps.js";
+import { composeNmrStep, dropRecursiveSteps, findNmrCrossing, quoteToken, readSoleNmrCommand, renderChain, } from "./steps.js";
 import { UserError } from "./UserError.js";
 import { COMMAND_VERBOSITY_ENV_VAR, readVerbosityEnv, resolveVerbosity, } from "./verbosity.js";
 import { writeVerdict } from "./verdict.js";
 import { readWorkspacePackageNames, resolveWorkspace } from "./workspace.js";
-const VERSION = readPackageVersion(import.meta.url);
+const VERSION = resolveSelfVersion(import.meta.url);
 const CROSSING_CONSEQUENCE = "so nmr handles the nested run's output as a tool's.";
 const RECURSIVE_REJECTION = '-R/--recursive did not match any workspace:';
 const LIST_CEILING = 10;
-const NAMED_ESCAPES = new Map([
-    ['\n', String.raw `\n`],
-    ['\r', String.raw `\r`],
-    ['\t', String.raw `\t`],
-]);
 export const RUN_IF_PRESENT_ENV_VAR = 'NMR_RUN_IF_PRESENT';
 export async function runCli(options) {
-    const { args, env, stdout, stderr } = options;
+    const established = await establishInvocation(options);
+    if (established.settled) {
+        return { exitCode: established.result.exitCode };
+    }
+    const invocation = established.value;
+    const planned = await planRun(invocation);
+    const { exitCode, isUnknownCommand = false } = planned.settled ? planned.result : await executePlan(planned.value);
+    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(options.env)) {
+        const hint = formatMisplacedFlagHint(options.args, invocation.parsedArgs.passthrough, invocation.styles.stderr);
+        if (hint !== undefined) {
+            options.stderr.write(`${hint}\n`);
+        }
+    }
+    return { exitCode };
+}
+async function establishInvocation(options) {
+    const { args, cwd, env, stdout, stderr } = options;
     const parseResult = parseArgs(args);
     if (!parseResult.ok) {
         reportError(parseResult.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const { parsedArgs } = parseResult;
     const presentationRead = readPresentation({
@@ -49,24 +62,12 @@ export async function runCli(options) {
     });
     if (!presentationRead.ok) {
         reportError(presentationRead.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const { styles } = presentationRead;
-    const { exitCode, isUnknownCommand = false } = await runInvocation({ ...options, parsedArgs, presentationRead });
-    if (exitCode !== 0 && !isUnknownCommand && isTopLevelInvocation(env)) {
-        const hint = formatMisplacedFlagHint(args, parsedArgs.passthrough, styles.stderr);
-        if (hint !== undefined) {
-            stderr.write(`${hint}\n`);
-        }
-    }
-    return { exitCode };
-}
-async function runInvocation(options) {
-    const { cwd, env, parsedArgs, presentationRead, stderr, stdout } = options;
-    const { styles } = presentationRead;
     if (parsedArgs.shouldShowVersion) {
         stdout.write(`${VERSION}\n`);
-        return { exitCode: 0 };
+        return { settled: true, result: { exitCode: 0 } };
     }
     const context = await resolveContext(cwd);
     const format = resolveReportFormat({ envFormat: presentationRead.format, hasJsonFlag: parsedArgs.shouldEmitJson });
@@ -77,15 +78,33 @@ async function runInvocation(options) {
         output: context.config.output,
         hasQuietFlag: parsedArgs.quiet,
     });
-    const quiet = verbosity === 'quiet';
     const shouldUseRoot = parsedArgs.isWorkspaceRoot || context.isRoot;
     const anchorDir = shouldUseRoot ? context.monorepoRoot : (context.packageDir ?? context.monorepoRoot);
     if (parsedArgs.shouldShowHelp || !parsedArgs.command) {
-        stdout.write(`${generateHelp(context.config, anchorDir, shouldUseRoot)}\n`);
-        return { exitCode: 0 };
+        stdout.write(`${generateHelp(context.config, context.monorepoRoot, anchorDir, shouldUseRoot)}\n`);
+        return { settled: true, result: { exitCode: 0 } };
     }
-    const { command } = parsedArgs;
-    const scope = path.basename(anchorDir);
+    return {
+        settled: false,
+        value: {
+            anchorDir,
+            command: parsedArgs.command,
+            context,
+            env,
+            format,
+            parsedArgs,
+            scope: path.basename(anchorDir),
+            shouldUseRoot,
+            stderr,
+            stdout,
+            styles,
+            verbosity,
+        },
+    };
+}
+async function planRun(invocation) {
+    const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
+    const quiet = invocation.verbosity === 'quiet';
     const snapshot = openGate({
         command,
         config: context.config,
@@ -99,13 +118,13 @@ async function runInvocation(options) {
     const runId = resolveRunId(env);
     const childEnv = buildChildEnv({
         env,
-        format,
+        format: invocation.format,
         shouldBypassCache,
         passthrough: parsedArgs.passthrough,
         runId,
         snapshot,
         styles,
-        verbosity,
+        verbosity: invocation.verbosity,
     });
     const runOptions = {
         quiet,
@@ -116,9 +135,14 @@ async function runInvocation(options) {
     const delegation = composeDelegation({ childEnv, command, parsedArgs });
     if (delegation !== undefined) {
         const result = await runDelegation({ context, delegation, parsedArgs, runOptions, stderr });
-        return { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) };
-    }
-    const registry = shouldUseRoot ? buildRootRegistry(context.config) : buildWorkspaceRegistry(context.config);
+        return {
+            settled: true,
+            result: { ...result, isUnknownCommand: result.exitCode !== 0 && !isDefinedInAnyScope(command, context) },
+        };
+    }
+    const registry = invocation.shouldUseRoot
+        ? buildRootRegistry(context.config, context.monorepoRoot)
+        : buildWorkspaceRegistry(context.config);
     assertNoSelfReference({
         anchorDir,
         command,
@@ -130,24 +154,50 @@ async function runInvocation(options) {
     const resolvedScript = resolveScript(command, registry, anchorDir, parsedArgs.isWorkspaceRoot);
     if (!resolvedScript) {
         if (env[RUN_IF_PRESENT_ENV_VAR] === '1') {
-            return { exitCode: 0 };
+            return { settled: true, result: { exitCode: 0 } };
         }
         reportError(`Unknown command: ${command}`, stderr);
-        return { exitCode: 1, isUnknownCommand: true };
+        return { settled: true, result: { exitCode: 1, isUnknownCommand: true } };
+    }
+    const entryRunOptions = parsedArgs.shouldPrintLog
+        ? runOptions
+        : {
+            ...runOptions,
+            env: enterChain({ anchorDir, command, env: childEnv, monorepoRoot: context.monorepoRoot }),
+        };
+    const chain = assembleChain({ invocation, registry, resolvedScript, snapshot });
+    if (chain.settled) {
+        return chain;
     }
+    return {
+        settled: false,
+        value: {
+            ...chain.value,
+            invocation,
+            overrideNotice: formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, styles.stdout),
+            runId,
+            runOptions: entryRunOptions,
+            shouldBypassCache,
+            snapshot,
+        },
+    };
+}
+function assembleChain(options) {
+    const { invocation, registry, resolvedScript, snapshot } = options;
+    const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
     const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
     const resolvedCommand = renderChain(runnableSteps);
     const noOpReason = findNoOpReason(resolvedCommand, isEmptiedByWorkspace);
     if (noOpReason !== undefined && !parsedArgs.shouldPrintLog) {
-        reportVerdict({ command, scope, outcome: 'no-op', reason: noOpReason }, stdout, format, styles.stdout);
-        return { exitCode: 0 };
+        reportVerdict({ command, scope: invocation.scope, outcome: 'no-op', reason: noOpReason }, stdout, invocation.format, styles.stdout);
+        return { settled: true, result: { exitCode: 0 } };
     }
     const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
     const substitutedCommand = renderChain(substitutedSteps);
     const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
     if (!bindResult.ok) {
         reportError(bindResult.error, stderr);
-        return { exitCode: 1 };
+        return { settled: true, result: { exitCode: 1 } };
     }
     const mainSteps = bindResult.steps;
     const isHookInvocation = isHookName(command);
@@ -162,7 +212,7 @@ async function runInvocation(options) {
         monorepoRoot: context.monorepoRoot,
         registry,
         resolvedScript,
-        shouldUseRoot,
+        shouldUseRoot: invocation.shouldUseRoot,
         stderr,
         style: styles.stderr,
     });
@@ -176,40 +226,14 @@ async function runInvocation(options) {
         stderr,
         substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
     });
+    return { settled: false, value: { commandString: fullCommand, key, ownSteps: mainSteps, steps: fullSteps } };
+}
+async function executePlan(plan) {
+    const { command, format, parsedArgs, scope, stdout, styles } = plan.invocation;
     if (parsedArgs.shouldPrintLog) {
-        return reportRecording({
-            anchorDir,
-            command,
-            commandString: fullCommand,
-            config: context.config,
-            env,
-            key,
-            monorepoRoot: context.monorepoRoot,
-            scope,
-            snapshot,
-            stderr,
-            stdout,
-            styles,
-        });
+        return reportRecording(plan);
     }
-    const { exitCode, outcome } = await runGated({
-        anchorDir,
-        command,
-        commandString: fullCommand,
-        config: context.config,
-        steps: fullSteps,
-        env,
-        key,
-        monorepoRoot: context.monorepoRoot,
-        overrideNotice: formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, styles.stdout),
-        ownSteps: mainSteps,
-        runId,
-        runOptions,
-        shouldBypassCache,
-        snapshot,
-        stderr,
-        stdout,
-    });
+    const { exitCode, outcome } = await runGated(plan);
     reportVerdict({ command, scope, ...outcome }, stdout, format, styles.stdout);
     return { exitCode };
 }
@@ -323,7 +347,8 @@ function describeCrossingRemedy(options) {
             };
         case 'package':
             return {
-                remedy: formatPackageRemedy({ configSite, crossingStep, isWorkspaceRoot, key: origin.key, registry }),
+                remedy: formatInlineRemedy({ crossingStep, file: origin.file, isWorkspaceRoot, key: origin.key, registry }) ??
+                    formatPackageRemedy({ configSite, crossingStep, isWorkspaceRoot, key: origin.key, registry }),
                 subject: `${path.relative(monorepoRoot, origin.file)}: \`scripts.${origin.key}\``,
             };
         default: {
@@ -348,12 +373,29 @@ function describeOrigin(origin, config, shouldUseRoot) {
         ? { tier: 'config', field, key: origin.key }
         : { tier: 'default', key: origin.key };
 }
-function escapeControlCharacters(text) {
-    let escapedText = text;
-    for (const [char, escape] of NAMED_ESCAPES) {
-        escapedText = escapedText.split(char).join(escape);
+function formatInlineRemedy(options) {
+    const { crossingStep, file, isWorkspaceRoot, key, registry } = options;
+    const name = readSoleNmrCommand(crossingStep);
+    if (name === undefined || name === key) {
+        return undefined;
+    }
+    const scripts = readPackageJsonScripts(path.dirname(file));
+    const value = scripts !== undefined && Object.hasOwn(scripts, name) ? scripts[name]?.trim() : undefined;
+    if (value === undefined || ['', ':'].includes(value)) {
+        return undefined;
     }
-    return escapedText;
+    if (findNmrCrossing([{ kind: 'opaque', command: value }]) !== undefined) {
+        return undefined;
+    }
+    const anchorDir = path.dirname(file);
+    if (!isHookName(name) &&
+        [`${name}:pre`, `${name}:post`].some((hook) => hasRunnableHook(hook, registry, anchorDir, isWorkspaceRoot))) {
+        return undefined;
+    }
+    const inlinedValue = escapeControlCharacters(value);
+    return Object.hasOwn(registry, name)
+        ? `Replace the value with \`${inlinedValue}\`, and keep \`${name}\`, which overrides nmr's own.`
+        : `Replace the value with \`${inlinedValue}\` and delete \`${name}\`, the script that it names.`;
 }
 function formatNmrCrossingWarning(options) {
     const { remedy, subject } = describeCrossingRemedy(options);
@@ -633,26 +675,27 @@ function parseArgs(args) {
     const error = findArgError(parsedArgs);
     return error === undefined ? { ok: true, parsedArgs } : { ok: false, error };
 }
-async function reportRecording(options) {
-    const { command, config, scope, styles } = options;
+async function reportRecording(plan) {
+    const { anchorDir, command, context, env, scope, stderr, stdout, styles } = plan.invocation;
+    const { config, monorepoRoot } = context;
     const lookup = await resolveRecording({
-        anchorDir: options.anchorDir,
+        anchorDir,
         command,
         currentIdentity: {
-            commandString: options.commandString,
+            commandString: plan.commandString,
             nmrVersion: VERSION,
             nodeVersion: CURRENT_RUNTIME.nodeVersion,
-            treeHash: options.snapshot?.hash,
+            treeHash: plan.snapshot?.hash,
         },
         isCacheable: isCacheableCommand(config.checkCache, command),
-        key: options.key,
-        monorepoRoot: options.monorepoRoot,
+        key: plan.key,
+        monorepoRoot,
     });
     if (!lookup.ok) {
-        options.stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
-        return { exitCode: options.env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
+        stderr.write(`${renderRefusal({ command, refusal: lookup.refusal, scope, style: styles.stderr })}\n`);
+        return { exitCode: env[RUN_IF_PRESENT_ENV_VAR] === '1' ? 0 : 1 };
     }
-    options.stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
+    stdout.write(renderRecording({ command, recording: lookup.recording, scope, style: styles.stdout }));
     return { exitCode: 0 };
 }
 function readPresentation(options) {
@@ -812,12 +855,14 @@ async function runDelegation(options) {
     const step = shouldWithholdInput ? { ...delegation.step, shouldWithholdInput } : delegation.step;
     return runSteps([step], context.monorepoRoot, { ...runOptions, env: delegation.env });
 }
-async function runGated(options) {
-    const { anchorDir, command, commandString, env, key, monorepoRoot, snapshot, stderr, stdout } = options;
-    const quiet = options.runOptions.quiet === true;
+async function runGated(plan) {
+    const { commandString, key, snapshot } = plan;
+    const { anchorDir, command, context, env, stderr, stdout } = plan.invocation;
+    const { config, monorepoRoot } = context;
+    const quiet = plan.runOptions.quiet === true;
     const gate = key !== undefined && snapshot !== undefined
         ? {
-            buildOutputBefore: await readBuildOutputState(monorepoRoot, options.config),
+            buildOutputBefore: await readBuildOutputState(monorepoRoot, config),
             key,
             retentionKey: computeRetentionKey({
                 channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
@@ -827,7 +872,7 @@ async function runGated(options) {
             snapshot,
         }
         : undefined;
-    if (gate !== undefined && !options.shouldBypassCache) {
+    if (gate !== undefined && !plan.shouldBypassCache) {
         const recalledPass = await lookUpRecordedPass({
             anchorDir,
             buildOutput: gate.buildOutputBefore,
@@ -841,16 +886,16 @@ async function runGated(options) {
         if (recalledPass !== undefined) {
             const { entry, ...recall } = recalledPass;
             if (recall.replay !== undefined) {
-                await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: options.runId, stderr });
+                await certifyRetention({ anchorDir, command, entry, env, monorepoRoot, runId: plan.runId, stderr });
             }
             return { exitCode: 0, outcome: { outcome: 'recalled', ...recall } };
         }
     }
-    if (options.overrideNotice !== undefined) {
-        stdout.write(options.overrideNotice);
+    if (plan.overrideNotice !== undefined) {
+        stdout.write(plan.overrideNotice);
     }
     const startedAtMs = Date.now();
-    const { exitCode, retainedOutput } = await runSteps(options.steps, anchorDir, options.runOptions);
+    const { exitCode, retainedOutput } = await runSteps(plan.steps, anchorDir, plan.runOptions);
     const durationMs = Date.now() - startedAtMs;
     if (exitCode === 0 && gate !== undefined) {
         await recordPass({
@@ -858,15 +903,15 @@ async function runGated(options) {
             buildOutputBefore: gate.buildOutputBefore,
             command,
             commandString,
-            config: options.config,
+            config,
             durationMs,
             env,
             key: gate.key,
             monorepoRoot,
-            ownSteps: options.ownSteps,
+            ownSteps: plan.ownSteps,
             retainedOutput,
             retentionKey: gate.retentionKey,
-            runId: options.runId,
+            runId: plan.runId,
             snapshot: gate.snapshot,
             stderr,
         });
@@ -894,7 +939,7 @@ function formatMisplacedFlagHint(args, passthrough, style) {
         `nmr reads its flags only before the command: \`${correctedTokens.map(quoteToken).join(' ')}\``);
 }
 function isDefinedInAnyScope(command, context) {
-    const registries = [buildRootRegistry(context.config), buildWorkspaceRegistry(context.config)];
+    const registries = [buildRootRegistry(context.config, context.monorepoRoot), buildWorkspaceRegistry(context.config)];
     if (registries.some((registry) => Object.hasOwn(registry, command))) {
         return true;
     }

package/dist/esm/runner.d.ts

@@ -75,6 +75,13 @@ export declare function resolveInheritedChannel(stream: Writable): OutputChannel
  * makes a signal to nmr end the run: The steps after it are never reached, whereas a shell would have gone on
  * running them unsupervised.
  *
+ * A background step is started and left running while the steps after it run. Its output is recorded rather
+ * than streamed, and printed whole at the first step boundary after it ends, so that it never interleaves with
+ * another step's. A failing foreground step still ends the sequence, but the list waits for every background step
+ * that it started and reports the first failure among them when the foreground did not fail. While a background
+ * step runs, a SIGINT or SIGTERM to nmr is forwarded to every running child, so that a signal sent to nmr alone
+ * still ends the children.
+ *
  * Returns a bounded copy of what the list's own commands wrote, so that a caller can retain it. Only opaque
  * steps contribute: A structural step is another nmr process reporting for the subtree beneath it, and its
  * output is that subtree's to account for.

package/dist/esm/runner.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
 import { createBoundedBuffer } from "./helpers/createBoundedBuffer.js";
+import { createOutputRecorder } from "./helpers/createOutputRecorder.js";
 const SIGNAL_EXIT_BASE = 128;
 const PIPE_DRAIN_GRACE_MS = 2_000;
 export function resolveChannel(stream, quiet) {
@@ -22,26 +23,81 @@ export async function runSteps(steps, cwd, options) {
     };
     const parts = [];
     let isCaptureWhole = true;
-    for (const step of steps) {
-        const result = await runStep(step, cwd, resolvedOptions);
-        if (step.kind === 'opaque') {
-            if (result.stderr === undefined || result.stdout === undefined) {
-                isCaptureWhole = false;
+    const backgroundRuns = [];
+    const runningChildren = new Set();
+    let receivedSignal;
+    let foregroundExitCode = 0;
+    function forwardSignal(signal) {
+        receivedSignal ??= signal;
+        for (const child of runningChildren)
+            child.kill(signal);
+    }
+    function launch(step, launchOptions) {
+        const started = startStep(step, cwd, launchOptions);
+        runningChildren.add(started.child);
+        void started.result.finally(() => runningChildren.delete(started.child));
+        return started;
+    }
+    function flushEndedBackgroundRuns() {
+        for (const run of backgroundRuns) {
+            if (run.result === undefined || run.isFlushed)
+                continue;
+            run.recorder.replay({ stderr: resolvedOptions.stderr, stdout: resolvedOptions.stdout });
+            run.isFlushed = true;
+        }
+    }
+    try {
+        for (const step of steps) {
+            if (receivedSignal !== undefined) {
+                foregroundExitCode = describeSignalExitCode(receivedSignal);
+                break;
             }
-            else {
-                parts.push({ stderr: result.stderr, stdout: result.stdout });
+            if (step.kind === 'structural' && step.shouldRunInBackground === true) {
+                if (backgroundRuns.length === 0) {
+                    process.on('SIGINT', forwardSignal);
+                    process.on('SIGTERM', forwardSignal);
+                }
+                backgroundRuns.push(startBackgroundRun(step, resolvedOptions, launch));
+                continue;
+            }
+            const result = await launch(step, resolvedOptions).result;
+            flushEndedBackgroundRuns();
+            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) {
+                foregroundExitCode = result.exitCode;
+                if (result.outcome === 'signaled') {
+                    for (const run of backgroundRuns)
+                        run.child.kill(result.signal);
+                }
+                break;
             }
         }
-        if (result.exitCode !== 0) {
-            return { exitCode: result.exitCode, ...composeRetainedOutput(parts, isCaptureWhole) };
+        for (const run of backgroundRuns) {
+            await run.settled;
+            flushEndedBackgroundRuns();
         }
     }
-    return { exitCode: 0, ...composeRetainedOutput(parts, isCaptureWhole) };
+    finally {
+        process.off('SIGINT', forwardSignal);
+        process.off('SIGTERM', forwardSignal);
+    }
+    const exitCode = selectExitCode(foregroundExitCode, receivedSignal, backgroundRuns);
+    return { exitCode, ...composeRetainedOutput(parts, isCaptureWhole) };
 }
 export async function runCommand(command, cwd, options) {
     return runSpawned({ args: [], file: command, input: 'inherit', shouldUseShell: true }, cwd, options);
 }
-async function runSpawned({ args, file, input, shouldUseShell }, cwd, options) {
+function runSpawned(spec, cwd, options) {
+    return startSpawned(spec, cwd, options).result;
+}
+function startSpawned({ args, file, input, shouldUseShell }, cwd, options) {
     const quiet = options.quiet === true;
     const stdout = options.stdout ?? process.stdout;
     const stderr = options.stderr ?? process.stderr;
@@ -52,6 +108,9 @@ async function runSpawned({ args, file, input, shouldUseShell }, cwd, options) {
         cwd,
         env,
     });
+    return { child, result: collectResult(child, { quiet, stderr, stdout }) };
+}
+async function collectResult(child, { quiet, stderr, stdout }) {
     const stdoutCapture = child.stdout === null ? undefined : captureStream(child.stdout, quiet ? undefined : stdout);
     const stderrCapture = child.stderr === null ? undefined : captureStream(child.stderr, quiet ? undefined : stderr);
     const commandCompletion = await awaitCompletion(child, () => {
@@ -75,17 +134,17 @@ async function runSpawned({ args, file, input, shouldUseShell }, cwd, options) {
     }
     return result;
 }
-function runStep(step, cwd, options) {
+function startStep(step, cwd, options) {
     const { quiet, stderr, stdout } = options;
     if (step.kind === 'opaque') {
-        return runSpawned({ args: [], file: step.command, input: 'inherit', shouldUseShell: true }, cwd, {
+        return startSpawned({ args: [], file: step.command, input: 'inherit', shouldUseShell: true }, cwd, {
             ...options,
             channels: { stderr: resolveChannel(stderr, quiet), stdout: resolveChannel(stdout, quiet) },
         });
     }
     const [file, ...args] = step.argv;
     const input = step.shouldWithholdInput === true ? 'ignore' : 'inherit';
-    return runSpawned({ args, file, input, shouldUseShell: false }, cwd, {
+    return startSpawned({ args, file, input, shouldUseShell: false }, cwd, {
         ...options,
         quiet: false,
         channels: { stderr: resolveInheritedChannel(stderr), stdout: resolveInheritedChannel(stdout) },
@@ -157,18 +216,49 @@ function awaitCompletion(child, stopReading) {
         });
     });
 }
+function buildBackgroundEnv(options) {
+    const env = options.env ?? process.env;
+    const shouldForceColor = isTerminal(options.stdout) && (env['NO_COLOR'] ?? '') === '' && env['FORCE_COLOR'] === undefined;
+    return shouldForceColor ? { ...env, FORCE_COLOR: '1' } : env;
+}
 function describeExit(code, signal) {
     if (signal !== null) {
-        return { outcome: 'signaled', exitCode: SIGNAL_EXIT_BASE + os.constants.signals[signal], signal };
+        return { outcome: 'signaled', exitCode: describeSignalExitCode(signal), signal };
     }
     return { outcome: 'exited', exitCode: code ?? 1 };
 }
+function describeSignalExitCode(signal) {
+    return SIGNAL_EXIT_BASE + os.constants.signals[signal];
+}
 function hasDescriptor(stream) {
     return 'fd' in stream && typeof stream.fd === 'number';
 }
 function isTerminal(stream) {
     return 'isTTY' in stream && stream.isTTY === true && hasDescriptor(stream);
 }
+async function recordResult(run, result) {
+    run.result = await result;
+}
+function selectExitCode(foregroundExitCode, receivedSignal, backgroundRuns) {
+    if (foregroundExitCode !== 0)
+        return foregroundExitCode;
+    if (receivedSignal !== undefined)
+        return describeSignalExitCode(receivedSignal);
+    return backgroundRuns.find((run) => run.result !== undefined && run.result.exitCode !== 0)?.result?.exitCode ?? 0;
+}
+function startBackgroundRun(step, options, launch) {
+    const recorder = createOutputRecorder();
+    const started = launch({ ...step, shouldWithholdInput: true }, { ...options, env: buildBackgroundEnv(options), stderr: recorder.stderr, stdout: recorder.stdout });
+    const run = {
+        child: started.child,
+        isFlushed: false,
+        recorder,
+        result: undefined,
+        settled: Promise.resolve(),
+    };
+    run.settled = recordResult(run, started.result);
+    return run;
+}
 function writeBuffer(buffer, destination) {
     if (buffer !== undefined && buffer.length > 0)
         destination.write(buffer);