rman 1.2.5 → 2.0.0-beta.2

package/README.md

@@ -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 (needs rman-node)
+# Publish everything that isn't already on the registry
 rman publish
 ```
 
@@ -90,17 +90,29 @@ worked examples of every single command, see **[docs/cli-rman.md](https://github
 | [`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 whose version isn't on its registry yet. |
 | [`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:
+**`ci` and `clean` come from the `node` built-in**, which ships inside this package - each is about
+npm or TypeScript rather than about repositories, so nothing it contributes exists until a
+repository asks for it:
 
 ```yaml
-plugins: ['rman-node']
+plugins: ['node']   # by name
+platform: node      # the same statement at a repository root, plus which technology its packages are
 ```
 
+Or say nothing: a repository that declares no technology gets the one its own files imply, announced
+on stderr rather than guessed silently. It used to take a second package (`rman-node`) and a
+`.rmanrc` before anything worked at all.
+
+**`publish` is here, but *where* a package ships is a plugin's to say.** A **publish target** is
+one answer to "is this version on the registry, and how do I push it" - rman ships `docker`
+(any language's project can push an image), and the `node` built-in contributes `npm` with the flags
+that only mean something there (`--access`, `--tag`, `--otp`, `--registry`, ...). So
+`rman publish --help` lists what this repository's targets actually understand.
+
 Options shared across several commands:
 
 - **`skip`** (`.rmanrc`, per package): leave this package alone - honoured by every command that
@@ -108,8 +120,10 @@ Options shared across several commands:
 - **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 -
+  for the full semantics. **`--scope /` is the repository's own root package** - the same `/`
+  `.rmanrc`'s `"[/]"` block uses, and not a glob, so `--scope '*'` means the members and a glob
+  never picks up the root by name.
+- **`--from-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`, `version`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
@@ -134,9 +148,10 @@ rman list --scope '@myorg/*' --ignore '*-internal'
 
 ### `rman info`
 
-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.
+Prints local environment (OS/CPU/memory, Node, git) and repository information. A platform adds its
+own ecosystem's part - the `node` built-in reports whichever package manager
+`.rmanrc "packageManager"` names, plus the installed `rman` packages, and only in a repository that
+asked for it.
 
 ```bash
 rman info
@@ -192,12 +207,12 @@ rman exec --topo=false pwd         # every package independently, alphabetical o
 ### `rman config`
 
 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
+cascade, `"[selector]"` blocks, `extends` and `${{ ... }}` expressions have all been
 applied. What rman actually sees there, which no single file shows.
 
 ```bash
 rman config                  # the package you are standing in
-rman config --root           # the repository root's own config instead
+rman config --from-root           # the repository root's own config instead
 rman config --json | jq .run
 ```
 
@@ -266,6 +281,29 @@ Release-As: patch
 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 whose current version isn't on its registry yet. Shows the plan first, then
+asks for confirmation (unless `--yes` or `--dry-run`), then publishes in topological order,
+dependencies before dependents.
+
+```bash
+rman publish                    # show the plan, then ask for confirmation
+rman publish --yes              # publish immediately, no confirmation
+rman publish --dry-run --json   # "is there anything to release?", for a CI gate
+rman publish --target docker    # only the packages configured for that target
+```
+
+**Where a package ships is a publish target, and a target is a contribution.** rman ships `docker`;
+the `node` built-in contributes `npm`. A package says where it goes with `.rmanrc "publish.target"`, or says
+nothing and goes wherever the installed targets claim it - so a Cargo package is never assumed to be
+an npm one. Each target adds its own flags, so `rman publish --help` is worth reading in your own
+repository. See
+[docs/cli/publish.md](https://github.com/panates/rman/blob/main/docs/cli/publish.md).
+
+It never looks at whether `version` ran: it inspects what is on disk and on each registry, so it
+behaves the same right after a bump or days later, and re-running is safe.
+
 ### `rman github-release`
 
 Creates the repository's GitHub Release for the version that just shipped - one per run, named after
@@ -294,7 +332,7 @@ 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`)
+## Shared config (`extends`) and adding to it (`value`)
 
 House rules live in one package, and a repository names it:
 
@@ -305,13 +343,18 @@ extends: '@panates/rman-monorepo'
 '[*]':
   run:
     build:
-      +before: 'rm -rf ./cache' # adds to the base's step, rather than replacing it
+      # adds to the base's step, rather than replacing it
+      before: "${{ [...value, 'rm -rf ./cache'] }}"
 ```
 
 `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).
+chained. `value` is what 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. It
+is the list form of whatever is underneath, so the spread needs no guard even when nothing is.
+See [docs/rman.md](https://github.com/panates/rman/blob/main/docs/rman.md#inheriting-a-shared-config-extends).
+
+There was a `+key` prefix for this and it is gone; one still in a config is refused, naming what to
+write instead.
 
 ## Your own commands
 
@@ -408,8 +451,9 @@ import { defineConfig } from 'rman';
 export default defineConfig({ allowBranch: ['main'] });
 ```
 
-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
+A plugin's keys arrive by declaration merging, so annotating with `RmanConfig` types them too;
+`RmanNodeConfig` is the alias that says out loud which set a config is using. 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.
 

package/cli.d.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
+/** Every built-in command, registered by importing them - see `commands.ts` for why the list lives
+ *  there rather than here. */
+import './commands.js';
+import { RmanApplication } from './core/application.js';
 export declare function runCli(options?: {
     argv?: string[];
     cwd?: string;
+    app?: RmanApplication;
 }): Promise<void>;

package/cli.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+/** Every built-in command, registered by importing them - see `commands.ts` for why the list lives
+ *  there rather than here. */
+import './commands.js';
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,24 +9,15 @@ import colors from 'ansi-colors';
 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 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 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 { RmanApplication } from './core/application.js';
+import { commandName, toYargsCommand } from './core/command-builder.js';
+import { assertNoBuiltinShadowing, defaultCommandGlobs, loadCustomCommands, } from './core/custom-command.js';
+import { checkCustomCommand } from './core/plugin-loader.js';
 import { Repository } from './core/repository.js';
+import { commandRegistry } from './interfaces/rman-config.interface.js';
 import { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
-import { filterPackages, readPackageFilterOptions, readRootOption } from './utils/package-filter.js';
+import { filterPackages, readFromRootOption, readPackageFilterOptions } from './utils/package-filter.js';
 import { printableConfig } from './utils/printable-config.js';
 import { runBin } from './utils/run-bin.js';
 export async function runCli(options) {
@@ -41,7 +35,10 @@ export async function runCli(options) {
         return;
     }
     try {
-        const repository = await Repository.create(options?.cwd);
+        /** One application per run, made here so `--log-level` reaches its logger, and handed to
+         *  `Repository.create` rather than found through a global. */
+        const app = options?.app ?? new RmanApplication();
+        const repository = await Repository.create(options?.cwd, { app });
         const program = yargs(_argv)
             .scriptName('rman')
             .version(version)
@@ -81,7 +78,7 @@ export async function runCli(options) {
              * - 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
+             * bin calls it, so do the 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
@@ -99,60 +96,94 @@ export async function runCli(options) {
          * 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);
-        changelogCommand.initCli(repository, program);
-        testCommand.initCli(repository, program);
-        versionCommand.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:
+         * **Built-ins come from `commandRegistry`, in the order their modules were imported.** Each
+         * entry is a register function that has not run yet - it runs here, with the repository, and
+         * returns the command's declaration; `toYargsCommand` is the only thing that knows how a
+         * declaration becomes a yargs registration.
          *
-         * - **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 thirteen hand-written `initCli(repository, program)` calls this replaces were the second
+         * place a command had to be listed, and the list the shadow check guards with was a third.
+         */
+        const builtIns = commandRegistry.map(register => register(app));
+        for (const meta of builtIns)
+            program.command(toYargsCommand(meta));
+        /**
+         * Commands that are not built in, all from **one** key: `.rmanrc "commands"`, whose default
+         * value is `.rman/*.{js,mjs,cjs}`.
+         *
+         * An entry is a command or a glob naming modules that export one, so a package contributing
+         * commands (a built-in's, a plugin's) and a repository writing its own reach yargs by the same path - there
+         * is one source of non-built-in commands and one precedence slot. A plugin used to hand them
+         * over separately through `addCommand`, which is the step this replaces.
+         *
+         * Registered after the built-ins so the shadow check below has the full list to compare
+         * against. A command taking a *built-in's* name is refused outright.
+         */
+        const { globs, direct } = commandEntries(repository);
+        const { commands: loaded, errors } = await loadCustomCommands(globs);
+        /**
+         * The two authoring forms, resolved the same way - a declarative one's factory runs here,
+         * where `app.repository` exists, rather than when the config was read.
+         *
+         * **The file name is the fallback for `command`**, which is the convention a command loaded
+         * from a *file* has and one written straight into the config has not: `checkCustomCommand`
+         * refuses nameless metadata, and an inline command has nothing to fall back on, so it must say
+         * its own name. Spread *under* the factory's result, so metadata that does declare one -
+         * `deploy <stage>`, with its positionals - wins.
+         *
+         * The name comes from what the factory *returned*, not from the file: those differ exactly
+         * when the metadata declared one, and using the file name would leave the clash check
+         * comparing something yargs never registered.
+         */
+        const localModules = [...direct, ...loaded].map(c => {
+            if (!c.register)
+                return { name: c.name, file: c.file, module: toCustomModule(c.custom, repository, app) };
+            const declared = c.register(app);
+            const meta = checkCustomCommand({ ...declared, command: declared.command?.trim() || c.name }, c.file);
+            return { name: commandName(meta.command), file: c.file, module: toYargsCommand(meta) };
+        });
+        /**
+         * **One command per name, keeping the last** - which is the precedence that already applied,
+         * made visible instead of left to yargs.
          *
-         * 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.
+         * A repository's own `.rman/check.mjs` overriding a command its config contributed is the
+         * intended escape hatch, and it is deliberately not an error: the same precedence a package's
+         * own `.rmanrc` has over an `extends` base. But both were being *registered*, and what that
+         * cost was the help output - measured, `rman --help` listed `deploy` twice, once with each
+         * description, and nothing said which of the two would run.
+         *
+         * Only the listing was wrong; the override itself was already clean (`rman deploy --help`
+         * showed the winner's options alone, and the loser's flag was rejected), which is why this is
+         * a registration fix and not a change to how a clash resolves. Registered later wins because
+         * `loaded` follows `direct` - a `.rman/` file after a contributed command - and yargs took the
+         * last, so keeping the last keeps today's behaviour exactly.
+         *
+         * The survivor takes the *loser's* position in the list, since that is where the name was
+         * first seen. Help ordering only.
+         */
+        const byName = new Map();
+        for (const command of localModules)
+            byName.set(command.name, command);
+        const commands = [...byName.values()];
+        /**
+         * Said out loud, at `verbose`, because deduplicating silently is what would make this the
+         * trap it is warned about elsewhere: before, two rows at least hinted that something was
+         * doubled - after, the overridden command is simply absent, and "my plugin's command does
+         * nothing" has no thread to pull. Not a warning: an override is a correct thing to do, and a
+         * repository that does it on purpose should not be nagged on every invocation.
          */
-        /** 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);
-                },
-            });
+        if (commands.length < localModules.length) {
+            const logger = new Logger(argvLogLevel(_argv) ?? resolveRootLogLevel(repository));
+            const survivors = new Set(commands);
+            for (const lost of localModules.filter(c => !survivors.has(c))) {
+                const winner = byName.get(lost.name);
+                logger.verbose(`"${lost.name}" from ${lost.file} is overridden by ${winner.file}.`);
+            }
         }
+        assertNoBuiltinShadowing(commands, builtInNames(builtIns));
+        for (const { module } of commands)
+            program.command(module);
         /** 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. */
@@ -199,6 +230,56 @@ export async function runCli(options) {
         throw e;
     }
 }
+/**
+ * Everything `.rmanrc "commands"` declares across the repository, split into the globs to load and
+ * the commands written straight into the config.
+ *
+ * **Collected from the root and from every package**, because `commands` is not a root-level key -
+ * a package's own `.rmanrc` may contribute one, and a glob was anchored to that file when it was
+ * read. The commands themselves are repository-wide; there is one command list, so a package
+ * declaring one is contributing it to the repository. (`plugins` and `publishTargets` cannot work
+ * this way: they are read before the packages exist, because a plugin is what finds them.)
+ *
+ * The cascade means a root-declared entry also appears in each package's resolved config, so the
+ * same one arrives many times over. Globs are de-duplicated here and by resolved *file* again in
+ * the loader - the second pass is the one that matters, since two different globs can name one
+ * file. Inline commands are de-duplicated by identity, which is what the cascade produces.
+ *
+ * The `.rman/` default is used only when nothing was declared anywhere. Declaring `commands` and
+ * still wanting `.rman/` scanned means naming it: the key appends to other layers, not to a
+ * built-in fallback, and a default that could never be turned off is not a default.
+ */
+function commandEntries(repository) {
+    const globs = new Set();
+    const seen = new Set();
+    const direct = [];
+    for (const config of [repository.rootPackage.config, ...repository.getPackages().map(p => p.config)]) {
+        const value = config?.commands;
+        for (const entry of Array.isArray(value) ? value : value ? [value] : []) {
+            if (typeof entry === 'string') {
+                if (entry.trim())
+                    globs.add(entry);
+                continue;
+            }
+            if (!entry || seen.has(entry))
+                continue;
+            seen.add(entry);
+            /** No file to fall back on, so the metadata has to name itself - `checkCustomCommand` says
+             *  so when it does not. `"commands"` stands in for the file in that message. */
+            if (typeof entry === 'function') {
+                direct.push({ name: '', file: '"commands"', register: entry });
+            }
+            else {
+                /** `checkCustomCommand` is what refuses a nameless one, with the message that names the
+                 *  omission - reached here rather than at registration so an inline command is checked
+                 *  the same way a plugin's used to be. */
+                const custom = checkCustomCommand(entry, '"commands"');
+                direct.push({ name: commandName(custom.command), file: '"commands"', custom });
+            }
+        }
+    }
+    return { globs: globs.size ? [...globs] : defaultCommandGlobs(repository.dirname), direct };
+}
 /**
  * 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.
@@ -279,10 +360,10 @@ function readOptions(args) {
 }
 /** 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. */
+ *  for a command that scopes by directory, unless `--from-root` says otherwise. */
 function commandTargets(repository, args) {
     const current = repository.currentPackage;
-    if (current && !readRootOption(args))
+    if (current && !readFromRootOption(args))
         return [current];
     return filterPackages(repository.getPackages(), readPackageFilterOptions(args));
 }
@@ -312,23 +393,68 @@ function isMain() {
 }
 if (isMain())
     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',
-];
+/**
+ * Every name a repository's own command may not take - **derived from what was actually
+ * registered**, not listed.
+ *
+ * It used to be a hand-maintained array, because yargs exposes no such list, and a spec had to pin
+ * it against the command sources so that adding a command could not quietly leave a repository's
+ * own able to shadow it. With the built-ins coming out of `commandRegistry` the list and the
+ * registrations cannot disagree: they are the same walk.
+ *
+ * Aliases count - `ls` is `list`, and shadowing it would be the same mistake. `completion` is
+ * yargs' own command rather than one of ours, so it is the one name still written here.
+ */
+function builtInNames(metas) {
+    const names = metas.flatMap(meta => [commandName(meta.command), ...(meta.aliases ?? [])]);
+    return [...names, 'completion'];
+}
+/**
+ * A `CustomCommand` - a `.rman/*.mjs` command, or a plugin's written the older way - as the yargs
+ * registration it describes. `toYargsCommand` is the same function for a *declarative* command;
+ * this is the other authoring form, and both end at one `program.command`.
+ *
+ * **Every field has to be copied deliberately**, because this builds a new object: anything the
+ * command declared and this forgets is silently lost. `--config` printed the whole config for every
+ * plugin command until `configKeys` was on this list (measured, on `clean` and `ci`).
+ */
+function toCustomModule(custom, repository, app) {
+    return {
+        command: custom.command,
+        describe: custom.describe,
+        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, app, ...opts }),
+                logger: new Logger(logLevel),
+            };
+            return custom.handler(context, args);
+        },
+    };
+}
+/**
+ * `--log-level` read straight off argv, for a message printed **before** yargs parses anything.
+ *
+ * Commands are registered before `parseAsync` runs - registering them is what makes parsing
+ * possible - so a diagnostic emitted at registration time cannot come from `args.logLevel`.
+ * Measured: the override note in `runCli` was silent for `--log-level verbose` and appeared only
+ * when `.rmanrc` said so, which is the one spelling a reader would not reach for first.
+ *
+ * A peek, not a parser. Both spellings, first match wins, and a value that is not a level is left
+ * alone for yargs to reject in its own words - this must not become a second place where an
+ * invalid `--log-level` is diagnosed.
+ */
+function argvLogLevel(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const value = arg === '--log-level' ? argv[i + 1] : arg.startsWith('--log-level=') ? arg.slice(12) : undefined;
+        if (value && LOG_LEVELS.includes(value))
+            return value;
+    }
+    return undefined;
+}