rman 1.3.0 → 2.0.0-beta.3

package/commands/version.command.js

@@ -1,11 +1,118 @@
 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',
+    },
+    json: {
+        target: 'cli',
+        alias: 'j',
+        describe: 'Print the plan as JSON and write nothing - the machine-readable form of --show, and what ' +
+            'the removed "changed" command was for.',
+        type: 'boolean',
+        conflicts: ['interactive', 'yes'],
+    },
+    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,77 +122,89 @@ 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,
                 preid: args.preid,
             });
+            /**
+             * **The machine-readable plan, and the whole of it.** This replaced `rman changed`, which
+             * was `getPlan` filtered to `status === 'bump'` - and that one-line filter produced two
+             * silent wrongs at once, measured together on a dirty tree: the entry it returned was the
+             * repository **root** (`buildRootEntry` reports `'bump'`, and the fact that it is
+             * informational lived only in `reason`), while `pkg-a`, the package that had actually
+             * changed, was dropped because a package with uncommitted changes is `'error'`. A CI script
+             * reading that array saw one name to release and it was the one name that must never be
+             * published.
+             *
+             * So nothing is filtered here. Every entry carries its own `status`, and `isRoot` is stated
+             * rather than left to be inferred from `group === "root"` - a consumer selects what it wants
+             * and can see what it is leaving out. Printed **before** the table and before the
+             * dirty-package throw, so stdout holds one JSON document and nothing else.
+             *
+             * **Exit 0 either way, deliberately.** `--show` exits 1 on a dirty package because a person
+             * needs stopping; here the same fact is in the data, and overloading the exit code would
+             * make a pipeline bail before it could read the very rows that explain why.
+             */
+            if (args.json) {
+                console.log(JSON.stringify(plan.map(e => ({
+                    name: e.package.name,
+                    selector: e.package.selector,
+                    isRoot: e.package.isRoot,
+                    group: e.group,
+                    status: e.status,
+                    from: e.from,
+                    to: e.to,
+                    reason: e.reason,
+                })), undefined, 2));
+                return;
+            }
             printPlan(plan);
             const errors = plan.filter(e => e.status === 'error');
             if (errors.length) {
@@ -115,15 +234,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.
  *
@@ -156,18 +276,112 @@ function printApplied(result) {
 }
 function printPlan(entries) {
     const table = new EasyTable();
-    for (const e of entries) {
-        table.cell('Status', statusLabel(e.status));
-        table.cell('Package', colors.cyan(e.package.name));
-        table.cell('Group', colors.gray(`(${e.group})`));
-        table.cell('From', e.from);
-        table.cell('', e.status === 'bump' ? '->' : '');
-        table.cell('To', e.status === 'bump' ? colors.yellow(e.to) : '');
-        table.cell('Reason', e.status === 'error' ? colors.red(e.reason ?? '') : colors.gray(e.reason ?? ''));
-        table.newRow();
+    let first = true;
+    for (const { members, shared } of planBlocks(entries)) {
+        if (!first)
+            table.pushDelimeter(PLAN_COLUMNS);
+        first = false;
+        for (const e of members)
+            printPlanRow(table, e, shared);
     }
     console.log(table.toString().trim());
 }
+/**
+ * The plan, split into the blocks a delimiter is drawn between: the **repository root** first, then
+ * every shared version line with its members together, then the packages that share a line with
+ * nobody.
+ *
+ * `getPlan` returns entries in *package* order, which is the order the workspace found them in -
+ * so two members of one group are adjacent only by luck. That matters more than it looks: a group
+ * releases as one version line, so "these four numbers move together" is the single fact the table
+ * exists to convey, and scattering the members leaves the `Group` column as the only thing saying
+ * so. Read top to bottom instead, each block now *is* a release.
+ *
+ * **The root is first, and it is the one row that is not a release.** Its number is the
+ * repository's identity - what the GitHub Release is named after, and on a calendar version a
+ * number no package shares - so it is the heading the rest of the table sits under rather than a
+ * footnote to it. `buildRootEntry` appends it, which is why it is pulled out by hand here; leaving
+ * it where the plan put it made it the last singleton, indistinguishable from a package that
+ * happens to be grouped with no one.
+ *
+ * **Solo packages are one block, not one block each.** `group: false` makes every package its own
+ * group of one, so a delimiter per group would draw a line between every row in exactly the
+ * repository that has nothing to group - noise standing in for structure. They share a block
+ * because what they have in common is real: none of them is tied to anyone else.
+ *
+ * `shared` travels with each block because it is also what decides whether the `Group` column is
+ * written at all - see `printPlanRow`. One partition, asked once, answering both questions; working
+ * it out again at the cell would be a second rule that could disagree with the blocks beside it.
+ */
+function planBlocks(entries) {
+    /**
+     * `package.isRoot` is by **directory**, which is the only reliable test - `Repository extends
+     * Package` while holding a separate `rootPackage` instance for the same directory, so an identity
+     * check answers `false` for one of the two objects that are both the root.
+     *
+     * In a single-package repository that one package *is* the root and `getPlan` pushes no root
+     * entry of its own, so it lands here and prints alone - one row, and no delimiter to draw.
+     */
+    const root = entries.filter(e => e.package.isRoot);
+    const members = entries.filter(e => !e.package.isRoot);
+    const byGroup = new Map();
+    for (const e of members) {
+        const group = byGroup.get(e.groupKey);
+        if (group)
+            group.push(e);
+        else
+            byGroup.set(e.groupKey, [e]);
+    }
+    const shared = [];
+    const solo = [];
+    for (const group of byGroup.values()) {
+        if (group.length > 1)
+            shared.push({ members: group, shared: true });
+        else
+            solo.push(group[0]);
+    }
+    return [
+        ...(root.length ? [{ members: root, shared: false }] : []),
+        ...shared,
+        ...(solo.length ? [{ members: solo, shared: false }] : []),
+    ];
+}
+/** `buildRootEntry`'s display label. Named here because `printPlanRow` has to recognize the one
+ *  singleton whose group is worth printing, and a bare `'root'` in a condition reads as a guess. */
+const ROOT_GROUP = 'root';
+/** The column names in the order `printPlanRow` writes them - `pushDelimeter` has to be handed the
+ *  same set, or the dashes appear under a column that does not exist yet. */
+const PLAN_COLUMNS = ['Status', 'Package', 'Group', 'From', '', 'To', 'Reason'];
+function printPlanRow(table, e, shared) {
+    table.cell('Status', statusLabel(e.status));
+    table.cell('Package', colors.cyan(e.package.name));
+    /**
+     * **Blank for a package that shares its version line with nobody.** `resolveGroupKey` gives an
+     * ungrouped package a group of one named after the package, so the cell printed the Package
+     * column again, one column to the right - a word that looks like information and carries none.
+     * Worse, it made `(default)` and `(@panates/tsconfig)` read as the same *kind* of answer when one
+     * names a line four packages move along and the other names nothing at all.
+     *
+     * The root keeps its label: `root` is not its package name but what the row *is*, and it is the
+     * only thing on the line saying that the number below is the repository's identity rather than a
+     * release. So the test is `shared`, plus that one entry - not "does this string repeat the name",
+     * which would blank a genuine group that happened to be called after one of its members.
+     */
+    table.cell('Group', shared || e.group === ROOT_GROUP ? colors.gray(`(${e.group})`) : '');
+    table.cell('From', e.from);
+    /**
+     * Gated on `to`, not on `status === 'bump'`, which is what kept the column blank on the one
+     * command whose whole job is to fill it: a dirty package aborts the run, and "you cannot
+     * release this" is only half of what the reader came for - the other half is which version it
+     * would have got. `getPlan` sets `to` on exactly the entries that earned one, so asking whether
+     * there is a version to show is the honest test. Dimmed rather than yellow when the entry is
+     * not a bump, because that number is a hypothetical and nothing is going to write it.
+     */
+    table.cell('', e.to ? '->' : '');
+    table.cell('To', e.to ? (e.status === 'bump' ? colors.yellow(e.to) : colors.gray(e.to)) : '');
+    table.cell('Reason', e.status === 'error' ? colors.red(e.reason ?? '') : colors.gray(e.reason ?? ''));
+    table.newRow();
+}
 function statusLabel(status) {
     switch (status) {
         case 'bump':

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/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/lint.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/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/lint.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.3.0';
+export const version = '2.0.0-beta.3';

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 { Registry } from './classes/registry.js';
+import type { Repository } from './classes/repository.js';
+import type { ServiceFactory, ServiceMap } from './classes/service.js';
+import { type Platform, type Plugin } from './interfaces/plugin.js';
+import type { PublishTarget } from './interfaces/publish-target.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;
+    /** `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;
+    });
+    /** 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;
+    /**
+     * 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;
+}