rman 2.0.0-beta.2 → 2.0.0-beta.4

package/core/{merge-config.js → config/merge-config.js}

@@ -1,9 +1,10 @@
 import path from 'node:path';
+import { isPlainObject } from '@jsopen/objects';
 /** Where a repository keeps command modules of its own, as a glob or a list of them. */
 export const COMMANDS_KEY = 'commands';
 /** The keys whose string entries are globs, and so have to be anchored to the file that wrote
- *  them - see `anchorContributions`. The same three that always append. */
-const GLOB_KEYS = ['plugins', COMMANDS_KEY, 'publishTargets'];
+ *  them - see `anchorContributions`. The same four that always append. */
+const GLOB_KEYS = ['plugins', 'platforms', COMMANDS_KEY, 'publishTargets'];
 /**
  * Keys that **append rather than replace**, which is the only append rman has.
  *
@@ -34,7 +35,7 @@ const GLOB_KEYS = ['plugins', COMMANDS_KEY, 'publishTargets'];
  * Do not extend this list casually: a key that always appends can never be *un*-said by a closer
  * layer, which is only acceptable where the value is a set of contributions rather than a decision.
  */
-export const ALWAYS_APPEND = ['plugins', COMMANDS_KEY, 'publishTargets'];
+export const ALWAYS_APPEND = ['plugins', 'platforms', COMMANDS_KEY, 'publishTargets'];
 /**
  * Where a key keeps what it is replacing, so the replacement can be handed it back as `value`.
  *
@@ -257,8 +258,3 @@ function anchorContributions(value, origin) {
 function looksLikePackageName(entry) {
     return /^(?:@[a-z0-9-~][\w.-]*\/)?[a-z0-9-~][\w.-]*$/i.test(entry) && !/\.[cm]?js$/i.test(entry);
 }
-/** A config object, as opposed to an array or anything with its own prototype - only the former
- *  merges key by key. */
-function isPlainObject(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value);
-}

package/core/{custom-command.d.ts → interfaces/custom-command.d.ts}

