rman 1.0.12 → 1.2.1

package/services.d.ts

@@ -1,12 +1,14 @@
 export { ChangelogService } from './services/changelog.service.js';
-export { CiService } from './services/ci.service.js';
-export { CleanService } from './services/clean.service.js';
 export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';
 export { ListService } from './services/list.service.js';
-export { PublishService } from './services/publish.service.js';
 export { RunService } from './services/run.service.js';
 export { SystemInfo } from './services/system-info.js';
 export { VersionService } from './services/version.service.js';
+export { VersionPlanService } from './services/version-plan.service.js';
+/** Release boundaries and tag names, both directions - `ChangeHashService.detect` is what a
+ *  plugin's planner answers `detectBoundary` with, and the only place a tag name is built. */
+export { ChangeHashService } from './services/change-hash.service.js';
+export { ConventionalCommitsService } from './services/conventional-commits.service.js';

package/services.js

@@ -1,12 +1,14 @@
 export { ChangelogService } from './services/changelog.service.js';
-export { CiService } from './services/ci.service.js';
-export { CleanService } from './services/clean.service.js';
 export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';
 export { ListService } from './services/list.service.js';
-export { PublishService } from './services/publish.service.js';
 export { RunService } from './services/run.service.js';
 export { SystemInfo } from './services/system-info.js';
 export { VersionService } from './services/version.service.js';
+export { VersionPlanService } from './services/version-plan.service.js';
+/** Release boundaries and tag names, both directions - `ChangeHashService.detect` is what a
+ *  plugin's planner answers `detectBoundary` with, and the only place a tag name is built. */
+export { ChangeHashService } from './services/change-hash.service.js';
+export { ConventionalCommitsService } from './services/conventional-commits.service.js';

