rman 1.3.0 → 2.0.0-beta.3

package/services/version-plan.service.d.ts

@@ -1,6 +1,7 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
-import { VersionScheme } from '../core/version-scheme.js';
+import { RmanApplication } from '../core/application.js';
+import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
+import { VersionScheme } from '../core/classes/version-scheme.js';
 import { type CommitInfo, GitHelper } from '../utils/git.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
@@ -97,6 +98,31 @@ export declare abstract class VersionPlanService {
      * wrong one here is invisible - it produces a plan that simply releases too little.
      */
     protected abstract cascade(bump: string): VersionPlanService.Cascade;
+    /**
+     * **Which planner answers for one package: its own technology's.**
+     *
+     * The two abstract members above are the ecosystem's, and a repository can hold more than one.
+     * `app.versionPlanner` is a single slot - last registration wins - so in a polyglot repository
+     * both of them used to be answered by whichever plugin happened to register last: a Cargo
+     * package's boundary fell back to `npm view`, and its cascade assumed npm's caret ranges. That is
+     * the same shape of bug the hardcoded `['npm']` publish default was, and the same fix - ask the
+     * technology that read the manifest.
+     *
+     * Falls back to `this`, which is what a single-technology repository always gets and what a
+     * `Plugin` contributing no planner of its own means.
+     */
+    protected plannerFor(pkg: Package): VersionPlanService;
+    /**
+     * `cascade` for a whole group, which is the unit it is asked about - one answer applies to every
+     * member, because the group releases as one version line.
+     *
+     * **Members disagreeing take the widest answer**, and the direction is deliberate: a cascade that
+     * is too narrow produces a plan that silently *releases too little* (the failure `cascade`'s own
+     * doc calls invisible), while one that is too wide releases a package that did not strictly need
+     * it - visible, and harmless. A mixed-technology group is unusual; a mixed group quietly skipping
+     * a dependent that pins exact versions is a broken install.
+     */
+    protected cascadeFor(members: Package[], bump: string): VersionPlanService.Cascade;
     /**
      * The largest bump `commits` ask for, in `scheme`'s own names.
      *
@@ -215,7 +241,11 @@ export declare namespace VersionPlanService {
         group: string;
         status: 'bump' | 'skip' | 'error' | 'no-change';
         from: string;
-        /** Only set when `status === 'bump'`. */
+        /** The version this package would receive. Set for `'bump'`, and for an `'error'` entry that
+         *  earned one - a package with uncommitted changes aborts the run, and `--show` exists to say
+         *  what it would get. **Never** set for `'skip'`: `--ignore-dirty` proceeds to write, and a
+         *  version beside an excluded package would name one it is not getting. So `status`, not `to`,
+         *  is what decides whether something is applied. */
         to?: string;
         /** Human-readable explanation - e.g. why a package was skipped, or why it's being bumped
          *  despite having no commits of its own (a dependency of it changed elsewhere). */
@@ -230,9 +260,6 @@ export declare namespace VersionPlanService {
      * repository layering its own policy plugin after `rman-node` could never take effect - which is
      * the only reason to name two in the first place.
      */
-    function setPlanner(planner: VersionPlanService): void;
-    /** For tests, which would otherwise leak a planner into every later case in the process. */
-    function clearPlanner(): void;
     /**
      * The registered planner. **Throws** when there is none, rather than falling back to some
      * built-in default: `Manifest` and `Workspace` can degrade honestly (a package named after its
@@ -240,5 +267,5 @@ export declare namespace VersionPlanService {
      * merely a diminished one - a wrong cascade or a wrong boundary reports a release that is
      * plausible and untrue.
      */
-    function getPlanner(): VersionPlanService;
+    function getPlanner(app: RmanApplication): VersionPlanService;
 }

package/services/version-plan.service.js

@@ -1,8 +1,10 @@
 import path from 'node:path';
-import { assertOneScheme, semverScheme, VersionScheme } from '../core/version-scheme.js';
+import { RmanApplication } from '../core/application.js';
+import { assertOneScheme, semverScheme, VersionScheme } from '../core/classes/version-scheme.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { findLastReleaseVersion, formatCalendarVersion, usesCalendarVersion } from '../utils/release-version.js';
+import { groupKeyOf } from '../utils/version-group.js';
 import { ConventionalCommitsService } from './conventional-commits.service.js';
 /**
  * Question A, computed and nothing else: **which packages have changed since their last release,
@@ -95,21 +97,39 @@ export class VersionPlanService {
         const packages = filterPackages(repository.getPackages(), options);
         const dirtyFiles = await git.listDirtyFiles({ absolute: true });
         const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const dirty = packages.filter(isDirty);
         const entries = new Map();
-        const eligible = [];
-        for (const pkg of packages) {
-            if (isDirty(pkg)) {
-                entries.set(pkg.name, {
-                    package: pkg,
-                    groupKey: this.resolveGroupKey(pkg),
-                    group: this.groupLabel(this.resolveGroupKey(pkg)),
-                    status: options.ignoreDirty ? 'skip' : 'error',
-                    from: pkg.version,
-                    reason: 'uncommitted local changes',
-                });
-                continue;
-            }
-            eligible.push(pkg);
+        /**
+         * **A dirty package is removed from the plan only when the run is going to proceed without it.**
+         * The two answers are not symmetric, and treating them as one is what left the `To` column
+         * blank on the command that exists to show it.
+         *
+         * - `--ignore-dirty` **writes**. The package is deliberately excluded, so it must not reach a
+         *   group either: a number its clean siblings receive cannot be derived from commits nobody is
+         *   releasing, and a `to` printed beside `skip` would name a version that package is not
+         *   getting. Diverted here, before `eligible`.
+         * - Aborting writes **nothing** - `getPlan` is pure and the command throws after printing - so
+         *   there is no number to keep safe, and the one thing the reader wants is what each package
+         *   would have got once it is committed. The plan is computed in full and the dirty entries are
+         *   marked at the very end, below.
+         *
+         * Excluding them from the abort case cost more than the column. `buildRootEntry` reads
+         * `e.to ?? e.from`, and its `groupCount` comes from the groups that were actually built - so a
+         * dirty tree quietly moved the repository's own release identity: measured on a four-package
+         * repo with `group: false`, three dirty packages left one group standing, which is
+         * `usesCalendarVersion`'s "one line" case, and the root reported `0.0.5 -> 2.1.6` on the
+         * *semver* path instead of the calendar version it takes with four.
+         */
+        const eligible = options.ignoreDirty ? packages.filter(pkg => !dirty.includes(pkg)) : packages;
+        for (const pkg of options.ignoreDirty ? dirty : []) {
+            entries.set(pkg.name, {
+                package: pkg,
+                groupKey: this.resolveGroupKey(pkg),
+                group: this.groupLabel(this.resolveGroupKey(pkg)),
+                status: 'skip',
+                from: pkg.version,
+                reason: 'uncommitted local changes',
+            });
         }
         const commitMessage = repository.rootPackage.config?.version?.commitMessage;
         const changeByPackage = new Map();
@@ -118,7 +138,7 @@ export class VersionPlanService {
                 changeByPackage.set(pkg.name, { bump: undefined, reason: `explicit version ${explicitVersion}` });
                 return;
             }
-            const since = await this.detectBoundary(git, pkg, options);
+            const since = await this.plannerFor(pkg).detectBoundary(git, pkg, options);
             const commits = since ? await git.listCommits({ hash: since }) : await git.listAllCommits();
             const belongsToPkg = (c) => c.files.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
             const real = commits.filter(c => belongsToPkg(c) && !ConventionalCommitsService.isReleaseCommit(c.subject, commitMessage));
@@ -150,8 +170,60 @@ export class VersionPlanService {
                 now: options.now ?? (() => new Date()),
             }));
         }
