rman 1.0.12 → 1.2.1

package/core/version-scheme.d.ts

@@ -0,0 +1,134 @@
+/**
+ * What the commits said *happened*, in Conventional Commits' own terms: a `!` or `BREAKING CHANGE:`
+ * footer, a `feat:`, or anything else (a `fix:`, an unrecognized type, a non-conventional subject).
+ *
+ * Three, because three is how many sizes a commit message distinguishes - which is a fact about
+ * commit messages, not about any version format. It is deliberately **not** `patch`/`minor`/`major`:
+ * those are semver's words for how a *number* moves, and a scheme numbering
+ * `major.minor.build.revision` has four of those and no `patch` at all. `VersionScheme.bumpFor`
+ * translates one of these into a bump that scheme actually has a name for.
+ */
+export type ChangeKind = 'fix' | 'feature' | 'breaking';
+/**
+ * How a package's versions are numbered: named, ordered, validated, and advanced.
+ *
+ * rman's release model was written in semver - tag patterns, changelog headings, release identity,
+ * "is this version on the registry yet", `"workspace:"` range rewriting all assume versions that
+ * can be ordered and incremented. This is the seam for an ecosystem that numbers differently (PEP
+ * 440, a date-based scheme, a build counter), and it is a *meaning* seam rather than a storage one:
+ * `ManifestProvider` answers "where is the version written", this answers "what does the next one
+ * look like".
+ *
+ * **`bumpNames` and `bumpFor` are the interesting part.** `fix:` -> patch, `feat:` -> minor,
+ * `feat!:` -> major is a sentence in *semver's* vocabulary from end to end, so a scheme that numbers
+ * differently does not need a different `inc()` - it needs its own set of bump names and its own
+ * answer to "what does a `feat:` mean for one of my version numbers". A CalVer scheme can
+ * legitimately answer all three with the same name and return today's date; that is the scheme's
+ * decision to make, which is why the seam is here and not around `semver.inc`.
+ *
+ * **An abstract class rather than an interface**, for the reason `VersionPlanService` is one:
+ * `highestVersion`, `highestBump` and `smallestBump` all *derive* from the members below them, so
+ * requiring every scheme to write them would be boilerplate and a second place for two answers to
+ * disagree - but each is a real decision a scheme may need to make differently (a repo maintaining
+ * parallel lines has its own idea of "highest"; a four-part scheme may want the ripple bump to be
+ * `build` rather than its actual smallest). Implemented here, overridable there. Subclass
+ * `SemverScheme` to keep semver's numbering and change only one of these.
+ */
+export declare abstract class VersionScheme {
+    /** For error messages, and for `info`. */
+    abstract readonly name: string;
+    /**
+     * Every bump this scheme accepts by name, **smallest first** - semver's
+     * `['patch', 'minor', 'major']`, a four-part `major.minor.build.revision` scheme's
+     * `['revision', 'build', 'minor', 'major']`.
+     *
+     * The scheme's, not rman's, because these are names for how a *version number* moves and only the
+     * scheme knows what parts it has. This is what `rman version <bump>` validates against and what
+     * `--help` lists, so a repository is offered the bumps its own numbering actually has.
+     *
+     * **The order is the default ranking** read by `highestBump` and `smallestBump`.
+     */
+    abstract readonly bumpNames: readonly string[];
+    /** Which of `bumpNames` a change of this kind calls for - the translation from what a commit said
+     *  to how this scheme's numbers move. A scheme that does not distinguish them may answer all
+     *  three the same. */
+    abstract bumpFor(kind: ChangeKind): string;
+    /** Is this a version this scheme recognizes? Used to accept an explicitly given version. */
+    abstract isValid(version: string): boolean;
+    /** Negative, zero or positive - `Array.prototype.sort`'s contract. */
+    abstract compare(a: string, b: string): number;
+    /** The version after `current`, given one of this scheme's own `bumpNames`. `preid` asks for a
+     *  prerelease line (`--preid`), which a scheme without such a concept may ignore. */
+    abstract next(current: string, bump: string, options?: {
+        preid?: string;
+    }): string;
+    /** Is this version a preview rather than a release? `github-release` reads it. */
+    abstract isPrerelease(version: string): boolean;
+    /**
+     * The highest of `versions` - a group's current version is the highest among its members, and a
+     * monorepo root's release identity the highest among the groups.
+     *
+     * Empty in, `undefined` out: a group with no versions has no highest one, and guessing `0.0.0`
+     * would put a real version line at risk. Override to answer differently - a repository
+     * maintaining parallel lines (a 1.x still receiving fixes beside a 2.x) may want the line being
+     * released rather than the numerically largest.
+     */
+    highestVersion(versions: readonly string[]): string | undefined;
+    /**
+     * The largest of `bumps` - what a group takes when its changed members ask for different sizes.
+     * Empty in, `undefined` out.
+     *
+     * A name this scheme does not declare ranks **below** every name it does, rather than throwing -
+     * a comparison helper is the wrong place to fail a release. It is a second line of defence, not
+     * the guard: `detectBump` already drops an unrecognized `Release-As:` footer before it gets here,
+     * because ranking such a word low is not the same as ignoring it (ranked low it still *replaces*
+     * what the commit's own subject said - measured, and it turned a `feat:` into a patch).
+     *
+     * Override for bumps that are not totally ordered, or to refuse an unknown name outright.
+     */
+    highestBump(bumps: readonly string[]): string | undefined;
+    /**
+     * What a package bumped *only* because a dependency of it moved receives - there being nothing
+     * about the package itself for a larger bump to describe. `bumpNames`' first entry by default.
+     *
+     * Throws when this scheme declares no bumps at all: such a scheme cannot express a release, and
+     * finding out here beats silently leaving every rippled package unbumped. Override to nominate a
+     * different one - a four-part scheme may reserve `revision` for something else and want `build`.
+     */
+    smallestBump(): string;
+}
+/**
+ * Semver, exported as a class so a scheme that numbers in semver but decides one thing differently
+ * can subclass it instead of restating all of it.
+ */
+export declare class SemverScheme extends VersionScheme {
+    readonly name = "semver";
+    readonly bumpNames: readonly ["patch", "minor", "major"];
+    bumpFor(kind: ChangeKind): string;
+    isValid(version: string): boolean;
+    compare(a: string, b: string): number;
+    next(current: string, bump: string, options?: {
+        preid?: string;
+    }): string;
+    isPrerelease(version: string): boolean;
+}
+/**
+ * The default, and what every package gets unless something says otherwise - so nothing about
+ * rman's behaviour changes by this seam existing.
+ */
+export declare const semverScheme: VersionScheme;
+/**
+ * Refuses a group whose packages do not agree on a scheme.
+ *
+ * A group is one version line: its members are compared against each other and bumped together, so
+ * two schemes in one group makes both of those undefined. Better to say so than to compare a PEP
+ * 440 version against a semver one and act on whatever falls out.
+ *
+ * A free function rather than a member, unlike the three above: this is a question about a *set of
+ * packages*, and asking one of the disagreeing schemes to arbitrate would be asking a party to the
+ * dispute.
+ */
+export declare function assertOneScheme(schemes: {
+    packageName: string;
+    scheme: VersionScheme;
+}[], group: string): void;

