rman 1.2.5 → 2.0.0-beta.2

package/core/plugin.js

@@ -1,189 +1,86 @@
-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.
- */
+/** Whether `value` came from `definePlatform` or `definePlugin`. */
+export function isDeclared(value) {
+    return !!value && typeof value === 'object' && value[declaredKey()] === true;
+}
+/** Declares a **platform** - one technology, whole. Returns it unchanged apart from the mark. */
+export function definePlatform(platform) {
+    return brand(platform);
+}
+/** Declares a **plugin** - whatever a package contributes, platforms included. Returns it unchanged
+ *  apart from the mark. */
 export function definePlugin(plugin) {
-    return plugin;
+    return brand(plugin);
+}
+/** Whether `value` is a platform rather than the broader plugin - `manifestProvider` is what makes
+ *  one, and it is the only required member either type has beyond `name`. */
+export function isPlatform(value) {
+    return !!value.manifestProvider;
 }
 /**
- * Loads every plugin the repository's `.rmanrc "plugins"` declares, in declaration order.
+ * The platform a package gets when **none** claimed its directory - a repository naming no
+ * platform, or a directory none of the named ones recognized.
  *
- * 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.
+ * It exists so `Package.platform` need not be optional. `Package.provider` was an empty string for
+ * exactly this case, and every reader had to know that; an object with an empty `name` says the
+ * same thing without a guard, and `pkg.provider === 'node'` - the check CLAUDE.md prescribes -
+ * reads the same either way.
  *
- * 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`).
+ * **Every documented behaviour of "no plugin" survives unchanged**, because the absences are the
+ * behaviour:
  *
- * 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.
+ * - a reader that recognizes nothing -> `Manifest.read` falls through to its own empty manifest,
+ *   exactly as it does when no plugin answers;
+ * - no `getWorkspace` -> a repository naming no plugin has no packages beyond itself, which is the
+ *   boundary working rather than failing (`workspaces` in a `package.json` is npm's idea);
+ * - no `getBinPaths` -> nothing is prepended to a child process's PATH, so the inherited one
+ *   stands on its own rather than being guessed at;
+ * - no `getRunSteps` -> a package's steps come from its `.rmanrc` alone, the core's only source;
+ * - no `versionPlanner` -> `version`/`changed` fail naming the key, rather than releasing a
+ *   plausible but untrue set of packages from a default nobody chose.
  */
-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;
-}
+export const basePlatform = definePlatform({
+    name: '',
+    manifestProvider: {
+        name: '',
+        fileName: '',
+        /** Recognizes nothing, which is the point: `Manifest.read` falls through to its own empty
+         *  manifest exactly as it does when no plugin answers. */
+        read: () => undefined,
+        write: () => undefined,
+    },
+});
 /**
- * One config's `plugins`, in declaration order.
+ * **Marks an object as declared through one of the factories below**, so `loadPlugins` can tell a
+ * 2.x contribution from anything else that happens to have the same shape.
  *
- * 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.
+ * It exists for one measured case, and there is no structural check that could replace it: an rman
+ * **1.x plugin was `{ name, init }`**, and under this split a 2.x plugin that only runs an `init`
+ * is *also* `{ name, init }`. They are indistinguishable by shape. The guard used to be
+ * `manifestProvider` being required - which only worked while the one type was both halves.
  *
- * `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.
+ * Non-enumerable, so it never reaches `JSON.stringify`, `rman config` or a `toEqual` diff, the same
+ * way `ORIGINS` and `PREVIOUS_VALUES` travel.
  *
- * **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.
+ * The cost, stated rather than hidden: a plain object literal in `plugins` is no longer accepted.
+ * `definePlatform`/`definePlugin` is one import and one call, and it is the explicit declaration
+ * that a runtime check needs - a type cannot reach a JavaScript config.
  *
- * **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.
+ * **A function rather than a `const`, and that is not a preference.** The file layout puts private
+ * declarations below the exported ones, and `basePlatform` is an exported const whose initializer
+ * *calls* `definePlatform` - so a `const DECLARED` below it sits in its temporal dead zone while the
+ * module is still evaluating. Measured: the whole suite failed to load with
+ * `ReferenceError: Cannot access 'DECLARED' before initialization`. A function declaration hoists,
+ * so the key is resolved when it is asked for instead of when the module reaches this line.
  *
- * 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.
+ * **`Symbol.for`, so two copies of rman in one process agree about the mark.** A per-module symbol
+ * would have a plugin declared against one copy refused by the other - with a message about rman
+ * 1.x plugins, which is the one explanation guaranteed to be wrong.
  */
