rman 1.1.1 → 1.2.2

package/core/repository.d.ts

@@ -24,6 +24,18 @@ export declare class Repository extends Package {
      * An internal cache has no business being walked anyway.
      */
     private _repoScope?;
+    /** Cached `${{ git.* }}` facts - see `_gitScope`. Non-enumerable for the same reason as above,
+     *  and because reading it is a subprocess: a deep walk of a package must not spawn one. */
+    private _git?;
+    /**
+     * Files `${{ read(...) }}` has parsed, shared by every package's scope and keyed by the identity
+     * of the bytes - see `readStructuredFile`.
+     *
+     * **On the repository rather than per scope, and that is the whole point of it**: `configScope`
+     * is built once per package, so a cache living there would re-read a repository-level file once
+     * for every package that mentions it.
+     */
+    private readonly _readCache;
     protected constructor(dirname: string, monorepo: boolean, packages: Package[], 
     /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
      *  resolved repository root, possibly several levels up), this is where the user's shell
@@ -64,6 +76,8 @@ export declare class Repository extends Package {
     configScope(pkg: Package, options?: {
         targetVersion?: string;
     }): ConfigScope;
+    /** `${{ git.* }}`, read at most once per repository per process. */
+    protected _gitScope(): GitScope;
     /**
      * Resolves the effective rman config for the repository root and every package, cascading
      * root -> intermediate directories -> package directory, so a `.rmanrc` placed anywhere along
@@ -104,7 +118,7 @@ export declare class Repository extends Package {
      */
     protected _resolveDeclaredPackage(entry: string): Package | undefined;
     protected _updateDependencies(): void;
-    /** `git` facts for a `${{ repository.git.* }}` expression. Synchronous on purpose: it backs a lazy
+    /** `git` facts for a `${{ git.* }}` expression. Synchronous on purpose: it backs a lazy
      *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
      *  error, just a repository without one. */
     protected _readGitScope(dirname: string): GitScope;

package/core/repository.js

@@ -2,7 +2,7 @@ import { execFileSync } from 'node:child_process';
 import path from 'path';
 import semver from 'semver';
 import { GitHelper } from '../utils/git.js';
-import { createFileScope, DEFERRED_PATHS, interpolateConfig, readDirConfig, resolveConfig, } from './config.js';
+import { createFileScope, createReadScope, DEFERRED_PATHS, interpolateConfig, readDirConfig, resolveConfig, } from './config.js';
 import { Manifest } from './manifest.js';
 import { Package } from './package.js';
 import { loadPlugins } from './plugin.js';
@@ -27,6 +27,18 @@ export class Repository extends Package {
      * An internal cache has no business being walked anyway.
      */
     _repoScope;
+    /** Cached `${{ git.* }}` facts - see `_gitScope`. Non-enumerable for the same reason as above,
+     *  and because reading it is a subprocess: a deep walk of a package must not spawn one. */
+    _git;
+    /**
+     * Files `${{ read(...) }}` has parsed, shared by every package's scope and keyed by the identity
+     * of the bytes - see `readStructuredFile`.
+     *
+     * **On the repository rather than per scope, and that is the whole point of it**: `configScope`
+     * is built once per package, so a cache living there would re-read a repository-level file once
+     * for every package that mentions it.
+     */
+    _readCache = new Map();
     constructor(dirname, monorepo, packages, 
     /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
      *  resolved repository root, possibly several levels up), this is where the user's shell
@@ -113,17 +125,43 @@ export class Repository extends Package {
      * seeing a value that means nothing to them.
      */
     configScope(pkg, options) {
+        const _this = this;
         return {
             pkg: this._packageScope(pkg, options?.targetVersion),
             repository: this._repositoryScope(),
             /** `pkg.dirname`, not the repository root: a `"[*]"` block asking whether
              *  `tsconfig-build.json` exists has to be answered per package. */
             file: createFileScope(pkg.dirname),
+            /** Same base directory as `file`, so one `"[*]"` declaration reads each package's own copy -
+             *  and the cache is the repository's, so a file they *share* is parsed once. */
+            read: createReadScope(pkg.dirname, this._readCache),
             env: { ...process.env },
             semver,
             path,
+            /**
+             * A getter, and cached on the **repository** rather than in this closure: `configScope` is
+             * called once per package, so a per-scope cache would still shell out once per package in a
+             * monorepo that mentions git at all.
+             *
+             * Enumerable, unlike `pkg.targetVersion` - it has a real answer everywhere, so nothing needs
+             * hiding. What keeps it lazy is `interpolateConfig` building its context from property
+             * descriptors instead of spreading; see the note there.
+             */
+            get git() {
+                return _this._gitScope();
+            },
         };
     }
+    /** `${{ git.* }}`, read at most once per repository per process. */
+    _gitScope() {
+        if (this._git)
+            return this._git;
+        const built = this._readGitScope(this.dirname);
+        /** Defined rather than assigned, so the cache stays out of every enumeration of the repository
+         *  - the same reason `_repoScope` is defined this way. */
+        Object.defineProperty(this, '_git', { value: built, enumerable: false, writable: true });
+        return built;
+    }
     /**
      * Resolves the effective rman config for the repository root and every package, cascading
      * root -> intermediate directories -> package directory, so a `.rmanrc` placed anywhere along
@@ -239,17 +277,11 @@ export class Repository extends Package {
         if (this._repoScope)
             return this._repoScope;
         const packageScopes = this.packages.map(p => this._packageScope(p));
-        const repoDir = this.dirname;
-        let gitScope;
-        const _this = this;
         const built = {
             ...this._packageScope(this.rootPackage),
             monorepo: this.monorepo,
             packages: packageScopes,
             package: (name) => packageScopes.find(p => p.name === name),
-            get git() {
-                return (gitScope ??= _this._readGitScope(repoDir));
-            },
         };
         /** Defined rather than assigned, so the cache stays out of every enumeration of this object -
          *  see the field's own doc for what walked into it. */
@@ -315,7 +347,7 @@ export class Repository extends Package {
             deepFindDependencies(pkg, pkg.dependencies);
         }
     }
-    /** `git` facts for a `${{ repository.git.* }}` expression. Synchronous on purpose: it backs a lazy
+    /** `git` facts for a `${{ git.* }}` expression. Synchronous on purpose: it backs a lazy
      *  getter, and a getter cannot await. Everything is `undefined` outside a git checkout - not an
      *  error, just a repository without one. */
     _readGitScope(dirname) {

package/core/run-step.d.ts

@@ -0,0 +1,75 @@
+import type { Logger } from '../utils/logger.js';
+import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
+import type { Package } from './package.js';
+import type { Repository } from './repository.js';
+/**
+ * What a **function step** is handed - a `run.<script>.before`/`.exec`/`.after` or a
+ * `version.<slot>` written as JavaScript instead of a shell command, and the `if` deciding whether
+ * a script runs at all.
+ *
+ * An object rather than loose parameters, for the reason `CommandContext` is one: a member added
+ * later must not break every step already written against it.
+ *
+ * **The whole point of the function form is *when* it runs.** A `${{ }}` expression is evaluated
+ * while the repository's config resolves - which every command does, `rman list` included - so it
+ * can only ever answer questions about the state the config was loaded in, and anything it *did*
+ * would happen on every invocation. A function step runs when its turn comes, with the real
+ * objects, in the package's own directory. Reach for it exactly when that difference matters;
+ * a shell command is still the right shape for a shell command.
+ */
+export interface RunStepContext {
+    /**
+     * The package this step is running for - `pkg`, matching `${{ pkg }}` in an expression rather
+     * than `CommandContext.package`. `package` is a reserved word, so that spelling forces every
+     * author to rename it while destructuring (`{ package: current }`), which is friction paid at
+     * every call site for no benefit.
+     *
+     * Always set, unlike `CommandContext.package`: a step belongs to a package by construction, and
+     * the repo-wide bookend belongs to the root package.
+     */
+    pkg: Package;
+    repository: Repository;
+    /**
+     * The directory this step is *about* - the package's own, or the repository root for a monorepo's
+     * bookend. The same directory a shell step in this slot is spawned in.
+     *
+     * **`process.cwd()` is NOT changed, and cannot be.** A shell step gets a real working directory
+     * because it is a child process; a function step runs inside rman's own, and `run` executes
+     * packages **concurrently** - one step calling `process.chdir()` would move the ground under
+     * every other step running at that moment. So a relative path resolves against wherever rman was
+     * invoked, which is almost never what the step meant:
+     *
+     * ```js
+     * fs.writeFileSync('out.txt', data)                  // the repository root. Measured, and wrong.
+     * fs.writeFileSync(path.join(ctx.cwd, 'out.txt'), data)   // the package
+     * ```
+     *
+     * `ctx.runBin` is already bound to this directory, so a binary run through it needs no such care.
+     */
+    cwd: string;
+    /**
+     * The repository's locally installed binaries, already carrying this run's `cwd` and log level -
+     * handed over rather than imported, for the reason `CommandContext.runBin` is.
+     */
+    runBin: (bin: string, argv: string[], options?: RunBinOptions) => Promise<RunBinResult>;
+    /** Logger at this run's resolved level. **Prefer it to `console`**: with the live progress panel
+     *  on, a direct write lands beside the panel rather than in the step's own log. */
+    logger: Logger;
+}
+/**
+ * A step written as JavaScript. **Failure is a throw** - the return value means nothing, exactly as
+ * a non-zero exit is what fails a shell step and what `runBin` rejects on. A step that can report
+ * trouble only by returning something nobody reads is a step that passes while doing nothing.
+ */
+export type RunStepFn = (context: RunStepContext) => void | Promise<void>;
+/** One entry of a `before`/`exec`/`after` slot: a shell command, or a function. A list of them runs
+ *  in sequence, and the two forms mix freely within one list. */
+export type RunStepValue = string | RunStepFn;
+/**
+ * A `run.<script>.if` written as JavaScript, deciding whether the script runs for this package.
+ *
+ * The string form is a small closed grammar (`changed and not private`) which cannot express an
+ * arbitrary condition, and a `${{ }}` one is frozen at config-load time. This is evaluated per
+ * package, when the run reaches it - the same context a step gets.
+ */
+export type RunConditionFn = (context: RunStepContext) => boolean | Promise<boolean>;

package/core/run-step.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

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

package/interfaces/rman-config.interface.d.ts

@@ -1,4 +1,5 @@
 import type { RmanPlugin } from '../core/plugin.js';
+import type { RunConditionFn, RunStepValue } from '../core/run-step.js';
 /**
  * Adds a `+key` alongside every key of `T`, which **appends** to whatever that key already resolved
  * to instead of replacing it - see `mergeConfig`.
@@ -9,6 +10,23 @@ import type { RmanPlugin } from '../core/plugin.js';
 export type WithAppend<T> = {
     [K in keyof T as `+${K & string}`]?: T[K];
 };
+/**
+ * The one key every nested config node may carry: `vars` scoping that node's subtree - a fresh copy
+ * per level, merged per key over the level above. See `withScopedVars` in `core/config.ts` for what
+ * it does at resolution time, and docs/rman.md#scoped-vars for how it reads.
+ *
+ * **Every nested options interface extends this**, and a new one has to remember to - which is the
+ * cost of the runtime rule being general (any object node scopes) while a type can only say it one
+ * interface at a time. TypeScript has no way to state "and every object below this may also carry
+ * `vars`" without a recursive remap that would wreck the error messages.
+ *
+ * Extended by the `XOptions` interface rather than declared on `XOptionsKeys`, so `WithAppend` does
+ * not generate a `+vars`: appending to `vars` means nothing, since objects merge either way.
+ */
+export interface ScopedVars {
+    /** Values for `${{ vars.* }}` to read, for this node and everything under it. */
+    vars?: Record<string, unknown>;
+}
 /**
  * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
  * `"rman"` key) - see docs/rman.md#configuration-rmanrc-rmanrcyml for the full reference. Every
@@ -120,8 +138,8 @@ export interface RmanConfigKeys {
     githubRelease?: RmanConfig.GithubReleaseOptions;
     /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). A bare string (or array of
      *  them) is shorthand for `{ exec: ... }` - `test: "mocha"` and `test: { exec: "mocha" }` mean
-     *  exactly the same thing. */
-    run?: Record<string, string | string[] | RmanConfig.RunScriptOptions>;
+     *  exactly the same thing, and a bare function is the same shorthand for a function step. */
+    run?: RmanConfig.RunConfig;
     /**
      * In-repo packages this one depends on **beyond what its own manifest declares** - purely for
      * rman's own dependency graph (topo-sort, `--deps`/`--dependents`, `run`'s scheduling, the version
@@ -190,7 +208,7 @@ export declare namespace RmanConfig {
         file: string;
         constant?: string;
     };
-    interface VersionOptions extends VersionOptionsKeys, WithAppend<VersionOptionsKeys> {
+    interface VersionOptions extends VersionOptionsKeys, WithAppend<VersionOptionsKeys>, ScopedVars {
     }
     interface VersionOptionsKeys {
         commitMessage?: string;
@@ -225,14 +243,17 @@ export declare namespace RmanConfig {
          *  that slot of its own (`version` in a Node repository's `package.json#scripts`, whatever a
          *  plugin's step source answers elsewhere - the package's own declaration wins, as in `run`).
          *  An array runs them in sequence. `${{ pkg.targetVersion }}` is bound here and in the two
-         *  below, and nowhere else. */
-        exec?: string | string[];
+         *  below, and nowhere else.
+         *
+         *  A `RunStepFn` runs in place of a shell command - but note that `${{ pkg.targetVersion }}` is
+         *  a *string* substitution, so a function reads the written version off `pkg` instead. */
+        exec?: RunStepValue | RunStepValue[];
         /** Same, before the write (`preversion` in a Node repository). */
-        before?: string | string[];
+        before?: RunStepValue | RunStepValue[];
         /** Same, after it (`postversion` in a Node repository). */
-        after?: string | string[];
+        after?: RunStepValue | RunStepValue[];
     }
-    interface ChangelogOptions extends ChangelogOptionsKeys, WithAppend<ChangelogOptionsKeys> {
+    interface ChangelogOptions extends ChangelogOptionsKeys, WithAppend<ChangelogOptionsKeys>, ScopedVars {
     }
     interface ChangelogOptionsKeys {
         ignoreTypes?: string[];
@@ -240,7 +261,23 @@ export declare namespace RmanConfig {
         filePath?: string;
         tagPattern?: string;
     }
-    interface RunScriptOptions extends RunScriptOptionsKeys, WithAppend<RunScriptOptionsKeys> {
+    /**
+     * The `run` block: scripts by name.
+     *
+     * **`run.vars` works at runtime but is deliberately not in this type**, and the reason is a
+     * measured trade rather than an oversight. `run` is keyed by script name, so any encoding that
+     * lets `vars` through has to widen the index signature's value type to something object-shaped -
+     * and TypeScript then stops excess-property-checking *every* script's options. Measured on the
+     * same file: with the widened index, `run: { build: { exce: 'tsc' } }` compiles clean.
+     *
+     * Catching that typo across every script is worth more than typing one key, so a typed JS config
+     * writing `run.vars` needs a cast (`run: { vars: { x: 2 }, build: ... } as RmanConfig['run']`).
+     * YAML and JSON configs are unchecked anyway and simply work. A key-remapped index signature
+     * (`{ [K in string as K extends 'vars' ? never : K]: ... }`) was tried and does not help - the
+     * remap still produces an index signature that claims `vars`.
+     */
+    type RunConfig = Record<string, RunStepValue | RunStepValue[] | RunScriptOptions>;
+    interface RunScriptOptions extends RunScriptOptionsKeys, WithAppend<RunScriptOptionsKeys>, ScopedVars {
     }
     interface RunScriptOptionsKeys {
         concurrency?: number;
@@ -250,17 +287,21 @@ export declare namespace RmanConfig {
         logLevel?: 'silent' | 'error' | 'info' | 'verbose';
         changedSince?: string;
         skip?: boolean;
-        if?: string;
+        /** Whether this script runs for a package at all - the small `changed and not private` grammar,
+         *  or a `RunConditionFn` for a condition it cannot express. Both are evaluated per package when
+         *  the run reaches it; a `${{ }}` expression here is not, having been resolved when the config
+         *  loaded. */
+        if?: string | RunConditionFn;
         /** Command(s) to run as this script itself, when the package's `package.json` doesn't define
-         *  it. An array runs them in sequence. */
-        exec?: string | string[];
+         *  it. An array runs them in sequence, and may mix shell commands with functions. */
+        exec?: RunStepValue | RunStepValue[];
         /** Same, for this script's `pre<script>` hook. */
-        before?: string | string[];
+        before?: RunStepValue | RunStepValue[];
         /** Same, for its `post<script>` hook. */
-        after?: string | string[];
+        after?: RunStepValue | RunStepValue[];
         override?: boolean;
     }
-    interface PublishOptions extends PublishOptionsKeys, WithAppend<PublishOptionsKeys> {
+    interface PublishOptions extends PublishOptionsKeys, WithAppend<PublishOptionsKeys>, ScopedVars {
     }
     interface PublishOptionsKeys {
         /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
@@ -286,7 +327,7 @@ export declare namespace RmanConfig {
     type PublishTarget = 'npm' | 'docker';
     /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
      *  docker` errors clearly on a package that opts in here but leaves this out. */
-    interface DockerPublishOptions extends DockerPublishOptionsKeys, WithAppend<DockerPublishOptionsKeys> {
+    interface DockerPublishOptions extends DockerPublishOptionsKeys, WithAppend<DockerPublishOptionsKeys>, ScopedVars {
     }
     interface DockerPublishOptionsKeys {
         /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
@@ -314,7 +355,7 @@ export declare namespace RmanConfig {
      *  (which tag, which repository, what the notes say) already has a sensible source. Nothing here
      *  decides *whether* a release is cut: a release records that the repository shipped, so it is
      *  always cut, and these are only details about how. */
-    interface GithubReleaseOptions extends GithubReleaseOptionsKeys, WithAppend<GithubReleaseOptionsKeys> {
+    interface GithubReleaseOptions extends GithubReleaseOptionsKeys, WithAppend<GithubReleaseOptionsKeys>, ScopedVars {
     }
     interface GithubReleaseOptionsKeys {
         /** Files to attach to the release, as glob patterns relative to the package's own directory

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.1.1",
+  "version": "1.2.2",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
+    "@xmldom/xmldom": "^0.9.12",
     "ansi-colors": "^4.1.3",
     "cross-dirname": "^0.1.0",
     "easy-table": "^1.2.0",

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,17 +53,36 @@ export declare namespace RunService {
      *   run:
      *     test: mocha          # same as   test: { exec: mocha }
      */
-    /** One command of a script, with the label the progress panel and the per-step log show. */
-    interface ScriptStep {
+    /**
+     * 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;
     }
-    /** The three slots a script is made of, each one command or several run in sequence. The same
-     *  three names a `.rmanrc "run.<script>"` block uses, because they are the same three things. */
-    interface ScriptSlots {
-        before?: string[];
-        exec?: string[];
-        after?: string[];
+    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`.
@@ -75,15 +95,15 @@ export declare namespace RunService {
      * Returns `undefined` for "this package declares nothing", not empty slots - the difference
      * decides whether the config's value applies.
      */
-    type StepSource = (pkg: Package, script: string) => ScriptSlots | undefined;
+    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.
      */
-    function addStepSource(source: StepSource): void;
+    export function addStepSource(source: StepSource): void;
     /** For tests, which would otherwise leak a source into every later case in the process. */
-    function clearStepSources(): void;
+    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.
@@ -95,7 +115,7 @@ export declare namespace RunService {
      * 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.
      */
-    function contributedSlots(pkg: Package, script: string): ScriptSlots | undefined;
+    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.
@@ -106,13 +126,38 @@ export declare namespace RunService {
      * 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 command, **already evaluated**: `version`'s three
+     * `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 `' && '`.
      */
-    function runLifecycleSlot(pkg: Package, script: string, slot: keyof ScriptSlots, fallback?: string): Promise<void>;
-    function getConfig(pkg: Package, script: string): Record<string, unknown>;
+    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) -
@@ -126,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;
@@ -144,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;