package/core/version-scheme.js

@@ -0,0 +1,148 @@
+import semver from 'semver';
+/**
+ * How a package's versions are numbered: named, ordered, validated, and advanced.
+ *
+ * rman's release model was written in semver - tag patterns, changelog headings, release identity,
+ * "is this version on the registry yet", `"workspace:"` range rewriting all assume versions that
+ * can be ordered and incremented. This is the seam for an ecosystem that numbers differently (PEP
+ * 440, a date-based scheme, a build counter), and it is a *meaning* seam rather than a storage one:
+ * `ManifestProvider` answers "where is the version written", this answers "what does the next one
+ * look like".
+ *
+ * **`bumpNames` and `bumpFor` are the interesting part.** `fix:` -> patch, `feat:` -> minor,
+ * `feat!:` -> major is a sentence in *semver's* vocabulary from end to end, so a scheme that numbers
+ * differently does not need a different `inc()` - it needs its own set of bump names and its own
+ * answer to "what does a `feat:` mean for one of my version numbers". A CalVer scheme can
+ * legitimately answer all three with the same name and return today's date; that is the scheme's
+ * decision to make, which is why the seam is here and not around `semver.inc`.
+ *
+ * **An abstract class rather than an interface**, for the reason `VersionPlanService` is one:
+ * `highestVersion`, `highestBump` and `smallestBump` all *derive* from the members below them, so
+ * requiring every scheme to write them would be boilerplate and a second place for two answers to
+ * disagree - but each is a real decision a scheme may need to make differently (a repo maintaining
+ * parallel lines has its own idea of "highest"; a four-part scheme may want the ripple bump to be
+ * `build` rather than its actual smallest). Implemented here, overridable there. Subclass
+ * `SemverScheme` to keep semver's numbering and change only one of these.
+ */
+export class VersionScheme {
+    /**
+     * The highest of `versions` - a group's current version is the highest among its members, and a
+     * monorepo root's release identity the highest among the groups.
+     *
+     * Empty in, `undefined` out: a group with no versions has no highest one, and guessing `0.0.0`
+     * would put a real version line at risk. Override to answer differently - a repository
+     * maintaining parallel lines (a 1.x still receiving fixes beside a 2.x) may want the line being
+     * released rather than the numerically largest.
+     */
+    highestVersion(versions) {
+        if (!versions.length)
+            return undefined;
+        return versions.reduce((highest, v) => (this.compare(v, highest) > 0 ? v : highest));
+    }
+    /**
+     * The largest of `bumps` - what a group takes when its changed members ask for different sizes.
+     * Empty in, `undefined` out.
+     *
+     * A name this scheme does not declare ranks **below** every name it does, rather than throwing -
+     * a comparison helper is the wrong place to fail a release. It is a second line of defence, not
+     * the guard: `detectBump` already drops an unrecognized `Release-As:` footer before it gets here,
+     * because ranking such a word low is not the same as ignoring it (ranked low it still *replaces*
+     * what the commit's own subject said - measured, and it turned a `feat:` into a patch).
+     *
+     * Override for bumps that are not totally ordered, or to refuse an unknown name outright.
+     */
+    highestBump(bumps) {
+        if (!bumps.length)
+            return undefined;
+        return bumps.reduce((highest, b) => (this.bumpNames.indexOf(b) > this.bumpNames.indexOf(highest) ? b : highest));
+    }
+    /**
+     * What a package bumped *only* because a dependency of it moved receives - there being nothing
+     * about the package itself for a larger bump to describe. `bumpNames`' first entry by default.
+     *
+     * Throws when this scheme declares no bumps at all: such a scheme cannot express a release, and
+     * finding out here beats silently leaving every rippled package unbumped. Override to nominate a
+     * different one - a four-part scheme may reserve `revision` for something else and want `build`.
+     */
+    smallestBump() {
+        const smallest = this.bumpNames[0];
+        if (!smallest) {
+            throw new Error(`Version scheme "${this.name}" declares no "bumpNames", so no version can be bumped.`);
+        }
+        return smallest;
+    }
+}
+/**
+ * Semver, exported as a class so a scheme that numbers in semver but decides one thing differently
+ * can subclass it instead of restating all of it.
+ */
+export class SemverScheme extends VersionScheme {
+    name = 'semver';
+    bumpNames = ['patch', 'minor', 'major'];
+    bumpFor(kind) {
+        switch (kind) {
+            case 'breaking':
+                return 'major';
+            case 'feature':
+                return 'minor';
+            case 'fix':
+                return 'patch';
+        }
+    }
+    isValid(version) {
+        return !!semver.valid(version);
+    }
+    compare(a, b) {
+        return semver.compare(a, b);
+    }
+    next(current, bump, options) {
+        const releaseType = bump;
+        const preid = options?.preid;
+        if (!preid)
+            return semver.inc(current, releaseType) ?? current;
+        /**
+         * Already on a prerelease under **this same identifier**: just advance its counter
+         * (`1.2.3-beta.0` -> `1.2.3-beta.1`), rather than jumping to a new base version every run of
+         * the same beta cycle. Anything else - a plain release, or a prerelease under a *different*
+         * identifier (`beta` -> `rc`) - starts a fresh prerelease of `bump`'s own type.
+         *
+         * Comparing the identifier, not merely "is a prerelease": treating any prerelease as the same
+         * line makes switching `beta` to `rc` silently continue the beta counter.
+         */
+        const existing = semver.prerelease(current);
+        const sameLine = existing && String(existing[0]) === preid;
+        const preType = sameLine ? 'prerelease' : `pre${releaseType}`;
+        return semver.inc(current, preType, preid) ?? current;
+    }
+    isPrerelease(version) {
+        return !!semver.prerelease(version);
+    }
+}
+/**
+ * The default, and what every package gets unless something says otherwise - so nothing about
+ * rman's behaviour changes by this seam existing.
+ */
+export const semverScheme = new SemverScheme();
+/**
+ * Refuses a group whose packages do not agree on a scheme.
+ *
+ * A group is one version line: its members are compared against each other and bumped together, so
+ * two schemes in one group makes both of those undefined. Better to say so than to compare a PEP
+ * 440 version against a semver one and act on whatever falls out.
+ *
+ * A free function rather than a member, unlike the three above: this is a question about a *set of
+ * packages*, and asking one of the disagreeing schemes to arbitrate would be asking a party to the
+ * dispute.
+ */
+export function assertOneScheme(schemes, group) {
+    const first = schemes[0];
+    if (!first)
+        return;
+    const odd = schemes.find(s => s.scheme.name !== first.scheme.name);
+    if (!odd)
+        return;
+    throw new Error(`Group "${group}" mixes version schemes: "${first.packageName}" uses ${first.scheme.name} and ` +
+        `"${odd.packageName}" uses ${odd.scheme.name}.\n` +
+        `  A group is one version line - its packages are compared and bumped together, which two ` +
+        `schemes make meaningless. Put them in separate groups (.rmanrc "group").`);
+}

