rman 1.3.0 → 2.0.0-beta.2

package/interfaces/rman-config.interface.d.ts

@@ -1,98 +1,272 @@
-import type { RmanPlugin } from '../core/plugin.js';
+import type * as yargs from 'yargs';
+import type { RmanApplication } from '../core/application.js';
+import type { ConfigValue } from '../core/config.js';
+import type { CustomCommand } from '../core/custom-command.js';
+import type { Plugin } from '../core/plugin.js';
+import type { PublishTarget } from '../core/publish-target.js';
 import type { RunConditionFn, RunStepValue } from '../core/run-step.js';
-/**
- * Adds a `+key` alongside every key of `T`, which **appends** to whatever that key already resolved
- * to instead of replacing it - see `mergeConfig`.
- *
- * Generated by key remapping rather than written out, so a key added to the interface gets its
- * append form automatically and the two can never drift apart.
- */
-export type WithAppend<T> = {
-    [K in keyof T as `+${K & string}`]?: T[K];
-};
-/**
- * The one key every nested config node may carry: `vars` scoping that node's subtree - a fresh copy
- * per level, merged per key over the level above. See `withScopedVars` in `core/config.ts` for what
- * it does at resolution time, and docs/rman.md#scoped-vars for how it reads.
- *
- * **Every nested options interface extends this**, and a new one has to remember to - which is the
- * cost of the runtime rule being general (any object node scopes) while a type can only say it one
- * interface at a time. TypeScript has no way to state "and every object below this may also carry
- * `vars`" without a recursive remap that would wreck the error messages.
- *
- * Extended by the `XOptions` interface rather than declared on `XOptionsKeys`, so `WithAppend` does
- * not generate a `+vars`: appending to `vars` means nothing, since objects merge either way.
- */
-export interface ScopedVars {
-    /** Values for `${{ vars.* }}` to read, for this node and everything under it. */
-    vars?: Record<string, unknown>;
-}
 /**
  * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
  * `"rman"` key) - see docs/rman.md#configuration-rmanrc-rmanrcyml for the full reference. Every
  * field is optional and cascades from the repository root down to each package's own directory.
- * Purely a typing aid (used by `defineConfig` below, and importable on its own for a `.rmanrc.ts`/
- * `.mts` authored config, or a plain `: RmanConfig` annotation) - never read by rman itself, which
- * only ever sees the plain JS object a JS config file exports.
+ * Purely a typing aid - never read by rman itself, which only ever sees the plain JS object a
+ * config file exports.
+ *
+ * **Two halves, and the split is who declares a key.** `RmanConfigKeys` holds the ones no command
+ * owns; `CommandConfigs` is what every command contributes its own into, from beside the command
+ * (see `CommandContribution`). This used to be two files and two types both called `RmanConfig` -
+ * one for the config shape, one for the command declarations - which is why the package could not
+ * export the second at all.
+ *
+ * **This is the type an *author* writes**, and `ResolvedConfig` - derived from it - is what a
+ * *reader* gets. One type could not be both: a value may be written as a **function** here, because
+ * rman calls it while the config resolves, and by the time anything reads `pkg.config` it has
+ * already been called. Answering only the reader's question is what this type used to do, and it
+ * made `docs/rman.md`'s own `changelog: { filePath: ({ vars }) => ... }` a compile error.
+ *
+ * **The direction matters, and it was measured the wrong way round first.** Widening this type
+ * while `Package.config` still used it moved the cast to every **read** - six sites broke
+ * (`version.command.ts`, `publish-target.ts`, `changelog.service.ts`, three in
+ * `github-release.service.ts`). The widening was right; leaving the reader on the same name was not.
+ * So the author's view is the declared one and the reader's is computed: see `Resolved`, which also
+ * records the two guards that make a mechanical transform safe here.
+ *
+ * **Deriving the other direction is what cannot work, and the reason is this name.** `RmanConfig` is
+ * also a **namespace** (`RmanConfig.CommandConfigs`, `CommandContribution`, …) that `rman-node`
+ * augments; a `type` alias cannot merge with a namespace, and the resulting circular reference
+ * resolves to `{}` **silently** - measured, every key then read as "does not exist", `vars` and
+ * `run` included. A derived *reader* view needs no such merge, which is why it is the half that is
+ * derived.
+ *
+ * Which keys may be written as a function is not a judgement made key by key: every option a
+ * command declares is one, because an option's value is by construction a value rather than a step
+ * (`CommandConfigFromMetadata`). Only the hand-written `Extra` keys are decided individually, since
+ * that is where a step key lives.
  */
