rman 2.8.0 → 2.10.0

package/core/command-builder.js

@@ -7,7 +7,14 @@
  * switches - arrives as data now, so a typo in any of it is a compile error at the command rather
  * than a flag that silently never existed.
  */
-export function toYargsCommand(meta) {
+export function toYargsCommand(meta, 
+/**
+ * Builds the `CommandContext` the handler gets as its **second** parameter, per invocation.
+ *
+ * Optional because a caller with no repository in hand (a spec listing the registrations) has
+ * nothing to build one from, and a handler that never reads it cannot tell.
+ */
+contextFor) {
     return {
         command: meta.command,
         aliases: meta.aliases,
@@ -51,23 +58,29 @@ export function toYargsCommand(meta) {
          * narrower one is the useful one, and this is the single place the widening is admitted -
          * previously it was an `as` per option read, in every handler.
          */
-        handler: withCommandPlatforms(meta),
+        handler: wrapHandler(meta, contextFor),
     };
 }
 /**
- * Carries `CommandMetadata.platforms` into argv, where `readPackageFilterOptions` picks it up.
+ * The handler yargs is given: carries `CommandMetadata.platforms` into argv, and hands the command
+ * its `CommandContext` as a second parameter.
+ *
+ * **`(args, context)`, not `(context, args)`** - the opposite order to `CustomCommand.handler`, and
+ * decided by compatibility rather than taste: every declared command in existence is `handler(args)`,
+ * so appending a parameter breaks none of them while prepending one breaks all of them. The two
+ * authoring forms therefore disagree about the order and agree about everything in the object,
+ * which is the cheaper of the two inconsistencies.
  *
- * Through argv rather than a parameter because `filterPackages` is called by ten *services*, none
- * of which knows which command is running - `options` is all they see. One wrap here reaches every
- * one of them and changes none.
+ * `platforms` goes through argv rather than a parameter because `filterPackages` is called by ten
+ * *services*, none of which knows which command is running - `options` is all they see. One wrap
+ * here reaches every one of them and changes none.
  */
-function withCommandPlatforms(meta) {
+function wrapHandler(meta, contextFor) {
     const handler = meta.handler;
-    if (!meta.platforms?.length)
-        return handler;
     return (args) => {
-        args.commandPlatforms = meta.platforms;
-        return handler(args);
+        if (meta.platforms?.length)
+            args.commandPlatforms = meta.platforms;
+        return handler(args, contextFor?.(args));
     };
 }
 /** A command's own name - the first word of its `command` string, before any positional. */

package/core/config/config-paths.js

@@ -65,6 +65,30 @@ export const STEP_PATHS = [
     'version.before',
     'version.exec',
     'version.after',
+    /**
+     * The step inside a step's **object** form (`{ topo: true, command: buildWithTsc() }`).
+     *
+     * Array indices are dropped before matching but object keys are not, so `run.build.after[0].command`
+     * arrives as `run.build.after.command` - one segment longer than `run.*.after`, which matches by
+     * length. Without these the function would be taken for a *value* function and called while the
+     * repository loads, which is the exact failure the step/value split exists to prevent.
+     *
+     * **Measured on `@panates/rman-preset`**, whose build hook is a function under `command`: without
+     * these entries every command in a repository extending it died with
+     * `Config function in "run.build.after.command" (node/config.js) failed: Cannot read properties
+     * of undefined (reading 'vars')` - the hook called with the config scope instead of a step
+     * context, while merely resolving the config.
+     *
+     * A string at these paths is interpolated either way, which is what keeps
+     * `command: 'tsc -b ${{ file.resolve(...) }}'` working.
+     */
+    'run.*.command',
+    'run.*.before.command',
+    'run.*.exec.command',
+    'run.*.after.command',
+    'version.before.command',
+    'version.exec.command',
+    'version.after.command',
 ];
 /**
  * Config paths left untouched when a repository's config is first resolved, and evaluated only by

package/core/interfaces/custom-command.d.ts

@@ -1,9 +1,11 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
 import type { RmanConfig as CommandDeclaration } from '../../interfaces/rman-config.interface.js';
+import type { RunService } from '../../services/run.service.js';
 import type { Logger } from '../../utils/logger.js';
 import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
 import type { Package } from '../classes/package.js';
 import type { Repository } from '../classes/repository.js';
+import type { RunStepFn } from './run-step.js';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export declare const CUSTOM_COMMAND_DIR = ".rman";
 /**
@@ -34,6 +36,43 @@ export interface CommandContext {
     runBin: (bin: string, argv: string[], options?: RunBinOptions) => Promise<RunBinResult>;
     /** Logger at this run's resolved level, for a command's own narration. */
     logger: Logger;
+    /**
+     * Runs `fn` once per package under the scheduler `run` uses - `--parallel`, `--bail`, dependency
+     * order on request, the progress panel, and `console` routed to the right row. Throws when any
+     * package failed, with the recap already printed.
+     *
+     * **A `for` loop is what this replaces, and the loop is worse in more ways than it looks.** It
+     * ignores `--parallel` outright, draws no panel, and leaves the command to re-implement `--bail`
+     * and a summary line. `rman check` was that loop: measured on a nineteen-package repository at
+     * 0.4-0.9s per package, eleven seconds of wall clock for work that is entirely independent.
+     *
+     * `fn` is handed exactly what a **function step** gets - `pkg`, `cwd`, a `runBin` already bound to
+     * that package's directory and this run's log level, and a `logger`. An imported `runBin` knows
+     * none of that, which is why a command using one had to thread `cwd`, `app` and `logLevel`
+     * through by hand at every call.
+     *
+     * ```js
+     * await context.forEachPackage(checkable, async ({ pkg, runBin }) => {
+     *   await runBin('dpdm', [...FLAGS, entry]);
+     * }, { label: 'check', parallel: args.parallel, bail: args.bail });
+     * ```
+     */
+    forEachPackage: (packages: readonly Package[], fn: RunStepFn, options?: RunService.ForEachOptions) => Promise<void>;
+    /**
+     * Runs `tasks` with at most `parallel` of them in flight - `Promise.all` under the repository's
+     * own concurrency rule.
+     *
+     * **The lower-level half, and the second thing to reach for.** It is the answer for work that is
+     * not per package (sharding a file list), and it buys nothing else: a bare list of functions
+     * carries no name, so there is no panel row to label, no package to name in a failure, and no
+     * dependency to order by. Anything per package wants `forEachPackage`.
+     *
+     * Rejects with the first failure once the tasks already started have settled, so nothing is left
+     * running behind the throw.
+     */
+    parallel: <T>(tasks: readonly (() => Promise<T>)[], options?: {
+        parallel?: boolean | number;
+    }) => Promise<T[]>;
 }
 /**
  * Which `.rmanrc` keys a command reads, for `--config` to print instead of running it - a dotted

package/core/interfaces/run-step.d.ts

@@ -62,9 +62,56 @@ export interface RunStepContext {
  * 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;
+/**
+ * One step written as an object, which is how a step says something *about itself* - today, whether
+ * it has to wait for the package's dependencies.
+ *
+ * ```yml
+ * run:
+ *   build:
+ *     before:
+ *       - { topo: false, command: eslint . }   # nothing to wait for
+ *     exec: { topo: true, command: tsc -b }    # cannot start before the dependencies are built
+ * ```
+ *
+ * `command` is the step itself and takes the same two forms the plain value does - a shell command
+ * or a function - so the object adds the marker and takes nothing away. An unknown key is refused
+ * rather than ignored.
+ */
+export interface RunStepObject {
+    /**
+     * What the step runs: a shell command, or a function ([`RunStepFn`](#RunStepFn)), exactly as the
+     * plain value form. `${{ }}` in a string is interpolated as usual.
+     *
+     * One key for both, because `run.<script>.exec` is already one key taking both - a second name
+     * for the function case would mean two spellings of one thing and a rule about which to use.
+     */
+    command?: string | RunStepFn;
+    /**
+     * Whether this step waits for every package this one depends on to finish. `true` is the useful
+     * one - a `tsc -b` cannot start before the packages it compiles against are built, while an
+     * `eslint .` beside it has nothing to wait for.
+     *
+     * **The wait is for a dependency's whole script, so the *first* `true` is where the package
+     * actually blocks.** Everything after that has its dependencies behind it already, which makes a
+     * later `topo: false` a true statement about the step that changes nothing about when it runs -
+     * worth writing as intent, not a lever.
+     *
+     * **A script whose steps mention `topo` at all is taken as the whole statement**: the first
+     * `true` is the barrier, and if no step says `true` there is no wait. A script where no step
+     * mentions it falls back to `run.<script>.topo` - on by default - waiting before its first step,
+     * which is where the wait has always been. `run.<script>.topo: false` and `--no-topo` still turn
+     * ordering off outright.
+     *
+     * Only in `run.<script>`: a `version` hook runs for one package around its own version write,
+     * with no package graph to join, and the key is refused there rather than quietly doing nothing.
+     */
+    topo?: boolean;
+}
+/** One entry of a `before`/`exec`/`after` slot: a shell command, a function, or a
+ *  [`RunStepObject`](#RunStepObject) saying something about the step. A list of them runs in
+ *  sequence, and the forms mix freely within one list. */
+export type RunStepValue = string | RunStepFn | RunStepObject;
 /**
  * A `run.<script>.if` written as JavaScript, deciding whether the script runs for this package.
  *

package/index.d.ts

@@ -66,7 +66,7 @@ export { Registry } from './core/classes/registry.js';
 export { Repository } from './core/classes/repository.js';
 export { Service, type ServiceFactory, type ServiceMap } from './core/classes/service.js';
 export { declaredTargets, type PublishTarget, shipsTo, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
-export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/interfaces/run-step.js';
+export type { RunConditionFn, RunStepContext, RunStepFn, RunStepObject, RunStepValue, } from './core/interfaces/run-step.js';
 /**
  * **`Platform` is one technology, whole**; **`Plugin` is whatever a package contributes**, platforms
  * among them.
@@ -124,6 +124,12 @@ export * from './services.js';
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
 export { applyBranchGuardOptions, assertAllowedBranch, type BranchGuardOptions, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+/**
+ * The flags every `run`-shaped command shares - `--parallel`, `--bail`, `--topo`, `--progress`,
+ * `--changed`, `--changed-since`, plus the package filters - and the reader that turns them into
+ * `RunService.Options`.
+ */
+export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from './utils/run-options.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
  *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';

package/index.js

@@ -106,6 +106,17 @@ export * from './services.js';
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
 export { applyBranchGuardOptions, assertAllowedBranch, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+/**
+ * The flags every `run`-shaped command shares - `--parallel`, `--bail`, `--topo`, `--progress`,
+ * `--changed`, `--changed-since`, plus the package filters - and the reader that turns them into
+ * `RunService.Options`.
+ */
+/* **Exported because a plugin cannot otherwise write an alias for `run <script>`.** `build` is one
+ * (`configKeys: ['run.build']`, a handler that calls `runScript`) and it reaches these through a
+ * relative import; a preset adding `compile` or `docs` had no way to, so it would restate the six
+ * flags and the reader - two lists free to disagree, which is how a flag ends up meaning one thing
+ * on `rman build` and nothing on the alias beside it. */
+export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from './utils/run-options.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
  *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';

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

@@ -1,7 +1,7 @@
 import type * as yargs from 'yargs';
 import type { RmanApplication } from '../core/application.js';
 import type { CodeSubtree } from '../core/config/config-paths.js';
-import type { CustomCommand } from '../core/interfaces/custom-command.js';
+import type { CommandContext, CustomCommand } from '../core/interfaces/custom-command.js';
 import type { Platform, Plugin } from '../core/interfaces/plugin.js';
 import type { PublishTarget } from '../core/interfaces/publish-target.js';
 import type { RunConditionFn, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
@@ -577,7 +577,16 @@ export declare namespace RmanConfig {
          * `toYargsCommand` casts the handler to yargs' own and that cast is the single place the two
          * descriptions of argv are admitted to disagree.
          */
-        handler: (argv: never) => void;
+        /**
+         * The second parameter is the [`CommandContext`](../core/interfaces/custom-command.ts) - this
+         * run's `runBin`, `logger`, `forEachPackage` and `parallel` - and is **optional**, so a command
+         * that does not take it still satisfies this.
+         *
+         * `(args, context)` is the opposite order to `CustomCommand.handler`'s `(context, args)`, and
+         * the reason is compatibility rather than taste: every declared command in existence was
+         * `handler(args)`, so appending a parameter breaks none and prepending one breaks all.
+         */
+        handler: (argv: never, context?: CommandContext) => void;
     };
     /**
      * The names a command string declares as positionals: `'run <script> [args..]'` is
@@ -783,7 +792,16 @@ export declare namespace RmanConfig {
      * (`{ [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>;
+    /**
+     * **The bare shorthand is a command, a function or a list - never a single step *object*.** At
+     * this position an object is the long form (`{ exec, before, after, topo, ... }`), so admitting a
+     * `RunStepObject` beside it would make `run: { build: { topo: true, command: 'tsc -b' } }`
+     * type-check and then do nothing: `getConfig` reads an object as the options block, finds no
+     * `exec`, and the package reports declaring no such script. A list keeps the step object
+     * (`run: { build: [{ topo: true, command: 'tsc -b' }] }`), where there is nothing to confuse it
+     * with.
+     */
+    type RunConfig = Record<string, string | RunStepFn | RunStepValue[] | RunScriptOptions>;
     interface RunScriptOptions extends RunScriptOptionsKeys, ScopedVars {
     }
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/services/changelog.service.js

@@ -600,33 +600,139 @@ function resolveFilePath(pkg, optionsFilePath) {
  */
 function partitionTargets(repository, targets, options) {
     const grouping = changelogGroupBy(repository, options);
-    const byKey = new Map();
-    for (const pkg of targets) {
-        const key = grouping === 'group' ? groupKeyOf(pkg) : `solo:${pkg.name}`;
-        const members = byKey.get(key);
-        if (members)
-            members.push(pkg);
-        else
-            byKey.set(key, [pkg]);
-    }
+    const groupFiles = grouping === 'group' ? readGroupFiles(repository, options) : {};
+    /** Checked against the **whole** repository, not against `targets`: a collision is a fact about
+     *  the configuration, and a `--scope` that happens to leave one of the two groups out must not be
+     *  what lets it through. */
+    if (grouping === 'group')
+        assertGroupFiles(repository, groupFiles, options);
     const repositoryLabel = `${path.basename(repository.dirname)} repository`;
-    return [...byKey].map(([key, members]) => {
+    return [...groupTargets(targets, grouping)].map(([key, members]) => {
         /** `targets` starts at the root, so a group holding it has it first - which is what makes the
          *  root the `home` of the default group without a second rule saying so. */
         const home = members[0];
         const grouped = !key.startsWith('solo:');
-        const named = key.startsWith('named:') ? key.slice('named:'.length) : undefined;
-        const filePkg = grouped ? repository.rootPackage : home;
+        const named = namedGroupOf(key);
         return {
             home,
-            filePkg,
+            filePkg: grouped ? repository.rootPackage : home,
             grouped,
             members: new Set(members),
             label: named ?? (home === repository.rootPackage ? repositoryLabel : home.name),
-            file: path.join(filePkg.dirname, suffixFileName(resolveFilePath(home, options.filePath), named)),
+            file: groupFile(repository, key, home, groupFiles, options),
         };
     });
 }
+/** The packages cut into what each file is about - by `.rmanrc group` under `groupBy: 'group'`, one
+ *  package each otherwise. Insertion order, so the first member of each group is the first of
+ *  `packages` to belong to it. */
+function groupTargets(packages, grouping) {
+    const byKey = new Map();
+    for (const pkg of packages) {
+        const key = grouping === 'group' ? groupKeyOf(pkg) : `solo:${pkg.name}`;
+        const members = byKey.get(key);
+        if (members)
+            members.push(pkg);
+        else
+            byKey.set(key, [pkg]);
+    }
+    return byKey;
+}
+/** `named:core` -> `core`; `undefined` for the default group and for a package that is its own. */
+function namedGroupOf(key) {
+    return key.startsWith('named:') ? key.slice('named:'.length) : undefined;
+}
+/**
+ * Where one group's changelog is written, absolute.
+ *
+ * In order: a named group listed in `changelog.groupFiles` goes where it says, relative to the
+ * repository root; any other named group takes the default file's name with its own suffixed
+ * (`CHANGELOG-core.md`), at the root; the default group takes the root's `changelog.filePath`; and a
+ * package that is a group of itself takes its own, in its own directory.
+ *
+ * **An explicit `--file-path` beats `groupFiles`**, as it already beats `changelog.filePath`: it
+ * names this run's file, and a run asking for one shape of name should not find half its groups
+ * somewhere a config put them. Named groups are still suffixed under it, so two cannot collide.
+ */
+function groupFile(repository, key, home, groupFiles, options) {
+    if (key.startsWith('solo:'))
+        return path.join(home.dirname, resolveFilePath(home, options.filePath));
+    const named = namedGroupOf(key);
+    const listed = named && !options.filePath ? groupFiles[named] : undefined;
+    if (listed)
+        return path.resolve(repository.dirname, listed);
+    return path.join(repository.dirname, suffixFileName(resolveFilePath(home, options.filePath), named));
+}
+/**
+ * `.rmanrc changelog.groupFiles`, off the repository root and nowhere else - a map from a named
+ * group to the file its changelog is written to, relative to the repository root.
+ *
+ * **The root's for the reason `groupBy` is the root's**: which file a group shares is a layout, and
+ * cascaded per package two members of one group could disagree about it, which has no answer.
+ */
+function readGroupFiles(repository, options) {
+    /** `--file-path` takes the whole decision - see `groupFile` - so the map is not even read. A
+     *  mistake in it is still a mistake, but not one this run acts on. */
+    if (options.filePath)
+        return {};
+    const declared = repository.rootPackage.config?.changelog?.groupFiles;
+    if (declared === undefined || declared === null)
+        return {};
+    if (typeof declared !== 'object' || Array.isArray(declared)) {
+        throw new Error(`.rmanrc "changelog.groupFiles" must map a group name to a file path, ` +
+            `e.g. { core: "packages/core/CHANGELOG.md" }.`);
+    }
+    for (const [group, file] of Object.entries(declared)) {
+        if (typeof file !== 'string' || !file) {
+            throw new Error(`.rmanrc "changelog.groupFiles.${group}" must be a file path, relative to the repository root.`);
+        }
+    }
+    return declared;
+}
+/**
+ * Refuses a `changelog.groupFiles` that would write somewhere wrong - before anything is written.
+ *
+ * Three ways, and each is silent otherwise:
+ *
+ * - **A key naming no group.** rman drops an unknown config key without a word, so a typo here would
+ *   leave the group on the default rule and nothing would say so. Here the groups are known, so the
+ *   key can be checked against them.
+ * - **A path leaving the repository.** `version --changelog` commits the file with the release; a
+ *   file outside the working tree is one it cannot add.
+ * - **Two groups sharing one file**, including the default group and any package that is a group of
+ *   itself. The `rman:documented-up-to` marker is one per file, so two groups writing into it would
+ *   each read the other's marker as its own boundary - entries missing or written twice, with
+ *   nothing failing. The default rule cannot produce a collision; an explicit map can, and an
+ *   unlisted group's suffixed name can land on a listed one's path.
+ */
+function assertGroupFiles(repository, groupFiles, options) {
+    const all = groupTargets([repository.rootPackage, ...repository.packages], 'group');
+    const named = [...all.keys()].map(namedGroupOf).filter((name) => !!name);
+    for (const [group, file] of Object.entries(groupFiles)) {
+        if (!named.includes(group)) {
+            throw new Error(`.rmanrc "changelog.groupFiles" names a group "${group}" that no package belongs to. ` +
+                (named.length ? `Named groups here: ${named.join(', ')}.` : 'This repository has no named groups.'));
+        }
+        const rel = path.relative(repository.dirname, path.resolve(repository.dirname, file));
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`.rmanrc "changelog.groupFiles.${group}" points outside the repository (${file}). ` +
+                `The file is committed with the release, so it has to be inside the working tree.`);
+        }
+    }
+    const owner = new Map();
+    for (const [key, members] of all) {
+        const file = groupFile(repository, key, members[0], groupFiles, options);
+        const label = namedGroupOf(key) ?? (key === 'default' ? 'the default group' : members[0].name);
+        const other = owner.get(file);
+        if (other) {
+            throw new Error(`Two changelogs would be written to one file: ${other} and ${label} both resolve to ` +
+                `${path.relative(repository.dirname, file)}.\n` +
+                `  Each file carries one "documented up to" marker, so two groups sharing it would read each ` +
+                `other's boundary. Give each its own path in .rmanrc "changelog.groupFiles".`);
+        }
+        owner.set(file, label);
+    }
+}
 /** `CHANGELOG.md` + `core` -> `CHANGELOG-core.md`, keeping whatever directory and extension
  *  `changelog.filePath` chose (`docs/HISTORY.md` -> `docs/HISTORY-core.md`). */
 function suffixFileName(filePath, suffix) {

package/services/run.service.d.ts

@@ -4,6 +4,7 @@ import { Service } from '../core/classes/service.js';
 import type { RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
 import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
  * consequences a namespace had.
@@ -17,6 +18,66 @@ export declare class RunService extends Service {
     runScript(script: string, options?: RunService.Options & {
         commandName?: string;
     }): Promise<void>;
+    /**
+     * **The scheduler, shared by every driver that runs work per package.**
+     *
+     * `runScript` is one driver and `forEachPackage` is the other; both hand over a plan per package
+     * and get the same machinery, which is the point of this being a method rather than a shape each
+     * one builds for itself. Four things have had to be fixed in it this month alone - the status
+     * region handover, the depth-counted console patch, the per-row command, the failed list - and a
+     * second copy would have needed each fix twice, with nothing reporting the one that was missed.
+     *
+     * Throws when any package failed, with `logged` set: the panel has already printed the recap.
+     */
+    protected schedule(options: {
+        panel: ProgressPanel;
+        concurrency: number;
+        /** What the panel-off log lines call this run (`run`, `build`, `check`). */
+        commandName: string;
+        /** Named in the failure thrown when a package fails - `"build" failed`. */
+        failureLabel: string;
+        /** A repo-wide bookend run first, alone, which every package then waits for. */
+        before?: RunService.PackagePlan;
+        plans: RunService.PackagePlan[];
+        /** A repo-wide bookend run last, alone, after every package. */
+        after?: RunService.PackagePlan;
+    }): Promise<void>;
+    /**
+     * Runs `fn` once per package, under the same scheduler `run` uses - concurrency, `--bail`,
+     * dependency order, the progress panel, and `console` routed to the right row.
+     *
+     * **This is what a command reaches for instead of a `for` loop.** `check` was that loop: `await
+     * runBin(...)` per package, which ignores `--parallel` outright, draws no panel, and had
+     * re-implemented `--bail`, the package filters, the two-endings rule and a summary line - about
+     * sixty lines of this service, already drifted (its own tally counted packages a bail had skipped
+     * as successes, a bug fixed here separately). Measured on `panates/opra`: nineteen packages at
+     * 0.4-0.9s each, so eleven seconds of wall clock where the work is entirely independent.
+     *
+     * `fn` is handed exactly what a **function step** gets - `pkg`, `cwd`, a `runBin` already bound to
+     * that package's directory and this run's log level, and a `logger`. That is the answer to the
+     * complaint this exists for: an imported `runBin` knows neither, and a command reaching for one
+     * had to thread `cwd`, `app` and `logLevel` through by hand at every call.
+     *
+     * Ordering is **off** unless `topo` asks for it: a command sweeping packages with an independent
+     * tool is the common case, and a wait nobody asked for is the more expensive mistake here.
+     */
+    forEachPackage(packages: readonly Package[], fn: RunStepFn, options?: RunService.ForEachOptions): Promise<void>;
+    /**
+     * Runs `tasks` with at most `parallel` of them in flight - `Promise.all` under the repository's
+     * own concurrency rule.
+     *
+     * **The low-level half of `forEachPackage`, for work that is not per package** - sharding a file
+     * list across cores, say. It buys the concurrency limit and nothing else: a bare list of functions
+     * carries no name, so there is no panel row to label, nothing to name in a failure, and no
+     * dependency to order by. That is why it is the second thing to reach for, not the first.
+     *
+     * **Settles the tasks already in flight before rejecting.** A plain `Promise.all` rejects on the
+     * first failure while its siblings keep running - with child processes behind them, that leaves
+     * output arriving after the command has reported and exited.
+     */
+    parallel<T>(tasks: readonly (() => Promise<T>)[], options?: {
+        parallel?: boolean | number;
+    }): Promise<T[]>;
 }
 export declare namespace RunService {
     export interface Options extends PackageFilterOptions {
@@ -41,6 +102,49 @@ export declare namespace RunService {
          *  root, or outside any known package. */
         fromRoot?: boolean;
     }
+    /** What `forEachPackage` takes - the scheduling half of `Options`, with no script to read it from
+     *  the config and no package filtering, which the caller has already done. */
+    export interface ForEachOptions {
+        /** Max packages at once: `true`/omitted = CPU count, a number = that many, `false` = serial. */
+        parallel?: boolean | number;
+        /** Stop the batch at the first failure. Default `true`, as `run`'s is. */
+        bail?: boolean;
+        /**
+         * Wait for a package's dependencies before running it. **Default `false`**, unlike `run`'s: a
+         * command sweeping packages with an independent tool is the common case here, and a wait nobody
+         * asked for costs the whole point of the call.
+         */
+        topo?: boolean;
+        /** Show the live progress panel. Default true; auto-disabled when stdout isn't a TTY. */
+        progress?: boolean;
+        logLevel?: LogLevel;
+        /** The panel's title, the row's step name and the word in the failure - the command's own name
+         *  (`check`) reads best. */
+        label?: string;
+    }
+    /**
+     * One package's share of a scheduled run: what to do, where, and under which rules.
+     *
+     * **The unit the scheduler takes, and why it is a package rather than a bare function.** A row has
+     * to be named for the panel to label it, for the summary to say which package failed, and for the
+     * failed list to have something to list; a dependency edge has to name a package for ordering to
+     * mean anything. A `(() => Promise<void>)[]` carries neither, which is what makes it the wrong
+     * shape for this even though it is the obvious one.
+     */
+    export interface PackagePlan {
+        pkg: Package;
+        /** The panel row's name and the task's - unique within the run, and a package's own name, which
+         *  is what lets dependency edges be handed to power-tasks as names. */
+        name: string;
+        /** What the panel-off log line calls it: the package's name, or `root` for a bookend. */
+        label: string;
+        steps: ScriptStep[];
+        /** The directory the steps run in - the package's own, or the repository root for a bookend. */
+        cwd: string;
+        topo: boolean;
+        bail: boolean;
+        logLevel: LogLevel;
+    }
     /**
      * A package's `.rmanrc` (cascaded) can configure `run.<script>.*` - e.g.
      *   run:
@@ -83,6 +187,10 @@ export declare namespace RunService {
         /** What the progress panel and the per-step log print: the command itself, or the function's
          *  own name. */
         label: string;
+        /** What a step written as an object said about waiting, `undefined` for one that said nothing -
+         *  and the three are three different answers, which is why this is not a plain boolean. See
+         *  `RunStepObject.topo`. */
+        topo?: boolean;
     }
     export interface CommandStep extends StepBase {
         command: string;
@@ -167,7 +275,9 @@ export declare namespace RunService {
      * Exported, and the only implementation: `VersionService` used to carry a second one that behaved
      * differently, which is how `version.<slot>` came to join its array with `' && '`.
      */
-    export function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
+    export function normalizeScriptValue(value: unknown, at: string, options?: {
+        topo?: boolean;
+    }): RunStepValue[];
     /**
      * Runs `fn` with `console` captured into `onLine`, and leaves the real `console` behind when the
      * last concurrent step is done.
@@ -224,6 +334,20 @@ export declare function resolveBool(cliValue: boolean | undefined, pkg: Package,
  */
 export declare function resolveBail(cliValue: boolean | undefined, pkg: Package, script: string, fallback: boolean): boolean;
 export declare function resolveNumber(cliValue: number | undefined, pkg: Package, script: string, key: string, fallback: number): number;
+/**
+ * How many packages run at once: what the flag said, or `whenUnset` where it said nothing.
+ *
+ * **`--parallel` and `concurrency` are deliberately different names**, so this is where the two
+ * meet: the flag is `boolean | number` (omit/`true` = CPU count, `false` = serially), the key is the
+ * number it resolves to. It was written out at `runScript`'s top and two more callers need the same
+ * answer - three copies of a four-branch ternary is how a flag comes to mean something slightly
+ * different depending on which command you typed.
+ *
+ * **Where the unset case comes from is the caller's**, and deliberately not read here: `run`'s is
+ * `run.<script>.concurrency`, while a command calling `forEachPackage` owns a key of its own
+ * (`check.concurrency`) that this function has no business guessing the name of.
+ */
+export declare function resolveConcurrency(parallel: boolean | number | undefined, whenUnset: number): number;
 export declare function resolveLogLevel(cliValue: LogLevel | undefined, pkg: Package, script: string, fallback: LogLevel): LogLevel;
 declare module '../core/classes/service.js' {
     interface ServiceMap {