rman 1.2.5 → 2.0.0-beta.2

package/commands/version.command.js

@@ -1,11 +1,110 @@
 import readline from 'node:readline/promises';
 import colors from 'ansi-colors';
 import EasyTable from 'easy-table';
-import { VersionService } from '../services/version.service.js';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { VersionPlanService } from '../services/version-plan.service.js';
-import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
-export function initCli(repository, program) {
+import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+/**
+ * Hoisted out of the metadata literal so the handler can be annotated against them - see
+ * `RmanConfig.ArgsOf` for why an inferred `argv` and the metadata's own typo checking cannot both
+ * work in one signature.
+ *
+ * `as const` on the command string is load-bearing twice over: the config key is derived from it
+ * (`'version'`), and so are the positional names it declares.
+ */
+const COMMAND = 'version [bump]';
+const config = {
+    /** The two shared groups, spread rather than applied - this is what
+     *  `applyBranchGuardOptions(applyPackageFilterOptions(cmd))` used to say. Spread first, so an
+     *  option deliberately overridden below wins. */
+    ...packageFilterOptions,
+    ...branchGuardOptions,
+    interactive: {
+        target: 'cli',
+        alias: 'i',
+        describe: 'Show the plan and ask for confirmation before applying (with or without an explicit bump)',
+        type: 'boolean',
+    },
+    show: {
+        target: 'cli',
+        describe: 'Show the resulting plan for the given bump without applying it - unlike omitting bump ' +
+            'entirely, this still uses the given bump keyword/version to compute the plan, ' +
+            'just never writes it.',
+        type: 'boolean',
+        conflicts: 'interactive',
+    },
+    yes: {
+        target: 'cli',
+        alias: 'y',
+        describe: 'Skip the confirmation prompt and apply the computed plan immediately - an auto-detected ' +
+            'bump included, no explicit bump keyword required (same idea as "publish --yes").',
+        type: 'boolean',
+        conflicts: 'interactive',
+    },
+    ignoreDirty: {
+        target: 'cli',
+        cliName: 'ignore-dirty',
+        describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
+        type: 'boolean',
+    },
+    push: {
+        target: 'cli',
+        describe: 'Push the resulting commit(s) and tag(s) to the remote once applied',
+        type: 'boolean',
+    },
+    message: {
+        target: 'cli',
+        alias: 'm',
+        describe: 'Override the commit message for every group this run commits (default: .rmanrc ' +
+            'version.commitMessage, or "chore(release): v{version}") - "{version}" is substituted ' +
+            "when a commit's own group shares one version.",
+        type: 'string',
+    },
+    changelog: {
+        target: 'both',
+        describe: "Also write each bumped package's CHANGELOG.md (same as running changelog --write " +
+            'separately) and fold it into the same commit as its version bump. Default: .rmanrc ' +
+            '"version.changelog", or false - --no-changelog forces it off even when that\'s true.',
+        type: 'boolean',
+    },
+    preid: {
+        target: 'cli',
+        describe: 'Make the bump a prerelease with this identifier (e.g. "beta" -> 1.2.3-beta.0). ' +
+            'Running again with the same --preid increments it (-> 1.2.3-beta.1); a different ' +
+            'identifier starts a fresh prerelease line. Ignored when bump is an explicit version.',
+        type: 'string',
+    },
+    /**
+     * Config-only, from here down: `.rmanrc "version.*"` keys with no reason to be a flag.
+     * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
+     * states once, not things a single run overrides.
+     */
+    commitMessage: {
+        target: 'config',
+        describe: 'The commit message for each group this run commits - "{version}" is substituted when a ' +
+            'commit\'s own group shares one version. Default "chore(release): v{version}".',
+        type: 'string',
+    },
+    releaseTagPattern: {
+        target: 'config',
+        describe: "Tag naming the repository's own release, as opposed to the per-package tags " +
+            '"changelog.tagPattern" names - only created when the root is on a calendar version. ' +
+            'Root-level only. Default "release-*". Must **not** match any package\'s own tag pattern, or ' +
+            "that package's changelog boundary resolves to the repository release instead of its own.",
+        type: 'string',
+    },
+    stampDockerfile: {
+        target: 'config',
+        describe: "Keep this package's Dockerfile org.opencontainers.image.version label in step with the " +
+            'version being written. Per-package cascaded. Default true - the label is by specification ' +
+            'the version of the packaged software, so there is only one correct value and "version" is ' +
+            'what knows it. Only ever rewrites a label the Dockerfile already declares.',
+        type: 'boolean',
+    },
+};
+const versionCommand = registerCommand(app => {
+    const repository = app.repository;
     /** `rman version <bump|version>` is validated by the root's scheme (see `getPlan`), so the help
      *  has to name that scheme's own words rather than semver's - otherwise `--help` in a repository
      *  numbering some other way documents keywords its own planner would reject. A four-part scheme
@@ -15,72 +114,52 @@ export function initCli(repository, program) {
     /** For the examples. Not `smallestBump`, which throws: `--help` must still render for a scheme
      *  that declares none, and the placeholder says what to write there. */
     const smallest = bumpNames[0] ?? '<bump>';
-    program.command({
-        command: 'version [bump]',
-        /** `changelog` too: `--changelog` folds one into the bump commit, and `group` is what decides
-         *  which packages move together. */
-        configKeys: ['version', 'changelog', 'group'],
+    return {
+        /** `as const` so the config key stays derivable from it: `CommandMetadata['command']` is a
+         *  plain `string`, so without the assertion inference widens `'version [bump]'` and there is
+         *  nothing left to read `'version'` out of. */
+        command: COMMAND,
         describe: 'Bumps versions of changed packages (and their dependents), grouped via .rmanrc "group"',
-        builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
-            .example(`$0 version ${smallest}`, `# Bump ${smallest} directly, applied immediately`)
-            .example('$0 version', "# Auto-detect the bump from commits, show the plan, don't write anything")
-            .example('$0 version --interactive', '# Show the plan either way, then ask for confirmation')
-            .example(`$0 version ${smallest} --show`, `# Preview what an explicit ${smallest} would do, without applying it`)
-            .positional('bump', {
-            describe: `A bump keyword (${bumps}) or an explicit ${scheme} version. ` +
-                'Omit to auto-detect from commits and only preview the plan.',
-            type: 'string',
-        })
-            .option('interactive', {
-            alias: 'i',
-            describe: 'Show the plan and ask for confirmation before applying (with or without an explicit bump)',
-            type: 'boolean',
-        })
-            .option('show', {
-            describe: 'Show the resulting plan for the given bump without applying it - unlike omitting bump ' +
-                'entirely, this still uses the given bump keyword/version to compute the plan, ' +
-                'just never writes it.',
-            type: 'boolean',
-        })
-            .conflicts('show', 'interactive')
-            .option('yes', {
-            alias: 'y',
-            describe: 'Skip the confirmation prompt and apply the computed plan immediately - an auto-detected ' +
-                'bump included, no explicit bump keyword required (same idea as "publish --yes").',
-            type: 'boolean',
-        })
-            .conflicts('yes', 'interactive')
-            .option('ignore-dirty', {
-            describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
-            type: 'boolean',
-        })
-            .option('push', {
-            describe: 'Push the resulting commit(s) and tag(s) to the remote once applied',
-            type: 'boolean',
-        })
-            .option('message', {
-            alias: 'm',
-            describe: 'Override the commit message for every group this run commits (default: .rmanrc ' +
-                'version.commitMessage, or "chore(release): v{version}") - "{version}" is substituted ' +
-                "when a commit's own group shares one version.",
-            type: 'string',
-        })
-            .option('changelog', {
-            describe: "Also write each bumped package's CHANGELOG.md (same as running changelog --write " +
-                'separately) and fold it into the same commit as its version bump. Default: .rmanrc ' +
-                '"version.changelog", or false - --no-changelog forces it off even when that\'s true.',
-            type: 'boolean',
-        })
-            .option('preid', {
-            describe: 'Make the bump a prerelease with this identifier (e.g. "beta" -> 1.2.3-beta.0). ' +
-                'Running again with the same --preid increments it (-> 1.2.3-beta.1); a different ' +
-                `identifier starts a fresh prerelease line. Ignored when bump is an explicit ${scheme} version.`,
-            type: 'string',
-        }),
+        /**
+         * Read, not owned - so they are named here rather than declared in `config`. `group` is a core
+         * per-package key that decides which packages move together, `changelog.*` is consulted when
+         * `--changelog` folds one into the bump commit, and `allowBranch`/`ignoreBranch` are repo-wide
+         * keys the shared branch-guard group only exposes as flags. `version` itself is not listed: it
+         * is this command's own key, derived from `command`.
+         */
+        configKeys: ['changelog', 'group', 'allowBranch', 'ignoreBranch'],
+        config,
+        examples: [
+            {
+                command: `$0 version ${smallest} --show`,
+                description: `# Bump ${smallest} directly, applied immediately`,
+            },
+            {
+                command: '$0 version',
+                description: "# Auto-detect the bump from commits, show the plan, don't write anything",
+            },
+            {
+                command: '$0 version --interactive',
+                description: '# Show the plan either way, then ask for confirmation',
+            },
+            {
+                command: `$0 version ${smallest} --show`,
+                description: `# Preview what an explicit ${smallest} would do, without applying it`,
+            },
+        ],
+        positionals: {
+            bump: {
+                describe: `A bump keyword (${bumps}) or an explicit ${scheme} version. ` +
+                    'Omit to auto-detect from commits and only preview the plan.',
+                type: 'string',
+            },
+        },
+        /** Annotated rather than inferred - `RmanConfig.ArgsOf` records why, and the casts this
+         *  replaces are the reason it is worth two hoisted declarations. */
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
             const bump = args.bump;
-            const plan = await VersionPlanService.getPlanner().getPlan(repository, {
+            const plan = await VersionPlanService.getPlanner(app).getPlan(repository, {
                 ...readPackageFilterOptions(args),
                 bump,
                 ignoreDirty: args.ignoreDirty,
@@ -115,15 +194,16 @@ export function initCli(repository, program) {
             if (!apply)
                 return;
             const changelog = args.changelog ?? repository.config?.version?.changelog ?? false;
-            const applied = await VersionService.applyPlan(repository, plan, {
+            const applied = await app.getService('version').applyPlan(plan, {
                 push: args.push,
                 message: args.message,
                 changelog,
             });
             printApplied(applied);
         },
-    });
-}
+    };
+});
+export default versionCommand;
 /**
  * What the run *did* - which is deliberately not the table again.
  *

package/commands.d.ts

@@ -0,0 +1,32 @@
+/**
+ * **Every built-in command, and the one place the list lives.**
+ *
+ * Imported for their side effect: each module calls `registerCommand`, which pushes its register
+ * function onto `commandRegistry`. Nothing reads the modules' exports - `runCli` walks the registry
+ * - so this import list *is* the built-in command list.
+ *
+ * **`index.ts` imports this too, and that is not tidiness.** Each module also carries a
+ * `declare module` augmentation contributing its own `.rmanrc` keys, and a type augmentation only
+ * applies where the module declaring it is part of the program. Reached only from `cli.ts`, those
+ * keys existed for rman itself and for nobody else: `rman-node` reading `pkg.config.publish` got
+ * `Property 'publish' does not exist on type 'RmanConfig'` (measured, the moment the keys stopped
+ * being hand-written centrally, in what is now `rman-config.interface.ts`).
+ */
+import './commands/build.command.js';
+import './commands/changed.command.js';
+import './commands/changelog.command.js';
+import './commands/config.command.js';
+import './commands/diff.command.js';
+import './commands/exec.command.js';
+import './commands/github-release.command.js';
+import './commands/import.command.js';
+import './commands/info.command.js';
+import './commands/list.command.js';
+import './commands/publish.command.js';
+import './commands/run.command.js';
+import './commands/test.command.js';
+import './commands/version.command.js';
+/** The config shapes a command declares by hand, where an option cannot describe them - see
+ *  `RmanConfig.CommandContribution`'s `Extra`. Exported so a plugin can name one. */
+export type { PublishExtraKeys, PublishTargetConfigs } from './commands/publish.command.js';
+export type { VersionExtraKeys, VersionStampEntry } from './commands/version.command.js';

package/commands.js

@@ -0,0 +1,28 @@
+/**
+ * **Every built-in command, and the one place the list lives.**
+ *
+ * Imported for their side effect: each module calls `registerCommand`, which pushes its register
+ * function onto `commandRegistry`. Nothing reads the modules' exports - `runCli` walks the registry
+ * - so this import list *is* the built-in command list.
+ *
+ * **`index.ts` imports this too, and that is not tidiness.** Each module also carries a
+ * `declare module` augmentation contributing its own `.rmanrc` keys, and a type augmentation only
+ * applies where the module declaring it is part of the program. Reached only from `cli.ts`, those
+ * keys existed for rman itself and for nobody else: `rman-node` reading `pkg.config.publish` got
+ * `Property 'publish' does not exist on type 'RmanConfig'` (measured, the moment the keys stopped
+ * being hand-written centrally, in what is now `rman-config.interface.ts`).
+ */
+import './commands/build.command.js';
+import './commands/changed.command.js';
+import './commands/changelog.command.js';
+import './commands/config.command.js';
+import './commands/diff.command.js';
+import './commands/exec.command.js';
+import './commands/github-release.command.js';
+import './commands/import.command.js';
+import './commands/info.command.js';
+import './commands/list.command.js';
+import './commands/publish.command.js';
+import './commands/run.command.js';
+import './commands/test.command.js';
+import './commands/version.command.js';

package/constants.js

@@ -1 +1 @@
-export const version = '1.2.5';
+export const version = '2.0.0-beta.2';

package/core/application.d.ts

@@ -0,0 +1,116 @@
+import type { VersionPlanService } from '../services/version-plan.service.js';
+import { Logger, type LogLevel } from '../utils/logger.js';
+import { type Platform, type Plugin } from './plugin.js';
+import type { PublishTarget } from './publish-target.js';
+import { Registry } from './registry.js';
+import type { Repository } from './repository.js';
+import type { ServiceFactory, ServiceMap } from './service.js';
+/**
+ * **One rman invocation, and everything it holds.** Created before anything else, handed to every
+ * plugin's `init`, and the owner of every registry and service that used to be a module-level
+ * variable.
+ *
+ * The point is that nothing is process-global any more. `Manifest`, `Workspace`, `BinPath`,
+ * `RunService` and `VersionPlanService` each kept their contributions in a module-scope array, so
+ * two repositories in one process shared them - which the test suite could only survive with a
+ * root hook emptying five of them before every test, and the failure that hook prevented was:
+ * whichever spec ran first decided the answer for the rest, and the core appeared to work in tests
+ * that had registered nothing. An application starts empty and is thrown away whole, so the hook
+ * is gone.
+ */
+export declare class RmanApplication {
+    /**
+     * The **technologies** this invocation knows about, in `plugins` declaration order.
+     *
+     * One registry rather than the four it replaces (`manifest`, `workspace`, `binPaths`,
+     * `runSteps`): a technology is a whole, and declaring part of one was never meaningful - see
+     * `Platform`.
+     *
+     * **Flattened out of the plugins**, because this is what every seam actually iterates - a
+     * manifest is read by a platform, a workspace is laid out by a platform, a PATH is contributed by
+     * a platform. A plugin providing two of them puts two entries here, and a plugin providing none
+     * puts none.
+     */
+    readonly platforms: Registry<Platform>;
+    /**
+     * The **plugins** themselves, in declaration order - what a config named, before the platforms
+     * were taken out of them.
+     *
+     * Kept apart from `platforms` because the two answer different questions: this is who contributed,
+     * that is what they contributed. `init` runs per plugin; nothing else reads this.
+     */
+    readonly plugins: Registry<Plugin>;
+    /**
+     * Where a package's artifact can ship, in registration order.
+     *
+     * A registry rather than a field because the answer is a *sum*: a package may ship to npm and
+     * Docker Hub at once, and `publish` runs every target a package declares. The core contributes
+     * `docker` (nobody's ecosystem), the `node` built-in contributes `npm`, and a plugin for any other
+     * technology adds its own without either of them changing - see `PublishTarget`.
+     */
+    readonly publishTargets: Registry<PublishTarget>;
+    /**
+     * **The planner that orchestrates a run**, not the one that answers for each package.
+     *
+     * One answer, not a sum - so a field rather than a registry, and last registration wins. What it
+     * decides is the shape of the whole plan: groups, the commit→size reading, the cross-group ripple
+     * and the root's release identity, none of which belongs to any one technology.
+     *
+     * The two decisions that *are* a technology's - `detectBoundary` and `cascade` - are asked of
+     * each package's own `Platform.versionPlanner` instead (`VersionPlanService.plannerFor`), so a
+     * polyglot repository no longer resolves both through whichever plugin registered last.
+     */
+    versionPlanner?: VersionPlanService;
+    readonly logger: Logger;
+    /** Which platform claims a directory - the first whose manifest provider recognizes it, because
+     *  before a package is read there is nothing else to go on. `basePlatform` when none does, so the
+     *  caller needs no guard. */
+    platformFor(dir: string): Platform;
+    /**
+     * **Not a constructor field, and that is forced by the order things happen in.** Plugins are what
+     * *find* the packages - `Repository.create` loads them before it calls `Workspace.resolve` - so
+     * the application has to exist, and be handed to every `init`, while there is still no
+     * repository to put in it.
+     *
+     * A throwing getter rather than `undefined`: a plugin reaching for packages during `init` has
+     * made a real mistake, and `undefined` would let it write a check that silently does nothing.
+     */
+    get repository(): Repository;
+    /** `info` until `--log-level` or `.rmanrc "logLevel"` is resolved - which cannot happen here,
+     *  since reading the config is itself work the application does. */
+    constructor(options?: {
+        logLevel?: LogLevel;
+    });
+    /**
+     * The single instance of a service, built on first use.
+     *
+     * **Lazy, and for two reasons.** `rman info` has no business constructing the changelog, version
+     * and release services, which is the same laziness the config scope's `git` getter was measured
+     * to need (0 git reads with property descriptors, 1 with a spread). And services call each other -
+     * `VersionService` reaches for `RunService` and `ChangelogService`, which reaches for
+     * `ChangeHashService` - so resolving at call time is what keeps that from being a construction
+     * cycle.
+     */
+    getService<K extends keyof ServiceMap>(name: K): ServiceMap[K];
+    /**
+     * Registers how a service is built. A plugin replacing one of the core's - a version planner that
+     * knows its own ecosystem's dependency ranges - does it here, which is why that no longer needs a
+     * seam of its own on the plugin interface.
+     *
+     * Refused once the service has been built: something is already holding the old instance, and
+     * swapping the factory then would leave two answers to one question in play.
+     */
+    setService<K extends keyof ServiceMap>(name: K, factory: ServiceFactory<ServiceMap[K]>): void;
+    /**
+     * Called by `Repository.create`, after the plugins that find the packages have run.
+     *
+     * **One application, one repository**, and a second is refused. It was briefly "last one wins",
+     * because a single shared application made two repositories in one test collide; each
+     * `Repository.create` makes its own now, so the rule holds again and nothing in a process is
+     * shared by accident.
+     */
+    attachRepository(repository: Repository): void;
+    private _repository?;
+    private readonly services;
+    private readonly factories;
+}

package/core/application.js

@@ -0,0 +1,143 @@
+import { Logger } from '../utils/logger.js';
+import { registerCoreServices } from './core-services.js';
+import { registerCoreTargets } from './core-targets.js';
+import { basePlatform } from './plugin.js';
+import { Registry } from './registry.js';
+/**
+ * **One rman invocation, and everything it holds.** Created before anything else, handed to every
+ * plugin's `init`, and the owner of every registry and service that used to be a module-level
+ * variable.
+ *
+ * The point is that nothing is process-global any more. `Manifest`, `Workspace`, `BinPath`,
+ * `RunService` and `VersionPlanService` each kept their contributions in a module-scope array, so
+ * two repositories in one process shared them - which the test suite could only survive with a
+ * root hook emptying five of them before every test, and the failure that hook prevented was:
+ * whichever spec ran first decided the answer for the rest, and the core appeared to work in tests
+ * that had registered nothing. An application starts empty and is thrown away whole, so the hook
+ * is gone.
+ */
+export class RmanApplication {
+    /**
+     * The **technologies** this invocation knows about, in `plugins` declaration order.
+     *
+     * One registry rather than the four it replaces (`manifest`, `workspace`, `binPaths`,
+     * `runSteps`): a technology is a whole, and declaring part of one was never meaningful - see
+     * `Platform`.
+     *
+     * **Flattened out of the plugins**, because this is what every seam actually iterates - a
+     * manifest is read by a platform, a workspace is laid out by a platform, a PATH is contributed by
+     * a platform. A plugin providing two of them puts two entries here, and a plugin providing none
+     * puts none.
+     */
+    platforms = new Registry();
+    /**
+     * The **plugins** themselves, in declaration order - what a config named, before the platforms
+     * were taken out of them.
+     *
+     * Kept apart from `platforms` because the two answer different questions: this is who contributed,
+     * that is what they contributed. `init` runs per plugin; nothing else reads this.
+     */
+    plugins = new Registry();
+    /**
+     * Where a package's artifact can ship, in registration order.
+     *
+     * A registry rather than a field because the answer is a *sum*: a package may ship to npm and
+     * Docker Hub at once, and `publish` runs every target a package declares. The core contributes
+     * `docker` (nobody's ecosystem), the `node` built-in contributes `npm`, and a plugin for any other
+     * technology adds its own without either of them changing - see `PublishTarget`.
+     */
+    publishTargets = new Registry();
+    /**
+     * **The planner that orchestrates a run**, not the one that answers for each package.
+     *
+     * One answer, not a sum - so a field rather than a registry, and last registration wins. What it
+     * decides is the shape of the whole plan: groups, the commit→size reading, the cross-group ripple
+     * and the root's release identity, none of which belongs to any one technology.
+     *
+     * The two decisions that *are* a technology's - `detectBoundary` and `cascade` - are asked of
+     * each package's own `Platform.versionPlanner` instead (`VersionPlanService.plannerFor`), so a
+     * polyglot repository no longer resolves both through whichever plugin registered last.
+     */
+    versionPlanner;
+    logger;
+    /** Which platform claims a directory - the first whose manifest provider recognizes it, because
+     *  before a package is read there is nothing else to go on. `basePlatform` when none does, so the
+     *  caller needs no guard. */
+    platformFor(dir) {
+        return this.platforms.first(p => (p.manifestProvider.read(dir) ? p : undefined)) ?? basePlatform;
+    }
+    /**
+     * **Not a constructor field, and that is forced by the order things happen in.** Plugins are what
+     * *find* the packages - `Repository.create` loads them before it calls `Workspace.resolve` - so
+     * the application has to exist, and be handed to every `init`, while there is still no
+     * repository to put in it.
+     *
+     * A throwing getter rather than `undefined`: a plugin reaching for packages during `init` has
+     * made a real mistake, and `undefined` would let it write a check that silently does nothing.
+     */
+    get repository() {
+        if (!this._repository) {
+            throw new Error('The repository is not available yet - plugins are loaded before the packages they are ' +
+                "what finds. Ask for it from a command or a service, not from a plugin's init().");
+        }
+        return this._repository;
+    }
+    /** `info` until `--log-level` or `.rmanrc "logLevel"` is resolved - which cannot happen here,
+     *  since reading the config is itself work the application does. */
+    constructor(options) {
+        this.logger = new Logger(options?.logLevel ?? 'info');
+        registerCoreServices(this);
+        registerCoreTargets(this);
+    }
+    /**
+     * The single instance of a service, built on first use.
+     *
+     * **Lazy, and for two reasons.** `rman info` has no business constructing the changelog, version
+     * and release services, which is the same laziness the config scope's `git` getter was measured
+     * to need (0 git reads with property descriptors, 1 with a spread). And services call each other -
+     * `VersionService` reaches for `RunService` and `ChangelogService`, which reaches for
+     * `ChangeHashService` - so resolving at call time is what keeps that from being a construction
+     * cycle.
+     */
+    getService(name) {
+        const existing = this.services.get(name);
+        if (existing)
+            return existing;
+        const factory = this.factories.get(name);
+        if (!factory)
+            throw new Error(`No service registered under "${String(name)}"`);
+        const service = factory(this);
+        this.services.set(name, service);
+        return service;
+    }
+    /**
+     * Registers how a service is built. A plugin replacing one of the core's - a version planner that
+     * knows its own ecosystem's dependency ranges - does it here, which is why that no longer needs a
+     * seam of its own on the plugin interface.
+     *
+     * Refused once the service has been built: something is already holding the old instance, and
+     * swapping the factory then would leave two answers to one question in play.
+     */
+    setService(name, factory) {
+        if (this.services.has(name)) {
+            throw new Error(`Service "${String(name)}" has already been built and cannot be replaced`);
+        }
+        this.factories.set(name, factory);
+    }
+    /**
+     * Called by `Repository.create`, after the plugins that find the packages have run.
+     *
+     * **One application, one repository**, and a second is refused. It was briefly "last one wins",
+     * because a single shared application made two repositories in one test collide; each
+     * `Repository.create` makes its own now, so the rule holds again and nothing in a process is
+     * shared by accident.
+     */
+    attachRepository(repository) {
+        if (this._repository)
+            throw new Error('This application already has a repository');
+        this._repository = repository;
+    }
+    _repository;
+    services = new Map();
+    factories = new Map();
+}

package/core/command-builder.d.ts

@@ -0,0 +1,14 @@
+import type { CommandModule } from 'yargs';
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+/**
+ * Turns a command's **declaration** into the yargs registration it describes.
+ *
+ * This is the one place that knows how the two relate, which is the point of declaring commands
+ * instead of building them: a command says what it has, and only this function says what yargs is
+ * told. Everything a `builder` used to do by hand - options, positionals, examples, parser
+ * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
+ * than a flag that silently never existed.
+ */
+export declare function toYargsCommand(meta: RmanConfig.CommandMetadata): CommandModule;
+/** A command's own name - the first word of its `command` string, before any positional. */
+export declare function commandName(command: string): string;