rman 1.3.0 → 2.0.0-beta.3

package/core/classes/workspace.js

@@ -0,0 +1,537 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_PRESETS } from '../../builtins/presets/index.js';
+import { ConfigReader } from '../config/config-reader.js';
+import { mergeConfig, ORIGINS } from '../config/merge-config.js';
+import { basePlatform } from '../interfaces/plugin.js';
+import { Package } from './package.js';
+/**
+ * A repository's layout, resolved: which directories hold packages, which technology claims each of
+ * them, what each one answers to, and the **raw** config each one ends up with.
+ *
+ * Built with {@link Workspace.create}, which runs the whole resolution; the constructor is
+ * protected, so there is no such thing as a half-built workspace.
+ *
+ * The configs it produces are **raw** - every `${{ }}` and every value function is still
+ * unevaluated. Resolving one needs `pkg`, `repository` and `git`, which belong to the repository
+ * rather than to its layout; `ConfigInterpolator` is the step after this.
+ */
+/* The three steps live together because they depend on each other in one direction only: the root's
+ * config names the plugins, the plugins decide which directories are packages, and a package's
+ * config is the directory chain above it layered together. None of it can be done out of order, and
+ * each step is useless on its own.
+ *
+ * Every step is an overridable `protected` method, so a technology or a spec can replace one and
+ * keep the rest. */
+export class Workspace {
+    options;
+    /** The repository root - where the walk starts and what every directory chain is relative to. */
+    rootDir;
+    /** Every plugin in play, in load order: the ones passed in first, then each level's own. */
+    plugins = [];
+    /** Every technology in play, in contribution order - which is what decides who claims a
+     *  directory, since the first that recognizes it wins. */
+    platforms = [];
+    /** The root directory's own package. Not one of `packages`, which holds the members. */
+    rootPackage;
+    /** Every package below the root, depth-first. */
+    packages = [];
+    /** Each directory's own config, read once - see `_readLevel`. */
+    _levels = new Map();
+    /** The packages whose selector came from a `"name"` declaration rather than from their platform,
+     *  for the clash message alone. */
+    _declaredSelectors = new Set();
+    /** Built on first use, unless `options.reader` supplied one. */
+    _configReader;
+    /**
+     * Builds a workspace and resolves it: discovery, selectors, and every package's raw config.
+     *
+     * A subclass inherits this and gets an instance of itself. Its declared return type stays
+     * `Workspace`, so a subclass wanting its own declares a one-line `create` that calls this.
+     *
+     * @param rootDir the repository root
+     */
+    /* **`new this()`, not `new Workspace()`.** In a static method `this` is the class the call was
+     * made on, so a subclass inheriting this factory builds itself; hard-coding the name would let
+     * someone override `_init` and never see it run. The spec for it asserts `instanceof` on the
+     * subclass.
+     *
+     * **The return type is a TypeScript limit rather than a choice.** The polymorphic form
+     * (`this: new (...) => T`) requires a *publicly* constructible class, and the constructor here is
+     * protected on purpose. The two cannot both be had, and the guard is worth more than the inferred
+     * type. */
+    static async create(rootDir, options) {
+        const workspace = new this(rootDir, options);
+        await workspace._init();
+        return workspace;
+    }
+    /** Use {@link Workspace.create}. */
+    /* Protected because an un-initialized workspace is a half-built object - no packages, no configs,
+     * and nothing saying so. */
+    constructor(rootDir, options) {
+        this.options = options;
+        this.rootDir = path.resolve(rootDir);
+        this.plugins = [...(options.plugins ?? [])];
+        this.platforms = [...(options.platforms ?? [])];
+    }
+    /** The package at a directory, root included, or `undefined` for one that holds none. */
+    packageAt(dirname) {
+        const resolved = path.resolve(dirname);
+        if (this.rootPackage && this.rootPackage.dirname === resolved)
+            return this.rootPackage;
+        return this.packages.find(pkg => pkg.dirname === resolved);
+    }
+    /** The whole resolution, in the one order the steps admit. */
+    /* Each line is a `protected` method rather than inline code precisely so this reads as the order
+     * and nothing else - and so a subclass replacing one step does not have to restate the rest. */
+    async _init() {
+        await this._discover();
+        await this._resolveSelectors();
+        this._assertUniqueSelectors();
+        await this._resolveConfigs();
+    }
+    /**
+     * Descends from the root, asking each directory's own technology where its children are, and
+     * fills `rootPackage` and `packages`.
+     *
+     * One step, repeated: read the directory's config (which loads whatever plugins it names and
+     * decides its platform), then ask *that* platform's `getWorkspace` for the directories below it
+     * holding packages. A directory is visited once, and `options.deep` bounds the descent.
+     */
+    /* **First visit wins.** A provider may legitimately name a directory another one already claimed
+     * (two overlapping globs, a symlinked package), and one naming an ancestor would otherwise
+     * recurse forever.
+     *
+     * `deep` bounds the descent for the same reason `findRoot` bounds its climb: a provider computing
+     * paths rather than reading them can produce a chain that never ends, and a guessed depth beats a
+     * hang with nothing printed. */
+    async _discover() {
+        const visited = new Set();
+        const descend = async (dir, parent, remaining) => {
+            const dirname = path.resolve(dir);
+            visited.add(dirname);
+            const level = await this._readLevel(dirname);
+            const platform = this._platformFor(dirname, level.config);
+            /** The platform is handed over rather than searched for: the walk that found this directory
+             *  is what established it, and `Package` re-guessing would be a second answer that can
+             *  disagree with the first. */
+            const pkg = this._createPackage(dirname, platform);
+            if (dirname === this.rootDir)
+                this.rootPackage = pkg;
+            else
+                this.packages.push(pkg);
+            if (parent) {
+                /** `children` is enumerable and `parent` is not: one edge, and only one direction can be
+                 *  the one a walk follows - a `Package` that can be serialized needs the back-reference
+                 *  hidden. */
+                parent.children.push(pkg);
+                Object.defineProperty(pkg, 'parent', { value: parent, enumerable: false, configurable: true });
+            }
+            if (remaining <= 0)
+                return;
+            /** **Its own platform is asked, and nobody else.** A platform that did not claim the
+             *  directory has no standing to say what is under it. A directory no technology claimed has
+             *  no `getWorkspace`, hence no children - which is a single-package repository arrived at
+             *  rather than guessed. */
+            for (const child of platform.getWorkspace?.(dirname) ?? []) {
+                const childDir = path.resolve(child);
+                if (visited.has(childDir))
+                    continue;
+                await descend(childDir, pkg, remaining - 1);
+            }
+        };
+        await descend(this.rootDir, undefined, this.options.deep ?? 10);
+    }
+    /**
+     * Gives every package the selector it answers to - its `.rmanrc "name"` when it declares one, and
+     * what its platform says otherwise.
+     *
+     * `"[glob]"` and `--scope` match this, never the package's name: a name is an *ecosystem's*
+     * promise rather than rman's.
+     */
+    /* **Resolved from a cascade run with no selector at all**, and that is the step whose absence is
+     * silent: a `"[pkg-a]"` block is applied on the strength of the selector, and the selector comes
+     * from `name`, which is inside the very config being resolved. Reading `name` while applying
+     * selector blocks would need the answer in order to find it. So the chain is walked twice -
+     * unmarked only, then for real - over one directory cache, which is what keeps the second pass
+     * free.
+     *
+     * `name` is refused inside a glob block for exactly this reason (`_assertSelectorBlocks`), so
+     * nothing is lost by the first pass ignoring them. */
+    async _resolveSelectors() {
+        for (const pkg of [this.rootPackage, ...this.packages]) {
+            const config = await this._cascade(pkg, undefined);
+            const declared = config.name;
+            if (declared !== undefined && (typeof declared !== 'string' || !declared.trim())) {
+                throw new Error(`"name" takes the selector this package answers to - "${pkg.dirname}" gave ${typeof declared}.`);
+            }
+            if (declared !== undefined)
+                this._declaredSelectors.add(pkg);
+            /** `platformSelector()` is the package's own - the manifest's name, or whatever its platform
+             *  says addresses it. `Package` already computed it in its constructor; this only replaces it
+             *  when the config declared one. */
+            pkg.selector = declared?.trim() || pkg.platformSelector();
+        }
+    }
+    /**
+     * Refuses two packages answering to one selector. The root is exempt - a glob never matches it and
+     * `"[/]"` needs no name, so it shares an address with nobody.
+     */
+    /* Two packages answering to one selector make `"[that]"` and `--scope that` ambiguous *silently* -
+     * the config reaches both and a lookup returns the first.
+     *
+     * `name` cascades like every unmarked key, so one declaration above two packages is the usual way
+     * in - and the message says so when that is what happened, since the fix is different. */
+    _assertUniqueSelectors() {
+        const bySelector = new Map();
+        for (const pkg of this.packages) {
+            const clash = bySelector.get(pkg.selector);
+            if (clash) {
+                const cascaded = this._declaredSelectors.has(pkg) && this._declaredSelectors.has(clash);
+                throw new Error(`Two packages answer to the selector "${pkg.selector}":\n  ${clash.dirname}\n  ${pkg.dirname}\n` +
+                    `  A selector has to be unique - "[${pkg.selector}]" and \`--scope ${pkg.selector}\` ` +
+                    `cannot mean two packages.` +
+                    (cascaded
+                        ? `\n  Both got it from one cascading "name" declaration above them; declare it in ` +
+                            `each package's own ".rmanrc" instead.`
+                        : ''));
+            }
+            bySelector.set(pkg.selector, pkg);
+        }
+    }
+    /** Cascades every package's config into `Package.rawConfig`, now that the selectors are known.
+     *  Still raw - `Repository` is what interpolates it into `Package.config`. */
+    async _resolveConfigs() {
+        for (const pkg of [this.rootPackage, ...this.packages]) {
+            pkg.rawConfig = await this._cascade(pkg, pkg.selector);
+        }
+    }
+    /**
+     * Every directory from the root down to `pkg`, layered into one config.
+     *
+     * Two layers per level: the level's unmarked keys first, then the `"[selector]"` blocks that
+     * speak for this package, in the order they were written - later wins, as `overrides` does in
+     * eslint and prettier.
+     *
+     * @param selector what the blocks are matched against; `undefined` skips them, except `"[/]"` for
+     *   the root, which is structural and needs no selector.
+     */
+    /* **Unmarked first because it is the widest thing the level says** - it configures that directory
+     * *and every package under it*, so it is the level's floor. A selector block written *above* the
+     * plain keys still beats them: unmarked is not a fourth selector, it is the layer that also feeds
+     * the directories below, and making that depend on key order in the file would be absurd. */
+    async _cascade(pkg, selector) {
+        const result = {};
+        const audience = {
+            isRoot: pkg.dirname === this.rootDir,
+            selector,
+            platform: pkg.platform.name,
+        };
+        for (const dir of this._dirChain(pkg.dirname)) {
+            const level = await this._readLevel(dir);
+            mergeConfig(result, this._stripSelectors(level.config));
+            for (const block of this._matchingSelectors(level.config, audience)) {
+                mergeConfig(result, block);
+            }
+        }
+        return result;
+    }
+    /** One directory's own config, read once and cached. Plugins the level names are loaded here and
+     *  accumulated into `plugins`. */
+    /* The cache is what makes the two cascade passes affordable - twenty packages sharing a root
+     * means that root is read once rather than forty times. It is also what keeps a level's plugins
+     * from being loaded a second time. */
+    async _readLevel(dirname) {
+        const resolved = path.resolve(dirname);
+        const hit = this._levels.get(resolved);
+        if (hit)
+            return hit;
+        const result = await this._reader().resolve(resolved, {
+            plugins: this.plugins,
+            platforms: this.platforms,
+            /** **The root alone**, because that is the level they belong to: everything below it inherits
+             *  whatever the root settled on, and laying them down again there would put a preset's
+             *  technology ahead of one an intermediate directory declared. */
+            presets: resolved === this.rootDir ? (this.options.presets ?? DEFAULT_PRESETS) : undefined,
+        });
+        /** Whatever this level added, in the order it was loaded - `plugins` appends, never replaces,
+         *  so a level naming one never means "and drop the ones above me". The technologies a plugin
+         *  carries are already in `result.platforms`; the reader puts them there, so this walk and the
+         *  reader cannot end up with two orders. */
+        for (const plugin of result.plugins) {
+            if (!this.plugins.some(p => p.name === plugin.name))
+                this.plugins.push(plugin);
+        }
+        for (const platform of result.platforms)
+            this._addPlatform(platform);
+        this._levels.set(resolved, result);
+        return result;
+    }
+    /** Appends a technology unless one already answers to its name. */
+    _addPlatform(platform) {
+        if (!this.platforms.some(p => p.name === platform.name))
+            this.platforms.push(platform);
+    }
+    /** The reader levels are read with - `options.reader`, or a default one. */
+    _reader() {
+        return (this._configReader ??= this.options.reader ?? new ConfigReader());
+    }
+    /** Root, then every directory down to `targetDir`, inclusive. A target outside the root is the
+     *  root alone. */
+    _dirChain(targetDir) {
+        const rel = path.relative(this.rootDir, targetDir);
+        if (!rel || rel === '.' || rel.startsWith('..'))
+            return [this.rootDir];
+        const dirs = [this.rootDir];
+        let dir = this.rootDir;
+        for (const segment of rel.split(path.sep)) {
+            dir = path.join(dir, segment);
+            dirs.push(dir);
+        }
+        return dirs;
+    }
+    /** A level's own settings - everything that is not a `"[...]"` block. */
+    _stripSelectors(config) {
+        const result = {};
+        for (const [key, value] of Object.entries(config))
+            if (!ConfigReader.isSelectorKey(key))
+                result[key] = value;
+        return result;
+    }
+    /**
+     * The blocks in `config` that speak for this package, in declaration order.
+     *
+     * `"[/]"` matches the root and nothing else; a glob matches a package's selector and never the
+     * root.
+     */
+    /* **A glob never matching the root removes two traps at once**: `"[my-*]"` cannot quietly pick up
+     * a repository whose root package is called `my-repo`, and `"[*]"` cannot hand a package-shaped
+     * setting to a root with no build directory to apply it to. A root block needs no selector, which
+     * is what makes `/` structural. */
+    _matchingSelectors(config, audience) {
+        const matches = [];
+        for (const [key, value] of Object.entries(config)) {
+            if (!ConfigReader.isSelectorKey(key) || !value || typeof value !== 'object')
+                continue;
+            const { scope, test } = ConfigReader.parseSelector(key);
+            if (!this._speaksFor(scope, test, audience))
+                continue;
+            matches.push(value);
+        }
+        return matches;
+    }
+    /**
+     * Whether one selector block speaks for this package.
+     *
+     * `"[/]"` asks only whether this *is* the root. Everything else matches packages **below** the
+     * root and never the root itself, which is addressed structurally or not at all.
+     */
+    /* **A glob never matching the root removes two traps at once**: `"[my-*]"` cannot quietly pick up
+     * a repository whose root package is called `my-repo`, and `"[*]"` cannot hand a package-shaped
+     * setting to a root with no build directory to apply it to. A platform block is held to the same
+     * line for consistency - the root has a platform, but it also has `"[/]"`.
+     *
+     * A package no technology claimed carries `basePlatform`, whose name is `''`, so it matches no
+     * platform block at all - `parseSelector`'s test refuses an empty name rather than letting an
+     * empty selector quietly match it. */
+    _speaksFor(scope, test, audience) {
+        if (scope === 'root')
+            return audience.isRoot;
+        if (audience.isRoot)
+            return false;
+        if (scope === 'platform')
+            return test(audience.platform);
+        return audience.selector !== undefined && test(audience.selector);
+    }
+    /**
+     * The platform that claims a directory - the one its config names, or the first loaded platform
+     * whose manifest provider recognizes it. `basePlatform` when none does, so a caller needs no
+     * guard; a *declared* platform no plugin provides is an error.
+     */
+    /* `ConfigReader` already decided the name, from a declaration or by asking the loaded plugins, so
+     * this only has to find the platform that answers to it. */
+    _platformFor(dirname, config) {
+        const declared = this._declaredPlatformName(config);
+        if (declared === undefined) {
+            return this.platforms.find(p => p.manifestProvider.read(dirname)) ?? basePlatform;
+        }
+        const named = this.platforms.find(p => p.name === declared);
+        if (!named) {
+            const have = this.platforms.map(p => p.name).filter(Boolean);
+            throw new Error(`"platform" names "${declared}" (${this._originOf(config, 'platform')}), which is not a ` +
+                `platform this repository has. ` +
+                `${have.length ? `Registered: ${have.join(', ')}. ` : 'None is registered. '}` +
+                `Contribute it with "platforms", or inherit it with "extends".`);
+        }
+        /** **A declaration is held to the directory it names.** The failure it replaces is invisible:
+         *  the manifest reads as nothing, so the package is named after its directory at `0.0.0` and
+         *  the repository looks fine. The message names the file the platform looked for, because that
+         *  is the thing to go and check. */
+        if (!named.manifestProvider.read(dirname)) {
+            throw new Error(`"${dirname}" declares \`platform: '${declared}'\` (${this._originOf(config, 'platform')}), ` +
+                `and "${declared}" does not recognize it - it looks for "${named.manifestProvider.fileName}".`);
+        }
+        return named;
+    }
+    /** A platform named unmarked or under `"[/]"` - both are the directory saying what it is. */
+    /* **An expression is refused rather than read as a literal.** `platform` is consulted before any
+     * package exists - it is what decides what a package *is* - so there is no `pkg` for an
+     * expression to be about, and interpolation runs long afterwards. Passed through, a `${{ }}` here
+     * reached the lookup as its raw text and failed as an unknown platform name, which sends the
+     * reader to check their `platforms` instead of the line they wrote.
+     *
+     * A value that is not a usable string is refused too, rather than read as "declared nothing": the
+     * two are opposite answers, and the silent one leaves a directory claimed by whichever technology
+     * happened to recognize it. */
+    _declaredPlatformName(config) {
+        const root = config['[/]'];
+        const declared = config.platform ?? (root && typeof root === 'object' ? root.platform : undefined);
+        if (declared === undefined)
+            return undefined;
+        const where = this._originOf(config, 'platform');
+        if (typeof declared !== 'string' || !declared.trim()) {
+            throw new Error(`"platform" takes a platform's name - ${where} gave ${typeof declared}.`);
+        }
+        if (declared.includes('${{')) {
+            throw new Error(`"platform" cannot be an expression (${where}) - it is read while the packages are still ` +
+                `being found, so there is no package for one to be about. Write the name, and use a ` +
+                `package's own ".rmanrc" where the answer differs.`);
+        }
+        return declared.trim();
+    }
+    /** Which file a key came from, for an error that can be acted on. */
+    /* A config is merged from a directory's own forms, an `extends` base, every `"[selector]"` block
+     * and one layer per directory before anything reads it, so the key alone leaves the reader
+     * searching all of them. `mergeConfig` records one file per key under `ORIGINS`. */
+    _originOf(config, key) {
+        const origins = config[ORIGINS];
+        return origins?.[key] ? `in "${origins[key]}"` : `the "${key}" key`;
+    }
+    /** Where a `Package` is made, and the only place - override it to build a subclass of `Package`
+     *  and keep the rest of the walk. */
+    _createPackage(dirname, platform) {
+        return new Package(dirname, this.options.app, platform);
+    }
+}
+/**
+ * How a repository is laid out, and who decides.
+ *
+ * A namespace for the same reason `Manifest` is one: it is what a plugin can *augment*
+ * (`declare module 'rman' { namespace Workspace { ... } }`), so whatever this seam grows later
+ * arrives as a member here rather than as another top-level export. It merges with the class above,
+ * so `Workspace.walk` and `Workspace.create` are reached the same way.
+ */
+(function (Workspace) {
+    /**
+     * **The walk**: descend from `rootDir`, asking each directory's own technology where its children
+     * are, and repeating for each answer.
+     *
+     * One step, applied recursively:
+     *
+     * 1. take the directory's **declared** platform if it has one, and otherwise the first registered
+     *    platform whose manifest provider recognizes it (`app.platformFor`, `basePlatform` if none);
+     * 2. ask **that** platform's `getWorkspace` for the directories below it holding packages;
+     * 3. do the same for each of them.
+     *
+     * **A declaration wins, and is then held to it.** A platform named for a directory it does not
+     * recognize is a statement that is simply untrue, and the failure it would otherwise become is
+     * invisible: the manifest reads as nothing, so the package is named after its directory at
+     * `0.0.0` and the repository looks like it works. The error names the directory, the platform and
+     * the file that platform looked for.
+     *
+     * The root node always exists - a repository is a package whatever its technology - so this never
+     * returns `undefined`. A repository nobody recognizes is a root with no children, which is the
+     * single-package answer arrived at rather than guessed.
+     *
+     * **A directory is visited once.** A provider may legitimately name a directory another one
+     * already claimed (two globs overlapping, a symlinked package), and a provider naming an ancestor
+     * would otherwise recurse forever. First visit wins, so a package sits where it was first found.
+     *
+     * `deep` bounds the descent for the same reason `findRoot` bounds its climb: a provider computing
+     * paths rather than reading them can produce a chain that never ends, and a guessed depth is
+     * better than a hang with nothing printed.
+     */
+    async function walk(app, rootDir, options) {
+        const visited = new Set();
+        const descend = async (dir, remaining) => {
+            const resolved = path.resolve(dir);
+            visited.add(resolved);
+            const declared = await options?.declared?.(resolved);
+            if (declared && !declared.manifestProvider.read(resolved)) {
+                throw new Error(`"${resolved}" declares \`platform: '${declared.name}'\`, and that platform does not ` +
+                    `recognize it - it looks for "${declared.manifestProvider.fileName}". Either the ` +
+                    `directory is not a ${declared.name} package, or the declaration belongs one level down.`);
+            }
+            const platform = declared ?? app.platformFor(resolved);
+            const node = { dirname: resolved, platform, children: [] };
+            if (remaining <= 0)
+                return node;
+            /**
+             * **Its own platform is asked, and nobody else.** A platform that did not claim the directory
+             * has no standing to say what is under it - that was the old first-wins rule, one level up.
+             * `basePlatform` has no `getWorkspace`, so a directory no technology claimed has no children,
+             * which is the documented behaviour of a repository naming no plugin.
+             */
+            for (const child of platform.getWorkspace?.(resolved) ?? []) {
+                const childDir = path.resolve(child);
+                if (visited.has(childDir))
+                    continue;
+                node.children.push(await descend(childDir, remaining - 1));
+            }
+            return node;
+        };
+        return descend(rootDir, options?.deep ?? 10);
+    }
+    Workspace.walk = walk;
+    /** Every node below `node`, depth-first, excluding `node` itself - the flat list `Repository`
+     *  reports as its packages, since the root is not one of its own members. */
+    function flatten(node) {
+        return node.children.flatMap(child => [child, ...flatten(child)]);
+    }
+    Workspace.flatten = flatten;
+    /**
+     * Where the repository starts, decided **without knowing anything about any ecosystem** - it has
+     * to be, because the plugins that do know are named in the config file this walk is looking for.
+     *
+     * Walking up from `from`, stopping after a directory holding `.git`, the root is:
+     *
+     * 1. the **outermost** directory in that chain holding an `.rmanrc*` - outermost, because a
+     *    *package* may have its own `.rmanrc` (that is a supported thing), and from inside such a
+     *    package the nearest one is the package's, not the repository's;
+     * 2. otherwise the `.git` directory itself, the ordinary meaning of "repository root";
+     * 3. otherwise `from`, which is all that is left to go on.
+     *
+     * **What "outermost" costs**, since the two cases genuinely conflict and only one can win: a
+     * self-contained project nested inside a larger git repository *and sharing its `.git`* resolves
+     * to the outer root, not to itself (measured). That is the same repository by any definition git
+     * recognizes, so it is the defensible answer - and a nested project with a `.git` of its own is
+     * found correctly, because the walk stops there before the outer `.rmanrc` is ever seen (also
+     * measured). A per-package `.rmanrc` is the common case and it is the one served.
+     */
+    function findRoot(from, deep = 10) {
+        const chain = [];
+        let dir = path.resolve(from);
+        let remaining = deep;
+        while (remaining-- >= 0 && fs.existsSync(dir)) {
+            chain.push(dir);
+            if (fs.existsSync(path.join(dir, '.git')))
+                break;
+            const parent = path.resolve(dir, '..');
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        const withConfig = chain.filter(hasRmanConfig);
+        if (withConfig.length)
+            return withConfig[withConfig.length - 1];
+        const gitRoot = chain.find(d => fs.existsSync(path.join(d, '.git')));
+        return gitRoot ?? path.resolve(from);
+    }
+    Workspace.findRoot = findRoot;
+    /** Every file form a `.rmanrc` comes in - `package.json#rman` is deliberately *not* one of them
+     *  here: it would make the root question npm-shaped again. */
+    const CONFIG_FILES = ['.rmanrc', '.rmanrc.yml', '.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
+    function hasRmanConfig(dir) {
+        return CONFIG_FILES.some(name => fs.existsSync(path.join(dir, name)));
+    }
+})(Workspace || (Workspace = {}));

package/core/command-builder.d.ts

@@ -0,0 +1,14 @@
+import type { CommandModule } from 'yargs';
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+/**
+ * Turns a command's **declaration** into the yargs registration it describes.
+ *
+ * This is the one place that knows how the two relate, which is the point of declaring commands
+ * instead of building them: a command says what it has, and only this function says what yargs is
+ * told. Everything a `builder` used to do by hand - options, positionals, examples, parser
+ * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
+ * than a flag that silently never existed.
+ */
+export declare function toYargsCommand(meta: RmanConfig.CommandMetadata): CommandModule;
+/** A command's own name - the first word of its `command` string, before any positional. */
+export declare function commandName(command: string): string;

package/core/command-builder.js

@@ -0,0 +1,94 @@
+/**
+ * Turns a command's **declaration** into the yargs registration it describes.
+ *
+ * This is the one place that knows how the two relate, which is the point of declaring commands
+ * instead of building them: a command says what it has, and only this function says what yargs is
+ * told. Everything a `builder` used to do by hand - options, positionals, examples, parser
+ * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
+ * than a flag that silently never existed.
+ */
+export function toYargsCommand(meta) {
+    return {
+        command: meta.command,
+        aliases: meta.aliases,
+        describe: meta.describe,
+        configKeys: configKeysOf(meta),
+        builder: (cmd) => {
+            if (meta.parserConfiguration)
+                cmd.parserConfiguration(meta.parserConfiguration);
+            for (const [name, spec] of Object.entries(meta.positionals ?? {}))
+                cmd.positional(name, spec);
+            for (const [key, option] of Object.entries(meta.config ?? {})) {
+                /**
+                 * **`target: 'config'` means "a `.rmanrc` key, and not a flag"** - `githubRelease.draft` is
+                 * the first of those. Skipping it here is what makes the field mean something rather than
+                 * being documentation.
+                 */
+                if (option.target === 'config')
+                    continue;
+                /** `target` and `cliName` are rman's, not yargs' - dropped rather than passed through. */
+                const { cliName, ...rest } = option;
+                delete rest.target;
+                /**
+                 * Registered under `cliName` when the flag and the config key are spelled differently
+                 * (`--ignore-dirty` for `ignoreDirty`). yargs expands the hyphenated form back to camelCase
+                 * in argv, so the handler reads the key it declared either way.
+                 */
+                cmd.option(cliName ?? key, rest);
+            }
+            for (const example of meta.examples ?? [])
+                cmd.example(example.command, example.description ?? '');
+            return cmd;
+        },
+        /**
+         * Cast because the two descriptions of argv disagree on purpose: yargs types it as an index
+         * signature of `unknown`, and a command annotates it with the options it actually declared. The
+         * narrower one is the useful one, and this is the single place the widening is admitted -
+         * previously it was an `as` per option read, in every handler.
+         */
+        handler: withCommandPlatforms(meta),
+    };
+}
+/**
+ * Carries `CommandMetadata.platforms` into argv, where `readPackageFilterOptions` picks it up.
+ *
+ * Through argv rather than a parameter because `filterPackages` is called by ten *services*, none
+ * of which knows which command is running - `options` is all they see. One wrap here reaches every
+ * one of them and changes none.
+ */
+function withCommandPlatforms(meta) {
+    const handler = meta.handler;
+    if (!meta.platforms?.length)
+        return handler;
+    return (args) => {
+        args.commandPlatforms = meta.platforms;
+        return handler(args);
+    };
+}
+/** A command's own name - the first word of its `command` string, before any positional. */
+export function commandName(command) {
+    return command.split(/\s+/)[0];
+}
+/**
+ * Which `.rmanrc` keys `--config` shows for a command: the ones it declared reading, plus **its own
+ * key when it has one**.
+ *
+ * `configKeys` is the read-only list on purpose - a command should not have to repeat the key it
+ * already owns, and `version` listing `'version'` beside `'changelog'` said nothing about which of
+ * the two it defines. Measured before this existed: `rman version --config` reported
+ * `changelog, group, allowBranch, ignoreBranch` and left out `version` itself.
+ *
+ * **Own key only when the command actually declares a config option.** `build` and `test` own
+ * nothing - their settings live in `run.build`/`run.test`, which they merely read - so prepending
+ * their names would print an empty `build: {}` that reads as "nothing is configured" about a key
+ * that does not exist. A `configKeys` given as a *function* is left alone entirely: `run` computes
+ * `run.<script>` from argv, which is narrower than its own key and deliberately so.
+ */
+function configKeysOf(meta) {
+    if (typeof meta.configKeys === 'function')
+        return meta.configKeys;
+    const ownsConfig = Object.values(meta.config ?? {}).some(o => o.target !== 'cli');
+    const own = ownsConfig ? [meta.configKey ?? commandName(meta.command)] : [];
+    const keys = [...own, ...(meta.configKeys ?? [])];
+    return keys.length ? keys : undefined;
+}