package/core/workspace.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How a repository is laid out, and who decides.
+ *
+ * A namespace for the same reason `Manifest` is one: it is what a plugin can *augment*
+ * (`declare module 'rman' { namespace Workspace { ... } }`), so whatever this seam grows later
+ * arrives as a member here rather than as another top-level export.
+ */
+export declare namespace Workspace {
+    /** What a repository looks like: where its root is, and which directories hold its packages. */
+    interface Layout {
+        /** Absolute path to the repository root. */
+        root: string;
+        /**
+         * Absolute paths to the package **directories**, outside the root. Empty for a repository that
+         * is itself the one package.
+         *
+         * Directories rather than `Package` objects, and not for want of trying: a provider runs before
+         * any package exists - `Repository.create` constructs them from these paths afterwards, through
+         * the *manifest* provider. A discovery provider returning packages would have to construct them
+         * itself, making discovery the owner of identity too.
+         *
+         * Unlike `Package.dependencies`, there is no identity question here: these are paths, and a
+         * path is unique by construction where a name is only unique if the ecosystem says so.
+         */
+        packageDirs: string[];
+    }
+    /**
+     * How a repository's packages are found.
+     *
+     * **The core has no provider**, and that is the point: "packages are the `workspaces` globs in
+     * the root `package.json`, and a package is a directory with a `package.json` in it" is true of
+     * npm and of nothing else. `rman-node` contributes that one; a plugin for another ecosystem
+     * contributes its own (a Cargo workspace, a `go.work`, a `pyproject.toml`).
+     *
+     * Returns `undefined` for "this is not a repository I recognize", so the next provider gets a
+     * turn and a repository nobody recognizes falls back to being a single package.
+     */
+    type Provider = (root: string) => Layout | undefined;
+    /**
+     * Registers a provider. Called by `loadPlugins` for each plugin's `workspace`, in `plugins`
+     * declaration order - so which provider answers 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;
+    /** The first provider that recognizes `root`, in declaration order. */
+    function resolve(root: string): Layout | undefined;
+    /**
+     * Where the repository starts, decided **without knowing anything about any ecosystem** - it has
+     * to be, because the plugins that do know are named in the config file this walk is looking for.
+     *
+     * Walking up from `from`, stopping after a directory holding `.git`, the root is:
+     *
+     * 1. the **outermost** directory in that chain holding an `.rmanrc*` - outermost, because a
+     *    *package* may have its own `.rmanrc` (that is a supported thing), and from inside such a
+     *    package the nearest one is the package's, not the repository's;
+     * 2. otherwise the `.git` directory itself, the ordinary meaning of "repository root";
+     * 3. otherwise `from`, which is all that is left to go on.
+     *
+     * **What "outermost" costs**, since the two cases genuinely conflict and only one can win: a
+     * self-contained project nested inside a larger git repository *and sharing its `.git`* resolves
+     * to the outer root, not to itself (measured). That is the same repository by any definition git
+     * recognizes, so it is the defensible answer - and a nested project with a `.git` of its own is
+     * found correctly, because the walk stops there before the outer `.rmanrc` is ever seen (also
+     * measured). A per-package `.rmanrc` is the common case and it is the one served.
+     */
+    function findRoot(from: string, deep?: number): string;
+}

