rman 1.0.12 → 1.1.1

package/core/config.js

@@ -2,10 +2,11 @@ import fs from 'fs';
 import * as yaml from 'js-yaml';
 import { createRequire } from 'module';
 import path from 'path';
-import merge from 'putil-merge';
 import semver from 'semver';
 import { pathToFileURL } from 'url';
 import vm from 'vm';
+import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
+import { finalizeConfig, mergeConfig } from './merge-config.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
@@ -58,33 +59,56 @@ async function loadJsConfig(file) {
  */
 export async function readDirConfig(dirname) {
     const result = {};
+    /** The file an `extends` in this directory resolves relative to. The last form that actually
+     *  declared one wins, which matters only for the unusual directory holding several. */
+    let extendsFrom = path.join(dirname, '.rmanrc');
     const pkgJsonFile = path.join(dirname, 'package.json');
     if (fs.existsSync(pkgJsonFile)) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonFile, 'utf-8'));
-        if (pkgJson && typeof pkgJson.rman === 'object')
-            merge(result, pkgJson.rman, { deep: true });
+        if (pkgJson && typeof pkgJson.rman === 'object') {
+            assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
+            if (EXTENDS_KEY in pkgJson.rman)
+                extendsFrom = pkgJsonFile;
+            mergeConfig(result, pkgJson.rman);
+        }
     }
     const ymlFile = path.join(dirname, '.rmanrc.yml');
     if (fs.existsSync(ymlFile)) {
         const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
-        if (obj && typeof obj === 'object')
-            merge(result, obj, { deep: true });
+        if (obj && typeof obj === 'object') {
+            assertNoSelectorExtends(obj, ymlFile);
+            if (EXTENDS_KEY in obj)
+                extendsFrom = ymlFile;
+            mergeConfig(result, obj);
+        }
     }
     const rcFile = path.join(dirname, '.rmanrc');
     if (fs.existsSync(rcFile)) {
         const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
-        if (obj && typeof obj === 'object')
-            merge(result, obj, { deep: true });
+        if (obj && typeof obj === 'object') {
+            assertNoSelectorExtends(obj, rcFile);
+            if (EXTENDS_KEY in obj)
+                extendsFrom = rcFile;
+            mergeConfig(result, obj);
+        }
     }
     for (const jsFileName of JS_CONFIG_FILES) {
         const jsFile = path.join(dirname, jsFileName);
         if (fs.existsSync(jsFile)) {
             const obj = await loadJsConfig(jsFile);
-            if (obj && typeof obj === 'object')
-                merge(result, obj, { deep: true });
+            if (obj && typeof obj === 'object') {
+                assertNoSelectorExtends(obj, jsFile);
+                if (EXTENDS_KEY in obj)
+                    extendsFrom = jsFile;
+                mergeConfig(result, obj);
+            }
         }
     }
-    return result;
+    /** Resolved per directory, once its own forms have been combined: `extends` is the base every
+     *  one of them sits on, and the directory chain then layers on top as it always did. Each form
+     *  was checked for a misplaced `extends` as it was read, so that error can name the file holding
+     *  it rather than whichever form happened to declare the real one. */
+    return resolveExtends(result, extendsFrom);
 }
 /**
  * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
@@ -97,9 +121,10 @@ export async function readDirConfig(dirname) {
  *   `.rmanrc` therefore configures the *root package* - which is where repo-wide settings
  *   (`packageManager`, `allowBranch`, `version.*`, `githubRelease.*`) are read from anyway - and
  *   not, silently, every package under it.
- * - **A `"[selector]"` block configures the packages it names** (`"[*]"` for all of them,
- *   `"[*-dialect]"` for a glob over package names). This is the only way a directory speaks about
- *   anything but its own package.
+ * - **A `"[selector]"` block configures the packages it names** - `"[*]"` for all of them (the root
+ *   included), `"[ws:*]"` for every one but the root, `"[/]"` for the root alone, `"[*-dialect]"`
+ *   for a glob over package names. See `parseSelector`. This is the only way a directory speaks
+ *   about anything but its own package.
  *
  * Splitting the two matters because the same key means different things to the two audiences. The
  * clearest case is `run.<script>.postScript`: on a package it's that package's build hook, run in
@@ -107,64 +132,137 @@ export async function readDirConfig(dirname) {
  * cascade that fed one declaration to both ran a package-relative command (`node
  * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
  *
- * `packageName` is what selectors match against; without it (resolving the root's own config, say)
- * selector blocks contribute nothing at all.
+ * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
+ * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
  */
 export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
     const result = {};
     const target = path.resolve(targetDir);
