rman 1.0.12 → 1.2.1

package/services/changelog.service.d.ts

@@ -2,20 +2,15 @@ import type { Package } from '../core/package.js';
 import type { Repository } from '../core/repository.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 export declare namespace ChangelogService {
-    /** Injectable dependencies shared by `getEntries`/`generate` - currently just the npm registry lookup
-     *  `detectChangeHash` otherwise makes for itself; overridable so tests (and advanced callers)
-     *  aren't forced through a real network call. */
-    interface Deps {
-        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
-    }
     interface Options extends PackageFilterOptions {
         /** Generate the changelog since this commit/hash - applied the same way to every package.
-         *  Default (also `"npm"` explicitly): auto-detect it per package instead, from that package's
+         *  Default (also `"auto"` explicitly): auto-detect it per package instead, from that package's
          *  own most recent release tag first - the same lookup `VersionService`/`changed` use, so this
-         *  never disagrees with them - falling back to its currently-published npm version only when
-         *  it has no tag yet (see `detectChangeHash`); a package this can't be resolved for either way
-         *  (never tagged, unpublished, no network) has never been released at all, so its whole
-         *  history counts as unreleased - the same view `version` takes. */
+         *  never disagrees with them - falling back to whatever its own ecosystem's registry reports
+         *  only when it has no tag yet (`ManifestProvider.publishedVersion`, and only ever to guess a
+         *  tag name - see `detectChangeHash`); a package this can't be resolved for either way (never
+         *  tagged, unpublished, no plugin) has never been released at all, so its whole history counts
+         *  as unreleased - the same view `version` takes. */
         from?: string;
         /** Generate for the whole repository even when the current directory is inside a single
          *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
@@ -67,7 +62,7 @@ export declare namespace ChangelogService {
      * sake side effect (a "save this" request), not presentation, so it stays here rather than in
      * the CLI command - printing what happened is the command's job.
      */
