rman 1.0.12 → 1.1.1

package/commands/config.command.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import colors from 'ansi-colors';
+import * as yaml from 'js-yaml';
+import { DEFERRED_PATHS } from '../core/config.js';
+import { applyRootOption, readRootOption } from '../utils/package-filter.js';
+export function initCli(repository, program) {
+    program.command({
+        command: 'config',
+        describe: 'Prints the effective .rmanrc config for the package of the current directory',
+        builder: cmd => applyRootOption(cmd, 'Print the config for')
+            .example('$0 config', '# The config of the package you are standing in')
+            .example('$0 config --root', "# The repository root's own config instead")
+            .example('$0 config --json | jq .version', '# Machine-readable')
+            .option('json', {
+            describe: 'Print as JSON instead of YAML - nothing else on stdout, so it can be piped.',
+            type: 'boolean',
+            default: false,
+        }),
+        handler: args => {
+            const target = (!readRootOption(args) && repository.currentPackage) || repository.rootPackage;
+            if (args.json) {
+                console.log(JSON.stringify(target.config, undefined, 2));
+                return;
+            }
+            /**
+             * **Colour only on a terminal, and here that is correctness rather than taste.** The header
+             * and notes are YAML `#` comments so the whole output stays loadable - and an escape sequence
+             * inside one makes it *unloadable*: `rman config > rmanrc.yml` wrote a file js-yaml rejects
+             * with "the stream contains non-printable characters" (measured; `ansi-colors` does not turn
+             * itself off for a pipe here). The repository's own convention for this is
+             * `process.stdout.isTTY`, as `run`/`exec`'s progress panel uses.
+             */
+            const comment = (text) => (process.stdout.isTTY ? colors.gray(text) : text);
+            const relativeDir = path.relative(repository.dirname, target.dirname) || '.';
+            console.log(comment(`# ${target.name} (${relativeDir})`));
+            for (const note of deferredNotes(target))
+                console.log(comment(`# ${note}`));
+            /** `noRefs`: a value appearing twice in the config is the *same object* after merging, and
+             *  js-yaml would otherwise emit the second as an `*anchor` reference - valid YAML that reads
+             *  as a mistake in something meant to be looked at. */
+            console.log(yaml.dump(target.config, { noRefs: true, lineWidth: 100 }).trimEnd());
+        },
+    });
+}
+/**
+ * The one honest caveat about this output: **`version.before`/`.exec`/`.after` are printed raw**,
+ * expressions and all, because they are the paths in `DEFERRED_PATHS` - `${{ pkg.targetVersion }}`
+ * cannot be evaluated until `version` has computed a plan, so the repository deliberately leaves
+ * them unevaluated at load. Without saying so, a reader sees an uninterpolated `${{ ... }}` sitting
+ * among interpolated values and concludes interpolation is broken.
+ */
+function deferredNotes(pkg) {
+    const raw = DEFERRED_PATHS.filter(p => valueAt(pkg.config, p) !== undefined);
+    if (!raw.length)
+        return [];
+    return [`${raw.join(', ')}: printed raw - evaluated by "version" itself, once it knows the target version`];
+}
+function valueAt(config, dotted) {
+    return dotted.split('.').reduce((node, key) => (node == null ? undefined : node[key]), config);
+}

package/commands/diff.command.js

@@ -1,14 +1,16 @@
 import path from 'node:path';
 import colors from 'ansi-colors';
-import { findLatestTag } from '../utils/change-hash.js';
+import { ChangeHashService } from '../services/change-hash.service.js';
 import { GitHelper } from '../utils/git.js';