@@ -1,9 +1,9 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
-import type { RmanConfig as CommandDeclaration } from '../interfaces/rman-config.interface.js';
-import type { Logger } from '../utils/logger.js';
-import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
-import type { Package } from './package.js';
-import type { Repository } from './repository.js';
+import type { RmanConfig as CommandDeclaration } from '../../interfaces/rman-config.interface.js';
+import type { Logger } from '../../utils/logger.js';
+import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
+import type { Package } from '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export declare const CUSTOM_COMMAND_DIR = ".rman";
 /**

package/core/{manifest.d.ts → interfaces/manifest.d.ts}

@@ -1,7 +1,7 @@
-import { RmanApplication } from './application.js';
-import type { Package } from './package.js';
+import { RmanApplication } from '../application.js';
+import type { Package } from '../classes/package.js';
+import { type VersionScheme } from '../classes/version-scheme.js';
 import type { Platform } from './plugin.js';
-import { type VersionScheme } from './version-scheme.js';
 /**
  * A package's identity, however its ecosystem happens to record it.
  *

package/core/{manifest.js → interfaces/manifest.js}

@@ -1,6 +1,6 @@
 import path from 'node:path';
-import { RmanApplication } from './application.js';
-import { semverScheme } from './version-scheme.js';
+import { RmanApplication } from '../application.js';
+import { semverScheme } from '../classes/version-scheme.js';
 /**
  * The registry, merged onto the `Manifest` interface so one name carries both the shape and the
  * operations - `Manifest.read(dir)` returns a `Manifest`.

package/core/{plugin.d.ts → interfaces/plugin.d.ts}

@@ -1,9 +1,10 @@
-import type { RunService } from '../services/run.service.js';
-import type { VersionPlanService } from '../services/version-plan.service.js';
-import type { BinPath } from '../utils/bin-path.js';
-import type { RmanApplication } from './application.js';
+import type { RunService } from '../../services/run.service.js';
+import type { VersionPlanService } from '../../services/version-plan.service.js';
+import type { BinPath } from '../../utils/bin-path.js';
+import type { RmanApplication } from '../application.js';
+import type { Repository } from '../classes/repository.js';
+import type { Workspace } from '../classes/workspace.js';
 import type { ManifestProvider } from './manifest.js';
-import type { Workspace } from './workspace.js';
 /**
  * **One technology, as a whole** - Node, Cargo, Maven. Everything rman needs in order to treat a
  * directory as a package of that technology.
@@ -93,45 +94,61 @@ export interface Platform {
  */
 export interface Plugin {
     /** How this plugin is named in messages, and the de-duplication key: registering twice under one
-     *  name is refused. A platform contributed by it keeps its *own* name, which is what a package
-     *  reports as `pkg.platform`. */
+     *  name is refused. */
     name: string;
-    /** The technologies this plugin provides, if any. */
-    platforms?: Platform[];
     /**
-     * Anything this plugin contributes that is not a platform, run once when it is registered.
+     * Run once the application exists and this plugin is on it, **before anything has been
+     * discovered** - no packages, no configs, no repository.
      *
-     * **The escape hatch, not the front door.** Commands and publish targets are `.rmanrc` keys
-     * (`commands`, `publishTargets`), so a plugin contributing only those declares them in its own
-     * config and needs no `init` at all. What is left for `init` is whatever the seams do not name
-     * yet, reached through `ctx.app`.
+     * This is where a plugin registers what the config keys have no word for: a service, a seam the
+     * core does not name yet. Reached through `ctx.app`.
+     */
+    afterInitApplication?(ctx: PluginContext): void | Promise<void>;
+    /**
+     * Run once the repository is **resolved** - every package found, every config baked, the
+     * dependency graph linked.
      *
-     * **It runs inside `Repository.create`**, before any package is known, so `ctx.app.repository`
-     * throws there. Anything wanting the repository belongs in a command's factory instead, which
-     * runs once there is one.
+     * The stage `afterInitApplication` cannot reach: that one runs inside `Repository.create` before
+     * any package is known, so `ctx.app.repository` throws there.
      */
-    init?(ctx: PluginContext): void | Promise<void>;
+    afterInitRepository?(ctx: PluginRepositoryContext): void | Promise<void>;
+}
+export declare namespace Plugin {
+    /** What a value was declared as - see {@link declaredKind}. */
+    type DeclaredKind = 'platform' | 'plugin';
 }
 /**
- * What `Plugin.init` is handed.
+ * What {@link Plugin.afterInitApplication} is handed.
  *
- * Only the application today. An object rather than a bare parameter so a member added later
- * breaks nothing already written against it - the same reason `CommandContext` is one, which has
- * already paid for itself twice.
+ * An object rather than a bare parameter so a member added later breaks nothing already written
+ * against it - the same reason `CommandContext` is one, which has already paid for itself twice.
  */
 export interface PluginContext {
     app: RmanApplication;
 }
+/** What {@link Plugin.afterInitRepository} is handed - the application, plus the repository that now
+ *  exists. */
+export interface PluginRepositoryContext extends PluginContext {
+    repository: Repository;
+}
+/**
+ * **What `value` was declared as**, or `undefined` for anything that was not - a plain object, an
+ * arbitrary module export, a config.
+ */
+export declare function declaredKind(value: unknown): Plugin.DeclaredKind | undefined;
 /** Whether `value` came from `definePlatform` or `definePlugin`. */
 export declare function isDeclared(value: unknown): boolean;
 /** Declares a **platform** - one technology, whole. Returns it unchanged apart from the mark. */
 export declare function definePlatform(platform: Platform): Platform;
-/** Declares a **plugin** - whatever a package contributes, platforms included. Returns it unchanged
- *  apart from the mark. */
+/** Declares a **plugin** - a name and whatever it wants to do at one of the two stages. Returns
+ *  it unchanged apart from the mark. */
 export declare function definePlugin(plugin: Plugin): 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 declare function isPlatform(value: Plugin | Platform): value is Platform;