-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);
+function declaredKey() {
+    return Symbol.for('rman.declared');
 }
-/** 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 };
+/** Stamps the mark, non-enumerably, and hands the object back. */
+function brand(value) {
+    Object.defineProperty(value, declaredKey(), { value: true, enumerable: false, configurable: true });
+    return value;
 }

package/core/publish-target.d.ts

@@ -0,0 +1,124 @@
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { PackageFilterOptions } from '../utils/package-filter.js';
+import type { RmanApplication } from './application.js';
+import type { Package } from './package.js';
+import type { Repository } from './repository.js';
+/**
+ * **Where a package's artifact ships, as a contribution.**
+ *
+ * `publish` used to be `rman-node`'s command, and that was backwards in a way worth stating: the
+ * command itself is about a *repository* - which packages are candidates, which versions are
+ * already out there, what order to push them in, what to print - and none of that is npm's. What is
+ * npm's is one answer to "is this version on the registry, and how do I push it", which is exactly
+ * the size of this interface. Docker publishing was in the core all along and could only be reached
+ * through a Node plugin's command; a Cargo repository could reach neither.
+ *
+ * So: the core ships `publish` and the `docker` target, the `node` built-in contributes `npm`, and a
+ * repository in any other ecosystem contributes its own without either package knowing about it.
+ *
+ * A target owns three things and no more:
+ *
+ * - **Which packages are its own by default** (`claims`) - see below.
+ * - **Its own CLI options**, merged into `publish`'s by the command. Every flag that only meant
+ *   something to npm (`--access`, `--tag`, `--otp`, `--registry`, `--userconfig`, `--contents`,
+ *   `--package-manager`) is declared here now instead of on a command the core would otherwise have
+ *   to know them all in advance.
+ * - **`getPlan`/`applyPlan`** - the same two-step shape every other rman service uses, and the
+ *   reason `--dry-run` and the confirmation prompt are the command's business rather than each
+ *   target's.
+ */
+export interface PublishTarget {
+    /** The name `publish.target` and `--target` use, and the label printed beside a package. */
+    readonly name: string;
+    /** One line for `--target`'s help - a reader asking `rman publish --help` in a polyglot
+     *  repository has no other way to find out which targets are even installed. */
+    readonly describe?: string;
+    /**
+     * This target's own flags, merged into `publish`'s options.
+     *
+     * Flat, not namespaced: `--tag` reads better than `--npm-tag`, and two targets colliding on a
+     * name is refused loudly by the command rather than resolved by a rule nobody would remember.
+     * Name a flag for the target when it genuinely belongs to one (`--docker-namespace`).
+     */
+    readonly options?: Record<string, RmanConfig.CommandOption>;
+    /**
+     * Whether a package that declares **no** `publish.target` at all ships here.
+     *
+     * Absent means never - the target is opt-in, which is what `docker` is. `npm`'s answer is
+     * `pkg.provider === 'node'`, and that is the fix for a real bug rather than a nicety: the default
+     * used to be a hardcoded `['npm']` in the core, so `rman list --json` reported
+     * `publishTargets: ["npm"]` for a Cargo package and `publish` treated it as an npm candidate.
+     * A default only the ecosystem can state had been written down by someone who could not know it.
+     */
+    claims?(pkg: Package): boolean;
+    /** What this target *would* do - never publishes. Called even under `--dry-run`, which is the
+     *  whole point of the split. */
+    getPlan(ctx: PublishTarget.Context): Promise<PublishTarget.Entry[]>;
+    /** Publishes every `'publish'` entry in `plan`, and returns what it did. */
+    applyPlan(ctx: PublishTarget.Context, plan: PublishTarget.Entry[]): Promise<PublishTarget.Entry[]>;
+}
+export declare namespace PublishTarget {
+    /**
+     * What a target is handed, once per call.
+     *
+     * `args` is the parsed argv, untyped on purpose: a target declared its own options, so it is the
+     * only thing that knows their names and types, and the core cannot be made to know them without
+     * becoming the thing this interface exists to stop it being.
+     */
+    interface Context {
+        readonly app: RmanApplication;
+        readonly repository: Repository;
+        /** The filters every target shares, read off argv once by the command. */
+        readonly options: Options;
+        /** The whole parsed argv - a target reads the options it declared out of this. */
+        readonly args: Record<string, any>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** A package with uncommitted local changes is excluded (`'skip'`) instead of aborting the
+         *  whole plan (`'error'`). */
+        ignoreDirty?: boolean;
+    }
+    /**
+     * One package's outcome for one target.
+     *
+     * `'skip'` and `'error'` differ in what they do to the run: an error aborts before anything is
+     * published, a skip is a package the plan deliberately leaves alone. A target may add fields of
+     * its own (docker carries the resolved image reference); `detail` is the one the command prints,
+     * so whatever a target wants shown beside a package goes there.
+     */
+    interface Entry {
+        package: Package;
+        version: string;
+        status: 'publish' | 'skip' | 'up-to-date' | 'error';
+        /** Printed after the package name - docker's resolved `<namespace>/<image>`, for instance. */
+        detail?: string;
+        reason?: string;
+    }
+}
+/**
+ * **A target's name, and deliberately not a union.**
+ *
+ * It was `'npm' | 'docker'`, the type half of a bug whose runtime half was a hardcoded `['npm']`
+ * default, so `rman list --json` reported `publishTargets: ["npm"]` for a Cargo package. Both are
+ * gone together - which targets exist is whatever the repository's plugins contribute
+ * (`RmanApplication.publishTargets`), so a union here would mean the core naming plugins it cannot
+ * know about, exactly as `Package.provider` must not.
+ *
+ * A name nothing implements is caught where the facts are, by `publish` itself, naming the targets
+ * this repository does have.
+ */
+export type PublishTargetName = string;
+/**
+ * The targets a package **declares**, or `undefined` when it declares none - which is not the same
+ * as an empty list, and the difference is what `claims` is asked about.
+ */
+export declare function declaredTargets(pkg: Package): string[] | undefined;
+/** Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ *  target's own `claims` decides when it does not. */
+export declare function shipsTo(pkg: Package, target: PublishTarget): boolean;
+/** Every registered target `pkg` ships to, in registration order. The single answer to "where does
+ *  this package go", so `publish` and `list --json` cannot disagree about it. */
+export declare function targetsOf(app: RmanApplication, pkg: Package): PublishTarget[];
+/** Names in a package's `publish.target` that no registered target answers to - a misconfiguration
+ *  that used to be caught by a `choices: ['npm', 'docker']` the core can no longer write down. */
+export declare function unknownTargets(app: RmanApplication, pkg: Package): string[];

