rman 1.1.1 → 1.2.1

package/services/run.service.js

@@ -1,11 +1,13 @@
 import os from 'node:os';
+import { inspect } from 'node:util';
 import colors from 'ansi-colors';
 import { tokenize } from 'fast-tokenizer';
 import { Task } from 'power-tasks';
 import { exec } from '../utils/exec.js';
-import { LOG_LEVELS, resolveRootLogLevel } from '../utils/logger.js';
+import { LOG_LEVELS, Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { ProgressPanel } from '../utils/progress-panel.js';
+import { runBin } from '../utils/run-bin.js';
 export var RunService;
 (function (RunService) {
     /**
@@ -53,26 +55,88 @@ export var RunService;
      * the copies would sit in the file that writes versions - which now runs no command of its own at
      * all.
      *
-     * `fallback` is the caller's own configured command, **already evaluated**: `version`'s three
+     * `fallback` is the caller's own configured step(s), **already evaluated**: `version`'s three
      * paths are in `DEFERRED_PATHS` precisely because only the caller can bind
      * `${{ pkg.targetVersion }}`, so interpolating here would either be too early or need a scope this
      * service has no business holding.
+     *
+     * **A list, not one joined string.** `VersionService` used to `join(' && ')` an array into a
+     * single shell line, which a function step cannot be part of - and which quietly changed the
+     * semantics of the shell case too, since `cd x && y` in one process is not the same as two.
      */
     async function runLifecycleSlot(pkg, script, slot, fallback) {
         const own = contributedSlots(pkg, script)?.[slot] ?? [];
-        const commands = own.length ? own : fallback ? [fallback] : [];
-        for (const command of commands)
-            await exec(command, { cwd: pkg.dirname, stdio: 'inherit' });
+        const values = own.length ? own : (fallback ?? []);
+        for (const value of values) {
+            if (typeof value === 'function') {
+                await value(createStepContext(pkg, pkg.dirname));
+                continue;
+            }
+            await exec(value, { cwd: pkg.dirname, stdio: 'inherit' });
+        }
     }
     RunService.runLifecycleSlot = runLifecycleSlot;
     function getConfig(pkg, script) {
         const runCfg = pkg.config?.run;
         const cfg = runCfg && typeof runCfg === 'object' ? runCfg[script] : undefined;
-        if (typeof cfg === 'string' || Array.isArray(cfg))
+        /** The bare-value shorthand. A function is `typeof 'function'`, not `'object'`, so without
+         *  naming it here `run: { build: myFn }` fell through to the `{}` below - the long form would
+         *  have worked and the short one silently done nothing, an arbitrary difference. */
+        if (typeof cfg === 'string' || typeof cfg === 'function' || Array.isArray(cfg))
             return { exec: cfg };
         return cfg && typeof cfg === 'object' ? cfg : {};
     }
     RunService.getConfig = getConfig;
+    /**
+     * The context a function step or `if` is handed - see [`RunStepContext`](../core/run-step.ts).
+     *
+     * `runBin` and `logger` are bound to *this run* rather than left to be imported, which is the
+     * whole reason they are handed over: an imported `runBin` knows neither the cwd nor the resolved
+     * log level.
+     */
+    /**
+     * A `run.<script>.before`/`.exec`/`.after` (or `version.<slot>`) value: one step, or several to
+     * run in sequence. A shell command or a function, and a list may mix them.
+     *
+     * **Anything else throws, naming the path.** It used to `return []`, which meant a value rman did
+     * not recognize was dropped with no trace: writing a function here - the obvious guess, and now
+     * the supported form - produced `1 succeeded, 0 failed` with the step never run (measured). A
+     * configuration mistake has to be loud; silence here reads as success.
+     *
+     * Exported, and the only implementation: `VersionService` used to carry a second one that behaved
+     * differently, which is how `version.<slot>` came to join its array with `' && '`.
+     */
+    function normalizeScriptValue(value, at) {
+        const items = Array.isArray(value) ? value : [value];
+        const steps = [];
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            /** An empty string and an absent value are both "nothing here", which is how a `"[*]"` block
+             *  declaring a slot some packages don't use has always behaved. */
+            if (item === undefined || item === null || item === '')
+                continue;
+            if (typeof item === 'string' || typeof item === 'function') {
+                steps.push(item);
+                continue;
+            }
+            const where = Array.isArray(value) ? `${at}[${i}]` : at;
+            throw new Error(`"${where}" must be a shell command or a function, but it is ${describeValue(item)}.\n` +
+                `  A list of either (or both) runs them in sequence.`);
+        }
+        return steps;
+    }
+    RunService.normalizeScriptValue = normalizeScriptValue;
+    function createStepContext(pkg, cwd) {
+        const logLevel = resolveRootLogLevel(pkg.repository);
+        return {
+            pkg,
+            repository: pkg.repository,
+            cwd,
+            runBin: (bin, argv, opts) => runBin(bin, argv, { cwd, logLevel, ...opts }),
+            logger: new Logger(logLevel),
+        };
+    }
+    RunService.createStepContext = createStepContext;
     function resolveEnvPlaceholders(value) {
         return value.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => process.env[name] ?? '');
     }
@@ -180,7 +244,7 @@ export var RunService;
          *  abort using *its own* resolved bail setting (see `runSteps` below) - power-tasks' own
          *  `bail` is a single blanket policy for the whole batch, it can't vary per package. */
         let rootTask;
-        const runSteps = async (ctx, pkgLabel, steps, cwd, pkgBail, pkgLogLevel) => {
+        const runSteps = async (ctx, pkg, pkgLabel, steps, cwd, pkgBail, pkgLogLevel) => {
             ctx.status = 'running';
             ctx.startedAt = Date.now();
             try {
@@ -189,15 +253,14 @@ export var RunService;
                     ctx.currentStep = step.name;
                     ctx.stepIndex = i;
                     if (panel.enabled) {
-                        await exec(step.command, {
-                            cwd,
-                            stdio: 'pipe',
-                            onLine: (line, stdio) => {
-                                ctx.log.push(line);
-                                ctx.lastLine = line;
-                                void stdio;
-                            },
-                        });
+                        const onLine = (line) => {
+                            ctx.log.push(line);
+                            ctx.lastLine = line;
+                        };
+                        if (step.run)
+                            await runFunctionStep(step.run, pkg, cwd, onLine);
+                        else
+                            await exec(step.command, { cwd, stdio: 'pipe', onLine });
                     }
                     else {
                         /** Match the classic rman output: raw command output streams straight through
@@ -206,7 +269,12 @@ export var RunService;
                         const stepStart = Date.now();
                         let stepError;
                         try {
-                            await exec(step.command, { cwd, stdio: 'inherit' });
+                            /** No capture with the panel off: the step owns the terminal, exactly as a shell
+                             *  step's `stdio: 'inherit'` does. */
+                            if (step.run)
+                                await runFunctionStep(step.run, pkg, cwd);
+                            else
+                                await exec(step.command, { cwd, stdio: 'inherit' });
                         }
                         catch (e) {
                             stepError = e;
@@ -238,9 +306,12 @@ export var RunService;
          *  Only in a monorepo. Without one the root *is* the single package, already in the loop below
          *  with the same hooks and the same directory - a bookend would simply run each of them a
          *  second time. */
-        const rootIf = !cwdScope && repository.monorepo && parseIfExpr(rootCfg.if);
-        const rootIfPasses = rootIf ? await evaluateIf(repository, repository.rootPackage, rootIf, ifStatusCache) : true;
-        const rootSkipped = !!cwdScope || !repository.monorepo || rootCfg.skip === true || !rootIfPasses;
+        /** Short-circuited deliberately: a root already out of the run for a structural reason must not
+         *  have its `if` evaluated, now that evaluating one can mean calling the repository's own code. */
+        const rootSkipped = !!cwdScope ||
+            !repository.monorepo ||
+            rootCfg.skip === true ||
+            !(await passesIf(repository, repository.rootPackage, rootCfg.if, repository.dirname, ifStatusCache));
         const rootSteps = rootSkipped ? [] : getScriptSteps(repository.rootPackage, script);
         /** Filtered on the slot, not on `'pre' + script`: the step labels are `before`/`exec`/`after`
          *  now - the same words the config uses - rather than npm's `pre<script>` naming, which moved
@@ -253,7 +324,7 @@ export var RunService;
             const ctx = panel.addItem(rootPreName, rootPre.length);
             const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
             const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
-            children.push(new Task(() => runSteps(ctx, 'root', rootPre, repository.dirname, pkgBail, pkgLogLevel), {
+            children.push(new Task(() => runSteps(ctx, repository.rootPackage, 'root', rootPre, repository.dirname, pkgBail, pkgLogLevel), {
                 name: ctx.name,
                 exclusive: true,
             }));
@@ -263,8 +334,7 @@ export var RunService;
             const pkgCfg = getConfig(pkg, script);
             if (pkgCfg.skip === true)
                 continue;
-            const pkgIf = parseIfExpr(pkgCfg.if);
-            if (pkgIf && !(await evaluateIf(repository, pkg, pkgIf, ifStatusCache)))
+            if (!(await passesIf(repository, pkg, pkgCfg.if, pkg.dirname, ifStatusCache)))
                 continue;
             const steps = getScriptSteps(pkg, script);
             if (steps.length)
@@ -283,7 +353,7 @@ export var RunService;
             const dependencies = pkgTopo ? pkg.dependencies.filter(d => stepsByPackage.has(d.name)).map(d => d.name) : [];
             if (rootPre.length)
                 dependencies.push(rootPreName);
-            children.push(new Task(() => runSteps(ctx, pkg.name, steps, pkg.dirname, pkgBail, pkgLogLevel), {
+            children.push(new Task(() => runSteps(ctx, pkg, pkg.name, steps, pkg.dirname, pkgBail, pkgLogLevel), {
                 name: ctx.name,
                 dependencies,
             }));
@@ -292,7 +362,7 @@ export var RunService;
             const ctx = panel.addItem(rootPostName, rootPost.length);
             const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
             const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
-            children.push(new Task(() => runSteps(ctx, 'root', rootPost, repository.dirname, pkgBail, pkgLogLevel), {
+            children.push(new Task(() => runSteps(ctx, repository.rootPackage, 'root', rootPost, repository.dirname, pkgBail, pkgLogLevel), {
                 name: ctx.name,
                 exclusive: true,
                 /** Must wait for every package task to finish, not just be "exclusive" once it starts. */
@@ -375,7 +445,7 @@ function printLegacyExecutingLine(commandName, pkgLabel, step, level) {
     if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('verbose'))
         return;
     const sep = colors.gray('┆');
-    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), sep, step.command);
+    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), sep, step.label);
 }
 function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, error) {
     if (!error && LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('info'))
@@ -385,15 +455,77 @@ function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, err
     const sep = colors.gray('┆');
     const levelLabel = error ? colors.red('error') : colors.green('info');
     const status = error ? colors.red.bold('failed') : colors.green.bold('success');
-    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, sep, step.command, colors.yellow(` (${durationMs} ms)`));
+    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, sep, step.label, colors.yellow(` (${durationMs} ms)`));
 }
