rman 1.3.0 → 2.0.0-beta.3

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

@@ -1,5 +1,7 @@
-import type { Package } from './package.js';
-import { type VersionScheme } from './version-scheme.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';
 /**
  * A package's identity, however its ecosystem happens to record it.
  *
@@ -13,7 +15,7 @@ export interface Manifest {
     /** Excluded from publishing by the package's own declaration (`package.json#private`). Not the
      *  same as `.rmanrc "publish.skip"`, which is the *repository's* declaration about it. */
     private?: boolean;
-    /** The document as the ecosystem wrote it. `rman-node`'s own commands read `package.json` fields
+    /** The document as the ecosystem wrote it. The `node` built-in's own commands read `package.json` fields
      *  the core has no opinion about (`scripts`, `publishConfig`, `engines`) off this. */
     raw: any;
 }
@@ -23,7 +25,7 @@ export interface Manifest {
  * **The core has no provider.** "The name and version live in a `package.json`" is true of npm and
  * of nothing else - a `Cargo.toml`, a `pyproject.toml` and a `go.mod` each say the same thing
  * differently, and the version is not even in the same *kind* of place in all of them.
- * `rman-node` contributes the `package.json` one.
+ * The `node` built-in contributes the `package.json` one.
  *
  * Paired with `VersionScheme` on purpose: the ecosystem that decides *where* a version is written
  * is the one that decides *how* it is numbered, so a provider supplies both and a package gets a
@@ -32,7 +34,7 @@ export interface Manifest {
 export interface ManifestProvider {
     /**
      * **The ecosystem this provider speaks for**, surfaced on every package it reads as
-     * `Package.provider` - `'node'` for `rman-node`. Short and about the technology, not about the
+     * `Package.provider` - `'node'` for the built-in of that name. Short and about the technology, not about the
      * file: `fileName` already says `package.json`, and a name repeating it would tell a caller
      * nothing it did not have.
      *
@@ -124,6 +126,23 @@ export interface ManifestProvider {
         scope?: string;
         unscopedName: string;
     };
+    /**
+     * **What addresses this package** - what a `"[glob]"` block and `--scope`/`--ignore` match
+     * against, and what has to be unique within a repository.
+     *
+     * **The platform's job, because a name is an ecosystem's promise and not rman's.** npm guarantees
+     * `package.json#name` exists and identifies the package, so the node built-in has nothing to do
+     * here and the default - the manifest's own name - is already its answer. An ecosystem where a
+     * package need not be named, or where the name is not unique, returns `undefined` and the
+     * repository assigns one with `.rmanrc "name"`.
+     *
+     * Separate from `Manifest.name`, which is what the package *calls itself*: those coincide for npm
+     * and need not anywhere else. A Go module's name is an import path, and `--scope github.com/x/y`
+     * is not how anyone would want to address it.
+     *
+     * Omit it and the manifest's name is used, so this seam existing changes nothing.
+     */
+    selector?(manifest: Manifest, dir: string): string | undefined;
     /**
      * Rewrites this manifest's references to in-repo packages that just got a new version.
      *
@@ -147,35 +166,37 @@ export interface ManifestProvider {
  *
  * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
  * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
- * `rman-node` already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * the `node` built-in already adds to `SystemInfo`, and anything this seam grows later can arrive the
  * same way instead of as another top-level export.
  */
 export declare namespace Manifest {
-    /** Registers a provider. Called by `loadPlugins` for each plugin's `manifest`, in `plugins`
-     *  declaration order - so which one answers is a function of the repository's own config. */
-    function addProvider(provider: ManifestProvider): void;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders(): void;
     /**
-     * Reads `dir`'s manifest through the first provider that recognizes it, with the scheme that
-     * provider brings.
-     *
-     * **With no provider registered, or none recognizing the directory**, the fallback is a package
-     * named after its own directory at version `0.0.0`. That is deliberately the least it can claim:
-     * the directory name is a fact, and `0.0.0` is the version a thing has when nothing says
-     * otherwise. The alternative - refusing to construct a package at all - would make `rman info` and
-     * `rman list` fail in a repository whose `.rmanrc` simply names no plugin yet, which is exactly
-     * when someone needs to run them.
+     * Reads `dir`'s manifest through **the platform that already claimed it**, with the scheme that
+     * platform brings.
+     *
+     * **It takes a platform rather than searching for one**, and that is where the walk changed
+     * things. This used to loop over every registered platform, once per `Package` constructed - so a
+     * package asked "who am I?" and the answer was whoever recognized it first, re-derived at every
+     * construction. The walk decides it once per directory now (`Workspace.walk` ->
+     * `app.platformFor`) and hands it to the package, which is also what lets a nested Cargo package
+     * sit inside a Node monorepo: the platform is a fact about the directory, established by whoever
+     * found it, not re-guessed by whoever reads it.
+     *
+     * **When that platform reads nothing** - `basePlatform`, or a provider that claimed the directory
+     * and then found nothing in it - the fallback is a package named after its own directory at
+     * version `0.0.0`. Deliberately the least it can claim: the directory name is a fact, and `0.0.0`
+     * is the version a thing has when nothing says otherwise. The alternative - refusing to construct
+     * a package at all - would make `rman info` and `rman list` fail in a repository whose `.rmanrc`
+     * simply names no plugin yet, which is exactly when someone needs to run them.
      */
-    function read(dir: string): {
+    function read(platform: Platform, dir: string): {
         manifest: Manifest;
         versionScheme: VersionScheme;
         fileName: string;
-        provider: string;
     };
     /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
      *  nowhere is worse than one that fails, since the caller has already decided the new version. */
-    function write(dir: string, manifest: Manifest): void;
+    function write(app: RmanApplication, dir: string, manifest: Manifest): void;
     /**
      * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
      *
@@ -186,7 +207,7 @@ export declare namespace Manifest {
     function dependenciesOf(pkg: Package, candidates: readonly Package[]): Package[];
     /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
      *  "no scope, the name is its own unscoped form" when none has an opinion. */
-    function splitName(dir: string, name: string): {
+    function splitName(app: RmanApplication, dir: string, name: string): {
         scope?: string;
         unscopedName: string;
     };
@@ -199,7 +220,7 @@ export declare namespace Manifest {
     function updateDependencyVersions(pkg: Package, bumped: ReadonlyMap<Package, string>): void;
     /**
      * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
-     * `ManifestProvider.stampVersion`.
+     * `Plugin.stampVersion`.
      *
      * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
      * provider claimed the package, the provider has no opinion about stamping, or it looked and found
@@ -217,6 +238,7 @@ export declare namespace Manifest {
      * plugin: git tags then answer the boundary question alone.
      */
     function publishedVersion(pkg: Package): Promise<string | undefined>;
-    /** The file names providers look for, for an error message that can say what was expected. */
-    function fileNames(): string[];
+    /** The file names the registered technologies look for, for an error message that can say what
+     *  was expected. */
+    function fileNames(app: RmanApplication): string[];
 }

package/core/interfaces/manifest.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+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`.
+ *
+ * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
+ * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
+ * the `node` built-in already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * same way instead of as another top-level export.
+ */
+export var Manifest;
+(function (Manifest) {
+    /**
+     * Reads `dir`'s manifest through **the platform that already claimed it**, with the scheme that
+     * platform brings.
+     *
+     * **It takes a platform rather than searching for one**, and that is where the walk changed
+     * things. This used to loop over every registered platform, once per `Package` constructed - so a
+     * package asked "who am I?" and the answer was whoever recognized it first, re-derived at every
+     * construction. The walk decides it once per directory now (`Workspace.walk` ->
+     * `app.platformFor`) and hands it to the package, which is also what lets a nested Cargo package
+     * sit inside a Node monorepo: the platform is a fact about the directory, established by whoever
+     * found it, not re-guessed by whoever reads it.
+     *
+     * **When that platform reads nothing** - `basePlatform`, or a provider that claimed the directory
+     * and then found nothing in it - the fallback is a package named after its own directory at
+     * version `0.0.0`. Deliberately the least it can claim: the directory name is a fact, and `0.0.0`
+     * is the version a thing has when nothing says otherwise. The alternative - refusing to construct
+     * a package at all - would make `rman info` and `rman list` fail in a repository whose `.rmanrc`
+     * simply names no plugin yet, which is exactly when someone needs to run them.
+     */
+    function read(platform, dir) {
+        const provider = platform.manifestProvider;
+        const manifest = provider.read(dir);
+        return {
+            manifest: manifest ?? { name: path.basename(dir), version: '0.0.0', raw: {} },
+            versionScheme: provider.versionScheme ?? semverScheme,
+            /** Nothing read means nothing to name - a caller listing "the file I changed" has no file to
+             *  list, which is correct rather than a placeholder that does not exist. */
+            fileName: manifest ? provider.fileName : '',
+        };
+    }
+    Manifest.read = read;
+    /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
+     *  nowhere is worse than one that fails, since the caller has already decided the new version. */
+    function write(app, dir, manifest) {
+        for (const platform of app.platforms) {
+            if (platform.manifestProvider.read(dir)) {
+                platform.manifestProvider.write(dir, manifest);
+                return;
+            }
+        }
+        throw new Error(`No manifest provider recognizes "${dir}", so there is nowhere to write its version.\n` +
+            `  A repository's ".rmanrc" names its technologies - see "plugins" (e.g. ['node']).`);
+    }
+    Manifest.write = write;
+    /**
+     * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
+     *
+     * No provider, or one with no opinion, means no declared dependencies - `.rmanrc "dependencies"`
+     * is then the only source, which is exactly right: a repository rman cannot read the manifests
+     * of can still describe its own graph by hand.
+     */
+    function dependenciesOf(pkg, candidates) {
+        return platformOf(pkg)?.manifestProvider.dependencies?.(pkg.manifest, candidates) ?? [];
+    }
+    Manifest.dependenciesOf = dependenciesOf;
+    /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
+     *  "no scope, the name is its own unscoped form" when none has an opinion. */
+    function splitName(app, dir, name) {
+        for (const platform of app.platforms) {
+            if (!platform.manifestProvider.read(dir))
+                continue;
+            return platform.manifestProvider.splitName?.(name) ?? { unscopedName: name };
+        }
+        return { unscopedName: name };
+    }
+    Manifest.splitName = splitName;
+    /**
+     * Refreshes `pkg`'s references to the packages in `bumped`, via whichever provider recognizes it.
+     *
+     * No provider, or one without an opinion, means nothing to rewrite - a repository whose packages
+     * reference each other by path has nothing here to go stale.
+     */
+    function updateDependencyVersions(pkg, bumped) {
+        platformOf(pkg)?.manifestProvider.updateDependencyVersions?.(pkg.manifest, bumped);
+    }
+    Manifest.updateDependencyVersions = updateDependencyVersions;
+    /**
+     * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
+     * `Plugin.stampVersion`.
+     *
+     * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
+     * provider claimed the package, the provider has no opinion about stamping, or it looked and found
+     * nothing to change. All three mean "this file was not stamped", which is what `version` reports.
+     */
+    function stampVersion(pkg, file, content, version, options) {
+        return platformOf(pkg)?.manifestProvider.stampVersion?.(file, content, version, options);
+    }
+    Manifest.stampVersion = stampVersion;
+    /**
+     * What `pkg`'s own ecosystem's registry says its current version is - see
+     * `ManifestProvider.publishedVersion` for the one thing this is for and the one thing it must
+     * never be used for.
+     *
+     * `undefined` when the provider has no opinion, which includes every repository that names no
+     * plugin: git tags then answer the boundary question alone.
+     */
+    async function publishedVersion(pkg) {
+        return platformOf(pkg)?.manifestProvider.publishedVersion?.(pkg);
+    }
+    Manifest.publishedVersion = publishedVersion;
+    /** The file names the registered technologies look for, for an error message that can say what
+     *  was expected. */
+    function fileNames(app) {
+        return [...app.platforms].map(platform => platform.manifestProvider.fileName);
+    }
+    Manifest.fileNames = fileNames;
+    /**
+     * The technology that claimed `pkg`, or `undefined` when none did - with nothing to look up.
+     *
+     * This used to search a registry by `pkg.provider` and fall back to re-reading the directory,
+     * because a package could be constructed before the provider that would claim it was registered.
+     * It cannot now: a package is handed its `Platform` at construction, by the application that
+     * resolved it. The `name` test is what "none claimed it" looks like - see `basePlatform`.
+     */
+    function platformOf(pkg) {
+        return pkg.platform.name ? pkg.platform : undefined;
+    }
+})(Manifest || (Manifest = {}));

package/core/interfaces/plugin.d.ts

@@ -0,0 +1,174 @@
+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';
+/**
+ * **One technology, as a whole** - Node, Cargo, Maven. Everything rman needs in order to treat a
+ * directory as a package of that technology.
+ *
+ * **This was called `Plugin`, and the name was a lie.** `manifestProvider` is required, which makes
+ * the type a *platform* by definition: a package that only ships commands never touches it, because
+ * commands are a config key. So the narrow thing took the narrow name, and `Plugin` became the
+ * broad one that may carry platforms - a plugin *provides* platforms, and may provide more than
+ * one (a package shipping both `maven` and `gradle` is one plugin, two platforms).
+ *
+ * These were six independent fields on a plugin, each with its own registry, and declaring one
+ * without the others type-checked. It is not a shape that admits sense: `getRunSteps` reads
+ * `pkg.manifest.raw?.scripts`, so contributing npm's step source without npm's manifest reader
+ * leaves it parsing whatever another technology produced. The coupling was already real; only the
+ * type failed to say so.
+ *
+ * **`RmanPlugin` and `TechStack` used to be two types and are now one.** The plugin existed solely to
+ * *register* the stack - its whole `init` was `ctx.addTechStack(...)` plus a command or two - and
+ * once a config carries commands and publish targets itself, that registration step has nothing
+ * left to do. What remains of a plugin is the technology, so that is what the type is.
+ *
+ * **`manifestProvider` stays grouped rather than flattened in here**, and it was tried the other
+ * way first: nine members about one file - reading it, writing it, what it declares, how its
+ * versions are numbered, stamped and looked up on a registry - are more legible as a named group
+ * than as nine siblings of `getBinPaths`. The name also keeps its distance from `Package.manifest`,
+ * which is the *data* this produces rather than the reader.
+ *
+ * **Everything optional is answered by its absence**, never by a default rman invented - see
+ * `basePlatform`.
+ */
+export interface Platform {
+    /**
+     * **The ecosystem this speaks for**, surfaced on every package it reads as `Package.platform` -
+     * `'node'` for the built-in of that name. Short and about the technology, not about the file:
+     * `manifestProvider.fileName` already says `package.json`, and a name repeating it would tell a
+     * caller nothing it did not have.
+     *
+     * This is what lets code that *does* know one ecosystem check before acting on a package -
+     * `if (pkg.platform === 'node')` - which matters most in a repository holding more than one,
+     * since a manifest is read per directory and two packages can legitimately answer to different
+     * technologies. It is also the de-duplication key: registering twice under one name is refused,
+     * because it would define the same commands twice and yargs does not survive that.
+     */
+    name: string;
+    /** Where this technology's packages keep their identity, and how to change it - reading and
+     *  writing the manifest, what it declares as dependencies, how its versions are numbered,
+     *  stamped, and looked up on a registry. */
+    manifestProvider: ManifestProvider;
+    /** Where this technology's packages are, given the repository root - npm reads `workspaces`,
+     *  Cargo a `[workspace] members`. `undefined` when it does not recognize the root. */
+    getWorkspace?: Workspace.Provider;
+    /** Directories to put in front of a child process's PATH, so a command an author wrote
+     *  (`eslint .`) runs the repository's pinned copy - `node_modules/.bin` walked up the tree, for
+     *  npm. Every plugin contributes, unlike the seams above where the first answer wins: a PATH is
+     *  a list, and a polyglot repository wants both ecosystems' binaries reachable. */
+    getBinPaths?: BinPath.Provider;
+    /**
+     * What the *package itself* declares for a lifecycle script, from this technology's own files -
+     * npm's `package.json` `scripts`, with `pre<script>`/`<script>`/`post<script>`.
+     *
+     * **A query, not a hook, and not build-specific** - which is why it is `getRunSteps` rather than
+     * anything beginning `on`. It returns what the package declares and rman decides what to do with
+     * it; `run`/`build`/`test` ask, and so does `version`, whose `preversion`/`version`/`postversion`
+     * are the same shape (`runLifecycleSlot` -> `contributedSlots`). A name mentioning `build` would
+     * have been wrong about half its callers.
+     */
+    getRunSteps?: RunService.StepSource;
+    /** How this technology's releases are planned - where a package's change boundary comes from
+     *  when it has no release tag, and how far into its group a bump reaches. */
+    versionPlanner?: VersionPlanService;
+}
+/**
+ * **A plugin is whatever a package contributes; a platform is one of the things it can contribute.**
+ *
+ * The broad half of the split. `Platform` is a technology and nothing else - required manifest
+ * reader, workspace layout, bin paths, steps, version planning. What is left over is this: an
+ * `init` for whatever the seams do not name yet, and the **declaration** that this plugin provides
+ * platforms.
+ *
+ * **`platforms` is a list, and that is not symmetry.** One package can speak for more than one
+ * technology - `maven` and `gradle` are the same toolchain family and a single plugin shipping both
+ * is the natural shape. A singular field would have made the second one a separate package for no
+ * reason.
+ *
+ * A bare `Platform` is accepted anywhere a `Plugin` is, as sugar for `{ name, platforms: [it] }` -
+ * which is what almost every entry is.
+ */
+export interface Plugin {
+    /** How this plugin is named in messages, and the de-duplication key: registering twice under one
+     *  name is refused. */
+    name: string;
+    /**
+     * Run once the application exists and this plugin is on it, **before anything has been
+     * discovered** - no packages, no configs, no repository.
+     *
+     * 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.
+     *
+     * The stage `afterInitApplication` cannot reach: that one runs inside `Repository.create` before
+     * any package is known, so `ctx.app.repository` throws there.
+     */
+    afterInitRepository?(ctx: PluginRepositoryContext): void | Promise<void>;
+}
+export declare namespace Plugin {
+    /** What a value was declared as - see {@link declaredKind}. */
+    type DeclaredKind = 'platform' | 'plugin';
+}
+/**
+ * What {@link Plugin.afterInitApplication} is handed.
+ *
+ * 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** - 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 - **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.
+ *
+ * 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.
+ *
+ * **Every documented behaviour of "no plugin" survives unchanged**, because the absences are the
+ * behaviour:
+ *
+ * - 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 declare const basePlatform: Platform;

package/core/interfaces/plugin.js

@@ -0,0 +1,124 @@
+/**
+ * **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 declaredKind(value) !== undefined;
+}
+/** Declares a **platform** - one technology, whole. Returns it unchanged apart from the mark. */
+export function definePlatform(platform) {
+    return brand(platform, 'platform');
+}
+/** 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, 'plugin');
+}
+/**
+ * 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 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
+ * platform, or a directory none of the named ones recognized.
+ *
+ * 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.
+ *
+ * **Every documented behaviour of "no plugin" survives unchanged**, because the absences are the
+ * behaviour:
+ *
+ * - 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 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,
+    },
+});
+/**
+ * **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.
+ *
+ * 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.
+ *
+ * Non-enumerable, so it never reaches `JSON.stringify`, `rman config` or a `toEqual` diff, the same
+ * way `ORIGINS` and `PREVIOUS_VALUES` travel.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * **`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 declaredKey() {
+    return Symbol.for('rman.declared');
+}
+/** Stamps the mark, non-enumerably, and hands the object back. */
+function brand(value, kind) {
+    Object.defineProperty(value, declaredKey(), { value: kind, enumerable: false, configurable: true });
+    return value;
+}