+        /**
+         * The abort case, marked **after** the root entry so the whole table reads as one coherent
+         * "if this were committed" preview rather than a mixture of two.
+         *
+         * `to` survives the overwrite; `status` is what every writer filters on (`VersionService`,
+         * `changed`), so an `'error'` entry carrying a version cannot be applied by any of them - and
+         * `version` throws on the first error before it would reach `applyPlan` anyway. The reason
+         * keeps the boundary it was computed from, because the status column already says `error` and
+         * a reader losing `changed since <tag>` loses the only thing that explains the number.
+         */
+        if (!options.ignoreDirty) {
+            for (const pkg of dirty) {
+                const entry = entries.get(pkg.name);
+                if (!entry)
+                    continue;
+                entry.status = 'error';
+                entry.reason = entry.reason ? `uncommitted local changes (${entry.reason})` : 'uncommitted local changes';
+            }
+        }
         return result;
     }
+    /**
+     * **Which planner answers for one package: its own technology's.**
+     *
+     * The two abstract members above are the ecosystem's, and a repository can hold more than one.
+     * `app.versionPlanner` is a single slot - last registration wins - so in a polyglot repository
+     * both of them used to be answered by whichever plugin happened to register last: a Cargo
+     * package's boundary fell back to `npm view`, and its cascade assumed npm's caret ranges. That is
+     * the same shape of bug the hardcoded `['npm']` publish default was, and the same fix - ask the
+     * technology that read the manifest.
+     *
+     * Falls back to `this`, which is what a single-technology repository always gets and what a
+     * `Plugin` contributing no planner of its own means.
+     */
+    plannerFor(pkg) {
+        return pkg.platform.versionPlanner ?? this;
+    }
+    /**
+     * `cascade` for a whole group, which is the unit it is asked about - one answer applies to every
+     * member, because the group releases as one version line.
+     *
+     * **Members disagreeing take the widest answer**, and the direction is deliberate: a cascade that
+     * is too narrow produces a plan that silently *releases too little* (the failure `cascade`'s own
+     * doc calls invisible), while one that is too wide releases a package that did not strictly need
+     * it - visible, and harmless. A mixed-technology group is unusual; a mixed group quietly skipping
+     * a dependent that pins exact versions is a broken install.
+     */
+    cascadeFor(members, bump) {
+        const answers = new Set(members.map(m => this.plannerFor(m).cascade(bump)));
+        for (const widest of CASCADE_WIDEST_FIRST)
+            if (answers.has(widest))
+                return widest;
+        return 'changed';
+    }
     /**
      * The largest bump `commits` ask for, in `scheme`'s own names.
      *
@@ -196,12 +268,7 @@ export class VersionPlanService {
      *  group; a non-empty string joins exactly the other packages sharing that string, regardless of
      *  the repo's own default; `false` makes it a solo group of one. */
     resolveGroupKey(pkg) {
-        const g = pkg.config?.group;
-        if (g === false)
-            return `solo:${pkg.name}`;
-        if (typeof g === 'string' && g)
-            return `named:${g}`;
-        return 'default';
+        return groupKeyOf(pkg);
     }
     /** The human-readable name behind a `groupKey` - what a plan's `group` column shows. */
     groupLabel(key) {
@@ -246,7 +313,7 @@ export class VersionPlanService {
             to = scheme.next(current, bump, { preid });
         }
         const bumping = new Set(changed);
-        const cascade = bump ? this.cascade(bump) : 'changed';
+        const cascade = bump ? this.cascadeFor(members, bump) : 'changed';
         if (cascade === 'group') {
             for (const m of members)
                 bumping.add(m);
@@ -377,15 +444,6 @@ export class VersionPlanService {
      * repository layering its own policy plugin after `rman-node` could never take effect - which is
      * the only reason to name two in the first place.
      */
-    function setPlanner(planner) {
-        current = planner;
-    }
-    VersionPlanService.setPlanner = setPlanner;
-    /** For tests, which would otherwise leak a planner into every later case in the process. */
-    function clearPlanner() {
-        current = undefined;
-    }
-    VersionPlanService.clearPlanner = clearPlanner;
     /**
      * The registered planner. **Throws** when there is none, rather than falling back to some
      * built-in default: `Manifest` and `Workspace` can degrade honestly (a package named after its
@@ -393,16 +451,18 @@ export class VersionPlanService {
      * merely a diminished one - a wrong cascade or a wrong boundary reports a release that is
      * plausible and untrue.
      */
-    function getPlanner() {
-        if (!current) {
+    function getPlanner(app) {
+        const planner = app.versionPlanner;
+        if (!planner) {
             throw new Error('No version planner is registered, so no version plan can be computed. Name a plugin that ' +
                 'contributes one in .rmanrc "plugins" - "rman-node" for a Node repository.');
         }
-        return current;
+        return planner;
     }
     VersionPlanService.getPlanner = getPlanner;
-    let current;
 })(VersionPlanService || (VersionPlanService = {}));
+/** Widest reach first - what `cascadeFor` walks when a group's members answer differently. */
+const CASCADE_WIDEST_FIRST = ['group', 'dependents', 'changed'];
 /** What one commit says happened, with no reference to any version format - `VersionScheme.bumpFor`
  *  turns it into a number's movement. Everything unrecognized is a `'fix'`: something changed, so
  *  the smallest release is still warranted. */

package/services/version.service.d.ts

@@ -1,17 +1,41 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
-import type { RunStepValue } from '../core/run-step.js';
+import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
+import { Service } from '../core/classes/service.js';
+import type { RunStepValue } from '../core/interfaces/run-step.js';
 import { VersionPlanService } from './version-plan.service.js';
 /**
  * Applying a version plan: the writes. Every manifest edit, dependency-range refresh, stamp,
  * commit and tag lives here; **what** to write is `VersionPlanService`'s answer.
  *
  * Nothing here knows what a `package.json` is, names an npm script, or runs a command: the version
- * goes through `Manifest`/`ManifestProvider`, refreshing a sibling's dependency range goes through
+ * goes through `Manifest`/`Plugin`'s manifest members, refreshing a sibling's dependency range goes through
  * the same provider, and the lifecycle hooks around the write go through
  * `RunService.runLifecycleSlot` - this module only supplies the `.rmanrc version.<slot>` fallback,
  * which is its own config. What is left is git, that config, and the version stamps.
  */
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had.
+ *
+ * **Only `applyPlan` became a method**, because only it takes a repository. `buildCommitMessage`,
+ * `stampDockerfile`, `stampSourceFiles` and `normalizeScriptValue` take a `Package` or nothing and
+ * stay functions on the namespace below - the same rule that leaves `ChangeHashService` a namespace
+ * entirely.
+ *
+ * **Declared before the namespace**, which TypeScript requires: the other order is
+ * `A namespace declaration cannot be located prior to a class with which it is merged`.
+ */
+export declare class VersionService extends Service {
+    /**
+     * Writes every `'bump'` entry's new version into its own manifest (and refreshes any other bumped
+     * package's dependency range on it), runs that package's own version-lifecycle hooks or its
+     * `.rmanrc version.before`/`.exec`/`.after` around the write - see the `hook` closure below -
+     * then commits and tags **once per group** - so independently-versioned groups each get their own clean commit/tag rather than one entangled
+     * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
+     * plain `npm version`, this never reaches the network on its own otherwise.
+     */
+    applyPlan(plan: VersionPlanService.Entry[], options?: VersionService.ApplyOptions): Promise<VersionService.ApplyResult>;
+}
 export declare namespace VersionService {
     interface ApplyOptions {
         /** Push the resulting commit(s) and tag(s) to the remote once applied. Default false - same
@@ -61,15 +85,6 @@ export declare namespace VersionService {
         /** True for the repository's own release tag, which belongs to no single package. */
         release?: boolean;
     }
-    /**
-     * Writes every `'bump'` entry's new version into its own manifest (and refreshes any other bumped
-     * package's dependency range on it), runs that package's own version-lifecycle hooks or its
-     * `.rmanrc version.before`/`.exec`/`.after` around the write - see the `hook` closure below -
-     * then commits and tags **once per group** - so independently-versioned groups each get their own clean commit/tag rather than one entangled
-     * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
-     * plain `npm version`, this never reaches the network on its own otherwise.
-     */
-    function applyPlan(repository: Repository, plan: VersionPlanService.Entry[], options?: ApplyOptions): Promise<ApplyResult>;
     /** `.rmanrc version.commitMessage` (root-level; `{version}` is replaced when every bumped package
      *  in this commit shares one version) - defaults to `"chore(release): v{version}"`, or a plain
      *  listing of `name@version` pairs when this particular commit spans different versions (a
@@ -119,8 +134,13 @@ export declare namespace VersionService {
      * pattern missed it) released a tagged commit with a stale constant and said nothing. The error
      * names the file and, when the package's ecosystem declared none, says so.
      *
-     * *How* a version is declared is the provider's (`ManifestProvider.stampVersion`); *which* files
+     * *How* a version is declared is the provider's (`Plugin.stampVersion`); *which* files
      * hold one is the repository's, which is why the list is config and the rewrite is a seam.
      */
     function stampSourceFiles(pkg: Package, version: string): string[];
 }
+declare module '../core/classes/service.js' {
+    interface ServiceMap {
+        version: VersionService;
+    }
+}

package/services/version.service.js

@@ -1,12 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { interpolateConfig } from '../core/config.js';
-import { Manifest } from '../core/manifest.js';
+import { Service } from '../core/classes/service.js';
+import { ConfigInterpolator } from '../core/config/config-interpolator.js';
+import { Manifest } from '../core/interfaces/manifest.js';
 import { GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion } from '../utils/release-version.js';
 import { stampVersionLabel } from '../utils/version-stamp.js';
 import { ChangeHashService } from './change-hash.service.js';
-import { ChangelogService } from './changelog.service.js';
 import { RunService } from './run.service.js';
 import { VersionPlanService } from './version-plan.service.js';
 /**
@@ -14,13 +14,24 @@ import { VersionPlanService } from './version-plan.service.js';
  * commit and tag lives here; **what** to write is `VersionPlanService`'s answer.
  *
  * Nothing here knows what a `package.json` is, names an npm script, or runs a command: the version
- * goes through `Manifest`/`ManifestProvider`, refreshing a sibling's dependency range goes through
+ * goes through `Manifest`/`Plugin`'s manifest members, refreshing a sibling's dependency range goes through
  * the same provider, and the lifecycle hooks around the write go through
  * `RunService.runLifecycleSlot` - this module only supplies the `.rmanrc version.<slot>` fallback,
  * which is its own config. What is left is git, that config, and the version stamps.
  */
-export var VersionService;
-(function (VersionService) {
+/**
+ * A service class - see `ListService` for the shape and `Service` for the three measured
+ * consequences a namespace had.
+ *
+ * **Only `applyPlan` became a method**, because only it takes a repository. `buildCommitMessage`,
+ * `stampDockerfile`, `stampSourceFiles` and `normalizeScriptValue` take a `Package` or nothing and
+ * stay functions on the namespace below - the same rule that leaves `ChangeHashService` a namespace
+ * entirely.
+ *
+ * **Declared before the namespace**, which TypeScript requires: the other order is
+ * `A namespace declaration cannot be located prior to a class with which it is merged`.
+ */
+export class VersionService extends Service {
     /**
      * Writes every `'bump'` entry's new version into its own manifest (and refreshes any other bumped
      * package's dependency range on it), runs that package's own version-lifecycle hooks or its
@@ -29,7 +40,8 @@ export var VersionService;
      * commit spanning unrelated version lines. Pushes only when `options.push` is set - same as a
      * plain `npm version`, this never reaches the network on its own otherwise.
      */
-    async function applyPlan(repository, plan, options = {}) {
+    async applyPlan(plan, options = {}) {
+        const repository = this.repository;
         const git = new GitHelper({ cwd: repository.dirname });
         // The root's own entry is only ever a real package to write/commit like any other when this
         // *isn't* a monorepo (see `getPlan`) - in a monorepo it's the separate, purely informational
@@ -53,6 +65,9 @@ export var VersionService;
          */
         for (const entry of bumped)
             assertStampable(entry.package, entry.to);
+        /** One for the whole run: it carries no per-package state, and `defer(...)`'s bookkeeping is
+         *  per call. */
+        const interpolator = new ConfigInterpolator();
         for (const entry of bumped) {
             const pkg = entry.package;
             /** The scope these hooks are evaluated against - the only place `${{ pkg.targetVersion }}`
@@ -68,20 +83,23 @@ export var VersionService;
             const hook = (slot) => RunService.runLifecycleSlot(pkg, VERSION_LIFECYCLE, slot, RunService.normalizeScriptValue(
             /** `at`: the path is what tells a step function from a value one, and this is a fragment -
              *  without it a function here was called while the hook was being prepared. */
-            interpolateConfig(pkg.config?.version?.[slot], scope, { at: ['version', slot] }), `version.${slot}`));
+            interpolator.interpolate({ config: pkg.config?.version?.[slot], scope, at: ['version', slot] }), `version.${slot}`));
             await hook('before');
             /** Through the manifest, not through a `package.json` field: where a version is written is
-             *  the provider's business (see `ManifestProvider`), and this is the one place rman changes
+             *  the provider's business (see `Plugin`'s manifest members), and this is the one place rman changes
              *  it. */
             pkg.manifest.version = entry.to;
             /** Which fields hold a sibling reference, and what a reference even looks like, is the
              *  ecosystem's - npm's four fields and its `"workspace:"` protocol used to be spelled out
-             *  here. See `ManifestProvider.updateDependencyVersions`. */
+             *  here. See `Plugin.updateDependencyVersions`. */
             Manifest.updateDependencyVersions(pkg, bumpedVersions);
             await hook('exec');
             pkg.writeManifest();
             // Before the `after` hook, so a script reacting to the bump sees the whole new state.
-            const stamped = [stampDockerfile(pkg, entry.to), ...stampSourceFiles(pkg, entry.to)].filter((f) => !!f);
+            const stamped = [
+                VersionService.stampDockerfile(pkg, entry.to),
+                ...VersionService.stampSourceFiles(pkg, entry.to),
+            ].filter((f) => !!f);
             if (stamped.length) {
                 stampedByPackage.set(pkg.name, stamped.map(f => path.relative(repository.dirname, f)));
             }
@@ -105,9 +123,9 @@ export var VersionService;
             for (const entry of bumped) {
                 const fromTag = ChangeHashService.expandTag(entry.package, entry.from);
                 const from = (await git.tagExists(fromTag)) ? fromTag : undefined;
-                const changelogEntries = await ChangelogService.generateToFile(repository, {
+                const changelogEntries = await this.app.getService('changelog').generateToFile({
                     scope: entry.package.name,
-                    root: true,
+                    fromRoot: true,
                     from,
                     // The tag for this release doesn't exist yet (it's created below), so changelog's own
                     // tag-derived version would resolve to the *previous* release and label the entry with it.
@@ -152,7 +170,7 @@ export var VersionService;
                     files.push(changelogFile);
                 files.push(...(stampedByPackage.get(e.package.name) ?? []));
             }
-            const message = buildCommitMessage(repository, groupEntries, options.message);
+            const message = VersionService.buildCommitMessage(repository, groupEntries, options.message);
             const sha = await git.commit(files, message);
             commits.push({ sha, message, packages: groupEntries.map(e => e.package.name) });
             const tags = new Set(groupEntries.map(e => ChangeHashService.expandTag(e.package, e.to)));
@@ -182,7 +200,8 @@ export var VersionService;
             await git.push();
         return { entries: plan, updated: bumped, commits, tags: tagged, pushed };
     }
-    VersionService.applyPlan = applyPlan;
+}
+(function (VersionService) {
     /** `.rmanrc version.commitMessage` (root-level; `{version}` is replaced when every bumped package
      *  in this commit shares one version) - defaults to `"chore(release): v{version}"`, or a plain
      *  listing of `name@version` pairs when this particular commit spans different versions (a
@@ -260,7 +279,7 @@ export var VersionService;
      * pattern missed it) released a tagged commit with a stale constant and said nothing. The error
      * names the file and, when the package's ecosystem declared none, says so.
      *
-     * *How* a version is declared is the provider's (`ManifestProvider.stampVersion`); *which* files
+     * *How* a version is declared is the provider's (`Plugin.stampVersion`); *which* files
      * hold one is the repository's, which is why the list is config and the rewrite is a seam.
      */
     function stampSourceFiles(pkg, version) {

package/services.d.ts

@@ -1,5 +1,5 @@
+export { DockerPublishService } from './builtins/publish-targets/docker/docker-publish.service.js';
 export { ChangelogService } from './services/changelog.service.js';
-export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';

package/services.js

@@ -1,5 +1,5 @@
+export { DockerPublishService } from './builtins/publish-targets/docker/docker-publish.service.js';
 export { ChangelogService } from './services/changelog.service.js';
-export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
 export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';

package/utils/bin-path.d.ts

@@ -1,3 +1,4 @@
+import { RmanApplication } from '../core/application.js';
 /**
  * Where a repository's **locally installed executables** live, so a command an author wrote
  * (`eslint .`, `cargo build`) is found the way it would be in their own shell.
@@ -6,7 +7,7 @@
  *
  * - **Which directories** is the *ecosystem's* answer, and the core has none - `node_modules/.bin`
  *   walked up the directory chain is npm's layout and nothing else's (a Python venv says
- *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `RmanPlugin.binPaths`.
+ *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `Plugin.getBinPaths`.
  * - **How a PATH is spelled** is the *operating system's*, and that stays here: the variable is
  *   `PATH` everywhere except Windows, where its case is whatever the environment happens to use.
  *   That has nothing to do with any ecosystem, and every provider would otherwise get it wrong
@@ -22,20 +23,18 @@ export declare namespace BinPath {
      *  Return them most-specific-first; the core concatenates providers without reordering. */
     type Provider = (cwd: string) => string[];
     interface EnvOptions {
+        /** The application whose technologies contribute directories. Omitted where a caller genuinely
+         *  has none - `exec` outside a repository - which leaves the inherited PATH untouched. */
+        readonly app?: RmanApplication;
         /** The directory the command will run in. Default `process.cwd()`. */
         readonly cwd?: string;
         /** The environment to derive from, like `process.env`. Default `process.env`. */
         readonly env?: ProcessEnv;
     }
-    /** Registers a provider. Called by `loadPlugins` for each plugin's `binPaths`, in `plugins`
-     *  declaration order - so what is on PATH is a function of the repository's own config. */
-    function addProvider(provider: Provider): void;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders(): void;
     /** Every provider's directories for `cwd`, concatenated in declaration order. Empty for a
      *  repository that names no plugin - the inherited PATH then stands on its own, which is the
      *  honest answer rather than a guess at some ecosystem's layout. */
-    function resolve(cwd: string): string[];
+    function resolve(app: RmanApplication, cwd: string): string[];
     /**
      * `env` with the contributed directories prepended to its PATH - what `exec` and `runBin` hand to
      * a child process.

package/utils/bin-path.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import process from 'node:process';
+import { RmanApplication } from '../core/application.js';
 /**
  * Where a repository's **locally installed executables** live, so a command an author wrote
  * (`eslint .`, `cargo build`) is found the way it would be in their own shell.
@@ -8,7 +9,7 @@ import process from 'node:process';
  *
  * - **Which directories** is the *ecosystem's* answer, and the core has none - `node_modules/.bin`
  *   walked up the directory chain is npm's layout and nothing else's (a Python venv says
- *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `RmanPlugin.binPaths`.
+ *   `.venv/bin`, a Ruby project `bin`). `rman-node` contributes it; see `Plugin.getBinPaths`.
  * - **How a PATH is spelled** is the *operating system's*, and that stays here: the variable is
  *   `PATH` everywhere except Windows, where its case is whatever the environment happens to use.
  *   That has nothing to do with any ecosystem, and every provider would otherwise get it wrong
@@ -20,25 +21,12 @@ import process from 'node:process';
  */
 export var BinPath;
 (function (BinPath) {
-    /** Registers a provider. Called by `loadPlugins` for each plugin's `binPaths`, in `plugins`
-     *  declaration order - so what is on PATH is a function of the repository's own config. */
-    function addProvider(provider) {
-        if (providers.includes(provider))
-            return;
-        providers.push(provider);
-    }
-    BinPath.addProvider = addProvider;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders() {
-        providers.length = 0;
-    }
-    BinPath.clearProviders = clearProviders;
     /** Every provider's directories for `cwd`, concatenated in declaration order. Empty for a
      *  repository that names no plugin - the inherited PATH then stands on its own, which is the
      *  honest answer rather than a guess at some ecosystem's layout. */
-    function resolve(cwd) {
+    function resolve(app, cwd) {
         const dir = path.resolve(cwd);
-        return providers.flatMap(provider => provider(dir));
+        return [...app.platforms].flatMap(stack => stack.getBinPaths?.(dir) ?? []);
     }
     BinPath.resolve = resolve;
     /**
@@ -52,7 +40,9 @@ export var BinPath;
         const cwd = options.cwd || process.cwd();
         const result = { ...(options.env || process.env) };
         const key = pathKey({ env: result });
-        const entries = resolve(cwd);
+        /** No application means no technologies, so nothing is prepended and the inherited PATH stands
+         *  on its own - the same answer a repository naming no plugin has always got. */
+        const entries = options.app ? resolve(options.app, cwd) : [];
         if (!entries.length)
             return result;
         const inherited = result[key];
@@ -78,5 +68,4 @@ export var BinPath;
             .find(key => key.toUpperCase() === 'PATH') || 'Path');
     }
     BinPath.pathKey = pathKey;
-    const providers = [];
 })(BinPath || (BinPath = {}));

package/utils/branch-guard.d.ts

@@ -1,11 +1,40 @@
 import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
+import type { Repository } from '../core/classes/repository.js';
 /** Same idea as GitHub Actions' own `branches`/`branches-ignore` workflow filters - restricts a
  *  command to running only from certain branches (or refuses certain ones), instead of any. */
 export interface BranchGuardOptions {
     allowBranch?: string | string[];
     ignoreBranch?: string | string[];
 }
+/**
+ * `--allow-branch`/`--ignore-branch` as a declaration, to spread into a command's `config` block.
+ * See `packageFilterOptions` for why this is `satisfies` rather than an annotation.
+ *
+ * **The key is the camelCase one and `cliName` carries the flag's spelling.** `allowBranch` is what
+ * a `.rmanrc` writes and what `assertAllowedBranch` reads off the config; `--allow-branch` is what
+ * the shell sees. The `Argv` version relied on yargs converting one into the other silently, which
+ * is why `applyBranchGuardOptions` declares `'allow-branch'` and `readBranchGuardOptions` reads
+ * `args.allowBranch`.
+ *
+ * **`target: 'cli'`, even though `allowBranch` *is* a config key.** It is a repo-wide core key read
+ * off the root, not any command's - so it belongs on `RmanConfig` directly, and a command that
+ * reads it names it in `configKeys`. Declaring it `'both'` here would contribute `version.allowBranch`,
+ * which nothing reads.
+ */
+export declare const branchGuardOptions: {
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+};
 /** `--allow-branch`/`--ignore-branch`, the same shape and describe text in every command that
  *  supports them - mirrors `package-filter.ts`'s own `applyPackageFilterOptions`. */
 export declare function applyBranchGuardOptions<T>(cmd: Argv<T>): Argv<T>;