rman 2.10.1 → 2.11.0

package/services/run.service.js

@@ -4,9 +4,10 @@ import { inspect } from 'node:util';
 import colors from 'ansi-colors';
 import { tokenize } from 'fast-tokenizer';
 import { Task } from 'power-tasks';
+import { LOG_LEVELS, Logger, resolveRootLogLevel } from '../core/classes/logger.js';
+import { PanelReporter, PlainReporter } from '../core/classes/run-reporters.js';
 import { Service } from '../core/classes/service.js';
 import { exec } from '../utils/exec.js';
-import { LOG_LEVELS, Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { ProgressPanel } from '../utils/progress-panel.js';
 import { runBin } from '../utils/run-bin.js';
@@ -44,7 +45,7 @@ export class RunService extends Service {
         }
         const concurrency = resolveConcurrency(options.parallel, resolveNumber(undefined, repository.rootPackage, script, 'concurrency', os.cpus().length));
         const progress = resolveBool(options.progress, repository.rootPackage, script, 'progress', true);
-        const panel = new ProgressPanel(`RUN ${script}`, !!process.stdout.isTTY && progress);
+        const panel = new ProgressPanel(`RUN ${script}`, !!process.stdout.isTTY && progress && !repository.app.logSink?.json);
         /** Shared across all `if: changed[ = hash]` evaluations so the same reference is only `git`-queried once. */
         const ifStatusCache = new Map();
         /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
@@ -123,11 +124,11 @@ export class RunService extends Service {
              *  repository the root *is* the one package, and is covered. */
             const definedSomewhere = repository.getPackages().some(pkg => getScriptSteps(pkg, script).length > 0);
             if (definedSomewhere) {
-                console.log(colors.gray(`Nothing to run - every package was filtered out of "${script}".`));
+                this.say('info', `Nothing to run - every package was filtered out of "${script}".`);
                 return;
             }
             const message = `No package defines a "${script}" script.`;
-            console.log(colors.red(message));
+            this.say('error', message);
             const err = new Error(message);
             err.logged = true;
             throw err;
@@ -147,6 +148,16 @@ export class RunService extends Service {
      */
     async schedule(options) {
         const { panel, concurrency, commandName } = options;
+        /** Every event of the run is produced once, here, and rendered by each reporter - the screen
+         *  (panel or plain lines, or neither under `--json`) and the log. See `Reporter`. */
+        const reporters = this.reportersFor(commandName, panel);
+        const emit = (event, origin) => {
+            for (const reporter of reporters)
+                reporter.report(event, origin);
+        };
+        /** What a child is started with so the reporters can render it - colour where one prints it. */
+        const childEnv = Object.assign({}, ...reporters.map(r => r.childEnv ?? {}));
+        const runStarted = Date.now();
         /** Set once the aggregate Task exists, so a package's own failure can trigger a manual
          *  abort using *its own* resolved bail setting (see `runSteps` below) - power-tasks' own
          *  `bail` is a single blanket policy for the whole batch, it can't vary per package. */
@@ -184,50 +195,60 @@ export class RunService extends Service {
                         ctx.currentCommand = command ?? stepLabel;
                     };
                     ctx.stepIndex = i;
-                    if (panel.enabled) {
-                        const onLine = (line) => {
-                            ctx.log.push(line);
-                            ctx.lastLine = line;
-                        };
+                    const stepStart = Date.now();
+                    const origin = { item: ctx, logLevel: pkgLogLevel, label: step.label };
+                    /** Every step is bracketed - `start` before, `end` after whatever happened - and every line
+                     *  it produces is an `output` event, whichever reporters render them. */
+                    emit({ event: 'start', package: pkgLabel, step: step.name, command: stepLabel }, origin);
+                    const onLine = (line, stream = 'stdout', level) => emit({ event: 'output', package: pkgLabel, stream, line, ...(level && { level }) }, origin);
+                    let stepError;
+                    try {
+                        /**
+                         * **Piped, never inherited - the child never sees a terminal**, whether or not a panel is
+                         * drawing. Every line comes back as an event and the reporters print or store it. A child
+                         * that finds a TTY draws its own live output, and a build is mostly other CLIs: the
+                         * shared preset's `run.build` is `rman check`, `rman lint`, `rman clean` and `tsc`.
+                         * Reported as `rman build --no-progress` printing progress and losing its logs: a nested
+                         * `rman check` drew its own panel inside a run asked not to draw one.
+                         *
+                         * **No TTY is the convention every well-behaved CLI already honours**, which is why it
+                         * beats telling children about `--no-progress`: an environment variable would reach
+                         * nested rman and nothing else. The cost, stated: a child cannot prompt. Nothing in a
+                         * run step should.
+                         */
                         if (step.run)
                             await runFunctionStep(step.run, pkg, cwd, onLine, onCommand);
-                        else
-                            await exec(step.command, { cwd, stdio: 'pipe', onLine, app: pkg.repository.app });
-                    }
-                    else {
-                        /** Match the classic rman output: raw command output streams straight through
-                         *  (unbuffered, unprefixed), followed by our own one-line-per-step summary. */
-                        printLegacyExecutingLine(commandName, pkgLabel, step, pkgLogLevel);
-                        const stepStart = Date.now();
-                        let stepError;
-                        try {
-                            /** No capture with the panel off: the step owns the terminal, exactly as a shell
-                             *  step's `stdio: 'inherit'` does. */
-                            if (step.run)
-                                await runFunctionStep(step.run, pkg, cwd, undefined, onCommand);
-                            else
-                                await exec(step.command, { cwd, stdio: 'inherit', app: pkg.repository.app });
-                        }
-                        catch (e) {
-                            /**
-                             * **Normalized to an `Error`, because a *falsy* throw was indistinguishable from no
-                             * failure at all.** This was `let stepError: any` with `if (stepError) throw
-                             * stepError` below, so a step doing `throw undefined` - legal JavaScript, and what a
-                             * rejected promise carrying nothing gives you - left `stepError` falsy: the step
-                             * line printed **success**, nothing was rethrown, and the run exited 0. Found by the
-                             * spec written for the message-reporting fix above, which is the only reason it is
-                             * not still there. A step that fails while reporting success is the one outcome this
-                             * slot exists to rule out.
-                             *
-                             * Only the panel-off path had it: with the panel on there is no local catch, and the
-                             * outer one runs whatever was thrown.
-                             */
-                            stepError = e instanceof Error ? e : new Error(messageOf(e));
+                        else {
+                            await exec(step.command, {
+                                cwd,
+                                stdio: 'pipe',
+                                onLine,
+                                env: Object.keys(childEnv).length ? childEnv : undefined,
+                                app: pkg.repository.app,
+                            });
                         }
-                        printLegacyStepLine(commandName, pkgLabel, step, Date.now() - stepStart, pkgLogLevel, stepError);
-                        if (stepError)
-                            throw stepError;
                     }
+                    catch (e) {
+                        /**
+                         * **Normalized to an `Error`, because a *falsy* throw was indistinguishable from no
+                         * failure at all.** This was `let stepError: any` with `if (stepError) throw
+                         * stepError` below, so a step doing `throw undefined` - legal JavaScript, and what a
+                         * rejected promise carrying nothing gives you - left `stepError` falsy: the step
+                         * line printed **success**, nothing was rethrown, and the run exited 0. A step that
+                         * fails while reporting success is the one outcome this slot exists to rule out.
+                         */
+                        stepError = e instanceof Error ? e : new Error(messageOf(e));
+                    }
+                    emit({
+                        event: 'end',
+                        package: pkgLabel,
+                        step: step.name,
+                        status: stepError ? 'failed' : 'success',
+                        ms: Date.now() - stepStart,
+                        error: stepError?.message,
+                    }, origin);
+                    if (stepError)
+                        throw stepError;
                 }
                 /** Another part is coming, so the package is not done - and it is about to sit at the
                  *  barrier, which the row says out loud rather than leaving the last step's command on
@@ -272,16 +293,17 @@ export class RunService extends Service {
             /**
              * **Where this package starts waiting for its dependencies**, or `-1` for not at all.
              *
-             * A script whose steps mention `topo` at all is taken as the whole statement: the first step
-             * saying `true` is where the package blocks, and a script where every step says `false` does
-             * not wait. Only where **no** step mentions it does `run.<script>.topo` decide, and then the
-             * wait is before the first step - where it has always been.
+             * The first step marked `true`. With none, the first step that says nothing - an unmarked
+             * step takes `run.<script>.topo`, which got here only by being on. Only a script whose every
+             * step says `false` does not wait.
              *
-             * The two halves cannot be collapsed into one `findIndex`: "no step marked true" and "no step
-             * marked at all" are different answers (no wait against the old wait at step 0), and reading
-             * `-1` as either one alone gets the other wrong.
+             * A step marked `false` frees itself and nothing else. It used to free the whole script: any
+             * mention of `topo` was read as the complete statement, so one `after: { topo: false }` from
+             * a shared preset left every unmarked step beside it - a repository's own `before`, a
+             * package's own `build` script - running with no wait at all. Measured on opra, where
+             * `@opra/angular`'s `ng build` started while `@opra/client` was still cleaning.
              */
-            const barrier = !plan.topo ? -1 : steps.some(s => s.topo !== undefined) ? steps.findIndex(s => s.topo) : 0;
+            const barrier = !plan.topo ? -1 : this.barrierOf(steps);
             /**
              * **Split only when the wait is in the middle of the package and there is something to wait
              * for.** A barrier at step 0 is one task, as it always was; a package with no in-run
@@ -320,6 +342,22 @@ export class RunService extends Service {
         }
         panel.detail = this.repository.name;
         panel.start(this.repository.app.statusRegion);
+        /**
+         * **With no panel, the status line is silenced for the run as well** - not handed over, silenced:
+         * the children's lines are printed straight to the terminal (see the panel-off path in
+         * `runSteps`), and a spinner redrawing in place moves the cursor up over whatever was printed
+         * since. This is the case `--no-progress` does not cover, since the CLI never draws the line under
+         * that flag: a panel turned off by `.rmanrc run.<script>.progress: false`, or by stdout being
+         * redirected while stderr is still a terminal.
+         *
+         * It used to be left drawing on the grounds that it was "the one thing such a run still shows".
+         * That held while the children inherited the terminal and nothing was printed past it; once the
+         * run prints their lines itself, the two cannot share the screen.
+         */
+        const statusRegion = this.repository.app.statusRegion;
+        const muted = !panel.enabled && !!statusRegion?.live;
+        if (muted)
+            statusRegion.suspend({ passThrough: text => process.stderr.write(text) });
         try {
             /** bail:false here - each package's own resolved bail setting decides whether to call
              *  `rootTask.abort()` itself (see `runSteps`), since power-tasks' own `bail` can't vary per package. */
@@ -338,13 +376,19 @@ export class RunService extends Service {
              *  packages went on to succeed. */
             await Promise.allSettled(children.map(child => child.toPromise()));
             panel.stop();
+            if (muted)
+                statusRegion.resume();
         }
-        const summary = panel.printSummary();
-        /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
-         *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
-         *  run it had just reported as failed - non-deterministically, since it came down to which
-         *  packages happened to still be running (measured: `1 0 1 1 0` across five identical runs).
-         *  A single failed package must fail the command, every time. */
+        /** Counted once, then reported - a screen reporter prints the recap from the same tally, so the
+         *  prose and the `summary` event cannot disagree. */
+        const summary = panel.tally();
+        emit({
+            event: 'summary',
+            succeeded: summary.successCount,
+            failed: summary.failedCount,
+            skipped: summary.skippedCount,
+            ms: Date.now() - runStarted,
+        });
         /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
          *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
          *  run it had just reported as failed - non-deterministically, since it came down to which
@@ -380,7 +424,7 @@ export class RunService extends Service {
         const label = options.label ?? 'each';
         const logLevel = options.logLevel ?? resolveRootLogLevel(repository);
         const concurrency = resolveConcurrency(options.parallel, os.cpus().length);
-        const panel = new ProgressPanel(label.toUpperCase(), !!process.stdout.isTTY && options.progress !== false);
+        const panel = new ProgressPanel(label.toUpperCase(), !!process.stdout.isTTY && options.progress !== false && !repository.app.logSink?.json);
         /** Nothing to do is not a failure, and the caller is the one that can tell the two endings
          *  apart - it knows why its list is empty. `check` says so itself and returns. */
         if (!packages.length)
@@ -455,6 +499,43 @@ export class RunService extends Service {
             throw failure;
         return results;
     }
+    /**
+     * The index of the step a package waits for its dependencies before, or `-1` when every step is
+     * marked `topo: false`: the first step marked `true`, else the first unmarked one.
+     */
+    barrierOf(steps) {
+        /* No steps still waits, as it always did: dependents wait on this package's task, so one that
+         * skipped the wait would let them past its own dependencies. */
+        if (!steps.length)
+            return 0;
+        const marked = steps.findIndex(s => s.topo === true);
+        if (marked >= 0)
+            return marked;
+        return steps.findIndex(s => s.topo === undefined);
+    }
+    /**
+     * A line of rman's own about the run - "nothing to run", "no package defines it" - on the console
+     * as prose, or as a `message` event under `--json`, where stdout belongs to the events. Also in the
+     * log file when there is one.
+     */
+    say(level, message) {
+        for (const reporter of this.reportersFor('run'))
+            reporter.report({ event: 'message', level, message });
+    }
+    /**
+     * Who renders a run: the panel when it draws, plain lines when it does not, neither under `--json`
+     * (stdout belongs to the events) - plus the run's log, when the CLI asked for one.
+     */
+    reportersFor(commandName, panel) {
+        const sink = this.repository.app.logSink;
+        const reporters = [];
+        if (!sink?.json) {
+            reporters.push(panel?.enabled ? new PanelReporter(commandName, panel) : new PlainReporter(commandName, panel));
+        }
+        if (sink?.active)
+            reporters.push(sink);
+        return reporters;
+    }
 }
 (function (RunService) {
     /**
@@ -601,15 +682,28 @@ export class RunService extends Service {
                         return pristine[method](...args);
                     /** Split, because one `console.log` may carry several lines and the panel's log is a list
                      *  of them - a multi-line entry would render as one unreadable row. */
+                    const stream = method === 'error' || method === 'warn' ? 'stderr' : 'stdout';
                     for (const line of format(args).split('\n'))
-                        sink(line);
+                        sink(line, stream);
                 };
             }
             pristineConsole = pristine;
         }
         /** `Promise.resolve`, because a step may be a plain function - `RunStepFn` returns
-         *  `void | Promise<void>` and only the promise form can be awaited. */
-        return Promise.resolve(consoleSink.run(onLine, fn)).finally(() => {
+         *  `void | Promise<void>` and only the promise form can be awaited.
+         *
+         *  **A synchronous throw is caught into a rejection**, or it leaves before `finally` is attached
+         *  and the depth never comes back down - every later step then finds the console "already
+         *  patched" and captures nothing. Hidden while only the panel path captured; it surfaced the
+         *  day a plain run did, as two specs in another describe block failing only after this one. */
+        let result;
+        try {
+            result = consoleSink.run(onLine, fn);
+        }
+        catch (e) {
+            result = Promise.reject(e);
+        }
+        return Promise.resolve(result).finally(() => {
             if (--consoleDepth > 0 || !pristineConsole)
                 return;
             for (const method of CAPTURED_CONSOLE)
@@ -724,36 +818,6 @@ export class RunService extends Service {
     }
     RunService.evaluateIf = evaluateIf;
 })(RunService || (RunService = {}));
-/**
- * Classic one-line-per-step log ("info build pkg ┆ step success ┆ command  (123 ms)"),
- * matching rman's original npmlog-based output. Used when the live panel is off.
- *
- * Respects `logLevel`: 'verbose' also prints an "executing" line before the step runs
- * (rman's old behavior, hidden by default); 'error' suppresses success lines; 'silent'
- * suppresses everything but a real failure.
- */
-function printLegacyExecutingLine(commandName, pkgLabel, step, level) {
-    if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('verbose'))
-        return;
-    const sep = colors.gray('┆');
-    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), ...describing(step));
-}
-function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, error) {
-    if (!error && LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('info'))
-        return;
-    if (error && level === 'silent')
-        return;
-    const sep = colors.gray('┆');
-    const levelLabel = error ? colors.red('error') : colors.green('info');
-    const status = error ? colors.red.bold('failed') : colors.green.bold('success');
-    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, ...describing(step), colors.yellow(` (${durationMs} ms)`));
-}
-/** The `┆ <what it runs>` tail of a legacy log line, **or nothing at all** when the step has no
- *  label of its own - an anonymous function handed to `forEachPackage`, where the slot name already
- *  said everything there is to say and a separator with nothing after it is just noise. */
-function describing(step) {
-    return step.label ? [colors.gray('┆'), step.label] : [];
-}
 function describeValue(value) {
     if (Array.isArray(value))
         return 'a nested array';
@@ -814,50 +878,30 @@ function assertStepObject(item, where, allowTopo) {
 /** What a step object may hold - the step itself, and the marker beside it. */
 const STEP_OBJECT_KEYS = ['command', 'topo'];
 /**
- * Runs a function step.
- *
- * **`console` is redirected while it runs, but only when the panel is on** - and that is the same
- * split a shell step already makes. `exec` hands the panel its output through `stdio: 'pipe'` and
- * `onLine`, so a function writing straight to the real stdout would print *over* the panel it is
- * being rendered inside. With the panel off, `exec` uses `stdio: 'inherit'` and the step owns the
- * terminal; a function gets the same, untouched.
+ * Runs a function step, with its `console` captured into `onLine` - the step's own lines, routed to
+ * whichever reporters the run has, beside those of the children it spawns.
  *
- * Restored in a `finally`, because a step that throws must not leave the rest of the run writing
- * into a log nobody reads.
+ * **Always captured, panel or not.** With no panel a function's `console.log` used to go straight to
+ * the terminal, so it was the one kind of step output a plain run could not lead with its package -
+ * and it reached `--json` stdout and the log file not at all.
  *
  * **Its failure message is reported here, because nothing else does it.** A shell step's reason
- * reaches the user on its own - the output streams through `onLine` or straight to the terminal,
- * and `exec` names the command and its exit code. A function step has neither: it fails by
- * throwing, and the throw goes to the outer `catch` that marks the package failed and rethrows an
- * error the CLI treats as already-logged. Measured on a real config whose build step threw a
- * carefully worded message about a missing `tsconfig.json`: the run printed
+ * reaches the user on its own - its output streams and `exec` names the command and its exit code.
+ * A function step fails by throwing, and the throw goes to the catch that marks the package failed
+ * and rethrows an error the CLI treats as already-logged. Measured on a real config whose build step
+ * threw a carefully worded message about a missing `tsconfig.json`: the run printed
  * `error build pkg-forgot ┆ exec failed ┆ buildWithTsc` and exited 1, and the message appeared
- * nowhere at all - so the one thing that said what to do was the one thing dropped.
- *
- * Written where a shell step's output goes, so it needs no second channel: through `onLine` with
- * the panel on (the step's own log, which is what the panel shows for a failed item), and to
- * stderr with it off, ahead of the `failed` line - the order a shell step already produces.
+ * nowhere at all. Written to `onLine` on stderr, ahead of the step's `end` - the order a shell step
+ * already produces.
  */
 async function runFunctionStep(run, pkg, cwd, onLine, onCommand) {
     const context = RunService.createStepContext(pkg, cwd, onCommand, onLine);
-    if (!onLine) {
-        try {
-            await run(context);
-        }
-        catch (e) {
-            console.error(colors.red(messageOf(e)));
-            throw e;
-        }
-        return;
-    }
     try {
         await RunService.withCapturedConsole(onLine, () => run(context));
     }
     catch (e) {
-        /** Straight to `onLine`, so the message lands in this step's log rather than over the panel it
-         *  is drawn inside. */
         for (const line of messageOf(e).split('\n'))
-            onLine(line);
+            onLine(colors.red(line), 'stderr', 'error');
         throw e;
     }
 }
@@ -959,9 +1003,30 @@ function slotValues(slot, own, configured, override) {
     if (override)
         return configured.length ? configured : own;
     if (slot === 'exec')
-        return own.length ? own : configured;
+        return own.length ? withTopoOf(configured, own) : configured;
     return slot === 'before' ? [...configured, ...own] : [...own, ...configured];
 }
+/**
+ * The package's own `exec` steps, carrying the `topo` mark of the configured `exec` they replace.
+ */
+/* **The command is the package's; the ordering is the config's.** A `package.json` script cannot
+ * say `topo` at all, so replacing the configured `exec: { topo: true, command }` with it dropped the
+ * mark - and a shared preset marks `exec` precisely so the build waits for its dependencies.
+ * Measured on opra: `@opra/angular`'s own `"build": "ng build"` started while `@opra/client`, a
+ * peer it builds against, was still cleaning. Every package with its own build script had the same
+ * hole; angular is where a missing dependency output fails loudly. A `true` anywhere in the
+ * replaced slot wins, since a missed wait is the failure that does not look like one. */
+function withTopoOf(configured, own) {
+    const marks = configured.map(v => (typeof v === 'object' ? v.topo : undefined)).filter(t => t !== undefined);
+    if (!marks.length)
+        return own;
+    const topo = marks.includes(true);
+    return own.map(v => {
+        if (typeof v === 'object')
+            return v.topo === undefined ? { ...v, topo } : v;
+        return { command: v, topo };
+    });
+}
 /**
  * What this package's own technology says it declares for `script`.
  *

package/services/version-plan.service.js

@@ -4,7 +4,7 @@ import { assertOneScheme, semverScheme, VersionScheme } from '../core/classes/ve
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { findLastReleaseVersion, formatCalendarVersion, usesCalendarVersion } from '../utils/release-version.js';
-import { groupKeyOf } from '../utils/version-group.js';
+import { groupKeyOf, ROOT_GROUP_KEY } from '../utils/version-group.js';
 import { ConventionalCommitsService } from './conventional-commits.service.js';
 /**
  * Question A, computed and nothing else: **which packages have changed since their last release,
@@ -479,7 +479,7 @@ export class VersionPlanService {
         const root = repository.rootPackage;
         const anyBumped = memberEntries.some(e => e.status === 'bump');
         if (!anyBumped) {
-            return { package: root, groupKey: '__root__', group: 'root', status: 'no-change', from: root.version };
+            return { package: root, groupKey: ROOT_GROUP_KEY, group: 'root', status: 'no-change', from: root.version };
         }
         const calendar = usesCalendarVersion({
             groupCount: context.groupCount,
@@ -492,7 +492,7 @@ export class VersionPlanService {
             : (root.versionScheme.highestVersion(finalVersions) ?? root.version);
         return {
             package: root,
-            groupKey: '__root__',
+            groupKey: ROOT_GROUP_KEY,
             group: 'root',
             status: 'bump',
             from: root.version,

package/utils/progress-panel.d.ts

@@ -90,5 +90,11 @@ export declare class ProgressPanel implements TerminalRegion {
      * per-item recap lines are only printed when the live panel was actually on - with it off, the
      * caller's own plain logging already showed each item's outcome as it happened.
      */
+    /**
+     * The tally `printSummary` reports, without printing anything - for a run whose output is not
+     * prose (`--json`). Settles every still-pending item as skipped, exactly as `printSummary` does, so
+     * the two can never count differently.
+     */
+    tally(): ProgressSummary;
     printSummary(): ProgressSummary;
 }

package/utils/progress-panel.js

@@ -226,21 +226,38 @@ export class ProgressPanel {
      * per-item recap lines are only printed when the live panel was actually on - with it off, the
      * caller's own plain logging already showed each item's outcome as it happened.
      */
-    printSummary() {
+    /**
+     * The tally `printSummary` reports, without printing anything - for a run whose output is not
+     * prose (`--json`). Settles every still-pending item as skipped, exactly as `printSummary` does, so
+     * the two can never count differently.
+     */
+    tally() {
         let successCount = 0;
         let failedCount = 0;
         let skippedCount = 0;
         for (const item of this.items.values()) {
             if (item.status === 'pending')
                 item.status = 'skipped';
+            if (item.status === 'success')
+                successCount++;
+            else if (item.status === 'failed')
+                failedCount++;
+            else
+                skippedCount++;
+        }
+        return { successCount, failedCount, skippedCount };
+    }
+    printSummary() {
+        /** Counted by `tally`, which also settles the pending items - so a `--json` run, which asks
+         *  `tally` alone, can never count differently from one that prints. */
+        const { successCount, failedCount, skippedCount } = this.tally();
+        for (const item of this.items.values()) {
             const duration = item.startedAt && item.finishedAt ? colors.gray(formatDuration(item.finishedAt - item.startedAt)) : '';
             if (item.status === 'success') {
-                successCount++;
                 if (this.live.enabled)
                     console.log(colors.green('✓'), item.name, duration);
             }
             else if (item.status === 'failed') {
-                failedCount++;
                 if (this.live.enabled) {
                     console.log(colors.red.bold('X'), item.name, duration);
                     /* **The replayed log is printed as it was captured, never painted.** It holds the output
@@ -261,10 +278,8 @@ export class ProgressPanel {
                         console.log(item.log.join('\n'));
                 }
             }
-            else {
-                skippedCount++;
-                if (this.live.enabled)
-                    console.log(colors.gray('○'), item.name, colors.gray('skipped'));
+            else if (this.live.enabled) {
+                console.log(colors.gray('○'), item.name, colors.gray('skipped'));
             }
         }
         const totalElapsed = formatDuration(Date.now() - this.startedAt);

package/utils/run-bin.d.ts

@@ -1,5 +1,5 @@
 import type { RmanApplication } from '../core/application.js';
-import { type LogLevel } from './logger.js';
+import { type LogLevel } from '../core/classes/logger.js';
 export interface RunBinOptions {
     /**
      * The application whose technologies put a repository's locally installed binaries on PATH -
@@ -30,7 +30,8 @@ export interface RunBinOptions {
     /**
      * Called once per line of the child's output **instead of writing it to the terminal**.
      */
-    onLine?: (line: string) => void;
+    /** The stream each line came from, so a caller printing them can keep stdout and stderr apart. */
+    onLine?: (line: string, stream: 'stdout' | 'stderr') => void;
     env?: Record<string, string | undefined>;
 }
 export interface RunBinResult {
@@ -58,3 +59,10 @@ export interface RunBinResult {
  * nothing is the outcome worth ruling out, and that is what silently discarding a code produces.
  */
 export declare function runBin(bin: string, argv: string[], options?: RunBinOptions): Promise<RunBinResult>;
+/**
+ * Whether a child whose lines rman prints itself should be told to colour them: our own stdout is a
+ * terminal, and `NO_COLOR` is not set. The one rule for both kinds of step - `runBin`'s, above, and a
+ * shell step `exec` runs with its lines printed by `RunService` - so the two cannot disagree about
+ * when a piped child gets its colour back.
+ */
+export declare function colorsPrintedOutput(): boolean;