rman 1.3.0 → 2.0.0-beta.2

package/core/version-scheme.js

@@ -6,7 +6,7 @@ import semver from 'semver';
  * "is this version on the registry yet", `"workspace:"` range rewriting all assume versions that
  * can be ordered and incremented. This is the seam for an ecosystem that numbers differently (PEP
  * 440, a date-based scheme, a build counter), and it is a *meaning* seam rather than a storage one:
- * `ManifestProvider` answers "where is the version written", this answers "what does the next one
+ * `Plugin`'s manifest members answers "where is the version written", this answers "what does the next one
  * look like".
  *
  * **`bumpNames` and `bumpFor` are the interesting part.** `fix:` -> patch, `feat:` -> minor,
@@ -25,6 +25,23 @@ import semver from 'semver';
  * `SemverScheme` to keep semver's numbering and change only one of these.
  */
 export class VersionScheme {
+    /**
+     * Which prerelease line this version belongs to - `'beta'` for `2.0.0-beta.1` - or `undefined`
+     * when it is not a preview, or is one with no identifier to name (`2.0.0-1`).
+     *
+     * **The one thing a preview needs beyond "is it one", and it is a *name*, which is why it is
+     * here rather than read out of the version with a regex by whoever wants it.** npm's publish
+     * target derives its dist-tag from this, so a beta lands on `beta` instead of on `latest`; the
+     * identifier is written in the version itself, so that is a reading rather than a guess.
+     *
+     * Implemented, not abstract, and returning `undefined` by default: a scheme whose previews have
+     * no name (or which has no previews at all) is answering honestly, and the caller's job is to
+     * say so rather than invent one. `SemverScheme` overrides it.
+     */
+    prereleaseId(version) {
+        void version;
+        return undefined;
+    }
     /**
      * The highest of `versions` - a group's current version is the highest among its members, and a
      * monorepo root's release identity the highest among the groups.
@@ -117,6 +134,17 @@ export class SemverScheme extends VersionScheme {
     isPrerelease(version) {
         return !!semver.prerelease(version);
     }
+    /**
+     * semver's first prerelease identifier, when it is a word: `2.0.0-beta.1` -> `'beta'`.
+     *
+     * **`undefined` for a numeric-only prerelease** (`2.0.0-1`, whose identifiers are `[1]`), because
+     * there is no name there to use - and a caller turning that into a dist-tag called `1` would be
+     * inventing one. Same answer for a release, which has no prerelease at all.
+     */
+    prereleaseId(version) {
+        const first = semver.prerelease(version)?.[0];
+        return typeof first === 'string' ? first : undefined;
+    }
 }
 /**
  * The default, and what every package gets unless something says otherwise - so nothing about

package/core/workspace.d.ts

@@ -1,3 +1,5 @@
+import type { RmanApplication } from './application.js';
+import type { Platform } from './plugin.js';
 /**
  * How a repository is laid out, and who decides.
  *
@@ -6,45 +8,94 @@
  * arrives as a member here rather than as another top-level export.
  */
 export declare namespace Workspace {
-    /** What a repository looks like: where its root is, and which directories hold its packages. */
-    interface Layout {
-        /** Absolute path to the repository root. */
-        root: string;
-        /**
-         * Absolute paths to the package **directories**, outside the root. Empty for a repository that
-         * is itself the one package.
-         *
-         * Directories rather than `Package` objects, and not for want of trying: a provider runs before
-         * any package exists - `Repository.create` constructs them from these paths afterwards, through
-         * the *manifest* provider. A discovery provider returning packages would have to construct them
-         * itself, making discovery the owner of identity too.
-         *
-         * Unlike `Package.dependencies`, there is no identity question here: these are paths, and a
-         * path is unique by construction where a name is only unique if the ecosystem says so.
-         */
-        packageDirs: string[];
-    }
     /**
-     * How a repository's packages are found.
+     * **Where one directory's own child packages are** - the directories immediately below it that
+     * hold a package, as absolute paths. `undefined` for "this is not a directory I recognize".
+     *
+     * **A provider answers for one directory, not for the repository**, and that is the whole
+     * correction. It used to be `(root) => { root, packageDirs }`: asked once, at the top, by the
+     * first platform that recognized it - so in a polyglot repository the technology listed first in
+     * `plugins` decided which directories were packages *at all*. Measured, and documented as a known
+     * limitation for a year: a `Cargo.toml`-only package was simply not found until a provider that
+     * looks for both was listed first.
+     *
+     * Asked per directory, each platform only ever answers about its own packages - which is all a
+     * platform knows - and the recursion is the core's (see `walk`). A Cargo workspace nested inside
+     * a Node monorepo is then just a node in the tree whose children came from a different platform.
+     *
+     * **Children, not descendants.** A provider returning the whole subtree would have to know what
+     * the platforms below it consider a package; returning one level means it never has to. npm's
+     * `workspaces` globs are already one level by construction (`deep: 0`).
+     *
+     * Still directories rather than `Package` objects, for the reason it always was: discovery runs
+     * before any package exists, so a provider returning packages would make discovery the owner of
+     * identity too. A path is also unique by construction, where a name is only unique if the
+     * ecosystem says so.
+     */
+    type Provider = (dir: string) => string[] | undefined;
+    /**
+     * One directory in the walk's result: which technology claimed it, and what sits below it.
      *
-     * **The core has no provider**, and that is the point: "packages are the `workspaces` globs in
-     * the root `package.json`, and a package is a directory with a `package.json` in it" is true of
-     * npm and of nothing else. `rman-node` contributes that one; a plugin for another ecosystem
-     * contributes its own (a Cargo workspace, a `go.work`, a `pyproject.toml`).
+     * A plain tree rather than `Package`s, keeping the line `Provider` draws: `Repository.create`
+     * turns this into packages, so identity stays with the manifest provider and discovery stays
+     * with this one.
+     */
+    interface Node {
+        /** Absolute path to the directory. */
+        dirname: string;
+        /** The technology that claimed it - `basePlatform` when none did, so a reader needs no guard. */
+        platform: Platform;
+        /** The nodes for the package directories directly below it, in the order the platform gave
+         *  them. Empty for a leaf. */
+        children: Node[];
+    }
+    /**
+     * What a directory's `.rmanrc "platform"` resolves to, when it declares one - `undefined` when
+     * it says nothing, so the walk falls back to the guess.
      *
-     * Returns `undefined` for "this is not a repository I recognize", so the next provider gets a
-     * turn and a repository nobody recognizes falls back to being a single package.
+     * **A callback rather than config knowledge in here**, which keeps this namespace answering one
+     * question. Reading a directory's cascaded config, deciding that a declared name has to be
+     * loaded, and refusing one that cannot be, are all the repository's business; where the packages
+     * are is this one's. `Repository.create` supplies it - and it is also the seam a spec uses to
+     * drive the declaration path without writing a config file.
      */
-    type Provider = (root: string) => Layout | undefined;
+    type DeclaredPlatform = (dir: string) => Promise<Platform | undefined>;
     /**
-     * Registers a provider. Called by `loadPlugins` for each plugin's `workspace`, in `plugins`
-     * declaration order - so which provider answers is a function of the repository's own config.
+     * **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.
      */
-    function addProvider(provider: Provider): void;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders(): void;
-    /** The first provider that recognizes `root`, in declaration order. */
-    function resolve(root: string): Layout | undefined;
+    function walk(app: RmanApplication, rootDir: string, options?: {
+        deep?: number;
+        declared?: DeclaredPlatform;
+    }): Promise<Node>;
+    /** 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: Node): Node[];
     /**
      * 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.

package/core/workspace.js

@@ -10,30 +10,72 @@ import path from 'node:path';
 export var Workspace;
 (function (Workspace) {
     /**
-     * Registers a provider. Called by `loadPlugins` for each plugin's `workspace`, in `plugins`
-     * declaration order - so which provider answers is a function of the repository's own config.
+     * **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.
      */
-    function addProvider(provider) {
-        if (providers.includes(provider))
-            return;
-        providers.push(provider);
+    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.addProvider = addProvider;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders() {
-        providers.length = 0;
-    }
-    Workspace.clearProviders = clearProviders;
-    /** The first provider that recognizes `root`, in declaration order. */
-    function resolve(root) {
-        for (const provider of providers) {
-            const layout = provider(root);
-            if (layout)
-                return layout;
-        }
-        return undefined;
+    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.resolve = resolve;
+    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.
@@ -79,5 +121,4 @@ export var Workspace;
     function hasRmanConfig(dir) {
         return CONFIG_FILES.some(name => fs.existsSync(path.join(dir, name)));
     }
-    const providers = [];
 })(Workspace || (Workspace = {}));

package/index.d.ts

@@ -6,44 +6,120 @@
  * per domain - CLI-only concerns (argv parsing, `--help` text, and all console/file presentation)
  * stay in `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
  *
- * **This is also the plugin contract.** A plugin (`rman-node`, say) is an ordinary package that
- * imports from here, so everything a command needs in order to live outside rman has to be
- * exported - the progress panel, the package filter, the branch guard, the git helper. What is
+ * **This is also the plugin contract.** A third-party plugin is an ordinary package that imports
+ * from here, so everything a command needs in order to live outside rman has to be exported - the progress panel, the package filter, the branch guard, the git helper. What is
  * *not* exported is deliberately private: config resolution internals, the expression evaluator,
  * the command registry.
  */
+/**
+ * **The `node` built-in's type augmentation, imported for the same reason `commands.ts` is.**
+ *
+ * A `declare module` augmentation applies only where the module declaring it is part of the
+ * program. The node plugin's lives in `plugins/node/augmentation/rman.augmentation.ts` and is
+ * imported by the *plugin's* entry point - which nothing here reached, so `clean`, `publish.npm`
+ * and the rest existed for rman itself and for nobody else.
+ *
+ * **Measured on a real consumer**, `@panates/rman-node`, a config package annotated with these
+ * types: `Object literal may only specify known properties, and 'clean' does not exist in type
+ * 'RmanConfig'`, plus `Property 'npm' does not exist` - ten errors across its config and its own
+ * suite. It is the identical failure the core's command keys caused when they stopped being
+ * hand-written centrally, and it reappeared the moment the plugin moved *inside* rman: until then
+ * a consumer imported `rman-node` and got the augmentation with the package.
+ *
+ * Type-only, so the emitted module is empty - imported for what it declares, not for what it does.
+ * Pinned in `docs-api.spec.ts`, which imports only from this file.
+ */
+import './plugins/node/augmentation/rman.augmentation.js';
+import type { RmanConfig as CommandDeclaration } from './interfaces/rman-config.interface.js';
 export { defineConfig } from './core/config.js';
+/**
+ * **A config value written as a function**, and the scope it is handed. Exported because a config
+ * author could not name either: `interpolateConfig` calls a function wherever a `${{ }}` could
+ * stand, but the only function form the types admitted was a *step* - so the primary spelling of
+ * `value` was unexpressible.
+ *
+ * `ConfigValueContext` is what a value function receives; `ConfigScope` is the same thing without
+ * `value`, i.e. what an expression sees. Not to be confused with `RunStepContext`, which is what a
+ * step gets, later, with a working directory and a `runBin`.
+ */
+export type { ConfigScope, ConfigValue, ConfigValueContext, FileScope, PackageScope, Resolved, ResolvedConfig, } from './core/config.js';
 export type { CommandContext, CustomCommand } from './core/custom-command.js';
 export { defineCommand } from './core/custom-command.js';
-/** The manifest seam: where a package's name and version are written, and how it is numbered.
- *  The core has no provider - `package.json` is npm's answer, and lives in `rman-node`. */
-export type { ManifestProvider } from './core/manifest.js';
 /** Both the shape and the registry: `const m: Manifest` and `Manifest.read(dir)` - merged onto one
  *  name so a plugin can augment it the way it augments `SystemInfo`. */
+export { RmanApplication } from './core/application.js';
+/** The manifest seam, grouped on a plugin as `Plugin.manifestProvider`: where a package's name and
+ *  version are written, what it declares, and how it is numbered and stamped. The core has none -
+ *  `package.json` is npm's answer, and belongs to the `node` built-in. */
+export type { ManifestProvider } from './core/manifest.js';
 export { Manifest } from './core/manifest.js';
 export { Package } from './core/package.js';
-export type { RmanPlugin } from './core/plugin.js';
-export { definePlugin } from './core/plugin.js';
+/** The publish seam: where a package's artifact ships. The core brings `docker` (nobody's
+ *  ecosystem); npm's target is the `node` built-in's, and any other technology's is its own plugin's. */
+export { declaredTargets, type PublishTarget, shipsTo, targetsOf, unknownTargets } from './core/publish-target.js';
+export { Registry } from './core/registry.js';
 export { Repository } from './core/repository.js';
 export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/run-step.js';
+export { Service, type ServiceFactory, type ServiceMap } from './core/service.js';
+/**
+ * **`Platform` is one technology, whole**; **`Plugin` is whatever a package contributes**, platforms
+ * among them.
+ *
+ * A platform says how its packages are recognized and written, where they live, what goes on a
+ * child's PATH and how its releases are planned - `manifestProvider` is what makes one, and it is
+ * required. A plugin carries `platforms` and an `init` for anything the seams do not name yet; a
+ * bare `Platform` is accepted wherever a `Plugin` is, as sugar for the plugin that provides only it.
+ *
+ * **Both must be declared through their factory.** `loadPlugins` checks for the mark, because an
+ * rman 1.x plugin was `{ name, init }` and so is a 2.x plugin contributing nothing but an `init` -
+ * no shape test can tell them apart.
+ */
+export { basePlatform, definePlatform, definePlugin, isPlatform, type Platform, type Plugin, type PluginContext, } from './core/plugin.js';
 export type { ChangeKind } from './core/version-scheme.js';
 /** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`
  *  are implemented from the members around them, so a scheme states only what it must and still
  *  overrides any of the three. `SemverScheme` is exported to subclass rather than restate. */
 export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/version-scheme.js';
 /** The workspace seam: how a repository's packages are found. A plugin contributes a provider
- *  (see `RmanPlugin.workspace`); the core has none, so `workspaces` is npm's idea and lives in
- *  `rman-node`. */
+ *  (see `Plugin.workspace`); the core has none, so `workspaces` is npm's idea and belongs to the
+ *  `node` built-in. */
 /** `Workspace.Layout`, `Workspace.Provider`, `Workspace.addProvider`, `Workspace.resolve`,
  *  `Workspace.findRoot` - one namespace, so a plugin can augment it. */
 export { Workspace } from './core/workspace.js';
+/**
+ * **How a command is declared** - the same API the built-ins use, so a plugin's command is declared
+ * rather than built: options as data (checked for typos), positionals named against the command
+ * string, `--config` keys derived from what the command owns, and `ArgsOf` for the handler.
+ *
+ * `declareCommand`, not `registerCommand`: the latter pushes onto a module-level registry every
+ * `runCli` walks, so a plugin using it would give its commands to repositories that never named it.
+ * Anything else puts the function in its config's `commands`.
+ *
+ * **Flat names rather than `RmanConfig.CommandOption`**, and they outlived the reason they were
+ * introduced: a second file exported a `RmanConfig` too, so the namespace holding these was
+ * unreachable from outside the package. The two are one file now and `RmanConfig` *is* exported -
+ * these stay because they are the better names for the job. A plugin author declaring a flag wants
+ * `CommandOption`; the config it happens to contribute to is not what they are naming.
+ */
+export { declareCommand } from './interfaces/rman-config.interface.js';
+export type CommandOption = CommandDeclaration.CommandOption;
+/** One declared positional, for the same reason `CommandOption` is here: it is the other half of a
+ *  command's surface, and it was the half a plugin could not name without importing yargs. */
+export type PositionalOption = CommandDeclaration.PositionalOption;
+export type CommandMetadata = CommandDeclaration.CommandMetadata;
+export type CommandRegisterFunction = CommandDeclaration.CommandRegisterFunction;
+/** The argv a command's handler is annotated with - see `RmanConfig.ArgsOf` for why it is annotated
+ *  rather than inferred. */
+export type ArgsOf<C, Cmd extends string> = CommandDeclaration.ArgsOf<C, Cmd>;
+export type GlobalArgs = CommandDeclaration.GlobalArgs;
+export * from './commands.js';
 export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
-export { applyBranchGuardOptions, assertAllowedBranch, type BranchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+export { applyBranchGuardOptions, assertAllowedBranch, type BranchGuardOptions, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
- *  plugin says which directories go on it (see `RmanPlugin.binPaths`). */
+ *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';
 /** A shell command, with the repository's local binaries on PATH - for a command string an author
  *  wrote. `runBin` is the one to reach for when the arguments are assembled in code. */
@@ -54,13 +130,34 @@ export type { LogLevel } from './utils/logger.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 /** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
  *  way every built-in does rather than inventing its own flags. */
-export { applyPackageFilterOptions, applyRootOption, filterPackages, type PackageFilterOptions, readPackageFilterOptions, readRootOption, } from './utils/package-filter.js';
+export { applyFromRootOption, applyPackageFilterOptions, filterPackages, fromRootOption, type PackageFilterOptions, packageFilterOptions, readFromRootOption, readPackageFilterOptions, ROOT_SELECTOR, } from './utils/package-filter.js';
 /** The live panel `run`/`build`/`clean` print - a plugin's per-package command looks like the rest
  *  of rman instead of like a script someone bolted on. */
 export { formatDuration, type ProgressItem, ProgressPanel, type ProgressStatus, type ProgressSummary, } from './utils/progress-panel.js';
-/** Version stamping helpers a `ManifestProvider.stampVersion` can delegate to - the quoted-constant
+/** Version stamping helpers a `Plugin.stampVersion` can delegate to - the quoted-constant
  *  pattern most languages share, and the OCI Dockerfile label (which `version` stamps itself, since
  *  the label's value is by specification the package's version). */
+/** A calendar version's time part (`2026.9.15-1430`) is a semver *prerelease identifier* by
+ *  construction, so anything asking "is this a preview?" has to rule it out first - `github-release`
+ *  does, and so must a publish target deciding whether a version needs its own dist-tag. Exported
+ *  because that second caller lives in a plugin. */
+/**
+ * **The `node` built-in's own surface.** It ships inside rman rather than as `rman-node`, so its
+ * services and target are named from here - a repository asks for the technology with
+ * `plugins: ['node']` (or lets detection find it) and never constructs any of this by hand.
+ *
+ * Its `.rmanrc` *keys* arrive separately, through the bare import at the top of this file - see
+ * there for why that import is not tidiness.
+ */
+export { BUILTIN_PLUGINS, builtinPluginNames, isBuiltinPlugin } from './plugins/builtins.js';
+export type { NodeConfigKeys, RmanNodeConfig } from './plugins/node/node-config.interface.js';
+export { NPM_TARGET, NpmPublishTarget } from './plugins/node/npm-publish-target.js';
+export { CiService } from './plugins/node/services/ci.service.js';
+export { CleanService } from './plugins/node/services/clean.service.js';
+export { PublishService } from './plugins/node/services/publish.service.js';
+export { NodeVersionPlanService } from './plugins/node/services/version-plan.service.js';
+export type { ParsedWorkspaceRange } from './plugins/node/utils/workspace-range.js';
+export { isCalendarVersion } from './utils/release-version.js';
 export type { RunBinOptions, RunBinResult } from './utils/run-bin.js';
 export { runBin } from './utils/run-bin.js';
 export { OCI_VERSION_LABEL, stampVersionConstant, stampVersionLabel } from './utils/version-stamp.js';

package/index.js

@@ -6,47 +6,123 @@
  * per domain - CLI-only concerns (argv parsing, `--help` text, and all console/file presentation)
  * stay in `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
  *
- * **This is also the plugin contract.** A plugin (`rman-node`, say) is an ordinary package that
- * imports from here, so everything a command needs in order to live outside rman has to be
- * exported - the progress panel, the package filter, the branch guard, the git helper. What is
+ * **This is also the plugin contract.** A third-party plugin is an ordinary package that imports
+ * from here, so everything a command needs in order to live outside rman has to be exported - the progress panel, the package filter, the branch guard, the git helper. What is
  * *not* exported is deliberately private: config resolution internals, the expression evaluator,
  * the command registry.
  */
+/**
+ * **The `node` built-in's type augmentation, imported for the same reason `commands.ts` is.**
+ *
+ * A `declare module` augmentation applies only where the module declaring it is part of the
+ * program. The node plugin's lives in `plugins/node/augmentation/rman.augmentation.ts` and is
+ * imported by the *plugin's* entry point - which nothing here reached, so `clean`, `publish.npm`
+ * and the rest existed for rman itself and for nobody else.
+ *
+ * **Measured on a real consumer**, `@panates/rman-node`, a config package annotated with these
+ * types: `Object literal may only specify known properties, and 'clean' does not exist in type
+ * 'RmanConfig'`, plus `Property 'npm' does not exist` - ten errors across its config and its own
+ * suite. It is the identical failure the core's command keys caused when they stopped being
+ * hand-written centrally, and it reappeared the moment the plugin moved *inside* rman: until then
+ * a consumer imported `rman-node` and got the augmentation with the package.
+ *
+ * Type-only, so the emitted module is empty - imported for what it declares, not for what it does.
+ * Pinned in `docs-api.spec.ts`, which imports only from this file.
+ */
+import './plugins/node/augmentation/rman.augmentation.js';
 export { defineConfig } from './core/config.js';
 export { defineCommand } from './core/custom-command.js';
 /** Both the shape and the registry: `const m: Manifest` and `Manifest.read(dir)` - merged onto one
  *  name so a plugin can augment it the way it augments `SystemInfo`. */
+export { RmanApplication } from './core/application.js';
 export { Manifest } from './core/manifest.js';
 export { Package } from './core/package.js';
-export { definePlugin } from './core/plugin.js';
+/** The publish seam: where a package's artifact ships. The core brings `docker` (nobody's
+ *  ecosystem); npm's target is the `node` built-in's, and any other technology's is its own plugin's. */
+export { declaredTargets, shipsTo, targetsOf, unknownTargets } from './core/publish-target.js';
+export { Registry } from './core/registry.js';
 export { Repository } from './core/repository.js';
+export { Service } from './core/service.js';
+/**
+ * **`Platform` is one technology, whole**; **`Plugin` is whatever a package contributes**, platforms
+ * among them.
+ *
+ * A platform says how its packages are recognized and written, where they live, what goes on a
+ * child's PATH and how its releases are planned - `manifestProvider` is what makes one, and it is
+ * required. A plugin carries `platforms` and an `init` for anything the seams do not name yet; a
+ * bare `Platform` is accepted wherever a `Plugin` is, as sugar for the plugin that provides only it.
+ *
+ * **Both must be declared through their factory.** `loadPlugins` checks for the mark, because an
+ * rman 1.x plugin was `{ name, init }` and so is a 2.x plugin contributing nothing but an `init` -
+ * no shape test can tell them apart.
+ */
+export { basePlatform, definePlatform, definePlugin, isPlatform, } from './core/plugin.js';
 /** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`
  *  are implemented from the members around them, so a scheme states only what it must and still
  *  overrides any of the three. `SemverScheme` is exported to subclass rather than restate. */
 export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/version-scheme.js';
 /** The workspace seam: how a repository's packages are found. A plugin contributes a provider
- *  (see `RmanPlugin.workspace`); the core has none, so `workspaces` is npm's idea and lives in
- *  `rman-node`. */
+ *  (see `Plugin.workspace`); the core has none, so `workspaces` is npm's idea and belongs to the
+ *  `node` built-in. */
 /** `Workspace.Layout`, `Workspace.Provider`, `Workspace.addProvider`, `Workspace.resolve`,
  *  `Workspace.findRoot` - one namespace, so a plugin can augment it. */
 export { Workspace } from './core/workspace.js';
+/**
+ * **How a command is declared** - the same API the built-ins use, so a plugin's command is declared
+ * rather than built: options as data (checked for typos), positionals named against the command
+ * string, `--config` keys derived from what the command owns, and `ArgsOf` for the handler.
+ *
+ * `declareCommand`, not `registerCommand`: the latter pushes onto a module-level registry every
+ * `runCli` walks, so a plugin using it would give its commands to repositories that never named it.
+ * Anything else puts the function in its config's `commands`.
+ *
+ * **Flat names rather than `RmanConfig.CommandOption`**, and they outlived the reason they were
+ * introduced: a second file exported a `RmanConfig` too, so the namespace holding these was
+ * unreachable from outside the package. The two are one file now and `RmanConfig` *is* exported -
+ * these stay because they are the better names for the job. A plugin author declaring a flag wants
+ * `CommandOption`; the config it happens to contribute to is not what they are naming.
+ */
+export { declareCommand } from './interfaces/rman-config.interface.js';
+export * from './commands.js';
 export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
 // --- what a command needs to behave like a built-in one -----------------------------------------
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
-export { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions, } from './utils/branch-guard.js';
+export { applyBranchGuardOptions, assertAllowedBranch, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
- *  plugin says which directories go on it (see `RmanPlugin.binPaths`). */
+ *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';
 export { exec } from './utils/exec.js';
 export { GitHelper } from './utils/git.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 /** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
  *  way every built-in does rather than inventing its own flags. */
-export { applyPackageFilterOptions, applyRootOption, filterPackages, readPackageFilterOptions, readRootOption, } from './utils/package-filter.js';
+export { applyFromRootOption, applyPackageFilterOptions, filterPackages, fromRootOption, packageFilterOptions, readFromRootOption, readPackageFilterOptions, ROOT_SELECTOR, } from './utils/package-filter.js';
 /** The live panel `run`/`build`/`clean` print - a plugin's per-package command looks like the rest
  *  of rman instead of like a script someone bolted on. */
 export { formatDuration, ProgressPanel, } from './utils/progress-panel.js';
+/** Version stamping helpers a `Plugin.stampVersion` can delegate to - the quoted-constant
+ *  pattern most languages share, and the OCI Dockerfile label (which `version` stamps itself, since
+ *  the label's value is by specification the package's version). */
+/** A calendar version's time part (`2026.9.15-1430`) is a semver *prerelease identifier* by
+ *  construction, so anything asking "is this a preview?" has to rule it out first - `github-release`
+ *  does, and so must a publish target deciding whether a version needs its own dist-tag. Exported
+ *  because that second caller lives in a plugin. */
+/**
+ * **The `node` built-in's own surface.** It ships inside rman rather than as `rman-node`, so its
+ * services and target are named from here - a repository asks for the technology with
+ * `plugins: ['node']` (or lets detection find it) and never constructs any of this by hand.
+ *
+ * Its `.rmanrc` *keys* arrive separately, through the bare import at the top of this file - see
+ * there for why that import is not tidiness.
+ */
+export { BUILTIN_PLUGINS, builtinPluginNames, isBuiltinPlugin } from './plugins/builtins.js';
+export { NPM_TARGET, NpmPublishTarget } from './plugins/node/npm-publish-target.js';
+export { CiService } from './plugins/node/services/ci.service.js';
+export { CleanService } from './plugins/node/services/clean.service.js';
+export { PublishService } from './plugins/node/services/publish.service.js';
+export { NodeVersionPlanService } from './plugins/node/services/version-plan.service.js';
+export { isCalendarVersion } from './utils/release-version.js';
 export { runBin } from './utils/run-bin.js';
 export { OCI_VERSION_LABEL, stampVersionConstant, stampVersionLabel } from './utils/version-stamp.js';