rman 2.7.0 → 2.9.0

package/services/version.service.d.ts

@@ -101,6 +101,8 @@ export declare namespace VersionService {
      * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
      * that have been `before`/`exec`/`after` for a long time.)
      */
+    /** `topo` is refused by default here, which is the one way this differs from `RunService`'s: a
+     *  version hook has no package ordering to join. */
     function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
     /**
      * Keeps a package's Dockerfile `org.opencontainers.image.version` label in step with the version

package/services/version.service.js

@@ -86,7 +86,10 @@ export class VersionService extends Service {
             const hook = (slot) => RunService.runLifecycleSlot(pkg, VERSION_LIFECYCLE, slot, RunService.normalizeScriptValue(
             /** `at`: the path is what tells a step function from a value one, and this is a fragment -
              *  without it a function here was called while the hook was being prepared. */
-            interpolator.interpolate({ config: pkg.config?.version?.[slot], scope, at: ['version', slot] }), `version.${slot}`));
+            interpolator.interpolate({ config: pkg.config?.version?.[slot], scope, at: ['version', slot] }), `version.${slot}`, 
+            /** A version hook runs for one package around its own version write - there is no
+             *  package graph here to wait on, so `topo` is refused rather than silently ignored. */
+            { topo: false }));
             await hook('before');
             /** Through the manifest, not through a `package.json` field: where a version is written is
              *  the provider's business (see `Plugin`'s manifest members), and this is the one place rman changes
@@ -286,8 +289,10 @@ export class VersionService extends Service {
      * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
      * that have been `before`/`exec`/`after` for a long time.)
      */
+    /** `topo` is refused by default here, which is the one way this differs from `RunService`'s: a
+     *  version hook has no package ordering to join. */
     function normalizeScriptValue(value, at) {
-        return RunService.normalizeScriptValue(value, at);
+        return RunService.normalizeScriptValue(value, at, { topo: false });
     }
     VersionService.normalizeScriptValue = normalizeScriptValue;
     /**

package/utils/progress-panel.js

@@ -45,7 +45,7 @@ export 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, stepsTotal) {
-        const item = { name, status: 'pending', stepsTotal, log: [] };
+        const item = new PanelItem(name, stepsTotal);
         this.items.set(name, item);
         return item;
     }
@@ -134,28 +134,46 @@ export class ProgressPanel {
             `${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
-         *  block taller than the terminal breaks cursor-up math (the terminal scrolls instead of
-         *  the cursor moving, so redraws land in the wrong place and pile up). */
+        /**
+         * **A package that failed stays on the list, under the ones still working.**
+         * It used to vanish the moment it failed, so on a long run the only sign that anything had gone
+         * wrong was a count in the header - and whatever it printed was not read until the recap, by
+         * which time the run had been going for another half-minute.
+         *
+         * **Below the running rows, and only with the space they leave.** Work in progress is what the
+         * panel is for; a repository that fails early would otherwise fill the block with corpses and
+         * push the live rows off the screen. One line each rather than two, so more of them fit - a
+         * failed row's value is that it is *named*, and its output is replayed in full at the end.
+         */
+        const failedList = [...this.items.values()].filter(i => i.status === 'failed');
+        /** Leave room for the header, a safety margin, and a possible "N more" line - a block taller
+         *  than the terminal breaks cursor-up math (the terminal scrolls instead of the cursor moving,
+         *  so redraws land in the wrong place and pile up). */
         const budget = Math.max(0, (process.stdout.rows || 24) - 3);
+        const width = process.stdout.columns || 80;
         let used = 0;
