rman 2.10.1 → 2.11.1

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

package/core/classes/run-reporters.js

@@ -0,0 +1,135 @@
+import colors from 'ansi-colors';
+import { colorsPrintedOutput } from '../../utils/run-bin.js';
+import { LOG_LEVELS } 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.
+ */
+/* **Every line names its package.** Packages run concurrently, so one package's lines land between
+ * another's, and a step's own status line comes only once the step has ended - *below* its output.
+ * Unlabelled, a compiler error read as the package whose line happened to sit above it: reported on
+ * opra, where `@opra/api-ui`'s TS2307 printed under `@opra/openapi ┆ after success` and the
+ * `api-ui ┆ exec failed` it belonged to came three lines later.
+ *
+ * **A step's lines are written to the stream, never through `console`.** A function step's own
+ * `console` is captured and arrives here as `output` events, synchronously and still inside that
+ * step's async context - so a `console.log` from here would be captured again and come straight
+ * back. The step lines and the recap are written outside any step and use `console` as they always
+ * did. */
+export class PlainReporter {
+    commandName;
+    panel;
+    childEnv;
+    /** Four letters per level, as winston and log4j-style formats shorten them - `ERROR` keeps its five. */
+    levelTags = {
+        error: 'ERROR',
+        info: 'INFO',
+        verbose: 'VERB',
+    };
+    constructor(
+    /** What the per-step lines call the run - `run`, `build`, `check`. */
+    commandName, 
+    /** Whose tally the recap prints; absent for a reporter that only says rman's own messages. */
+    panel) {
+        this.commandName = commandName;
+        this.panel = panel;
+        /** A child is run without a terminal and its lines are printed by rman, so it would drop its
+         *  colour; this brings it back where our own stdout is a terminal - and only the colour, since
+         *  tools gate their live output on `isTTY`, which stays false. */
+        this.childEnv = colorsPrintedOutput() ? { FORCE_COLOR: '1' } : undefined;
+    }
+    report(event, origin) {
+        switch (event.event) {
+            case 'start':
+                if (origin)
+                    this.started(event, origin);
+                return;
+            case 'output':
+                if (origin)
+                    this.output(event, origin);
+                return;
+            case 'end':
+                if (origin)
+                    this.ended(event, origin);
+                return;
+            case 'summary':
+                this.panel?.printSummary();
+                return;
+            case 'message':
+                console.log(event.level === 'error' ? colors.red(event.message) : colors.gray(event.message));
+        }
+    }
+    /** The `executing` line, at `verbose` only - rman's old behaviour, hidden by default. */
+    started(event, origin) {
+        if (!this.atLeast(origin.logLevel, 'verbose'))
+            return;
+        console.log(this.levelTag('verbose'), this.commandName, colors.cyan(event.package), colors.gray('┆'), colors.cyanBright.bold(event.step), colors.cyanBright.bold('executing'), ...this.describing(origin));
+    }
+    /** 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'`). */
+    /* **Red only where rman knows, and the stream is not knowing.** It was "red on stderr" for one
+     * build, and every progress line went red with it: dpdm prints `Start analyzing dependencies...`
+     * and `Analyze done!` to stderr, as spinner libraries do. In the other direction tsc writes its
+     * diagnostics to **stdout** (measured: a type error, exit 2, one line on stdout, none on stderr).
+     * Neither direction holds. A line is printed as it arrives, before anything knows whether its
+     * step will fail, so what is left is the message rman writes itself - a function step's throw,
+     * `runBin`'s `exited with code`. Reading the text for `error` is a guess: a test runner prints
+     * "0 errors" on success. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- the panel's override needs the row
+    output(event, origin) {
+        const name = event.level === 'error' ? colors.red(event.package) : colors.cyan(event.package);
+        const prefix = name + ' ' + colors.gray('┆') + ' ';
+        (event.stream === 'stderr' ? process.stderr : process.stdout).write(prefix + event.line + '\n');
+    }
+    /** `[INFO] build pkg ┆ exec success ┆ tsc -b  (123 ms)` - suppressed below `info` unless it failed,
+     *  and under `silent` even then. */
+    ended(event, origin) {
+        const failed = event.status === 'failed';
+        if (!failed && !this.atLeast(origin.logLevel, 'info'))
+            return;
+        if (failed && origin.logLevel === 'silent')
+            return;
+        console.log(this.levelTag(failed ? 'error' : 'info'), this.commandName, failed ? colors.red(event.package) : colors.cyan(event.package), colors.gray('┆'), colors.cyanBright.bold(event.step), failed ? colors.red.bold('failed') : colors.green.bold('success'), ...this.describing(origin), colors.yellow(` (${event.ms} ms)`));
+    }
+    /**
+     * A line's own level as `[INFO]`, `[VERB]`, `[ERROR]` - upper case, four letters but for `ERROR`, in
+     * the level's colour.
+     */
+    /* **The line's level, not the package's threshold.** `origin.logLevel` decides which lines are
+     * printed; the tag says what this line is. Printing the threshold would tag a success line `[VERB]`
+     * in a package set to `verbose` - winston and the rest tag the message, not the logger. */
+    levelTag(level) {
+        const tag = `[${this.levelTags[level]}]`;
+        return level === 'error' ? colors.red(tag) : level === 'info' ? colors.green(tag) : colors.magenta(tag);
+    }
+    /** Whether `level` prints what `wanted` does. */
+    atLeast(level, wanted) {
+        return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(wanted);
+    }
+    /** 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. */
+    describing(origin) {
+        return origin.label ? [colors.gray('┆'), origin.label] : [];
+    }
+}
+/**
+ * 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 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. */
+    childEnv = undefined;
+    constructor(commandName, panel) {
+        super(commandName, panel);
+    }
+    /** The row names the step itself; there is no separate line to print. */
+    started() { }
+    output(event, origin) {
+        origin.item.log.push(event.line);
+        origin.item.lastLine = event.line;
+    }
+    /** The row shows the step's outcome; the recap prints the package's. */
+    ended() { }
+}

