rman 2.2.0 → 2.3.0

package/cli.js

@@ -21,6 +21,7 @@ import { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 import { filterPackages, readFromRootOption, readPackageFilterOptions } from './utils/package-filter.js';
 import { printableConfig, withoutContributions } from './utils/printable-config.js';
 import { runBin } from './utils/run-bin.js';
+import { StatusRegion } from './utils/status-region.js';
 export async function runCli(options) {
     const _argv = options?.argv || hideBin(process.argv);
     /**
@@ -97,6 +98,14 @@ export async function runCli(options) {
          * quietly does nothing on whichever command forgot it is worse than no flag.
          */
         interceptConfigFlag(repository, program);
+        /**
+         * **A command that says nothing is indistinguishable from one that did not run.** `rman lint`
+         * on a clean repository starts and ends in silence - eslint prints nothing when it has nothing
+         * to say - and the reader is left wondering whether the command exists. One line when it
+         * starts and one when it ends answers that for every command at once, which is the same reason
+         * `--config` is applied here rather than per command.
+         */
+        interceptStatusLines(repository, program);
         /**
          * **Built-ins come from `commandRegistry`, in the order their modules were imported.** Each
          * entry is a register function that has not run yet - it runs here, with the repository, and
@@ -106,9 +115,10 @@ export async function runCli(options) {
          * The thirteen hand-written `initCli(repository, program)` calls this replaces were the second
          * place a command had to be listed, and the list the shadow check guards with was a third.
          */
+        /** Registered further down, once the contributed commands are known - a `shadowable` built-in
+         *  whose name one of them took must not be registered at all, or `--help` lists the name twice
+         *  with two descriptions and nothing says which runs. */
         const builtIns = commandRegistry.map(register => register(app));
-        for (const meta of builtIns)
-            program.command(toYargsCommand(meta));
         /**
          * Commands that are not built in, all from **one** key: `.rmanrc "commands"`, whose default
          * value is `.rman/*.{js,mjs,cjs}`.
@@ -184,6 +194,34 @@ export async function runCli(options) {
             }
         }
         assertNoBuiltinShadowing(commands, builtInNames(builtIns));
+        /**
+         * **Built-ins first, minus any `shadowable` one a contributed command has taken.**
+         *
+         * Skipping the registration rather than letting yargs' last-wins settle it is the same fix
+         * `byName` above is: the override already resolved correctly either way, but both rows appeared
+         * in `--help`, each with its own description and nothing to say which would run. Measured here
+         * on `test`, with rman's alias and `@panates/rman-preset`'s command both listed.
+         *
+         * Order is unchanged - built-ins are still registered before the contributed ones, so help
+         * reads as it always has.
+         */
+        const taken = new Set(commands.map(c => c.name));
+        const shadowed = builtIns.filter(meta => meta.shadowable && taken.has(commandName(meta.command)));
+        for (const meta of builtIns) {
+            if (shadowed.includes(meta))
+                continue;
+            program.command(toYargsCommand(meta));
+        }
+        /** Said out loud at `verbose`, for the reason the contributed-on-contributed note above gives:
+         *  an override is correct and should not nag, but "rman test does something else here" needs a
+         *  thread to pull. */
+        if (shadowed.length) {
+            const logger = new Logger(argvLogLevel(_argv) ?? resolveRootLogLevel(repository));
+            for (const meta of shadowed) {
+                const name = commandName(meta.command);
+                logger.verbose(`rman's own "${name}" is overridden by ${describeCommandSource(byName.get(name).file)}.`);
+            }
+        }
         for (const { module } of commands)
             program.command(module);
         /** Warned about, not thrown: one unparseable file must not take the other commands with it.
@@ -305,6 +343,74 @@ function interceptConfigFlag(repository, program) {
         });
     };
 }
+/**
+ * Replaces `program.command` with a version that brackets every handler in a line naming the
+ * command and a line giving its result and elapsed time.
+ *
+ * One interception point rather than a line written into each command - the same reason
+ * `interceptConfigFlag` is one, and it has to go in **before** any command is registered.
+ */
+/* **Why this exists at all**: a command that prints nothing is indistinguishable from one that
+ * never ran. `rman lint` on a clean repository is exactly that - eslint says nothing when it has
+ * nothing to say - and the reader is left asking whether the command took.
+ *
+ * **Four cases stay silent**, and each is about not corrupting something:
+ *
+ *   - `printsDocument` - the command's stdout *is* its answer. `rman config` writes a loadable YAML
+ *     document; a line above it makes the document unparseable, which is the same failure its own
+ *     colour handling already avoids for a pipe.
+ *   - `--json` and `--config` - machine output, whichever command produced it. `--json` is checked
+ *     rather than declared because any command may grow one, and a consumer doing
+ *     `rman version --json | jq` must never receive prose.
+ *   - `--log-level silent`, which is what it is for.
+ *
+ * **Written to stderr, not stdout**, so `rman changelog > NOTES.md` keeps the notes alone in the
+ * file even for a command that declares no `printsDocument`. The status is about the run, not the
+ * answer, and stderr is where that belongs.
+ *
+ * **The end line reports failure too, and then rethrows.** A command that throws still deserves the
+ * bracket closed - a start line with nothing after it reads as a hang. The error itself is left to
+ * the caller, which already prints it. */
+function interceptStatusLines(repository, program) {
+    const register = program.command.bind(program);
+    program.command = (spec) => {
+        if (!spec || typeof spec !== 'object' || typeof spec.handler !== 'function')
+            return register(spec);
+        const run = spec.handler;
+        return register({
+            ...spec,
+            handler: async (args) => {
+                /** The flag when it was given, the repository's own `logLevel` otherwise - the same
+                 *  precedence every other reader of it applies. `argvLogLevel` is not used here: that one
+                 *  exists for diagnostics emitted *before* parsing, and by now yargs has the answer. */
+                const level = args.logLevel ?? repository.config?.logLevel;
+                if (spec.printsDocument || args.json || args.config || level === 'silent')
+                    return run(args);
+                const name = commandName(spec.command ?? '');
+                /** Held on the application so `runBin` can find it through the `app` it already receives -
+                 *  see `RmanApplication.statusRegion` for why that rather than ambient state. */
+                const region = new StatusRegion(name, repository.name ?? '');
+                repository.app.statusRegion = region;
+                region.start();
+                try {
+                    const result = await run(args);
+                    region.stop('ok');
+                    return result;
+                }
+                catch (e) {
+                    /** **The bracket is closed even on a failure.** A spinner that simply stops, leaving its
+                     *  last frame on screen, reads as a hang - which is the thing this exists to prevent. The
+                     *  error itself is left to the caller, which already prints it. */
+                    region.stop('fail');
+                    throw e;
+                }
+                finally {
+                    repository.app.statusRegion = undefined;
+                }
+            },
+        });
+    };
+}
 /**
  * What a command would run with: its resolved options, the packages it would act on, and the
  * `.rmanrc` those packages carry.
@@ -420,7 +526,13 @@ if (isMain())
  * yargs' own command rather than one of ours, so it is the one name still written here.
  */
 function builtInNames(metas) {
-    const names = metas.flatMap(meta => [commandName(meta.command), ...(meta.aliases ?? [])]);
+    /** **A `shadowable` built-in is left out, so a contributed command may take its name.** Only
+     *  `build` and `test` are, and only because they carry no logic of their own - see
+     *  `CommandMetadata.shadowable`. Everything else defends its name, which is what keeps
+     *  `rman publish` from resolving to two different things. */
+    const names = metas
+        .filter(meta => !meta.shadowable)
+        .flatMap(meta => [commandName(meta.command), ...(meta.aliases ?? [])]);
     return [...names, 'completion'];
 }
 /**

package/commands/build.command.d.ts

@@ -83,6 +83,9 @@ type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const buildCommand: (app: import("../index.js").RmanApplication) => {
     command: "build";
     describe: string;
+    /** An alias carries no logic of its own, so a repository with a better answer for the name may
+     *  take it - see `CommandMetadata.shadowable`. */
+    shadowable: true;
     /**
      * Read, not owned - and it owns nothing at all. `build` is `run build` under another name, so its
      * settings live in `run.build`, which belongs to `run`. Two commands cannot contribute under one

package/commands/build.command.js

@@ -8,6 +8,9 @@ const buildCommand = registerCommand(app => {
     return {
         command: COMMAND,
         describe: 'Alias for "run build"',
+        /** An alias carries no logic of its own, so a repository with a better answer for the name may
+         *  take it - see `CommandMetadata.shadowable`. */
+        shadowable: true,
         /**
          * Read, not owned - and it owns nothing at all. `build` is `run build` under another name, so its
          * settings live in `run.build`, which belongs to `run`. Two commands cannot contribute under one

package/commands/changelog.command.d.ts

@@ -174,6 +174,8 @@ export interface ChangelogExtraKeys {
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const changelogCommand: (app: import("../index.js").RmanApplication) => {
     command: "changelog";
+    /** Prints the notes themselves, which a caller redirects into a file. */
+    printsDocument: true;
     describe: string;
     /** Read, not owned: `publish.skip` is `publish`'s key, reused here on purpose - a package that is
      *  never distributed gets no release notes either. */

package/commands/changelog.command.js

@@ -135,6 +135,8 @@ const changelogCommand = registerCommand(app => {
     const repository = app.repository;
     return {
         command: COMMAND,
+        /** Prints the notes themselves, which a caller redirects into a file. */
+        printsDocument: true,
         describe: 'Generates a changelog per package from unreleased commits',
         /** Read, not owned: `publish.skip` is `publish`'s key, reused here on purpose - a package that is
          *  never distributed gets no release notes either. */

package/commands/config.command.d.ts

@@ -19,6 +19,8 @@ type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 /** Prints config; declares none of its own, so it contributes nothing to `RmanConfig`. */
 declare const configCommand: (app: import("../index.js").RmanApplication) => {
     command: "config";
+    /** Prints a loadable YAML document - a line above it is what makes it unparseable. */
+    printsDocument: true;
     describe: string;
     config: {
         json: {

package/commands/config.command.js

@@ -22,6 +22,8 @@ const configCommand = registerCommand(app => {
     const repository = app.repository;
     return {
         command: COMMAND,
+        /** Prints a loadable YAML document - a line above it is what makes it unparseable. */
+        printsDocument: true,
         describe: 'Prints the effective .rmanrc config for the package of the current directory',
         config,
         examples: [

package/commands/diff.command.d.ts

@@ -12,6 +12,8 @@ declare const config: {
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const diffCommand: (app: import("../index.js").RmanApplication) => {
     command: "diff [package]";
+    /** Prints git's own diff, passed through. */
+    printsDocument: true;
     describe: string;
     config: {
         fromRoot: {

package/commands/diff.command.js

@@ -10,6 +10,8 @@ const diffCommand = registerCommand(app => {
     const repository = app.repository;
     return {
         command: COMMAND,
+        /** Prints git's own diff, passed through. */
+        printsDocument: true,
         describe: "Shows the git diff since a package's (or the whole repository's) last release tag",
         config,
         positionals: {

package/commands/info.command.d.ts

@@ -12,6 +12,8 @@ type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 /** Reports; declares no config key of its own. */
 declare const infoCommand: (app: import("../index.js").RmanApplication) => {
     command: "info";
+    /** Prints a report, which is the whole output. */
+    printsDocument: true;
     describe: string;
     config: {
         json: {

package/commands/info.command.js

@@ -11,6 +11,8 @@ const infoCommand = registerCommand(app => {
     const repository = app.repository;
     return {
         command: COMMAND,
+        /** Prints a report, which is the whole output. */
+        printsDocument: true,
         describe: 'Prints local environment and repository information',
         config,
         examples: [

package/commands/list.command.d.ts

@@ -79,6 +79,8 @@ declare const config: {
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const listCommand: (app: import("../index.js").RmanApplication) => {
     command: "list [options...]";
+    /** Prints a table, and `--json` beside it. */
+    printsDocument: true;
     aliases: string[];
     describe: string;
     config: {

package/commands/list.command.js

@@ -43,6 +43,8 @@ const config = {
 const listCommand = registerCommand(app => {
     return {
         command: COMMAND,
+        /** Prints a table, and `--json` beside it. */
+        printsDocument: true,
         aliases: ['ls'],
         describe: 'Lists packages in repository',
         config,

package/commands/test.command.d.ts

@@ -83,6 +83,9 @@ type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 declare const testCommand: (app: import("../index.js").RmanApplication) => {
     command: "test";
     describe: string;
+    /** An alias carries no logic of its own, so a repository with a better answer for the name may
+     *  take it - see `CommandMetadata.shadowable`. */
+    shadowable: true;
     /** Owns nothing, for the same reason `build` does not - see there. */
     configKeys: string[];
     config: {

package/commands/test.command.js

@@ -8,6 +8,9 @@ const testCommand = registerCommand(app => {
     return {
         command: COMMAND,
         describe: 'Alias for "run test"',
+        /** An alias carries no logic of its own, so a repository with a better answer for the name may
+         *  take it - see `CommandMetadata.shadowable`. */
+        shadowable: true,
         /** Owns nothing, for the same reason `build` does not - see there. */
         configKeys: ['run.test'],
         config,

package/constants.js

@@ -1 +1 @@
-export const version = '2.2.0';
+export const version = '2.3.0';

package/core/application.d.ts

@@ -1,5 +1,6 @@
 import type { VersionPlanService } from '../services/version-plan.service.js';
 import { Logger, type LogLevel } from '../utils/logger.js';
+import type { StatusRegion } from '../utils/status-region.js';
 import { Registry } from './classes/registry.js';
 import type { Repository } from './classes/repository.js';
 import type { ServiceFactory, ServiceMap } from './classes/service.js';
@@ -32,6 +33,15 @@ export declare class RmanApplication {
      * puts none.
      */
     readonly platforms: Registry<Platform>;
+    /**
+     * The live status line, while a command is running under one - `cli.ts` sets it and clears it.
+     *
+     * Read by whatever spawns a child process: a region draws a block at the bottom of the terminal
+     * and redraws it in place, so a child writing straight to the terminal scrolls the screen and the
+     * next redraw erases the wrong rows. `runBin` therefore pipes the child while this is set and
+     * routes its output through `passThrough`.
+     */
+    statusRegion?: StatusRegion;
     /**
      * The **plugins** themselves, in declaration order - what a config named, before the platforms
      * were taken out of them.

package/core/application.js

@@ -37,6 +37,19 @@ export class RmanApplication {
      * puts none.
      */
     platforms = new Registry();
+    /**
+     * The live status line, while a command is running under one - `cli.ts` sets it and clears it.
+     *
+     * Read by whatever spawns a child process: a region draws a block at the bottom of the terminal
+     * and redraws it in place, so a child writing straight to the terminal scrolls the screen and the
+     * next redraw erases the wrong rows. `runBin` therefore pipes the child while this is set and
+     * routes its output through `passThrough`.
+     */
+    /* **On the application rather than a module-level singleton**, which is the same seam `BinPath`
+     * already uses: `runBin` and `exec` are handed an `app`, so nothing has to reach for ambient
+     * state, and a spec that builds its own application cannot be affected by one that built
+     * another. The root-hook era this repository removed is what that rule is about. */
+    statusRegion;
     /**
      * The **plugins** themselves, in declaration order - what a config named, before the platforms
      * were taken out of them.

package/core/command-builder.js

@@ -13,6 +13,11 @@ export function toYargsCommand(meta) {
         aliases: meta.aliases,
         describe: meta.describe,
         configKeys: configKeysOf(meta),
+        /** Carried through like `configKeys`, and for the same reason: `cli.ts` reads it off the
+         *  registration, which is the only shape that reaches `program.command`. Left out, the flag is
+         *  a field nothing ever sees - measured, `rman config` printed a status line above its own YAML
+         *  document while declaring `printsDocument: true`. */
+        printsDocument: meta.printsDocument,
         builder: (cmd) => {
             if (meta.parserConfiguration)
                 cmd.parserConfiguration(meta.parserConfiguration);

package/core/interfaces/custom-command.d.ts

@@ -68,6 +68,10 @@ export interface CustomCommand {
 declare module 'yargs' {
     interface CommandModule<T = {}, U = {}> {
         configKeys?: ConfigKeys;
+        /** Whether this command's stdout is a document nothing may be printed around - see
+         *  `CommandMetadata.printsDocument`. Here as well as there because `cli.ts` reads it off the
+         *  *registration*, which is the only shape that reaches `program.command`. */
+        printsDocument?: boolean;
     }
 }
 /**

package/interfaces/rman-config.interface.d.ts

@@ -536,6 +536,27 @@ export declare namespace RmanConfig {
          * parses.
          */
         positionals?: Record<string, PositionalOption>;
+        /**
+         * **This command's stdout *is* its answer, so nothing may be printed around it.** `rman config`
+         * writes a loadable YAML document, `list` a table, `changelog` the notes themselves - a status
+         * line above or below any of them is content the reader did not ask for, and for `config` it
+         * makes the output unloadable.
+         *
+         * Everything else gets a line naming the command when it starts and one giving the result and
+         * the elapsed time when it ends (`cli.ts`'s `interceptStatusLines`).
+         */
+        printsDocument?: boolean;
+        /**
+         * **Whether a contributed command may take this name.** `build` and `test` are the only two,
+         * and they are the only two that carry no logic of their own - both are `run <script>` under a
+         * shorter name. A name whose holder has nothing to defend should belong to whoever has the
+         * better answer for it.
+         *
+         * Read by `cli.ts`'s `builtInNames`, which is what `assertNoBuiltinShadowing` checks against.
+         * The existing "one registration per name, keeping the last" rule then does the rest, and
+         * announces the override at `--log-level verbose`.
+         */
+        shadowable?: boolean;
         /**
          * **The parameter is the command's own business, so this states no type for it.**
          * A handler annotates itself with `ArgsOf<typeof config, typeof COMMAND>`, which this interface

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/utils/live-region.d.ts

@@ -9,7 +9,12 @@
 export declare class LiveRegion {
     private lineCount;
     readonly enabled: boolean;
-    constructor(enabled?: boolean);
+    /** Where the block is drawn. **stdout by default**, which is what the progress panel has always
+     *  used; a caller whose *answer* goes to stdout passes stderr instead, so redirecting the answer
+     *  into a file does not capture cursor-movement codes. Both land on the same terminal, so only
+     *  one region may be live at a time either way. */
+    private readonly stream;
+    constructor(enabled?: boolean, stream?: NodeJS.WriteStream);
     render(lines: string[]): void;
     /** Erases the block entirely, leaving the cursor where it started. */
     clear(): void;

package/utils/live-region.js

@@ -9,13 +9,19 @@
 export class LiveRegion {
     lineCount = 0;
     enabled;
-    constructor(enabled = !!process.stdout.isTTY) {
-        this.enabled = enabled;
+    /** Where the block is drawn. **stdout by default**, which is what the progress panel has always
+     *  used; a caller whose *answer* goes to stdout passes stderr instead, so redirecting the answer
+     *  into a file does not capture cursor-movement codes. Both land on the same terminal, so only
+     *  one region may be live at a time either way. */
+    stream;
+    constructor(enabled, stream = process.stdout) {
+        this.stream = stream;
+        this.enabled = enabled ?? !!stream.isTTY;
     }
     render(lines) {
         if (!this.enabled)
             return;
-        const width = process.stdout.columns || 80;
+        const width = this.stream.columns || 80;
         /** Measure by visible length, not raw length - a heavily-colored line has far more
          *  bytes than visible characters, and slicing the raw string would cut mid-escape-code. */
         let clipped = lines.map(l => {
@@ -27,7 +33,7 @@ export class LiveRegion {
          *  scrolls the screen, "move up N rows" can't actually get back N rows, and every
          *  redraw lands lower than the last, leaving a trail instead of a single updating block.
          *  Callers should size their own content to fit, but this is a hard backstop. */
-        const maxRows = Math.max(1, (process.stdout.rows || 24) - 1);
+        const maxRows = Math.max(1, (this.stream.rows || 24) - 1);
         if (clipped.length > maxRows)
             clipped = clipped.slice(0, maxRows);
         let out = this.lineCount ? `\x1b[${this.lineCount}A` : '';
@@ -37,7 +43,7 @@ export class LiveRegion {
             out += '\r\x1b[2K\n';
         if (clipped.length < this.lineCount)
             out += `\x1b[${this.lineCount - clipped.length}A`;
-        process.stdout.write(out);
+        this.stream.write(out);
         this.lineCount = clipped.length;
     }
     /** Erases the block entirely, leaving the cursor where it started. */
@@ -48,7 +54,7 @@ export class LiveRegion {
         for (let i = 0; i < this.lineCount; i++)
             out += '\r\x1b[2K\n';
         out += `\x1b[${this.lineCount}A`;
-        process.stdout.write(out);
+        this.stream.write(out);
         this.lineCount = 0;
     }
 }

package/utils/run-bin.js

@@ -26,23 +26,52 @@ export async function runBin(bin, argv, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const logLevel = options.logLevel ?? 'info';
     const atLeast = (level) => LOG_LEVELS.indexOf(logLevel) >= LOG_LEVELS.indexOf(level);
+    /**
+     * **A live status region forces `pipe`, whatever the log level would have chosen.** The region
+     * draws a block at the bottom of the terminal and redraws it in place; a child writing straight
+     * to the terminal scrolls the screen, and the next redraw's "move up N rows" then erases what the
+     * child just printed. So the child is piped and every line goes through `passThrough`, which
+     * erases the block, writes, and redraws below it - the same arrangement `RunService` makes for the
+     * progress panel, for the same reason.
+     *
+     * An explicit `options.stdio` still wins: a caller that has thought about it outranks this.
+     */
+    const region = options.app?.statusRegion?.live ? options.app.statusRegion : undefined;
     /** Below 'info' the output is captured rather than streamed, so a quiet run stays quiet and a
      *  failing one can still say what went wrong. */
-    const stdio = options.stdio ?? (atLeast('info') ? 'inherit' : 'pipe');
+    const stdio = options.stdio ?? (region ? 'pipe' : atLeast('info') ? 'inherit' : 'pipe');
     if (atLeast('verbose'))
         console.log(colors.magenta('verbose'), colors.gray('$'), bin, argv.join(' '));
     const child = spawn(process.platform === 'win32' ? `${bin}.cmd` : bin, argv, {
         cwd,
         stdio: stdio === 'inherit' ? 'inherit' : 'pipe',
-        env: BinPath.env({ cwd, env: options.env, app: options.app }),
+        /** **`FORCE_COLOR` when a region made us pipe.** A child checks `isTTY` to decide whether to
+         *  colour, and a pipe is not one - so routing eslint's output through the region would
+         *  otherwise strip the colour it had when it inherited the terminal. Set only for that case:
+         *  a caller that asked for `pipe` itself is usually capturing text to read, not to show. */
+        env: BinPath.env({
+            cwd,
+            env: region && atLeast('info') ? { FORCE_COLOR: '1', ...options.env } : options.env,
+            app: options.app,
+        }),
         windowsHide: true,
     });
     /** So an interrupted rman does not leave this running - `exec` always did this and this did not,
      *  which meant a plugin command's child outlived a Ctrl-C. See `trackChild`. */
     trackChild(child);
     let output = '';
-    child.stdout?.on('data', (d) => (output += d.toString()));
-    child.stderr?.on('data', (d) => (output += d.toString()));
+    /** **Streamed through the region as it arrives, not held to the end.** Piping is how the region
+     *  stays intact; buffering would additionally make a long command look silent, which is the very
+     *  thing the region exists to fix. Only when a region is live - otherwise `pipe` keeps meaning
+     *  "capture, and surface it if this fails". */
+    const collect = (d) => {
+        const text = d.toString();
+        output += text;
+        if (region && atLeast('info'))
+            region.passThrough(text);
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
     return new Promise((resolve, reject) => {
         child.on('error', (e) => {
             reject(e?.code === 'ENOENT' ? new Error(`"${bin}" was not found - is it installed in this repository?`) : e);
@@ -52,8 +81,10 @@ export async function runBin(bin, argv, options = {}) {
                 return resolve({ code: 0, output });
             /** Captured output has to be surfaced here or it is lost with the process - the one thing
              *  worse than a noisy failure is a silent one. 'silent' is the caller saying otherwise. */
-            if (stdio === 'pipe' && output && logLevel !== 'silent')
+            /** Already streamed through the region, so printing it again would double it. */
+            if (stdio === 'pipe' && output && logLevel !== 'silent' && !(region && atLeast('info'))) {
                 process.stderr.write(output);
+            }
             const err = new Error(`"${bin} ${argv.join(' ')}" exited with code ${code}`);
             err.code = code;
             err.output = output;

package/utils/status-region.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One line at the bottom of the terminal while a command runs - a spinner, the command's name, the
+ * repository, and the elapsed time counting up - replaced by a result line when it ends.
+ *
+ * ```
+ * ⠹ lint  postgrejs  2.4s      <- while running, redrawn in place
+ * ✔ lint  3.6s                 <- once it ends
+ * ```
+ */
+export declare class StatusRegion {
+    private readonly label;
+    private readonly detail;
+    private readonly region;
+    private readonly startedAt;
+    private timer?;
+    private frame;
+    constructor(label: string, detail?: string, enabled?: boolean);
+    /** Whether the spinner is actually drawn. `false` leaves `passThrough` a plain write and `stop`
+     *  its single line, which is what a non-TTY wants. */
+    get live(): boolean;
+    /** Starts the spinner. Safe to call when not live - it does nothing. */
+    start(): void;
+    /** Writes `text` without corrupting the block: erase, write, redraw underneath. */
+    passThrough(text: string): void;
+    /** Erases the spinner and leaves one line saying how it went. */
+    stop(outcome: 'ok' | 'fail'): void;
+    private draw;
+    /** `0.4s` while running and `950ms` / `4.1s` / `2m 03s` at the end - one formatter, because a
+     *  duration that changes shape as it ticks reads as a glitch. */
+    private elapsed;
+}
+/** `950ms`, `4.1s`, `2m 03s` - the three magnitudes a command run lands in. Seconds to one decimal
+ *  because the difference between 4.1s and 4.9s is worth seeing and 4.13s is not. */
+export declare function formatElapsed(ms: number): string;

package/utils/status-region.js

@@ -0,0 +1,109 @@
+import colors from 'ansi-colors';
+import { LiveRegion } from './live-region.js';
+/**
+ * One line at the bottom of the terminal while a command runs - a spinner, the command's name, the
+ * repository, and the elapsed time counting up - replaced by a result line when it ends.
+ *
+ * ```
+ * ⠹ lint  postgrejs  2.4s      <- while running, redrawn in place
+ * ✔ lint  3.6s                 <- once it ends
+ * ```
+ */
+/* **Why a live line rather than one printed at the start**: a command that prints nothing is
+ * indistinguishable from one that never ran, and a static start line answers "did it start" without
+ * answering "is it still going". `rman lint` on a clean repository is silent for several seconds
+ * because eslint says nothing when it has nothing to say.
+ *
+ * **On stderr, unlike `ProgressPanel`'s region.** A command's *answer* goes to stdout, and
+ * `rman changelog > NOTES.md` has to leave the notes alone in the file - cursor-movement codes in
+ * there would be worse than noise. The two streams share a terminal, so only one region is ever
+ * live.
+ *
+ * **Anything printed while it is live has to go through `passThrough`**, which erases the block,
+ * writes, and redraws below. A write that bypasses it scrolls the screen, and the next redraw's
+ * "move up N rows" then lands on the wrong rows and erases what was just printed - the same cursor
+ * arithmetic `LiveRegion` documents as its own hard edge. That is why `runBin` pipes a child while
+ * a region is live instead of letting it inherit the terminal.
+ *
+ * **No-op when stderr is not a TTY** (CI, a pipe), where the escape codes mean nothing. There the
+ * caller still gets the result line, which is the part that carries information. */
+export class StatusRegion {
+    label;
+    detail;
+    region;
+    startedAt = Date.now();
+    timer;
+    frame = 0;
+    constructor(label, detail = '', enabled) {
+        this.label = label;
+        this.detail = detail;
+        this.region = new LiveRegion(enabled, process.stderr);
+    }
+    /** Whether the spinner is actually drawn. `false` leaves `passThrough` a plain write and `stop`
+     *  its single line, which is what a non-TTY wants. */
+    get live() {
+        return this.region.enabled;
+    }
+    /** Starts the spinner. Safe to call when not live - it does nothing. */
+    start() {
+        if (!this.region.enabled)
+            return;
+        this.draw();
+        /** **`unref`, so a spinner never holds the process open.** A command that finishes its work and
+         *  leaves nothing else pending would otherwise wait out the interval before exiting. */
+        this.timer = setInterval(() => {
+            this.frame++;
+            this.draw();
+        }, FRAME_MS);
+        this.timer.unref();
+    }
+    /** Writes `text` without corrupting the block: erase, write, redraw underneath. */
+    passThrough(text) {
+        if (!this.region.enabled) {
+            process.stderr.write(text);
+            return;
+        }
+        this.region.clear();
+        process.stderr.write(text);
+        this.draw();
+    }
+    /** Erases the spinner and leaves one line saying how it went. */
+    stop(outcome) {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.region.clear();
+        const mark = outcome === 'ok' ? colors.green('✔') : colors.red('✖');
+        process.stderr.write(`${mark} ${colors.bold(this.label)} ${colors.gray(this.elapsed())}\n`);
+    }
+    draw() {
+        const spinner = colors.cyan(FRAMES[this.frame % FRAMES.length]);
+        const parts = [
+            spinner,
+            colors.bold(this.label),
+            this.detail && colors.gray(this.detail),
+            colors.gray(this.elapsed()),
+        ];
+        this.region.render([parts.filter(Boolean).join(' ')]);
+    }
+    /** `0.4s` while running and `950ms` / `4.1s` / `2m 03s` at the end - one formatter, because a
+     *  duration that changes shape as it ticks reads as a glitch. */
+    elapsed() {
+        return formatElapsed(Date.now() - this.startedAt);
+    }
+}
+/** `950ms`, `4.1s`, `2m 03s` - the three magnitudes a command run lands in. Seconds to one decimal
+ *  because the difference between 4.1s and 4.9s is worth seeing and 4.13s is not. */
+export function formatElapsed(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const m = Math.floor(ms / 60_000);
+    return `${m}m ${String(Math.round((ms % 60_000) / 1000)).padStart(2, '0')}s`;
+}
+/** Braille dots - one cell wide in every terminal font that has them, where an emoji spinner is two
+ *  cells in some and one in others and makes the line jitter. */
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** Fast enough to read as motion, slow enough that a redraw is not most of what the process does. */
+const FRAME_MS = 80;