package/utils/bin-path.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where a repository's **locally installed executables** live, so a command an author wrote
+ * (`eslint .`, `cargo build`) is found the way it would be in their own shell.
+ *
+ * Two halves, split by who actually owns them:
+ *
+ * - **Which directories** is the *ecosystem's* answer, and the core has none - `node_modules/.bin`
+ *   walked up the directory chain is npm's layout and nothing else's (a Python venv says
+ *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `RmanPlugin.binPaths`.
+ * - **How a PATH is spelled** is the *operating system's*, and that stays here: the variable is
+ *   `PATH` everywhere except Windows, where its case is whatever the environment happens to use.
+ *   That has nothing to do with any ecosystem, and every provider would otherwise get it wrong
+ *   separately.
+ *
+ * **Every provider contributes, in `plugins` declaration order** - unlike `Manifest`/`Workspace`,
+ * which take the first that recognizes a repository. A PATH is a list, and a repository holding two
+ * ecosystems wants both sets of binaries reachable; "first wins" would silently hide one.
+ */
+export declare namespace BinPath {
+    type ProcessEnv = Record<string, string | undefined>;
+    /** Absolute directories to put **ahead of** the inherited PATH, for a command run in `cwd`.
+     *  Return them most-specific-first; the core concatenates providers without reordering. */
+    type Provider = (cwd: string) => string[];
+    interface EnvOptions {
+        /** The directory the command will run in. Default `process.cwd()`. */
+        readonly cwd?: string;
+        /** The environment to derive from, like `process.env`. Default `process.env`. */
+        readonly env?: ProcessEnv;
+    }
+    /** Registers a provider. Called by `loadPlugins` for each plugin's `binPaths`, in `plugins`
+     *  declaration order - so what is on PATH is a function of the repository's own config. */
+    function addProvider(provider: Provider): void;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders(): void;
+    /** Every provider's directories for `cwd`, concatenated in declaration order. Empty for a
+     *  repository that names no plugin - the inherited PATH then stands on its own, which is the
+     *  honest answer rather than a guess at some ecosystem's layout. */
+    function resolve(cwd: string): string[];
+    /**
+     * `env` with the contributed directories prepended to its PATH - what `exec` and `runBin` hand to
+     * a child process.
+     *
+     * Prepended, not appended: a repository's own pinned `eslint` has to win over one that happens to
+     * be installed globally, which is the whole point of a local install.
+     */
+    function env(options?: EnvOptions): ProcessEnv;
+    /**
+     * The name of the PATH variable in `env` - `PATH` everywhere but Windows, where the environment
+     * is case-insensitive and the key can genuinely arrive as `Path`.
+     *
+     * The OS's business, so it lives here rather than in any provider: read the *existing* key rather
+     * than writing a second one, or a child process inherits two PATHs and the one it reads is up to
+     * the platform.
+     */
+    function pathKey(options?: {
+        env?: ProcessEnv;
+        platform?: string;
+    }): string;
+}

package/utils/bin-path.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import process from 'node:process';
+/**
+ * Where a repository's **locally installed executables** live, so a command an author wrote
+ * (`eslint .`, `cargo build`) is found the way it would be in their own shell.
+ *
+ * Two halves, split by who actually owns them:
+ *
+ * - **Which directories** is the *ecosystem's* answer, and the core has none - `node_modules/.bin`
+ *   walked up the directory chain is npm's layout and nothing else's (a Python venv says
+ *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `RmanPlugin.binPaths`.
+ * - **How a PATH is spelled** is the *operating system's*, and that stays here: the variable is
+ *   `PATH` everywhere except Windows, where its case is whatever the environment happens to use.
+ *   That has nothing to do with any ecosystem, and every provider would otherwise get it wrong
+ *   separately.
+ *
+ * **Every provider contributes, in `plugins` declaration order** - unlike `Manifest`/`Workspace`,
+ * which take the first that recognizes a repository. A PATH is a list, and a repository holding two
+ * ecosystems wants both sets of binaries reachable; "first wins" would silently hide one.
+ */
+export var BinPath;
+(function (BinPath) {
+    /** Registers a provider. Called by `loadPlugins` for each plugin's `binPaths`, in `plugins`
+     *  declaration order - so what is on PATH is a function of the repository's own config. */
+    function addProvider(provider) {
+        if (providers.includes(provider))
+            return;
+        providers.push(provider);
+    }
+    BinPath.addProvider = addProvider;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders() {
+        providers.length = 0;
+    }
+    BinPath.clearProviders = clearProviders;
+    /** Every provider's directories for `cwd`, concatenated in declaration order. Empty for a
+     *  repository that names no plugin - the inherited PATH then stands on its own, which is the
+     *  honest answer rather than a guess at some ecosystem's layout. */
+    function resolve(cwd) {
+        const dir = path.resolve(cwd);
+        return providers.flatMap(provider => provider(dir));
+    }
+    BinPath.resolve = resolve;
+    /**
+     * `env` with the contributed directories prepended to its PATH - what `exec` and `runBin` hand to
+     * a child process.
+     *
+     * Prepended, not appended: a repository's own pinned `eslint` has to win over one that happens to
+     * be installed globally, which is the whole point of a local install.
+     */
+    function env(options = {}) {
+        const cwd = options.cwd || process.cwd();
+        const result = { ...(options.env || process.env) };
+        const key = pathKey({ env: result });
+        const entries = resolve(cwd);
+        if (!entries.length)
+            return result;
+        const inherited = result[key];
+        result[key] = [...entries, ...(inherited ? [inherited] : [])].join(path.delimiter);
+        return result;
+    }
+    BinPath.env = env;
+    /**
+     * The name of the PATH variable in `env` - `PATH` everywhere but Windows, where the environment
+     * is case-insensitive and the key can genuinely arrive as `Path`.
+     *
+     * The OS's business, so it lives here rather than in any provider: read the *existing* key rather
+     * than writing a second one, or a child process inherits two PATHs and the one it reads is up to
+     * the platform.
+     */
+    function pathKey(options) {
+        const source = options?.env || process.env;
+        const platform = options?.platform || process.platform;
+        if (platform !== 'win32')
+            return 'PATH';
+        return (Object.keys(source)
+            .reverse()
+            .find(key => key.toUpperCase() === 'PATH') || 'Path');
+    }
+    BinPath.pathKey = pathKey;
+    const providers = [];
+})(BinPath || (BinPath = {}));

package/utils/child-tracker.d.ts

@@ -0,0 +1,16 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Registers `child` to be killed if rman exits while it is still running - Ctrl-C, a signal, a throw
+ * on some other path.
+ *
+ * **Here rather than inside `exec`, because `runBin` needs the same thing and did not have it.** A
+ * child spawned by `runBin` (which is what a plugin's or a `.rman/*.mjs` command's `runBin` reaches)
+ * outlived an interrupted rman run: the registry and the exit hook lived in `exec.ts` and nothing
+ * else could see them. Anything in rman that spawns a process goes through one of those two, so
+ * tracking belongs where both can reach it.
+ *
+ * Untracks itself on `close`/`error`, so a long session does not accumulate dead entries. Adding
+ * listeners here is safe alongside the caller's own - an `error` event needs *a* listener, not
+ * exactly one, and both `exec` and `runBin` attach theirs anyway.
+ */
+export declare function trackChild(child: ChildProcess): void;

package/utils/child-tracker.js

@@ -0,0 +1,30 @@
+import { onExit } from 'signal-exit';
+/**
+ * Registers `child` to be killed if rman exits while it is still running - Ctrl-C, a signal, a throw
+ * on some other path.
+ *
+ * **Here rather than inside `exec`, because `runBin` needs the same thing and did not have it.** A
+ * child spawned by `runBin` (which is what a plugin's or a `.rman/*.mjs` command's `runBin` reaches)
+ * outlived an interrupted rman run: the registry and the exit hook lived in `exec.ts` and nothing
+ * else could see them. Anything in rman that spawns a process goes through one of those two, so
+ * tracking belongs where both can reach it.
+ *
+ * Untracks itself on `close`/`error`, so a long session does not accumulate dead entries. Adding
+ * listeners here is safe alongside the caller's own - an `error` event needs *a* listener, not
+ * exactly one, and both `exec` and `runBin` attach theirs anyway.
+ */
+export function trackChild(child) {
+    const pid = child.pid;
+    /** No pid means the spawn failed before the OS gave it one - there is nothing to kill, and the
+     *  caller's own `error` handler is about to report it. */
+    if (!pid)
+        return;
+    running.set(pid, child);
+    const forget = () => running.delete(pid);
+    child.on('close', forget);
+    child.on('error', forget);
+}
+const running = new Map();
+onExit(() => {
+    running.forEach(child => child.kill());
+});

package/utils/exec.d.ts

@@ -3,10 +3,11 @@ export interface ExecOptions {
      *  'pipe' (default) captures output so the caller can drive a live view via onLine. */
     stdio?: 'inherit' | 'pipe';
     cwd?: string;
-    argv?: string[];
     env?: Record<string, string | undefined>;
-    shell?: boolean;
     onLine?: (line: string, stdio: 'stderr' | 'stdout') => void;
+    /** Reject on a non-zero exit (default `true`). Set false to read `code` instead - for a command
+     *  whose failure is an expected answer rather than a problem (`docker buildx create --use` on a
+     *  builder that already exists). */
     throwOnError?: boolean;
 }
 export interface ExecResult {
@@ -14,4 +15,14 @@ export interface ExecResult {
     error?: Error;
     stdout?: string;
 }
+/**
+ * Runs `command` **through a shell, as one string** - the right tool for a command line a config
+ * author wrote, shell operators and all (`run.<script>`, `version` hooks, `rman exec`).
+ *
+ * **It takes no argv and the shell is not optional**, deliberately: an `argv`/`shell: false` pair
+ * would make this able to do `runBin`'s job badly, and for years nothing passed either. Arguments
+ * assembled in code go to `runBin`, which spawns with no shell - so an interpolated value holding a
+ * space stays one argument and one holding `;` stays data. Keeping the boundary in the *signature*
+ * is what stops a caller from having to know that rule.
+ */
 export declare function exec(command: string, options?: ExecOptions): Promise<ExecResult>;

package/utils/exec.js

@@ -1,14 +1,23 @@
-import { ChildProcess, spawn } from 'child_process';
-import { onExit } from 'signal-exit';
-import { npmRunPathEnv } from './npm-run-path.js';
+import { spawn } from 'node:child_process';
+import { BinPath } from './bin-path.js';
+import { trackChild } from './child-tracker.js';
+/**
+ * Runs `command` **through a shell, as one string** - the right tool for a command line a config
+ * author wrote, shell operators and all (`run.<script>`, `version` hooks, `rman exec`).
+ *
+ * **It takes no argv and the shell is not optional**, deliberately: an `argv`/`shell: false` pair
+ * would make this able to do `runBin`'s job badly, and for years nothing passed either. Arguments
+ * assembled in code go to `runBin`, which spawns with no shell - so an interpolated value holding a
+ * space stays one argument and one holding `;` stays data. Keeping the boundary in the *signature*
+ * is what stops a caller from having to know that rule.
+ */
 export async function exec(command, options) {
     const opts = {
-        shell: true,
         throwOnError: true,
         ...options,
     };
     opts.env = {
-        ...npmRunPathEnv({ cwd: opts.cwd }),
+        ...BinPath.env({ cwd: opts.cwd }),
         ...opts.env,
     };
     opts.cwd = opts.cwd || process.cwd();
@@ -16,7 +25,7 @@ export async function exec(command, options) {
         stdio: opts.stdio === 'inherit' ? 'inherit' : 'pipe',
         env: opts.env,
         cwd: opts.cwd,
-        shell: opts.shell,
+        shell: true,
         windowsHide: true,
     };
     const result = { code: undefined, stdout: '' };
@@ -43,16 +52,13 @@ export async function exec(command, options) {
         else
             stderrBuffer = buf;
     };
-    const child = spawn(command, opts.argv || [], spawnOptions);
-    if (child.pid)
-        runningChildren.set(child.pid, child);
+    const child = spawn(command, [], spawnOptions);
+    trackChild(child);
     child.stdout?.on('data', data => processLines(String(data), 'stdout'));
     child.stderr?.on('data', data => processLines(String(data), 'stderr'));
     return new Promise((resolve, reject) => {
         let resolved = false;
         child.on('error', (err) => {
-            if (child.pid)
-                runningChildren.delete(child.pid);
             processLines('', 'stdout', true);
             processLines('', 'stderr', true);
             if (resolved)
@@ -70,8 +76,6 @@ export async function exec(command, options) {
             resolve(result);
         });
         child.on('close', (code) => {
-            if (child.pid)
-                runningChildren.delete(child.pid);
             processLines('', 'stdout', true);
             processLines('', 'stderr', true);
             if (resolved)
@@ -86,7 +90,3 @@ export async function exec(command, options) {
         });
     });
 }
-const runningChildren = new Map();
-onExit(() => {
-    runningChildren.forEach(child => child.kill());
-});

package/utils/git.d.ts

@@ -62,9 +62,15 @@ export declare class GitHelper {
      *  `undefined` for a repository with no commits at all. The "since the beginning" boundary for
      *  a package being released for the first time, with no earlier tag to measure from. */
     rootCommit(): Promise<string | undefined>;
-    /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
-     *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
-    commit(files: string[], message: string): Promise<void>;
+    /**
+     * Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
+     * blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for.
+     *
+     * Returns the **short sha** of the commit it made. It used to return nothing, which left every
+     * caller unable to say what it had just done: `version` made up to one commit per group and
+     * reported none of them.
+     */
+    commit(files: string[], message: string): Promise<string>;
     /** Creates an annotated tag `name` pointing at HEAD, with `message` (defaults to `name`).
      *  Throws if a tag with that name already exists - callers wanting idempotent tagging should
      *  check `tagExists` first. */

package/utils/git.js

@@ -207,12 +207,20 @@ export class GitHelper {
             return undefined;
         }
     }
-    /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
-     *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
+    /**
+     * Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
+     * blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for.
+     *
+     * Returns the **short sha** of the commit it made. It used to return nothing, which left every
+     * caller unable to say what it had just done: `version` made up to one commit per group and
+     * reported none of them.
+     */
     async commit(files, message) {
         try {
             await execFileAsync('git', ['add', '--', ...files], { cwd: this.cwd });
             await execFileAsync('git', ['commit', '-m', message], { cwd: this.cwd });
+            const { stdout } = await execFileAsync('git', ['rev-parse', '--short', 'HEAD'], { cwd: this.cwd });
+            return stdout.trim();
         }
         catch (e) {
             throw new Error(`Unable to commit ${files.join(', ')}: ${e.message}`, { cause: e });

package/utils/package-filter.d.ts

@@ -2,7 +2,9 @@ import type { Argv } from 'yargs';
 import type { Package } from '../core/package.js';
 /** Shared by every command that iterates packages (`run`/`build`/`test`/`exec`, `list`, `ci`,
  *  `clean`, `version`, `publish`, `changelog`) - narrows *which* packages a command applies to,
- *  independent of what the command actually does to them. */
+ *  independent of what the command actually does to them. The repository's own standing filter,
+ *  `.rmanrc "skip"`, is applied by `filterPackages` itself rather than being an option here: it is
+ *  the repository's statement, not the caller's. */
 export interface PackageFilterOptions {
     /** Only include packages whose name matches at least one of these globs (e.g. `@scope/*`). */
     scope?: string | string[];
@@ -28,5 +30,34 @@ export declare function readPackageFilterOptions(args: any): PackageFilterOption
  * `Repository`'s own `_updateDependencies`) and their results are unioned in - so `--deps
  * --dependents` together never re-expands one direction's additions through the other, which
  * would otherwise tend to blow up toward "the whole repository" for any reasonably-connected graph.
+ *
+ * A package excluded by its own `.rmanrc "skip"` is dropped **first**, before any of that - so
+ * `--deps` never drags a skipped package back in through a dependency edge.
  */
-export declare function filterPackages(packages: Package[], options: PackageFilterOptions): Package[];
+export declare function filterPackages(packages: Package[], options: PackageFilterOptions, 
+/**
+ * Whether each package's own `.rmanrc "skip"` applies. Default `true`: every command that *acts*
+ * on packages honours it, which is the point of one standing "leave this package alone" instead
+ * of a separate `skip` invented per command.
+ *
+ * `list` passes `false` - an inventory that hides part of the repository is answering a different
+ * question than the one asked. That is the only caller that does, and it is the test for whether a
+ * new command should: does it *do* something to the packages, or does it *report* on them?
+ */
+applySkip?: boolean): Package[];
+/**
+ * `--root`/`-r`, with one describe text instead of four near-identical ones.
+ *
+ * **It only means anything where a command scopes by the current directory** - `run`/`build`/`test`,
+ * `exec`, `clean`, `changelog` and `diff` narrow to `Repository.currentPackage` when you stand
+ * inside a package, and this is the escape hatch. On a command that already works across the whole
+ * repository (`version`, `publish`, `list`, `changed`) it would be a flag that does nothing, which
+ * is worse than not offering it: a no-op flag reads as a promise.
+ *
+ * `verb` is the command's own word for what it does, so the text stays the sentence each command was
+ * already saying.
+ */
+export declare function applyRootOption<T>(cmd: Argv<T>, verb: string): Argv<T>;
+/** The `--root` flag as the services read it - beside `readPackageFilterOptions`, so a command
+ *  reads both the same way. */
+export declare function readRootOption(args: any): boolean | undefined;

package/utils/package-filter.js

@@ -40,9 +40,22 @@ export function readPackageFilterOptions(args) {
  * `Repository`'s own `_updateDependencies`) and their results are unioned in - so `--deps
  * --dependents` together never re-expands one direction's additions through the other, which
  * would otherwise tend to blow up toward "the whole repository" for any reasonably-connected graph.
+ *
+ * A package excluded by its own `.rmanrc "skip"` is dropped **first**, before any of that - so
+ * `--deps` never drags a skipped package back in through a dependency edge.
  */
-export function filterPackages(packages, options) {
-    let matched = packages;
+export function filterPackages(packages, options, 
+/**
+ * Whether each package's own `.rmanrc "skip"` applies. Default `true`: every command that *acts*
+ * on packages honours it, which is the point of one standing "leave this package alone" instead
+ * of a separate `skip` invented per command.
+ *
+ * `list` passes `false` - an inventory that hides part of the repository is answering a different
+ * question than the one asked. That is the only caller that does, and it is the test for whether a
+ * new command should: does it *do* something to the packages, or does it *report* on them?
+ */
+applySkip = true) {
+    let matched = applySkip ? packages.filter(p => p.config?.skip !== true) : packages;
     if (options.scope) {
         const patterns = toArray(options.scope);
         matched = matched.filter(p => micromatch.isMatch(p.name, patterns));
@@ -53,21 +66,48 @@ export function filterPackages(packages, options) {
     }
     if (!options.deps && !options.dependents)
         return matched;
-    const included = new Set(matched.map(p => p.name));
+    /** A set of packages, not of names: `Package.dependencies` holds references now, so identity is
+     *  what these comparisons are about. */
+    const included = new Set(matched);
     if (options.deps) {
         for (const p of matched)
             for (const dep of p.dependencies)
                 included.add(dep);
     }
     if (options.dependents) {
-        const matchedNames = new Set(matched.map(p => p.name));
+        const matchedSet = new Set(matched);
         for (const p of packages) {
-            if (p.dependencies.some(d => matchedNames.has(d)))
-                included.add(p.name);
+            if (p.dependencies.some(d => matchedSet.has(d)))
+                included.add(p);
         }
     }
-    return packages.filter(p => included.has(p.name));
+    return packages.filter(p => included.has(p));
 }
 function toArray(value) {
     return Array.isArray(value) ? value : [value];
 }
+/**
+ * `--root`/`-r`, with one describe text instead of four near-identical ones.
+ *
+ * **It only means anything where a command scopes by the current directory** - `run`/`build`/`test`,
+ * `exec`, `clean`, `changelog` and `diff` narrow to `Repository.currentPackage` when you stand
+ * inside a package, and this is the escape hatch. On a command that already works across the whole
+ * repository (`version`, `publish`, `list`, `changed`) it would be a flag that does nothing, which
+ * is worse than not offering it: a no-op flag reads as a promise.
+ *
+ * `verb` is the command's own word for what it does, so the text stays the sentence each command was
+ * already saying.
+ */
+export function applyRootOption(cmd, verb) {
+    return cmd.option('root', {
+        alias: 'r',
+        describe: `${verb} across the whole repository even when the current directory is inside a single ` +
+            'package (which otherwise scopes it to just that package). No effect elsewhere.',
+        type: 'boolean',
+    });
+}
+/** The `--root` flag as the services read it - beside `readPackageFilterOptions`, so a command
+ *  reads both the same way. */
+export function readRootOption(args) {
+    return args.root;
+}

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

package/utils/release-version.js

@@ -1,4 +1,4 @@
-import { applyTagPattern, extractVersion } from './change-hash.js';
+import { ChangeHashService } from '../services/change-hash.service.js';
 /**
  * A calendar release version: `YYYY.M.D-HHmm`, every part **unpadded** (`2026.9.5-930`, not
  * `2026.09.05-0930`). The padding isn't a style choice - semver forbids leading zeroes in numeric
@@ -52,7 +52,7 @@ export function usesCalendarVersion(options) {
 /** The tag naming a given repository release - `releaseTagPattern` run forward, the way
  *  `expandTag` runs `changelog.tagPattern` forward for a package. */
 export function expandReleaseTag(root, version) {
-    return applyTagPattern(releaseTagPattern(root), root.name, version);
+    return ChangeHashService.applyTagPattern(releaseTagPattern(root), root.name, version);
 }
 /** The version of the repository's most recent release, from its release tags (highest by version
  *  sort) - `undefined` for a repo that has never cut one, or whose tags aren't available (a shallow
@@ -61,6 +61,6 @@ export function expandReleaseTag(root, version) {
 export async function findLastReleaseVersion(git, root) {
     const glob = releaseTagPattern(root).replace('{name}', root.name);
     const tag = (await git.listTags(glob))[0];
-    return tag ? extractVersion(tag, glob) : undefined;
+    return tag ? ChangeHashService.extractVersion(tag, glob) : undefined;
 }
 const DEFAULT_RELEASE_TAG_PATTERN = 'release-*';

package/utils/run-bin.d.ts

@@ -0,0 +1,46 @@
+import { type LogLevel } from './logger.js';
+export interface RunBinOptions {
+    /** Where to run it, and the directory `node_modules/.bin` is resolved from. Default `process.cwd()`. */
+    cwd?: string;
+    /** 'inherit' streams the child's output straight to the terminal; 'pipe' captures it and resolves
+     *  with it instead - for a binary being asked a question rather than doing work. Defaults to
+     *  whatever `logLevel` implies (see below). */
+    stdio?: 'inherit' | 'pipe';
+    /**
+     * Verbosity, defaulting to 'info'. This is what a caller holding the session's resolved level
+     * passes in - `CommandContext.runBin` does exactly that, so a repository's own command honors
+     * `--log-level` and `.rmanrc logLevel` without reading either itself.
+     *
+     * - 'verbose' also prints the command before running it.
+     * - 'info' streams the child's output through (`stdio: 'inherit'`).
+     * - 'error'/'silent' capture it instead, and surface it only if the command fails - 'silent' not
+     *   even then. An explicit `stdio` still wins over all of this.
+     */
+    logLevel?: LogLevel;
+    env?: Record<string, string | undefined>;
+}
+export interface RunBinResult {
+    code: number;
+    /** Captured stdout+stderr, only with `stdio: 'pipe'`. */
+    output: string;
+}
+/**
+ * Runs one of the repository's locally installed binaries, passing **argv as an array** - no shell.
+ *
+ * Use this over `exec` whenever the arguments aren't a fixed string: `exec` runs through a shell, so
+ * an interpolated path containing a space silently becomes two arguments, and a value containing
+ * `;` or `&&` becomes another command. Here they cannot - each element of `argv` arrives as exactly
+ * one argument. `exec` remains the right tool for a command the config author wrote as a string,
+ * shell operators and all (`run.<script>`, `version` hooks).
+ *
+ * The binary is found by PATH, not spawned by path: `BinPath.env` prepends whatever the repository's
+ * plugins say a local install lives in (`node_modules/.bin`
+ * from `cwd` up the directory tree, which is what makes `eslint` resolve to the repository's own
+ * copy - and on Windows resolve `eslint.cmd`, which spawning a bare path would not.
+ *
+ * Rejects on a non-zero exit (the error names the command and the code) and on a missing binary,
+ * where it asks the useful question instead of reporting `ENOENT`. A non-zero exit has to be an
+ * error rather than a returned code: a lint or type-check step that passes in CI having checked
+ * nothing is the outcome worth ruling out, and that is what silently discarding a code produces.
+ */
+export declare function runBin(bin: string, argv: string[], options?: RunBinOptions): Promise<RunBinResult>;