-    function generateToFile(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    function generateToFile(repository: Repository, options?: Options): Promise<Entry[]>;
     /**
      * Computes a changelog entry per package (root included) from real commits only - either
      * everything since a given `--from <hash>` (applied the same way to every package), or, by
@@ -107,5 +102,5 @@ export declare namespace ChangelogService {
      * Run from inside a single package's own directory, it only covers that package unless
      * `options.root` says otherwise (see `Repository.currentPackage`).
      */
-    function getEntries(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    function getEntries(repository: Repository, options?: Options): Promise<Entry[]>;
 }

package/services/changelog.service.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { detectChangeHash, extractVersion, findLatestTag, tagPattern } from '../utils/change-hash.js';
-import { isReleaseCommit, parseConventionalCommit } from '../utils/conventional-commits.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
+import { ChangeHashService } from './change-hash.service.js';
+import { ConventionalCommitsService } from './conventional-commits.service.js';
 export var ChangelogService;
 (function (ChangelogService) {
     /**
@@ -13,8 +13,8 @@ export var ChangelogService;
      * sake side effect (a "save this" request), not presentation, so it stays here rather than in
      * the CLI command - printing what happened is the command's job.
      */
-    async function generateToFile(repository, options = {}, deps = {}) {
-        const entries = await getEntries(repository, options, deps);
+    async function generateToFile(repository, options = {}) {
+        const entries = await getEntries(repository, options);
         for (const entry of entries)
             prependToChangelogFile(entry.package, entry.filePath, entry.content);
         return entries;
@@ -59,7 +59,7 @@ export var ChangelogService;
      * Run from inside a single package's own directory, it only covers that package unless
      * `options.root` says otherwise (see `Repository.currentPackage`).
      */
-    async function getEntries(repository, options = {}, deps = {}) {
+    async function getEntries(repository, options = {}) {
         const cwdScope = options.root ? undefined : repository.currentPackage;
         const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
         const targets = (cwdScope ? [cwdScope] : filterPackages([repository.rootPackage, ...packages], options)).filter(pkg => options.includeSkipped || !pkg.config.publish?.skip);
@@ -67,7 +67,7 @@ export var ChangelogService;
         const commitMessage = repository.rootPackage.config?.version?.commitMessage;
         // dropped up front, not just while grouping - a package whose only commits are release markers
         // should get no entry at all, rather than a heading with nothing real underneath it.
-        const dropVersionBumps = (commits) => commits.filter(c => !isReleaseCommit(c.subject, commitMessage));
+        const dropVersionBumps = (commits) => commits.filter(c => !ConventionalCommitsService.isReleaseCommit(c.subject, commitMessage));
         // Several packages often resolve to the identical hash (an explicit --from <hash> applies to
         // all of them the same way; under fixed versioning, npm auto-detection usually does too) - so
         // the git fetch for a given hash is cached, run once no matter how many packages share it.
@@ -86,9 +86,8 @@ export var ChangelogService;
         };
         const commitsByTarget = await Promise.all(targets.map(async (pkg) => {
             const catchUpFile = path.join(pkg.dirname, resolveFilePath(pkg, options.filePath));
-            const from = await detectChangeHash(git, pkg, {
+            const from = await ChangeHashService.detect(git, pkg, {
                 from: options.from,
-                npmViewVersion: deps.npmViewVersion,
                 catchUpFile: fs.existsSync(catchUpFile) ? catchUpFile : undefined,
             });
             return listCommitsCached(from);
@@ -132,7 +131,7 @@ function ignoreTypesConfig(pkg) {
 function groupCommits(subjects, ignoreTypes = new Set()) {
     const grouped = { features: [], fixes: [], other: [] };
     for (const subject of subjects) {
-        const parsed = parseConventionalCommit(subject);
+        const parsed = ConventionalCommitsService.parseSubject(subject);
         if (!parsed) {
             grouped.other.push(subject);
             continue;
@@ -198,8 +197,10 @@ function resolveFilePath(pkg, optionsFilePath) {
  * if no matching tag exists at all (never tagged, or a fresh package) - see `findLatestTag`.
  */
 async function resolveVersion(git, pkg) {
-    const tag = await findLatestTag(git, pkg);
-    return tag ? extractVersion(tag, tagPattern(pkg).replace('{name}', pkg.name)) : pkg.version || '';
+    const tag = await ChangeHashService.findLatestTag(git, pkg);
+    return tag
+        ? ChangeHashService.extractVersion(tag, ChangeHashService.tagPattern(pkg).replace('{name}', pkg.name))
+        : pkg.version || '';
 }
 /** The most specific package whose directory contains `file` - the repository root itself as the
  *  fallback for anything outside every package (e.g. root-level config files). Mirrors

package/services/conventional-commits.service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Conventional Commits, as rman reads them: the subject-line shape, the breaking-change markers,
+ * the `Release-As:` escape hatch, and the counter-question of whether a commit is a *release
+ * marker* rather than a change at all.
+ *
+ * A namespace for the reason `ChangeHashService` is one - one subject, several operations, named for
+ * what they do rather than repeating the subject (`parseSubject`, not `parseConventionalCommit`).
+ *
+ * **Nothing here knows about versions.** A commit says what happened; `VersionScheme.bumpFor` turns
+ * that into how a number moves. `parseReleaseAs` is the one place the two meet, and it deliberately
+ * returns the word as written rather than judging it - see its own doc.
+ */
+export declare namespace ConventionalCommitsService {
+    /**
+     * `type(scope): description`, optionally with a `!` breaking-change marker - Conventional
+     * Commits' subject-line shape. Anything that doesn't match falls into "Other Changes" as-is (for
+     * changelog entries) or defaults to a patch-level change (for version bump severity) - see
+     * `parseSubject`.
+     */
+    const SUBJECT_PATTERN: RegExp;
+    /** A bare version-bump commit (`"6.0.1"`, `"v2.3.0-beta.1"`, ...) - many release tools commit the
+     *  version bump itself with just the new version number as the message. That's a release marker,
+     *  not a real change worth describing (or worth bumping a version over on its own), so it's
+     *  dropped everywhere a real change is being looked for. */
+    const VERSION_BUMP_PATTERN: RegExp;
+    /**
+     * Whether `subject` is a release marker rather than a real change - dropped everywhere real
+     * changes are looked for (changelog entries, and what counts as "changed" for a version bump).
+     *
+     * Covers the bare-version form other tools use (`VERSION_BUMP_PATTERN`) plus every message shape
+     * `version` itself writes: its commit message (`commitMessageTemplate`, or the built-in
+     * `"chore(release): v{version}"` when a repo doesn't override it), the multi-version form that
+     * template falls back to when one commit spans several versions (`chore(release): a@1.2.0,
+     * b@1.3.0`), and the monorepo root's own version-sync commit. Without this, rman's own release
+     * commits show up in the changelogs it generates - visible whenever the boundary reaches back past
+     * a previous release (see `ChangeHashService.detect`'s `catchUpFile`).
+     */
+    function isReleaseCommit(subject: string, commitMessageTemplate?: string): boolean;
+    interface ParsedSubject {
+        type: string;
+        scope?: string;
+        /** A `!` right before the `:` (e.g. `feat!:`) - Conventional Commits' inline breaking-change
+         *  marker. Doesn't cover a `BREAKING CHANGE:` footer, since only the subject line is available. */
+        breaking: boolean;
+        description: string;
+    }
+    /** Parses a commit subject as Conventional Commits, or `undefined` if it doesn't match at all
+     *  (a non-conventional message - still a real change, just with no `type` to key off of). */
+    function parseSubject(subject: string): ParsedSubject | undefined;
+    /** Whether a commit `body` carries a Conventional Commits `BREAKING CHANGE:` (or
+     *  `BREAKING-CHANGE:`) footer - the other, footer-based way to mark a breaking change, alongside
+     *  the inline `!` the subject line alone can carry (see `parseSubject`, whose own
+     *  `breaking` only ever reflects that marker, never a footer, since it only sees the subject). */
+    function hasBreakingChangeFooter(body: string): boolean;
+    /**
+     * A `Release-As: <bump>` footer in a commit `body` - lets that one commit's own contribution to the
+     * detected bump be overridden by hand, regardless of what its subject line (or a `BREAKING CHANGE:`
+     * footer) would otherwise imply. The motivating case: a `feat:` commit that needs to ship right now
+     * as a patch, without waiting for the rest of a minor's worth of work to land - `Release-As: patch`
+     * on just that commit ships it alone, at patch size, while a later genuine `feat:` (with no
+     * override) still correctly triggers a minor of its own. Case-insensitive; the last match wins if a
+     * body somehow has more than one, matching how multiple git trailers of the same key are
+     * conventionally read (later overrides earlier).
+     *
+     * **Returns the word as written, and does not judge it** - which bumps exist is the package's
+     * `VersionScheme.bumpNames`, and this module is about commit messages. The caller checks it against
+     * those and treats anything else as *no override at all*, falling back to what the commit's own
+     * subject said (see `VersionPlanService.detectBump`). That keeps two cases harmless: a typo, and release-please's own
+     * `Release-As: 1.2.3`, which uses the same trailer for a literal version and appears in real
+     * repositories rman gets adopted onto.
+     */
+    function parseReleaseAs(body: string): string | undefined;
+}

package/services/conventional-commits.service.js

@@ -0,0 +1,116 @@
+/**
+ * Conventional Commits, as rman reads them: the subject-line shape, the breaking-change markers,
+ * the `Release-As:` escape hatch, and the counter-question of whether a commit is a *release
+ * marker* rather than a change at all.
+ *
+ * A namespace for the reason `ChangeHashService` is one - one subject, several operations, named for
+ * what they do rather than repeating the subject (`parseSubject`, not `parseConventionalCommit`).
+ *
+ * **Nothing here knows about versions.** A commit says what happened; `VersionScheme.bumpFor` turns
+ * that into how a number moves. `parseReleaseAs` is the one place the two meet, and it deliberately
+ * returns the word as written rather than judging it - see its own doc.
+ */
+export var ConventionalCommitsService;
+(function (ConventionalCommitsService) {
+    /**
+     * `type(scope): description`, optionally with a `!` breaking-change marker - Conventional
+     * Commits' subject-line shape. Anything that doesn't match falls into "Other Changes" as-is (for
+     * changelog entries) or defaults to a patch-level change (for version bump severity) - see
+     * `parseSubject`.
+     */
+    ConventionalCommitsService.SUBJECT_PATTERN = /^(\w+)(\(([^)]+)\))?(!)?:\s*(.+)$/;
+    /** A bare version-bump commit (`"6.0.1"`, `"v2.3.0-beta.1"`, ...) - many release tools commit the
+     *  version bump itself with just the new version number as the message. That's a release marker,
+     *  not a real change worth describing (or worth bumping a version over on its own), so it's
+     *  dropped everywhere a real change is being looked for. */
+    ConventionalCommitsService.VERSION_BUMP_PATTERN = /^v?\d+\.\d+\.\d+(?:[-+][\w.]+)?$/;
+    /**
+     * Whether `subject` is a release marker rather than a real change - dropped everywhere real
+     * changes are looked for (changelog entries, and what counts as "changed" for a version bump).
+     *
+     * Covers the bare-version form other tools use (`VERSION_BUMP_PATTERN`) plus every message shape
+     * `version` itself writes: its commit message (`commitMessageTemplate`, or the built-in
+     * `"chore(release): v{version}"` when a repo doesn't override it), the multi-version form that
+     * template falls back to when one commit spans several versions (`chore(release): a@1.2.0,
+     * b@1.3.0`), and the monorepo root's own version-sync commit. Without this, rman's own release
+     * commits show up in the changelogs it generates - visible whenever the boundary reaches back past
+     * a previous release (see `ChangeHashService.detect`'s `catchUpFile`).
+     */
+    function isReleaseCommit(subject, commitMessageTemplate) {
+        if (ConventionalCommitsService.VERSION_BUMP_PATTERN.test(subject))
+            return true;
+        if (ROOT_SYNC_PATTERN.test(subject))
+            return true;
+        if (MULTI_VERSION_RELEASE_PATTERN.test(subject))
+            return true;
+        // The built-in message is checked even when a repo overrides it: the override only applies to
+        // commits spanning a single version (see `buildCommitMessage`), and a repo that adopted one later
+        // still has older releases committed under the default.
+        if (templatePattern(DEFAULT_COMMIT_MESSAGE).test(subject))
+            return true;
+        return !!commitMessageTemplate && templatePattern(commitMessageTemplate).test(subject);
+    }
+    ConventionalCommitsService.isReleaseCommit = isReleaseCommit;
+    /** Parses a commit subject as Conventional Commits, or `undefined` if it doesn't match at all
+     *  (a non-conventional message - still a real change, just with no `type` to key off of). */
+    function parseSubject(subject) {
+        const m = ConventionalCommitsService.SUBJECT_PATTERN.exec(subject);
+        if (!m)
+            return undefined;
+        const [, type, , scope, breakingMark, description] = m;
+        return { type: type.toLowerCase(), scope, breaking: !!breakingMark, description };
+    }
+    ConventionalCommitsService.parseSubject = parseSubject;
+    /** Whether a commit `body` carries a Conventional Commits `BREAKING CHANGE:` (or
+     *  `BREAKING-CHANGE:`) footer - the other, footer-based way to mark a breaking change, alongside
+     *  the inline `!` the subject line alone can carry (see `parseSubject`, whose own
+     *  `breaking` only ever reflects that marker, never a footer, since it only sees the subject). */
+    function hasBreakingChangeFooter(body) {
+        return /^BREAKING[ -]CHANGE:/im.test(body);
+    }
+    ConventionalCommitsService.hasBreakingChangeFooter = hasBreakingChangeFooter;
+    /**
+     * A `Release-As: <bump>` footer in a commit `body` - lets that one commit's own contribution to the
+     * detected bump be overridden by hand, regardless of what its subject line (or a `BREAKING CHANGE:`
+     * footer) would otherwise imply. The motivating case: a `feat:` commit that needs to ship right now
+     * as a patch, without waiting for the rest of a minor's worth of work to land - `Release-As: patch`
+     * on just that commit ships it alone, at patch size, while a later genuine `feat:` (with no
+     * override) still correctly triggers a minor of its own. Case-insensitive; the last match wins if a
+     * body somehow has more than one, matching how multiple git trailers of the same key are
+     * conventionally read (later overrides earlier).
+     *
+     * **Returns the word as written, and does not judge it** - which bumps exist is the package's
+     * `VersionScheme.bumpNames`, and this module is about commit messages. The caller checks it against
+     * those and treats anything else as *no override at all*, falling back to what the commit's own
+     * subject said (see `VersionPlanService.detectBump`). That keeps two cases harmless: a typo, and release-please's own
+     * `Release-As: 1.2.3`, which uses the same trailer for a literal version and appears in real
+     * repositories rman gets adopted onto.
+     */
+    function parseReleaseAs(body) {
+        const matches = [...body.matchAll(/^release-as:\s*([\w.+-]+)\s*$/gim)];
+        const last = matches.at(-1);
+        return last ? last[1].toLowerCase() : undefined;
+    }
+    ConventionalCommitsService.parseReleaseAs = parseReleaseAs;
+})(ConventionalCommitsService || (ConventionalCommitsService = {}));
+/** A semver version, as it appears inside a commit subject - the `\d+\.\d+\.\d+` core of
+ *  `VERSION_BUMP_PATTERN`, reusable inside the larger patterns below. */
+const SEMVER_SOURCE = String.raw `\d+\.\d+\.\d+(?:[-+][\w.]+)?`;
+/** Mirrors `VersionService`'s own default `version.commitMessage` - kept in sync by
+ *  `version.command.ts`'s documented default, not imported, to keep this module dependency-free. */
+const DEFAULT_COMMIT_MESSAGE = 'chore(release): v{version}';
+/** `VersionService.applyPlan`'s trailing commit for a monorepo root's informational version. */
+const ROOT_SYNC_PATTERN = new RegExp(String.raw `^chore: sync root version to ${SEMVER_SOURCE}$`);
+/** What the commit-message template falls back to when one commit covers several versions at once
+ *  (a cross-group ripple) - `{version}` has nothing single to substitute, so each bumped package is
+ *  listed by name instead. */
+const MULTI_VERSION_RELEASE_PATTERN = new RegExp(String.raw `^chore\(release\): \S+@${SEMVER_SOURCE}(?:, \S+@${SEMVER_SOURCE})*$`);
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Turns a `version.commitMessage` template into a matcher for the commits it produces: every
+ *  literal part escaped, each `{version}` placeholder standing in for any semver. */
+function templatePattern(template) {
+    const source = template.split('{version}').map(escapeRegExp).join(SEMVER_SOURCE);
+    return new RegExp(`^${source}$`);
+}

package/services/docker-publish.service.js

@@ -185,7 +185,7 @@ async function updateDescription(entry) {
     const res = await fetch(`https://hub.docker.com/v2/repositories/${namespace}/${imageName}/`, {
         method: 'PATCH',
         headers: { Authorization: `JWT ${token}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ description: pkg.json.description, full_description: readme }),
+        body: JSON.stringify({ description: pkg.manifest.raw.description, full_description: readme }),
     });
     if (!res.ok)
         throw new Error(`DockerHub description update failed: ${res.status}`);

package/services/exec.service.js

@@ -47,7 +47,7 @@ export var ExecService;
         const names = new Set(packages.map(p => p.name));
         const children = packages.map(pkg => {
             const ctx = panel.addItem(pkg.name);
-            const dependencies = topo ? pkg.dependencies.filter(d => names.has(d)) : [];
+            const dependencies = topo ? pkg.dependencies.filter(d => names.has(d.name)).map(d => d.name) : [];
             return new Task(() => execForPackage(ctx, panel.enabled, pkg.dirname, command, logger, bail ? () => rootTask?.abort() : () => { }), { name: pkg.name, dependencies });
         });
         panel.start();

package/services/github-release.service.d.ts

@@ -1,5 +1,5 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.js';
+import { Package } from '../core/package.js';
+import { Repository } from '../core/repository.js';
 export declare namespace GithubReleaseService {
     /** Injectable "does this release already exist" check - mainly for tests, so they don't depend
      *  on network access or a real GitHub token. Same shape as `DockerPublishService.Deps`' own

package/services/github-release.service.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import fastGlob from 'fast-glob';
-import semver from 'semver';
-import { expandTag, tagPattern } from '../utils/change-hash.js';
+import { Package } from '../core/package.js';
+import { Repository } from '../core/repository.js';
 import { GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion, releaseTagPattern } from '../utils/release-version.js';
+import { ChangeHashService } from './change-hash.service.js';
 import { ChangelogService } from './changelog.service.js';
 export var GithubReleaseService;
 (function (GithubReleaseService) {
@@ -129,18 +130,22 @@ const GITHUB_UPLOADS = 'https://uploads.github.com';
  *  so the release needs a name of its own (`release-*`); a plain one means every package shares it,
  *  and that shared version's tag already *is* the release. */
 function releaseTagFor(root) {
-    return isCalendarVersion(root.version) ? expandReleaseTag(root, root.version) : expandTag(root, root.version);
+    return isCalendarVersion(root.version)
+        ? expandReleaseTag(root, root.version)
+        : ChangeHashService.expandTag(root, root.version);
 }
 /** The glob matching the tags `releaseTagFor` produces - for stepping back to the previous one. */
 function releaseTagGlob(root) {
-    const pattern = isCalendarVersion(root.version) ? releaseTagPattern(root) : tagPattern(root);
+    const pattern = isCalendarVersion(root.version) ? releaseTagPattern(root) : ChangeHashService.tagPattern(root);
     return pattern.replace('{name}', root.name);
 }
 function resolvePrerelease(root, version) {
     const configured = root.config?.githubRelease?.prerelease;
     // A calendar version's time part is a semver prerelease identifier by construction - it says
     // nothing about the release being a preview, so it must not be read as one.
-    return configured ?? (!isCalendarVersion(version) && !!semver.prerelease(version));
+    /** The root's own scheme decides what a preview looks like - `semver.prerelease` was that
+     *  question with semver's answer baked in. */
+    return configured ?? (!isCalendarVersion(version) && root.versionScheme.isPrerelease(version));
 }
 /** `owner/repo` out of either remote URL form git hands back - `git@github.com:owner/repo.git`
  *  (SSH) or `https://github.com/owner/repo.git` (HTTPS, credentials and all). `undefined` for

package/services/list.service.js

@@ -7,7 +7,10 @@ export var ListService;
      *  status relative to upstream. Pure data - no console output; `rman list`'s own command
      *  decides how to present it (table, JSON, parseable, names only, or a dependency graph). */
     async function getPackages(repository, options = {}) {
-        const packages = filterPackages(repository.getPackages({ toposort: options.toposort }), options);
+        /** `false`: `list` is the inventory, so a package its own `.rmanrc "skip"` excludes is still
+         *  *in* the repository and still listed - hiding it would answer a different question. Every
+         *  other caller honours it, being a command that acts rather than reports. */
+        const packages = filterPackages(repository.getPackages({ toposort: options.toposort }), options, false);
         const status = await repository.listStatus({ hash: options.changedSince });
         let items = packages.map(p => {
             const target = p.config.publish?.target;
@@ -18,7 +21,7 @@ export var ListService;
                 location: path.relative(repository.dirname, p.dirname) || '.',
                 private: p.isPrivate,
                 status: status[p.name],
-                dependencies: [...p.dependencies],
+                dependencies: p.dependencies.map(d => d.name),
                 publishTargets: [...publishTargets],
                 docker: publishTargets.includes('docker') ? p.config.publish?.docker : undefined,
             };

package/services/run.service.d.ts

@@ -1,9 +1,10 @@
 import type { Package } from '../core/package.js';
 import type { Repository } from '../core/repository.js';
+import type { RunStepContext, RunStepFn, RunStepValue } from '../core/run-step.js';
 import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 export declare namespace RunService {
-    interface Options extends PackageFilterOptions {
+    export interface Options extends PackageFilterOptions {
         /** Max packages built at once: `true`/omitted = CPU count, a number = that many, `false` = serial (1). */
         parallel?: boolean | number;
         /** Respect the package dependency graph: a package waits for its dependencies and is skipped
@@ -52,7 +53,111 @@ export declare namespace RunService {
      *   run:
      *     test: mocha          # same as   test: { exec: mocha }
      */
-    function getConfig(pkg: Package, script: string): Record<string, unknown>;
+    /**
+     * One step of a script - a shell command, or a function ([`RunStepFn`](../core/run-step.ts)).
+     *
+     * A union rather than one shape with two optional fields, so every consumer is made to say which
+     * it is handling: the executor that forgets is the one that silently runs nothing, which is
+     * exactly the bug this type replaces (a function in `after` used to be dropped by
+     * `normalizeScriptValue` and reported as a step that succeeded).
+     */
+    export type ScriptStep = CommandStep | FunctionStep;
+    interface StepBase {
+        /** The slot it came from - `before`/`exec`/`after`, which is what the log line shows. */
+        name: string;
+        /** What the progress panel and the per-step log print: the command itself, or the function's
+         *  own name. */
+        label: string;
+    }
+    export interface CommandStep extends StepBase {
+        command: string;
+        run?: undefined;
+    }
+    export interface FunctionStep extends StepBase {
+        run: RunStepFn;
+        command?: undefined;
+    }
+    /** The three slots a script is made of, each one step or several run in sequence. The same three
+     *  names a `.rmanrc "run.<script>"` block uses, because they are the same three things. */
+    export interface ScriptSlots {
+        before?: RunStepValue[];
+        exec?: RunStepValue[];
+        after?: RunStepValue[];
+    }
+    /**
+     * Where a package's steps can come from besides its `.rmanrc`.
+     *
+     * The core knows one source: the config. **`package.json#scripts` is not a source the core has**,
+     * because "a script lives in package.json" is true of a Node repository and of nothing else -
+     * `rman-node` contributes that one (with npm's `pre<script>`/`post<script>` convention and its
+     * `&&` splitting), and a plugin for another ecosystem would contribute its own.
+     *
+     * Returns `undefined` for "this package declares nothing", not empty slots - the difference
+     * decides whether the config's value applies.
+     */
+    export type StepSource = (pkg: Package, script: string) => ScriptSlots | undefined;
+    /**
+     * Registers a source. Called by `loadPlugins` for each plugin's `runSteps`, in `plugins`
+     * declaration order - never as an import side effect, so what is registered is exactly what the
+     * repository's `.rmanrc` asked for.
+     */
+    export function addStepSource(source: StepSource): void;
+    /** For tests, which would otherwise leak a source into every later case in the process. */
+    export function clearStepSources(): void;
+    /**
+     * What the *package itself* declares for the lifecycle `script`, from the contributed sources
+     * alone - no `.rmanrc` involved. `undefined` when it declares nothing.
+     *
+     * Exported because `run` is not the only lifecycle rman wraps: `version` runs hooks around the
+     * version write, and npm spells those `preversion`/`version`/`postversion` in `package.json` -
+     * which is the same `pre<script>`/`<script>`/`post<script>` shape a step source already answers.
+     * So `VersionService` asks here for `'version'` instead of reading `manifest.raw.scripts` itself,
+     * and npm's version lifecycle keeps working with no second seam and no extra line in any plugin.
+     * A plugin for another ecosystem gets its own lifecycle hooks the moment it contributes steps.
+     */
+    export function contributedSlots(pkg: Package, script: string): ScriptSlots | undefined;
+    /**
+     * Runs one slot of a lifecycle belonging to some operation other than `run` itself - `version`'s
+     * hooks around the version write are the only one so far.
+     *
+     * **Here rather than in `VersionService`, because the rule it applies is this service's**: the
+     * package's own declaration for `script` wins over the caller's `fallback`, slot by slot, exactly
+     * as `getScriptSteps` decides it for `run`. Kept in two places that rule would drift, and one of
+     * the copies would sit in the file that writes versions - which now runs no command of its own at
+     * all.
+     *
+     * `fallback` is the caller's own configured step(s), **already evaluated**: `version`'s three
+     * paths are in `DEFERRED_PATHS` precisely because only the caller can bind
+     * `${{ pkg.targetVersion }}`, so interpolating here would either be too early or need a scope this
+     * service has no business holding.
+     *
+     * **A list, not one joined string.** `VersionService` used to `join(' && ')` an array into a
+     * single shell line, which a function step cannot be part of - and which quietly changed the
+     * semantics of the shell case too, since `cd x && y` in one process is not the same as two.
+     */
+    export function runLifecycleSlot(pkg: Package, script: string, slot: keyof ScriptSlots, fallback?: RunStepValue[]): Promise<void>;
+    export function getConfig(pkg: Package, script: string): Record<string, unknown>;
+    /**
+     * The context a function step or `if` is handed - see [`RunStepContext`](../core/run-step.ts).
+     *
+     * `runBin` and `logger` are bound to *this run* rather than left to be imported, which is the
+     * whole reason they are handed over: an imported `runBin` knows neither the cwd nor the resolved
+     * log level.
+     */
+    /**
+     * A `run.<script>.before`/`.exec`/`.after` (or `version.<slot>`) value: one step, or several to
+     * run in sequence. A shell command or a function, and a list may mix them.
+     *
+     * **Anything else throws, naming the path.** It used to `return []`, which meant a value rman did
+     * not recognize was dropped with no trace: writing a function here - the obvious guess, and now
+     * the supported form - produced `1 succeeded, 0 failed` with the step never run (measured). A
+     * configuration mistake has to be loud; silence here reads as success.
+     *
+     * Exported, and the only implementation: `VersionService` used to carry a second one that behaved
+     * differently, which is how `version.<slot>` came to join its array with `' && '`.
+     */
+    export function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
+    export function createStepContext(pkg: Package, cwd: string): RunStepContext;
     /**
      * `.rmanrc` conditional execution, GitHub Actions-`if`-flavored but a small closed grammar
      * instead of a full expression language (less to get wrong, still covers what's asked for) -
@@ -66,7 +171,7 @@ export declare namespace RunService {
      *       if: changed = {CHANGE_HASH}                     # {NAME} -> process.env.NAME first
      *       if: (changed or dirty) and not committed
      */
-    type IfNode = {
+    export type IfNode = {
         kind: 'atom';
         name: string;
         value?: string;
@@ -84,13 +189,14 @@ export declare namespace RunService {
     };
     /** Recursive-descent parser over `tokenizeIf`'s output: expr := or ; or := and ('or' and)* ;
      *  and := unary ('and' unary)* ; unary := 'not' unary | GROUP | NAME ['=' VALUE] */
-    function parseIfExpr(raw: unknown): IfNode | undefined;
+    export function parseIfExpr(raw: unknown): IfNode | undefined;
     /** Evaluates a parsed `if` expression for one package. `statusCache` avoids repeat `git` calls
      *  for the same reference hash across packages/scripts in a single run. */
-    function evaluateIf(repository: Repository, pkg: Package, node: IfNode, statusCache: Map<string, Record<string, Repository.PackageStatus>>): Promise<boolean>;
-    function runScript(repository: Repository, script: string, options?: Options & {
+    export function evaluateIf(repository: Repository, pkg: Package, node: IfNode, statusCache: Map<string, Record<string, Repository.PackageStatus>>): Promise<boolean>;
+    export function runScript(repository: Repository, script: string, options?: Options & {
         commandName?: string;
     }): Promise<void>;
+    export {};
 }
 /** Resolution order: explicit CLI flag > the package's resolved `.rmanrc` > `fallback`. */
 export declare function resolveBool(cliValue: boolean | undefined, pkg: Package, script: string, key: string, fallback: boolean): boolean;