rman 1.0.12 → 1.2.1

package/core/repository.js

@@ -1,17 +1,44 @@
 import { execFileSync } from 'node:child_process';
-import glob from 'fast-glob';
-import fs from 'fs';
 import path from 'path';
 import semver from 'semver';
 import { GitHelper } from '../utils/git.js';
-import { interpolateConfig, 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';
+import { Workspace } from './workspace.js';
 export class Repository extends Package {
     dirname;
     monorepo;
     packages;
     cwd;
     rootPackage;
+    /** Commands the repository's plugins contributed, loaded during `create` because the workspace
+     *  providers they bring are needed before any package can be found. `cli.ts` registers them. */
+    pluginCommands = [];
+    /**
+     * Cached repository scope - see `_repositoryScope`.
+     *
+     * **Non-enumerable**, and for the same reason `targetVersion` itself is: this cache holds a
+     * `PackageScope` per package, each carrying that throwing getter, and it hangs off a `Repository`
+     * which every `Package` points back at. Left enumerable, *any* deep walk of a package reached it
+     * and threw - measured through a test's own `toEqual` diff, but a `JSON.stringify` or a debugger
+     * would do it too, with an error about `version` that has nothing to do with what the caller did.
+     * 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
@@ -54,7 +81,7 @@ export class Repository extends Package {
             result = result.filter(p => scopes.includes(p.name));
         }
         if (options?.toposort)
-            topoSortPackages(result);
+            this._topoSortPackages(result);
         return result;
     }
     getPackage(name) {
@@ -88,6 +115,53 @@ export class Repository extends Package {
         }
         return result;
     }
+    /**
+     * The scope a `${{ ... }}` expression is evaluated against for `pkg`, optionally with the version
+     * a run is about to write bound into it.
+     *
+     * `version` is the only caller that passes one, and it has to: the config was resolved before its
+     * plan existed, so `pkg.targetVersion` had nothing to be. Re-evaluating that raw value against
+     * this is how that one binding gets filled in, without every other command paying for it - or
+     * 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
@@ -98,77 +172,165 @@ export class Repository extends Package {
      * single-package repository it *is* the one package, so `"[*]"` has to reach it; in a monorepo
      * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
+    /**
+     * Gives every package its `repository` and `parent`, before any config is resolved - a config
+     * expression or a provider may already want to navigate from a package outwards.
+     *
+     * A repository's own `repository` is itself, which reads oddly and is the honest answer:
+     * `Repository extends Package`, so the repository *is* a package of its own repository.
+     */
+    _linkPackages() {
+        this.repository = this;
+        this.rootPackage.repository = this;
+        for (const pkg of this.packages) {
+            pkg.repository = this;
+            /** The deepest package that strictly contains it - the root for an ordinary member, an
+             *  enclosing package for a nested one. Longest containing path wins, the same rule
+             *  `currentPackage` uses to resolve "the package I am standing in". */
+            let parent = this.monorepo ? this.rootPackage : undefined;
+            for (const other of this.packages) {
+                if (other === pkg)
+                    continue;
+                const rel = path.relative(other.dirname, pkg.dirname);
+                const contains = !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+                if (contains && (!parent || other.dirname.length > parent.dirname.length))
+                    parent = other;
+            }
+            pkg.parent = pkg === this.rootPackage ? undefined : parent;
+        }
+    }
     async _resolveConfigs() {
         const cache = new Map();
-        const repoDir = this.dirname;
-        const scopeOf = (pkg) => {
-            // A package.json without a "name" is unusual but legal, and `info` prints such a package
-            // rather than refusing it - so the scope has to survive one too.
-            const name = pkg.name ?? '';
-            const at = name.lastIndexOf('/');
-            return {
-                name,
-                scope: at > 0 ? name.slice(0, at) : undefined,
-                unscopedName: at > 0 ? name.slice(at + 1) : name,
-                version: pkg.version ?? '',
-                basename: path.basename(pkg.dirname),
-                dirname: pkg.dirname,
-                relativeDir: path.relative(this.dirname, pkg.dirname),
-                // A copy: an expression has no business mutating the package rman is about to act on.
-                json: { ...pkg.json },
-            };
+        /**
+         * `DEFERRED_PATHS` are left *raw* in the result (see `interpolateConfig`'s `walk`), so the
+         * resolved config is the only copy anyone needs - `version` reads its own hooks straight off
+         * `config` and interpolates them itself once `pkg.targetVersion` exists. There used to be a
+         * second `rawConfig` copy of every package's config for that one reader; measured identical.
+         */
+        /**
+         * The root is resolved **with its name**, like every other package, because selectors now speak
+         * to it: `"[/]"` names it and `"[*]"` includes it. It used to be resolved without one, which is
+         * what made `"[*]"` quietly mean "the workspace packages" - `"[ws:*]"` is that, spelled.
+         */
+        const rootRaw = await resolveConfig(this.dirname, this.dirname, cache, this.rootPackage.name);
+        this.config = interpolateConfig(rootRaw, this.configScope(this.rootPackage), { skip: DEFERRED_PATHS });
+        for (const pkg of this.packages) {
+            const raw = await resolveConfig(this.dirname, pkg.dirname, cache, pkg.name);
+            pkg.config = interpolateConfig(raw, this.configScope(pkg), { skip: DEFERRED_PATHS });
+        }
+        if (this.monorepo)
+            this.rootPackage.config = this.config;
+    }
+    _topoSortPackages(packages) {
+        packages.sort((a, b) => {
+            if (b.dependencies.includes(a))
+                return -1;
+            if (a.dependencies.includes(b))
+                return 1;
+            return 0;
+        });
+    }
+    _packageScope(pkg, targetVersion) {
+        // A manifest without a "name" is unusual but legal, and `info` prints such a package rather
+        // than refusing it - so the scope has to survive one too.
+        const name = pkg.name ?? '';
+        /** Splitting `@scope/name` is npm's convention, not a universal - the provider decides. */
+        const { scope: nameScope, unscopedName } = Manifest.splitName(pkg.dirname, name);
+        const scope = {
+            name,
+            scope: nameScope,
+            unscopedName,
+            version: pkg.version ?? '',
+            basename: path.basename(pkg.dirname),
+            dirname: pkg.dirname,
+            relativeDir: path.relative(this.dirname, pkg.dirname),
+            /** The same `Package.provider`, so a `"[*]"` declaration can say something for one ecosystem
+             *  only - `if: "${{ pkg.provider === 'node' }}"` in a polyglot repository. Omitting it would
+             *  leave the expression scope and the `Package` disagreeing about what a package is. */
+            provider: pkg.provider,
+            // A copy: an expression has no business mutating the package rman is about to act on.
+            manifest: { ...pkg.manifest.raw },
         };
-        const packageScopes = this.packages.map(scopeOf);
-        let gitScope;
-        const repository = {
-            ...scopeOf(this.rootPackage),
+        if (targetVersion !== undefined) {
+            scope.targetVersion = targetVersion;
+            return scope;
+        }
+        /** Otherwise a getter that *throws*, rather than a missing key handing back `undefined` and
+         *  letting a tag come out as "app:undefined". Defined rather than assigned because there is no
+         *  value to assign - outside a `version` run there is no target version to name.
+         *
+         *  Non-enumerable, and that is load-bearing: spreading an object runs its enumerable getters,
+         *  so an enumerable one threw the moment `_repositoryScope` spread the root's scope - which is
+         *  every `configScope()` call, for every command. Property access still triggers it, which is
+         *  the only thing it exists for. */
+        Object.defineProperty(scope, 'targetVersion', {
+            enumerable: false,
+            get() {
+                throw new Error('pkg.targetVersion is only available while "version" is running - no other command has a target version');
+            },
+        });
+        return scope;
+    }
+    /** Built once and reused: it is the same for every package, and its `git` getter caches too, so a
+     *  repository whose config never mentions git spawns none. */
+    _repositoryScope() {
+        if (this._repoScope)
+            return this._repoScope;
+        const packageScopes = this.packages.map(p => this._packageScope(p));
+        const built = {
+            ...this._packageScope(this.rootPackage),
             monorepo: this.monorepo,
             packages: packageScopes,
             package: (name) => packageScopes.find(p => p.name === name),
-            // A getter, so a repository whose config never mentions git spawns no git at all - and every
-            // command resolves config, not just the ones that care.
-            get git() {
-                return (gitScope ??= readGitScope(repoDir));
-            },
         };
-        const withVars = (pkg, config) => interpolateConfig(config, { pkg: scopeOf(pkg), repository, env: { ...process.env }, semver });
-        this.config = withVars(this.rootPackage, await resolveConfig(this.dirname, this.dirname, cache));
-        for (const pkg of this.packages) {
-            pkg.config = withVars(pkg, await resolveConfig(this.dirname, pkg.dirname, cache, pkg.name));
-        }
-        if (this.monorepo)
-            this.rootPackage.config = this.config;
+        /** 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. */
+        Object.defineProperty(this, '_repoScope', { value: built, enumerable: false, writable: true });
+        return built;
+    }
+    /**
+     * One `.rmanrc "dependencies"` entry to a package: its **name** first, then a
+     * **repository-relative directory**.
+     *
+     * The path form is what makes the key usable outside npm. A name identifies a package only where
+     * the ecosystem guarantees uniqueness - the same reason `Package.dependencies` holds references
+     * and `Workspace.Layout` carries paths - so a repository whose names collide, or whose packages
+     * have no names rman can read, states the edge by directory instead.
+     *
+     * Name first because that is what a Node repository writes and there is no ambiguity in practice:
+     * a package name that is also an existing directory path in the same repository does not occur.
+     * An entry matching neither is ignored, as an unknown name always was - the graph is a statement
+     * about packages that exist.
+     */
+    _resolveDeclaredPackage(entry) {
+        const byName = this.getPackage(entry);
+        if (byName)
+            return byName;
+        const dir = path.resolve(this.dirname, entry);
+        return this.packages.find(p => path.resolve(p.dirname) === dir);
     }
     _updateDependencies() {
         const deps = {};
         for (const pkg of this.packages) {
-            const o = {
-                ...pkg.json.dependencies,
-                ...pkg.json.devDependencies,
-                ...pkg.json.peerDependencies,
-                ...pkg.json.optionalDependencies,
-            };
-            const configDeps = pkg.config.dependencies;
-            if (configDeps) {
-                if (Array.isArray(configDeps))
-                    configDeps.forEach(x => (o[x] = o[x] || '*'));
-                else
-                    Object.assign(o, configDeps);
+            /** Which manifest fields hold dependencies is the ecosystem's business, so the provider
+             *  reads them - npm's four field names used to be spelled out right here. */
+            const dependencies = [...Manifest.dependenciesOf(pkg, this.packages)];
+            /** `.rmanrc "dependencies"` on top, and it works with no provider at all: a repository rman
+             *  cannot read the manifests of can still declare its graph by hand. */
+            const declared = pkg.config.dependencies ?? [];
+            for (const entry of declared) {
+                const p = this._resolveDeclaredPackage(entry);
+                if (p && p !== pkg && !dependencies.includes(p))
+                    dependencies.push(p);
             }
-            const dependencies = [];
-            for (const k of Object.keys(o)) {
-                const p = this.getPackage(k);
-                if (p)
-                    dependencies.push(k);
-            }
-            deps[pkg.name] = dependencies;
+            deps[pkg.name] = dependencies.map(d => d.name);
             pkg.dependencies = dependencies;
         }
         let circularCheck;
         const deepFindDependencies = (pkg, target) => {
-            if (circularCheck.includes(pkg.name))
+            if (circularCheck.includes(pkg))
                 return;
-            circularCheck.push(pkg.name);
+            circularCheck.push(pkg);
             for (const s of pkg.dependencies) {
                 /** `target` starts out *as* the top-level package's own `dependencies` array, so its
                  *  direct entries are trivially "already in target" - recursing only when newly-added
@@ -177,9 +339,7 @@ export class Repository extends Package {
                  *  and never let the top-level package end up depending on itself via a cycle. */
                 if (s !== circularCheck[0] && !target.includes(s))
                     target.push(s);
-                const p = this.getPackage(s);
-                if (p)
-                    deepFindDependencies(p, target);
+                deepFindDependencies(s, target);
             }
         };
         for (const pkg of this.packages) {
@@ -187,25 +347,63 @@ export class Repository extends Package {
             deepFindDependencies(pkg, pkg.dependencies);
         }
     }
-    static async create(root, options) {
-        const dirname = root || process.cwd();
-        let deep = options?.deep ?? 10;
-        let pkgDirname = dirname;
-        while (deep-- >= 0 && fs.existsSync(pkgDirname)) {
-            const f = path.join(pkgDirname, 'package.json');
-            if (fs.existsSync(f)) {
-                const pkgJson = JSON.parse(fs.readFileSync(f, 'utf-8'));
-                if (Array.isArray(pkgJson.workspaces)) {
-                    const packages = this._resolvePackages(pkgDirname, pkgJson.workspaces);
-                    return Repository._init(new Repository(pkgDirname, true, packages, dirname));
-                }
-                /** If we reach to the root of the project */
-                if (fs.existsSync(path.join(pkgDirname, '.git')))
-                    break;
+    /** `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) {
+        const run = (args) => {
+            try {
+                return execFileSync('git', args, { cwd: dirname, stdio: ['ignore', 'pipe', 'ignore'] })
+                    .toString()
+                    .trim();
             }
-            pkgDirname = path.resolve(pkgDirname, '..');
-        }
-        return Repository._init(new Repository(dirname, false, [], dirname));
+            catch {
+                return undefined;
+            }
+        };
+        const sha = run(['rev-parse', 'HEAD']);
+        if (sha === undefined)
+            return { branch: undefined, sha: undefined, shortSha: undefined, dirty: undefined };
+        const status = run(['status', '--porcelain']);
+        return {
+            // Empty on a detached HEAD, which is what a CI checkout often is - reported as undefined
+            // rather than an empty string, so `?? 'detached'` in an expression works.
+            branch: run(['branch', '--show-current']) || undefined,
+            sha,
+            shortSha: sha.slice(0, 7),
+            dirty: status === undefined ? undefined : status.length > 0,
+        };
+    }
+    /**
+     * Opens the repository containing `root` (default: the current directory).
+     *
+     * Three steps, in this order because each needs the one before it:
+     *
+     * 1. **Find the root** without knowing any ecosystem - see `Workspace.findRoot`. It cannot be
+     *    otherwise: the plugins that know what a package is are named in the config file this step
+     *    is looking for.
+     * 2. **Load the plugins** the root's config names, which registers their workspace providers
+     *    (and their commands, handed on via `pluginCommands` - `cli.ts` registers those).
+     * 3. **Ask the providers** for the layout. None recognizing it means a repository that is itself
+     *    the one package.
+     *
+     * **A repository whose `.rmanrc` names no plugin has no packages beyond itself**, and that is the
+     * boundary working rather than failing: `workspaces` in a `package.json` is npm's idea, so it
+     * takes `plugins: ['rman-node']` to be read as one.
+     */
+    static async create(root, options) {
+        const from = root || process.cwd();
+        const rootDir = Workspace.findRoot(from, options?.deep ?? 10);
+        /** The root's own config, raw: `plugins` is a list of package names, so it needs neither the
+         *  package list (which does not exist yet) nor expression interpolation. */
+        const rootConfig = await readDirConfig(rootDir);
+        const pluginCommands = await loadPlugins(rootDir, rootConfig);
+        const layout = Workspace.resolve(rootDir);
+        const packages = (layout?.packageDirs ?? []).map(dir => new Package(dir));
+        const repo = new Repository(layout?.root ?? rootDir, packages.length > 0, packages, from);
+        repo.pluginCommands = pluginCommands;
+        repo._linkPackages();
+        return Repository._init(repo);
     }
     /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
      *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
@@ -215,57 +413,4 @@ export class Repository extends Package {
         repo._updateDependencies();
         return repo;
     }
-    static _resolvePackages(dirname, patterns) {
-        const packages = [];
-        for (const pattern of patterns) {
-            const dirs = glob.sync(pattern, {
-                cwd: dirname,
-                absolute: true,
-                deep: 0,
-                onlyDirectories: true,
-            });
-            for (const dir of dirs) {
-                const f = path.join(dir, 'package.json');
-                if (fs.existsSync(f))
-                    packages.push(new Package(dir));
-            }
-        }
-        return packages;
-    }
-}
-function topoSortPackages(packages) {
-    packages.sort((a, b) => {
-        if (b.dependencies.includes(a.name))
-            return -1;
-        if (a.dependencies.includes(b.name))
-            return 1;
-        return 0;
-    });
-}
-/** `git` facts for a `${{ repository.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. */
-function readGitScope(dirname) {
-    const run = (args) => {
-        try {
-            return execFileSync('git', args, { cwd: dirname, stdio: ['ignore', 'pipe', 'ignore'] })
-                .toString()
-                .trim();
-        }
-        catch {
-            return undefined;
-        }
-    };
-    const sha = run(['rev-parse', 'HEAD']);
-    if (sha === undefined)
-        return { branch: undefined, sha: undefined, shortSha: undefined, dirty: undefined };
-    const status = run(['status', '--porcelain']);
-    return {
-        // Empty on a detached HEAD, which is what a CI checkout often is - reported as undefined
-        // rather than an empty string, so `?? 'detached'` in an expression works.
-        branch: run(['branch', '--show-current']) || undefined,
-        sha,
-        shortSha: sha.slice(0, 7),
-        dirty: status === undefined ? undefined : status.length > 0,
-    };
 }

package/core/resolve-target.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolves a config-supplied module reference - an `extends` base, a `plugins` entry - **relative
+ * to the file that named it**, not to rman's own location.
+ *
+ * That distinction is the whole reason this is a function: resolving from rman would look in rman's
+ * own dependencies, where a repository's shared config or plugin has no reason to be. A bare
+ * specifier therefore goes through `from`'s own `node_modules` (a package's `exports` subpaths
+ * included); anything path-like resolves against `from`'s directory.
+ *
+ * `label` names the config key in the error, so a failure says which setting to go and look at.
+ */
+export declare function resolveConfigTarget(target: string, from: string, label: string): string;

package/core/resolve-target.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** File forms a path-like target may take when it names no extension of its own. */
+const TARGET_EXTENSIONS = ['', '.yml', '.yaml', '.json', '.cjs', '.mjs', '.js'];
+/**
+ * Resolves a config-supplied module reference - an `extends` base, a `plugins` entry - **relative
+ * to the file that named it**, not to rman's own location.
+ *
+ * That distinction is the whole reason this is a function: resolving from rman would look in rman's
+ * own dependencies, where a repository's shared config or plugin has no reason to be. A bare
+ * specifier therefore goes through `from`'s own `node_modules` (a package's `exports` subpaths
+ * included); anything path-like resolves against `from`'s directory.
+ *
+ * `label` names the config key in the error, so a failure says which setting to go and look at.
+ */
+export function resolveConfigTarget(target, from, label) {
+    const dir = path.dirname(path.resolve(from));
+    if (target.startsWith('.') || path.isAbsolute(target)) {
+        const candidate = path.resolve(dir, target);
+        const found = TARGET_EXTENSIONS.map(ext => candidate + ext).find(f => fs.existsSync(f) && fs.statSync(f).isFile());
+        if (!found)
+            throw new Error(`"${label}" target "${target}" was not found, resolved from "${from}"`);
+        return found;
+    }
+    try {
+        return createRequire(pathToFileURL(path.join(dir, 'noop.js'))).resolve(target);
+    }
+    catch {
+        throw new Error(`"${label}" target "${target}" could not be resolved from "${from}" - is it installed in this repository?`);
+    }
+}

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 {};