package/core/publish-target.js

@@ -0,0 +1,30 @@
+/**
+ * The targets a package **declares**, or `undefined` when it declares none - which is not the same
+ * as an empty list, and the difference is what `claims` is asked about.
+ */
+export function declaredTargets(pkg) {
+    const declared = pkg.config.publish?.target;
+    if (declared === undefined)
+        return undefined;
+    return Array.isArray(declared) ? [...declared] : [declared];
+}
+/** Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ *  target's own `claims` decides when it does not. */
+export function shipsTo(pkg, target) {
+    const declared = declaredTargets(pkg);
+    return declared ? declared.includes(target.name) : !!target.claims?.(pkg);
+}
+/** Every registered target `pkg` ships to, in registration order. The single answer to "where does
+ *  this package go", so `publish` and `list --json` cannot disagree about it. */
+export function targetsOf(app, pkg) {
+    return app.publishTargets.all.filter(target => shipsTo(pkg, target));
+}
+/** Names in a package's `publish.target` that no registered target answers to - a misconfiguration
+ *  that used to be caught by a `choices: ['npm', 'docker']` the core can no longer write down. */
+export function unknownTargets(app, pkg) {
+    const declared = declaredTargets(pkg);
+    if (!declared)
+        return [];
+    const known = new Set(app.publishTargets.all.map(t => t.name));
+    return declared.filter(name => !known.has(name));
+}