-        let shown = 0;
-        for (const item of runningList) {
-            const elapsed = item.startedAt ? formatDuration(Date.now() - item.startedAt) : '';
+        let shownRunning = 0;
+        let shownFailed = 0;
+        /** The fixed-width half of a row, plus the command truncated into whatever is left. */
+        const describe = (item, elapsed) => {
             const step = item.stepsTotal && item.stepsTotal > 1 && item.stepIndex != null
                 ? `${item.currentStep} (${item.stepIndex + 1}/${item.stepsTotal})`
                 : item.currentStep || '';
-            /** Measured against the *plain* text: every piece below is wrapped in escape sequences, and
+            /** Measured against the *plain* text: every piece 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 command = truncate(item.currentCommand ?? '', (process.stdout.columns || 80) - fixed - 2);
+            return { step, command: truncate(item.currentCommand ?? '', width - fixed - 2) };
+        };
+        for (const item of runningList) {
+            const elapsed = item.startedAt ? formatDuration(Date.now() - item.startedAt) : '';
+            const { step, command } = describe(item, elapsed);
             /**
              * **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.
+             * 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)}  ${colors.yellow(elapsed)}` +
@@ -167,11 +185,27 @@ export class ProgressPanel {
                 break;
             lines.push(...group);
             used += group.length;
-            shown++;
+            shownRunning++;
+        }
+        for (const item of failedList) {
+            if (used + 1 > budget)
+                break;
+            const elapsed = item.startedAt && item.finishedAt ? formatDuration(item.finishedAt - item.startedAt) : '';
+            const { step, command } = describe(item, elapsed);
+            lines.push(`${colors.red.bold('✖')} ${colors.bold(item.name)}  ${colors.gray(step)}  ${colors.yellow(elapsed)}` +
+                (command ? `  ${colors.gray('|')} ${colors.red(command)}` : ''));
+            used++;
+            shownFailed++;
         }
-        const remaining = runningList.length - shown;
-        if (remaining > 0)
-            lines.push(colors.gray(`… and ${remaining} more running`));
+        /** One line for both, or a run with rows cut from each would need two and the block is already
+         *  budgeted to the row. */
+        const hidden = [];
+        if (runningList.length > shownRunning)
+            hidden.push(`${runningList.length - shownRunning} more running`);
+        if (failedList.length > shownFailed)
+            hidden.push(`${failedList.length - shownFailed} more failed`);
+        if (hidden.length)
+            lines.push(colors.gray(`… and ${hidden.join(', ')}`));
         this.live.render(lines);
     }
     /** Stops the redraw loop and erases the panel, leaving the cursor where it started. */
@@ -267,3 +301,51 @@ function renderProgressBar(done, total, width = 24) {
     const filled = Math.max(0, Math.min(width, cells));
     return colors.green('█'.repeat(filled)) + colors.gray('░'.repeat(width - filled));
 }
+/**
+ * What `addItem` hands back - a `ProgressItem` whose `currentStep` and `currentCommand` clear
+ * `lastLine` when they change.
+ */
+/* **Accessors rather than a line at each call site**, because the call sites are four services and
+ * a command and the one that forgets is invisible: stale output under a new command does not look
+ * like a bug, it looks like output. Reported from `ci`, where the row read
+ * `install (2/2) | npm install` over `removed node_modules, package-lock.json` - the wipe's line,
+ * sitting under the install's command as though it belonged to it.
+ *
+ * **Cleared where it changes, not at render time.** The panel redraws every 100ms, so comparing
+ * there would race a line that arrived between the change and the next frame and throw away real
+ * output. This is synchronous with the assignment.
+ */
+class PanelItem {
+    name;
+    status = 'pending';
+    stepIndex;
+    stepsTotal;
+    lastLine;
+    startedAt;
+    finishedAt;
+    log = [];
+    _currentStep;
+    _currentCommand;
+    constructor(name, stepsTotal) {
+        this.name = name;
+        this.stepsTotal = stepsTotal;
+    }
+    get currentStep() {
+        return this._currentStep;
+    }
+    set currentStep(value) {
+        if (value === this._currentStep)
+            return;
+        this._currentStep = value;
+        this.lastLine = undefined;
+    }
+    get currentCommand() {
+        return this._currentCommand;
+    }
+    set currentCommand(value) {
+        if (value === this._currentCommand)
+            return;
+        this._currentCommand = value;
+        this.lastLine = undefined;
+    }
+}

package/utils/run-bin.d.ts

@@ -27,6 +27,10 @@ export interface RunBinOptions {
      *   even then. An explicit `stdio` still wins over all of this.
      */
     logLevel?: LogLevel;
+    /**
+     * Called once per line of the child's output **instead of writing it to the terminal**.
+     */
+    onLine?: (line: string) => void;
     env?: Record<string, string | undefined>;
 }
 export interface RunBinResult {

package/utils/run-bin.js

@@ -39,7 +39,11 @@ export async function runBin(bin, argv, options = {}) {
     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 ?? (region ? 'pipe' : atLeast('info') ? 'inherit' : 'pipe');
+    /** **`onLine` forces `pipe` the same way a live region does.** Left to the default, a caller at
+     *  `info` would get `inherit` - the child writes straight to the terminal, `child.stdout` is
+     *  null, and the callback is never called at all. An option that silently does nothing is worse
+     *  than one that does not exist. */
+    const stdio = options.stdio ?? (options.onLine || 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, {
@@ -74,6 +78,14 @@ export async function runBin(bin, argv, options = {}) {
     const collect = (d) => {
         const text = d.toString();
         output += text;
+        /** A caller taking the lines owns them - it is showing them somewhere of its own, and writing
+         *  them here as well would both double them and scroll whatever it is drawing. */
+        if (options.onLine) {
+            for (const line of text.split(/\r?\n/))
+                if (line)
+                    options.onLine(line);
+            return;
+        }
         if (region && atLeast('info'))
             region.passThrough(text);
     };
@@ -89,7 +101,7 @@ export async function runBin(bin, argv, options = {}) {
             /** 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. */
             /** Already streamed through the region, so printing it again would double it. */
-            if (stdio === 'pipe' && output && logLevel !== 'silent' && !(region && atLeast('info'))) {
+            if (stdio === 'pipe' && output && logLevel !== 'silent' && !options.onLine && !(region && atLeast('info'))) {
                 process.stderr.write(output);
             }
             const err = new Error(`"${bin} ${argv.join(' ')}" exited with code ${code}`);

package/utils/run-options.d.ts

@@ -1,4 +1,48 @@
 import type { RunService } from '../services/run.service.js';
+/**
+ * The three scheduling flags any command that sweeps packages can take - `--parallel`, `--bail`,
+ * `--progress`.
+ *
+ * **Exported as a group for the reason `packageFilterOptions` is**: a command spreading it gets the
+ * flags spelled and behaving exactly as `run`'s, where restating them means `--parallel` quietly
+ * accepting a number on one command and not on another. `--parallel`'s `coerce` is the part nobody
+ * would copy correctly - it takes a boolean *or* a number, and the type of the parsed value is read
+ * off that function.
+ *
+ * **`--topo` is deliberately not in it.** `run`'s default is ordering on; a command reaching for
+ * this is sweeping packages with an independent tool, where a wait nobody asked for costs the whole
+ * point. A command that does want it declares it, and `forEachPackage` takes `topo` as an option.
+ *
+ * The `describe` texts here name no `.rmanrc run.<script>` key, because a command using them owns
+ * its own (`check.concurrency`) - which is also why `runOptions` keeps its own wording rather than
+ * spreading this.
+ */
+export declare const parallelOptions: {
+    parallel: {
+        target: "cli";
+        describe: string;
+        /** No `type`: the flag takes a boolean *or* a number, and `coerce` is what says so - which is
+         *  also where `OptionValue` reads this option's type from. */
+        coerce: (v: unknown) => boolean | number | undefined;
+    };
+    bail: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    progress: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+/** The scheduling half of `forEachPackage`'s options, read off argv - the mirror of
+ *  `readRunOptions` for a command that declared `parallelOptions`. */
+export declare function readParallelOptions(args: any): {
+    parallel?: boolean | number;
+    bail?: boolean;
+    progress?: boolean;
+};
 /**
  * Everything `run`, `build` and `test` accept - the package filter, the branch guard, `--from-root`, and
  * the scheduling flags on top.

package/utils/run-options.js

@@ -1,5 +1,60 @@
 import { branchGuardOptions } from './branch-guard.js';
 import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from './package-filter.js';
+/**
+ * The three scheduling flags any command that sweeps packages can take - `--parallel`, `--bail`,
+ * `--progress`.
+ *
+ * **Exported as a group for the reason `packageFilterOptions` is**: a command spreading it gets the
+ * flags spelled and behaving exactly as `run`'s, where restating them means `--parallel` quietly
+ * accepting a number on one command and not on another. `--parallel`'s `coerce` is the part nobody
+ * would copy correctly - it takes a boolean *or* a number, and the type of the parsed value is read
+ * off that function.
+ *
+ * **`--topo` is deliberately not in it.** `run`'s default is ordering on; a command reaching for
+ * this is sweeping packages with an independent tool, where a wait nobody asked for costs the whole
+ * point. A command that does want it declares it, and `forEachPackage` takes `topo` as an option.
+ *
+ * The `describe` texts here name no `.rmanrc run.<script>` key, because a command using them owns
+ * its own (`check.concurrency`) - which is also why `runOptions` keeps its own wording rather than
+ * spreading this.
+ */
+export const parallelOptions = {
+    parallel: {
+        target: 'cli',
+        describe: 'Max packages at once: omit/true for CPU count, a number for that many, false to run serially',
+        /** No `type`: the flag takes a boolean *or* a number, and `coerce` is what says so - which is
+         *  also where `OptionValue` reads this option's type from. */
+        coerce: (v) => {
+            if (v === undefined)
+                return undefined;
+            if (v === 'false' || v === false)
+                return false;
+            if (v === 'true' || v === true)
+                return true;
+            const n = Number(v);
+            return Number.isFinite(n) ? n : true;
+        },
+    },
+    bail: {
+        target: 'cli',
+        describe: 'Stop at the first failure. Default true.',
+        type: 'boolean',
+    },
+    progress: {
+        target: 'cli',
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
+        type: 'boolean',
+    },
+};
+/** The scheduling half of `forEachPackage`'s options, read off argv - the mirror of
+ *  `readRunOptions` for a command that declared `parallelOptions`. */
+export function readParallelOptions(args) {
+    return {
+        parallel: args.parallel,
+        bail: args.bail,
+        progress: args.progress,
+    };
+}
 /**
  * Everything `run`, `build` and `test` accept - the package filter, the branch guard, `--from-root`, and
  * the scheduling flags on top.