+import { applyRootOption, readRootOption } from '../utils/package-filter.js';
 export function initCli(repository, program) {
     program.command({
         command: 'diff [package]',
         describe: "Shows the git diff since a package's (or the whole repository's) last release tag",
-        builder: cmd => cmd
+        builder: cmd => applyRootOption(cmd, 'Diff')
             .example('$0 diff', "# Since the repository's own last tag")
             .example('$0 diff pkg-a', "# Since pkg-a's own last tag, scoped to its directory")
+            .example('$0 diff --root', '# The whole repository, from inside a package')
             .positional('package', {
             describe: 'Package name - diffs just that package, since its own last tag. Omit to diff the whole ' +
                 "repository since its own last tag (or the current directory's package, if standing inside one).",
@@ -31,11 +33,14 @@ export function initCli(repository, program) {
                 target = pkg;
                 pathspec = path.relative(repository.dirname, pkg.dirname);
             }
-            else if (repository.currentPackage) {
+            else if (!readRootOption(args) && repository.currentPackage) {
+                /** The measured gap this closes: `diff` narrowed to the current package like `run` and
+                 *  `changelog` do, but offered no way to say "the whole repository" without naming a
+                 *  package - and no package name means the repository, so there was nothing to type. */
                 target = repository.currentPackage;
                 pathspec = path.relative(repository.dirname, target.dirname);
             }
-            const tag = await findLatestTag(git, target);
+            const tag = await ChangeHashService.findLatestTag(git, target);
             if (!tag) {
                 console.log(colors.gray(`No release tag found for "${target.name}" - nothing to diff against.`));
                 return;

package/commands/exec.command.js

@@ -1,11 +1,11 @@
 import { ExecService } from '../services/exec.service.js';
 import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
 export function initCli(repository, program) {
     program.command({
         command: 'exec [command..]',
         describe: 'Runs an arbitrary shell command in each package - unlike run, not tied to any npm script',
-        builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
+        builder: cmd => applyRootOption(applyBranchGuardOptions(applyPackageFilterOptions(cmd)), 'Run')
             .parserConfiguration({ 'populate--': true, 'unknown-options-as-args': true })
             .example('$0 exec rm -rf dist', '# Not an npm script - runs directly in every package')
             .example('$0 exec --scope pkg-a -- ls -la', '# "--" needed only if the command shares a flag name with exec\'s own')
@@ -50,12 +50,6 @@ export function initCli(repository, program) {
             .option('changed-since', {
             describe: 'Only run in packages that have changed since the given git commit/hash',
             type: 'string',
-        })
-            .option('root', {
-            alias: 'r',
-            describe: 'Run across the whole repository even when the current directory is inside a single ' +
-                'package (which otherwise scopes the run to just that package). No effect elsewhere.',
-            type: 'boolean',
         })
             .conflicts('changed', 'changed-since'),
         handler: async (args) => {

package/commands/github-release.command.js

@@ -5,6 +5,7 @@ import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions }
 export function initCli(repository, program) {
     program.command({
         command: 'github-release',
+        configKeys: ['githubRelease', 'version.releaseTagPattern'],
         describe: "Creates the repository's GitHub Release for the version that just shipped",
         builder: cmd => applyBranchGuardOptions(cmd)
             .example('$0 github-release', '# Show what would be released, then ask for confirmation')

package/commands/info.command.d.ts

@@ -1,3 +1,12 @@
 import type { Argv } from 'yargs';
 import type { Repository } from '../core/repository.js';
+/**
+ * `rman info` - environment and repository, and back in the core because most of what it reports
+ * (OS, CPU, shell, git, the repository's own shape) is true of any repository.
+ *
+ * The Node half is not here at all: installing `rman-node` augments `SystemInfo` and the package
+ * manager, `npmPackages` and this plugin's own version start appearing. Without it nothing
+ * npm-shaped is asked for or printed, which is the right answer for a repository in any other
+ * language.
+ */
 export declare function initCli(repository: Repository, program: Argv): void;

package/commands/info.command.js

@@ -1,6 +1,5 @@
 import colors from 'ansi-colors';
 import semver from 'semver';
-import { CiService } from '../services/ci.service.js';
 import { SystemInfo } from '../services/system-info.js';
 function printSystemInfo(systemInfo) {
     const maxName = Object.keys(systemInfo).reduce((l, p) => Object.keys(systemInfo[p]).reduce((i, x) => Math.max(i, x.length), l), 0);
@@ -36,6 +35,15 @@ function printRepositoryInfo(info) {
         console.log('    ' + colors.reset('Packages') + ' :', colors.yellowBright(String(info.packageCount)), colors.gray('(run "list" to see them)'));
     }
 }
+/**
+ * `rman info` - environment and repository, and back in the core because most of what it reports
+ * (OS, CPU, shell, git, the repository's own shape) is true of any repository.
+ *
+ * The Node half is not here at all: installing `rman-node` augments `SystemInfo` and the package
+ * manager, `npmPackages` and this plugin's own version start appearing. Without it nothing
+ * npm-shaped is asked for or printed, which is the right answer for a repository in any other
+ * language.
+ */
 export function initCli(repository, program) {
     program.command({
         command: 'info',
@@ -49,7 +57,9 @@ export function initCli(repository, program) {
             type: 'boolean',
         }),
         handler: async (args) => {
-            const systemInfo = await SystemInfo.getSystemInfo(CiService.resolvePackageManager(repository));
+            /** Only the repository - which package manager to report, if any, is a question the core
+             *  cannot ask. `rman-node`'s augmentation reads `.rmanrc "packageManager"` off this. */
+            const systemInfo = await SystemInfo.getSystemInfo({ repository });
             const repositoryInfo = SystemInfo.getRepositoryInfo(repository);
             if (args.json) {
                 console.log(JSON.stringify({ ...systemInfo, repository: repositoryInfo }, undefined, 2));

package/commands/run.command.js

@@ -1,8 +1,8 @@
 import { RunService } from '../services/run.service.js';
 import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
 export function applyRunOptions(cmd) {
-    return applyBranchGuardOptions(applyPackageFilterOptions(cmd))
+    return applyRootOption(applyBranchGuardOptions(applyPackageFilterOptions(cmd)), 'Run')
         .option('parallel', {
         describe: 'Max packages to build at once: omit/true for CPU count (or .rmanrc run.<script>.concurrency), ' +
             'a number for that many, false to run serially. Packages always build in dependency order.',
@@ -39,12 +39,6 @@ export function applyRunOptions(cmd) {
         .option('changed-since', {
         describe: 'Only run in packages that have changed since the given git commit/hash',
         type: 'string',
-    })
-        .option('root', {
-        alias: 'r',
-        describe: 'Run across the whole repository even when the current directory is inside a single ' +
-            'package (which otherwise scopes the run to just that package). No effect elsewhere.',
-        type: 'boolean',
     })
         .conflicts('changed', 'changed-since');
 }
@@ -64,6 +58,9 @@ export function readRunOptions(args) {
 export function initCli(repository, program) {
     program.command({
         command: 'run <script>',
+        /** Which `.rmanrc` `--config` shows for this command: the script's own block, whichever
+         *  script was asked for. */
+        configKeys: (args) => ['run.' + args.script],
         describe: 'Run an npm script in each package',
         builder: cmd => applyRunOptions(cmd)
             .example('$0 run build', '')

package/commands/test.command.js

@@ -4,6 +4,7 @@ import { applyRunOptions, readRunOptions } from './run.command.js';
 export function initCli(repository, program) {
     program.command({
         command: 'test',
+        configKeys: ['run.test'],
         describe: 'Alias for "run test"',
         builder: cmd => applyRunOptions(cmd).example('$0 test', '# Tests packages'),
         handler: async (args) => {

package/commands/version.command.js

@@ -2,19 +2,32 @@ import readline from 'node:readline/promises';
 import colors from 'ansi-colors';
 import EasyTable from 'easy-table';
 import { VersionService } from '../services/version.service.js';
+import { VersionPlanService } from '../services/version-plan.service.js';
 import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
 import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
 export function initCli(repository, program) {
+    /** `rman version <bump|version>` is validated by the root's scheme (see `getPlan`), so the help
+     *  has to name that scheme's own words rather than semver's - otherwise `--help` in a repository
+     *  numbering some other way documents keywords its own planner would reject. A four-part scheme
+     *  lists four here. */
+    const { name: scheme, bumpNames } = repository.rootPackage.versionScheme;
+    const bumps = bumpNames.map(n => `"${n}"`).join('/');
+    /** For the examples. Not `smallestBump`, which throws: `--help` must still render for a scheme
+     *  that declares none, and the placeholder says what to write there. */
+    const smallest = bumpNames[0] ?? '<bump>';
     program.command({
         command: 'version [bump]',
+        /** `changelog` too: `--changelog` folds one into the bump commit, and `group` is what decides
+         *  which packages move together. */
+        configKeys: ['version', 'changelog', 'group'],
         describe: 'Bumps versions of changed packages (and their dependents), grouped via .rmanrc "group"',
         builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
-            .example('$0 version patch', '# Bump patch severity directly, applied immediately')
-            .example('$0 version', "# Auto-detect severity from commits, show the plan, don't write anything")
+            .example(`$0 version ${smallest}`, `# Bump ${smallest} directly, applied immediately`)
+            .example('$0 version', "# Auto-detect the bump from commits, show the plan, don't write anything")
             .example('$0 version --interactive', '# Show the plan either way, then ask for confirmation')
-            .example('$0 version patch --show', '# Preview what an explicit patch bump would do, without applying it')
+            .example(`$0 version ${smallest} --show`, `# Preview what an explicit ${smallest} would do, without applying it`)
             .positional('bump', {
-            describe: 'A release-type keyword ("patch"/"minor"/"major") or an explicit semver version. ' +
+            describe: `A bump keyword (${bumps}) or an explicit ${scheme} version. ` +
                 'Omit to auto-detect from commits and only preview the plan.',
             type: 'string',
         })
@@ -25,15 +38,15 @@ export function initCli(repository, program) {
         })
             .option('show', {
             describe: 'Show the resulting plan for the given bump without applying it - unlike omitting bump ' +
-                'entirely, this still uses the given release-type keyword/version to compute the plan, ' +
+                'entirely, this still uses the given bump keyword/version to compute the plan, ' +
                 'just never writes it.',
             type: 'boolean',
         })
             .conflicts('show', 'interactive')
             .option('yes', {
             alias: 'y',
-            describe: 'Skip the confirmation prompt and apply the computed plan immediately - auto-detected ' +
-                'severity included, no explicit bump keyword required (same idea as "publish --yes").',
+            describe: 'Skip the confirmation prompt and apply the computed plan immediately - an auto-detected ' +
+                'bump included, no explicit bump keyword required (same idea as "publish --yes").',
             type: 'boolean',
         })
             .conflicts('yes', 'interactive')
@@ -61,13 +74,13 @@ export function initCli(repository, program) {
             .option('preid', {
             describe: 'Make the bump a prerelease with this identifier (e.g. "beta" -> 1.2.3-beta.0). ' +
                 'Running again with the same --preid increments it (-> 1.2.3-beta.1); a different ' +
-                'identifier starts a fresh prerelease line. Ignored when bump is an explicit semver version.',
+                `identifier starts a fresh prerelease line. Ignored when bump is an explicit ${scheme} version.`,
             type: 'string',
         }),
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
             const bump = args.bump;
-            const plan = await VersionService.getPlan(repository, {
+            const plan = await VersionPlanService.getPlanner().getPlan(repository, {
                 ...readPackageFilterOptions(args),
                 bump,
                 ignoreDirty: args.ignoreDirty,
@@ -107,14 +120,40 @@ export function initCli(repository, program) {
                 message: args.message,
                 changelog,
             });
-            for (const entry of applied) {
-                if (entry.status === 'bump') {
-                    console.log(colors.green('updated'), colors.cyan(entry.package.name), entry.from, '->', colors.yellow(entry.to));
-                }
-            }
+            printApplied(applied);
         },
     });
 }
+/**
+ * What the run *did* - which is deliberately not the table again.
+ *
+ * The plan is printed above, so repeating `name from -> to` per package said nothing: `applyPlan`
+ * returned the same array it was handed, so the second list could not have differed. What it never
+ * reported is everything below - the commits (one per group, plus the root's informational sync),
+ * the tags, a tag that already existed and was left alone, and whether any of it was pushed. A
+ * release that is committed but not pushed looks identical to one that is, until someone looks.
+ */
+function printApplied(result) {
+    const count = result.updated.length;
+    console.log(`\n${colors.green('updated')} ${count} package${count === 1 ? '' : 's'}`);
+    for (const commit of result.commits) {
+        console.log(`${colors.green('commit')}  ${colors.yellow(commit.sha)}  ${colors.gray(commit.message.split('\n')[0])}`);
+    }
+    if (result.tags.length) {
+        const label = (tag) => colors.cyan(tag.name) + (tag.created ? '' : colors.gray(' (existing, left alone)'));
+        const release = result.tags.filter(t => t.release);
+        const perPackage = result.tags.filter(t => !t.release);
+        if (perPackage.length)
+            console.log(`${colors.green('tags')}    ${perPackage.map(label).join(', ')}`);
+        /** Listed on its own line: it belongs to the repository rather than to any package, which is
+         *  the whole reason it exists. */
+        if (release.length)
+            console.log(`${colors.green('tags')}    ${release.map(label).join(', ')} ${colors.gray('(repository release)')}`);
+    }
+    console.log(result.pushed
+        ? `${colors.green('push')}    pushed, with tags`
+        : `${colors.gray('push')}    ${colors.gray('not pushed - run with --push, or push it yourself')}`);
+}
 function printPlan(entries) {
     const table = new EasyTable();
     for (const e of entries) {

package/constants.js

@@ -1 +1 @@
-export const version = '1.0.12';
+export const version = '1.1.1';

package/core/config.d.ts

@@ -1,3 +1,4 @@
+import path from 'path';
 import semver from 'semver';
 import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 /**
@@ -32,9 +33,10 @@ export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
  *   `.rmanrc` therefore configures the *root package* - which is where repo-wide settings
  *   (`packageManager`, `allowBranch`, `version.*`, `githubRelease.*`) are read from anyway - and
  *   not, silently, every package under it.
- * - **A `"[selector]"` block configures the packages it names** (`"[*]"` for all of them,
- *   `"[*-dialect]"` for a glob over package names). This is the only way a directory speaks about
- *   anything but its own package.
+ * - **A `"[selector]"` block configures the packages it names** - `"[*]"` for all of them (the root
+ *   included), `"[ws:*]"` for every one but the root, `"[/]"` for the root alone, `"[*-dialect]"`
+ *   for a glob over package names. See `parseSelector`. This is the only way a directory speaks
+ *   about anything but its own package.
  *
  * Splitting the two matters because the same key means different things to the two audiences. The
  * clearest case is `run.<script>.postScript`: on a package it's that package's build hook, run in
@@ -42,21 +44,87 @@ export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
  * cascade that fed one declaration to both ran a package-relative command (`node
  * ../../support/postbuild.cjs`) at the root, where it cannot resolve.
  *
- * `packageName` is what selectors match against; without it (resolving the root's own config, say)
- * selector blocks contribute nothing at all.
+ * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
+ * all. The root package passes its own, since `"[/]"` and `"[*]"` speak to it.
  */
 export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>, packageName?: string): Promise<RmanConfig>;
-/** A config key naming packages rather than settings: `"[*]"`, `"[*-dialect]"`, `"[pkg-a]"`. The
+/** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[ws:*]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
  *  one - and in YAML they also mean the key always needs quoting (`"[*]":`), since a bare `[*]`
  *  parses as a flow sequence. */
 export declare function isSelectorKey(key: string): boolean;
+/**
+ * **Which packages a selector speaks for.** Three audiences, because a repository has three:
+ *
+ * | | |
+ * | --- | --- |
+ * | `"[/]"` | the **root package** only |
+ * | `"[*]"`, `"[pkg-a]"`, `"[*-dialect]"` | **every** package the glob matches, root included |
+ * | `"[ws:*]"`, `"[workspace:pkg-*]"` | every **non-root** package the glob matches |
+ *
+ * `/` for the root because that is what a repository root is called everywhere else, and it cannot
+ * collide with a package name. `ws:` is a qualifier on the glob rather than a separate spelling of
+ * `*`, so `"[ws:pkg-*]"` means what it looks like.
+ *
+ * **`"[*]"` includes the root, and that is a change from how it used to read.** Before, selectors
+ * were not applied to the root at all, so `"[*]"` silently meant "the workspace packages" - a
+ * catch-all with an exception nothing in the syntax mentioned. The three names above say which
+ * audience is meant; `"[ws:*]"` is the old behaviour, now spelled.
+ */
+export declare function parseSelector(key: string): {
+    scope: 'root' | 'all' | 'workspace';
+    test: (name: string) => boolean;
+};
 /** The glob inside a selector key, as a `RegExp` anchored at both ends - so `"[*-dialect]"` matches
  *  `mysql-dialect` but not `my-dialect-helper`. Glob rather than regex, to match every other
  *  pattern in rman (`allowBranch`, `changelog.tagPattern`, `clean.include`). */
 export declare function selectorToRegExp(key: string): RegExp;
 /** One package, as an expression sees it - the same shape for the package the config belongs to
  *  and for the repository itself, so `${{ repository.basename }}` reads the way `${{ pkg.basename }}` does. */
+/**
+ * `file` in a `${{ ... }}` expression: what is actually on disk, resolved against **the package
+ * the config was resolved for** - so one declaration in a `"[*]"` block asks each package about
+ * its own directory.
+ *
+ * The pair exists because a config has two different questions about a path, and answering both
+ * with one function would mean picking a wrong default for the other:
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       # first of these that exists, and an error naming the config path if none do
+ *       exec: 'tsc -b ${{ file.exists("tsconfig-build.json") || file.resolve("tsconfig.json") }}'
+ * ```
+ */
+export interface FileScope {
+    /**
+     * The absolute path if it exists, **`''` if it does not** - so `a || b || c` picks the first one
+     * present, and so a miss never reaches the "nullish inside a string" guard that `undefined` would
+     * trip. Accepts a relative path (against the package directory) or an absolute one.
+     *
+     * It returns a path rather than a boolean on purpose: the caller almost always wants the path,
+     * and a separate `file.path()` to fetch it after a boolean test would read the disk twice and
+     * invite the two calls to disagree.
+     */
+    exists(target: string): string;
+    /** The absolute path, or **throws** - for a file whose absence is a mistake rather than a case to
+     *  handle. The error names the config path holding the expression, like any other. */
+    resolve(target: string): string;
+    /**
+     * The first of several that exists, or **throws** naming every candidate it tried:
+     *
+     * ```yaml
+     * exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.build.json", "tsconfig.json") }}'
+     * ```
+     *
+     * The same thing an `exists() || exists() || resolve()` chain does, said once - and it cannot be
+     * got subtly wrong the way that chain can: ending it in `exists()` leaves `tsc -b ` with no
+     * argument when nothing matches, and tsc then silently falls back to the directory's default
+     * rather than reporting that the package has no build config.
+     */
+    resolveFirst(...targets: string[]): string;
+}
 export interface PackageScope {
     /** The package's own name, scope included (`@sqb/builder`). */
     name: string;
@@ -73,9 +141,29 @@ export interface PackageScope {
     /** That directory relative to the repository root (`packages/builder`), which is what a command
      *  addressing another package from the root usually needs. Empty string for the root itself. */
     relativeDir: string;
-    /** The whole `package.json`, as a copy - so an expression can reach a field rman itself has no
-     *  opinion about (`pkg.json.engines.node`). */
-    json: Record<string, unknown>;
+    /**
+     * Which ecosystem this package belongs to - `'node'` for one read by `rman-node`, empty when no
+     * plugin claimed it. The same `Package.provider`, so one declaration can address a single
+     * ecosystem in a polyglot repository (`if: "${{ pkg.provider === 'node' }}"`).
+     */
+    provider: string;
+    /**
+     * The whole manifest, as a copy - so an expression can reach a field rman itself has no opinion
+     * about (`${{ pkg.manifest.engines.node }}`).
+     *
+     * Named `manifest`, not `json`: which file a package's identity lives in is the ecosystem's
+     * business now (see `ManifestProvider`), and `json` was that assumption showing through the one
+     * remaining user-facing name. A config written against `${{ pkg.json... }}` needs the rename.
+     */
+    manifest: Record<string, unknown>;
+    /**
+     * The version this run is about to write - **bound only during `version`**, and only once its
+     * plan is computed. Reading it anywhere else throws rather than yielding `undefined`: no other
+     * command has a target version, so an expression asking for one has been put in the wrong place,
+     * and a config that quietly evaluates to "undefined" is the failure this evaluator exists to
+     * prevent.
+     */
+    targetVersion: string;
 }
 /** Facts about the repository, on top of the root package's own - because the repository root *is*
  *  a package (`repository.name` is what its `package.json` says, `repository.basename` the directory
@@ -99,18 +187,40 @@ export interface GitScope {
     /** Whether the working tree has uncommitted changes. */
     dirty: boolean | undefined;
 }
-/** What a `${{ ... }}` expression can see - the bindings of the fresh global it is evaluated in.
- *  Namespaced rather than a flat bag of loose names: one obvious place per fact, and room to add
- *  helpers to `pkg`/`repository` later without crowding the global. */
+/**
+ * What a `${{ ... }}` expression can see - the bindings of the fresh global it is evaluated in.
+ * Namespaced rather than a flat bag of loose names: one obvious place per fact, and room to add
+ * helpers to `pkg`/`repository` later without crowding the global.
+ *
+ * Alongside these, **the config's own top-level keys are bound bare** (`${{ publish.directory }}`,
+ * `${{ clean.include }}`) - see `interpolateConfig`. They are not listed here because they come
+ * from the config being interpolated, not from this object; a name here wins over a config key of
+ * the same name.
+ *
+ * **Trap: bare `${{ version }}` is the `version` *options block*, not the package's version
+ * string** - that is `${{ pkg.version }}`. Same word, two different things, and the plain one
+ * belongs to the config because every other config key is reachable that way.
+ */
 export interface ConfigScope {
     /** The package the config was resolved for - which is what lets one declaration at the root
      *  still say something package-specific. */
     pkg: PackageScope;
     repository: RepositoryScope;
+    /** Paths, resolved against the package the config was resolved for. */
+    file: FileScope;
     env: Record<string, string | undefined>;
     /** rman's own `semver`, for the arithmetic every release config eventually wants
      *  (`semver.major(pkg.version)`). */
     semver: typeof semver;
+    /**
+     * Node's own `node:path` - `${{ path.join(pkg.dirname, 'LICENSE') }}`, rather than gluing
+     * strings with `+ "/" +` and getting a double separator or none.
+     *
+     * The platform's flavour, not `path.posix`, so a joined path is the one the shell on *this*
+     * machine understands; `path.posix` and `path.win32` are reachable through it when a config
+     * genuinely needs one of them (a Docker image path, say, which is always posix).
+     */
+    path: typeof path;
 }
 /**
  * Evaluates every `${{ ... }}` expression in **every** string value of a resolved config, against
@@ -121,8 +231,13 @@ export interface ConfigScope {
  *   clean:
  *     include: ["build", "../../coverage/${{ pkg.basename }}"]
  *   publish:
+ *     directory: build
  *     docker:
  *       image: "panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}"
+ *   run:
+ *     build:
+ *       # the config's own keys are in scope, so this is not a second copy of "build"
+ *       after: "cp README.md ${{ publish.directory }}/"
  * ```
  *
  * Every string, with no list of "interpolated keys" to memorize - a rule with exceptions is a rule
@@ -149,4 +264,18 @@ export interface ConfigScope {
  * A failing expression throws with the config path that holds it, rather than being left in place:
  * silently passing through a mistake is how a config ends up quietly doing nothing.
  */
-export declare function interpolateConfig<T>(config: T, scope: ConfigScope): T;
+export declare function interpolateConfig<T>(config: T, scope: ConfigScope, options?: {
+    skip?: string[];
+}): T;
+/**
+ * Config paths left untouched when a repository's config is first resolved, and evaluated only by
+ * the command that runs them.
+ *
+ * `version`'s own hooks are the one place `${{ pkg.targetVersion }}` makes sense, and the version
+ * being written is not known until `version` has computed its plan - long after the config was
+ * resolved. Evaluating these eagerly would throw while merely *loading* the repository, so any
+ * command at all would fail on a config that mentions it.
+ */
+export declare const DEFERRED_PATHS: string[];
+/** The `file` namespace for one package's directory - see `FileScope`. */
+export declare function createFileScope(dirname: string): FileScope;