+/**
+ * Whether `value` is a platform - **what it was declared as**, not what it looks like.
+ */
+export declare function isPlatform(value: unknown): value is Platform;
+/** Whether `value` is a plugin - again by declaration, so a platform is not one. */
+export declare function isPlugin(value: unknown): value is Plugin;
 /**
  * The platform a package gets when **none** claimed its directory - a repository naming no
  * platform, or a directory none of the named ones recognized.

package/core/{plugin.js → interfaces/plugin.js}

@@ -1,20 +1,58 @@
+/**
+ * **What `value` was declared as**, or `undefined` for anything that was not - a plain object, an
+ * arbitrary module export, a config.
+ */
+/* **One mark carrying the kind, rather than one mark per type.** The mark used to be `true`, so it
+ * could answer *whether* something was declared and never *what* - which left `isPlatform` testing
+ * for `manifestProvider`, a structural guess, and left the loader unable to say the one useful
+ * thing about the commonest mistake: that a platform was put in `plugins`.
+ *
+ * A symbol per type was the alternative and this is the same information for less machinery. The
+ * key has to be a **hoisted function** (see `declaredKey`), which is a trap every additional key
+ * would repeat; `isDeclared` stays one lookup instead of an OR someone has to remember to extend;
+ * and a third declarable slots in as a new string - `publishTargets` is checked structurally today
+ * (`typeof target.name === 'string'`) and is the obvious next one, though nothing is being built
+ * for it here.
+ *
+ * **The value was `true` before this**, and `Symbol.for` is shared - so an object marked by an
+ * older copy of rman in the same process now reads as undeclared. 2.0 is unreleased and the mark
+ * is 2.x's own, so there is nothing in the field to be compatible with. */
+export function declaredKind(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const kind = value[declaredKey()];
+    return kind === 'platform' || kind === 'plugin' ? kind : undefined;
+}
 /** Whether `value` came from `definePlatform` or `definePlugin`. */
 export function isDeclared(value) {
-    return !!value && typeof value === 'object' && value[declaredKey()] === true;
+    return declaredKind(value) !== undefined;
 }
 /** Declares a **platform** - one technology, whole. Returns it unchanged apart from the mark. */
 export function definePlatform(platform) {
-    return brand(platform);
+    return brand(platform, 'platform');
 }
