rman 1.3.0 → 2.0.0-beta.2

package/services/version-plan.service.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { RmanApplication } from '../core/application.js';
 import { assertOneScheme, semverScheme, VersionScheme } from '../core/version-scheme.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
@@ -118,7 +119,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));
@@ -152,6 +153,39 @@ export class VersionPlanService {
         }
         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.
      *
@@ -246,7 +280,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 +411,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 +418,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 { Service } from '../core/service.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/service.js' {
+    interface ServiceMap {
+        version: VersionService;
+    }
+}

package/services/version.service.js

@@ -2,11 +2,11 @@ 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/service.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
@@ -71,17 +83,20 @@ export var VersionService;
             interpolateConfig(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 +120,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 +167,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 +197,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 +276,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/targets/docker.target.d.ts

@@ -0,0 +1,53 @@
+import type { ConfigValue } from '../core/config.js';
+import type { PublishTarget } from '../core/publish-target.js';
+import type { ScopedVars } from '../interfaces/rman-config.interface.js';
+/**
+ * **`publish.docker.*`** - this target's own config block, declared here rather than centrally.
+ *
+ * Reaches `RmanConfig` through the `PublishTargetConfigs` slot `publish.command.ts` exports, which
+ * is the same slot the `node` built-in declares `publish.npm.*` in. Whoever reads a key declares it: the
+ * only thing that reads these is `DockerPublishService`, two files away.
+ *
+ * Required once `"docker"` is one of a package's `publish.target`s - `publish --target docker`
+ * errors clearly on a package that opts in and leaves this out.
+ */
+export interface DockerPublishOptions extends DockerPublishOptionsKeys, ScopedVars {
+}
+/** Every key here is a **value**, so every one is a `ConfigValue` - this target declares no step,
+ *  which is what makes the whole block uniform (see `VersionExtraKeys` for the interface where it
+ *  is not). */
+export interface DockerPublishOptionsKeys {
+    /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
+     *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
+     *  verbatim. */
+    image: ConfigValue<string>;
+    /** Relative to the package's own directory. Default `"Dockerfile"`. */
+    dockerfile?: ConfigValue<string>;
+    /** Default `["linux/amd64"]`. */
+    platforms?: ConfigValue<string[]>;
+    /** Build `cwd` override, relative to the repository root - only needed when the Dockerfile's
+     *  own `COPY`/`ADD` paths expect something other than the package's own directory (rare). */
+    cwd?: ConfigValue<string>;
+    /** Named `docker buildx build --build-context <name>=<path>` entries, keyed by name - each
+     *  path is relative to the package's own directory (or absolute). */
+    buildContexts?: ConfigValue<Record<string, string>>;
+    /** `docker buildx build --build-arg <name>=<value>` entries - a value of exactly `"$NAME"`
+     *  expands to `process.env.NAME` at build time (e.g. to pass a CI secret through). */
+    buildArgs?: ConfigValue<Record<string, string>>;
+    /** A file (relative to the package's own directory) whose contents become the DockerHub repo's
+     *  full description, if present. Default `"DOCKER_README.md"`. */
+    readme?: ConfigValue<string>;
+}
+/**
+ * **Docker, as a publish target** - the core's own, and the reason `PublishTarget` is in the core
+ * rather than in a plugin.
+ *
+ * Any language's project can ship an image; nothing about `docker buildx build --push` is npm's, or
+ * Cargo's, or Maven's. It was already a core *service*, and could still only be reached through
+ * `rman-node`'s `publish` command - so a repository with no JavaScript in it had to install a Node
+ * plugin to push a container. This file is the ten lines that fix that.
+ *
+ * Opt-in, and therefore no `claims`: most packages in a repository are not images, so a package
+ * ships here only by naming `"docker"` in its own `publish.target`.
+ */
+export declare const dockerPublishTarget: PublishTarget;

package/targets/docker.target.js

@@ -0,0 +1,40 @@
+import { DOCKER_TARGET } from '../services/docker-publish.service.js';
+/**
+ * **Docker, as a publish target** - the core's own, and the reason `PublishTarget` is in the core
+ * rather than in a plugin.
+ *
+ * Any language's project can ship an image; nothing about `docker buildx build --push` is npm's, or
+ * Cargo's, or Maven's. It was already a core *service*, and could still only be reached through
+ * `rman-node`'s `publish` command - so a repository with no JavaScript in it had to install a Node
+ * plugin to push a container. This file is the ten lines that fix that.
+ *
+ * Opt-in, and therefore no `claims`: most packages in a repository are not images, so a package
+ * ships here only by naming `"docker"` in its own `publish.target`.
+ */
+export const dockerPublishTarget = {
+    name: DOCKER_TARGET,
+    describe: 'Build and push a container image (docker buildx build --push)',
+    options: {
+        dockerNamespace: {
+            target: 'cli',
+            cliName: 'docker-namespace',
+            describe: 'Prefixed onto a bare (no "/") "publish.docker.image" - default: the DOCKERHUB_NAMESPACE ' +
+                'environment variable.',
+            type: 'string',
+        },
+    },
+    getPlan(ctx) {
+        return ctx.app.getService('dockerPublish').getPlan(optionsOf(ctx));
+    },
+    applyPlan(ctx, plan) {
+        /** The entries are this target's own - `getPlan` produced them - so the cast reads back what
+         *  was put in rather than claiming anything new. The command only ever passes a plan back to
+         *  the target that made it. */
+        return ctx.app.getService('dockerPublish').applyPlan(plan);
+    },
+};
+/** The shared filters plus the one flag this target declared - read here rather than in the service,
+ *  so the service keeps taking a plain options object and stays callable without a CLI. */
+function optionsOf(ctx) {
+    return { ...ctx.options, namespace: ctx.args.dockerNamespace };
+}

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

@@ -6,6 +6,35 @@ 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>;

package/utils/branch-guard.js

@@ -1,6 +1,37 @@
 import colors from 'ansi-colors';
 import micromatch from 'micromatch';
 import { GitHelper } from './git.js';
+/**
+ * `--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 const branchGuardOptions = {
+    allowBranch: {
+        target: 'cli',
+        cliName: 'allow-branch',
+        describe: 'Refuse to run unless the current branch matches this glob (repeatable) - default: .rmanrc ' +
+            '"allowBranch", or no restriction at all',
+        type: 'string',
+    },
+    ignoreBranch: {
+        target: 'cli',
+        cliName: 'ignore-branch',
+        describe: 'Refuse to run if the current branch matches this glob (repeatable) - default: .rmanrc ' +
+            '"ignoreBranch", or no restriction at all',
+        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 function applyBranchGuardOptions(cmd) {

package/utils/exec.d.ts

@@ -1,4 +1,14 @@
+import type { RmanApplication } from '../core/application.js';
 export interface ExecOptions {
+    /**
+     * The application whose technologies put a repository's locally installed binaries on PATH -
+     * `node_modules/.bin` for a Node repository, whatever another technology uses.
+     *
+     * Passed rather than looked up, so a command run against one repository can never pick up the
+     * binaries of another in the same process. Omitted (a caller outside any repository) leaves the
+     * inherited PATH exactly as it was, which is also what a repository naming no plugin gets.
+     */
+    app?: RmanApplication;
     /** 'inherit' streams the child directly to our stdio (used for non-TTY/CI passthrough).
      *  'pipe' (default) captures output so the caller can drive a live view via onLine. */
     stdio?: 'inherit' | 'pipe';

package/utils/exec.js

@@ -17,7 +17,7 @@ export async function exec(command, options) {
         ...options,
     };
     opts.env = {
-        ...BinPath.env({ cwd: opts.cwd }),
+        ...BinPath.env({ cwd: opts.cwd, app: opts.app }),
         ...opts.env,
     };
     opts.cwd = opts.cwd || process.cwd();

package/utils/logger.d.ts

@@ -4,7 +4,7 @@ export declare const LOG_LEVELS: LogLevel[];
 /**
  * Gates console output by verbosity (`--log-level`/`.rmanrc logLevel`) so a command's routine
  * narration can be turned down without losing failure output - the same semantics `run`'s own
- * classic per-step log already used (see `resolveLogLevel` in `commands/run.ts`), centralized here
+ * classic per-step log already used (see `resolveLogLevel` in `commands/run.command.ts`), centralized here
  * so every command can respect `--log-level` instead of reimplementing the checks, or ignoring it
  * altogether via plain `console.log`.
  */

package/utils/logger.js

@@ -2,7 +2,7 @@ export const LOG_LEVELS = ['silent', 'error', 'info', 'verbose'];
 /**
  * Gates console output by verbosity (`--log-level`/`.rmanrc logLevel`) so a command's routine
  * narration can be turned down without losing failure output - the same semantics `run`'s own
- * classic per-step log already used (see `resolveLogLevel` in `commands/run.ts`), centralized here
+ * classic per-step log already used (see `resolveLogLevel` in `commands/run.command.ts`), centralized here
  * so every command can respect `--log-level` instead of reimplementing the checks, or ignoring it
  * altogether via plain `console.log`.
  */