rman 1.0.12 → 1.2.1

package/README.md

@@ -11,7 +11,7 @@ packages, computing semantic version bumps from your commit history, publishing,
 importing external repos with history intact, and more - all driven by a single, cascading
 `.rmanrc`/`.rmanrc.yml` config.
 
-Every command is also available as a **programmatic API** - see [docs/api.md](docs/api.md) if you
+Every command is also available as a **programmatic API** - see [docs/rman.md](https://github.com/panates/rman/blob/main/docs/rman.md) if you
 want to call `rman`'s logic directly from a Node.js script instead of shelling out to the CLI.
 
 ## Table of contents
@@ -66,7 +66,7 @@ rman version
 # Apply it: bump versions, write CHANGELOG.md, commit, tag
 rman version --changelog
 
-# Publish everything that isn't already on the registry
+# Publish everything that isn't already on the registry (needs rman-node)
 rman publish
 ```
 
@@ -75,7 +75,7 @@ Run any command with `--help` for its full option list (`rman version --help`, `
 ## Commands
 
 The summaries and examples below cover the common cases. For the full option list, defaults, and
-worked examples of every single command, see **[docs/cli.md](docs/cli.md)**.
+worked examples of every single command, see **[docs/cli-rman.md](https://github.com/panates/rman/blob/main/docs/cli-rman.md)**.
 
 | Command | Purpose |
 | --- | --- |
@@ -85,23 +85,34 @@ worked examples of every single command, see **[docs/cli.md](docs/cli.md)**.
 | [`build`](#rman-build) | Alias for `run build`. |
 | [`test`](#rman-test) | Alias for `run test`. |
 | [`exec <command..>`](#rman-exec-command) | Runs an arbitrary shell command in each package. |
-| [`ci`](#rman-ci) | Deletes `node_modules`/lockfiles everywhere, then reinstalls from scratch. |
-| [`clean`](#rman-clean) | Removes compiled TypeScript output and configured extra files/dirs. |
+| [`config`](#rman-config) | Prints the effective `.rmanrc` config for the current directory's package. |
 | [`changed`](#rman-changed) | Shows which packages the next `version` run would bump. |
 | [`diff [package]`](#rman-diff-package) | Shows the git diff since a package's (or the repo's) last release tag. |
 | [`changelog`](#rman-changelog) | Generates a changelog per package from unreleased commits. |
 | [`version [bump]`](#rman-version-bump) | Bumps versions of changed packages (and their dependents). |
-| [`publish`](#rman-publish) | Publishes every package to its configured target(s) - npm, Docker and/or GitHub Releases. |
+| [`github-release`](#rman-github-release) | Creates the repository's GitHub Release for its release tag. |
 | [`import <path>`](#rman-import-path) | Imports an external git repository as a new package, with history. |
 
+**`publish`, `ci` and `clean` come from [`rman-node`](https://www.npmjs.com/package/rman-node)**,
+not from this package - each is about npm or TypeScript rather than about repositories. Name the
+plugin in `.rmanrc` to get them:
+
+```yaml
+plugins: ['rman-node']
+```
+
 Options shared across several commands:
 
-- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `ci`, `clean`, `version`, `publish`,
-  `changelog`): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
-  [Package filtering](docs/api.md#package-filtering-scopeignoredepsdependents) for the full
-  semantics.
+- **`skip`** (`.rmanrc`, per package): leave this package alone - honoured by every command that
+  *acts* on packages, ignored by `list`, which reports on them.
+- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `version`, `changelog`, and a
+  plugin's own commands): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
+  [Package filtering](https://github.com/panates/rman/blob/main/docs/rman.md#package-filtering-scopeignoredepsdependents)
+  for the full semantics.
+- **`--root`/`-r`** (every command that narrows to the package you are standing in -
+  `run`/`build`/`test`, `exec`, `changelog`, `diff`): run against the whole repository instead.
 - **Branch guard** (every command that mutates state or runs scripts - `run`/`build`/`test`,
-  `exec`, `ci`, `clean`, `version`, `publish`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
+  `exec`, `version`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
   refuses to run unless (or if) the current git branch matches, the same idea as GitHub Actions'
   own `branches`/`branches-ignore` workflow filters.
 
@@ -123,8 +134,9 @@ rman list --scope '@myorg/*' --ignore '*-internal'
 
 ### `rman info`
 
-Prints local environment (OS/CPU/memory, Node + whichever package manager `.rmanrc
-"packageManager"` configures, git) and repository information.
+Prints local environment (OS/CPU/memory, Node, git) and repository information. A plugin adds its
+own ecosystem's part - `rman-node` reports whichever package manager `.rmanrc "packageManager"`
+names, plus the installed `rman` packages.
 
 ```bash
 rman info
@@ -148,7 +160,7 @@ rman run build --scope pkg-a --deps # pkg-a plus everything it depends on
 
 Per-package/script behavior (pre/post hooks, `if` conditions, skip, concurrency, ...) is
 configurable via `.rmanrc run.<script>.*` - see [Configuration](#configuration) below and the full
-writeup in [docs/api.md](docs/api.md#runservice).
+writeup in [docs/rman.md](https://github.com/panates/rman/blob/main/docs/rman.md#runservice).
 
 ### `rman build`
 
@@ -177,25 +189,16 @@ rman exec --scope pkg-a -- ls -la
 rman exec --topo=false pwd         # every package independently, alphabetical order
 ```
 
-### `rman ci`
-
-Deletes `node_modules` and any lockfile in every package (or runs the package's own `"ci"` script
-instead, if it defines one), then installs once at the root.
-
-```bash
-rman ci
-rman ci --package-manager pnpm
-```
-
-### `rman clean`
+### `rman config`
 
-Removes compiled TypeScript output (`.js`/`.js.map`/`.d.ts` under `src`/`test`, plus any
-`*.tsbuildinfo`) and whatever `.rmanrc clean.include`/`clean.exclude` configures. Never touches
-`node_modules` - that's `ci`'s job.
+Prints the **effective** config for the package of the current directory - after the directory
+cascade, `"[selector]"` blocks, `extends`, `+key` appends and `${{ ... }}` expressions have all been
+applied. What rman actually sees there, which no single file shows.
 
 ```bash
-rman clean
-rman clean --dry-run              # preview what would be removed
+rman config                  # the package you are standing in
+rman config --root           # the repository root's own config instead
+rman config --json | jq .run
 ```
 
 ### `rman changed`
@@ -260,36 +263,9 @@ feat: needs to ship right now
 Release-As: patch
 ```
 
-See [docs/api.md#versionservice](docs/api.md#versionservice) for the full grouping/propagation
+See [docs/rman.md#versionservice](https://github.com/panates/rman/blob/main/docs/rman.md#versionservice) for the full grouping/propagation
 algorithm, prerelease semantics, and `"workspace:"` dependency-range handling.
 
-### `rman publish`
-
-Publishes every package to its configured registry - `npm` by default, or whatever each package's
-own `.rmanrc "publish.target"` says (`"npm"`, `"docker"`, or both). Each target decides for itself
-whether the current version is already out there: `npm view` on the npm side, `docker manifest
-inspect` on the docker side.
-
-```bash
-rman publish                              # show the plan, then ask for confirmation
-rman publish --yes                        # publish immediately, no confirmation
-rman publish --dry-run                    # only show the plan, never publish
-rman publish --access public               # required for a new scoped package
-rman publish --tag next
-rman publish --otp 123456
-rman publish --registry https://registry.example.com --userconfig ./ci.npmrc
-rman publish --package-manager pnpm
-rman publish --target docker              # only the packages configured for the "docker" target
-```
-
-A `"workspace:*"`/`"workspace:^"`/`"workspace:~"` dependency range is automatically rewritten to a
-real, registry-consumable range immediately before each package's publish, and restored right
-after - see [docs/api.md#publishservice](docs/api.md#publishservice).
-
-A package opts into building/pushing a Docker image via `.rmanrc "publish.target": ["docker"]` plus
-a `"publish.docker"` block (`image`, `platforms`, `buildContexts`, `buildArgs`, ...) - see
-[docs/cli/publish.md#docker-publishing-publishdocker](docs/cli/publish.md#docker-publishing-publishdocker).
-
 ### `rman github-release`
 
 Creates the repository's GitHub Release for the version that just shipped - one per run, named after
@@ -302,7 +278,7 @@ rman github-release --yes
 It is deliberately neither a `publish.target` nor opt-in: a release isn't a registry a package ships
 to, it's the repository's own record that a version shipped, and every repository wants that record.
 It needs no configuration at all - see
-[docs/cli/github-release.md](docs/cli/github-release.md).
+[docs/cli/github-release.md](https://github.com/panates/rman/blob/main/docs/cli/github-release.md).
 
 ### `rman import <path>`
 
@@ -318,6 +294,51 @@ rman import ../my-old-standalone-repo --dest libs   # under libs/ instead of pac
 already. After importing, add the new directory to your `workspaces` glob if it isn't already
 covered, then run `rman ci` to install it.
 
+## Shared config (`extends`) and appending (`+key`)
+
+House rules live in one package, and a repository names it:
+
+```yaml
+# .rmanrc.yml
+extends: '@panates/rman-monorepo'
+
+'[*]':
+  run:
+    build:
+      +before: 'rm -rf ./cache' # adds to the base's step, rather than replacing it
+```
+
+`extends` merges underneath the file naming it (a package, a path, or a list), and may itself be
+chained. `+key` appends to whatever the key already resolved to - from the base, a parent directory,
+or a selector - which is what lets a repository add one step without restating a list it doesn't
+own. See [docs/rman.md](https://github.com/panates/rman/blob/main/docs/rman.md#inheriting-a-shared-config-extends).
+
+## Your own commands
+
+A module in `.rman/` at the repository root becomes an `rman` command:
+
+```js
+// .rman/deploy.mjs
+import { defineCommand, PublishService } from 'rman';
+
+export default defineCommand({
+  describe: 'Ships what was just published to the staging cluster',
+  builder: y => y.option('stage', { choices: ['dev', 'prod'], demandOption: true }),
+  async handler({ repository }, args) {
+    const plan = await PublishService.getPlan(repository);
+    console.log(plan.filter(e => e.status === 'publish').length, '->', args.stage);
+  },
+});
+```
+
+```bash
+rman deploy --stage prod
+```
+
+It gets its own `--help` entry, its own options, and the `Repository` handed to it. For a shell step
+across every package, reach for `.rmanrc "run.<script>"` instead - see
+[docs/cli/custom-commands.md](https://github.com/panates/rman/blob/main/docs/cli/custom-commands.md) for where the line falls.
+
 ## Configuration
 
 `rman` reads config cascaded from the repository root down to each package's own directory (the
@@ -373,25 +394,24 @@ version:
 { "group": "plugins" }
 ```
 
-See [docs/api.md#configuration-rmanrc-rmanrcyml](docs/api.md#configuration-rmanrc-rmanrcyml) for the
+See [docs/rman.md#configuration-rmanrc--rmanrcyml](https://github.com/panates/rman/blob/main/docs/rman.md#configuration-rmanrc--rmanrcyml) for the
 full key reference (every `run.<script>.*` sub-key, `clean.*`, `changelog.*`, selector precedence,
 and which keys are root-level-only today).
 
-**Editor autocomplete:** `rman` ships a JSON Schema for `.rmanrc`/`.rmanrc.yml` at
-`rman/rmanrc.schema.json` - add `"$schema": "./node_modules/rman/rmanrc.schema.json"` to your
-`.rmanrc` (or the equivalent `# yaml-language-server: $schema=...` comment in `.rmanrc.yml`) to get
-autocomplete and validation in VS Code/WebStorm. For a `.rmanrc.cjs`/`.mjs`/`.js` config, wrap it in
-the exported `defineConfig()` helper instead for the same autocomplete via the `RmanConfig` type:
+**Editor autocomplete** comes from the `RmanConfig` type, so it applies to the JS forms of the
+config - wrap a `.rmanrc.cjs`/`.mjs`/`.js` in the exported `defineConfig()` helper (or annotate it
+with `/** @type {import('rman').RmanConfig} */`):
 
 ```js
 // .rmanrc.mjs
 import { defineConfig } from 'rman';
-export default defineConfig({ packageManager: 'pnpm' });
+export default defineConfig({ allowBranch: ['main'] });
 ```
 
-See
-[docs/api.md#editor-support-json-schema](docs/api.md#editor-support-json-schema) for details,
-including a WebStorm setup that needs no changes to the config file itself.
+With a plugin, import `defineConfig` from the plugin instead (`rman-node`'s carries its own keys
+into the type). The `.rmanrc`/`.rmanrc.yml` forms get no checking - see
+[docs/rman.md#editor-support-types](https://github.com/panates/rman/blob/main/docs/rman.md#editor-support-types) for why the JSON Schema that
+used to cover them was removed.
 
 ## Programmatic API
 
@@ -408,7 +428,7 @@ await VersionService.applyPlan(repository, plan, { changelog: true, push: true }
 
 Full reference, with detailed examples for every service (`VersionService`, `PublishService`,
 `ChangelogService`, `RunService`, `CiService`, `CleanService`, `ExecService`, `ListService`,
-`ImportService`, `SystemInfo`) and the `Repository`/`Package` core classes: **[docs/api.md](docs/api.md)**.
+`ImportService`, `SystemInfo`) and the `Repository`/`Package` core classes: **[docs/rman.md](https://github.com/panates/rman/blob/main/docs/rman.md)**.
 
 ## Node compatibility
 

package/cli.js

@@ -1,27 +1,31 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import colors from 'ansi-colors';
-import yargs from 'yargs';
+import * as yaml from 'js-yaml';
+import yargs, {} from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import * as buildCommand from './commands/build.command.js';
 import * as changedCommand from './commands/changed.command.js';
 import * as changelogCommand from './commands/changelog.command.js';
-import * as ciCommand from './commands/ci.command.js';
-import * as cleanCommand from './commands/clean.command.js';
+import * as configCommand from './commands/config.command.js';
 import * as diffCommand from './commands/diff.command.js';
 import * as execCommand from './commands/exec.command.js';
 import * as githubReleaseCommand from './commands/github-release.command.js';
 import * as importCommand from './commands/import.command.js';
 import * as infoCommand from './commands/info.command.js';
 import * as listCommand from './commands/list.command.js';
-import * as publishCommand from './commands/publish.command.js';
 import * as runCommand from './commands/run.command.js';
 import * as testCommand from './commands/test.command.js';
 import * as versionCommand from './commands/version.command.js';
 import { version } from './constants.js';
+import { assertNoBuiltinShadowing, loadCustomCommands } from './core/custom-command.js';
 import { Repository } from './core/repository.js';
-import { LOG_LEVELS } from './utils/logger.js';
+import { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
+import { filterPackages, readPackageFilterOptions, readRootOption } from './utils/package-filter.js';
+import { printableConfig } from './utils/printable-config.js';
+import { runBin } from './utils/run-bin.js';
 export async function runCli(options) {
     try {
         const repository = await Repository.create(options?.cwd);
@@ -37,6 +41,12 @@ export async function runCli(options) {
             describe: 'Default verbosity of the per-step log for run/build/ci (default: info, or .rmanrc "logLevel"; ' +
                 'overridable per-package via .rmanrc run.<script>.logLevel)',
             choices: LOG_LEVELS,
+        })
+            .option('config', {
+            describe: 'Show what this command would run with - its resolved options, the packages it would act ' +
+                'on, and the .rmanrc keys it reads - and run nothing',
+            type: 'boolean',
+            default: false,
         })
             .showHelpOnFail(false, 'Run with --help for available options')
             .fail((msg, err) => {
@@ -47,36 +57,218 @@ export async function runCli(options) {
                         ? err.message
                         : '';
                 console.log('\n' + colors.red(text));
-                throw msg;
+                /** A real `Error`, marked `logged` since the text above just went out: yargs hands the
+                 *  reason over as a bare string, and rethrowing that raw made bad argv indistinguishable
+                 *  from success to anything holding the promise - or the shell. */
+                const failure = new Error(typeof msg === 'string' && msg ? msg : typeof err?.message === 'string' ? err.message : 'invalid arguments');
+                failure.logged = true;
+                throw failure;
             }
-            else
-                process.exit(1);
+            /**
+             * Already printed by whoever threw it (the `logged` convention), so there is nothing to say
+             * - but it still has to **throw**, not exit.
+             *
+             * This branch called `process.exit(1)`, and `runCli` is a library entry point: rman's own
+             * bin calls it, so do `rman-node`'s fixtures and every spec. Exiting from in here took the
+             * whole process down before any caller could see the rejection - which in mocha meant the
+             * first command that failed killed the run and the suite could not report a single result.
+             * The exit belongs to the bin entry alone (see `isMain()` at the bottom), which already does
+             * it; the shell sees the same code either way.
+             */
+            const failure = new Error(err?.message || 'command failed');
+            failure.logged = true;
+            throw failure;
         });
+        /**
+         * **`--config` is applied here, once, rather than in every command.** Every command - built-in,
+         * a plugin's, a `.rman/*.mjs` one - reaches yargs through `program.command`, so wrapping that
+         * one method is what makes the flag genuinely global. Adding an option to each command instead
+         * would have meant twelve edits plus a rule for plugin authors to remember, and a flag that
+         * quietly does nothing on whichever command forgot it is worse than no flag.
+         */
+        interceptConfigFlag(repository, program);
         infoCommand.initCli(repository, program);
         listCommand.initCli(repository, program);
         runCommand.initCli(repository, program);
         buildCommand.initCli(repository, program);
-        ciCommand.initCli(repository, program);
-        cleanCommand.initCli(repository, program);
         changelogCommand.initCli(repository, program);
         testCommand.initCli(repository, program);
         versionCommand.initCli(repository, program);
-        publishCommand.initCli(repository, program);
         githubReleaseCommand.initCli(repository, program);
         execCommand.initCli(repository, program);
         changedCommand.initCli(repository, program);
         diffCommand.initCli(repository, program);
+        configCommand.initCli(repository, program);
         importCommand.initCli(repository, program);
+        /**
+         * Commands that are not built in, from two places, registered after the built-ins so the clash
+         * check below has the full list to compare against:
+         *
+         * - **plugins** (`.rmanrc "plugins"`) - a *package* contributing commands, which is how
+         *   everything Node-specific lives outside rman's core;
+         * - **`.rman/*.mjs`** - this one repository's own commands.
+         *
+         * The repository wins a name clash with a plugin, and silently: it is the more specific
+         * statement, the same way its own `.rmanrc` overrides an `extends` base. A plugin taking a
+         * *built-in's* name is still refused outright.
+         */
+        /** Already loaded: `Repository.create` had to, because a plugin's workspace provider is what
+         *  finds the packages. This is just what it brought back. */
+        const pluginCommands = repository.pluginCommands;
+        const { commands: localCommands, errors } = await loadCustomCommands(repository.dirname);
+        const localNames = new Set(localCommands.map(c => c.name));
+        const commands = [...pluginCommands.filter(c => !localNames.has(c.name)), ...localCommands];
+        assertNoBuiltinShadowing(commands, BUILT_IN_COMMANDS);
+        for (const custom of commands) {
+            program.command({
+                command: custom.command,
+                describe: custom.describe,
+                /** Forwarded, not dropped: this loop builds a *new* spec object, so anything the command
+                 *  declared and is not copied here is silently lost - `--config` printed the whole config
+                 *  for every plugin command until this line existed (measured, on `clean` and `ci`). */
+                configKeys: custom.configKeys,
+                builder: custom.builder ?? (y => y),
+                handler: args => {
+                    /** Resolved per invocation, not once at registration: `--log-level` is only known now. */
+                    const logLevel = args.logLevel ?? resolveRootLogLevel(repository);
+                    const context = {
+                        repository,
+                        package: repository.currentPackage,
+                        runBin: (bin, argv, opts) => runBin(bin, argv, { cwd: repository.dirname, logLevel, ...opts }),
+                        logger: new Logger(logLevel),
+                    };
+                    return custom.handler(context, args);
+                },
+            });
+        }
+        /** Warned about, not thrown: one unparseable file must not take the other commands with it.
+         *  Loud enough not to be mistaken for success, and it names the file and the reason - "my
+         *  command isn't there" is otherwise a long afternoon. */
+        for (const { file, reason } of errors) {
+            console.error(colors.yellow(`Skipped "${path.relative(process.cwd(), file)}": ${reason}`));
+        }
         program.demandCommand(1).strict().recommendCommands().completion();
         if (!_argv.length)
             program.showHelp();
+        /** Rejects rather than exiting, for the reason the `fail` handler above does - the bin entry
+         *  turns the rejection into an exit code. */
         else
-            await program.parseAsync().catch(() => process.exit(1));
+            await program.parseAsync();
     }
     catch (e) {
-        console.error(colors.red(e.message));
+        /** Setup failures - no `package.json` to be found, a `.rman` command shadowing a built-in -
+         *  used to be printed and then swallowed, so the shell saw success: `rman info` in the wrong
+         *  directory reported failure on stdout and 0 to whatever called it. Printed once (unless the
+         *  thrower already did, per the `logged` convention) and rethrown, so the exit code agrees
+         *  with the message. */
+        if (!e?.logged)
+            console.error(colors.red(e.message));
+        throw e;
+    }
+}
+/**
+ * Replaces `program.command` with a version that wraps every handler: with `--config` it prints
+ * what the command would run with and returns, instead of running it.
+ *
+ * One interception point rather than an option per command - see the call site. It has to go in
+ * **before** any command is registered, since it only affects registrations that pass through it.
+ */
+function interceptConfigFlag(repository, program) {
+    const register = program.command.bind(program);
+    program.command = (spec) => {
+        if (!spec || typeof spec !== 'object' || typeof spec.handler !== 'function')
+            return register(spec);
+        const run = spec.handler;
+        return register({
+            ...spec,
+            handler: (args) => (args.config ? printCommandConfig(repository, spec, args) : run(args)),
+        });
+    };
+}
+/**
+ * What a command would run with: its resolved options, the packages it would act on, and the
+ * `.rmanrc` those packages carry.
+ *
+ * The three parts answer the three ways a run surprises someone. **Options** is the parsed argv -
+ * what *this invocation* asked for, plus any default yargs itself declares. Most of rman's own
+ * defaults are not yargs defaults (`run`'s `bail`/`topo`/`progress` are resolved per package inside
+ * `RunService`, from `.rmanrc run.<script>.*`), so an option missing here means "not stated on the
+ * command line", and the `.rmanrc` section below is where its value comes from. **Packages** is the
+ * set after `--scope`/`--ignore`/
+ * `--deps`/`skip`, computed the way the command itself computes it, because a config that is
+ * perfect for a package the command never reaches explains nothing. **Config** is narrowed to the
+ * keys the command declares it reads (`configKeys` on the command object, which yargs ignores) and
+ * is the whole effective config otherwise - the honest answer when nobody has said which half
+ * matters.
+ */
+function printCommandConfig(repository, spec, args) {
+    const name = String(spec.command).split(/\s+/)[0];
+    const comment = (text) => (process.stdout.isTTY ? colors.gray(text) : text);
+    console.log(comment(`# ${name} --config: nothing was run.`));
+    console.log(`command: ${name}`);
+    const options = readOptions(args);
+    console.log(Object.keys(options).length
+        ? `options:\n${indent(yaml.dump(printableConfig(options), { noRefs: true }).trimEnd())}`
+        : `options: {}${comment('   # nothing but defaults')}`);
+    const targets = commandTargets(repository, args);
+    console.log(`packages: ${targets.length ? `[${targets.map(p => p.name).join(', ')}]` : '[]'}`);
+    const keys = typeof spec.configKeys === 'function' ? spec.configKeys(args) : spec.configKeys;
+    console.log(comment(`# .rmanrc${keys?.length ? `, the keys ${name} reads: ${keys.join(', ')}` : ', in full'}`));
+    /**
+     * **The root package is always listed, even when it is not a target.** A repo-wide setting is
+     * read off the root - `packageManager`, `allowBranch`, `version.*`, `githubRelease.*` - so
+     * showing only the targets answered `rman ci --config` with `pkg-a: {}`, which reads as "nothing
+     * is configured" about the one key `ci` actually reads (measured).
+     */
+    const shown = [...targets];
+    if (!shown.some(p => p === repository.rootPackage))
+        shown.push(repository.rootPackage);
+    const config = {};
+    for (const pkg of shown)
+        config[pkg.name] = keys?.length ? pick(pkg.config, keys) : pkg.config;
+    console.log(indent(yaml.dump(printableConfig(config), { noRefs: true, lineWidth: 100 }).trimEnd()));
+    if (!targets.includes(repository.rootPackage)) {
+        console.log(comment(`# "${repository.rootPackage.name}" is the root - listed because repo-wide keys are read there.`));
     }
 }
+/** The parsed argv, minus what yargs adds and minus the camelCase twin of every dashed option -
+ *  both spellings are the same option, and printing both reads as two settings. */
+function readOptions(args) {
+    const dashed = new Set(Object.keys(args).filter(k => k.includes('-')));
+    const camel = new Set([...dashed].map(k => k.replace(/-([a-z])/g, (_, c) => c.toUpperCase())));
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (key === '_' || key === '$0' || key === 'config' || camel.has(key))
+            continue;
+        result[key] = value;
+    }
+    return result;
+}
+/** The packages the command would act on - `filterPackages` with the command's own options, so
+ *  this is the same set the command will compute, `skip` included. Narrowed to the current package
+ *  for a command that scopes by directory, unless `--root` says otherwise. */
+function commandTargets(repository, args) {
+    const current = repository.currentPackage;
+    if (current && !readRootOption(args))
+        return [current];
+    return filterPackages(repository.getPackages(), readPackageFilterOptions(args));
+}
+/** The named config paths only - `"run.build"` keeps just that subtree, under that path. */
+function pick(config, keys) {
+    const result = {};
+    for (const key of keys) {
+        const value = key.split('.').reduce((node, part) => (node == null ? undefined : node[part]), config);
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+function indent(text) {
+    return text
+        .split('\n')
+        .map(line => (line ? `  ${line}` : line))
+        .join('\n');
+}
 function isMain() {
     try {
         return !!process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
@@ -86,4 +278,24 @@ function isMain() {
     }
 }
 if (isMain())
-    runCli().catch(() => 0);
+    runCli().catch(() => process.exit(1));
+/** Every name a built-in command answers to - what a `.rman/*.mjs` command may not take. Kept here
+ *  rather than read back out of yargs (which exposes no such list) and pinned by a test against the
+ *  `command:` strings in `src/commands/*.command.ts`, so adding a command can't quietly leave a
+ *  repository's own able to shadow it. */
+const BUILT_IN_COMMANDS = [
+    'build',
+    'changed',
+    'changelog',
+    'completion',
+    'config',
+    'diff',
+    'exec',
+    'github-release',
+    'import',
+    'info',
+    'list',
+    'run',
+    'test',
+    'version',
+];

package/commands/build.command.js

@@ -4,6 +4,7 @@ import { applyRunOptions, readRunOptions } from './run.command.js';
 export function initCli(repository, program) {
     program.command({
         command: 'build',
+        configKeys: ['run.build'],
         describe: 'Alias for "run build"',
         builder: cmd => applyRunOptions(cmd).example('$0 build', '# Builds packages'),
         handler: async (args) => {

package/commands/changed.command.js

@@ -1,5 +1,5 @@
 import colors from 'ansi-colors';
-import { VersionService } from '../services/version.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
 import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
 export function initCli(repository, program) {
     program.command({
@@ -11,7 +11,7 @@ export function initCli(repository, program) {
             type: 'boolean',
         }),
         handler: async (args) => {
-            const plan = await VersionService.getPlan(repository, readPackageFilterOptions(args));
+            const plan = await VersionPlanService.getPlanner().getPlan(repository, readPackageFilterOptions(args));
             const changed = plan.filter(e => e.status === 'bump');
             if (args.json) {
                 console.log(JSON.stringify(changed.map(e => ({ name: e.package.name, group: e.group, from: e.from, to: e.to, reason: e.reason })), undefined, 2));

package/commands/changelog.command.js

@@ -1,19 +1,22 @@
 import colors from 'ansi-colors';
+import { ChangeHashService } from '../services/change-hash.service.js';
 import { ChangelogService } from '../services/changelog.service.js';
 import { Logger, resolveRootLogLevel } from '../utils/logger.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
 export function initCli(repository, program) {
     program.command({
         command: 'changelog',
+        configKeys: ['changelog', 'publish.skip'],
         describe: 'Generates a changelog per package from unreleased commits',
-        builder: cmd => applyPackageFilterOptions(cmd)
+        builder: cmd => applyRootOption(applyPackageFilterOptions(cmd), 'Generate')
             .example('$0 changelog', "# Auto-detects each package's own last release tag (or npm version)")
             .example('$0 changelog --from <hash> --write', '# Since a specific commit, written to file')
             .option('from', {
             describe: 'Generate the changelog since this commit/hash, applied the same way to every package. ' +
-                'Default (also "npm" explicitly): auto-detect per package from its own most recent release ' +
-                'tag - same as "version"/"changed" - falling back to its published npm version (no tag yet), ' +
-                "then to its whole history for a package that's never been released at all",
+                'Default (also "auto" explicitly): auto-detect per package from its own most recent release ' +
+                'tag - same as "version"/"changed" - falling back to the version its own ecosystem\'s ' +
+                "registry reports (no tag yet), then to its whole history for a package that's never been " +
+                'released at all',
             type: 'string',
         })
             .option('write', {
@@ -24,12 +27,6 @@ export function initCli(repository, program) {
             describe: "With --write, the file to prepend into, relative to each package's own directory " +
                 '(default: "CHANGELOG.md", or .rmanrc "changelog.filePath")',
             type: 'string',
-        })
-            .option('root', {
-            alias: 'r',
-            describe: 'Generate for 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',
         })
             .option('include-skipped', {
             describe: 'Also generate for a package with .rmanrc "publish.skip" - excluded by default',
@@ -46,10 +43,11 @@ export function initCli(repository, program) {
             const from = args.from;
             const write = args.write;
             const logger = new Logger(args.logLevel ?? resolveRootLogLevel(repository));
-            if (!from || from === 'npm') {
-                // Auto-detection is mostly local git work, but the npm fallback it can reach for (only
-                // when a package has no tag at all) is a network round trip per package - without this,
-                // the command looks hung for that stretch instead of just busy.
+            if (!from || from === ChangeHashService.AUTO) {
+                // Auto-detection is mostly local git work, but the registry fallback it can reach for
+                // (only when a package has no tag at all, and only if the package's own ecosystem provides
+                // one) is a network round trip per package - without this, the command looks hung for that
+                // stretch instead of just busy.
                 logger.info(colors.gray("Detecting each package's last release..."));
             }
             const options = {