-/** A `run.<script>.before`/`.exec`/`.after` value: one command, or several to run in sequence. */
-function normalizeScriptValue(value) {
-    if (typeof value === 'string')
-        return value ? [value] : [];
+function describeValue(value) {
     if (Array.isArray(value))
-        return value.filter((v) => typeof v === 'string' && !!v);
-    return [];
+        return 'a nested array';
+    if (value && typeof value === 'object')
+        return 'an object';
+    return `a ${typeof value} (${JSON.stringify(value)})`;
+}
+/** One step, with the label the panel and the per-step log show. A function's own name - so
+ *  `function copyDocs()` and `const copyDocs = () => {}` both read as `copyDocs` - falling back to
+ *  the slot's own word for one passed inline, which has no name at all. */
+function toStep(slot, value) {
+    if (typeof value === 'function')
+        return { name: slot, label: value.name || `${slot} (js)`, run: value };
+    return { name: slot, label: value, command: value };
+}
+/**
+ * Runs a function step.
+ *
+ * **`console` is redirected while it runs, but only when the panel is on** - and that is the same
+ * split a shell step already makes. `exec` hands the panel its output through `stdio: 'pipe'` and
+ * `onLine`, so a function writing straight to the real stdout would print *over* the panel it is
+ * being rendered inside. With the panel off, `exec` uses `stdio: 'inherit'` and the step owns the
+ * terminal; a function gets the same, untouched.
+ *
+ * Restored in a `finally`, because a step that throws must not leave the rest of the run writing
+ * into a log nobody reads.
+ */
+async function runFunctionStep(run, pkg, cwd, onLine) {
+    const context = RunService.createStepContext(pkg, cwd);
+    if (!onLine) {
+        await run(context);
+        return;
+    }
+    const console_ = globalThis.console;
+    const original = {};
+    for (const method of CAPTURED_CONSOLE) {
+        original[method] = console_[method];
+        console_[method] = (...args) => {
+            /** Split, because one `console.log` may carry several lines and the panel's log is a list of
+             *  them - a multi-line entry would render as one unreadable row. */
+            for (const line of format(args).split('\n'))
+                onLine(line);
+        };
+    }
+    try {
+        await run(context);
+    }
+    finally {
+        for (const method of CAPTURED_CONSOLE)
+            console_[method] = original[method];
+    }
+}
+const CAPTURED_CONSOLE = ['log', 'info', 'warn', 'error', 'debug'];
+function format(args) {
+    return args.map(arg => (typeof arg === 'string' ? arg : inspect(arg))).join(' ');
+}
+/**
+ * Whether a script runs for `pkg` at all - `run.<script>.if`, in either of its two forms.
+ *
+ * The function form is checked **first**: `parseIfExpr` answers `undefined` for anything that is
+ * not a string, which the caller reads as "no condition given", so a function reaching it would be
+ * a condition that silently always passed.
+ */
+async function passesIf(repository, pkg, raw, cwd, statusCache) {
+    if (typeof raw === 'function') {
+        return !!(await raw(RunService.createStepContext(pkg, cwd)));
+    }
+    const node = RunService.parseIfExpr(raw);
+    return node ? RunService.evaluateIf(repository, pkg, node, statusCache) : true;
 }
 /**
  * Resolves a package's steps for `script`, from its `.rmanrc` and from whatever sources plugins
@@ -419,17 +551,17 @@ function getScriptSteps(pkg, script) {
     const override = cfg.override === true;
     const contributed = firstContributed(pkg, script);
     const fromConfig = {
-        before: normalizeScriptValue(cfg.before),
-        exec: normalizeScriptValue(cfg.exec),
-        after: normalizeScriptValue(cfg.after),
+        before: RunService.normalizeScriptValue(cfg.before, `run.${script}.before`),
+        exec: RunService.normalizeScriptValue(cfg.exec, `run.${script}.exec`),
+        after: RunService.normalizeScriptValue(cfg.after, `run.${script}.after`),
     };
     const steps = [];
     for (const slot of SCRIPT_SLOTS) {
         const own = contributed?.[slot] ?? [];
         const configured = fromConfig[slot] ?? [];
-        const commands = override ? (configured.length ? configured : own) : own.length ? own : configured;
-        for (const command of commands)
-            steps.push({ name: slot, command });
+        const values = override ? (configured.length ? configured : own) : own.length ? own : configured;
+        for (const value of values)
+            steps.push(toStep(slot, value));
     }
     return steps;
 }

package/services/version.service.d.ts

@@ -1,5 +1,6 @@
 import type { Package } from '../core/package.js';
 import type { Repository } from '../core/repository.js';
+import type { RunStepValue } from '../core/run-step.js';
 import { VersionPlanService } from './version-plan.service.js';
 /**
  * Applying a version plan: the writes. Every manifest edit, dependency-range refresh, stamp,
@@ -74,9 +75,18 @@ export declare namespace VersionService {
      *  listing of `name@version` pairs when this particular commit spans different versions (a
      *  cross-group ripple can land a lone forced patch in a group that otherwise didn't move). */
     function buildCommitMessage(repository: Repository, entries: VersionPlanService.Entry[], messageOverride?: string): string;
-    /** A `version.<key>` value: one command, or several to run in sequence - same shape as
-     *  `run.<script>.script`/`.preScript`/`.postScript`. */
-    function normalizeScriptValue(value: unknown): string | undefined;
+    /**
+     * A `version.<slot>` value: one step, or several to run in sequence - the same shape, and now the
+     * same function, as `run.<script>.before`/`.exec`/`.after`.
+     *
+     * It used to be a second implementation living here, and it differed in two ways that both had to
+     * go. It **joined an array with `' && '`** into one shell line, which a function step cannot be
+     * part of and which was not even right for shell steps - `cd x && y` in one process is not two
+     * processes. And it **dropped anything it did not recognize**, so a function here was silently
+     * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
+     * that have been `before`/`exec`/`after` for a long time.)
+     */
+    function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
     /**
      * Keeps a package's Dockerfile `org.opencontainers.image.version` label in step with the version
      * just written, returning the absolute path when it actually changed (so the caller can fold it

package/services/version.service.js

@@ -65,7 +65,10 @@ export var VersionService;
              * pre-empts it, and running the thing, are `RunService`'s (`runLifecycleSlot`), so nothing
              * here names a script, a file, or a shell.
              */
-            const hook = (slot) => RunService.runLifecycleSlot(pkg, VERSION_LIFECYCLE, slot, normalizeScriptValue(interpolateConfig(pkg.config?.version?.[slot], scope)));
+            const hook = (slot) => RunService.runLifecycleSlot(pkg, VERSION_LIFECYCLE, slot, RunService.normalizeScriptValue(
+            /** `at`: the path is what tells a step function from a value one, and this is a fragment -
+             *  without it a function here was called while the hook was being prepared. */
+            interpolateConfig(pkg.config?.version?.[slot], scope, { at: ['version', slot] }), `version.${slot}`));
             await hook('before');
             /** Through the manifest, not through a `package.json` field: where a version is written is
              *  the provider's business (see `ManifestProvider`), and this is the one place rman changes
@@ -198,16 +201,19 @@ export var VersionService;
         return `chore(release): ${entries.map(e => `${e.package.name}@${e.to}`).join(', ')}`;
     }
     VersionService.buildCommitMessage = buildCommitMessage;
-    /** A `version.<key>` value: one command, or several to run in sequence - same shape as
-     *  `run.<script>.script`/`.preScript`/`.postScript`. */
-    function normalizeScriptValue(value) {
-        if (typeof value === 'string')
-            return value || undefined;
-        if (Array.isArray(value)) {
-            const parts = value.filter((v) => typeof v === 'string' && !!v);
-            return parts.length ? parts.join(' && ') : undefined;
-        }
-        return undefined;
+    /**
+     * A `version.<slot>` value: one step, or several to run in sequence - the same shape, and now the
+     * same function, as `run.<script>.before`/`.exec`/`.after`.
+     *
+     * It used to be a second implementation living here, and it differed in two ways that both had to
+     * go. It **joined an array with `' && '`** into one shell line, which a function step cannot be
+     * part of and which was not even right for shell steps - `cd x && y` in one process is not two
+     * processes. And it **dropped anything it did not recognize**, so a function here was silently
+     * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
+     * that have been `before`/`exec`/`after` for a long time.)
+     */
+    function normalizeScriptValue(value, at) {
+        return RunService.normalizeScriptValue(value, at);
     }
     VersionService.normalizeScriptValue = normalizeScriptValue;
     /**

package/utils/printable-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A copy of a resolved config with every value a serializer cannot represent replaced by a short
+ * description of it - for `rman config` and `--config`, which exist to be *looked at*.
+ *
+ * Needed because a config legitimately holds functions now: a `run.<script>` or `version.<slot>`
+ * step written as JavaScript, and an `if` written the same way. It was already needed before that,
+ * though, which is the better argument for doing it here rather than at one call site - a
+ * `plugins` entry given in its object form carries the plugin's seams, and `rman config --root`
+ * died on one with `unacceptable kind of an object to dump [object Function]` (measured, on a
+ * repository whose shared config did nothing more unusual than `extends` a plugin package).
+ *
+ * A function prints as `[Function: copyDocs]`, so the output says *which* one - an anonymous step
+ * reads as `[Function]`, which is itself worth seeing.
+ */
+export declare function printableConfig<T>(config: T): T;

package/utils/printable-config.js

@@ -0,0 +1,42 @@
+/**
+ * A copy of a resolved config with every value a serializer cannot represent replaced by a short
+ * description of it - for `rman config` and `--config`, which exist to be *looked at*.
+ *
+ * Needed because a config legitimately holds functions now: a `run.<script>` or `version.<slot>`
+ * step written as JavaScript, and an `if` written the same way. It was already needed before that,
+ * though, which is the better argument for doing it here rather than at one call site - a
+ * `plugins` entry given in its object form carries the plugin's seams, and `rman config --root`
+ * died on one with `unacceptable kind of an object to dump [object Function]` (measured, on a
+ * repository whose shared config did nothing more unusual than `extends` a plugin package).
+ *
+ * A function prints as `[Function: copyDocs]`, so the output says *which* one - an anonymous step
+ * reads as `[Function]`, which is itself worth seeing.
+ */
+export function printableConfig(config) {
+    return walk(config, new WeakSet());
+}
+function walk(value, seen) {
+    if (typeof value === 'function')
+        return `[Function${value.name ? `: ${value.name}` : ''}]`;
+    if (!value || typeof value !== 'object')
+        return value;
+    /** A resolved config is a tree, but a plugin object is arbitrary code's data and may not be.
+     *  js-yaml's `noRefs` turns a repeat into a copy rather than an anchor, which on a true cycle
+     *  never terminates - so the cycle is cut here, where it can be named. */
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map(item => walk(item, seen));
+        const result = {};
+        for (const [key, item] of Object.entries(value))
+            result[key] = walk(item, seen);
+        return result;
+    }
+    finally {
+        /** Released on the way out, so a value that merely appears twice in *different* branches - the
+         *  ordinary case after merging - is printed both times rather than reported as a cycle. */
+        seen.delete(value);
+    }
+}