rman 1.0.10 → 1.1.1

package/core/config.js

@@ -2,8 +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
@@ -56,53 +59,225 @@ 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 `targetDir` by cascading from `rootDir`
- * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
- * works: each directory level overrides the ones above it. This lets a
- * package (or any intermediate directory) narrow or override the repository's
- * root configuration for itself and everything below it.
+ * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
+ * it (inclusive) - each directory level overrides the ones above it, the way tsconfig's `extends`
+ * chain does.
+ *
+ * Every level contributes in two ways, and the difference is the whole model:
+ *
+ * - **Unmarked keys configure the package of the directory that declares them.** The root's own
+ *   `.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 (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
+ * its own directory; on the root it's a repo-wide bookend run once at the repository root. A
+ * 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, 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()) {
+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);
         }
-        merge(result, local, { 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'));
+        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));
     }
+    /** 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: `"[*]"`, `"[/]"`, `"[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) {
+    return globToRegExp(key.slice(1, -1));
+}
+/**
+ * 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;
+        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) => 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 = {};
+    for (const [key, value] of Object.entries(config))
+        if (!isSelectorKey(key))
+            result[key] = value;
     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('..'))
@@ -115,3 +290,220 @@ function dirChain(rootDir, targetDir) {
     }
     return dirs;
 }
+/**
+ * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
+ * the package it was resolved for:
+ *
+ * ```yaml
+ * "[*]":
+ *   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
+ * nobody remembers.
+ *
+ * The contents are **real JavaScript**, not a template mini-language, so there is no growing list
+ * of substitutions to keep adding (`{{major}}`, `{{scope}}`, ...) - see `ConfigScope` for what is
+ * in scope.
+ *
+ * **`${{ }}`, deliberately not `{{ }}`.** A config value may legitimately carry `{{...}}` meant for
+ * something else entirely (`helm template --set tag={{.Values.tag}}`); with the plainer delimiter
+ * rman would try to evaluate it. To emit a literal, let an expression produce it, the way GitHub
+ * Actions does: `${{ '${{' }}`.
+ *
+ * A string that is *nothing but* one expression keeps the value's own type (`"${{ pkg.private }}"`
+ * -> a boolean), since otherwise this could only ever produce strings and settings like
+ * `run.<script>.skip` would be unreachable. Embedded in surrounding text it is stringified.
+ *
+ * Evaluation happens in a fresh V8 context holding only the scope's bindings. That is a clean
+ * scope, **not a sandbox** - `node:vm` is explicitly not a security mechanism, and no sandbox is
+ * called for here anyway: a `.rmanrc` that can say `exec: "..."` already runs arbitrary shell, so
+ * the expression evaluator adds no trust boundary that wasn't already wide open.
+ *
+ * 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, options) {
+    const skip = options?.skip ?? [];
+    const context = vm.createContext({ ...scope });
+    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;
+/** 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], skip));
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, item] of Object.entries(value))
+            result[key] = walk(item, scope, context, [...at, key], skip);
+        return result;
+    }
+    return value;
+}
+function interpolateString(value, context, at) {
+    if (!value.includes('${{'))
+        return value;
+    const found = [...value.matchAll(EXPRESSION)];
+    if (!found.length)
+        return value;
+    /** Counted rather than matched with an anchored `^...$` regex: a lazy quantifier still backtracks
+     *  to satisfy an end anchor, so `"${{ a }} and ${{ b }}"` looked like *one* expression whose body
+     *  ran from `a` to `b`, brace-ends and all - invalid JavaScript. */
+    const soleExpression = found.length === 1 && found[0][0] === value.trim();
+    // Alone, a nullish result is just "this setting is unset" - a legitimate answer.
+    if (soleExpression)
+        return evaluate(found[0][1], value, context, at);
+    return value.replace(EXPRESSION, (_, expr) => {
+        const result = evaluate(expr, value, context, at);
+        /** Embedded in text, though, it never is: splicing in the word "undefined" produces a path or
+         *  tag like `app:undefined` that looks plausible and is wrong - the exact silent-mistake shape
+         *  this evaluator exists to avoid. `?? 'fallback'` says what was meant. */
+        if (result === undefined || result === null) {
+            const where = at.length ? formatPath(at) : 'the config root';
+            throw new Error(`Expression in "${where}" is ${result} inside a string: ${value.trim()}\n` +
+                `  \${{${expr}}} has no value here - give it a fallback (\${{${expr.trim()} ?? '...'}}).`);
+        }
+        return String(result);
+    });
+}
+/** Names the config path as well as the expression: an error saying only "x is not defined" sends
+ *  the reader hunting through a file that may hold dozens of them. */
+function evaluate(expr, source, context, at) {
+    try {
+        return vm.runInContext(expr, context, { timeout: EXPRESSION_TIMEOUT });
+    }
+    catch (e) {
+        const where = at.length ? formatPath(at) : 'the config root';
+        throw new Error(`Invalid expression in "${where}": ${source.trim()}\n  ${e?.message ?? e}`, { cause: e });
+    }
+}
+function formatPath(at) {
+    return at.reduce((acc, part) => (typeof part === 'number' ? `${acc}[${part}]` : acc ? `${acc}.${part}` : String(part)), '');
+}
+/** Guards against an expression that never returns (`while(true)`) taking the whole command with
+ *  it - a typo, not an attack, but the failure mode is identical. */
+const EXPRESSION_TIMEOUT = 1000;

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;