rman 2.10.0 → 2.11.0

package/builtins/platforms/node/services/ci.service.d.ts

@@ -1,5 +1,5 @@
+import type { LogLevel } from '../../../../core/classes/logger.js';
 import type { Repository } from '../../../../core/classes/repository.js';
-import type { LogLevel } from '../../../../utils/logger.js';
 import type { PackageFilterOptions } from '../../../../utils/package-filter.js';
 export declare namespace CiService {
     /**

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

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import colors from 'ansi-colors';
+import { Logger, resolveRootLogLevel } from '../../../../core/classes/logger.js';
 import { exec } from '../../../../utils/exec.js';
-import { Logger, resolveRootLogLevel } from '../../../../utils/logger.js';
 import { filterPackages } from '../../../../utils/package-filter.js';
 import { formatDuration, ProgressPanel } from '../../../../utils/progress-panel.js';
 export var CiService;

package/builtins/platforms/node/services/clean.service.d.ts

@@ -1,5 +1,5 @@
+import type { LogLevel } from '../../../../core/classes/logger.js';
 import type { Repository } from '../../../../core/classes/repository.js';
-import type { LogLevel } from '../../../../utils/logger.js';
 import type { PackageFilterOptions } from '../../../../utils/package-filter.js';
 export declare namespace CleanService {
     interface Options extends PackageFilterOptions {

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

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import colors from 'ansi-colors';
 import fg from 'fast-glob';
-import { Logger, resolveRootLogLevel } from '../../../../utils/logger.js';
+import { Logger, resolveRootLogLevel } from '../../../../core/classes/logger.js';
 import { filterPackages } from '../../../../utils/package-filter.js';
 import { ProgressPanel } from '../../../../utils/progress-panel.js';
 export var CleanService;

package/cli.js

@@ -11,13 +11,14 @@ import yargs, {} from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { version } from './constants.js';
 import { RmanApplication } from './core/application.js';
+import { LogSink } from './core/classes/log-sink.js';
+import { LOG_LEVELS, Logger, resolveRootLogLevel } from './core/classes/logger.js';
 import { Repository } from './core/classes/repository.js';
 import { commandName, toYargsCommand } from './core/command-builder.js';
 import { assertNoBuiltinShadowing, defaultCommandGlobs, describeCommandSource, loadCustomCommands, } from './core/interfaces/custom-command.js';
 import { checkCustomCommand } from './core/plugin-loader.js';
 import { commandRegistry } from './interfaces/rman-config.interface.js';
 import { colorYaml } from './utils/color-yaml.js';
-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';
@@ -58,6 +59,20 @@ export async function runCli(options) {
                 'on, and the .rmanrc keys it reads - and run nothing',
             type: 'boolean',
             default: false,
+        })
+            /** **Global, not per command** - the format of what rman writes, the way `--log-level` is its
+             *  volume. A command that declares its own `--json` (`list`, `version`, `publish`, ...) keeps
+             *  that declaration and its meaning: its *result* as JSON, which the shared release workflow
+             *  parses. See `LogSink`. */
+            .option('json', {
+            describe: 'Write the log as JSON Lines - one event per line on stdout, and no panel, spinner or prose. ' +
+                'A command that prints a result (list, version, publish, ...) prints that result as JSON',
+            type: 'boolean',
+        })
+            .option('log-file', {
+            describe: 'Also write the log to this file - JSON Lines under --json, plain text lines otherwise. ' +
+                'Overwritten each run; relative to the current directory',
+            type: 'string',
         })
             .showHelpOnFail(false, 'Run with --help for available options')
             .fail((msg, err) => {
@@ -384,37 +399,80 @@ function interceptStatusLines(repository, program) {
         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();
+                /** Built for every command, used by whichever writes a log - see `LogSink`. A command owning
+                 *  `--json` prints its result as JSON, so the log must not be written to stdout beside it. */
+                const sink = new LogSink({ json: !!args.json && !spec.ownsJson, file: args.logFile, cwd: repository.cwd });
+                repository.app.logSink = sink;
                 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;
+                    return await runWithStatusLine(args, name);
                 }
                 finally {
-                    repository.app.statusRegion = undefined;
+                    sink.close();
+                    repository.app.logSink = undefined;
+                    warnUnhonoured(name, args, sink, !!spec.ownsJson);
                 }
             },
         });