+    /** The root *package* is the one whose directory is the repository root - no other test is
+     *  needed, and none would be as reliable: a name can be anything. In a single-package repository
+     *  that is the only package, so `"[/]"` reaches it and `"[ws:*]"` reaches nothing. */
+    const isRoot = target === path.resolve(rootDir);
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
         if (!local) {
             local = await readDirConfig(dir);
             cache.set(dir, local);
         }
-        // Selectors first, so a directory's own unmarked config still wins over a selector declared
-        // alongside it - "this package" is a more specific statement than "packages matching a glob".
-        if (packageName) {
-            for (const block of matchingSelectors(local, packageName))
-                merge(result, block, { deep: true });
-        }
         // A directory holding a package speaks for that package only - which is what keeps the root's
         // own config off every package under it. A directory that holds none (an intermediate
         // `packages/`, say) has no package to speak for, so its unmarked config can only mean
         // "everything below" and still cascades.
         const ownsAPackage = fs.existsSync(path.join(dir, 'package.json'));
-        if (!ownsAPackage || path.resolve(dir) === target)
-            merge(result, stripSelectors(local), { deep: true });
+        const speaksForTarget = !ownsAPackage || path.resolve(dir) === target;
+        /**
+         * `vars` is the **one** unmarked key that cascades past the package its directory speaks for,
+         * and it is not a hole in that rule - it is a key the rule was never about. The rule exists
+         * because a setting means different things to the two audiences (`run.build.after` on the root
+         * is a repo-wide bookend, on a package its own hook), so one declaration cannot serve both.
+         * `vars: {x: 1}` means the number 1 to everyone; there is no second audience to be wrong for.
+         *
+         * Merged *before* this directory's selector blocks, so `"[*]": {vars: ...}` - which names the
+         * packages explicitly - overrides the same directory's plainer statement.
+         */
+        if (!speaksForTarget && local.vars !== undefined)
+            mergeConfig(result, { vars: local.vars });
+        // Selectors next, so a directory's own unmarked config still wins over a selector declared
+        // alongside it - "this package" is a more specific statement than "packages matching a glob".
+        if (packageName) {
+            for (const block of matchingSelectors(local, packageName, isRoot))
+                mergeConfig(result, block);
+        }
+        if (speaksForTarget)
+            mergeConfig(result, stripSelectors(local));
     }
-    return result;
+    /** Every layer has had its turn, so an append still outstanding has nothing left to attach to
+     *  and becomes the value itself. Done here rather than per layer: until the chain is finished,
+     *  the key it appends to may still be coming. */
+    return finalizeConfig(result);
 }
-/** A config key naming packages rather than settings: `"[*]"`, `"[*-dialect]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
 export function isSelectorKey(key) {
     return key.length > 2 && key.startsWith('[') && key.endsWith(']');
 }
+/**
+ * **Which packages a selector speaks for.** Three audiences, because a repository has three:
+ *
+ * | | |
+ * | --- | --- |
+ * | `"[/]"` | the **root package** only |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
+ * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package the glob matches |
+ *
+ * `/` for the root because that is what a repository root is called everywhere else, and it cannot
+ * collide with a package name. `ws:` is a qualifier on the glob rather than a separate spelling of
+ * `*`, so `"[ws:pkg-*]"` means what it looks like.
+ *
+ * **`"[*]"` includes the root, and that is a change from how it used to read.** Before, selectors
+ * were not applied to the root at all, so `"[*]"` silently meant "the workspace packages" - a
+ * catch-all with an exception nothing in the syntax mentioned. The three names above say which
+ * audience is meant; `"[ws:*]"` is the old behaviour, now spelled.
+ */
+export function parseSelector(key) {
+    const inner = key.slice(1, -1);
+    if (inner === ROOT_SELECTOR_INNER)
+        return { scope: 'root', test: () => true };
+    for (const prefix of WORKSPACE_PREFIXES) {
+        if (inner.startsWith(prefix)) {
+            const re = globToRegExp(inner.slice(prefix.length));
+            return { scope: 'workspace', test: name => re.test(name) };
+        }
+    }
+    const re = globToRegExp(inner);
+    return { scope: 'all', test: name => re.test(name) };
+}
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
  *  `mysql-dialect` but not `my-dialect-helper`. Glob rather than regex, to match every other
  *  pattern in rman (`allowBranch`, `changelog.tagPattern`, `clean.include`). */
 export function selectorToRegExp(key) {
-    const glob = key.slice(1, -1);
-    const source = glob
-        .split('*')
-        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
-        .join('.*');
-    return new RegExp(`^${source}$`);
+    return globToRegExp(key.slice(1, -1));
 }