-export interface RmanConfig extends RmanConfigKeys, WithAppend<RmanConfigKeys> {
+export interface RmanConfig extends RmanConfigKeys, RmanConfig.CommandConfigs {
     /**
      * Configs to inherit from, merged **underneath** this one - a shared package
      * (`"@panates/rman-monorepo"`), a relative path, or an array applied in declaration order.
      *
-     * A bare name resolves through *this* file's own `node_modules`, so a subpath works too
-     * (`"@panates/rman-monorepo/strict"`). The target may be YAML, JSON, or a module exporting a
-     * config via `defineConfig`, and may itself `extends` another.
+     * A bare name resolves through *this* file's own `node_modules`, so a subpath works too. The
+     * target may be YAML, JSON, or a module exporting a config via `defineConfig`, and may itself
+     * `extends` another.
      *
      * Top level only: a `"[selector]"` block naming one is an error rather than a no-op, since
      * inheritance is a statement about this config and not about the packages a selector names.
+     *
+     * Resolved away long before a reader sees one, and kept on this type because `rman config` prints
+     * the object it was resolved from.
      */
     extends?: string | string[];
 }
-/** Every setting a config may carry, without the `+key` append forms or `extends` - the shape
- *  `RmanConfig` is built from, kept separate only so `WithAppend` has something to map over. */
+/**
+ * One entry of `.rmanrc "commands"` - a command, or a **glob** naming `.js` modules that
+ * `export default` one.
+ *
+ * Both authoring forms count as "a command": the declarative `app => ({ ... })` factory, which is
+ * the one to write, and the older `defineCommand({ ... })` object a `.rman/*.mjs` uses.
+ */
+export type CommandEntry = string | CustomCommand | RmanConfig.CommandRegisterFunction;
+/** One entry of `.rmanrc "publishTargets"` - a target, or a **glob** naming `.js` modules that
+ *  `export default` one. */
+export type PublishTargetEntry = string | PublishTarget;
+/**
+ * **The `.rmanrc` keys no command owns**, without `extends` - kept
+ * separate from `RmanConfig` only so the two halves stay legible. A key a *command* owns is
+ * declared beside that command and arrives through `RmanConfig.CommandConfigs` instead.
+ *
+ * **A plugin adds its own keys here, by declaration merging** - `rman-node` contributes `clean`
+ * from its own `interfaces/rman-config.interface.ts`, so `pkg.config.clean` stays typed wherever it
+ * is read without the core having to know npm has a `node_modules` or that TypeScript has build
+ * output. (A *target's* block is different again: `publish.npm.*` goes through the
+ * `PublishTargetConfigs` slot, beside the core's own `publish.docker.*`.)
+ *
+ * A config author annotates with the plugin's own name for the union - `RmanNodeConfig` - which is
+ * what makes the import that carries the augmentation explicit rather than incidental.
+ */
 export interface RmanConfigKeys {
     /**
-     * **A plugin adds its own keys here, by declaration merging** - `rman-node` contributes
-     * `clean` and `publish.directory` from its own
-     * `interfaces/rman-config.interface.ts`, so `pkg.config.clean` stays typed wherever it is read
-     * without the core having to know npm has a `node_modules` or that TypeScript has build output.
-     * `WithAppend` is a mapped type evaluated at use, so an augmented key gets its `+key` form too.
-     *
-     * A config author annotates with the plugin's own name for the union - `RmanNodeConfig` - which
-     * is what makes the import that carries the augmentation explicit rather than incidental.
+     * The technologies this repository holds, in declaration order - how its packages are
+     * recognized, where they are, how their versions are planned. One per ecosystem: `rman-node`
+     * contributes the `node` one, a Cargo plugin would contribute `cargo`, and a polyglot repository
+     * names both.
+     *
+     * Each entry is **a plugin, or a glob naming `.js` modules that `export default` one** - the same
+     * two forms `commands` and `publishTargets` take:
+     *
+     * ```js
+     * // .rmanrc.mjs - the instance, which a JS config can hand over and a YAML one cannot
+     * import { defineConfig, definePlugin } from 'rman';
+     * export default defineConfig({ plugins: [definePlugin({ name: 'cargo', manifestProvider })] });
+     * ```
+     *
+     * A *published* plugin is not usually named here at all: its package exports a config carrying
+     * it, so the repository writes `extends` and the plugin arrives with everything else the package
+     * declares. `rman-node` deliberately exports no `NodePlugin` for this reason - there is nothing a
+     * consumer needs to do with it by hand.
+     *
+     * ```yaml
+     * # .rmanrc.yml - a glob, anchored to this file's own directory
+     * plugins: './plugins/*.js'
+     * ```
+     *
+     * **A package name is not one of the forms, and `plugins: ['rman-node']` is never valid.** That
+     * package's entry point exports an rman *config* - `{ plugins, commands, publishTargets }` - and
+     * a config's way into a repository is `extends`, the key that means "merge this underneath
+     * mine". The two are different statements: `extends: 'rman-node'` inherits everything the
+     * package declares, while `plugins` names the technologies themselves. Naming the package here
+     * is refused with a message saying so, rather than half-read.
+     *
+     * A plugin that cannot be loaded is an error, not a skip - silently losing a manifest reader
+     * means every package reads as nameless at `0.0.0`, which looks like a working repository.
+     *
+     * **Root level only, and unlike `commands` this is forced rather than chosen**: `loadPlugins`
+     * runs inside `Repository.create` *before* the packages are known, because a plugin's
+     * `getWorkspace` is what finds them - so there are no package configs to read. An entry in a
+     * package's own `.rmanrc` is never seen.
      */
+    plugins?: string | Plugin | (string | Plugin)[];
     /**
-     * Plugins to load, in declaration order - a *package* contributing commands, where `.rman/*.mjs`
-     * contributes one repository's own.
+     * **Which technology a package belongs to**, by `Platform.name`.
+     *
+     * ```yaml
+     * plugins: ['node']
+     * "[/]":
+     *   platform: node
+     * ```
+     *
+     * **`plugins` loads; this selects.** They were one key for a while and that conflated two
+     * statements: `plugins` says which technologies this repository has available, which is a fact
+     * about the *repository* and is read once at its root. Which technology a given directory's
+     * package belongs to is a fact about the *package*, and a repository may hold more than one - so
+     * it is an ordinary cascading key, declared wherever the answer changes.
      *
-     * Each entry is **either a package name (or path) to import, or a plugin object itself**:
+     * - **A declaration wins over the guess.** Without it, a directory belongs to the first
+     *   registered platform whose manifest provider recognizes it (`app.platformFor`) - which is a
+     *   reasonable default and is registration order deciding a question about someone's code. Naming
+     *   it takes the answer away from load order.
+     * - **The named platform validates it, and a mismatch is an error.** If it does not recognize the
+     *   directory the declaration is simply untrue, and the alternative is a package reading as
+     *   nameless at `0.0.0` - which looks like a working repository. The message names the file the
+     *   platform looked for.
+     * - **It cascades like any unmarked key**, so one line at the root covers a single-technology
+     *   repository and a package's own `.rmanrc` overrides it for that subtree. `"[/]"` keeps it on
+     *   the root package alone.
+     * - **At the root it also means the repository said something**, so detection does not run - the
+     *   same rule `plugins: []` follows. A repository that states its technology is not a repository
+     *   that stated nothing.
+     *
+     * **At the root, naming a built-in is the same statement as `plugins: ['node']`** - it is put at
+     * the *front* of `plugins`, so the whole built-in arrives: the technology, its commands and its
+     * publish targets. Saying which technology this repository is *is* saying it has it, and making
+     * an author write both was a distinction only rman could see. At the front rather than appended,
+     * because `platformFor` takes the first registered platform that recognizes a directory - the one
+     * the repository says it *is* should win over whatever a shared config brought along. Read from
+     * the unmarked key or from `"[/]"`, since both are the root speaking.
+     *
+     * **Below the root it loads the technology alone**, and that is structural rather than chosen:
+     * `plugins` is read once, at the root, before any package exists, so a nested declaration cannot
+     * contribute commands even in principle. It is also what you want there - a Node package inside a
+     * Cargo repository wants npm's manifest read, not a repo-wide `rman clean` sweeping the tree.
+     *
+     * Only a built-in is promoted. A platform rman does not ship is loaded by the `plugins` entry
+     * that brings it, and naming one with no such entry is an error listing what the repository has -
+     * putting the bare name into `plugins` would hand the loader a glob matching no file, so the
+     * failure would read as the plugin being missing while it is registered perfectly well.
+     *
+     * **A plain string, never a `${{ }}` expression.** This is read while the packages are still
+     * being found, so there is no `pkg` for an expression to be about - it is what decides what a
+     * package *is*. An expression here is refused rather than passed through as a literal, which is
+     * what silently happened until it was.
+     */
+    platform?: string;
+    /**
+     * **The selector this package answers to** - what a `"[glob]"` block and `--scope`/`--ignore`
+     * match against, overriding whatever its platform said.
      *
      * ```yaml
-     * # .rmanrc.yml - imported by name, resolved through the repository's own node_modules
-     * plugins: ['rman-node']
+     * # packages/web/.rmanrc
+     * name: web
      * ```
      *
-     * ```js
-     * // .rmanrc.mjs - or handed over directly, which a JS config can do and a YAML one cannot
-     * import { defineConfig, definePlugin } from 'rman';
-     * export default defineConfig({ plugins: [definePlugin({ name: 'mine', commands: [...] })] });
+     * **The escape hatch for an ecosystem that cannot name a package, and only that.** npm can:
+     * `package.json#name` exists and identifies the package, so a Node repository never writes this.
+     * An ecosystem where a package need not be named, or where the name is an import path nobody
+     * would type after `--scope`, leaves `ManifestProvider.selector` unanswered and the repository
+     * fills it in here.
+     *
+     * **It does not rename the package.** `pkg.name` is still what the manifest says, so tags,
+     * changelogs and the registry are untouched - this is an address, and `Package.selector` is where
+     * it lands.
+     *
+     * **Unique within the repository, and checked.** Two packages answering to one selector make
+     * `"[that]"` and `--scope that` ambiguous, and the ambiguity is silent: the config reaches both
+     * and `getPackage` returns whichever came first. The error names both directories.
+     *
+     * **Cascades like any unmarked key, which for this one is almost always a mistake** - one
+     * declaration above two packages gives them the same address, so the uniqueness check fires and
+     * says so. Declare it in the package's own `.rmanrc`.
+     *
+     * **Not inside a `"[glob]"` block**, which is refused rather than ignored: the glob matches the
+     * selector, so a block that sets it would need its own answer to find itself. Read from the
+     * unmarked cascade for the same reason `platform` is - before the package exists.
+     */
+    name?: string;
+    /**
+     * Where this repository keeps command modules of its own - a glob, or a list of them.
+     *
+     * ```yaml
+     * commands: ['tools/commands/*.mjs']
      * ```
      *
-     * The object form is what lets a **plugin package export a config** rather than a single plugin:
-     * `rman-node`'s entry point is `export default defineConfig({ plugins: [ ... ] })`, so it is an
-     * `.rmanrc` like any other and is free to grow a second plugin without changing its shape. When an
-     * imported module exports a config this way, **only its `plugins` are read** - a config's other
-     * keys reach a repository through `extends`, which is the key that means "merge this underneath
-     * mine".
+     * **Where a command comes from, whoever ships it.** A repository writing one of its own, and a
+     * package contributing three, reach yargs by this one key - so there is one source of
+     * non-built-in commands and one precedence slot. `.rman/*.{js,mjs,cjs}` is simply this key's
+     * default value rather than a second mechanism beside it, and a package needs no plugin to
+     * contribute a command: a plugin is a *technology*, and a command is not one.
+     *
+     * **A relative glob is anchored to the file that declared it**, not to the repository root (see
+     * `anchorContributions`), so a shared config can ship commands with `commands: './commands/*.js'`
+     * and have it mean its own directory.
+     *
+     * **Always appends** (`ALWAYS_APPEND`), like the other two contribution keys and for the same
+     * reason: naming a directory of your own never means "and stop loading the ones my shared config
+     * ships". It follows that a closer layer cannot *un*-say one.
+     *
+     * **Trap: a glob replaces the `.rman/` default and an instance does not.** The default applies
+     * only when *no* glob was declared anywhere - the key appends onto other layers, not onto a
+     * built-in fallback - so a shared config shipping its commands by glob silently takes the
+     * `.rman/` directory away from every repository inheriting it. Measured both ways on the same
+     * pair of repositories: with the shared config declaring instances, the consumer's own
+     * `.rman/hello.mjs` is in `rman --help`; with it declaring `'./commands/*.js'`, that command is
+     * simply gone. **A config meant to be inherited should therefore list its commands
+     * individually.**
+     *
+     * Declared at any level, unlike `plugins` and `publishTargets`, because by the time this is read
+     * the packages exist - so a package's own `.rmanrc` may contribute one. The commands themselves
+     * are still repository-wide, because there is one command list; a package declaring one is
+     * contributing it to the repository.
+     *
+     * A module exports either form: the declarative `app => ({ ... })` factory, which is the one to
+     * write, or the `defineCommand({ ... })` object. **`.ts` is not loadable** - rman imports these in
+     * its own process, with no loader registered - so a TypeScript repository compiles them first or
+     * writes them as `.mjs`.
+     */
+    commands?: CommandEntry | CommandEntry[];
+    /**
+     * Publish targets this repository has - where a package's artifact ships. An instance, or a glob
+     * naming `.js` modules that `export default` one.
      *
-     * This is how everything that only means something in a Node repository lives outside rman's
-     * core. A plugin that cannot be loaded is an error, not a skip: silently losing `rman publish` is
-     * worse than not starting.
+     * The same two forms as `plugins` and `commands`, and for the same reason: a target is a
+     * contribution, so a config declares it rather than a plugin registering it by hand. rman's own
+     * `docker` target is built in; `rman-node` contributes `npm` from its own config.
      *
-     * Root level only - which commands exist is a property of the repository, not of a package.
+     * Always appends. **Root level only, like `plugins` and for the same mechanical reason** - both
+     * are read by `loadPlugins` inside `Repository.create`, before there is a package whose config
+     * could be consulted. `commands` is the one of the three that is read at any level.
      */
-    plugins?: string | RmanPlugin | (string | RmanPlugin)[];
+    publishTargets?: PublishTargetEntry | PublishTargetEntry[];
     /**
      * Values for `${{ vars.* }}` to read - a name for something the config would otherwise repeat:
      *
@@ -132,10 +306,6 @@ export interface RmanConfigKeys {
      */
     skip?: boolean;
     group?: boolean | string;
-    version?: RmanConfig.VersionOptions;
-    changelog?: RmanConfig.ChangelogOptions;
-    publish?: RmanConfig.PublishOptions;
-    githubRelease?: RmanConfig.GithubReleaseOptions;
     /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). A bare string (or array of
      *  them) is shorthand for `{ exec: ... }` - `test: "mocha"` and `test: { exec: "mocha" }` mean
      *  exactly the same thing, and a bare function is the same shorthand for a function step. */
@@ -155,11 +325,11 @@ export interface RmanConfigKeys {
      * **A list, and only a list.** It used to accept a `Record<string, string>` too, documented as "an
      * explicit name -> range map" - and the ranges went nowhere: the one reader took `Object.keys` and
      * dropped the values. Nor could they ever mean anything here, since the cascade works from groups
-     * and severities, and `ManifestProvider.updateDependencyVersions` rewrites ranges in the
+     * and severities, and `Plugin.updateDependencyVersions` rewrites ranges in the
      * *manifest* - a range declared only in `.rmanrc` has no file to be written to. What this key
      * states is an **edge**, and an edge needs two ends and nothing else.
      *
-     * **Core, and it has to be**: it is layered on top of whatever `ManifestProvider.dependencies`
+     * **Core, and it has to be**: it is layered on top of whatever `Plugin.readDependencies`
      * read, and it is the *only* way a repository with no provider at all has a graph - a repo whose
      * manifests rman cannot read can still state its edges by hand. Moving it to an ecosystem plugin
      * would take that away from exactly the repositories that need it.
@@ -198,73 +368,355 @@ export interface RmanConfigKeys {
      */
     [selector: `[${string}]`]: RmanConfig;
 }
+export declare const commandRegistry: RmanConfig.CommandRegisterFunction[];
+/**
+ * The one key every nested config node may carry: `vars` scoping that node's subtree - a fresh copy
+ * per level, merged per key over the level above. See `withScopedVars` in `core/config.ts` for what
+ * it does at resolution time, and docs/rman.md#scoped-vars for how it reads.
+ *
+ * **Every nested options interface has to carry this**, and a hand-written one had to remember to -
+ * which is the cost of the runtime rule being general (any object node scopes) while a type can only
+ * say it one interface at a time. TypeScript has no way to state "and every object below this may
+ * also carry `vars`" without a recursive remap that would wreck the error messages. A command's
+ * contributed block gets it from `RmanConfig.ConfigBlock` and cannot forget.
+ */
+export interface ScopedVars {
+    /** Values for `${{ vars.* }}` to read, for this node and everything under it. */
+    vars?: Record<string, unknown>;
+}
 export declare namespace RmanConfig {
     /**
-     * One `version.stamp` entry: a path, or a path plus the identifier that holds the version.
+     * **The slot every command merges its own keys into.** Empty here on purpose: the core declares
+     * no command's config, each command declares its own beside the command itself, and a plugin's
+     * commands do the same from their own package.
+     *
+     * A command augments it with its derived contribution rather than a hand-written interface, so
+     * the option list and the config type cannot drift apart:
      *
-     * The object form exists because the identifier was unnameable - only the exact lowercase word
-     * `version` was ever matched, so a Go `const Version`, a Python `__version__` and a plain
-     * `appVersion` were all silently skipped. What the identifier *means* is the ecosystem's
-     * (`ManifestProvider.stampVersion`); which file holds one is the repository's, which is why it is
-     * here.
+     * ```ts
+     * const versionCommand = registerCommand(...);
+     * export default versionCommand;
+     *
+     * declare module '../interfaces/rman-config.interface.js' {
+     *   namespace RmanConfig {
+     *     interface CommandConfigs extends CommandContribution<ReturnType<typeof versionCommand>> {}
+     *   }
+     * }
+     * ```
+     *
+     * **Two commands may not contribute under the same top-level key.** Interface merging is not a
+     * deep merge: `{run: {build: ...}}` and `{run: {test: ...}}` is
+     * `Interface 'CommandConfigs' cannot simultaneously extend types ...` - measured. That is the
+     * mechanical reason `build` and `test` own nothing and only *read* `run.build`/`run.test`; `run`
+     * is the single owner of that subtree.
      */
-    type VersionStampEntry = string | {
-        file: string;
-        constant?: string;
-    };
-    interface VersionOptions extends VersionOptionsKeys, WithAppend<VersionOptionsKeys>, ScopedVars {
+    interface CommandConfigs {
     }
-    interface VersionOptionsKeys {
-        commitMessage?: string;
-        /** Default for `version --changelog` when the CLI flag isn't given - a standing "always fold
-         *  the changelog into the version-bump commit" policy, rather than something that behaves
-         *  differently on the one run someone forgets to pass `--changelog`. An explicit `--changelog`/
-         *  `--no-changelog` on the command line still wins either way. Root-level only. Default `false`. */
-        changelog?: boolean;
-        /** Tag naming the repository's own release, as opposed to the per-package/group tags
-         *  `changelog.tagPattern` names - only created when the root is on a calendar version (a repo
-         *  with more than one version line). Root-level only. Default `"release-*"`. Must **not** match
-         *  any package's own `changelog.tagPattern`, or that package's changelog boundary will resolve
-         *  to the repository release instead of its own last release. */
-        releaseTagPattern?: string;
-        /** Keep this package's Dockerfile `org.opencontainers.image.version` label in step with the
-         *  version being written. Per-package cascaded. Default `true` - the label's value is, by
-         *  specification, the version of the packaged software, so there is only ever one correct
-         *  value for it, and `version` is what knows it. Only ever *rewrites* a label the Dockerfile
-         *  already declares (never inserts one), and reads the same path `publish --target docker`
-         *  builds from (`publish.docker.dockerfile`), so a package without one is a no-op. */
-        stampDockerfile?: boolean;
-        /** Files whose hard-coded version is rewritten to the version being written, in the same
-         *  commit as the bump - paths relative to the package's own directory (e.g.
-         *  `["src/constants.ts"]`). Per-package cascaded; a listed file a package doesn't have is a
-         *  silent no-op, so one `"[*]"` declaration covers a repo where only some packages carry one.
-         *
-         *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
-         *  claiming a placeholder, so anything running from source reports that placeholder, git never
-         *  records the released version, and the rewrite has to be redone on every build. */
-        stamp?: VersionStampEntry | VersionStampEntry[];
-        /** Command(s) run at the version write itself, when the package does not declare a hook for
-         *  that slot of its own (`version` in a Node repository's `package.json#scripts`, whatever a
-         *  plugin's step source answers elsewhere - the package's own declaration wins, as in `run`).
-         *  An array runs them in sequence. `${{ pkg.targetVersion }}` is bound here and in the two
-         *  below, and nowhere else.
-         *
-         *  A `RunStepFn` runs in place of a shell command - but note that `${{ pkg.targetVersion }}` is
-         *  a *string* substitution, so a function reads the written version off `pkg` instead. */
-        exec?: RunStepValue | RunStepValue[];
-        /** Same, before the write (`preversion` in a Node repository). */
-        before?: RunStepValue | RunStepValue[];
-        /** Same, after it (`postversion` in a Node repository). */
-        after?: RunStepValue | RunStepValue[];
-    }
-    interface ChangelogOptions extends ChangelogOptionsKeys, WithAppend<ChangelogOptionsKeys>, ScopedVars {
+    interface CommandConfig {
+        skip?: boolean;
+        logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+        vars?: RmanConfig.VarsMap;
+        [index: string]: any;
     }
-    interface ChangelogOptionsKeys {
-        ignoreTypes?: string[];
-        template?: string;
-        filePath?: string;
-        tagPattern?: string;
+    interface VarsMap {
+        /** Values for `${{ vars.* }}` to read, for this node and everything under it. */
+        vars?: Record<string, unknown>;
     }
+    /**
+     * Called during init, with the application - not at import, and not with just the repository.
+     *
+     * The application is what a command reaches services through (`app.getService('changelog')`), and
+     * `app.repository` is still there for the metadata that reads it: `version`'s help names its own
+     * scheme's bump words, which cannot be known before a repository exists.
+     */
+    type CommandRegisterFunction = (app: RmanApplication) => CommandMetadata;
+    /** One declared option: everything yargs takes, plus where it may be set from. */
+    type CommandOption = yargs.Options & {
+        array?: boolean;
+        conflicts?: string | string[];
+        target: 'cli' | 'config' | 'both';
+        /** The flag's spelling on the command line when it differs from the config key - `ignoreDirty`
+         *  is `--ignore-dirty`. The key stays the camelCase one, since that is what a `.rmanrc` writes. */
+        cliName?: string;
+    };
+    /**
+     * One declared positional, as `CommandMetadata.positionals` holds them - yargs' own type, named
+     * here so a command's author can reach it.
+     *
+     * **An alias with no additions, and it earns its place anyway.** `positionals` was the one part
+     * of a declaration that could only be typed by importing yargs, and a plugin does not depend on
+     * yargs - rman does. Nothing enforced that, because a returned object literal is checked
+     * structurally: measured on a JavaScript plugin, `positionals: { paths: { type: 'string' } }`
+     * widens `'string'` to `string` and fails `PositionalOptionsType`, with the error arriving on
+     * the whole `commands` key several levels of "is not assignable" away from the word that caused
+     * it. A `satisfies Record<string, PositionalOption>` beside the options' own puts it back on the
+     * line. Same reasoning as the flat `CommandOption` in `index.ts`.
+     */
+    type PositionalOption = yargs.PositionalOptions;
+    type CommandMetadata = {
+        command: string;
+        /** Other names the command answers to - `list` is also `ls`. */
+        aliases?: string[];
+        /**
+         * yargs parser switches this command needs. `exec` is the only one so far and needs two:
+         * `populate--` to keep everything after `--` out of its own options, and
+         * `unknown-options-as-args` so the flags of the command *being run* pass through untouched.
+         */
+        parserConfiguration?: Partial<yargs.ParserConfigurationOptions>;
+        describe?: string;
+        examples?: {
+            command: string;
+            description?: string;
+        }[];
+        /**
+         * The options this command **owns** - the ones it contributes to `RmanConfig`, under
+         * `configKey`. An option a command merely *reads* belongs to whoever declares it; name it in
+         * `configKeys` instead. One key, one owner: two commands declaring the same key differently
+         * would collide silently in the augmentation's intersection.
+         */
+        config?: Record<string, CommandOption>;
+        /**
+         * Where `config` lands in a `.rmanrc`. Defaults to the first word of `command`, and a dotted
+         * path nests (`'run.build'` -> `{ run: { build: ... } }`).
+         *
+         * **Needed exactly once across the nine commands today**, which is why it is optional rather
+         * than required: `github-release` writes `githubRelease`, since a config key is camelCase and a
+         * command name is hyphenated. Deriving that with a kebab-to-camel rule was the alternative and
+         * was refused - it is one more rule to remember, and when it goes wrong the key lands somewhere
+         * plausible and nobody notices.
+         */
+        configKey?: string;
+        /**
+         * Config subtrees this command reads but does not own - what `--config` should show beside its
+         * own. A function of argv where the answer depends on it (`run <script>` reads `run.<script>`).
+         *
+         * `version` is the clearest case: it owns `version.*`, but `group` decides which packages move
+         * together and `changelog.*` is consulted when `--changelog` folds one into the bump commit.
+         * Neither is `version`'s to declare.
+         */
+        configKeys?: string[] | ((argv: yargs.Arguments) => string[]);
+        /**
+         * The positionals `command` declares, described - `'version [bump]'` names `bump`, this says
+         * what it is. Keyed by name, and **the names are checked against the command string**: a typo
+         * or a positional the command never declared fails on its own key and names the string it was
+         * checked against, which the `.positional('bump', ...)` builder call could never do.
+         *
+         * Only the description belongs here. Whether one is required (`<x>`) or variadic (`[x..]`) is
+         * part of the command string, which is the only place it can be, since that is what yargs
+         * parses.
+         */
+        positionals?: Record<string, PositionalOption>;
+        /**
+         * **The parameter is the command's own business, so this states no type for it.**
+         * A handler annotates itself with `ArgsOf<typeof config, typeof COMMAND>`, which this interface
+         * cannot compute for it - `M` is inferred from the literal the handler sits in, so naming it
+         * here is the circularity `ArgsOf` documents.
+         *
+         * It was `(argv: yargs.Arguments) => void`, and that was **not** a neutral placeholder: a
+         * parameter is checked contravariantly, so every command's own `Args` had to be a *supertype* of
+         * yargs' `{ [argName: string]: unknown }`. An index signature does not make a property present,
+         * so any required key put the declaration out of assignment - which is what forced `ArgsOf` to
+         * mark **everything** optional, required positionals included. Measured when it stopped:
+         * `Property 'script' is missing in type '{ [argName: string]: unknown; ... }' but required in
+         * type '{ script: string; }'`, on `run` and `import` alone.
+         *
+         * `never` is the spelling for "any parameter type is acceptable" - it constrains the *shape*
+         * (one argument, returning nothing a caller reads) and leaves the type to the annotation. It is
+         * not an `any` that could leak: nothing ever reads argv through this field, since
+         * `toYargsCommand` casts the handler to yargs' own and that cast is the single place the two
+         * descriptions of argv are admitted to disagree.
+         */
+        handler: (argv: never) => void;
+    };
+    /**
+     * The names a command string declares as positionals: `'run <script> [args..]'` is
+     * `'script' | 'args'`.
+     *
+     * Handles all four spellings in use - `<required>`, `[optional]`, `[variadic..]`, and the
+     * `[three...]` that `list` writes (yargs' own marker is two dots, so that one is a latent bug
+     * worth fixing separately; the parser tolerates it rather than silently producing a name with a
+     * dot in it).
+     */
+    type PositionalsOf<C extends string> = C extends `${string}<${infer N}>${infer Rest}` ? StripDots<N> | PositionalsOf<Rest> : C extends `${string}[${infer N}]${infer Rest}` ? StripDots<N> | PositionalsOf<Rest> : never;
+    /**
+     * `argv` as a command's own declarations describe it - every option by its config key, every
+     * positional the command string names, plus yargs' own two.
+     *
+     * **It is written as an explicit annotation on the handler, not inferred**, and that is a
+     * measured limitation rather than a preference. Inferring it from the sibling `config` works on
+     * its own, but not beside the `M & ValidMeta<M>` check: `M` is inferred from the whole literal,
+     * `handler` is part of that literal, so `ArgsOf<M>` is circular and resolves to
+     * `ArgsOf<CommandMetadata>` - every option "does not exist". Splitting the inference sites gets
+     * the names back and loses the values instead, because `M` and `C` then infer from the same
+     * `config` property and the literals widen, so every option arrives as `unknown`.
+     *
+     * So the declarations are hoisted out of the literal and the handler is annotated:
+     *
+     * ```ts
+     * const COMMAND = 'version [bump]' as const;
+     * const config = { ... } satisfies Record<string, RmanConfig.CommandOption>;
+     *
+     * handler: (args: RmanConfig.ArgsOf<typeof config, typeof COMMAND>) => { ... }
+     * ```
+     *
+     * Two lines, and in exchange the typo checking stays and a renamed option can no longer survive
+     * silently in the handler behind an `as`.
+     *
+     * **A `<required>` positional is required here too, and that is the one thing argv genuinely
+     * guarantees.** yargs refuses the call before the handler runs - measured on both commands that
+     * declare one: `rman run` and `rman import` each exit 1 with `Not enough non-option arguments:
+     * got 0, need at least 1`. Typed optional, the two handlers had to say so themselves
+     * (`args.script as string`, `args.path!`), and an `as` in a handler is exactly what declaring
+     * commands exists to remove - it is also how a renamed positional would survive silently. The
+     * rule is purely syntactic (`<x>` vs `[x]`), so it needs nothing but the command string, which
+     * is already the only place that says whether a positional is variadic.
+     *
+     * **What had made everything optional was not a judgement about argv - it was `handler`'s own
+     * parameter type**, which is where that story is written down. Worth knowing before adding a
+     * required key here: the constraint was three types away from the one that looked responsible.
+     * The claim and the parsing are pinned together in `cli.spec.ts` ("cli: a required positional"),
+     * since a type asserting a key is present is only honest while yargs refuses the call without it.
+     *
+     * **Every option stays optional, `default:` included, and that asymmetry is deliberate.**
+     * Narrowing on `default` needs *two* conditions, not one: the default must be present **and**
+     * `target !== 'config'`, because `toYargsCommand` never registers a `target: 'config'` option, so
+     * yargs never applies its default and the key is simply absent from argv. Written with the one
+     * obvious condition the type would claim a key is present where the runtime has `undefined` -
+     * failing in the direction that crashes. The gain does not pay for that risk yet: rman declares
+     * exactly **one** real option default (`config --json`), read as `if (args.json)`, so `undefined`
+     * and `false` already behave alike. The day a contributed command wants it, both conditions are
+     * written down here. `demandOption` would take the same pair of conditions and no declared
+     * command uses it - the only mention in the tree is a `CustomCommand`'s hand-written `builder`,
+     * which does not go through `ArgsOf` at all.
+     */
+    type ArgsOf<C, Cmd extends string> = {
+        [K in keyof C]?: OptionValue<C[K]>;
+    } & {
+        [K in RequiredPositionalsOf<Cmd>]: PositionalValue<Cmd, K>;
+    } & {
+        [K in Exclude<PositionalsOf<Cmd>, RequiredPositionalsOf<Cmd>>]?: PositionalValue<Cmd, K>;
+    } & GlobalArgs;
+    /**
+     * What every command's argv carries whatever it declares - yargs' own two, and rman's global
+     * options, which are registered on the program rather than per command.
+     *
+     * **Measured the moment `exec` was converted**: its handler read `args.logLevel`, which compiled
+     * only because `yargs.Arguments` is an index signature. With a real type it is
+     * `Property 'logLevel' does not exist` - correct, and exactly the kind of thing that was invisible
+     * before. Global options have to be stated once, here, or every handler that reads one is wrong.
+     */
+    type GlobalArgs = {
+        _: (string | number)[];
+        $0: string;
+        /** `--log-level`, declared on the program in `cli.ts`. */
+        logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+        /** `--config`: print what this command would run with, and run nothing. */
+        config?: boolean;
+        /** Everything after `--`, present when the command sets `populate--` - `exec` reads it to tell
+         *  its own flags from the ones belonging to the command it runs. */
+        '--'?: (string | number)[];
+    };
+    /**
+     * The config object a command's `config` declaration describes - `{ type: 'string' }` becomes
+     * `string`, `{ type: 'string', array: true }` becomes `string[]`.
+     *
+     * **The literal survives inference, which is the whole reason this works.** `{ type: 'string' }`
+     * would normally widen to `string`, but `yargs.Options['type']` is a union of string literals and
+     * the generic's constraint types the object literal contextually - so `ReturnType<T>` still holds
+     * `'string'` by the time this maps over it. Measured, with negative controls: reading a mapped
+     * value as the wrong type errors, and so does naming an option that was not declared.
+     *
+     * `choices` narrows further, and is the one place the caller has to help: an array literal widens
+     * to `string[]` on its own, so `choices: ['a', 'b'] as const` is what yields `'a' | 'b'`. Without
+     * the assertion it falls back to the declared `type`.
+     *
+     * **Every one of them is a `ConfigValue`, and that needs no per-key judgement.** An option
+     * declares a `type` yargs can parse, so what it contributes to `.rmanrc` is by construction a
+     * *value* - never a step, which is why steps arrive through `Extra` instead and have to be decided
+     * one at a time. So the whole derived half widens here, in one place, and a config author may
+     * write `changelog: { filePath: ({ vars }) => ... }` for any of them. `Resolved` takes it back off
+     * again for the reader.
+     */
+    type CommandConfigFromMetadata<T extends CommandMetadata> = T['config'] extends infer C ? C extends Record<string, CommandOption> ? {
+        [K in keyof ConfigOnly<C>]?: ConfigValue<OptionValue<ConfigOnly<C>[K]>>;
+    } : {} : {};
+    /**
+     * What the command adds to `RmanConfig`: its config options, under the key they live at -
+     * `{ version: { changelog: boolean } }`, or `{ run: { build: { exec: string } } }` for a dotted
+     * `configKey`.
+     *
+     * **`Extra` is for what an option cannot describe**, and only that. A `CommandOption` says
+     * `type: 'string'` or `type: 'boolean'`; it has no way to say `{ file: string; constant?: string }`
+     * or "a shell command or a function". So `version.stamp` and `version.before`/`.exec`/`.after`
+     * arrive through `Extra`, hand-written beside the command, while `version.commitMessage` and
+     * `version.releaseTagPattern` are ordinary `target: 'config'` options and are derived like the
+     * rest. Reach for `Extra` when the shape genuinely resists, never to avoid declaring an option.
+     *
+     * **One key, one declaration - which is what makes `Extra` necessary rather than convenient.**
+     * Interface merging is not a deep merge, so a key that arrives from two places is
+     * `Interface 'RmanConfig' cannot simultaneously extend types ... Named property 'publish' of
+     * types ... are not identical` (measured). A command therefore contributes its key *whole*: the
+     * derived half intersected with the hand-written one, never one half here and the other in some
+     * central interface.
+     *
+     * **`run` is the one command this cannot describe**, and it is worth knowing before relying on
+     * this: `run.<script>.*` is keyed by script name, so there is no flat option map to derive from
+     * and `Extra` would be the entire block. Its contribution stays hand-written in `RmanConfig`.
+     *
+     * **A widened key is refused rather than used**, because the damage otherwise is not local:
+     * `Nest<string, V>` is an index signature, so a `configKey` that lost its literal (a missing
+     * `as const`) turns `CommandConfigs` into "every string key has this command's shape" and every
+     * other key in `RmanConfig` then fails to satisfy it. Measured, on `github-release`: four errors
+     * pointing at `extends`, `logLevel`, `vars` and `changelog`, none of them anywhere near the
+     * mistake. The named property fails at the augmentation instead, and says what to add.
+     */
+    type CommandContribution<T extends CommandMetadata, Extra = {}> = string extends ConfigKeyOf<T> ? {
+        __configKeyMustBeALiteral: 'add `as const` to `command` (or to `configKey`)';
+    } : Nest<ConfigKeyOf<T>, ConfigBlock<CommandConfigFromMetadata<T> & Extra>>;
+    /**
+     * One config block as a `.rmanrc` may actually write it: the keys themselves, their `+key` append
+     * forms, and the `vars` that scopes the subtree.
+     *
+     * This is what a hand-written options interface said by extending
+     * `XOptionsKeys, ScopedVars` - clauses every new one had to remember. Derived, it cannot be
+     * forgotten. `ScopedVars` is folded in **before**
+     * `ScopedVars` is added, so no `+vars` is generated: appending to `vars` means nothing, since
+     * objects merge either way.
+     */
+    type ConfigBlock<K> = K & ScopedVars;
+    /** The declared `configKey`, or the first word of `command`. */
+    type ConfigKeyOf<T> = T extends {
+        configKey: infer K extends string;
+    } ? K : T extends {
+        command: infer C extends string;
+    } ? C extends `${infer N} ${string}` ? N : C : never;
+    /** One option's value type: the scalar its `type` denotes, in a list when it is one. */
+    type OptionValue<O> = O extends {
+        array: true;
+    } ? OptionScalar<O>[] : O extends {
+        type: 'array';
+    } ? OptionScalar<O>[] : OptionScalar<O>;
+    /**
+     * The scalar behind a yargs `type`, in decreasing order of how much each says.
+     *
+     * `coerce` first: it is a function that *produces* the value, so its return type is the answer and
+     * whatever `type` claims is a description of the input. `run --parallel` is the case - it takes a
+     * flag, a number or `false` and coerces them into `boolean | number | undefined`, which no `type`
+     * can state. Then `choices`, which narrows a `type` to the values it allows; then the `type`
+     * itself. An option declaring none of the three is `unknown` rather than `any` - a value nothing
+     * described should not silently type-check against everything.
+     */
+    type OptionScalar<O> = O extends {
+        coerce: (...args: never[]) => infer R;
+    } ? R : O extends {
+        choices: readonly (infer C)[];
+    } ? C : O extends {
+        type: 'string';
+    } ? string : O extends {
+        type: 'number' | 'count';
+    } ? number : O extends {
+        type: 'boolean';
+    } ? boolean : unknown;
     /**
      * The `run` block: scripts by name.
      *
@@ -281,14 +733,29 @@ export declare namespace RmanConfig {
      * remap still produces an index signature that claims `vars`.
      */
     type RunConfig = Record<string, RunStepValue | RunStepValue[] | RunScriptOptions>;
-    interface RunScriptOptions extends RunScriptOptionsKeys, WithAppend<RunScriptOptionsKeys>, ScopedVars {
+    interface RunScriptOptions extends RunScriptOptionsKeys, ScopedVars {
     }
+    /**
+     * **Which level a key is read at is not uniform, and it follows what the key decides.**
+     * `RunService` reads `concurrency`, `progress`, `changed` and `changedSince` off the **root
+     * package only** - one scheduler, one answer for the whole batch - so those belong under
+     * `"[/]"`, and a `"[*]"` block declaring them is silently ignored (measured: `concurrency: 1`
+     * under `"[*]"` still ran two packages at once). `logLevel`, `skip`, `if`, `override` and the
+     * step slots are per package. `topo` and `bail` are read **both** ways and mean different things
+     * at each: the root's `topo` picks the sort (topological vs alphabetical), a package's own
+     * decides whether *it* waits for its dependencies; the root's `bail` is the default, a package's
+     * own outranks even an explicit CLI flag.
+     */
     interface RunScriptOptionsKeys {
         concurrency?: number;
         topo?: boolean;
         bail?: boolean;
         progress?: boolean;
         logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+        /** Only run in packages that have changed since their last release - the config twin of
+         *  `--changed`, read off the root. It was read at runtime long before it was declared here, so
+         *  a typed config could not say the thing that already worked. */
+        changed?: boolean;
         changedSince?: string;
         skip?: boolean;
         /** Whether this script runs for a package at all - the small `changed and not private` grammar,
@@ -305,74 +772,130 @@ export declare namespace RmanConfig {
         after?: RunStepValue | RunStepValue[];
         override?: boolean;
     }
-    interface PublishOptions extends PublishOptionsKeys, WithAppend<PublishOptionsKeys>, ScopedVars {
-    }
-    interface PublishOptionsKeys {
-        /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
-         *  keeps working unchanged). A package that only ever wants Docker images (typically also
-         *  `"private": true`, since it's not meant for npm at all) sets `['docker']`; both works too.
-         *  Each target answers "is this version already out there?" against its own registry, so a
-         *  package is never left without one: npm via `npm view`, docker via `docker manifest inspect`.
-         *
-         *  Note this is strictly about *package distribution*. The repository's GitHub Release is not
-         *  a target here - it isn't a place a package ships to, it's the repository's own record that
-         *  a release happened, and it is never opted into: see `githubRelease` and the
-         *  `github-release` command. */
-        target?: PublishTarget | PublishTarget[];
-        docker?: DockerPublishOptions;
-        /** Excludes this package from `publish` entirely (every target), regardless of
-         *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package
-         *  released through some separate, unrelated process. `changelog` also skips it by default
-         *  (see its own `--include-skipped`) - there's little point changelogging something that's
-         *  never actually released. Independent of `version`, which never consults this at all - a
-         *  package can still be meaningfully versioned without ever being published. */
-        skip?: boolean;
-    }
-    type PublishTarget = 'npm' | 'docker';
-    /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
-     *  docker` errors clearly on a package that opts in here but leaves this out. */
-    interface DockerPublishOptions extends DockerPublishOptionsKeys, WithAppend<DockerPublishOptionsKeys>, ScopedVars {
-    }
-    interface DockerPublishOptionsKeys {
-        /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
-         *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
-         *  verbatim. */
-        image: string;
-        /** Relative to the package's own directory. Default `"Dockerfile"`. */
-        dockerfile?: string;
-        /** Default `["linux/amd64"]`. */
-        platforms?: string[];
-        /** Build `cwd` override, relative to the repository root - only needed when the Dockerfile's
-         *  own `COPY`/`ADD` paths expect something other than the package's own directory (rare). */
-        cwd?: string;
-        /** Named `docker buildx build --build-context <name>=<path>` entries, keyed by name - each
-         *  path is relative to the package's own directory (or absolute). */
-        buildContexts?: Record<string, string>;
-        /** `docker buildx build --build-arg <name>=<value>` entries - a value of exactly `"$NAME"`
-         *  expands to `process.env.NAME` at build time (e.g. to pass a CI secret through). */
-        buildArgs?: Record<string, string>;
-        /** A file (relative to the package's own directory) whose contents become the DockerHub repo's
-         *  full description, if present. Default `"DOCKER_README.md"`. */
-        readme?: string;
-    }
-    /** Entirely optional - `github-release` needs no configuration at all, since every required fact
-     *  (which tag, which repository, what the notes say) already has a sensible source. Nothing here
-     *  decides *whether* a release is cut: a release records that the repository shipped, so it is
-     *  always cut, and these are only details about how. */
-    interface GithubReleaseOptions extends GithubReleaseOptionsKeys, WithAppend<GithubReleaseOptionsKeys>, ScopedVars {
-    }
-    interface GithubReleaseOptionsKeys {
-        /** Files to attach to the release, as glob patterns relative to the package's own directory
-         *  (e.g. `["dist/*.tar.gz"]`). Read from **every** package, since one release covers the whole
-         *  source tree. A release with no assets at all is still perfectly valid - it records that the
-         *  version shipped, which is all a deploy-elsewhere package needs. */
-        assets?: string[];
-        /** `owner/repo`. Default: parsed from the `origin` remote's URL. Root-level only. */
-        repository?: string;
-        /** Create the release as an unpublished draft. Default `false`. Root-level only. */
-        draft?: boolean;
-        /** Default: whether the version being released is itself a prerelease by the root's own version
-         *  scheme (`1.3.0-beta.0` under semver) - see `VersionScheme.isPrerelease`. Root-level only. */
-        prerelease?: boolean;
-    }
 }
+/**
+ * Registers a command and hands the register function straight back.
+ *
+ * **It returns the function, not the command's config, and that is the point.** The function has
+ * not run yet - it runs during init, once there is a `Repository` - so at registration time no
+ * config object exists to return. Declaring one anyway is what made the old body
+ * (`return def['config']`) uncompilable: `def` is a function, and `config` belongs to what it
+ * *returns*.
+ *
+ * Nothing is lost by being honest, because the metadata type rides along on the return type:
+ * `ReturnType<typeof someCommand>` is the `CommandMetadata`, and `CommandConfigFromMetadata` maps
+ * it to the config object the command contributes. A phantom property carrying the config type was
+ * tried and is unnecessary for exactly this reason - and it would not have survived being stored in
+ * `commandRegistry`, whose element type erases it.
+ *
+ * **`M` is inferred from the metadata rather than from the function, so that the same position can
+ * check it.** With the plainer `<T extends CommandRegisterFunction>(def: T)`, `T` is inferred from
+ * the literal itself, so the constraint is a subtype check - and a subtype check does no
+ * excess-property checking. Measured: `anotherBogusTopLevelKey: true` and a `totallyBogusKey`
+ * inside an option both compiled silently, which is how `cliName` and `examples` went unnoticed in
+ * `version.command.ts`. `M & ValidMeta<M>` keeps the bare `M` as the inference site and puts the
+ * check beside it, so a misspelled key now errors on its own line and names itself.
+ *
+ * **A command's `command` string needs `as const`** for the config key to be derivable from it
+ * (`'version [bump]' as const` -> `'version'`). `type: 'string'` survives inference on its own,
+ * since `yargs.Options['type']` is a union of literals and a union suppresses widening; `command`
+ * is a plain `string`, so it widens without the assertion. Spelling it `` `${string}` `` does not
+ * help - measured; that trick only applies where the constraint sits on the generic parameter.
+ */
+export declare function registerCommand<M extends RmanConfig.CommandMetadata>(def: (app: RmanApplication) => M & ValidMeta<M>): (app: RmanApplication) => M;
+/**
+ * The same declaration, **without** the registration - for a command that must exist only when
+ * something asks for it.
+ *
+ * That is exactly a contributed command's situation: `commandRegistry` is a module-level array
+ * walked by every `runCli`, so a package pushing onto it would give its commands to repositories
+ * that never named it - the module is imported as soon as anything imports the package. A package
+ * puts the function in its config's `commands` instead, and `cli.ts` calls it once the repository
+ * exists.
+ *
+ * **Why a factory rather than the metadata itself**: the config is resolved *inside*
+ * `Repository.create`, before the packages are known (plugins are what find them), so
+ * `app.repository` throws at that point. The function is stored unrun and called later, in
+ * `cli.ts`, where the built-ins' own factories run.
+ *
+ * Everything `registerCommand` documents about inference - `M & ValidMeta<M>`, the `as const` on
+ * `command`, the metadata riding on the return type - applies here unchanged; the two differ in one
+ * line.
+ */
+export declare function declareCommand<M extends RmanConfig.CommandMetadata>(def: (app: RmanApplication) => M & ValidMeta<M>): (app: RmanApplication) => M;
+/**
+ * Only the options a `.rmanrc` may actually set. `target: 'cli'` says the flag exists on the
+ * command line and nowhere else - `--interactive`, `--yes`, `--show` - and putting those in the
+ * config type would invite writing them where nothing reads them.
+ */
+type ConfigOnly<C> = {
+    [K in keyof C as C[K] extends {
+        target: 'config' | 'both';
+    } ? K : never]: C[K];
+};
+/**
+ * A dotted path into nested objects: `'run.build'` + shape -> `{ run?: { build?: shape } }`.
+ *
+ * **Optional at every level**, and that is not a detail: a required key would make the whole
+ * contribution mandatory, so `defineConfig({})` stopped compiling with
+ * `Property 'version' is missing in type '{}'` (measured). A `.rmanrc` may say nothing about a
+ * command, and usually does.
+ */
+type Nest<P extends string, V> = P extends `${infer H}.${infer R}` ? {
+    [K in H]?: Nest<R, V>;
+} : {
+    [K in P]?: V;
+};
+/** Keys `T` declares that `Shape` does not know about. */
+type Excess<T, Shape> = Exclude<keyof T, keyof Shape>;
+/**
+ * `T` itself when it declares nothing extra; otherwise a shape it cannot satisfy, so the assignment
+ * fails on the offending key and says which one it is.
+ *
+ * The failure payload is an **object** rather than a tuple or a string literal. Intersecting a
+ * property's real type with an object leaves a real object type, so the error reads `Property
+ * '__unknownKey' is missing`; with a string or a tuple the intersection collapses to `never` and the
+ * message stops naming anything.
+ */
+type Exact<T, Shape> = [Excess<T, Shape>] extends [never] ? T : {
+    [K in Excess<T, Shape>]: {
+        __unknownKey: K;
+    };
+};
+/** Every option checked against `CommandOption`, so a typo inside one is caught too. */
+type ValidConfig<C> = {
+    [K in keyof C]: Exact<C[K], RmanConfig.CommandOption>;
+};
+type ValidMeta<M> = Exact<M, RmanConfig.CommandMetadata> & {
+    config?: M extends {
+        config: infer C;
+    } ? ValidConfig<C> : unknown;
+    positionals?: ValidPositionals<M>;
+};
+/** A positional the `command` string never declared fails on its own key, naming the string it was
+ *  checked against. */
+type ValidPositionals<M> = M extends {
+    command: infer C extends string;
+    positionals: infer P;
+} ? {
+    [K in keyof P]: K extends RmanConfig.PositionalsOf<C> ? P[K] : {
+        __notDeclaredIn: C;
+    };
+} : unknown;
+/** A trailing `..`/`...` is yargs' variadic marker, not part of the positional's name. */
+type StripDots<S extends string> = S extends `${infer N}...` ? N : S extends `${infer N}..` ? N : S;
+/**
+ * The names a command string declares as **required** positionals - `'run <script> [args..]'` is
+ * `'script'` alone. `ArgsOf`'s only caller, which is why it is private: whether a positional is
+ * required is `ArgsOf`'s question, while `PositionalsOf` answers the different one `ValidPositionals`
+ * asks - which names the string declares at all.
+ *
+ * Unlike `PositionalsOf` it recurses through **one** branch, so a `[bracketed]` name is never
+ * emitted; the recursion still steps past one, since `${string}` matches whatever precedes the next
+ * `<`.
+ */
+type RequiredPositionalsOf<C extends string> = C extends `${string}<${infer N}>${infer Rest}` ? StripDots<N> | RequiredPositionalsOf<Rest> : never;
+/** A variadic positional (`[command..]`) collects a list; every other one is a single value. The
+ *  command string is the only place that says which, since it is what yargs parses. */
+type PositionalValue<Cmd extends string, N extends string> = Cmd extends `${string}${'<' | '['}${N}..${string}` ? string[] : string;
+export {};