package/core/classes/service.d.ts

@@ -1,5 +1,5 @@
-import type { Logger } from '../../utils/logger.js';
 import type { RmanApplication } from '../application.js';
+import type { Logger } from './logger.js';
 import type { Repository } from './repository.js';
 /**
  * **The one service shape.** Everything that does work on a repository is a class extending this,

package/core/command-builder.js

@@ -25,6 +25,9 @@ contextFor) {
          *  a field nothing ever sees - measured, `rman config` printed a status line above its own YAML
          *  document while declaring `printsDocument: true`. */
         printsDocument: meta.printsDocument,
+        /** A command declaring `--json` itself prints its result that way, and owns the flag: under the
+         *  global `--json` its stdout is that result, never a stream of log events. */
+        ownsJson: !!meta.config && 'json' in meta.config,
         builder: (cmd) => {
             if (meta.parserConfiguration)
                 cmd.parserConfiguration(meta.parserConfiguration);

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

@@ -1,8 +1,8 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
 import type { RmanConfig as CommandDeclaration } from '../../interfaces/rman-config.interface.js';
 import type { RunService } from '../../services/run.service.js';
-import type { Logger } from '../../utils/logger.js';
 import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
+import type { Logger } from '../classes/logger.js';
 import type { Package } from '../classes/package.js';
 import type { Repository } from '../classes/repository.js';
 import type { RunStepFn } from './run-step.js';
@@ -111,6 +111,10 @@ declare module 'yargs' {
          *  `CommandMetadata.printsDocument`. Here as well as there because `cli.ts` reads it off the
          *  *registration*, which is the only shape that reaches `program.command`. */
         printsDocument?: boolean;
+        /** Whether the command declares its own `--json`, printing its *result* as JSON - in which case
+         *  the global `--json` is that, and its log is not written to stdout. Carried from the
+         *  declaration by `toYargsCommand`, for the reason `printsDocument` is. */
+        ownsJson?: boolean;
     }
 }
 /**

package/core/interfaces/run-step.d.ts

@@ -1,5 +1,5 @@
-import type { Logger } from '../../utils/logger.js';
 import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
+import type { Logger } from '../classes/logger.js';
 import type { Package } from '../classes/package.js';
 import type { Repository } from '../classes/repository.js';
 /**
@@ -97,10 +97,10 @@ export interface RunStepObject {
      * later `topo: false` a true statement about the step that changes nothing about when it runs -
      * worth writing as intent, not a lever.
      *
-     * **A script whose steps mention `topo` at all is taken as the whole statement**: the first
-     * `true` is the barrier, and if no step says `true` there is no wait. A script where no step
-     * mentions it falls back to `run.<script>.topo` - on by default - waiting before its first step,
-     * which is where the wait has always been. `run.<script>.topo: false` and `--no-topo` still turn
+     * **The barrier is the first step marked `true`; with none, the first unmarked step**, which
+     * takes `run.<script>.topo` - on by default. A `false` frees its own step only, so a script waits
+     * nowhere only when every step says `false`. A package's own script replacing a marked `exec`
+     * (an npm `build`) keeps that mark. `run.<script>.topo: false` and `--no-topo` still turn
      * ordering off outright.
      *
      * Only in `run.<script>`: a `version` hook runs for one package around its own version write,

package/index.d.ts

@@ -135,11 +135,11 @@ export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from
 export { BinPath } from './utils/bin-path.js';
 /** A shell command, with the repository's local binaries on PATH - for a command string an author
  *  wrote. `runBin` is the one to reach for when the arguments are assembled in code. */