-/** Every selector block in `config` matching `packageName`, in increasing precedence: `"[*]"` first
- *  and the rest in declaration order - so a specific glob overrides the catch-all, and two equally
- *  specific ones resolve by the order they were written in. */
-function matchingSelectors(config, packageName) {
+/**
+ * Every selector block in `config` that speaks for this package, in increasing precedence.
+ *
+ * Order, lowest first: **`"[*]"`, then a catch-all `"[ws:*]"`, then the rest in declaration
+ * order** - so narrowing the audience wins over the widest one, a named package or `"[/]"` wins
+ * over both, and two equally specific globs resolve by the order they were written in. A catch-all
+ * is ranked rather than left to declaration order on purpose: where you happen to write "everything"
+ * should not decide whether it beats a rule about one package.
+ */
+function matchingSelectors(config, packageName, isRoot) {
     const matches = [];
     for (const [key, value] of Object.entries(config)) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
-        if (selectorToRegExp(key).test(packageName))
-            matches.push([key, value]);
+        const { scope, test } = parseSelector(key);
+        if (scope === 'root' && !isRoot)
+            continue;
+        if (scope === 'workspace' && isRoot)
+            continue;
+        if (!test(packageName))
+            continue;
+        matches.push([selectorRank(key), value]);
     }
-    return matches.sort((a, b) => Number(b[0] === CATCH_ALL) - Number(a[0] === CATCH_ALL)).map(([, block]) => block);
+    return matches.sort((a, b) => a[0] - b[0]).map(([, block]) => block);
+}
+/** 0 for `"[*]"`, 1 for a catch-all workspace selector, 2 for anything that names something. Equal
+ *  ranks keep their declaration order, since `Array.prototype.sort` is stable. */
+function selectorRank(key) {
+    if (key === CATCH_ALL)
+        return 0;
+    const inner = key.slice(1, -1);
+    return WORKSPACE_PREFIXES.some(prefix => inner === `${prefix}*`) ? 1 : 2;
+}
+function globToRegExp(glob) {
+    const source = glob
+        .split('*')
+        .map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*');
+    return new RegExp(`^${source}$`);
 }
 function stripSelectors(config) {
     const result = {};
@@ -174,6 +272,12 @@ function stripSelectors(config) {
     return result;
 }
 const CATCH_ALL = '[*]';
+/** `"[/]"` - the root package, spelled the way a repository root is spelled everywhere else, and
+ *  unable to collide with a package name. */
+const ROOT_SELECTOR_INNER = '/';
+/** Both spellings of "the workspace packages, not the root". The long one reads in a config file
+ *  someone else has to understand; the short one is what gets typed. */
+const WORKSPACE_PREFIXES = ['workspace:', 'ws:'];
 function dirChain(rootDir, targetDir) {
     const rel = path.relative(rootDir, targetDir);
     if (!rel || rel === '.' || rel.startsWith('..'))
@@ -195,8 +299,13 @@ function dirChain(rootDir, targetDir) {
  *   clean:
  *     include: ["build", "../../coverage/${{ pkg.basename }}"]
  *   publish:
+ *     directory: build
  *     docker:
  *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
+ *   run:
+ *     build:
+ *       # the config's own keys are in scope, so this is not a second copy of "build"
+ *       after: "cp README.md ${{ publish.directory }}/"
  * ```
  *
  * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
@@ -223,20 +332,134 @@ function dirChain(rootDir, targetDir) {
  * A failing expression throws with the config path that holds it, rather than being left in place:
  * silently passing through a mistake is how a config ends up quietly doing nothing.
  */
-export function interpolateConfig(config, scope) {
+export function interpolateConfig(config, scope, options) {
+    const skip = options?.skip ?? [];
     const context = vm.createContext({ ...scope });
-    return walk(config, scope, context, []);
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return walk(config, scope, context, [], skip);
+    /**
+     * The config's own top-level keys, readable bare: `${{ publish.directory }}`. So a value that
+     * restates another - `after: "cp README.md ${{ publish.directory }}/"` - stops being a second
+     * copy that drifts when the first one changes.
+     *
+     * Resolved **on demand**, one key at a time, and memoized. Interpolating the config in tree order
+     * and handing an expression whatever was ready would make the answer depend on key order in the
+     * file, which is exactly the kind of quiet wrongness this evaluator exists to prevent: a key
+     * declared above would read as resolved and one below as raw. On demand, each key is resolved
+     * when first read and the order in the file means nothing.
+     */
+    const resolved = new Map();
+    const resolving = [];
+    /**
+     * A cycle is **recorded here rather than thrown from the getter**, and that is not a style
+     * choice: a host getter that throws inside a `vm` property interceptor has its exception
+     * swallowed, and V8 then reports the global as absent - so a self-referencing key came out as
+     * `publish is not defined`, which sends the reader looking for a missing key instead of a loop
+     * (measured). The getter returns `undefined`, the resulting `ReferenceError` is caught below, and
+     * this replaces it.
+     */
+    let cycle;
+    const resolve = (key) => {
+        if (resolved.has(key))
+            return resolved.get(key);
+        if (resolving.includes(key)) {
+            cycle ??= new Error(`Config expression forms a cycle: ${[...resolving, key].join(' -> ')}\n` +
+                `  A value cannot be derived from itself, directly or through another key.`);
+            return undefined;
+        }
+        resolving.push(key);
+        try {
+            const value = walk(config[key], scope, context, [key], skip);
+            resolved.set(key, value);
+            return value;
+        }
+        catch (e) {
+            /** Not cleared: a cycle aborts the whole interpolation, and each level up would otherwise
+             *  re-swallow its own replacement the same way - leaving it set lets the outermost frame,
+             *  the one with a real stack to throw from, report it. */
+            if (cycle)
+                throw new Error(`${String(e?.message).split('\n')[0]}\n  ${cycle.message}`, { cause: e });
+            throw e;
+        }
+        finally {
+            resolving.pop();
+        }
+    };
+    for (const key of Object.keys(config)) {
+        /** A scope binding wins: `pkg`/`repository`/`env`/`semver` are not config keys, so nothing
+         *  collides today, and a future key that did must not silently take over the namespace. */
+        if (key in scope || !IDENTIFIER.test(key))
+            continue;
+        Object.defineProperty(context, key, { enumerable: true, configurable: true, get: () => resolve(key) });
+    }
+    /** Built through the same memo the getters use, so every key is walked exactly once whether an
+     *  expression asked for it first or the result did. */
+    const result = {};
+    for (const key of Object.keys(config))
+        result[key] = resolve(key);
+    return result;
 }
+/**
+ * Config paths left untouched when a repository's config is first resolved, and evaluated only by
+ * the command that runs them.
+ *
+ * `version`'s own hooks are the one place `${{ pkg.targetVersion }}` makes sense, and the version
+ * being written is not known until `version` has computed its plan - long after the config was
+ * resolved. Evaluating these eagerly would throw while merely *loading* the repository, so any
+ * command at all would fail on a config that mentions it.
+ */
+export const DEFERRED_PATHS = ['version.before', 'version.exec', 'version.after'];
 const EXPRESSION = /\$\{\{([\s\S]*?)\}\}/g;
-function walk(value, scope, context, at) {
+/** A config key an expression could actually name. Anything else - a `"[selector]"` block, a
+ *  `"lint:fix"` - is unreachable as a bare identifier anyway, so it is not bound. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** The `file` namespace for one package's directory - see `FileScope`. */
+export function createFileScope(dirname) {
+    const locate = (target) => {
+        if (typeof target !== 'string' || !target.trim()) {
+            throw new Error('file.exists()/file.resolve() need a path - they were given ' + JSON.stringify(target));
+        }
+        const resolved = path.resolve(dirname, target);
+        return { path: resolved, found: fs.existsSync(resolved) };
+    };
+    return {
+        exists(target) {
+            const { path: resolved, found } = locate(target);
+            return found ? resolved : '';
+        },
+        resolve(target) {
+            const { path: resolved, found } = locate(target);
+            if (!found) {
+                throw new Error(`file.resolve("${target}") found nothing at ${resolved}\n` +
+                    `  Use file.exists() instead if its absence is a case to handle rather than a mistake.`);
+            }
+            return resolved;
+        },
+        resolveFirst(...targets) {
+            if (!targets.length)
+                throw new Error('file.resolveFirst() needs at least one path');
+            for (const target of targets) {
+                const { path: resolved, found } = locate(target);
+                if (found)
+                    return resolved;
+            }
+            throw new Error(`file.resolveFirst() found none of: ${targets.map(t => `"${t}"`).join(', ')}\n` + `  Looked in ${dirname}.`);
+        },
+    };
+}
+function walk(value, scope, context, at, skip) {
+    /** Compared on the key path rather than the value, so a deferred key's whole subtree - a single
+     *  command or an array of them - is handed on untouched. */
+    if (at.length && skip.includes(at.filter(p => typeof p === 'string').join('.')))
+        return value;
     if (typeof value === 'string')
         return interpolateString(value, context, at);
     if (Array.isArray(value))
-        return value.map((item, i) => walk(item, scope, context, [...at, i]));
+        return value.map((item, i) => walk(item, scope, context, [...at, i], skip));
     if (value && typeof value === 'object') {
         const result = {};
         for (const [key, item] of Object.entries(value))
-            result[key] = walk(item, scope, context, [...at, key]);
+            result[key] = walk(item, scope, context, [...at, key], skip);
         return result;
     }
     return value;

package/core/custom-command.d.ts

@@ -0,0 +1,133 @@
+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';
+/** Where a repository keeps its own commands - one module per command, named after it. */
+export declare const CUSTOM_COMMAND_DIR = ".rman";
+/**
+ * What a repository's own command is handed. An object rather than loose parameters so later
+ * additions don't break every command already written against it.
+ */
+export interface CommandContext {
+    repository: Repository;
+    /**
+     * The package whose directory rman was invoked from, or `undefined` at the repository root (and
+     * in a single-package repository, which is always "at the root") - the same
+     * `Repository.currentPackage` the built-in commands scope themselves by. A command that only
+     * makes sense inside a package should say so itself rather than assume.
+     */
+    package: Package | undefined;
+    /**
+     * Runs one of the repository's locally installed binaries - `runBin` (see
+     * `../utils/run-bin.ts`), already carrying **this run's** settings: `cwd` defaults to the
+     * repository root, and `logLevel` to the level resolved from `--log-level` and `.rmanrc
+     * logLevel`. Either can still be overridden per call.
+     *
+     * Handed over here rather than left to be imported, because those settings are the whole point:
+     * importing `runBin` straight from `'rman'` gets a helper that knows neither, so
+     * `--log-level silent` would quietly not apply to the one part of the command that produces
+     * output. Anything else a run turns out to carry is added here the same way, and no command
+     * written against this breaks.
+     */
+    runBin: (bin: string, argv: string[], options?: RunBinOptions) => Promise<RunBinResult>;
+    /** Logger at this run's resolved level, for a command's own narration. */
+    logger: Logger;
+}
+/**
+ * Which `.rmanrc` keys a command reads, for `--config` to print instead of running it - a dotted
+ * path each (`'run.build'`, `'publish.docker'`), or a function of the parsed argv when the answer
+ * depends on it (`run <script>` reads `run.<script>`).
+ *
+ * **Declared beside the command rather than in a list somewhere central**, so it cannot drift out
+ * of step with the code that does the reading, and so a plugin's command or a `.rman/*.mjs` one can
+ * say it too. Omitted, `--config` prints the whole effective config - the honest answer when
+ * nothing has said which part matters.
+ */
+export type ConfigKeys = string[] | ((args: ArgumentsCamelCase) => string[]);
+export interface CustomCommand {
+    /** yargs command string, for a command taking positionals (`'deploy <stage>'`). Defaults to the
+     *  module's own file name, which is the whole point of the directory. */
+    command?: string;
+    /** Required: without it `rman --help` has nothing to list the command by. */
+    describe: string;
+    builder?: (argv: Argv) => Argv;
+    handler: (context: CommandContext, args: ArgumentsCamelCase) => void | Promise<void>;
+    /** See `ConfigKeys` - what `rman <this command> --config` narrows its output to. */
+    configKeys?: ConfigKeys;
+}
+/**
+ * The same field on **yargs's own** command object, which is what the built-in commands pass.
+ *
+ * By augmentation rather than a wrapper type of ours: `program.command({ ... })` takes a literal,
+ * and TypeScript's excess-property check fires on a literal however the parameter is typed - so a
+ * field yargs does not know about is a compile error even though it is ignored at runtime
+ * (measured, on nine commands at once). One block, here, beside `ConfigKeys` itself.
+ */
+declare module 'yargs' {
+    interface CommandModule<T = {}, U = {}> {
+        configKeys?: ConfigKeys;
+    }
+}
+/**
+ * Identity helper for authoring a `.rman/<name>.mjs` command with full type-checking and
+ * autocomplete - the same `defineConfig` pattern, for the same reason. Returns `command`
+ * unchanged.
+ *
+ * ```js
+ * // .rman/deploy.mjs
+ * import { defineCommand, VersionService } 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, runBin, logger }, args) {
+ *     const plan = await VersionService.getPlan(repository);
+ *     for (const entry of plan.filter(e => e.status === 'bump')) {
+ *       logger.info(`${entry.package.name} -> ${args.stage}`);
+ *     }
+ *     await runBin('helm', ['upgrade', '--install', args.stage, './chart']);
+ *   },
+ * });
+ * ```
+ *
+ * Take `runBin` from the context rather than importing it: the one on the context already carries
+ * this run's `cwd` (the repository root) and log level.
+ *
+ * This is for **one repository-level operation with logic of its own** - branching, its own CLI
+ * options, rman's services. Running a shell step across every package is what `.rmanrc
+ * "run.<script>"` already does, with the scheduling, topological order, `bail` and progress panel
+ * that come with it; reimplementing that loop here would only lose them.
+ */
+export declare function defineCommand(command: CustomCommand): CustomCommand;
+export interface LoadedCommand extends CustomCommand {
+    /** The command's name - its file's basename, or the first word of an explicit `command`. */
+    name: string;
+    file: 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. */
+export interface CommandLoadError {
+    file: string;
+    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.
+ *
+ * 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<{
+    commands: LoadedCommand[];
+    errors: CommandLoadError[];
+}>;
+/**
+ * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
+ * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * `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;

package/core/custom-command.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** 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
+ *  `.ts` command would need a loader registered in rman's own process, which is a separate
+ *  question from this one. */
+const EXTENSIONS = ['.js', '.mjs', '.cjs'];
+/**
+ * Identity helper for authoring a `.rman/<name>.mjs` command with full type-checking and
+ * autocomplete - the same `defineConfig` pattern, for the same reason. Returns `command`
+ * unchanged.
+ *
+ * ```js
+ * // .rman/deploy.mjs
+ * import { defineCommand, VersionService } 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, runBin, logger }, args) {
+ *     const plan = await VersionService.getPlan(repository);
+ *     for (const entry of plan.filter(e => e.status === 'bump')) {
+ *       logger.info(`${entry.package.name} -> ${args.stage}`);
+ *     }
+ *     await runBin('helm', ['upgrade', '--install', args.stage, './chart']);
+ *   },
+ * });
+ * ```
+ *
+ * Take `runBin` from the context rather than importing it: the one on the context already carries
+ * this run's `cwd` (the repository root) and log level.
+ *
+ * This is for **one repository-level operation with logic of its own** - branching, its own CLI
+ * options, rman's services. Running a shell step across every package is what `.rmanrc
+ * "run.<script>"` already does, with the scheduling, topological order, `bail` and progress panel
+ * that come with it; reimplementing that loop here would only lose them.
+ */
+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.
+ *
+ * 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);
+    const commands = [];
+    const errors = [];
+    if (!fs.existsSync(dir))
+        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);
+        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({ ... })`');
+            }
+            if (typeof command.handler !== 'function')
+                throw new Error('"handler" is missing, or is not a function');
+            if (typeof command.describe !== 'string' || !command.describe) {
+                throw new Error('"describe" is missing - `rman --help` has nothing to list the command by without it');
+            }
+            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],
+                file,
+            });
+        }
+        catch (e) {
+            errors.push({ file, reason: e?.message ?? String(e) });
+        }
+    }
+    return { commands, errors };
+}
+/**
+ * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
+ * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
+ * it unable to tell which ran.
+ */
+export function assertNoBuiltinShadowing(commands, builtins) {
+    const clash = commands.find(c => builtins.includes(c.name));
+    if (!clash)
+        return;
+    throw new Error(`"${path.relative(process.cwd(), clash.file)}" would shadow rman's built-in "${clash.name}" command.\n` +
+        `  Rename the file, or give it its own name with \`command: '<name>'\`.`);
+}