@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/cli/command.js

@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Declaring a command. One `defineCommand` call is the whole description of a
+ * command: its name and help, its arguments and options, which combinations
+ * are valid, and `run`. The types `run` receives are inferred from the
+ * declarations, so no flag is ever described twice.
+ *
+ *     export const build = defineCommand({
+ *       name: 'build',
+ *       summary: 'Build the browser',
+ *       args: { paths: arg.list('Directories to rebuild') },
+ *       options: {
+ *         ui: opt.flag('Rebuild front-end files only'),
+ *         jobs: opt.integer('Parallel compile jobs', { short: 'j', min: 1 }),
+ *         ...lockOptions,
+ *       },
+ *       constraints: { exclusive: [['ui', 'paths']] },
+ *       run: async (ctx, args, opts) => { ... },  // opts.jobs: number | undefined
+ *     });
+ *
+ * An option's flag is its key in kebab case: `waitLock` is `--wait-lock`.
+ */
+import { resolve } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { COMMAND_WAIT_MS } from '../kernel/lock.js';
+/**
+ * A refusal of the command line itself: exit code 8, code `invalid-argument`.
+ *
+ * @param message - What is wrong with the invocation
+ * @param hint - What to pass instead
+ */
+export function usageError(message, hint) {
+    return new FireForgeError('invalid-argument', message, {
+        exitCode: ExitCode.INVALID_ARGUMENT,
+        ...(hint === undefined ? {} : { hint }),
+    });
+}
+function single(raw) {
+    return typeof raw === 'string' ? raw : Array.isArray(raw) ? raw.at(-1) : undefined;
+}
+function valueOption(description, config, defaults, parse) {
+    const notes = [
+        defaults.note,
+        config?.default === undefined ? undefined : `default ${String(config.default)}`,
+    ];
+    return {
+        description,
+        kind: 'value',
+        short: config?.short,
+        valueName: config?.valueName ?? defaults.valueName,
+        negatable: false,
+        env: config?.env,
+        hidden: config?.hidden ?? false,
+        note: notes.filter((note) => note !== undefined).join('; ') || undefined,
+        convert(raw, flag, cwd) {
+            const text = single(raw);
+            if (text !== undefined)
+                return parse(text, flag, cwd);
+            if (config?.required === true)
+                throw usageError(`${flag} is required`);
+            return config?.default;
+        },
+    };
+}
+function parseNumber(noun, accepts, bounds) {
+    const range = bounds.min !== undefined && bounds.max !== undefined
+        ? ` between ${bounds.min} and ${bounds.max}`
+        : bounds.min !== undefined
+            ? ` of at least ${bounds.min}`
+            : bounds.max !== undefined
+                ? ` of at most ${bounds.max}`
+                : '';
+    return (text, flag) => {
+        const value = text.trim() === '' ? NaN : Number(text);
+        const inRange = value >= (bounds.min ?? -Infinity) && value <= (bounds.max ?? Infinity);
+        if (!accepts(value) || !inRange) {
+            throw usageError(`${flag} must be ${noun}${range} (got "${text}")`);
+        }
+        return value;
+    };
+}
+function parseChoice(values) {
+    return (text, flag) => {
+        const match = values.find((value) => value === text);
+        if (match === undefined) {
+            throw usageError(`${flag} must be one of: ${values.join(', ')} (got "${text}")`);
+        }
+        return match;
+    };
+}
+/** Option declarations. */
+export const opt = {
+    /**
+     * A switch: present or absent. With `negatable`, `--no-<flag>` turns a
+     * default-on switch off, and help says the switch is on by default.
+     */
+    flag(description, config = {}) {
+        return {
+            description,
+            kind: 'flag',
+            short: config.short,
+            valueName: '',
+            negatable: config.negatable ?? false,
+            env: config.env,
+            hidden: config.hidden ?? false,
+            note: config.default === true ? 'on by default' : undefined,
+            convert: (raw) => (typeof raw === 'boolean' ? raw : (config.default ?? false)),
+        };
+    },
+    /** Free text. */
+    string(description, config) {
+        return valueOption(description, config, { valueName: 'value' }, (text) => text);
+    },
+    /** A whole number within optional bounds. */
+    integer(description, config) {
+        const parse = parseNumber('an integer', Number.isSafeInteger, config ?? {});
+        return valueOption(description, config, { valueName: 'n' }, parse);
+    },
+    /** A number within optional bounds. */
+    number(description, config) {
+        const parse = parseNumber('a number', Number.isFinite, config ?? {});
+        return valueOption(description, config, { valueName: 'n' }, parse);
+    },
+    /** One of a fixed set of words. */
+    enum(values, description, config) {
+        const defaults = { valueName: 'choice', note: `one of: ${values.join(', ')}` };
+        return valueOption(description, config, defaults, parseChoice(values));
+    },
+    /** A filesystem path, resolved against the working directory to an absolute path. */
+    path(description, config) {
+        return valueOption(description, config, { valueName: 'path' }, (text, _flag, cwd) => resolve(cwd, text));
+    },
+    /** A repeatable option: `--only a --only b` gives `['a', 'b']`. Absent gives `[]`. */
+    list(description, config = {}) {
+        return {
+            description,
+            kind: 'list',
+            short: config.short,
+            valueName: config.valueName ?? 'value',
+            negatable: false,
+            env: config.env,
+            hidden: config.hidden ?? false,
+            convert: (raw) => Array.isArray(raw) ? [...raw] : typeof raw === 'string' ? [raw] : [],
+        };
+    },
+};
+function positional(description, config, parse) {
+    return {
+        description,
+        required: config?.optional !== true,
+        variadic: false,
+        convert(raw, name, cwd) {
+            const text = single(raw);
+            return (text === undefined ? undefined : parse(text, name, cwd));
+        },
+    };
+}
+/** Positional argument declarations, in the order the keys are written. */
+export const arg = {
+    /** Free text. Required unless `optional`. */
+    string(description, config) {
+        return positional(description, config, (text) => text);
+    },
+    /** One of a fixed set of words. */
+    enum(values, description, config) {
+        return positional(description, config, parseChoice(values));
+    },
+    /** A filesystem path, resolved against the working directory to an absolute path. */
+    path(description, config) {
+        return positional(description, config, (text, _name, cwd) => resolve(cwd, text));
+    },
+    /** Every remaining argument, including whatever follows `--`. Must be declared last. */
+    list(description, config = {}) {
+        return {
+            description,
+            required: config.required ?? false,
+            variadic: true,
+            convert: (raw) => (Array.isArray(raw) ? [...raw] : []),
+        };
+    },
+};
+/**
+ * Declares a command.
+ *
+ * @param spec - See {@link CommandSpec}
+ */
+export function defineCommand(spec) {
+    const run = spec.run;
+    return {
+        name: spec.name,
+        summary: spec.summary,
+        description: spec.description,
+        group: spec.group,
+        args: spec.args ?? {},
+        options: spec.options ?? {},
+        constraints: spec.constraints ?? {},
+        json: spec.json ?? false,
+        verdict: spec.verdict ?? false,
+        hidden: spec.hidden ?? false,
+        subcommands: spec.subcommands ?? [],
+        run: run === undefined
+            ? undefined
+            : async (ctx, args, opts) => {
+                await run(ctx, args, opts);
+            },
+    };
+}
+/**
+ * The flag spelling of an option key: `waitLock` is `--wait-lock`.
+ *
+ * @param key - The key in the command's `options` or `args`
+ */
+export function kebabCase(key) {
+    return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+/**
+ * Converts and validates a parsed invocation: every value through its
+ * declaration, then the command's constraints.
+ *
+ * @param command - The command being run
+ * @param raw - What the parser collected
+ * @param cwd - Directory that relative paths resolve against
+ * @returns The typed `args` and `opts` for `run`
+ * @throws A usage error naming the flag or argument at fault
+ */
+export function resolveInvocation(command, raw, cwd) {
+    const args = {};
+    const opts = {};
+    const display = new Map();
+    const given = new Set();
+    for (const [key, spec] of Object.entries(command.args)) {
+        const name = `<${kebabCase(key)}>`;
+        display.set(key, name);
+        const value = spec.convert(raw.args[key], name, cwd);
+        args[key] = value;
+        if (Array.isArray(value) ? value.length > 0 : value !== undefined)
+            given.add(key);
+        else if (spec.required)
+            throw usageError(`${name} is required`);
+    }
+    for (const [key, spec] of Object.entries(command.options)) {
+        const flag = `--${kebabCase(key)}`;
+        display.set(key, flag);
+        opts[key] = spec.convert(raw.options[key], flag, cwd);
+        if (raw.given(key))
+            given.add(key);
+    }
+    const shown = (keys) => keys.map((key) => display.get(key) ?? key).join(', ');
+    for (const group of command.constraints.exclusive ?? []) {
+        const present = group.filter((key) => given.has(key));
+        if (present.length > 1)
+            throw usageError(`${shown(present)} cannot be used together`);
+    }
+    for (const group of command.constraints.oneOf ?? []) {
+        const present = group.filter((key) => given.has(key));
+        if (present.length === 0)
+            throw usageError(`One of ${shown(group)} is required`);
+        if (present.length > 1)
+            throw usageError(`${shown(present)} cannot be used together`);
+    }
+    for (const [key, needed] of Object.entries(command.constraints.requires ?? {})) {
+        const missing = (needed ?? []).filter((other) => !given.has(other));
+        if (given.has(key) && missing.length > 0) {
+            throw usageError(`${shown([key])} requires ${shown(missing)}`);
+        }
+    }
+    return { args, opts };
+}
+/** Options for a command that takes a lock another FireForge command may hold. */
+export const lockOptions = {
+    waitLock: opt.integer(`Wait up to this many seconds for what another FireForge command holds, with a progress ` +
+        `line each minute naming the holder; 0 does not wait (default: ${COMMAND_WAIT_MS / 1000})`, { valueName: 'seconds', min: 0, max: 86_400, env: 'FIREFORGE_WAIT_LOCK' }),
+};
+/**
+ * `--wait-lock` as the milliseconds the lock functions take.
+ *
+ * @param seconds - The option's value
+ * @returns The wait; {@link COMMAND_WAIT_MS} when the option was not given
+ */
+export function lockWaitMs(seconds) {
+    return seconds === undefined ? COMMAND_WAIT_MS : seconds * 1000;
+}
+/** Options for a command that asks before a destructive change. */
+export const confirmOptions = {
+    yes: opt.flag('Proceed without the confirmation prompt', { short: 'y' }),
+};

package/dist/src/cli/output.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * A command's result channel. stdout carries results and nothing else:
+ *
+ *  - Without `--json`: the lines a command writes, optionally ending in one
+ *    `FIREFORGE-VERDICT:` line that nothing may follow.
+ *  - With `--json`: exactly one JSON document carrying `schemaVersion`. On
+ *    failure that document is `{ schemaVersion, error, code }`.
+ *
+ * Progress and diagnostics go to stderr through `kernel/log.ts`.
+ */
+import { invariant } from '../kernel/errors.js';
+import { info } from '../kernel/log.js';
+import { onShutdown } from '../kernel/signals.js';
+/** Version of the `--json` envelope. Adding a key keeps it; removing or retyping one raises it. */
+const SCHEMA_VERSION = 1;
+/** Prefix of the line that ends the stdout of a pass/fail command. */
+const VERDICT_PREFIX = 'FIREFORGE-VERDICT:';
+/**
+ * Renders a verdict line. Whitespace and `%` inside a value are
+ * percent-encoded, so the line always splits on spaces into `key=value` pairs.
+ *
+ * @param pass - The judgement
+ * @param fields - Further `key=value` pairs, in insertion order
+ */
+export function formatVerdict(pass, fields = {}) {
+    const pairs = Object.entries(fields)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}=${String(value).replace(/[%\s]/g, encodeURIComponent)}`);
+    return [VERDICT_PREFIX, pass ? 'PASS' : 'FAIL', ...pairs].join(' ');
+}
+/** The {@link Out} of one command run, with the hooks the program needs around it. */
+export class Output {
+    stdout;
+    isJson;
+    jsonWritten = false;
+    sealed = false;
+    disarm;
+    constructor(stdout, isJson) {
+        this.stdout = stdout;
+        this.isJson = isJson;
+    }
+    line(text = '') {
+        this.write(`${text}\n`);
+    }
+    write(text) {
+        if (this.isJson)
+            return;
+        // After the verdict, stdout is closed to everything else.
+        if (this.sealed)
+            info(text.replace(/\n$/, ''));
+        else
+            this.stdout(text);
+    }
+    json(document) {
+        if (!this.isJson)
+            return;
+        invariant(!this.jsonWritten, 'a command writes one JSON document');
+        this.jsonWritten = true;
+        this.stdout(`${JSON.stringify({ schemaVersion: SCHEMA_VERSION, ...document })}\n`);
+    }
+    verdict(pass, fields = {}) {
+        if (this.isJson || this.sealed)
+            return;
+        this.sealed = true;
+        this.stdout(`${formatVerdict(pass, fields)}\n`);
+    }
+    /**
+     * Declares that this run ends in a verdict, so an interrupt writes
+     * `FAIL reason=killed signal=<signal>` before anything that can stall: a
+     * log tail must be able to tell "killed" from "still running".
+     */
+    expectVerdict() {
+        this.disarm = onShutdown('announce', (signal) => {
+            this.verdict(false, { reason: 'killed', signal });
+        });
+    }
+    /**
+     * Reports a failed run on stdout: the failure envelope under `--json`
+     * (unless the command already wrote its document), or a failing verdict
+     * for a run that owed one and had not written it.
+     */
+    fail(error) {
+        if (this.isJson && !this.jsonWritten) {
+            this.json({ error: error.message, code: error.code, hint: error.hint });
+        }
+        else if (this.disarm !== undefined) {
+            this.verdict(false, { reason: error.code });
+        }
+    }
+    /** Ends the run: stops listening for interrupts. */
+    close() {
+        this.disarm?.();
+        this.disarm = undefined;
+    }
+}

package/dist/src/cli/program.js

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Turns command declarations into a running program: parsing, help, the
+ * global flags, and the one place a thrown error becomes output and an exit
+ * code. Nothing here ends the process; {@link runProgram} returns the code.
+ */
+import { Argument, Command as Commander, CommanderError, Option } from 'commander';
+import { CancelledError, ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import * as log from '../kernel/log.js';
+import { kebabCase, resolveInvocation, usageError, } from './command.js';
+import { Output } from './output.js';
+/** The tokens before `--`: everything after it belongs to the program being run. */
+function ownTokens(argv) {
+    const end = argv.indexOf('--');
+    return end === -1 ? argv : argv.slice(0, end);
+}
+function optionFlags(key, spec) {
+    const long = `--${kebabCase(key)}`;
+    const short = spec.short === undefined ? '' : `-${spec.short}, `;
+    return spec.kind === 'flag' ? `${short}${long}` : `${short}${long} <${spec.valueName}>`;
+}
+/** Reads an option's value from its environment variable, in the form the parser would give it. */
+function fromEnvironment(spec, io) {
+    const value = spec.env === undefined ? undefined : io.env[spec.env]?.trim();
+    if (value === undefined || value === '')
+        return undefined;
+    return spec.kind === 'flag' ? !['0', 'false', 'no'].includes(value.toLowerCase()) : value;
+}
+function declare(parent, command, io, onInvoke) {
+    const node = parent.command(command.name, { hidden: command.hidden }).summary(command.summary);
+    node.description(command.description ?? command.summary);
+    if (command.group !== undefined)
+        node.helpGroup(`${command.group}:`);
+    for (const [key, spec] of Object.entries(command.args)) {
+        const name = `${kebabCase(key)}${spec.variadic ? '...' : ''}`;
+        // Every argument is optional to the parser: the declaration decides what
+        // is required, so the refusal is worded the same as every other one.
+        node.addArgument(new Argument(`[${name}]`, spec.description));
+    }
+    for (const [key, spec] of Object.entries(command.options)) {
+        const notes = [spec.note, spec.env === undefined ? undefined : `env: ${spec.env}`]
+            .filter((note) => note !== undefined)
+            .join('; ');
+        const option = new Option(optionFlags(key, spec), notes === '' ? spec.description : `${spec.description} (${notes})`);
+        if (spec.kind === 'list') {
+            option.argParser((value, previous) => [
+                ...(Array.isArray(previous) ? previous : []),
+                value,
+            ]);
+        }
+        if (spec.hidden)
+            option.hideHelp();
+        node.addOption(option);
+        if (spec.negatable) {
+            node.addOption(new Option(`--no-${kebabCase(key)}`, `Turn off --${kebabCase(key)}`));
+        }
+    }
+    for (const child of command.subcommands)
+        declare(node, child, io, onInvoke);
+    const run = command.run;
+    if (run === undefined) {
+        // A command group run without a subcommand answers with its help.
+        node.action(() => {
+            node.outputHelp();
+        });
+        return;
+    }
+    if (command.json)
+        node.option('--json', 'Write the result as one JSON document on stdout');
+    node.option('-v, --verbose', 'Show debug output');
+    node.action((...received) => {
+        const parsed = node.opts();
+        const options = {};
+        const given = new Set();
+        for (const [key, spec] of Object.entries(command.options)) {
+            const value = node.getOptionValueSource(key) === 'cli' ? parsed[key] : fromEnvironment(spec, io);
+            if (value === undefined)
+                continue;
+            options[key] = value;
+            given.add(key);
+        }
+        onInvoke({
+            command,
+            run,
+            json: parsed['json'] === true,
+            verbose: node.optsWithGlobals().verbose === true,
+            raw: {
+                args: Object.fromEntries(Object.keys(command.args).map((key, index) => [
+                    key,
+                    received[index],
+                ])),
+                options,
+                given: (key) => given.has(key),
+            },
+        });
+    });
+}
+function build(spec, io, onInvoke) {
+    const stderr = io.stderr ?? ((text) => process.stderr.write(text));
+    const program = new Commander(spec.name)
+        .description(spec.description)
+        // Without this the parser ends the process itself, with its own exit code.
+        .exitOverride()
+        .configureOutput({
+        writeOut: io.stdout,
+        writeErr: stderr,
+        // The parser's own refusals take the form every other failure has.
+        outputError: (text, write) => {
+            write(text.replace(/^error: /, `error[${usageError('').code}]: `));
+        },
+    })
+        // Root options are read only before the command name, so a command may
+        // declare a `--version` of its own.
+        .enablePositionalOptions()
+        .showSuggestionAfterError()
+        .option('-v, --verbose', 'Show debug output')
+        .option('-V, --version', 'Print the version');
+    for (const command of spec.commands)
+        declare(program, command, io, onInvoke);
+    return program;
+}
+async function reportError(error, spec) {
+    if (error instanceof CancelledError) {
+        log.info(error.message);
+        return { code: error.code, message: error.message, exitCode: error.exitCode };
+    }
+    if (!(error instanceof FireForgeError)) {
+        const unexpected = toError(error);
+        log.failure('unexpected-error', `Unexpected error: ${unexpected.message}`);
+        if (unexpected.stack !== undefined)
+            log.info(unexpected.stack);
+        return {
+            code: 'unexpected-error',
+            message: unexpected.message,
+            exitCode: ExitCode.GENERAL_ERROR,
+        };
+    }
+    if (error.exitCode === ExitCode.INTERNAL_ERROR) {
+        const issues = await spec.issuesUrl?.().catch(() => undefined);
+        log.failure(error.code, `Internal error: ${error.message}\n` +
+            'This is a bug in FireForge, not a problem with your project. It stopped at the first ' +
+            'inconsistency instead of continuing to write.' +
+            (issues === undefined ? '' : `\nPlease report it, with this output, at ${issues}`));
+        if (error.stack !== undefined)
+            log.info(error.stack);
+    }
+    else {
+        log.failure(error.code, error.message, error.hint);
+    }
+    // The underlying git output, errno or parse failure, for whoever asks.
+    let cause = error.cause;
+    for (let depth = 0; log.isVerbose() && cause !== undefined && cause !== null && depth < 8; depth++) {
+        const inner = toError(cause);
+        log.verbose(`Caused by: ${inner.stack ?? inner.message}`);
+        cause = inner.cause;
+    }
+    return {
+        code: error.code,
+        message: error.message,
+        exitCode: error.exitCode,
+        ...(error.hint === undefined ? {} : { hint: error.hint }),
+    };
+}
+async function execute(invocation, spec, io, out) {
+    const { command, run, raw } = invocation;
+    try {
+        const { args, opts } = resolveInvocation(command, raw, io.cwd);
+        const context = { cwd: io.cwd, env: io.env, out, interactive: io.interactive };
+        if (command.verdict)
+            out.expectVerdict();
+        await run(context, args, opts);
+        return ExitCode.SUCCESS;
+    }
+    catch (error) {
+        const failure = await reportError(error, spec);
+        out.fail(failure);
+        return failure.exitCode;
+    }
+    finally {
+        out.close();
+    }
+}
+/**
+ * Runs one invocation of the program.
+ *
+ * @param spec - The program: its name, version and commands
+ * @param io - Arguments, working directory, environment and output sinks
+ * @returns The exit code. The caller ends the process
+ */
+export async function runProgram(spec, io) {
+    const own = ownTokens(io.argv);
+    const logConfig = io.stderr === undefined ? {} : { write: io.stderr };
+    const previousLog = log.configureLog(logConfig);
+    try {
+        const hasCommand = own.some((token) => !token.startsWith('-'));
+        if (!hasCommand && (own.includes('--version') || own.includes('-V'))) {
+            io.stdout(`${await spec.version()}\n`);
+            return ExitCode.SUCCESS;
+        }
+        let invocation;
+        const program = build(spec, io, (next) => {
+            invocation = next;
+        });
+        try {
+            await program.parseAsync([...io.argv], { from: 'user' });
+        }
+        catch (error) {
+            if (!(error instanceof CommanderError))
+                throw error;
+            // Help, and a command group run without a subcommand, are answers, not errors.
+            if (error.exitCode === 0 || error.code === 'commander.help')
+                return ExitCode.SUCCESS;
+            // The parser has already written its message to stderr. A command line
+            // that did not parse cannot say whether --json was an option's value, so
+            // the token decides: a script asking for JSON gets the failure as JSON.
+            const usage = usageError(error.message.replace(/^error:\s*/, ''));
+            new Output(io.stdout, own.includes('--json')).fail({
+                message: usage.message,
+                code: usage.code,
+            });
+            return usage.exitCode;
+        }
+        if (invocation === undefined)
+            return ExitCode.SUCCESS;
+        log.configureLog({ ...logConfig, verbose: invocation.verbose });
+        return await execute(invocation, spec, io, new Output(io.stdout, invocation.json));
+    }
+    finally {
+        log.configureLog(previousLog);
+    }
+}

package/dist/src/cli/stdio.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Process-level stdio concerns for the entry point: a reader that closes the
+ * pipe early, and output still queued when the process is about to exit.
+ */
+let brokenPipeHandled = false;
+/**
+ * Treats a closed output pipe (`fireforge status | head`) as a clean end
+ * instead of an unhandled stream error. Any other stream error is rethrown.
+ */
+export function handleBrokenPipe() {
+    if (brokenPipeHandled)
+        return;
+    brokenPipeHandled = true;
+    const onError = (error) => {
+        if (error.code !== 'EPIPE')
+            throw error;
+        process.exitCode = 0;
+    };
+    process.stdout.on('error', onError);
+    process.stderr.on('error', onError);
+}
+function flushed(stream) {
+    return stream.destroyed || stream.writableFinished || stream.writableLength === 0;
+}
+function drain(stream, timeoutMs) {
+    if (flushed(stream))
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const settle = () => {
+            clearTimeout(timer);
+            stream.off('drain', onDrain);
+            stream.off('error', settle);
+            stream.off('close', settle);
+            resolve();
+        };
+        const onDrain = () => {
+            if (flushed(stream))
+                settle();
+        };
+        const timer = setTimeout(settle, timeoutMs);
+        stream.on('drain', onDrain);
+        // A destroyed pipe can never drain and must not stall the exit behind it.
+        stream.on('error', settle);
+        stream.on('close', settle);
+    });
+}
+/**
+ * Waits, at most `timeoutMs`, for stdout and stderr to hand their queued
+ * writes to the operating system. `process.exit` discards whatever a pipe
+ * still has queued, which truncates a large `--json` document mid-object.
+ * Never rejects.
+ *
+ * @param timeoutMs - The bound; a stalled reader cannot wedge the exit
+ * @param streams - The streams to wait for
+ */
+export async function drainStdio(timeoutMs, streams = [process.stdout, process.stderr]) {
+    await Promise.all(streams.map((stream) => drain(stream, timeoutMs)));
+}