rman 2.6.0 → 2.7.0

package/builtins/platforms/node/services/ci.service.js

@@ -72,7 +72,8 @@ export var CiService;
         const progress = options.progress ?? true;
         const panel = new ProgressPanel('CI', !!process.stdout.isTTY && progress);
         const runStartedAt = Date.now();
-        panel.start();
+        panel.detail = repository.name;
+        panel.start(repository.app.statusRegion);
         const items = [];
         let failed = false;
         try {
@@ -122,6 +123,9 @@ const LOCK_FILES = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.loc
  *  log uses. `logLine` is expected to go through a `Logger` (so it respects `--log-level`), not a
  *  raw `console.log`. */
 async function runStep(app, item, panelEnabled, cwd, command, logLine) {
+    /** **Set here rather than at each of the three call sites**, which is also what keeps `wipe` out
+     *  of it: a wipe runs no command, and this is the one place a `ci` step has one. */
+    item.currentCommand = command;
     if (panelEnabled) {
         await exec(command, {
             app,

package/builtins/platforms/node/services/clean.service.js

@@ -53,7 +53,8 @@ export var CleanService;
         const progress = options.progress ?? true;
         const logger = new Logger(options.logLevel ?? resolveRootLogLevel(repository));
         const panel = new ProgressPanel(dryRun ? 'CLEAN (dry-run)' : 'CLEAN', !!process.stdout.isTTY && progress);
-        panel.start();
+        panel.detail = repository.name;
+        panel.start(repository.app.statusRegion);
         let failed = false;
         try {
             const results = await Promise.allSettled(targets.map(pkg => {

package/commands/changelog.command.js

@@ -225,7 +225,8 @@ const changelogCommand = registerCommand(app => {
                 progress: panelReporter(panel),
             };
             const changelog = app.getService('changelog');
-            panel.start();
+            panel.detail = repository.name;
+            panel.start(app.statusRegion);
             let entries;
             try {
                 entries = write ? await changelog.generateToFile(options) : await changelog.getEntries(options);

package/constants.js

@@ -1 +1 @@
-export const version = '2.6.0';
+export const version = '2.7.0';

package/package.json

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

package/services/exec.service.js

@@ -52,10 +52,15 @@ export class ExecService extends Service {
         const names = new Set(packages.map(p => p.name));
         const children = packages.map(pkg => {
             const ctx = panel.addItem(pkg.name);
+            /** One command for every package and it never changes, so it is set once here rather than
+             *  threaded into `execForPackage` - the row is the only thing that was not saying what `exec`
+             *  is actually running. */
+            ctx.currentCommand = command;
             const dependencies = topo ? pkg.dependencies.filter(d => names.has(d.name)).map(d => d.name) : [];
             return new Task(() => execForPackage(this.app, ctx, panel.enabled, pkg.dirname, command, logger, bail ? () => rootTask?.abort() : () => { }), { name: pkg.name, dependencies });
         });
-        panel.start();
+        panel.detail = repository.name;
+        panel.start(repository.app.statusRegion);
         let failed = false;
         try {
             /** bail:false here - each item's own task decides whether to call `rootTask.abort()`

package/services/run.service.d.ts

@@ -168,7 +168,11 @@ export declare namespace RunService {
      * differently, which is how `version.<slot>` came to join its array with `' && '`.
      */
     export function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
-    export function createStepContext(pkg: Package, cwd: string): RunStepContext;
+    /**
+     * `onCommand` is told what the step is spawning, for as long as it runs - the argv while a child
+     * is up, `undefined` when it returns.
+     */
+    export function createStepContext(pkg: Package, cwd: string, onCommand?: (command: string | undefined) => void): RunStepContext;
     /**
      * `.rmanrc` conditional execution, GitHub Actions-`if`-flavored but a small closed grammar
      * instead of a full expression language (less to get wrong, still covers what's asked for) -

package/services/run.service.js

@@ -66,7 +66,13 @@ export class RunService extends Service {
                      *  does not distinguish a JS step from a shell one. `step.label` is not used directly
                      *  because for a function it already folds the slot in (`before (js)`), which the row
                      *  prints two characters to its left. */
-                    ctx.currentCommand = step.command ?? (step.run?.name ? `${step.run.name}()` : '(js function)');
+                    const stepLabel = step.command ?? (step.run?.name ? `${step.run.name}()` : '(js function)');
+                    ctx.currentCommand = stepLabel;
+                    /** A function step names itself until it spawns something, and takes its name back when
+                     *  that returns - so the row says `tsc -b tsconfig.json` for as long as tsc is up. */
+                    const onCommand = (command) => {
+                        ctx.currentCommand = command ?? stepLabel;
+                    };
                     ctx.stepIndex = i;
                     if (panel.enabled) {
                         const onLine = (line) => {
@@ -74,7 +80,7 @@ export class RunService extends Service {
                             ctx.lastLine = line;
                         };
                         if (step.run)
-                            await runFunctionStep(step.run, pkg, cwd, onLine);
+                            await runFunctionStep(step.run, pkg, cwd, onLine, onCommand);
                         else
                             await exec(step.command, { cwd, stdio: 'pipe', onLine, app: pkg.repository.app });
                     }
@@ -88,7 +94,7 @@ export class RunService extends Service {
                             /** 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);
+                                await runFunctionStep(step.run, pkg, cwd, undefined, onCommand);
                             else
                                 await exec(step.command, { cwd, stdio: 'inherit', app: pkg.repository.app });
                         }
@@ -228,7 +234,8 @@ export class RunService extends Service {
             err.logged = true;
             throw err;
         }
-        panel.start();
+        panel.detail = repository.name;
+        panel.start(repository.app.statusRegion);
         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. */
@@ -361,13 +368,31 @@ export class RunService extends Service {
         return steps;
     }
     RunService.normalizeScriptValue = normalizeScriptValue;
-    function createStepContext(pkg, cwd) {
+    /**
+     * `onCommand` is told what the step is spawning, for as long as it runs - the argv while a child
+     * is up, `undefined` when it returns.
+     */
+    /* **Without it a function step can only name itself.** The row showed `buildWithTsc()` for the
+     * whole of a build, because that is all the slot knows; what a reader wants is the `tsc -b
+     * <tsconfig>` it is sitting in. A function step is the shape every shared config uses, so this is
+     * the common case rather than an edge one. */
+    function createStepContext(pkg, cwd, onCommand) {
         const logLevel = resolveRootLogLevel(pkg.repository);
         return {
             pkg,
             repository: pkg.repository,
             cwd,
-            runBin: (bin, argv, opts) => runBin(bin, argv, { cwd, logLevel, app: pkg.repository.app, ...opts }),
+            runBin: async (bin, argv, opts) => {
+                onCommand?.([bin, ...argv].join(' '));
+                try {
+                    return await runBin(bin, argv, { cwd, logLevel, app: pkg.repository.app, ...opts });
+                }
+                finally {
+                    /** Back to whatever the caller had, or a step that spawns once would wear that command
+                     *  for the rest of its run. */
+                    onCommand?.(undefined);
+                }
+            },
             logger: new Logger(logLevel),
         };
     }
@@ -510,8 +535,8 @@ function toStep(slot, value) {
  * 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.
  */
-async function runFunctionStep(run, pkg, cwd, onLine) {
-    const context = RunService.createStepContext(pkg, cwd);
+async function runFunctionStep(run, pkg, cwd, onLine, onCommand) {
+    const context = RunService.createStepContext(pkg, cwd, onCommand);
     if (!onLine) {
         try {
             await run(context);

package/utils/progress-panel.d.ts

@@ -1,4 +1,5 @@
 import { LiveRegion } from './live-region.js';
+import type { StatusRegion, TerminalRegion } from './status-region.js';
 export type ProgressStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
 export interface ProgressItem {
     readonly name: string;
@@ -41,11 +42,19 @@ export declare function formatDuration(ms: number): string;
  * callers are expected to fall back to their own plain logging in that case, the way `run`
  * falls back to its "classic" per-step log.
  */
-export declare class ProgressPanel {
+export declare class ProgressPanel implements TerminalRegion {
     private readonly title;
     readonly live: LiveRegion;
     private readonly items;
     private renderLoop?;
+    /** The region this panel took the terminal from, handed back in `stop`. */
+    private statusRegion?;
+    /**
+     * What the run is about - the repository name, shown beside the title. Assigned rather than
+     * constructed with, the way a `ProgressItem`'s fields are: it keeps `stream` from needing an
+     * `undefined` placeholder at four of the five call sites.
+     */
+    detail?: string;
     private spinnerFrame;
     private startedAt;
     /**
@@ -59,8 +68,19 @@ export declare class ProgressPanel {
     /** Registers an item and returns it - callers mutate the returned object directly (`status`,
      *  `currentStep`, `lastLine`, ...) to drive the next render tick. */
     addItem(name: string, stepsTotal?: number): ProgressItem;
-    /** Starts the redraw loop. No-op (and no timer) when disabled. */
-    start(): void;
+    /**
+     * Starts the redraw loop. No-op (and no timer) when disabled.
+     *
+     * **Pass `statusRegion` wherever one exists** - `app.statusRegion`, which every command has while
+     * it runs. The panel takes the terminal over for as long as it draws and hands it back in `stop`;
+     * without that, two regions redraw on top of each other and the bottom lines visibly swap places
+     * several times a second. See `StatusRegion.suspend`.
+     */
+    start(statusRegion?: StatusRegion): void;
+    /** Writes `text` above the panel without corrupting it - erase, write, redraw underneath. The
+     *  `TerminalRegion` half of the takeover, so a `runBin` child's output goes somewhere sane while
+     *  a panel is up. */
+    passThrough(text: string): void;
     private render;
     /** Stops the redraw loop and erases the panel, leaving the cursor where it started. */
     stop(): void;

package/utils/progress-panel.js

@@ -19,6 +19,14 @@ export class ProgressPanel {
     live;
     items = new Map();
     renderLoop;
+    /** The region this panel took the terminal from, handed back in `stop`. */
+    statusRegion;
+    /**
+     * What the run is about - the repository name, shown beside the title. Assigned rather than
+     * constructed with, the way a `ProgressItem`'s fields are: it keeps `stream` from needing an
+     * `undefined` placeholder at four of the five call sites.
+     */
+    detail;
     spinnerFrame = 0;
     startedAt = 0;
     /**
@@ -41,13 +49,36 @@ export class ProgressPanel {
         this.items.set(name, item);
         return item;
     }
-    /** Starts the redraw loop. No-op (and no timer) when disabled. */
-    start() {
+    /**
+     * Starts the redraw loop. No-op (and no timer) when disabled.
+     *
+     * **Pass `statusRegion` wherever one exists** - `app.statusRegion`, which every command has while
+     * it runs. The panel takes the terminal over for as long as it draws and hands it back in `stop`;
+     * without that, two regions redraw on top of each other and the bottom lines visibly swap places
+     * several times a second. See `StatusRegion.suspend`.
+     */
+    start(statusRegion) {
         this.startedAt = Date.now();
         if (!this.live.enabled)
             return;
+        /** Only when this panel is actually drawing: a disabled panel owns nothing, and suspending the
+         *  status line for it would take away the one thing a non-TTY run still shows. */
+        this.statusRegion = statusRegion;
+        this.statusRegion?.suspend(this);
         this.renderLoop = setInterval(() => this.render(), 100);
     }
+    /** Writes `text` above the panel without corrupting it - erase, write, redraw underneath. The
+     *  `TerminalRegion` half of the takeover, so a `runBin` child's output goes somewhere sane while
+     *  a panel is up. */
+    passThrough(text) {
+        if (!this.live.enabled) {
+            process.stdout.write(text);
+            return;
+        }
+        this.live.clear();
+        process.stdout.write(text);
+        this.render();
+    }
     render() {
         this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
         const spinner = colors.cyan(SPINNER_FRAMES[this.spinnerFrame]);
@@ -86,8 +117,21 @@ export class ProgressPanel {
         const bar = renderProgressBar(filled, total);
         const totalElapsed = formatDuration(Date.now() - this.startedAt);
         const failedText = failedSoFar > 0 ? colors.red.bold(`${failedSoFar} failed`) : colors.gray(`${failedSoFar} failed`);
+        /**
+         * **The header says what is running, because nothing else does any more.** The status line used
+         * to carry `ci opra` beside this panel; it is suspended now so the two stop redrawing over each
+         * other, and suppressing it without moving its content here took the command and the repository
+         * off the screen entirely. The badge already names the command, so what had to move is the
+         * repository.
+         *
+         * **At the right end, where the line has room.** Between the badge and the bar it would push
+         * every column right by the length of a repository name - so the bar, the counts and the clock
+         * would sit at a different place in each repository, and the bar would shift the moment a
+         * panel's detail were set. The tail is empty space in every terminal this fits in.
+         */
+        const detail = this.detail ? `   ${colors.gray(this.detail)}` : '';
         const lines = [
-            `${header} ${bar} ${colors.bold(`${done}/${total}`)}  ${colors.cyan(`${running} running`)}  ${failedText}  ${colors.yellow(totalElapsed)}`,
+            `${header} ${bar} ${colors.bold(`${done}/${total}`)}  ${colors.cyan(`${running} running`)}  ${failedText}  ${colors.yellow(totalElapsed)}${detail}`,
         ];
         const runningList = [...this.items.values()].filter(i => i.status === 'running');
         /** Leave room for the header, a safety margin, and a possible "N more running" line - a
@@ -103,12 +147,19 @@ export class ProgressPanel {
                 : item.currentStep || '';
             /** Measured against the *plain* text: every piece below is wrapped in escape sequences, and
              *  `String.length` counts those, so budgeting on the rendered string wraps a row that fits. */
-            const fixed = `  ${item.name}  ${step}  ${elapsed}`.length;
+            const fixed = `  ${item.name}  ${step}  ${elapsed} | `.length;
             const command = truncate(item.currentCommand ?? '', (process.stdout.columns || 80) - fixed - 2);
+            /**
+             * **The command last, after a `|`, and that is not only layout.** It is the one field with no
+             * bound on its length - a `tsc -b` line carries a path, a `run` step carries whatever the
+             * author wrote - so between the step and the clock it pushed the elapsed time to a different
+             * column on every row, and off the end entirely once a command was long. Everything fixed-width
+             * now reads down a straight edge and the variable part runs off to the right, where `truncate`
+             * cuts it.
+             */
             const group = [
-                `${spinner} ${colors.bold(item.name)}  ${colors.gray(step)}` +
-                    (command ? `  ${colors.cyan(command)}` : '') +
-                    `  ${colors.yellow(elapsed)}`,
+                `${spinner} ${colors.bold(item.name)}  ${colors.gray(step)}  ${colors.yellow(elapsed)}` +
+                    (command ? `  ${colors.gray('|')} ${colors.cyan(command)}` : ''),
             ];
             if (item.lastLine)
                 group.push(`    ${colors.dim(item.lastLine)}`);
@@ -129,6 +180,11 @@ export class ProgressPanel {
             clearInterval(this.renderLoop);
         this.renderLoop = undefined;
         this.live.clear();
+        /** **Handed back, not left suspended.** A command keeps working after its panel comes down -
+         *  `ci` prints its summary, `run` its recap - and those writes have to go through a region
+         *  again, or they scroll the status line's own block. */
+        this.statusRegion?.resume();
+        this.statusRegion = undefined;
     }
     /**
      * Prints the final per-item recap (✓/X/○) and the "N succeeded, M failed (Xs)" summary line,

package/utils/status-region.d.ts

@@ -7,19 +7,64 @@
  * ✔ lint  3.6s                 <- once it ends
  * ```
  */
-export declare class StatusRegion {
+/**
+ * What a region has to offer to take the terminal over from `StatusRegion` - and `passThrough` is
+ * the whole of it.
+ *
+ * **Deliberately not `live`.** `StatusRegion.live` answers "does something own this terminal", which
+ * is what `runBin` reads and which stays true across a takeover; `ProgressPanel` spells the same
+ * question `enabled` and uses `live` for the `LiveRegion` itself. Putting it in the contract would
+ * force one of the two to be renamed for no gain - the handover needs somewhere to write, nothing
+ * more.
+ */
+export interface TerminalRegion {
+    /** Write `text` without corrupting the block: erase, write, redraw underneath. */
+    passThrough(text: string): void;
+}
+export declare class StatusRegion implements TerminalRegion {
     private readonly label;
     private readonly detail;
     private readonly region;
     private readonly startedAt;
     private timer?;
     private frame;
+    /**
+     * Who owns the terminal while this region is suspended - see `suspend`. Pass-through is forwarded
+     * there, so `runBin` keeps asking one object (`app.statusRegion`) whatever is actually drawing.
+     */
+    private takeover?;
     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;
+    /**
+     * **Hands the terminal to another region**, usually a `ProgressPanel` - the spinner stops, its
+     * line is erased, and pass-through is forwarded to `takeover` until `resume`.
+     *
+     * **Two live regions on one terminal cannot both work, and this is what enforces that.** Each
+     * redraws by moving the cursor up by *its own* line count; interleaved, every redraw lands on the
+     * other's rows. On screen that reads as the last line and the status line swapping places several
+     * times a second - reported on `rman ci`, and `rman build` has it too through `runBin`, whose
+     * pass-through went to this region while the panel was drawing. `LiveRegion`'s own doc has said
+     * "only one region is ever live" since it grew a `stream` parameter; nothing enforced it.
+     *
+     * `live` deliberately stays `true` while suspended: it answers "does something own this
+     * terminal", which is what `runBin` needs to decide to pipe rather than let a child scroll the
+     * screen. The answer to *which* region is the forwarding above.
+     */
+    suspend(takeover?: TerminalRegion): void;
+    /**
+     * Takes the terminal back - a no-op when it was never suspended.
+     *
+     * **The first frame waits for the timer rather than being drawn now**, which `start` does. A
+     * command is usually seconds from finishing when its panel comes down, and drawing immediately
+     * put one spinner frame on screen between the panel's recap and the result line that replaces it
+     * - a single flash, which is the thing this whole mechanism exists to remove. Anything still
+     * working is drawn 80ms later and nobody waits for it.
+     */
+    resume(): 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. */

package/utils/status-region.js

@@ -1,32 +1,5 @@
 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;
@@ -34,6 +7,11 @@ export class StatusRegion {
     startedAt = Date.now();
     timer;
     frame = 0;
+    /**
+     * Who owns the terminal while this region is suspended - see `suspend`. Pass-through is forwarded
+     * there, so `runBin` keeps asking one object (`app.statusRegion`) whatever is actually drawing.
+     */
+    takeover;
     constructor(label, detail = '', enabled) {
         this.label = label;
         this.detail = detail;
@@ -57,8 +35,55 @@ export class StatusRegion {
         }, FRAME_MS);
         this.timer.unref();
     }
+    /**
+     * **Hands the terminal to another region**, usually a `ProgressPanel` - the spinner stops, its
+     * line is erased, and pass-through is forwarded to `takeover` until `resume`.
+     *
+     * **Two live regions on one terminal cannot both work, and this is what enforces that.** Each
+     * redraws by moving the cursor up by *its own* line count; interleaved, every redraw lands on the
+     * other's rows. On screen that reads as the last line and the status line swapping places several
+     * times a second - reported on `rman ci`, and `rman build` has it too through `runBin`, whose
+     * pass-through went to this region while the panel was drawing. `LiveRegion`'s own doc has said
+     * "only one region is ever live" since it grew a `stream` parameter; nothing enforced it.
+     *
+     * `live` deliberately stays `true` while suspended: it answers "does something own this
+     * terminal", which is what `runBin` needs to decide to pipe rather than let a child scroll the
+     * screen. The answer to *which* region is the forwarding above.
+     */
+    suspend(takeover) {
+        this.takeover = takeover;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.region.clear();
+    }
+    /**
+     * Takes the terminal back - a no-op when it was never suspended.
+     *
+     * **The first frame waits for the timer rather than being drawn now**, which `start` does. A
+     * command is usually seconds from finishing when its panel comes down, and drawing immediately
+     * put one spinner frame on screen between the panel's recap and the result line that replaces it
+     * - a single flash, which is the thing this whole mechanism exists to remove. Anything still
+     * working is drawn 80ms later and nobody waits for it.
+     */
+    resume() {
+        if (!this.takeover && this.timer)
+            return;
+        this.takeover = undefined;
+        if (!this.region.enabled || this.timer)
+            return;
+        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.takeover) {
+            this.takeover.passThrough(text);
+            return;
+        }
         if (!this.region.enabled) {
             process.stderr.write(text);
             return;
@@ -69,6 +94,7 @@ export class StatusRegion {
     }
     /** Erases the spinner and leaves one line saying how it went. */
     stop(outcome) {
+        this.takeover = undefined;
         if (this.timer)
             clearInterval(this.timer);
         this.timer = undefined;