rman 1.0.12 → 1.1.1

package/core/merge-config.js

@@ -0,0 +1,146 @@
+/** The prefix that turns a key into an append instead of a replacement: `+before` adds to whatever
+ *  `before` already resolved to, rather than taking its place. */
+export const APPEND_PREFIX = '+';
+/**
+ * Keys that **append whether or not you ask** - `+plugins` is accepted and means nothing extra.
+ *
+ * `plugins` is the whole list because it is the one key where replacing is never what anyone meant:
+ * every other setting has a value a closer layer can sensibly overrule, while a plugin *adds
+ * commands and seams*, and a repository naming one has no wish to lose the ones its shared config
+ * brought. Replacing was the silent failure - `extends`-ing a toolchain config and then adding a
+ * plugin of your own dropped the toolchain's, and what you noticed was `Unknown argument: publish`.
+ *
+ * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
+ * layer, which is only acceptable where the value is a set of contributions rather than a decision.
+ */
+export const ALWAYS_APPEND = ['plugins'];
+/** `"+before"` -> `"before"`, or `undefined` for a key that isn't an append. */
+export function appendTarget(key) {
+    return key.length > APPEND_PREFIX.length && key.startsWith(APPEND_PREFIX)
+        ? key.slice(APPEND_PREFIX.length)
+        : undefined;
+}
+/**
+ * Merges `source` onto `target` in place, the way every layer of rman config is combined - a
+ * directory's own file forms, the directory chain, `"[selector]"` blocks, and an `extends` base.
+ * One implementation for all of them, so they cannot disagree about what an append means.
+ *
+ * Plain keys replace, and nested objects merge recursively, as a deep merge always has. What this
+ * adds is `+key`:
+ *
+ * ```yaml
+ * # the root says          before: "rm ./build"
+ * # a package adds        +before: "rm ./cache"
+ * # it resolves to         before: ["rm ./build", "rm ./cache"]
+ * ```
+ *
+ * Appending is the half a shared config can't live without: a base that declares
+ * `before: ["rm ./build"]` otherwise forces every repository wanting one more step to restate the
+ * whole list - which is a copy of the base, silently frozen at the version it was copied from.
+ *
+ * A scalar is promoted to a list on the way, so neither side has to be written as an array. With
+ * nothing inherited, `+key` simply produces a one-element list.
+ *
+ * On a value that isn't a list, the prefix is **ignored** rather than an error, because there the
+ * two spellings already mean the same thing: objects merge whether or not you asked them to, and a
+ * scalar has nothing to append to, so `+key` behaves exactly as `key` would. Nothing is silently
+ * dropped - the value still lands.
+ *
+ * `key` and `+key` in the same object are both honored, in that order: the replacement happens
+ * first, then the append lands on top of it.
+ */
+export function mergeConfig(target, source) {
+    // Plain keys first, so a `+key` alongside its own `key` appends to that replacement rather than
+    // to whatever the previous layer had.
+    for (const [key, value] of Object.entries(source)) {
+        if (appendTarget(key))
+            continue;
+        /** `plugins`: additive at every layer, so the closer one adds rather than takes over. */
+        if (ALWAYS_APPEND.includes(key)) {
+            appendList(target, key, value);
+            continue;
+        }
+        assignMerged(target, key, value);
+    }
+    for (const [key, value] of Object.entries(source)) {
+        const plain = appendTarget(key);
+        if (!plain)
+            continue;
+        // An object merges either way, so the prefix asks for nothing extra - resolve it now and let
+        // the two spellings coincide.
+        if (isPlainObject(value) || isPlainObject(target[plain])) {
+            assignMerged(target, plain, value);
+            continue;
+        }
+        if (plain in target) {
+            appendList(target, plain, value);
+            continue;
+        }
+        /** Nothing to append to *yet*. Kept as an append rather than collapsed into the plain key,
+         *  because the layer that provides it may still be coming: a directory's own file forms are
+         *  merged into an empty object long before the selector blocks and parent directories they
+         *  append to are. Collapsing here lost both of those - measured. `finalizeConfig` turns
+         *  whatever is still outstanding at the end into a plain list. */
+        target[key] = [...toList(target[key] ?? []), ...toList(value)];
+    }
+    return target;
+}
+/**
+ * Turns any `+key` still outstanding into its plain key, as a list - the "nothing was inherited"
+ * case, where an append simply is the whole value.
+ *
+ * Called once on a fully resolved config, and only there: until then an outstanding append may
+ * still find the layer it belongs to, and a config handed to a command must carry no `+key` at all
+ * or every reader would have to know about them.
+ */
+export function finalizeConfig(config) {
+    if (Array.isArray(config))
+        return config.map(finalizeConfig);
+    if (!isPlainObject(config))
+        return config;
+    const result = {};
+    for (const [key, value] of Object.entries(config)) {
+        const plain = appendTarget(key);
+        if (!plain) {
+            result[key] = finalizeConfig(value);
+            continue;
+        }
+        const pending = finalizeConfig(value);
+        result[plain] = plain in result ? [...toList(result[plain]), ...toList(pending)] : toList(pending);
+    }
+    return result;
+}
+function assignMerged(target, key, value) {
+    if (isPlainObject(value)) {
+        if (!isPlainObject(target[key]))
+            target[key] = {};
+        mergeConfig(target[key], value);
+        return;
+    }
+    target[key] = Array.isArray(value) ? [...value] : value;
+}
+/**
+ * Appends `value` to `target[key]`, de-duplicating **only** an `ALWAYS_APPEND` key.
+ *
+ * That asymmetry is the point. `plugins` appends without being asked, so a repository and the config
+ * it extends both naming `'rman-node'` is the ordinary case rather than a mistake, and the list is
+ * also what `rman config` prints. An explicit `+before`, by contrast, was *written* - repeating a
+ * step that is already there is a strange thing to ask for, but it is what was asked for, and
+ * silently collapsing it would make one layer's list depend on another's contents.
+ *
+ * By identity (`===`), which covers a string by value and a plugin object by reference; two
+ * *different* objects claiming one plugin name are caught where it counts, at registration - see
+ * `loadPlugins`.
+ */
+function appendList(target, key, value) {
+    const merged = [...toList(target[key] ?? []), ...toList(value)];
+    target[key] = ALWAYS_APPEND.includes(key) ? merged.filter((entry, at) => merged.indexOf(entry) === at) : merged;
+}
+function toList(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/** A config object, as opposed to an array or anything with its own prototype - only the former
+ *  merges key by key. */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/core/package.d.ts

@@ -1,17 +1,83 @@
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { Manifest } from './manifest.js';
+import type { Repository } from './repository.js';
+import { type VersionScheme } from './version-scheme.js';
 export declare class Package {
     readonly dirname: string;
-    private _json;
-    dependencies: string[];
-    /** Effective rman config for this package, cascaded from the repository root. */
+    /**
+     * This package's identity, read through whichever `ManifestProvider` recognizes its directory.
+     *
+     * There is no `json` here any more, and that is the point: `package.json` is npm's answer to
+     * "where is a package's name and version written", not rman's. `manifest.raw` is still the whole
+     * document for a command that knows its own ecosystem - `rman-node` reads `scripts` and
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest: Manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
+     */
+    dependencies: Package[];
+    /** Effective rman config for this package, cascaded from the repository root, with every
+     *  `${{ ... }}` expression already evaluated. */
     config: RmanConfig;
+    /**
+     * The repository this package belongs to - so anything holding a package can reach the whole
+     * picture (its siblings, the root's config, git) without being handed it separately.
+     *
+     * Assigned by `Repository.create` rather than taken as a constructor argument, and it has to be:
+     * `Repository extends Package`, so a repository constructing itself runs this constructor before
+     * it exists to be passed in. A repository's own is itself.
+     */
+    repository: Repository;
+    /**
+     * The package whose directory contains this one - the repository root for an ordinary member, and
+     * a genuine enclosing package for one nested inside another (which `Repository.currentPackage`
+     * already has to reason about). `undefined` for the root itself, which nothing contains.
+     */
+    parent?: Package;
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme: VersionScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  changed (a commit's path list). Empty when no provider recognized this directory. */
+    manifestFileName: string;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one read by `rman-node`, from the
+     * `ManifestProvider.name` that claimed the directory. Empty when no provider did.
+     *
+     * The escape hatch for code that legitimately knows one technology: `if (pkg.provider === 'node')`
+     * before reaching into `manifest.raw` for something only npm has. Per *package*, not per
+     * repository, because `Manifest.read` asks per directory - a polyglot monorepo can hold a `node`
+     * package beside a `cargo` one, and a command sweeping over `getPackages()` has to be able to
+     * tell.
+     *
+     * Not a union type on purpose: the set of ecosystems is whatever the repository's `plugins`
+     * contribute, so narrowing it here would mean the core listing plugins it cannot know about.
+     */
+    provider: string;
     constructor(dirname: string);
     get basename(): string;
     get name(): string;
     get version(): string;
-    get json(): any;
-    get jsonFileName(): string;
     get isPrivate(): boolean;
-    reloadJson(): any;
-    writeJson(): void;
+    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
+     *  package to agree with the file again. */
+    reloadManifest(): Manifest;
+    /** Writes the current manifest back through its provider. */
+    writeManifest(): void;
 }

package/core/package.js

@@ -1,44 +1,106 @@
-import fs from 'fs';
 import path from 'path';
+import { Manifest } from './manifest.js';
+import { semverScheme } from './version-scheme.js';
 export class Package {
     dirname;
-    _json;
+    /**
+     * This package's identity, read through whichever `ManifestProvider` recognizes its directory.
+     *
+     * There is no `json` here any more, and that is the point: `package.json` is npm's answer to
+     * "where is a package's name and version written", not rman's. `manifest.raw` is still the whole
+     * document for a command that knows its own ecosystem - `rman-node` reads `scripts` and
+     * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
+     */
+    manifest;
+    /**
+     * In-repo packages this one depends on - **the full transitive closure**, not just its direct
+     * dependencies (see `Repository._updateDependencies`).
+     *
+     * References, not names: a name is only an identifier if the ecosystem guarantees uniqueness,
+     * which npm does and others do not - Go identifies a module by import path, and nothing stops a
+     * repository from holding two packages whose short names collide. A `Package` is unambiguous
+     * whatever the ecosystem, and comparing by identity removes a lookup from every consumer.
+     */
     dependencies = [];
-    /** Effective rman config for this package, cascaded from the repository root. */
+    /** Effective rman config for this package, cascaded from the repository root, with every
+     *  `${{ ... }}` expression already evaluated. */
     config = {};
+    /**
+     * The repository this package belongs to - so anything holding a package can reach the whole
+     * picture (its siblings, the root's config, git) without being handed it separately.
+     *
+     * Assigned by `Repository.create` rather than taken as a constructor argument, and it has to be:
+     * `Repository extends Package`, so a repository constructing itself runs this constructor before
+     * it exists to be passed in. A repository's own is itself.
+     */
+    repository;
+    /**
+     * The package whose directory contains this one - the repository root for an ordinary member, and
+     * a genuine enclosing package for one nested inside another (which `Repository.currentPackage`
+     * already has to reason about). `undefined` for the root itself, which nothing contains.
+     */
+    parent;
+    /**
+     * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
+     *
+     * Comes from the same provider that read the manifest, because the ecosystem that decides where
+     * a version is written is the one that decides how it is numbered - a `pyproject.toml` read with
+     * semver's arithmetic would be a pair that never occurs in reality.
+     *
+     * Defaults to semver, so this seam existing changes nothing. **A group must not mix schemes** -
+     * a group is one version line, and comparing across schemes is meaningless; `assertOneScheme`
+     * refuses it rather than acting on whatever falls out.
+     */
+    versionScheme = semverScheme;
+    /** The file the manifest was read from, absolute - for a command that has to say which file it
+     *  changed (a commit's path list). Empty when no provider recognized this directory. */
+    manifestFileName;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one read by `rman-node`, from the
+     * `ManifestProvider.name` that claimed the directory. Empty when no provider did.
+     *
+     * The escape hatch for code that legitimately knows one technology: `if (pkg.provider === 'node')`
+     * before reaching into `manifest.raw` for something only npm has. Per *package*, not per
+     * repository, because `Manifest.read` asks per directory - a polyglot monorepo can hold a `node`
+     * package beside a `cargo` one, and a command sweeping over `getPackages()` has to be able to
+     * tell.
+     *
+     * Not a union type on purpose: the set of ecosystems is whatever the repository's `plugins`
+     * contribute, so narrowing it here would mean the core listing plugins it cannot know about.
+     */
+    provider;
     constructor(dirname) {
         this.dirname = dirname;
-        this.reloadJson();
+        const { manifest, versionScheme, fileName, provider } = Manifest.read(dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(dirname, fileName) : '';
+        this.provider = provider;
     }
     get basename() {
         return path.basename(this.dirname);
     }
     get name() {
-        return this._json.name;
+        return this.manifest.name;
     }
     get version() {
-        return this._json.version;
-    }
-    get json() {
-        return this._json;
-    }
-    get jsonFileName() {
-        return path.join(this.dirname, 'package.json');
+        return this.manifest.version;
     }
     get isPrivate() {
-        return !!this._json.private;
+        return !!this.manifest.private;
     }
-    reloadJson() {
-        const f = this.jsonFileName;
-        if (!fs.existsSync(f)) {
-            throw new Error(`Package.json not found at ${f}`);
-        }
-        this._json = JSON.parse(fs.readFileSync(f, 'utf-8'));
-        return this._json;
+    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
+     *  package to agree with the file again. */
+    reloadManifest() {
+        const { manifest, versionScheme, fileName, provider } = Manifest.read(this.dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(this.dirname, fileName) : '';
+        this.provider = provider;
+        return this.manifest;
     }
-    writeJson() {
-        const f = this.jsonFileName;
-        const data = JSON.stringify(this._json, undefined, 2);
-        fs.writeFileSync(f, data, 'utf-8');
+    /** Writes the current manifest back through its provider. */
+    writeManifest() {
+        Manifest.write(this.dirname, this.manifest);
     }
 }

package/core/plugin.d.ts

@@ -0,0 +1,112 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import { RunService } from '../services/run.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
+import { BinPath } from '../utils/bin-path.js';
+import type { CustomCommand, LoadedCommand } from './custom-command.js';
+import { type ManifestProvider } from './manifest.js';
+import { Workspace } from './workspace.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export declare const PLUGINS_KEY = "plugins";
+/**
+ * What a plugin package hands rman.
+ *
+ * An object rather than a bare array of commands, for the reason `CommandContext` is one: a plugin
+ * will eventually contribute more than commands (config defaults, publish targets, a package
+ * provider for a non-Node repository), and nothing written against this should have to change when
+ * it does.
+ */
+export interface RmanPlugin {
+    /** For error messages and `--help` grouping. Conventionally the package's own name. */
+    name: string;
+    commands?: CustomCommand[];
+    /**
+     * Where `run` can find a package's steps besides its `.rmanrc` - `rman-node` contributes
+     * `package.json#scripts` here, with npm's `pre`/`post` lifecycle.
+     *
+     * Registered in `plugins` declaration order, and only for plugins the repository actually named:
+     * what a script resolves to is then a function of the config rather than of what happened to be
+     * imported.
+     */
+    runSteps?: RunService.StepSource;
+    /**
+     * How this ecosystem's repositories are laid out - `rman-node` reads `workspaces` from the root
+     * `package.json` here.
+     *
+     * Loaded **before any package is known**, since this is what finds them: `Repository.create`
+     * reads the root config, loads the plugins it names, and only then asks. A repository naming no
+     * plugin therefore has no packages beyond itself.
+     */
+    workspace?: Workspace.Provider;
+    /**
+     * Where a package's name and version are written, and how it is numbered - `rman-node`
+     * contributes `package.json` here.
+     *
+     * Registered before any package is constructed, since `Package` reads through it. A repository
+     * naming no plugin therefore gets packages named after their own directories at version
+     * `0.0.0` - see `readManifest`.
+     */
+    manifest?: ManifestProvider;
+    /**
+     * How a release is planned - which packages have changed since their last release and what
+     * version each gets. `rman-node` contributes `NodeVersionPlanService` here.
+     *
+     * **`VersionPlanService` is abstract, so `version`/`changed` do not work without one** (they fail
+     * naming this key). Unlike `manifest` and `workspace`, which degrade to honest defaults, a plan is
+     * either right or it quietly releases the wrong set of packages - see `VersionPlanService`.
+     *
+     * Consulted when a command asks, not at load time, so this is declared and nothing else has to
+     * happen as the plugin's module is imported.
+     */
+    versionPlanner?: VersionPlanService;
+    /**
+     * Where this ecosystem keeps a repository's locally installed executables - `rman-node`
+     * contributes npm's `node_modules/.bin`, walked up the directory chain.
+     *
+     * Prepended to PATH for every `exec`/`runBin` child process, so a command an author wrote runs
+     * against the repository's own pinned tools. **Every plugin's entries are used**, not just the
+     * first - see `BinPath`.
+     */
+    binPaths?: BinPath.Provider;
+}
+/**
+ * Identity helper for authoring a plugin with full type-checking - the `defineConfig`/
+ * `defineCommand` pattern again, for the same reason. Returns `plugin` unchanged.
+ *
+ * **A plugin package's entry point exports a *config*, not this**, so that a package is an
+ * `.rmanrc` like any other and can carry a second plugin later without changing shape:
+ *
+ * ```js
+ * // rman-node's entry point
+ * import { defineConfig, definePlugin } from 'rman';
+ * import publishCommand from './commands/publish.js';
+ *
+ * export const nodePlugin = definePlugin({ name: 'rman-node', commands: [publishCommand] });
+ * export default defineConfig({ plugins: [nodePlugin] });
+ * ```
+ *
+ * **A module exporting the plugin itself is refused**, with a message saying so. Accepting both
+ * would mean telling a plugin from a config at runtime, and `name` is a key either may have - the
+ * test would be a guess, and guessing "plugin" registers nothing while reporting success.
+ */
+export declare function definePlugin(plugin: RmanPlugin): RmanPlugin;
+/**
+ * Loads every plugin the repository's `.rmanrc "plugins"` declares, in declaration order.
+ *
+ * This is what lets a *package* contribute commands. `.rman/*.mjs` covers one repository's own
+ * commands (see `loadCustomCommands`); a plugin covers a whole class of repository - `rman-node`
+ * carrying everything that only means something because the repository is a Node one, so rman's
+ * core does not have to.
+ *
+ * An entry is a package name, a path, or a plugin object - and a named package's entry point
+ * exports a **config**, whose own `plugins` are then loaded the same way (see `loadInto`).
+ *
+ * Names resolve relative to the repository root's own `node_modules`, the way `extends` resolves -
+ * a plugin is the repository's dependency, not rman's.
+ *
+ * **A plugin that cannot be loaded throws**, unlike a broken `.rman/*.mjs` file, which is warned
+ * about and skipped. The two differ because the consequence does: a skipped local command affects
+ * only itself, while a missing plugin silently removes commands the repository is built around -
+ * `rman publish` would simply not exist, and "not a known command" sends the reader looking in the
+ * wrong place entirely.
+ */
+export declare function loadPlugins(rootDir: string, rootConfig: RmanConfig): Promise<LoadedCommand[]>;

package/core/plugin.js

@@ -0,0 +1,189 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RunService } from '../services/run.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
+import { BinPath } from '../utils/bin-path.js';
+import { Manifest } from './manifest.js';
+import { resolveConfigTarget } from './resolve-target.js';
+import { Workspace } from './workspace.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export const PLUGINS_KEY = 'plugins';
+/**
+ * Identity helper for authoring a plugin with full type-checking - the `defineConfig`/
+ * `defineCommand` pattern again, for the same reason. Returns `plugin` unchanged.
+ *
+ * **A plugin package's entry point exports a *config*, not this**, so that a package is an
+ * `.rmanrc` like any other and can carry a second plugin later without changing shape:
+ *
+ * ```js
+ * // rman-node's entry point
+ * import { defineConfig, definePlugin } from 'rman';
+ * import publishCommand from './commands/publish.js';
+ *
+ * export const nodePlugin = definePlugin({ name: 'rman-node', commands: [publishCommand] });
+ * export default defineConfig({ plugins: [nodePlugin] });
+ * ```
+ *
+ * **A module exporting the plugin itself is refused**, with a message saying so. Accepting both
+ * would mean telling a plugin from a config at runtime, and `name` is a key either may have - the
+ * test would be a guess, and guessing "plugin" registers nothing while reporting success.
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}
+/**
+ * Loads every plugin the repository's `.rmanrc "plugins"` declares, in declaration order.
+ *
+ * This is what lets a *package* contribute commands. `.rman/*.mjs` covers one repository's own
+ * commands (see `loadCustomCommands`); a plugin covers a whole class of repository - `rman-node`
+ * carrying everything that only means something because the repository is a Node one, so rman's
+ * core does not have to.
+ *
+ * An entry is a package name, a path, or a plugin object - and a named package's entry point
+ * exports a **config**, whose own `plugins` are then loaded the same way (see `loadInto`).
+ *
+ * Names resolve relative to the repository root's own `node_modules`, the way `extends` resolves -
+ * a plugin is the repository's dependency, not rman's.
+ *
+ * **A plugin that cannot be loaded throws**, unlike a broken `.rman/*.mjs` file, which is warned
+ * about and skipped. The two differ because the consequence does: a skipped local command affects
+ * only itself, while a missing plugin silently removes commands the repository is built around -
+ * `rman publish` would simply not exist, and "not a known command" sends the reader looking in the
+ * wrong place entirely.
+ */
+export async function loadPlugins(rootDir, rootConfig) {
+    const commands = [];
+    /** Resolved against the repository root, where the `.rmanrc` declaring them lives. */
+    await loadInto(commands, rootConfig, path.join(rootDir, '.rmanrc'), { files: new Set(), names: new Set() });
+    return commands;
+}
+/**
+ * One config's `plugins`, in declaration order.
+ *
+ * Recursive because a plugin package **exports a config**, not a plugin: `rman-node`'s entry point
+ * is `export default defineConfig({ plugins: [ ... ] })`, so resolving a name lands on another
+ * config whose own `plugins` are the ones to register. That also means a plugin package can name a
+ * plugin of its own and it simply works.
+ *
+ * `from` is the file the entries are resolved against, and it changes as it descends - an entry in
+ * `rman-node`'s config resolves through *its* `node_modules`, not the repository's, the same rule
+ * `extends` follows.
+ *
+ * **Only `plugins` is read out of an imported config.** Its other keys are not merged: a config's
+ * way into a repository is `extends`, which is the key that says "merge this underneath mine".
+ * Reading them here would make a plugin able to configure a repository by being installed.
+ */
+async function loadInto(commands, config, from, seen) {
+    const declared = config?.[PLUGINS_KEY];
+    if (declared === undefined)
+        return;
+    for (const entry of Array.isArray(declared) ? declared : [declared]) {
+        /**
+         * The object form: a JS config handing a plugin over directly, and what a plugin package's own
+         * config holds. Nothing to resolve or import.
+         *
+         * An object here **is** a plugin - it is not guessed at. The one thing checked is that it has a
+         * `name`, because everything downstream (the registration guard, `--help` grouping, every error
+         * message) is keyed by it.
+         */
+        if (isPlainObject(entry)) {
+            if (typeof entry.name !== 'string' || !entry.name) {
+                throw new Error(`A plugin object in "${PLUGINS_KEY}" has no "name" - every other message is keyed by it.`);
+            }
+            register(commands, entry, entry.name, from, seen);
+            continue;
+        }
+        if (typeof entry !== 'string' || !entry.trim()) {
+            throw new Error(`"${PLUGINS_KEY}" takes a package name, a path, or a plugin object - not ${JSON.stringify(entry)}`);
+        }
+        const file = resolveConfigTarget(entry, from, PLUGINS_KEY);
+        /** A config naming itself, or two naming each other, would otherwise recurse forever. Keyed by
+         *  resolved file, so the same package reached by two names is still loaded once. */
+        if (seen.files.has(file))
+            continue;
+        seen.files.add(file);
+        const mod = await import(pathToFileURL(file).href);
+        const exported = mod?.default ?? mod?.plugin;
+        /**
+         * **A module exports one thing: an rman config.** Not a plugin, and not either-or.
+         *
+         * Accepting both meant having to *tell them apart*, and there is no reliable way to - `name` is
+         * a key a config may have as well, so the test came down to "a name plus at least one of the
+         * things a plugin contributes", which is a guess. Guess wrong in the direction of "plugin" and
+         * nothing is registered while the command reports success, which is the worst outcome on offer.
+         * One shape, one rule, one error.
+         */
+        if (!isPlainObject(exported) || exported.plugins === undefined) {
+            throw new Error(`Plugin "${entry}" must export an rman config - \`export default defineConfig({ plugins: [ ... ] })\`. ` +
+                describeExport(exported));
+        }
+        await loadInto(commands, exported, file, seen);
+    }
+}
+/**
+ * Everything a plugin contributes, in one place - so the object and the imported forms cannot drift
+ * apart in what they support.
+ *
+ * **One registration per plugin name.** `plugins` appends at every layer now, so the same plugin
+ * arriving twice is an ordinary consequence of `extends` rather than a mistake to report - and
+ * registering it twice would define its commands twice, which yargs does not survive. The config
+ * merge already drops an identical entry; this catches the rest, including two objects claiming one
+ * name and an object that duplicates a named package.
+ */
+function register(commands, plugin, label, specifier, seen) {
+    if (seen.names.has(plugin.name))
+        return;
+    seen.names.add(plugin.name);
+    if (plugin.runSteps)
+        RunService.addStepSource(plugin.runSteps);
+    if (plugin.manifest)
+        Manifest.addProvider(plugin.manifest);
+    if (plugin.workspace)
+        Workspace.addProvider(plugin.workspace);
+    if (plugin.binPaths)
+        BinPath.addProvider(plugin.binPaths);
+    if (plugin.versionPlanner)
+        VersionPlanService.setPlanner(plugin.versionPlanner);
+    for (const command of plugin.commands ?? []) {
+        commands.push(toLoadedCommand(command, label || specifier, specifier));
+    }
+}
+/**
+ * The second half of the error above - what the module *did* export, so the author can see how far
+ * off it was.
+ *
+ * It recognizes a plugin object only to **say so in a message**. That is the one safe use for this
+ * shape test: it decides nothing, so a wrong guess costs a slightly less helpful sentence rather
+ * than a plugin that silently does not load.
+ */
+function describeExport(exported) {
+    if (exported === undefined)
+        return 'It has no default export.';
+    if (!isPlainObject(exported))
+        return `Its default export is a ${typeof exported}.`;
+    const looksLikePlugin = PLUGIN_SEAMS.some(seam => exported[seam] !== undefined);
+    return looksLikePlugin
+        ? `Its default export looks like the plugin itself - put it in a config's "${PLUGINS_KEY}".`
+        : `Its default export has no "${PLUGINS_KEY}".`;
+}
+const PLUGIN_SEAMS = ['commands', 'runSteps', 'workspace', 'manifest', 'versionPlanner', 'binPaths'];
+/** A config object, as opposed to an array or anything with its own prototype. */
+function isPlainObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** A plugin's command, checked the same way a `.rman/*.mjs` one is - the name it answers to comes
+ *  from its own `command` string, since a plugin has no file name to fall back on. */
+function toLoadedCommand(command, pluginName, specifier) {
+    const declared = command?.command?.trim();
+    if (!declared) {
+        throw new Error(`Plugin "${pluginName}" has a command with no "command" name - it cannot be registered.`);
+    }
+    if (typeof command.handler !== 'function') {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "handler" function.`);
+    }
+    if (typeof command.describe !== 'string' || !command.describe) {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "describe" - \`rman --help\` would have ` +
+            `nothing to list it by.`);
+    }
+    return { ...command, command: declared, name: declared.split(/\s+/)[0], file: specifier };
+}