+export type { LogLevel } from './core/classes/logger.js';
+export { LOG_LEVELS, Logger, resolveRootLogLevel } from './core/classes/logger.js';
 export type { ExecOptions, ExecResult } from './utils/exec.js';
 export { exec } from './utils/exec.js';
 export { GitHelper } from './utils/git.js';
-export type { LogLevel } from './utils/logger.js';
-export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 /** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
  *  way every built-in does rather than inventing its own flags. */
 export { applyFromRootOption, applyPackageFilterOptions, filterPackages, fromRootOption, type PackageFilterOptions, packageFilterOptions, readFromRootOption, readPackageFilterOptions, ROOT_SELECTOR, } from './utils/package-filter.js';

package/index.js

@@ -120,9 +120,9 @@ export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
  *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';
+export { LOG_LEVELS, Logger, resolveRootLogLevel } from './core/classes/logger.js';
 export { exec } from './utils/exec.js';
 export { GitHelper } from './utils/git.js';
-export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 /** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
  *  way every built-in does rather than inventing its own flags. */
 export { applyFromRootOption, applyPackageFilterOptions, filterPackages, fromRootOption, packageFilterOptions, readFromRootOption, readPackageFilterOptions, ROOT_SELECTOR, } from './utils/package-filter.js';

package/package.json

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

package/services/exec.service.d.ts

@@ -1,5 +1,5 @@
+import { type LogLevel } from '../core/classes/logger.js';
 import { Service } from '../core/classes/service.js';
-import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured

package/services/exec.service.js

@@ -1,9 +1,9 @@
 import os from 'node:os';
 import colors from 'ansi-colors';
 import { Task } from 'power-tasks';
+import { Logger, resolveRootLogLevel } from '../core/classes/logger.js';
 import { Service } from '../core/classes/service.js';
 import { exec as execCommand } from '../utils/exec.js';
-import { Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { ProgressPanel } from '../utils/progress-panel.js';
 /**

package/services/run.service.d.ts

@@ -1,8 +1,9 @@
+import type { Reporter } from '../core/classes/log-sink.js';
+import { type LogLevel } from '../core/classes/logger.js';
 import type { Package } from '../core/classes/package.js';
 import type { Repository } from '../core/classes/repository.js';
 import { Service } from '../core/classes/service.js';
 import type { RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
-import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 import { ProgressPanel } from '../utils/progress-panel.js';
 /**
@@ -78,6 +79,24 @@ export declare class RunService extends Service {
     parallel<T>(tasks: readonly (() => Promise<T>)[], options?: {
         parallel?: boolean | number;
     }): Promise<T[]>;
+    /**
+     * The index of the step a package waits for its dependencies before, or `-1` when every step is
+     * marked `topo: false`: the first step marked `true`, else the first unmarked one.
+     */
+    protected barrierOf(steps: readonly {
+        topo?: boolean;
+    }[]): number;
+    /**
+     * A line of rman's own about the run - "nothing to run", "no package defines it" - on the console
+     * as prose, or as a `message` event under `--json`, where stdout belongs to the events. Also in the
+     * log file when there is one.
+     */
+    protected say(level: 'info' | 'error', message: string): void;
+    /**
+     * Who renders a run: the panel when it draws, plain lines when it does not, neither under `--json`
+     * (stdout belongs to the events) - plus the run's log, when the CLI asked for one.
+     */
+    protected reportersFor(commandName: string, panel?: ProgressPanel): Reporter[];
 }
 export declare namespace RunService {
     export interface Options extends PackageFilterOptions {
@@ -282,12 +301,12 @@ export declare namespace RunService {
      * Runs `fn` with `console` captured into `onLine`, and leaves the real `console` behind when the
      * last concurrent step is done.
      */
-    export function withCapturedConsole<T>(onLine: (line: string) => void, fn: () => T | Promise<T>): Promise<T>;
+    export function withCapturedConsole<T>(onLine: (line: string, stream?: 'stdout' | 'stderr') => void, fn: () => T | Promise<T>): Promise<T>;
     /**
      * `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, onLine?: (line: string) => void): RunStepContext;
+    export function createStepContext(pkg: Package, cwd: string, onCommand?: (command: string | undefined) => void, onLine?: (line: string, stream?: 'stdout' | 'stderr') => 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) -