package/core/registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * An ordered collection of contributions, held **on the application** rather than in a module.
+ *
+ * Every registry rman had was a module-level array (`const providers: Provider[] = []` in
+ * `manifest.ts`, `workspace.ts`, `bin-path.ts`, `run.service.ts`), which made it process-global:
+ * two repositories in one process shared it. The test suite needed a root hook emptying five of
+ * them before every single test, and without it whichever spec ran first decided the answer for
+ * the rest - so the core appeared to work in tests that had registered nothing.
+ *
+ * An instance per `RmanApplication` closes the whole class: a new application starts empty, and
+ * nothing has to be cleaned up afterwards - the root hook is deleted.
+ *
+ * **Registry, not service.** The distinction is multiplicity: a registry is for a question whose
+ * answer is the *sum* of what was contributed (every provider's bin directories, the first provider
+ * that recognizes a directory). A question with exactly one answer is a service, replaceable
+ * through `RmanApplication.getService`.
+ */
+export declare class Registry<T> implements Iterable<T> {
+    private readonly items;
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all(): readonly T[];
+    get size(): number;
+    /** Idempotent by identity: a plugin may both declare a contribution and register it itself, and
+     *  the same function arriving twice would make the registry lie about what is in it. */
+    add(item: T): this;
+    /** The first contribution `ask` gives an answer for - "first that recognizes it" resolution,
+     *  which is how a directory finds the manifest reader and the workspace layout that claim it. */
+    first<R>(ask: (item: T) => R | undefined): R | undefined;
+    [Symbol.iterator](): Iterator<T>;
+}

package/core/registry.js

@@ -0,0 +1,47 @@
+/**
+ * An ordered collection of contributions, held **on the application** rather than in a module.
+ *
+ * Every registry rman had was a module-level array (`const providers: Provider[] = []` in
+ * `manifest.ts`, `workspace.ts`, `bin-path.ts`, `run.service.ts`), which made it process-global:
+ * two repositories in one process shared it. The test suite needed a root hook emptying five of
+ * them before every single test, and without it whichever spec ran first decided the answer for
+ * the rest - so the core appeared to work in tests that had registered nothing.
+ *
+ * An instance per `RmanApplication` closes the whole class: a new application starts empty, and
+ * nothing has to be cleaned up afterwards - the root hook is deleted.
+ *
+ * **Registry, not service.** The distinction is multiplicity: a registry is for a question whose
+ * answer is the *sum* of what was contributed (every provider's bin directories, the first provider
+ * that recognizes a directory). A question with exactly one answer is a service, replaceable
+ * through `RmanApplication.getService`.
+ */
+export class Registry {
+    items = [];
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all() {
+        return this.items;
+    }
+    get size() {
+        return this.items.length;
+    }
+    /** Idempotent by identity: a plugin may both declare a contribution and register it itself, and
+     *  the same function arriving twice would make the registry lie about what is in it. */
+    add(item) {
+        if (!this.items.includes(item))
+            this.items.push(item);
+        return this;
+    }
+    /** The first contribution `ask` gives an answer for - "first that recognizes it" resolution,
+     *  which is how a directory finds the manifest reader and the workspace layout that claim it. */
+    first(ask) {
+        for (const item of this.items) {
+            const answer = ask(item);
+            if (answer !== undefined)
+                return answer;
+        }
+        return undefined;
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+}