+        async function runWithStatusLine(args, name) {
+            /** 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);
+            /** 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.
+             *
+             *  **Not drawn under `--no-progress`**, which asks for *no* live output rather than "no
+             *  panel": the spinner is progress too, and it would redraw over the plain lines such a run
+             *  prints. Its result line still prints, as it does without a TTY. Children are not told -
+             *  they are run without a terminal instead, see `RunService`'s panel-off path. */
+            const region = new StatusRegion(name, repository.name ?? '', args.progress === false ? false : undefined);
+            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;
+            }
+        }
     };
 }
+/**
+ * One line on stderr for a `--json` or `--log-file` that the command did not honour - so a flag that
+ * does nothing does not pass for one that worked.
+ *
+ * **Detected, not listed.** Whether a command writes a log is whatever went through the sink, so a
+ * command that starts writing one stops being warned about with no list to update - the rule
+ * `builtInNames` follows. On stderr because under `--json` stdout belongs to the events.
+ */
+/* **Why warn rather than refuse.** Both flags are global now, so yargs accepts them on every command,
+ * and `rman clean --json` - which `.strict()` used to reject as an unknown argument - would otherwise
+ * be quietly ignored. Refusing would turn a log option into a reason for a release step to fail. The
+ * commands that write a log so far are the ones whose steps run through `RunService` - `run`,
+ * `build`, `test`, and a command using `forEachPackage`. */
+function warnUnhonoured(name, args, sink, ownsJson) {
+    /** `--config` runs nothing by design, so nothing written is the right outcome there. */
+    if (sink.used || args.config)
+        return;
+    if (args.logFile) {
+        process.stderr.write(colors.yellow(`--log-file: "rman ${name}" does not write a log yet, so ${args.logFile} was not created.\n`));
+    }
+    if (args.json && !ownsJson) {
+        process.stderr.write(colors.yellow(`--json: "rman ${name}" has no JSON output yet; what it printed is unchanged.\n`));
+    }
+}
 /**
  * What a command would run with: its resolved options, the packages it would act on, and the
  * `.rmanrc` those packages carry.

package/commands/changelog.command.js

@@ -1,8 +1,8 @@
 import path from 'node:path';
 import colors from 'ansi-colors';
+import { Logger, resolveRootLogLevel } from '../core/classes/logger.js';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { ChangeHashService } from '../services/change-hash.service.js';
-import { Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
 import { ProgressPanel } from '../utils/progress-panel.js';
 const COMMAND = 'changelog';

package/commands/version.command.js

@@ -5,6 +5,7 @@ import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { VersionPlanService } from '../services/version-plan.service.js';
 import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { isNamedGroupKey, isSoloGroupKey, ROOT_GROUP_KEY } from '../utils/version-group.js';
 /**
  * Hoisted out of the metadata literal so the handler can be annotated against them - see
  * `RmanConfig.ArgsOf` for why an inferred `argv` and the metadata's own typo checking cannot both
@@ -289,12 +290,12 @@ function printApplied(result) {
 function printPlan(entries) {
     const table = new EasyTable();
     let first = true;
-    for (const { members, shared } of planBlocks(entries)) {
+    for (const { members } of planBlocks(entries)) {
         if (!first)
             table.pushDelimeter(PLAN_COLUMNS);
         first = false;
         for (const e of members)
-            printPlanRow(table, e, shared);
+            printPlanRow(table, e);
     }
     console.log(table.toString().trim());
 }
@@ -321,9 +322,9 @@ function printPlan(entries) {
  * repository that has nothing to group - noise standing in for structure. They share a block
  * because what they have in common is real: none of them is tied to anyone else.
  *
- * `shared` travels with each block because it is also what decides whether the `Group` column is
- * written at all - see `printPlanRow`. One partition, asked once, answering both questions; working
- * it out again at the cell would be a second rule that could disagree with the blocks beside it.
+ * The Group column is decided per row from the group key (`groupCell`), not from the block: both ask
+ * the same key the same question - is this package in a group, and did anybody name it - so they
+ * cannot disagree.
  */
 function planBlocks(entries) {
     /**
@@ -344,42 +345,31 @@ function planBlocks(entries) {
         else
             byGroup.set(e.groupKey, [e]);
     }
+    /**
+     * **Classified by the key, not by how many members a group has.** This was `group.length > 1`,
+     * which stands in for "is this a group" and is wrong in exactly one case: a group the repository
+     * *named* that happens to have a single member. Reported on a real repository - a package alone in
+     * `group: "abisena-iomt"` landed among the ungrouped and printed an empty Group cell, reading
+     * exactly like a package that had opted out. Its name decides its changelog file and its tag, so
+     * it is a line of its own whatever its size.
+     */
     const shared = [];
     const solo = [];
-    for (const group of byGroup.values()) {
-        if (group.length > 1)
-            shared.push({ members: group, shared: true });
+    for (const [key, group] of byGroup) {
+        if (isSoloGroupKey(key))
+            solo.push(...group);
         else
-            solo.push(group[0]);
+            shared.push({ members: group });
     }
-    return [
-        ...(root.length ? [{ members: root, shared: false }] : []),
-        ...shared,
-        ...(solo.length ? [{ members: solo, shared: false }] : []),
-    ];
+    return [...(root.length ? [{ members: root }] : []), ...shared, ...(solo.length ? [{ members: solo }] : [])];
 }
-/** `buildRootEntry`'s display label. Named here because `printPlanRow` has to recognize the one
- *  singleton whose group is worth printing, and a bare `'root'` in a condition reads as a guess. */
-const ROOT_GROUP = 'root';
 /** The column names in the order `printPlanRow` writes them - `pushDelimeter` has to be handed the
  *  same set, or the dashes appear under a column that does not exist yet. */
 const PLAN_COLUMNS = ['Status', 'Package', 'Group', 'From', '', 'To', 'Reason'];
-function printPlanRow(table, e, shared) {
+function printPlanRow(table, e) {
     table.cell('Status', statusLabel(e.status));
     table.cell('Package', colors.cyan(e.package.name));
-    /**
-     * **Blank for a package that shares its version line with nobody.** `resolveGroupKey` gives an
-     * ungrouped package a group of one named after the package, so the cell printed the Package
-     * column again, one column to the right - a word that looks like information and carries none.
-     * Worse, it made `(default)` and `(@panates/tsconfig)` read as the same *kind* of answer when one
-     * names a line four packages move along and the other names nothing at all.
-     *
-     * The root keeps its label: `root` is not its package name but what the row *is*, and it is the
-     * only thing on the line saying that the number below is the repository's identity rather than a
-     * release. So the test is `shared`, plus that one entry - not "does this string repeat the name",
-     * which would blank a genuine group that happened to be called after one of its members.
-     */
-    table.cell('Group', shared || e.group === ROOT_GROUP ? colors.gray(`(${e.group})`) : '');
+    table.cell('Group', groupCell(e));
     table.cell('From', e.from);
     /**
      * Gated on `to`, not on `status === 'bump'`, which is what kept the column blank on the one
@@ -394,6 +384,38 @@ function printPlanRow(table, e, shared) {
     table.cell('Reason', e.status === 'error' ? colors.red(e.reason ?? '') : colors.gray(e.reason ?? ''));
     table.newRow();
 }
+/**
+ * What the Group column says for one row - a **name** where the repository gave the group one, a
+ * **description** in grey parentheses where it did not, and nothing where there is no group at all.
+ */
+/* **A name and a description are different kinds of thing, and the cell says which.** `(default)`
+ * and `(root)` are not names anybody wrote - the default group is the line every package is on until
+ * told otherwise, and `root` is what the row *is*: the repository's release identity rather than a
+ * release. Both are notes about the row, so they read as notes. A named group (`group: "core"`) is a
+ * value the repository chose, decides its changelog file and its tag, and is printed as a value -
+ * bare, in the ordinary colour. Asked for directly: printed `(abisena-iomt)` in grey, a real group
+ * read like an annotation beside the default one.
+ *
+ * **Decided by the group key, never by the label.** A group may be *named* `default` or `root` - both
+ * pass `assertGroupName` - and testing the label would print it as the description it is spelling.
+ *
+ * **Blank for a package in no group** (`group: false`): its group of one is named after the package,
+ * so the cell would repeat the Package column - a word that looks like information and carries none.
+ *
+ * **Blank for a single-package repository's one package** too, which is the root and is in the
+ * default group: there is nothing there to group, and `(default)` on the only row would be noise. It
+ * was blank before this cell distinguished names from descriptions, and stays so. */
+function groupCell(e) {
+    if (e.groupKey === ROOT_GROUP_KEY)
+        return colors.gray(`(${e.group})`);
+    if (e.package.isRoot || isSoloGroupKey(e.groupKey))
+        return '';
+    if (isNamedGroupKey(e.groupKey))
+        return e.group;
+    /** The default group - and any key a custom planner's `resolveGroupKey` returns, which is a
+     *  description of its own making rather than a name the repository wrote. */
+    return colors.gray(`(${e.group})`);
+}
 function statusLabel(status) {
     switch (status) {
         case 'bump':

package/constants.js

@@ -1 +1 @@
-export const version = '2.10.0';
+export const version = '2.11.0';

package/core/application.d.ts

@@ -1,6 +1,7 @@
 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 type { LogSink } from './classes/log-sink.js';
+import { Logger, type LogLevel } from './classes/logger.js';
 import { Registry } from './classes/registry.js';
 import type { Repository } from './classes/repository.js';
 import type { ServiceFactory, ServiceMap } from './classes/service.js';
@@ -42,6 +43,12 @@ export declare class RmanApplication {
      * routes its output through `passThrough`.
      */
     statusRegion?: StatusRegion;
+    /**
+     * Where the run's log goes besides the screen - the global `--json` and `--log-file`. Set and
+     * closed by `cli.ts` around each command, like `statusRegion`; absent for a caller that did not
+     * come through the CLI, which writes no log.
+     */
+    logSink?: LogSink;
     /**
      * The **plugins** themselves, in declaration order - what a config named, before the platforms
      * were taken out of them.

package/core/application.js

@@ -7,7 +7,7 @@ import { ImportService } from '../services/import.service.js';
 import { ListService } from '../services/list.service.js';
 import { RunService } from '../services/run.service.js';
 import { VersionService } from '../services/version.service.js';
-import { Logger } from '../utils/logger.js';
+import { Logger } from './classes/logger.js';
 import { Registry } from './classes/registry.js';
 import { basePlatform } from './interfaces/plugin.js';
 /**
@@ -50,6 +50,12 @@ export class RmanApplication {
      * 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;
+    /**
+     * Where the run's log goes besides the screen - the global `--json` and `--log-file`. Set and
+     * closed by `cli.ts` around each command, like `statusRegion`; absent for a caller that did not
+     * come through the CLI, which writes no log.
+     */
+    logSink;
     /**
      * The **plugins** themselves, in declaration order - what a config named, before the platforms
      * were taken out of them.

package/core/classes/log-sink.d.ts

@@ -0,0 +1,99 @@
+import type { ProgressItem } from '../../utils/progress-panel.js';
+import type { LogLevel } from './logger.js';
+/**
+ * One thing that happened during a run, in the order it happened. The JSON form is exactly this
+ * object with a `time` added; the text form is one line per event.
+ */
+export type LogEvent = {
+    event: 'start';
+    package: string;
+    step: string;
+    command?: string;
+} | {
+    event: 'output';
+    package: string;
+    stream: 'stdout' | 'stderr';
+    line: string;
+    /** Set on a line rman itself wrote to say why a step failed - never inferred from the stream. */
+    level?: 'error';
+} | {
+    event: 'end';
+    package: string;
+    step: string;
+    status: 'success' | 'failed';
+    ms: number;
+    error?: string;
+} | {
+    event: 'summary';
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    ms: number;
+} | {
+    event: 'message';
+    level: 'info' | 'error';
+    message: string;
+};
+/**
+ * Something a run's events are rendered by - the screen, the `--json` stream, a log file.
+ *
+ * The scheduler produces each event once and hands it to every reporter the run has; none of them
+ * knows the others exist. Adding a destination is a reporter, never another branch where the event
+ * is produced.
+ */
+export interface Reporter {
+    /**
+     * One event. `origin` is given for every event that belongs to a package - which row it is, the
+     * package's own log level, and the step's label - and is absent for the run's own (`summary`,
+     * `message`).
+     */
+    report(event: LogEvent, origin?: ReportOrigin): void;
+    /**
+     * Environment a child should be started with for this reporter to render its lines - `FORCE_COLOR`
+     * where a reporter prints them to a terminal, nothing where colour would only be stripped again.
+     */
+    readonly childEnv?: Record<string, string>;
+}
+/** Which package an event is about, as a screen reporter needs to know it. */
+export interface ReportOrigin {
+    /** The package's row - the run's state for it, whether or not a panel is drawing it. */
+    item: ProgressItem;
+    /** The package's own `run.<script>.logLevel`, which decides what a plain screen prints. */
+    logLevel: LogLevel;
+    /** The step's label for a one-line-per-step log; empty for an anonymous function. */
+    label?: string;
+}
+/**
+ * Where a run's log goes besides the screen - the global `--json` and `--log-file`.
+ *
+ * - **`--json`**: the log is written to stdout as JSON Lines, one event per line, and nothing else
+ *   is - no panel, no spinner, no prose.
+ * - **`--log-file <path>`**: the log is written to that file, in the same format the console uses -
+ *   JSON Lines under `--json`, plain text lines otherwise.
+ *
+ * One per invocation, on `RmanApplication.logSink`, beside `statusRegion` and for the same reason:
+ * what writes to it is handed the application already, so nothing reaches for ambient state.
+ */
+export declare class LogSink implements Reporter {
+    /** The console format is JSON Lines - so nothing but events may reach stdout. */
+    readonly json: boolean;
+    /** Whether anything was written - read by the CLI to warn about a flag nothing honoured. */
+    used: boolean;
+    private fd?;
+    private readonly file?;
+    constructor(options: {
+        /** Write the log to stdout as JSON Lines, and use that format for the file. */
+        json?: boolean;
+        /** Where to write the log; resolved against `cwd`. */
+        file?: string;
+        cwd?: string;
+    });
+    /** Whether an event would go anywhere. A caller can skip building one when it would not. */
+    get active(): boolean;
+    /** The resolved file, for the message that reports it. */
+    get filePath(): string | undefined;
+    report(event: LogEvent): void;
+    /** Closes the file, if one was opened. Safe to call twice. */
+    close(): void;
+    protected append(text: string): void;
+}

package/core/classes/log-sink.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Where a run's log goes besides the screen - the global `--json` and `--log-file`.
+ *
+ * - **`--json`**: the log is written to stdout as JSON Lines, one event per line, and nothing else
+ *   is - no panel, no spinner, no prose.
+ * - **`--log-file <path>`**: the log is written to that file, in the same format the console uses -
+ *   JSON Lines under `--json`, plain text lines otherwise.
+ *
+ * One per invocation, on `RmanApplication.logSink`, beside `statusRegion` and for the same reason:
+ * what writes to it is handed the application already, so nothing reaches for ambient state.
+ */
+/* **A log, not an answer.** `list`, `version`, `publish`, `config`, `info` and `github-release`
+ * declare their own `--json`, and what it prints is the command's *result* - a contract the shared
+ * release workflow reads with `jq` (`rman publish --dry-run --json`, `rman list --json`). This never
+ * writes to stdout for one of those: the result stays where it was, in the shape it had.
+ *
+ * **Every line is stripped of escape sequences** before it is written anywhere. A child piped with
+ * `FORCE_COLOR` carries colour, and a JSON string or a log file holding `\u001b[32m` is noise to every
+ * reader that is not a terminal - which is every reader of either.
+ *
+ * **The file is opened on the first event, not up front**, so a command that writes no log leaves
+ * no empty file behind - and `used` stays false, which is how the CLI can say so. Written
+ * synchronously, line by line: an interrupted run keeps every line written before the interrupt,
+ * and lines from concurrent packages stay whole and in order. */
+export class LogSink {
+    /** The console format is JSON Lines - so nothing but events may reach stdout. */
+    json;
+    /** Whether anything was written - read by the CLI to warn about a flag nothing honoured. */
+    used = false;
+    fd;
+    file;
+    constructor(options) {
+        this.json = !!options.json;
+        this.file = options.file ? path.resolve(options.cwd ?? process.cwd(), options.file) : undefined;
+    }
+    /** Whether an event would go anywhere. A caller can skip building one when it would not. */
+    get active() {
+        return this.json || !!this.file;
+    }
+    /** The resolved file, for the message that reports it. */
+    get filePath() {
+        return this.file;
+    }
+    report(event) {
+        if (!this.active)
+            return;
+        this.used = true;
+        const time = new Date().toISOString();
+        const clean = stripEvent(event);
+        const json = JSON.stringify({ time, ...clean });
+        if (this.json)
+            process.stdout.write(json + '\n');
+        if (this.file)
+            this.append((this.json ? json : textLine(time, clean)) + '\n');
+    }
+    /** Closes the file, if one was opened. Safe to call twice. */
+    close() {
+        if (this.fd === undefined)
+            return;
+        fs.closeSync(this.fd);
+        this.fd = undefined;
+    }
+    append(text) {
+        if (this.fd === undefined) {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            this.fd = fs.openSync(this.file, 'w');
+        }
+        fs.writeSync(this.fd, text);
+    }
+}
+/** One event as a line of the text log: the time, the package in brackets, and what happened. */
+function textLine(time, e) {
+    switch (e.event) {
+        case 'start':
+            return `${time} [${e.package}] ▶ ${e.step}${e.command ? ` | ${e.command}` : ''}`;
+        case 'output':
+            return `${time} [${e.package}] ${e.line}`;
+        case 'end':
+            return (`${time} [${e.package}] ${e.status === 'success' ? '✔' : '✖'} ${e.step} ${e.status} (${e.ms} ms)` +
+                (e.error ? `\n${time} [${e.package}] ${e.error.split('\n').join(`\n${time} [${e.package}] `)}` : ''));
+        case 'summary':
+            return (`${time} ${e.succeeded} succeeded, ${e.failed} failed` +
+                (e.skipped ? `, ${e.skipped} skipped` : '') +
+                ` (${e.ms} ms)`);
+        case 'message':
+            return `${time} ${e.message}`;
+    }
+}
+/** Every string field of an event, with escape sequences removed. */
+function stripEvent(e) {
+    const out = {};
+    for (const [k, v] of Object.entries(e))
+        out[k] = typeof v === 'string' ? stripAnsi(v) : v;
+    return out;
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+}

package/{utils → core/classes}/logger.d.ts

@@ -1,4 +1,4 @@
-import type { Repository } from '../core/classes/repository.js';
+import type { Repository } from './repository.js';
 export type LogLevel = 'silent' | 'error' | 'info' | 'verbose';
 export declare const LOG_LEVELS: LogLevel[];
 /**

package/core/classes/run-reporters.d.ts

@@ -0,0 +1,64 @@
+import type { ProgressPanel } from '../../utils/progress-panel.js';
+import type { LogEvent, Reporter, ReportOrigin } from './log-sink.js';
+import { type LogLevel } from './logger.js';
+/**
+ * The screen with no live panel: each line a step prints, led by its package, and one line per step
+ * when it ends - the output `--no-progress`, a pipe or CI gets.
+ */
+export declare class PlainReporter implements Reporter {
+    /** What the per-step lines call the run - `run`, `build`, `check`. */
+    protected readonly commandName: string;
+    /** Whose tally the recap prints; absent for a reporter that only says rman's own messages. */
+    protected readonly panel?: ProgressPanel | undefined;
+    readonly childEnv: Record<string, string> | undefined;
+    /** Four letters per level, as winston and log4j-style formats shorten them - `ERROR` keeps its five. */
+    protected readonly levelTags: Readonly<Record<Exclude<LogLevel, 'silent'>, string>>;
+    constructor(
+    /** What the per-step lines call the run - `run`, `build`, `check`. */
+    commandName: string, 
+    /** Whose tally the recap prints; absent for a reporter that only says rman's own messages. */
+    panel?: ProgressPanel | undefined);
+    report(event: LogEvent, origin?: ReportOrigin): void;
+    /** The `executing` line, at `verbose` only - rman's old behaviour, hidden by default. */
+    protected started(event: Extract<LogEvent, {
+        event: 'start';
+    }>, origin: ReportOrigin): void;
+    /** One line of a step's output, to the stream it came from, led by its package - in red when rman
+     *  itself wrote the line to say why the step failed (`level: 'error'`). */
+    protected output(event: Extract<LogEvent, {
+        event: 'output';
+    }>, origin: ReportOrigin): void;
+    /** `[INFO] build pkg ┆ exec success ┆ tsc -b  (123 ms)` - suppressed below `info` unless it failed,
+     *  and under `silent` even then. */
+    protected ended(event: Extract<LogEvent, {
+        event: 'end';
+    }>, origin: ReportOrigin): void;
+    /**
+     * A line's own level as `[INFO]`, `[VERB]`, `[ERROR]` - upper case, four letters but for `ERROR`, in
+     * the level's colour.
+     */
+    protected levelTag(level: Exclude<LogLevel, 'silent'>): string;
+    /** Whether `level` prints what `wanted` does. */
+    protected atLeast(level: LogLevel, wanted: LogLevel): boolean;
+    /** The `┆ <what it runs>` tail of a step 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 and a separator with nothing after it is noise. */
+    protected describing(origin: ReportOrigin): string[];
+}
+/**
+ * The screen while the live panel draws: a step's lines go to its package's row - the last one
+ * shown under it, all of them replayed if the package fails - and the recap lists every package.
+ */
+export declare class PanelReporter extends PlainReporter {
+    /** A child's lines are only stored, and replayed into a row whose width is measured - colour
+     *  would only be escape codes counted as text there. */
+    readonly childEnv: undefined;
+    constructor(commandName: string, panel: ProgressPanel);
+    /** The row names the step itself; there is no separate line to print. */
+    protected started(): void;
+    protected output(event: Extract<LogEvent, {
+        event: 'output';
+    }>, origin: ReportOrigin): void;
+    /** The row shows the step's outcome; the recap prints the package's. */
+    protected ended(): void;
+}