rman 1.3.0 → 2.0.0-beta.3

package/core/interfaces/publish-target.d.ts

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

package/core/interfaces/publish-target.js

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

package/core/{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/interfaces/run-step.js

@@ -0,0 +1 @@
+export {};

package/core/plugin-loader.d.ts

@@ -0,0 +1,25 @@
+import type { RmanApplication } from './application.js';
+import { type Platform, type Plugin } from './interfaces/plugin.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export declare const PLUGINS_KEY = "plugins";
+/**
+ * **Puts one contribution onto an application** - a technology, or a plugin - and the only place
+ * that knows how.
+ *
+ * **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.
+ *
+ * **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;
+    handler?: unknown;
+}>(command: T, pluginName: string): T & {
+    command: string;
+};

package/core/plugin-loader.js

@@ -0,0 +1,53 @@
+import { isPlatform } from './interfaces/plugin.js';
+/** The `.rmanrc` key naming plugin packages to load. */
+export const PLUGINS_KEY = 'plugins';
+/**
+ * **Puts one contribution onto an application** - a technology, or a plugin - and the only place
+ * that knows how.
+ *
+ * **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.
+ *
+ * **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.
+ */
+/* **Two registries and no normalization, which is what the split bought.** A bare `Platform` used
+ * to be wrapped in `{ name, platforms: [entry] }` so that everything downstream dealt in one shape
+ * - and that shape was `Plugin.platforms`, which is gone: `platforms` is a config key now, so a
+ * package shipping a technology declares it there and nothing has to invent a plugin around it.
+ * What is left is a question with two honest answers, asked once. */
+export function registerPlugin(app, entry) {
+    if (isPlatform(entry)) {
+        app.platforms.add(entry);
+        /**
+         * **The orchestrator, and only that.** A plan is computed for the whole repository at once -
+         * groups span packages, the ripple crosses them - so one planner drives the traversal and the
+         * last registration wins it.
+         *
+         * The two decisions that belong to a *technology* are not taken from here: `detectBoundary`
+         * and `cascade` are asked of `pkg.platform.versionPlanner` per package, which is why a platform
+         * still declares one even when it is not the last to register.
+         */
+        if (entry.versionPlanner)
+            app.versionPlanner = entry.versionPlanner;
+        return;
+    }
+    app.plugins.add(entry);
+}
+export function checkCustomCommand(command, pluginName) {
+    const declared = command?.command?.trim();
+    if (!declared) {
+        throw new Error(`Plugin "${pluginName}" has a command with no "command" name - it cannot be registered.`);
+    }
+    if (typeof command.handler !== 'function') {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "handler" function.`);
+    }
+    if (typeof command.describe !== 'string' || !command.describe) {
+        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "describe" - \`rman --help\` would have ` +
+            `nothing to list it by.`);
+    }
+    return { ...command, command: declared };
+}

package/index.d.ts

@@ -6,44 +6,121 @@
  * 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.
  */
-export { defineConfig } 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';
+/**
+ * **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 './builtins/platforms/node/augmentation/rmanrc.augmentation.js';
+import type { RmanConfig as CommandDeclaration } from './interfaces/rman-config.interface.js';
+export { defineConfig } from './interfaces/rman-config.interface.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 { CommandContext, CustomCommand } from './core/interfaces/custom-command.js';
+export { defineCommand } from './core/interfaces/custom-command.js';
+export type { ConfigScope, ConfigValueContext, FileScope, PackageScope } from './interfaces/config-scope.interface.js';
+export type { ConfigValue, Resolved, ResolvedConfig } from './interfaces/rman-config.interface.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 { Manifest } from './core/manifest.js';
-export { Package } from './core/package.js';
-export type { RmanPlugin } from './core/plugin.js';
-export { definePlugin } from './core/plugin.js';
-export { Repository } from './core/repository.js';
-export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/run-step.js';
-export type { ChangeKind } from './core/version-scheme.js';
+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 { Package } from './core/classes/package.js';
+export type { ManifestProvider } from './core/interfaces/manifest.js';
+export { Manifest } from './core/interfaces/manifest.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 { Registry } from './core/classes/registry.js';
+export { Repository } from './core/classes/repository.js';
+export { Service, type ServiceFactory, type ServiceMap } from './core/classes/service.js';
+export { declaredTargets, type PublishTarget, shipsTo, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
+export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/interfaces/run-step.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 type { ChangeKind } from './core/classes/version-scheme.js';
+export { basePlatform, definePlatform, definePlugin, isPlatform, type Platform, type Plugin, type PluginContext, } from './core/interfaces/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';
+export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/classes/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';
+export { Workspace } from './core/classes/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 +131,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` preset's own surface.** It ships inside rman rather than as `rman-node`, so its
+ * services and target are named from here - a repository gets the technology from
+ * `DEFAULT_PRESETS`, or names it with `extends: "rman:node"`, 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 type { NodeConfigKeys, RmanNodeConfig } from './builtins/platforms/node/node-config.interface.js';
+export { CiService } from './builtins/platforms/node/services/ci.service.js';
+export { CleanService } from './builtins/platforms/node/services/clean.service.js';
+export { PublishService } from './builtins/platforms/node/services/publish.service.js';
+export { NodeVersionPlanService } from './builtins/platforms/node/services/version-plan.service.js';
+export type { ParsedWorkspaceRange } from './builtins/platforms/node/utils/workspace-range.js';
+export { NPM_TARGET, NpmPublishTarget } from './builtins/publish-targets/npm/npm-publish-target.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,97 @@
  * 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.
  */
-export { defineConfig } from './core/config.js';
-export { defineCommand } from './core/custom-command.js';
+/**
+ * **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 './builtins/platforms/node/augmentation/rmanrc.augmentation.js';
+export { defineConfig } from './interfaces/rman-config.interface.js';
+export { defineCommand } from './core/interfaces/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 { Manifest } from './core/manifest.js';
-export { Package } from './core/package.js';
-export { definePlugin } from './core/plugin.js';
-export { Repository } from './core/repository.js';
+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 { Package } from './core/classes/package.js';
+export { Manifest } from './core/interfaces/manifest.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 { Registry } from './core/classes/registry.js';
+export { Repository } from './core/classes/repository.js';
+export { Service } from './core/classes/service.js';
+export { declaredTargets, shipsTo, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
+export { basePlatform, definePlatform, definePlugin, isPlatform, } from './core/interfaces/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';
+export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/classes/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';
+export { Workspace } from './core/classes/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';
+export { CiService } from './builtins/platforms/node/services/ci.service.js';
+export { CleanService } from './builtins/platforms/node/services/clean.service.js';
+export { PublishService } from './builtins/platforms/node/services/publish.service.js';
+export { NodeVersionPlanService } from './builtins/platforms/node/services/version-plan.service.js';
+export { NPM_TARGET, NpmPublishTarget } from './builtins/publish-targets/npm/npm-publish-target.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';