-/** Declares a **plugin** - whatever a package contributes, platforms included. Returns it unchanged
- *  apart from the mark. */
+/** Declares a **plugin** - a name and whatever it wants to do at one of the two stages. Returns
+ *  it unchanged apart from the mark. */
 export function definePlugin(plugin) {
-    return brand(plugin);
+    return brand(plugin, '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`. */
+/**
+ * Whether `value` is a platform - **what it was declared as**, not what it looks like.
+ */
+/* It used to ask whether `manifestProvider` was present, which was the only test available while
+ * one type was both halves. As a question about an arbitrary import that is a guess, and it gets
+ * the commonest mistake exactly backwards: a config object carrying a `manifestProvider`-shaped key
+ * would pass, and a platform someone forgot to declare would be reported as an rman 1.x plugin.
+ *
+ * The cost, stated: an undeclared platform-shaped object is no longer a platform. Everything
+ * arriving through a config has to be declared anyway, and every `registerPlugin` caller in the
+ * tree passes a `definePlatform(...)` result. */
 export function isPlatform(value) {
-    return !!value.manifestProvider;
+    return declaredKind(value) === 'platform';
+}
+/** Whether `value` is a plugin - again by declaration, so a platform is not one. */
+export function isPlugin(value) {
+    return declaredKind(value) === 'plugin';
 }
 /**
  * The platform a package gets when **none** claimed its directory - a repository naming no
@@ -80,7 +118,7 @@ function declaredKey() {
     return Symbol.for('rman.declared');
 }
 /** Stamps the mark, non-enumerably, and hands the object back. */
-function brand(value) {
-    Object.defineProperty(value, declaredKey(), { value: true, enumerable: false, configurable: true });
+function brand(value, kind) {
+    Object.defineProperty(value, declaredKey(), { value: kind, enumerable: false, configurable: true });
     return value;
 }

package/core/{publish-target.d.ts → interfaces/publish-target.d.ts}

@@ -1,8 +1,8 @@
-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';
+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 '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
 /**
  * **Where a package's artifact ships, as a contribution.**
  *
@@ -41,14 +41,24 @@ export interface PublishTarget {
      * Name a flag for the target when it genuinely belongs to one (`--docker-namespace`).
      */
     readonly options?: Record<string, RmanConfig.CommandOption>;
+    /**
+     * The technologies this target is for, by `Platform.name` - `['node']` for `npm`. Absent means
+     * every platform, which is what a technology-agnostic target says: any package can carry a
+     * Dockerfile, so `docker` declares none.
+     *
+     * On its own it is the whole of `claims`: a package of one of these platforms that declares no
+     * `publish.target` ships here. With `claims` beside it, this narrows first and `claims` decides
+     * within.
+     *
+     * The same word `CommandMetadata.platforms` uses, and the same question.
+     */
+    readonly platforms?: string[];
     /**
      * 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.
+     * Absent means never - the target is opt-in, which is what `docker` is - unless `platforms` says
+     * otherwise, in which case that is the answer. Present, it decides for the packages `platforms`
+     * let through.
      */
     claims?(pkg: Package): boolean;
     /** What this target *would* do - never publishes. Called even under `--dry-run`, which is the
@@ -113,8 +123,10 @@ export type PublishTargetName = string;
  * 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. */
+/**
+ * Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ * target's `platforms`/`claims` decide 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. */

package/core/{publish-target.js → interfaces/publish-target.js}

@@ -8,11 +8,24 @@ export function declaredTargets(pkg) {
         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. */
+/**
+ * Whether `pkg` ships to `target`: its own `publish.target` decides when it has one, and the
+ * target's `platforms`/`claims` decide when it does not.
+ */
+/* **A declared `publish.target` is the last word**, and neither `platforms` nor `claims` is asked
+ * after it - a package naming a target has said where it goes, whatever ecosystem it is. Narrowing
+ * that would turn a default into a rule about who may say what. */
 export function shipsTo(pkg, target) {
     const declared = declaredTargets(pkg);
-    return declared ? declared.includes(target.name) : !!target.claims?.(pkg);
+    if (declared)
+        return declared.includes(target.name);
+    /** `platforms` narrows first; `claims` decides within what it let through. With only `platforms`,
+     *  belonging to one of them *is* the claim; with neither, the target is opt-in. */
+    if (target.platforms?.length && !target.platforms.includes(pkg.provider))
+        return false;
+    if (target.claims)
+        return target.claims(pkg);
+    return !!target.platforms?.length;
 }
 /** 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. */

package/core/{run-step.d.ts → interfaces/run-step.d.ts}

@@ -1,7 +1,7 @@
-import type { Logger } from '../utils/logger.js';
-import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
-import type { Package } from './package.js';
-import type { Repository } from './repository.js';
+import type { Logger } from '../../utils/logger.js';
+import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
+import type { Package } from '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
 /**
  * What a **function step** is handed - a `run.<script>.before`/`.exec`/`.after` or a
  * `version.<slot>` written as JavaScript instead of a shell command, and the `if` deciding whether

package/core/plugin-loader.d.ts

@@ -1,61 +1,21 @@
-import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 import type { RmanApplication } from './application.js';
-import { type Platform, type Plugin } from './plugin.js';
+import { type Platform, type Plugin } from './interfaces/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`.
+ * **Puts one contribution onto an application** - a technology, or a plugin - and the only place
+ * that knows how.
  *
- * **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:
+ * **Exported because a spec must not reimplement it.** A fixture writing the registrations 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.
  *
- * - **`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.
+ * **Neither hook is called here, and that is deliberate.** `afterInitApplication` and
+ * `afterInitRepository` belong to `Repository.create`, which knows when each stage is reached and
+ * can await them; this is a synchronous call a fixture makes while building an application.
  */
+export declare function registerPlugin(app: RmanApplication, entry: Plugin | Platform): void;
 export declare function checkCustomCommand<T extends {
     command?: string;
     describe?: unknown;