rman 2.10.1 → 2.11.1

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/builtins/platforms/node/services/publish.service.d.ts

@@ -43,6 +43,11 @@ export declare namespace PublishService {
          * goes green" is the most important sentence in the plan when it applies.
          */
         staged?: boolean;
+        /** Subdirectory to publish from, relative to the package's own directory - only consulted when
+         *  the package doesn't already declare its own `package.json` `publishConfig.directory` (npm's
+         *  native mechanism for this, which always wins when present). A plan option, because the
+         *  manifest in that directory is what the plan decides from. */
+        contents?: string;
     }
     interface ApplyOptions extends Options {
         packageManager?: CiService.PackageManager;
@@ -50,10 +55,6 @@ export declare namespace PublishService {
         access?: 'public' | 'restricted';
         /** `npm publish --otp <otp>` - a 2FA one-time password, for registries that require it. */
         otp?: string;
-        /** Subdirectory to publish from, relative to the package's own directory - only consulted when
-         *  the package doesn't already declare its own `package.json` `publishConfig.directory` (npm's
-         *  native mechanism for this, which always wins when present). */
-        contents?: string;
     }
     /** One package's outcome in a publish plan - see `getPlan`. */
     interface Entry {
@@ -101,7 +102,11 @@ export declare namespace PublishService {
      * queries it to decide, so it's safe to call any time, including as the plan a bare `rman
      * publish` shows before asking for confirmation.
      *
-     * A `private: true` package is always `'skip'`ped outright. Each remaining package's **dist-tag**
+     * **Whether a package is private is read from the manifest that would be published** - the one in
+     * its build directory when it publishes from one, its own otherwise. A build directory with no
+     * `package.json` is an `'error'`: nothing has been built to publish. A package `private` in its
+     * source with no `publishConfig` is skipped before that is asked, since it stays private in any
+     * manifest derived from it. Each remaining package's **dist-tag**
      * is settled next (`distTagFor`): usually derived from the version itself, `'error'` in the two
      * cases with nothing to derive - that one is about the invocation rather than the package, so it
      * is answered before anything touches the network. A package with uncommitted local changes is

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

@@ -72,21 +72,19 @@ function preparePublishManifest(pkg, publishDir, packagesByName) {
  *   builds a native module on install. The rest (`build`, `test`, `prepare`, ...) never reach the
  *   consumer - `prepare` runs for a git dependency, which builds from the repository, not from this
  *   tarball.
- * - `private` - it is a statement about the **source tree**, not about the artifact derived from it,
- *   and a manifest being published is by definition not private. rman's own gate normally stops a
- *   private package before this runs, so the line looks unreachable; it is not, because `private`
- *   is also how a repository keeps a stray `npm publish` out of the package directory while
- *   publishing `build/` on purpose. That is a real configuration - this repository ran it until
- *   `rman publish` became its own release path and the gate started refusing the thing it ships.
- *   A narrower guard (`prepublishOnly`, which never reaches a consumer either) says the same thing
- *   without claiming the artifact is unpublishable.
+ * - `private` - **only when the package declares a `publishConfig`**. A package configured to be
+ *   published that is also `private` is guarding its source tree against a stray `npm publish`,
+ *   not refusing to ship; one with no `publishConfig` means it, and keeps the flag. `getPlan`
+ *   decides from the manifest this produces, so the rule here *is* the publish rule - a preset
+ *   writing the build directory's manifest must apply the same one.
  * - `publishConfig.directory` - it pointed *here*; kept, it would point one level deeper again.
  */
 function derivePublishManifest(pkg, packagesByName) {
     const json = structuredClone(pkg.manifest.raw);
     resolveWorkspaceRanges(json, packagesByName);
     delete json.devDependencies;
-    delete json.private;
+    if (json.publishConfig)
+        delete json.private;
     if (json.scripts) {
         const kept = Object.fromEntries(Object.entries(json.scripts).filter(([name]) => CONSUMER_SCRIPTS.has(name)));
         if (Object.keys(kept).length)
@@ -129,7 +127,11 @@ export var PublishService;
      * queries it to decide, so it's safe to call any time, including as the plan a bare `rman
      * publish` shows before asking for confirmation.
      *
-     * A `private: true` package is always `'skip'`ped outright. Each remaining package's **dist-tag**
+     * **Whether a package is private is read from the manifest that would be published** - the one in
+     * its build directory when it publishes from one, its own otherwise. A build directory with no
+     * `package.json` is an `'error'`: nothing has been built to publish. A package `private` in its
+     * source with no `publishConfig` is skipped before that is asked, since it stays private in any
+     * manifest derived from it. Each remaining package's **dist-tag**
      * is settled next (`distTagFor`): usually derived from the version itself, `'error'` in the two
      * cases with nothing to derive - that one is about the invocation rather than the package, so it
      * is answered before anything touches the network. A package with uncommitted local changes is
@@ -187,7 +189,19 @@ export var PublishService;
                     reason: 'excluded via .rmanrc "publish.skip"',
                 });
             }
-            else if (pkg.isPrivate) {
+            else if (privateBySource(pkg)) {
+                entries.set(pkg.name, { package: pkg, version: pkg.version, status: 'skip', reason: 'private package' });
+            }
+            else if (!fs.existsSync(path.join(resolvePublishDir(pkg, options.contents), 'package.json'))) {
+                const dir = path.relative(pkg.dirname, resolvePublishDir(pkg, options.contents)) || '.';
+                entries.set(pkg.name, {
+                    package: pkg,
+                    version: pkg.version,
+                    status: 'error',
+                    reason: `nothing to publish in "${dir}" - it has no package.json; build the package first`,
+                });
+            }
+            else if (publishedManifestOf(pkg, options.contents).private) {
                 entries.set(pkg.name, { package: pkg, version: pkg.version, status: 'skip', reason: 'private package' });
             }
             else if (distTag.error) {
@@ -310,6 +324,27 @@ function resolvePublishDir(pkg, contentsOverride) {
     const rel = (typeof native === 'string' && native) || configured || contentsOverride;
     return rel ? path.resolve(pkg.dirname, rel) : pkg.dirname;
 }
+/** The manifest `npm publish` will read for `pkg` - its build directory's, or its own when it
+ *  publishes in place. */
+/* **Decided from the artifact, not the source**, because the two disagree about `private` and only
+ * one of them is published. Read before any build, the plan answered `skip - private package` for a
+ * single-package repository whose source carries `private: true` as a guard against a stray
+ * `npm publish` - while `derivePublishManifest` was removing that very flag from what it ships.
+ * Reported from `postgrejs-kysely`: version, tag and GitHub release all went through, and the
+ * registry got nothing. */
+function publishedManifestOf(pkg, contentsOverride) {
+    const dir = resolvePublishDir(pkg, contentsOverride);
+    if (path.resolve(dir) === path.resolve(pkg.dirname))
+        return pkg.manifest.raw;
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+}
+/** `private` in the source with no `publishConfig` - private in every manifest derived from it too,
+ *  so it is known without a build. */
+/* Asked first so an unbuilt private package is skipped rather than reported as unbuilt: opra's
+ * examples inherit `publish.npm.directory` from the shared preset and skip their build. */
+function privateBySource(pkg) {
+    return !!pkg.manifest.raw.private && !pkg.manifest.raw.publishConfig;
+}
 /**
  * Which registry a package's own version is asked about, and published to.
  *

package/builtins/publish-targets/npm/npm-publish-target.js

@@ -84,7 +84,6 @@ export class NpmPublishTarget {
             packageManager: ctx.args.packageManager,
             access: ctx.args.access,
             otp: ctx.args.otp,
-            contents: ctx.args.contents,
         });
     }
     /** The shared filters plus the two flags both halves need - read here rather than in the
@@ -103,6 +102,9 @@ export class NpmPublishTarget {
              *  flag was not given, so each package's own `publish.npm.staged` still decides - `false`
              *  here would mean `--no-staged` and silently overrule the config. */
             staged: ctx.args.staged,
+            /** The plan decides from the manifest in the directory being published, so it has to know
+             *  which directory that is. */
+            contents: ctx.args.contents,
         };
     }
 }

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,7 +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 { isSoloGroupKey } from '../utils/version-group.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
@@ -290,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());
 }
@@ -322,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) {
     /**
@@ -359,36 +359,17 @@ function planBlocks(entries) {
         if (isSoloGroupKey(key))
             solo.push(...group);
         else
-            shared.push({ members: group, shared: true });
+            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
@@ -403,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.1';
+export const version = '2.11.1';

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;
+}