package/core/workspace.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * How a repository is laid out, and who decides.
+ *
+ * A namespace for the same reason `Manifest` is one: it is what a plugin can *augment*
+ * (`declare module 'rman' { namespace Workspace { ... } }`), so whatever this seam grows later
+ * arrives as a member here rather than as another top-level export.
+ */
+export var Workspace;
+(function (Workspace) {
+    /**
+     * Registers a provider. Called by `loadPlugins` for each plugin's `workspace`, in `plugins`
+     * declaration order - so which provider answers is a function of the repository's own config.
+     */
+    function addProvider(provider) {
+        if (providers.includes(provider))
+            return;
+        providers.push(provider);
+    }
+    Workspace.addProvider = addProvider;
+    /** For tests, which would otherwise leak a provider into every later case in the process. */
+    function clearProviders() {
+        providers.length = 0;
+    }
+    Workspace.clearProviders = clearProviders;
+    /** The first provider that recognizes `root`, in declaration order. */
+    function resolve(root) {
+        for (const provider of providers) {
+            const layout = provider(root);
+            if (layout)
+                return layout;
+        }
+        return undefined;
+    }
+    Workspace.resolve = resolve;
+    /**
+     * Where the repository starts, decided **without knowing anything about any ecosystem** - it has
+     * to be, because the plugins that do know are named in the config file this walk is looking for.
+     *
+     * Walking up from `from`, stopping after a directory holding `.git`, the root is:
+     *
+     * 1. the **outermost** directory in that chain holding an `.rmanrc*` - outermost, because a
+     *    *package* may have its own `.rmanrc` (that is a supported thing), and from inside such a
+     *    package the nearest one is the package's, not the repository's;
+     * 2. otherwise the `.git` directory itself, the ordinary meaning of "repository root";
+     * 3. otherwise `from`, which is all that is left to go on.
+     *
+     * **What "outermost" costs**, since the two cases genuinely conflict and only one can win: a
+     * self-contained project nested inside a larger git repository *and sharing its `.git`* resolves
+     * to the outer root, not to itself (measured). That is the same repository by any definition git
+     * recognizes, so it is the defensible answer - and a nested project with a `.git` of its own is
+     * found correctly, because the walk stops there before the outer `.rmanrc` is ever seen (also
+     * measured). A per-package `.rmanrc` is the common case and it is the one served.
+     */
+    function findRoot(from, deep = 10) {
+        const chain = [];
+        let dir = path.resolve(from);
+        let remaining = deep;
+        while (remaining-- >= 0 && fs.existsSync(dir)) {
+            chain.push(dir);
+            if (fs.existsSync(path.join(dir, '.git')))
+                break;
+            const parent = path.resolve(dir, '..');
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        const withConfig = chain.filter(hasRmanConfig);
+        if (withConfig.length)
+            return withConfig[withConfig.length - 1];
+        const gitRoot = chain.find(d => fs.existsSync(path.join(d, '.git')));
+        return gitRoot ?? path.resolve(from);
+    }
+    Workspace.findRoot = findRoot;
+    /** Every file form a `.rmanrc` comes in - `package.json#rman` is deliberately *not* one of them
+     *  here: it would make the root question npm-shaped again. */
+    const CONFIG_FILES = ['.rmanrc', '.rmanrc.yml', '.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
+    function hasRmanConfig(dir) {
+        return CONFIG_FILES.some(name => fs.existsSync(path.join(dir, name)));
+    }
+    const providers = [];
+})(Workspace || (Workspace = {}));

package/index.d.ts

@@ -1,19 +1,66 @@
 /**
  * Programmatic API - the same logic the CLI commands run, importable directly without going
  * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
- * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
- * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
- * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
- * separate since they're genuinely independent capabilities, not just steps of one operation) -
- * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
- * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ * (e.g. `ChangelogService`, `ListService`, `RunService`, `VersionService`),
+ * re-exported here via `./services.js`. Purpose-specific functions, not one generic `run`/`get`
+ * per domain - CLI-only concerns (argv parsing, `--help` text, and all console/file presentation)
+ * stay in `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ *
+ * **This is also the plugin contract.** A plugin (`rman-node`, say) is an ordinary package that
+ * imports from here, so everything a command needs in order to live outside rman has to be
+ * exported - the progress panel, the package filter, the branch guard, the git helper. What is
+ * *not* exported is deliberately private: config resolution internals, the expression evaluator,
+ * the command registry.
  */
 export { defineConfig } from './core/config.js';
+export type { CommandContext, CustomCommand } from './core/custom-command.js';
+export { defineCommand } from './core/custom-command.js';
+/** The manifest seam: where a package's name and version are written, and how it is numbered.
+ *  The core has no provider - `package.json` is npm's answer, and lives in `rman-node`. */
+export type { ManifestProvider } from './core/manifest.js';
+/** Both the shape and the registry: `const m: Manifest` and `Manifest.read(dir)` - merged onto one
+ *  name so a plugin can augment it the way it augments `SystemInfo`. */
+export { Manifest } from './core/manifest.js';
 export { Package } from './core/package.js';
+export type { RmanPlugin } from './core/plugin.js';
+export { definePlugin } from './core/plugin.js';
 export { Repository } from './core/repository.js';
+export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/run-step.js';
+export type { ChangeKind } from './core/version-scheme.js';
+/** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`
+ *  are implemented from the members around them, so a scheme states only what it must and still
+ *  overrides any of the three. `SemverScheme` is exported to subclass rather than restate. */
+export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/version-scheme.js';
+/** The workspace seam: how a repository's packages are found. A plugin contributes a provider
+ *  (see `RmanPlugin.workspace`); the core has none, so `workspaces` is npm's idea and lives in
+ *  `rman-node`. */
+/** `Workspace.Layout`, `Workspace.Provider`, `Workspace.addProvider`, `Workspace.resolve`,
+ *  `Workspace.findRoot` - one namespace, so a plugin can augment it. */
+export { Workspace } from './core/workspace.js';
 export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
-export type { DetectChangeHashOptions } from './utils/change-hash.js';
-export { detectChangeHash } from './utils/change-hash.js';
+/** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
+ *  the wrong branch exactly as `publish` and `version` do. */
+export { applyBranchGuardOptions, assertAllowedBranch, type BranchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+/** Where a repository's locally installed binaries live - the core spells the PATH variable, a
+ *  plugin says which directories go on it (see `RmanPlugin.binPaths`). */
+export { BinPath } from './utils/bin-path.js';
+/** A shell command, with the repository's local binaries on PATH - for a command string an author
+ *  wrote. `runBin` is the one to reach for when the arguments are assembled in code. */
+export type { ExecOptions, ExecResult } from './utils/exec.js';
+export { exec } from './utils/exec.js';
+export { GitHelper } from './utils/git.js';
 export type { LogLevel } from './utils/logger.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
+/** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
+ *  way every built-in does rather than inventing its own flags. */
+export { applyPackageFilterOptions, applyRootOption, filterPackages, type PackageFilterOptions, readPackageFilterOptions, readRootOption, } from './utils/package-filter.js';
+/** The live panel `run`/`build`/`clean` print - a plugin's per-package command looks like the rest
+ *  of rman instead of like a script someone bolted on. */
+export { formatDuration, type ProgressItem, ProgressPanel, type ProgressStatus, type ProgressSummary, } from './utils/progress-panel.js';
+/** Version stamping helpers a `ManifestProvider.stampVersion` can delegate to - the quoted-constant
+ *  pattern most languages share, and the OCI Dockerfile label (which `version` stamps itself, since
+ *  the label's value is by specification the package's version). */
+export type { RunBinOptions, RunBinResult } from './utils/run-bin.js';
+export { runBin } from './utils/run-bin.js';
+export { OCI_VERSION_LABEL, stampVersionConstant, stampVersionLabel } from './utils/version-stamp.js';

package/index.js

@@ -1,17 +1,52 @@
 /**
  * Programmatic API - the same logic the CLI commands run, importable directly without going
  * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
- * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
- * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
- * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
- * separate since they're genuinely independent capabilities, not just steps of one operation) -
- * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
- * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ * (e.g. `ChangelogService`, `ListService`, `RunService`, `VersionService`),
+ * re-exported here via `./services.js`. Purpose-specific functions, not one generic `run`/`get`
+ * per domain - CLI-only concerns (argv parsing, `--help` text, and all console/file presentation)
+ * stay in `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ *
+ * **This is also the plugin contract.** A plugin (`rman-node`, say) is an ordinary package that
+ * imports from here, so everything a command needs in order to live outside rman has to be
+ * exported - the progress panel, the package filter, the branch guard, the git helper. What is
+ * *not* exported is deliberately private: config resolution internals, the expression evaluator,
+ * the command registry.
  */
 export { defineConfig } from './core/config.js';
+export { defineCommand } from './core/custom-command.js';
+/** Both the shape and the registry: `const m: Manifest` and `Manifest.read(dir)` - merged onto one
+ *  name so a plugin can augment it the way it augments `SystemInfo`. */
+export { Manifest } from './core/manifest.js';
 export { Package } from './core/package.js';
+export { definePlugin } from './core/plugin.js';
 export { Repository } from './core/repository.js';
+/** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`
+ *  are implemented from the members around them, so a scheme states only what it must and still
+ *  overrides any of the three. `SemverScheme` is exported to subclass rather than restate. */
+export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/version-scheme.js';
+/** The workspace seam: how a repository's packages are found. A plugin contributes a provider
+ *  (see `RmanPlugin.workspace`); the core has none, so `workspaces` is npm's idea and lives in
+ *  `rman-node`. */
+/** `Workspace.Layout`, `Workspace.Provider`, `Workspace.addProvider`, `Workspace.resolve`,
+ *  `Workspace.findRoot` - one namespace, so a plugin can augment it. */
+export { Workspace } from './core/workspace.js';
 export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
-export { detectChangeHash } from './utils/change-hash.js';
+// --- what a command needs to behave like a built-in one -----------------------------------------
+/** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
+ *  the wrong branch exactly as `publish` and `version` do. */
+export { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions, } from './utils/branch-guard.js';
+/** Where a repository's locally installed binaries live - the core spells the PATH variable, a
+ *  plugin says which directories go on it (see `RmanPlugin.binPaths`). */
+export { BinPath } from './utils/bin-path.js';
+export { exec } from './utils/exec.js';
+export { GitHelper } from './utils/git.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
+/** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
+ *  way every built-in does rather than inventing its own flags. */
+export { applyPackageFilterOptions, applyRootOption, filterPackages, readPackageFilterOptions, readRootOption, } from './utils/package-filter.js';
+/** The live panel `run`/`build`/`clean` print - a plugin's per-package command looks like the rest
+ *  of rman instead of like a script someone bolted on. */
+export { formatDuration, ProgressPanel, } from './utils/progress-panel.js';
+export { runBin } from './utils/run-bin.js';
+export { OCI_VERSION_LABEL, stampVersionConstant, stampVersionLabel } from './utils/version-stamp.js';