rman 1.3.0 → 2.0.0-beta.3

package/core/{merge-config.d.ts → config/merge-config.d.ts}

@@ -1,8 +1,19 @@
-/** The prefix that turns a key into an append instead of a replacement: `+before` adds to whatever
- *  `before` already resolved to, rather than taking its place. */
-export declare const APPEND_PREFIX = "+";
+/** Where a repository keeps command modules of its own, as a glob or a list of them. */
+export declare const COMMANDS_KEY = "commands";
 /**
- * Keys that **append whether or not you ask** - `+plugins` is accepted and means nothing extra.
+ * Keys that **append rather than replace**, which is the only append rman has.
+ *
+ * **There used to be a `+key` prefix on every key, and it is gone.** It said "add to what this
+ * resolved to below", which is exactly what `value` says - and `value` says it better: it composes
+ * (three layers each deriving from the one under them), it can reorder or filter rather than only
+ * append, and it does not need the merge to keep an append *outstanding* until the layer it belongs
+ * to turns up. The prefix also carried a bug `value` does not: appending onto a value that was a
+ * sole `${{ }}` expression returning an array nested it, because the merge promoted the expression
+ * *string* to a list and interpolation only later turned that element into the array (measured,
+ * `[['a','b'],'c']` where a literal list gave `['a','b','c']`).
+ *
+ * What is left is this list, where appending is not a choice the author makes per layer but what
+ * the key *means*.
  *
  * `plugins` is the whole list because it is the one key where replacing is never what anyone meant:
  * every other setting has a value a closer layer can sensibly overrule, while a plugin *adds
@@ -10,6 +21,12 @@ export declare const APPEND_PREFIX = "+";
  * brought. Replacing was the silent failure - `extends`-ing a toolchain config and then adding a
  * plugin of your own dropped the toolchain's, and what you noticed was `Unknown argument: publish`.
  *
+ * `commands` and `publishTargets` are the same kind of statement - what this repository has, in
+ * instances or in globs naming them - so they append for the same reason: a repository adding one
+ * of its own never means "and stop loading the ones my shared config brought". All three are what
+ * a config *contributes*, and a contribution list is exactly the case where replacing is never
+ * what anyone meant.
+ *
  * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
@@ -24,7 +41,7 @@ export declare const ALWAYS_APPEND: readonly string[];
  * carry one.
  *
  * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
- * through `mergeConfig`, `finalizeConfig` and `rman config` without any of them having to know it
+ * through `mergeConfig` and `rman config` without either of them having to know it
  * is there.
  *
  * Each entry is a link, not a single slot: three layers each deriving from the one below need
@@ -51,47 +68,29 @@ export interface PreviousValue {
 }
 /** Only these two can ask for `value`, so only these two are worth remembering a previous for. */
 export declare function carriesPreviousValue(value: unknown): boolean;
-/** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
-export declare function appendTarget(key: string): string | undefined;
 /**
  * Merges `source` onto `target` in place, the way every layer of rman config is combined - a
  * directory's own file forms, the directory chain, `"[selector]"` blocks, and an `extends` base.
  * One implementation for all of them, so they cannot disagree about what an append means.
  *
- * Plain keys replace, and nested objects merge recursively, as a deep merge always has. What this
- * adds is `+key`:
+ * Plain keys replace and nested objects merge recursively, as a deep merge always has. The two
+ * things it adds are the contribution keys, which append instead (`ALWAYS_APPEND`), and the record
+ * of what each key held underneath, so a closer layer can derive from it as `value`.
  *
  * ```yaml
- * # the root says          before: "rm ./build"
- * # a package adds        +before: "rm ./cache"
- * # it resolves to         before: ["rm ./build", "rm ./cache"]
+ * # the root says   before: "rm ./build"
+ * # a package says  before: "${{ [...value, 'rm ./cache'] }}"
+ * # it resolves to   before: ["rm ./build", "rm ./cache"]
  * ```
  *
- * Appending is the half a shared config can't live without: a base that declares
- * `before: ["rm ./build"]` otherwise forces every repository wanting one more step to restate the
- * whole list - which is a copy of the base, silently frozen at the version it was copied from.
- *
- * A scalar is promoted to a list on the way, so neither side has to be written as an array. With
- * nothing inherited, `+key` simply produces a one-element list.
+ * That is the half a shared config cannot live without: a base declaring `before: ["rm ./build"]`
+ * otherwise forces every repository wanting one more step to restate the whole list - which is a
+ * copy of the base, silently frozen at the version it was copied from.
  *
- * On a value that isn't a list, the prefix is **ignored** rather than an error, because there the
- * two spellings already mean the same thing: objects merge whether or not you asked them to, and a
- * scalar has nothing to append to, so `+key` behaves exactly as `key` would. Nothing is silently
- * dropped - the value still lands.
- *
- * `key` and `+key` in the same object are both honored, in that order: the replacement happens
- * first, then the append lands on top of it.
+ * **A `+key` prefix used to mean this and is refused now**, naming the key and what to write
+ * instead - see the check at the top of the loop.
  */
 export declare function mergeConfig(target: Record<string, any>, source: Record<string, any>, 
 /** The file `source` was read from, recorded per key - see `ORIGINS`. A caller merging a value it
  *  built rather than read (a selector block already carrying its own origins) passes nothing. */
 origin?: string): Record<string, any>;
