rman 1.3.0 → 2.0.0-beta.2

package/core/package.js

@@ -4,11 +4,11 @@ import { semverScheme } from './version-scheme.js';
 export class Package {
     dirname;
     /**
-     * This package's identity, read through whichever `ManifestProvider` recognizes its directory.
+     * This package's identity, read through whichever `Plugin`'s manifest members 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
+     * document for a command that knows its own ecosystem - the `node` built-in reads `scripts` and
      * `publishConfig` off it - but the core only ever touches `name`, `version` and `private`.
      */
     manifest;
@@ -22,24 +22,30 @@ export class Package {
      * 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, 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.
+     * Effective rman config for this package, cascaded from the repository root, with every
+     * `${{ ... }}` expression already evaluated.
      *
-     * 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.
+     * **`ResolvedConfig`, not `RmanConfig`, and that is the whole two-view split in one line.**
+     * `RmanConfig` is what an *author* writes, where a value may be a function; this is what a
+     * *reader* gets, where it has already been called. Derived from the one the author writes, so
+     * there is no second type to keep in step - see `Resolved`.
      */
-    repository;
+    config = {};
     /**
-     * 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.
+     * The packages whose directories sit directly inside this one - **the tree edge**, in the order
+     * the platform that claimed this directory gave them.
+     *
+     * This is the shape discovery actually has, and it used to be flattened away: a provider was
+     * asked once at the repository root and returned one list, so a package nested inside another was
+     * only reconstructible by comparing path prefixes (which `_linkPackages` and `currentPackage`
+     * both did, separately). `Workspace.walk` descends, so the containment is known as it is found -
+     * and `Repository.packages` is now this tree flattened rather than the other way round.
+     *
+     * Empty for a leaf, and for every package in an ordinary flat monorepo - where the root's
+     * `children` is the whole member list.
      */
-    parent;
+    children = [];
     /**
      * How this package's versions are numbered - `pkg.versionScheme.next(pkg.version, 'minor')`.
      *
@@ -56,26 +62,85 @@ export class Package {
      *  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.
+     * **What addresses this package**: what a `.rmanrc "[glob]"` block and `--scope`/`--ignore` match
+     * against, and what must be unique within the repository.
+     *
+     * Three sources, first one that answers:
+     *
+     * 1. the package's own `.rmanrc "name"` - the repository assigning one;
+     * 2. its platform's `manifestProvider.selector`;
+     * 3. the manifest's own `name`, which is the default that answer falls back to.
+     *
+     * **Not `name`, and the split is the point.** `name` is what the package calls itself, read from
+     * its manifest, and it is an *ecosystem's* promise that such a thing exists and identifies the
+     * package - npm's promise, not rman's. Selectors matched `pkg.name` until this existed, so a
+     * repository whose technology has no name concept had packages it could not address at all, and
+     * one whose names are not unique (or are import paths) could only address them badly. They
+     * coincide for every Node repository, which is why nothing had to change for one.
+     *
+     * **The root's is nearly unused, deliberately.** A glob never matches the root and `"[/]"` needs
+     * no name - the root is addressed structurally, which is the whole reason it is `/`. It still has
+     * one so that nothing has to special-case it.
+     *
+     * Assigned by `Repository.create`, which is what has the config; a bare `new Package(dir, app)`
+     * gets the manifest's name, which is sources 2 and 3 with no config to consult.
+     */
+    selector;
+    /**
+     * **The technology this package belongs to** - the platform whose manifest provider claimed the
+     * directory, or `basePlatform` when none did.
+     *
+     * Per *package*, not per repository: the question is asked per directory, so a polyglot monorepo
+     * can hold a `node` package beside a `cargo` one and a command sweeping `getPackages()` can tell
+     * them apart. It is also what carries the rest of the technology's answers - where its binaries
+     * live, where its scripts come from, how its releases are planned - so anything that used to walk
+     * four separate registries asking "is this yours?" now asks the package it already has.
+     */
+    platform;
+    /**
+     * **Which ecosystem this package belongs to** - `'node'` for one the `node` built-in read. Empty when
+     * no stack claimed the directory.
      *
      * 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.
+     * before reaching into `manifest.raw` for something only npm has.
      *
      * 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) {
+    get provider() {
+        return this.platform.name;
+    }
+    /**
+     * **Takes the application but does not keep it.** A package needs it once, to find out which
+     * technology claims its directory; afterwards it holds only data, so nothing that has a package
+     * can reach a service through it. Data down, behaviour up - the work belongs to services, and a
+     * piece of code holding only a package is not doing any.
+     *
+     * It also keeps the package out of every spread and serialization the application would
+     * otherwise be dragged into: `{...pkg}` and `pkg.manifest.raw` are both real, and an `app` field
+     * here would carry the whole world into them.
+     */
+    constructor(dirname, app, 
+    /**
+     * The technology that claimed this directory, when the caller already knows - which
+     * `Repository.create` does, because the walk that found the directory is what established it.
+     *
+     * Optional so a bare `new Package(dir, app)` still works: that is what the fixtures build, and
+     * it is also the honest fallback for anyone constructing a package outside a walk. It costs one
+     * search of the registry (`app.platformFor`), which is what *every* construction used to do.
+     */
+    platform) {
         this.dirname = dirname;
-        const { manifest, versionScheme, fileName, provider } = Manifest.read(dirname);
-        this.manifest = manifest;
-        this.versionScheme = versionScheme;
-        this.manifestFileName = fileName ? path.join(dirname, fileName) : '';
-        this.provider = provider;
+        this.platform = platform ?? app.platformFor(dirname);
+        this._readManifest();
+        this.selector = this.platformSelector();
+    }
+    /** What this package's **platform** says addresses it, before any config is consulted - the
+     *  manifest's own name when the platform has no opinion, and the directory when it has no name
+     *  either (which is unique among siblings and is all there is to go on). */
+    platformSelector() {
+        const asked = this.platform.manifestProvider.selector?.(this.manifest, this.dirname);
+        return asked || this.manifest.name || this.basename;
     }
     get basename() {
         return path.basename(this.dirname);
@@ -89,18 +154,45 @@ export class Package {
     get isPrivate() {
         return !!this.manifest.private;
     }
-    /** Re-reads from disk - for a command that has just written the manifest itself and wants the
-     *  package to agree with the file again. */
+    /**
+     * Whether this is the repository's **own root package** - what `--scope /` and `.rmanrc`'s
+     * `"[/]"` both select.
+     *
+     * **By directory, and deliberately not by name or by identity.** The documented rule is that the
+     * root package is the one whose directory *is* the repository root, because a name can be
+     * anything - and identity (`this === repository.rootPackage`) is not equivalent either:
+     * `Repository extends Package` while holding a separate `rootPackage` instance for the same
+     * directory, so a comparison by reference answers `false` for one of the two objects that are
+     * both, truthfully, the root.
+     *
+     * `false` before `Repository.create` has assigned `repository` - a bare `new Package(dir, app)`
+     * (which the test fixtures build) belongs to no repository yet, so there is no root for it to be.
+     */
+    get isRoot() {
+        const repository = this.repository;
+        return !!repository && path.resolve(this.dirname) === path.resolve(repository.dirname);
+    }
+    /**
+     * Re-reads from disk - for a command that has just written the manifest itself and wants the
+     * package to agree with the file again.
+     *
+     * Through **its own** technology's provider, like the constructor: the package already knows
+     * which platform claimed it, and a second opinion on a re-read was never wanted.
+     */
     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;
+        this._readManifest();
         return this.manifest;
     }
     /** Writes the current manifest back through its provider. */
     writeManifest() {
-        Manifest.write(this.dirname, this.manifest);
+        this.platform.manifestProvider.write(this.dirname, this.manifest);
+    }
+    /** The three fields a manifest read sets, in one place - so construction and `reloadManifest`
+     *  cannot disagree about what "reading the manifest" means. */
+    _readManifest() {
+        const { manifest, versionScheme, fileName } = Manifest.read(this.platform, this.dirname);
+        this.manifest = manifest;
+        this.versionScheme = versionScheme;
+        this.manifestFileName = fileName ? path.join(this.dirname, fileName) : '';
     }
 }

package/core/plugin-loader.d.ts

@@ -0,0 +1,65 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { RmanApplication } from './application.js';
+import { type Platform, type Plugin } from './plugin.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export declare const PLUGINS_KEY = "plugins";
+/**
+ * The repository's plugins and publish targets, registered onto `app`.
+ *
+ * **Three keys share one shape** - `plugins`, `publishTargets` and `commands` each take an
+ * instance or a **glob** naming `.js` modules that `export default` one, and each appends rather
+ * than replaces. Two of them are read here; `commands` is read by `cli.ts`, and the split is not
+ * arbitrary:
+ *
+ * - **`plugins` and `publishTargets` are root-level, because they have to be.** This runs inside
+ *   `Repository.create` *before* the packages are known, since a plugin's `getWorkspace` is what
+ *   finds them - so there are no package configs to read yet. A `plugins` entry in a package's own
+ *   `.rmanrc` is never seen, which has always been true and is now true for the same reason.
+ * - **`commands` is read at any level**, after the packages exist, which is why `cli.ts` owns it:
+ *   it already holds the whole command pipeline - the `.rman/` default, de-duplication by name,
+ *   and the built-in shadow check. Reading it here as well would register every config-declared
+ *   command twice, and yargs does not survive that.
+ *
+ * **Order within this function is load-bearing**: plugins first, then targets. rman's own
+ * `publish` builds its `--target` choices from `app.publishTargets` when its factory runs, and a
+ * target contributed by a plugin's `init` has to be there before the list is read.
+ *
+ * **A contribution that cannot be loaded throws**, unlike a broken `.rman/*.mjs`, which is warned
+ * about and skipped. The consequence differs: 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.
+ */
+export declare function loadPlugins(app: RmanApplication, rootConfig: RmanConfig): Promise<void>;
+/**
+ * **Puts one plugin onto an application** - what `plugins` does with an entry once it has been
+ * found and vetted, and the only place that knows how.
+ *
+ * **A bare `Platform` is sugar**, which is what almost every entry is - a plugin that provides one
+ * technology and nothing else. Normalized here, so nothing downstream deals in two shapes.
+ *
+ * **Exported because a spec must not reimplement it.** The registration is two registries plus a
+ * planner assignment, and a fixture writing that out by hand is a second implementation that
+ * drifts - which is exactly how a fixture ends up proving the core works when it does not. A spec
+ * brings its own technology through this, the same door a config's does.
+ *
+ * **`init` is not called here, and that is why this returns the normalized plugin.** An `init` runs
+ * once, when a *config* brought the plugin in, and it may be asynchronous - so it belongs to the
+ * loader above rather than to a function a fixture calls synchronously while building an
+ * application.
+ */
+export declare function registerPlugin(app: RmanApplication, entry: Plugin | Platform): Plugin;
+/**
+ * A plugin's `CustomCommand`, 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.
+ *
+ * Exported because `cli.ts` runs the identical checks on what a *declarative* command's factory
+ * returns, and they must not drift: a plugin written in JavaScript reaches both forms with no type
+ * checker in the way.
+ */
+export declare function checkCustomCommand<T extends {
+    command?: string;
+    describe?: unknown;
+    handler?: unknown;
+}>(command: T, pluginName: string): T & {
+    command: string;
+};

package/core/plugin-loader.js

@@ -0,0 +1,234 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import fastGlob from 'fast-glob';
+import { COMMANDS_KEY } from './merge-config.js';
+import { isDeclared, isPlatform } from './plugin.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export const PLUGINS_KEY = 'plugins';
+/**
+ * The repository's plugins and publish targets, registered onto `app`.
+ *
+ * **Three keys share one shape** - `plugins`, `publishTargets` and `commands` each take an
+ * instance or a **glob** naming `.js` modules that `export default` one, and each appends rather
+ * than replaces. Two of them are read here; `commands` is read by `cli.ts`, and the split is not
+ * arbitrary:
+ *
+ * - **`plugins` and `publishTargets` are root-level, because they have to be.** This runs inside
+ *   `Repository.create` *before* the packages are known, since a plugin's `getWorkspace` is what
+ *   finds them - so there are no package configs to read yet. A `plugins` entry in a package's own
+ *   `.rmanrc` is never seen, which has always been true and is now true for the same reason.
+ * - **`commands` is read at any level**, after the packages exist, which is why `cli.ts` owns it:
+ *   it already holds the whole command pipeline - the `.rman/` default, de-duplication by name,
+ *   and the built-in shadow check. Reading it here as well would register every config-declared
+ *   command twice, and yargs does not survive that.
+ *
+ * **Order within this function is load-bearing**: plugins first, then targets. rman's own
+ * `publish` builds its `--target` choices from `app.publishTargets` when its factory runs, and a
+ * target contributed by a plugin's `init` has to be there before the list is read.
+ *
+ * **A contribution that cannot be loaded throws**, unlike a broken `.rman/*.mjs`, which is warned
+ * about and skipped. The consequence differs: 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.
+ */
+export async function loadPlugins(app, rootConfig) {
+    const seen = new Set();
+    for (const { value, from } of await resolveEntries(rootConfig.plugins, PLUGINS_KEY)) {
+        const plugin = value;
+        if (!isPlainObject(plugin) || typeof plugin.name !== 'string' || !plugin.name) {
+            throw new Error(`"${PLUGINS_KEY}" takes a plugin or a glob naming modules that export one - ${from} gave ` +
+                `${describeExport(plugin)}. Every message about a plugin is keyed by its \`name\`.`);
+        }
+        /**
+         * **Declared through `definePlatform`/`definePlugin`, and checked for it.**
+         *
+         * The guard used to be `manifestProvider` being required, which worked only while one type was
+         * both halves. A 2.x plugin that contributes nothing but an `init` is `{ name, init }` - and so
+         * was an rman **1.x plugin**, exactly. They are indistinguishable by shape, so a shape test
+         * cannot tell them apart and the declaration has to be explicit.
+         *
+         * Measured on the real case before there was any guard: `@panates/rman-node`'s 1.x plugin
+         * loaded, registered, and died inside its own `init` with
+         * `TypeError: ctx.addCommand is not a function`, fifteen times over, naming neither the plugin
+         * nor the version it was written against.
+         */
+        if (!isDeclared(plugin)) {
+            throw new Error(`Plugin "${plugin.name}" (${from}) was not declared with definePlatform() or ` +
+                `definePlugin(). A plain object is how an rman 1.x plugin looks, and a 1.x plugin has ` +
+                `nothing left to do: commands, publish targets and other plugins are "${COMMANDS_KEY}", ` +
+                `"publishTargets" and "${PLUGINS_KEY}" keys of a config now. Wrap a technology in ` +
+                `definePlatform({ name, manifestProvider, ... }), anything else in definePlugin({ ... }).`);
+        }
+        /** One registration per name. Twice would define the same commands twice, which yargs does not
+         *  survive - and two layers naming one plugin is ordinary rather than a mistake. */
+        if (seen.has(plugin.name))
+            continue;
+        seen.add(plugin.name);
+        await registerPlugin(app, plugin).init?.({ app });
+    }
+    for (const { value, from } of await resolveEntries(rootConfig.publishTargets, 'publishTargets')) {
+        const target = value;
+        if (!isPlainObject(value) || typeof target.name !== 'string' || !target.name) {
+            throw new Error(`"publishTargets" takes a target or a glob naming modules that export one - ${from} gave ` +
+                `${describeExport(target)}.`);
+        }
+        app.publishTargets.add(target);
+    }
+}
+/**
+ * **Puts one plugin onto an application** - what `plugins` does with an entry once it has been
+ * found and vetted, and the only place that knows how.
+ *
+ * **A bare `Platform` is sugar**, which is what almost every entry is - a plugin that provides one
+ * technology and nothing else. Normalized here, so nothing downstream deals in two shapes.
+ *
+ * **Exported because a spec must not reimplement it.** The registration is two registries plus a
+ * planner assignment, and a fixture writing that out by hand is a second implementation that
+ * drifts - which is exactly how a fixture ends up proving the core works when it does not. A spec
+ * brings its own technology through this, the same door a config's does.
+ *
+ * **`init` is not called here, and that is why this returns the normalized plugin.** An `init` runs
+ * once, when a *config* brought the plugin in, and it may be asynchronous - so it belongs to the
+ * loader above rather than to a function a fixture calls synchronously while building an
+ * application.
+ */
+export function registerPlugin(app, entry) {
+    const declared = isPlatform(entry) ? { name: entry.name, platforms: [entry] } : entry;
+    app.plugins.add(declared);
+    for (const platform of declared.platforms ?? []) {
+        app.platforms.add(platform);
+        /**
+         * **The orchestrator, and only that.** A plan is computed for the whole repository at once -
+         * groups span packages, the ripple crosses them - so one planner drives the traversal and the
+         * last registration wins it.
+         *
+         * The two decisions that belong to a *technology* are not taken from here: `detectBoundary`
+         * and `cascade` are asked of `pkg.platform.versionPlanner` per package, which is why a platform
+         * still declares one even when it is not the last to register.
+         */
+        if (platform.versionPlanner)
+            app.versionPlanner = platform.versionPlanner;
+    }
+    return declared;
+}
+/**
+ * The shared half of the three keys: an instance is itself, a string is a glob whose matches are
+ * imported and unwrapped.
+ *
+ * **A glob is already absolute** by the time it gets here - `mergeConfig` anchors it to the file
+ * that declared it as the config is read, which is the last moment that is knowable (see
+ * `anchorContributions`). Nothing here resolves a path.
+ *
+ * **`.js` only.** rman imports these in its own process with no loader registered, so a `.ts`
+ * module cannot be one; a TypeScript repository compiles first or writes `.mjs`. Stated rather
+ * than attempted, because a `.ts` that happens to load under a test runner's loader and not under
+ * the CLI is the worst of both.
+ */
+async function resolveEntries(declared, key) {
+    if (declared === undefined)
+        return [];
+    const out = [];
+    for (const entry of (Array.isArray(declared) ? declared : [declared])) {
+        if (typeof entry !== 'string') {
+            out.push({ value: entry, from: `"${key}"` });
+            continue;
+        }
+        if (!entry.trim())
+            throw new Error(`"${key}" has an empty glob.`);
+        const files = await fastGlob(entry.split(path.sep).join('/'), { absolute: true, onlyFiles: true });
+        /**
+         * **A glob matching nothing is an error here**, unlike in `commands`, and the asymmetry is the
+         * point. Losing a plugin silently removes commands and seams the repository is built around -
+         * `rman publish` would simply not exist, and "not a known command" sends the reader looking in
+         * the wrong place. `commands` can match nothing legitimately: `.rman/*.js` is its default, and
+         * most repositories have no such directory.
+         */
+        if (!files.length) {
+            /**
+             * **A package name gets the answer it is actually asking for.** A bare `rman-node` here is a
+             * glob that matches nothing, and "matched no file" sends the reader to check their paths -
+             * when what they wrote is a *package*, whose config reaches a repository through `extends`.
+             * Two documents promised this message named the fix (`docs/rman.md`, `docs/cli-rman.md`) and
+             * it did not; measured, `plugins: ['rman-node']` exited 1 saying only that a glob matched
+             * nothing.
+             *
+             * Reaching this intact takes `mergeConfig`'s help: it anchors a contribution glob to the file
+             * that declared it, which used to turn `rman-node` into `<dir>/rman-node` and erase the
+             * evidence. `looksLikePackageName` there leaves this shape alone; the same predicate is
+             * spelled again here rather than shared, because the two modules answer different questions
+             * with it and a merge concern importing a loader concern (or the reverse) is the coupling
+             * neither wants.
+             */
+            const isPackageName = /^(?:@[a-z0-9-~][\w.-]*\/)?[a-z0-9-~][\w.-]*$/i.test(entry) && !/\.[cm]?js$/i.test(entry);
+            if (isPackageName) {
+                throw new Error(`"${key}" entry "${entry}" looks like a package name, and this key does not take one - ` +
+                    `it takes a plugin, or a glob naming modules that export one. A plugin package exports ` +
+                    `an rman config, so write \`extends: "${entry}"\` instead, which merges everything that ` +
+                    `package declares underneath your own config.`);
+            }
+            throw new Error(`"${key}" glob "${entry}" matched no file. A plugin that does not load is not a plugin.`);
+        }
+        for (const file of [...new Set(files.map(f => path.resolve(f)))].sort()) {
+            const mod = await import(pathToFileURL(file).href);
+            const exported = mod?.default;
+            if (exported === undefined) {
+                throw new Error(`"${key}" matched "${file}", which has no default export. ${describeExport(mod)}`);
+            }
+            out.push({ value: exported, from: file });
+        }
+    }
+    return out;
+}
+/**
+ * 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}".`;
+}
+/**
+ * The members only a plugin has, for that sentence alone.
+ *
+ * **`name` is deliberately not one of them**, and it used to be: a config may carry a `name` too,
+ * so anything with one "looked like a plugin" - which sent the author of a perfectly ordinary
+ * config to go and wrap it in `plugins`. Each of these belongs to a technology and to nothing
+ * else, `manifestProvider` first because it is the one a plugin cannot be without.
+ */
+const PLUGIN_SEAMS = ['manifestProvider', 'getWorkspace', 'getBinPaths', 'getRunSteps', 'versionPlanner'];
+/** 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 `CustomCommand`, 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.
+ *
+ * Exported because `cli.ts` runs the identical checks on what a *declarative* command's factory
+ * returns, and they must not drift: a plugin written in JavaScript reaches both forms with no type
+ * checker in the way.
+ */
+export function checkCustomCommand(command, pluginName) {
+    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 };
+}