-/**
- * Turns any `+key` still outstanding into its plain key, as a list - the "nothing was inherited"
- * case, where an append simply is the whole value.
- *
- * Called once on a fully resolved config, and only there: until then an outstanding append may
- * still find the layer it belongs to, and a config handed to a command must carry no `+key` at all
- * or every reader would have to know about them.
- */
-export declare function finalizeConfig<T>(config: T): T;

package/core/config/merge-config.js

@@ -0,0 +1,260 @@
+import path from 'node:path';
+import { isPlainObject } from '@jsopen/objects';
+/** Where a repository keeps command modules of its own, as a glob or a list of them. */
+export const COMMANDS_KEY = 'commands';
+/** The keys whose string entries are globs, and so have to be anchored to the file that wrote
+ *  them - see `anchorContributions`. The same four that always append. */
+const GLOB_KEYS = ['plugins', 'platforms', COMMANDS_KEY, 'publishTargets'];
+/**
+ * Keys that **append rather than replace**, which is the only append rman has.
+ *
+ * **There used to be a `+key` prefix on every key, and it is gone.** It said "add to what this
+ * resolved to below", which is exactly what `value` says - and `value` says it better: it composes
+ * (three layers each deriving from the one under them), it can reorder or filter rather than only
+ * append, and it does not need the merge to keep an append *outstanding* until the layer it belongs
+ * to turns up. The prefix also carried a bug `value` does not: appending onto a value that was a
+ * sole `${{ }}` expression returning an array nested it, because the merge promoted the expression
+ * *string* to a list and interpolation only later turned that element into the array (measured,
+ * `[['a','b'],'c']` where a literal list gave `['a','b','c']`).
+ *
+ * What is left is this list, where appending is not a choice the author makes per layer but what
+ * the key *means*.
+ *
+ * `plugins` is the whole list because it is the one key where replacing is never what anyone meant:
+ * every other setting has a value a closer layer can sensibly overrule, while a plugin *adds
+ * commands and seams*, and a repository naming one has no wish to lose the ones its shared config
+ * brought. Replacing was the silent failure - `extends`-ing a toolchain config and then adding a
+ * plugin of your own dropped the toolchain's, and what you noticed was `Unknown argument: publish`.
+ *
+ * `commands` and `publishTargets` are the same kind of statement - what this repository has, in
+ * instances or in globs naming them - so they append for the same reason: a repository adding one
+ * of its own never means "and stop loading the ones my shared config brought". All three are what
+ * a config *contributes*, and a contribution list is exactly the case where replacing is never
+ * what anyone meant.
+ *
+ * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
+ * layer, which is only acceptable where the value is a set of contributions rather than a decision.
+ */
+export const ALWAYS_APPEND = ['plugins', 'platforms', COMMANDS_KEY, 'publishTargets'];
+/**
+ * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
+ *
+ * A **symbol-keyed chain on the containing object**, one entry per key, rather than something
+ * attached to the value itself. It started as a wrapper around a *function*, which is the only kind
+ * of value you can hang a property on - and that is exactly why it had to change: `value` belongs to
+ * an expression (`"${{ [...value, 'x'] }}"`) just as much as to a function, and a string cannot
+ * carry one.
+ *
+ * A symbol is invisible to `Object.entries`, `JSON.stringify` and js-yaml, so the chain travels
+ * through `mergeConfig` and `rman config` without either of them having to know it
+ * is there.
+ *
+ * Each entry is a link, not a single slot: three layers each deriving from the one below need
+ * `A <- expr2 <- expr3`, and one slot would have lost `A` the moment `expr3` arrived.
+ */
+export const PREVIOUS_VALUES = Symbol('rman.previousValues');
+/**
+ * Which file each key came from, so an error can name it.
+ *
+ * A config is merged from several files before anything reads it - a directory's own four forms, an
+ * `extends` base, every `"[selector]"` block, and one layer per directory from the root down - so by
+ * the time an expression fails, `version.commitMessage` could have been written in any of them.
+ * Saying only the key sends the reader looking through all of them.
+ *
+ * Recorded the same way `PREVIOUS_VALUES` is, for the same reason: a symbol on the containing
+ * object, invisible to `Object.entries`, `JSON.stringify` and js-yaml, so it travels with the config
+ * without any reader having to know it is there.
+ */
+export const ORIGINS = Symbol('rman.origins');
+/** Only these two can ask for `value`, so only these two are worth remembering a previous for. */
+export function carriesPreviousValue(value) {
+    return typeof value === 'function' || (typeof value === 'string' && value.includes('${{'));
+}
+/**
+ * Merges `source` onto `target` in place, the way every layer of rman config is combined - a
+ * directory's own file forms, the directory chain, `"[selector]"` blocks, and an `extends` base.
+ * One implementation for all of them, so they cannot disagree about what an append means.
+ *
+ * Plain keys replace and nested objects merge recursively, as a deep merge always has. The two
+ * things it adds are the contribution keys, which append instead (`ALWAYS_APPEND`), and the record
+ * of what each key held underneath, so a closer layer can derive from it as `value`.
+ *
+ * ```yaml
+ * # the root says   before: "rm ./build"
+ * # a package says  before: "${{ [...value, 'rm ./cache'] }}"
+ * # it resolves to   before: ["rm ./build", "rm ./cache"]
+ * ```
+ *
+ * That is the half a shared config cannot live without: a base declaring `before: ["rm ./build"]`
+ * otherwise forces every repository wanting one more step to restate the whole list - which is a
+ * copy of the base, silently frozen at the version it was copied from.
+ *
+ * **A `+key` prefix used to mean this and is refused now**, naming the key and what to write
+ * instead - see the check at the top of the loop.
+ */
+export function mergeConfig(target, source, 
+/** The file `source` was read from, recorded per key - see `ORIGINS`. A caller merging a value it
+ *  built rather than read (a selector block already carrying its own origins) passes nothing. */
+origin) {
+    for (const [key, value] of Object.entries(source)) {
+        /**
+         * **A retired `+key` is refused, not ignored.** rman validates no config keys at all - there is
+         * no schema behind `.rmanrc`/`.rmanrc.yml` any more - so an unknown key is silent, and a
+         * repository upgrading from 1.x with `+before:` in its config would simply lose that step with
+         * nothing said. Measured before this check: `+include: ['extra']` resolved to the inherited
+         * list unchanged, exactly as if the line were not there.
+         *
+         * Here rather than in a validator, because this is the one function every layer passes through,
+         * and it is the only place that still knows which file the key came from.
+         */
+        if (key.length > 1 && key.startsWith('+')) {
+            const plain = key.slice(1);
+            throw new Error(`"${key}" is no longer a config key${origin ? ` (${origin})` : ''}. The \`+key\` prefix is ` +
+                `gone: write "${plain}" as a value that derives from what it inherited - ` +
+                `\`${plain}: ({ value }) => [...value, 'x']\`, or \`"\${{ [...value, 'x'] }}"\` in YAML. ` +
+                `\`value\` is the layers below this one, and spreads as empty when there are none.`);
+        }
+        /** `plugins`/`commands`/`publishTargets`: additive at every layer, so the closer one adds
+         *  rather than takes over. A glob among them is anchored to its own file on the way in - see
+         *  `anchorContributions`. */
+        if (ALWAYS_APPEND.includes(key)) {
+            appendList(target, key, GLOB_KEYS.includes(key) ? anchorContributions(value, origin) : value);
+            continue;
+        }
+        assignMerged(target, key, value, source, origin);
+    }
+    return target;
+}
+function assignMerged(target, key, value, source, origin) {
+    /** A source that already carries origins wins over the caller's: an `extends` base keeps the file
+     *  its own keys were written in, rather than being attributed to the file that named it. */
+    const from = source[ORIGINS]?.[key] ?? origin;
+    if (from !== undefined) {
+        const carrier = target;
+        /** **Non-enumerable**, like `PREVIOUS_VALUES`: `expect`'s `toEqual` compares symbol properties,
+         *  so a plain assignment turned every config-shape assertion in the suite into a diff about
+         *  bookkeeping (measured, five specs at once). Nothing should see this but the error messages. */
+        if (!carrier[ORIGINS])
+            Object.defineProperty(target, ORIGINS, { value: {}, writable: true });
+        carrier[ORIGINS][key] = from;
+    }
+    if (isPlainObject(value)) {
+        if (!isPlainObject(target[key]))
+            target[key] = {};
+        mergeConfig(target[key], value, from);
+        return;
+    }
+    /**
+     * A value that can ask for `value` **replaces** like any other - and remembers what it replaced:
+     *
+     * ```js
+     * '[*]':    { clean: { include: ({ vars }) => [vars.buildDir] } }
+     * '[*]': { clean: { include: "${{ [...value, pkg.basename + '.log'] }}" } }
+     * ```
+     *
+     * Chained here rather than at resolution time because only the merge knows the order of the
+     * layers - by the time `interpolateConfig` sees the config they have collapsed into one object,
+     * and whatever a closer layer said has already taken the place of what it was derived from.
+     */
+    /**
+     * **A chain already on `source` is carried over**, the way its `ORIGINS` are just above - and for
+     * the same reason: `source` may itself be several layers already merged, and only the merge knows
+     * their order.
+     *
+     * Without this, a chain recorded *inside* a source was silently dropped whenever the key was
+     * absent from the target, because the link below was only ever recorded for a key being
+     * *replaced*. The shape that hit it is the ordinary one for a shared config: a base and its
+     * consumer both writing `"[*]"`. Those two blocks merge into one before `matchingSelectors` sees
+     * them - recording the chain on the merged block - and that block is then merged into a `result`
+     * which has no such key, so the chain went nowhere.
+     *
+     * Measured, on a base declaring `clean.include: ['build']` and a consumer's `"[*]"` deriving from
+     * it: `${{ [...value, 'dist'] }}` answered `['dist']`, losing `build` outright. It answers
+     * `['build', 'dist']` now. Two *different* selectors (`"[*]"` then `"[pkg-a]"`) always worked,
+     * and so did an unmarked key, which is why this went unnoticed - those merge into a target that
+     * already holds the key.
+     */
+    const sourceChain = source[PREVIOUS_VALUES]?.[key];
+    if (carriesPreviousValue(value) && (key in target || sourceChain)) {
+        const carrier = target;
+        const chain = (carrier[PREVIOUS_VALUES] ??= {});
+        /** The layer the target itself stands for, bottom-most of the three: what it holds now, over
+         *  whatever *that* was derived from. Absent when the target never had the key. */
+        const below = key in target ? { value: target[key], previous: chain[key] } : chain[key];
+        /** Bottom-up: the target's layer, then `source`'s own intermediate ones, then `value` on top -
+         *  so `source`'s chain keeps its internal order and gets the target's spliced beneath it. */
+        chain[key] = sourceChain ? graftChain(sourceChain, below) : below;
+    }
+    target[key] = Array.isArray(value) ? [...value] : value;
+}
+/** `node`'s chain, copied with `tail` spliced in beneath its deepest link - so two layer-stacks
+ *  join into one without either being mutated (a chain is shared by every package that resolved
+ *  through it, so grafting in place would rewrite what the others see). */
+function graftChain(node, tail) {
+    return { value: node.value, previous: node.previous ? graftChain(node.previous, tail) : tail };
+}
+/**
+ * Appends `value` to `target[key]`, de-duplicating **only** an `ALWAYS_APPEND` key.
+ *
+ * That asymmetry is the point. `plugins` appends without being asked, so a repository and the config
+ * it extends both naming `'node'` is the ordinary case rather than a mistake, and the list is
+ * also what `rman config` prints. An explicit `+before`, by contrast, was *written* - repeating a
+ * step that is already there is a strange thing to ask for, but it is what was asked for, and
+ * silently collapsing it would make one layer's list depend on another's contents.
+ *
+ * By identity (`===`), which covers a string by value and a plugin object by reference; two
+ * *different* objects claiming one plugin name are caught where it counts, at registration - see
+ * `loadPlugins`.
+ */
+function appendList(target, key, value) {
+    const merged = [...toList(target[key] ?? []), ...toList(value)];
+    target[key] = ALWAYS_APPEND.includes(key) ? merged.filter((entry, at) => merged.indexOf(entry) === at) : merged;
+}
+function toList(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Anchors every glob in `plugins`/`commands`/`publishTargets` to the directory of the file that
+ * declared it, on the way in. A non-string entry - an instance written straight into the config -
+ * passes through untouched.
+ *
+ * **Done here, at the merge, because this is the last moment the answer is known.** `commands`
+ * always appends, so one resolved list ends up holding entries from the repository's own
+ * `.rmanrc`, from each `extends` base, and from every directory above - and `ORIGINS` records one
+ * file per *key*, not per element, so after the merge there is nothing left to attribute them by.
+ * Rewriting each glob as it arrives makes the merge trivially correct and costs one `path.resolve`.
+ *
+ * It is what lets a **shared config ship its own contributions**: `commands: './commands/*.js'`
+ * in a published package means that package's directory, wherever the repository inheriting it
+ * happens to sit. All three keys behave the same way; `plugins` used to resolve every entry
+ * against the repository root instead, whatever file declared it, and that asymmetry is gone.
+ *
+ * `origin` is absent when a caller merges a value it built rather than read (a selector block, the
+ * directory chain layering already-resolved configs); those globs have been anchored already, and
+ * an absolute path is left alone by `path.resolve` anyway.
+ */
+function anchorContributions(value, origin) {
+    if (!origin)
+        return value;
+    const dir = path.dirname(origin);
+    const anchor = (entry) => typeof entry === 'string' && !looksLikePackageName(entry) ? path.resolve(dir, entry) : entry;
+    return Array.isArray(value) ? value.map(anchor) : anchor(value);
+}
+/**
+ * Whether an entry is shaped like a **package name** rather than a glob - `rman-node`,
+ * `@panates/rman-node`, but not `*.js`, `./x.js` or `commands/*.mjs`.
+ *
+ * Such an entry is left unanchored, because it is not a relative path and turning it into one
+ * destroys the only evidence of what the author meant. A package name is never valid in these keys
+ * (a package's config arrives through `extends`), so the whole value of keeping it intact is the
+ * error message: anchored, `plugins: ['rman-node']` failed with `glob ".../rman-node" matched no
+ * file`, which sends the reader to check their paths. `loadPlugins` can now say what they actually
+ * wrote and what to write instead - which two doc pages already promised it did.
+ *
+ * Shape, not a resolver call: decidable without touching the disk, and a wrong guess only chooses
+ * which of two error messages a failing entry gets. An extension is excluded so a bare `plugin.js`
+ * beside the config is still anchored as the relative path it is.
+ */
+function looksLikePackageName(entry) {
+    return /^(?:@[a-z0-9-~][\w.-]*\/)?[a-z0-9-~][\w.-]*$/i.test(entry) && !/\.[cm]?js$/i.test(entry);
+}

package/core/{resolve-target.d.ts → config/resolve-config-target.d.ts}

@@ -15,7 +15,7 @@ export declare function resolveConfigTarget(target: string, from: string, label:
  * repository cannot resolve it.
  *
  * A globally installed rman's siblings *are* the globally installed packages, so this is what makes
- * `rman ci` work on a fresh clone - the command comes from `rman-node`, and `ci` exists to create
+ * `rman ci` work on a fresh clone - the command came from `rman-node` then, and `ci` exists to create
  * the very `node_modules` the plugin would otherwise have to be found in. Measured: with both
  * installed globally, a clone answered `"plugins" target "rman-node" could not be resolved ... is
  * it installed in this repository?`, which was true and useless.

package/core/{resolve-target.js → config/resolve-config-target.js}

@@ -39,7 +39,7 @@ export function resolveConfigTarget(target, from, label) {
  * repository cannot resolve it.
  *
  * A globally installed rman's siblings *are* the globally installed packages, so this is what makes
- * `rman ci` work on a fresh clone - the command comes from `rman-node`, and `ci` exists to create
+ * `rman ci` work on a fresh clone - the command came from `rman-node` then, and `ci` exists to create
  * the very `node_modules` the plugin would otherwise have to be found in. Measured: with both
  * installed globally, a clone answered `"plugins" target "rman-node" could not be resolved ... is
  * it installed in this repository?`, which was true and useless.

package/core/{custom-command.d.ts → interfaces/custom-command.d.ts}

@@ -1,8 +1,9 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
-import type { Logger } from '../utils/logger.js';
-import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
-import type { Package } from './package.js';
-import type { Repository } from './repository.js';
+import type { RmanConfig as CommandDeclaration } from '../../interfaces/rman-config.interface.js';
+import type { Logger } from '../../utils/logger.js';
+import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
+import type { Package } from '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export declare const CUSTOM_COMMAND_DIR = ".rman";
 /**
@@ -100,10 +101,25 @@ declare module 'yargs' {
  * that come with it; reimplementing that loop here would only lose them.
  */
 export declare function defineCommand(command: CustomCommand): CustomCommand;
-export interface LoadedCommand extends CustomCommand {
+/**
+ * One command module that loaded, in whichever form it exported.
+ *
+ * Both forms are accepted, and the same pair is accepted for a command written straight into
+ * `.rmanrc "commands"` - one key, one set of rules. The declarative factory is what rman asks a
+ * command author to write; a repository's own command should not be stuck on the older object
+ * shape just because it lives in a file rather than in a config.
+ */
+export interface LoadedCommand {
     /** The command's name - its file's basename, or the first word of an explicit `command`. */
     name: string;
     file: string;
+    /** The declarative form (`app => ({ ... })`). `cli.ts` runs it where a plugin's and a built-in's
+     *  own factories run, because it wants `app.repository` and loading happens before one exists. */
+    register?: CommandDeclaration.CommandRegisterFunction;
+    /** The `defineCommand({ ... })` object form, already checked and named. */
+    custom?: CustomCommand & {
+        command: string;
+    };
 }
 /** A module that couldn't be loaded or doesn't look like a command. Reported, never thrown: one
  *  unparseable file must not take `rman publish` down with it. */
@@ -112,15 +128,32 @@ export interface CommandLoadError {
     reason: string;
 }
 /**
- * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
- * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
- * included.
+ * The globs a repository's own commands are loaded from when it names none: `.rman/*.{js,mjs,cjs}`
+ * under the repository root.
+ *
+ * **`.rman/` is this default, not a second mechanism.** It used to be a hardcoded directory scan
+ * beside which `commands` would have been a third source of repository-level commands - and a
+ * third precedence question. Making it the default value instead leaves one source, one slot, and
+ * a zero-config path that behaves exactly as it did.
+ */
+export declare function defaultCommandGlobs(rootDir: string): string[];
+/**
+ * Loads every command module matching `patterns` - absolute globs, already anchored to whichever
+ * config file declared them (see `anchorContributions`).
+ *
+ * A repository matching nothing pays for one glob and no imports, which matters because this runs
+ * on *every* rman invocation, `info` included.
+ *
+ * **Deduplicated by resolved path**, because `commands` appends at every level and cascades: the
+ * root's glob reaches each package's resolved config too, so the same file is named more than once
+ * as a matter of course rather than as a mistake. Loading it twice would register the command
+ * twice, which yargs does not survive.
  *
  * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
  * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
  * `assertNoBuiltinShadowing`.
  */
-export declare function loadCustomCommands(rootDir: string): Promise<{
+export declare function loadCustomCommands(patterns: string[]): Promise<{
     commands: LoadedCommand[];
     errors: CommandLoadError[];
 }>;
@@ -130,4 +163,7 @@ export declare function loadCustomCommands(rootDir: string): Promise<{
  * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
  * it unable to tell which ran.
  */
-export declare function assertNoBuiltinShadowing(commands: LoadedCommand[], builtins: readonly string[]): void;
+export declare function assertNoBuiltinShadowing(commands: readonly {
+    name: string;
+    file: string;
+}[], builtins: readonly string[]): void;

package/core/{custom-command.js → interfaces/custom-command.js}

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import fastGlob from 'fast-glob';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export const CUSTOM_COMMAND_DIR = '.rman';
 /** Loadable module forms, matching what a `.rmanrc.cjs`/`.mjs`/`.js` config already accepts. A
@@ -41,30 +41,58 @@ export function defineCommand(command) {
     return command;
 }
 /**
- * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
- * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
- * included.
+ * The globs a repository's own commands are loaded from when it names none: `.rman/*.{js,mjs,cjs}`
+ * under the repository root.
+ *
+ * **`.rman/` is this default, not a second mechanism.** It used to be a hardcoded directory scan
+ * beside which `commands` would have been a third source of repository-level commands - and a
+ * third precedence question. Making it the default value instead leaves one source, one slot, and
+ * a zero-config path that behaves exactly as it did.
+ */
+export function defaultCommandGlobs(rootDir) {
+    return [path.join(rootDir, CUSTOM_COMMAND_DIR, `*{${EXTENSIONS.join(',')}}`)];
+}
+/**
+ * Loads every command module matching `patterns` - absolute globs, already anchored to whichever
+ * config file declared them (see `anchorContributions`).
+ *
+ * A repository matching nothing pays for one glob and no imports, which matters because this runs
+ * on *every* rman invocation, `info` included.
+ *
+ * **Deduplicated by resolved path**, because `commands` appends at every level and cascades: the
+ * root's glob reaches each package's resolved config too, so the same file is named more than once
+ * as a matter of course rather than as a mistake. Loading it twice would register the command
+ * twice, which yargs does not survive.
  *
  * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
  * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
  * `assertNoBuiltinShadowing`.
  */
-export async function loadCustomCommands(rootDir) {
-    const dir = path.join(rootDir, CUSTOM_COMMAND_DIR);
+export async function loadCustomCommands(patterns) {
     const commands = [];
     const errors = [];
-    if (!fs.existsSync(dir))
+    if (!patterns.length)
         return { commands, errors };
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !EXTENSIONS.includes(path.extname(entry.name)))
-            continue;
-        const file = path.join(dir, entry.name);
+    /** Sorted so the order a command is registered in does not depend on the filesystem, and
+     *  `absolute` because a pattern may name a directory outside the repository entirely - which is
+     *  exactly what a shared config shipping its own commands does. */
+    const files = await fastGlob(patterns.map(p => p.split(path.sep).join('/')), { absolute: true, onlyFiles: true });
+    for (const file of [...new Set(files.map(f => path.resolve(f)))].sort()) {
         try {
             const mod = await import(pathToFileURL(file).href);
-            const command = mod?.default ?? mod?.command;
-            if (!command || typeof command !== 'object') {
-                throw new Error('no default export - end the module with `export default defineCommand({ ... })`');
+            const exported = mod?.default ?? mod?.command;
+            const basename = path.basename(file, path.extname(file));
+            /** The declarative form. Nothing to check here beyond its shape - the factory has not run,
+             *  so there is no metadata to validate yet; `cli.ts` checks what it returns. */
+            if (typeof exported === 'function') {
+                commands.push({ name: basename, file, register: exported });
+                continue;
+            }
+            if (!exported || typeof exported !== 'object') {
+                throw new Error('no command exported - end the module with `export default defineCommand({ ... })`, or with ' +
+                    'the declarative `export default app => ({ ... })`');
             }
+            const command = exported;
             if (typeof command.handler !== 'function')
                 throw new Error('"handler" is missing, or is not a function');
             if (typeof command.describe !== 'string' || !command.describe) {
@@ -72,10 +100,9 @@ export async function loadCustomCommands(rootDir) {
             }
             const declared = command.command?.trim();
             commands.push({
-                ...command,
-                command: declared || path.basename(entry.name, path.extname(entry.name)),
-                name: (declared || path.basename(entry.name, path.extname(entry.name))).split(/\s+/)[0],
+                name: (declared || basename).split(/\s+/)[0],
                 file,
+                custom: { ...command, command: declared || basename },
             });
         }
         catch (e) {