rman 1.3.0 → 2.0.0-beta.3

package/utils/package-filter.js

@@ -1,17 +1,120 @@
 import micromatch from 'micromatch';
+/**
+ * **`--scope /` is the repository's own root package**, the one selector that is not a glob.
+ *
+ * The same `/` `.rmanrc`'s `"[/]"` block uses, and for the same reason stated there: *the root is
+ * never selected by name.* A glob matches package names, and a name can be anything - so
+ * `--scope rman-repo` happened to work (measured) while being exactly the name-based addressing the
+ * config selectors were redesigned to remove. `/` is structural, cannot collide with a package
+ * (nothing can be named it), and gives "the root" one spelling across config and CLI.
+ *
+ * Accepted by `--ignore` too. The asymmetry would be the thing to remember, and `--ignore /` -
+ * every package but the root - is a real thing to want of `clean`.
+ *
+ * **It selects nothing on a command whose candidates exclude the root**, which is most of them:
+ * `repository.packages` holds the workspace members only, so `rman list --scope /` and
+ * `rman run build --scope /` match nothing and say so. That is the honest answer rather than a
+ * special case - the root has no `list` row and contributes only `pre`/`post` bookends to `run`.
+ * `clean` and `changelog`, which put the root in their candidate list on purpose, are where it bites.
+ */
+export const ROOT_SELECTOR = '/';
+/**
+ * `--scope`/`--ignore`/`--deps`/`--dependents` as a **declaration** rather than a builder call -
+ * spread into a command's `config` block:
+ *
+ * ```ts
+ * config: { ...packageFilterOptions, ...branchGuardOptions, changelog: { ... } }
+ * ```
+ *
+ * **`satisfies`, never a `: Record<...>` annotation.** An annotation widens `type: 'string'` back to
+ * `string`, and every type derived from the declaration - the config contribution, the option's own
+ * value type - collapses with it. `satisfies` checks the shape and keeps the literals, and it also
+ * catches a misspelled key *here*, at the group's own line, rather than in the ten commands that
+ * spread it. The `Argv` chaining this replaces could not: a typo there was simply a new option.
+ *
+ * **Every option is `target: 'cli'`, including the ones that have a config twin.** A shared group
+ * belongs to no command, so declaring one `'both'` would contribute `version.scope` - a key nothing
+ * reads. Where a `.rmanrc` equivalent exists it is a core key in its own right (`allowBranch`), and
+ * a command that reads it names it in `configKeys`.
+ */
+export const packageFilterOptions = {
+    scope: {
+        target: 'cli',
+        describe: 'Only include packages whose name matches this glob, or "/" for the root package (repeatable)',
+        // Deliberately 'string', not 'array': an array-typed option greedily swallows every
+        // following bare word as its own value, which would eat "exec"'s [command..] positional
+        // whole. yargs still collects repeated "--scope a --scope b" into an array either way.
+        type: 'string',
+    },
+    ignore: {
+        target: 'cli',
+        describe: 'Exclude packages matching this glob (or "/" for the root) - applied after --scope',
+        type: 'string',
+    },
+    platform: {
+        target: 'cli',
+        describe: 'Only include packages of these platforms, e.g. --platform=node,cargo (repeatable)',
+        type: 'string',
+    },
+    deps: {
+        target: 'cli',
+        describe: 'Also include every package the matched set depends on',
+        type: 'boolean',
+    },
+    dependents: {
+        target: 'cli',
+        describe: 'Also include every package that depends on the matched set',
+        type: 'boolean',
+    },
+};
+/**
+ * `--from-root`/`-r` - a group of one, and a function because its text is the command's own word
+ * for what it does. Spread it like the others: `...fromRootOption('Build')`.
+ *
+ * Only where a command scopes by the current directory; see `applyFromRootOption` for why adding it
+ * elsewhere is worse than leaving it out.
+ *
+ * **It was `--root` through 1.x, and the name said the opposite of what it does.** Every reader
+ * spells it the same single line - `options.fromRoot ? undefined : repository.currentPackage` - so
+ * the flag means *ignore where I am standing*, i.e. the **whole repository**. `--root` reads as "the
+ * root alone", which is the narrowest possible set rather than the widest, and the confusion was
+ * about to become a contradiction: a `--root-only` beside a `--root` that meant "everything" is
+ * unreadable.
+ *
+ * **`-r` is kept, and a two-letter `-fr` is not possible.** yargs' `short-option-groups` is on by
+ * default, so `-fr` parses as `-f -r` and `.strict()` answers `Unknown arguments: f, r` (measured).
+ * Turning that off makes `-fr` work and breaks every grouped short - `rman list -sj` works today.
+ * So the long name carries the meaning and the incumbent short stays.
+ */
+export function fromRootOption(verb) {
+    return {
+        fromRoot: {
+            target: 'cli',
+            cliName: 'from-root',
+            alias: 'r',
+            describe: `${verb} across the whole repository even when the current directory is inside a single ` +
+                'package (which otherwise scopes it to just that package). No effect elsewhere.',
+            type: 'boolean',
+        },
+    };
+}
 /** `--scope`/`--ignore`/`--deps`/`--dependents`, the same shape and describe text in every command
  *  that supports them - mirrors `run.command.ts`'s own `applyRunOptions`. */
 export function applyPackageFilterOptions(cmd) {
     return cmd
         .option('scope', {
-        describe: 'Only include packages whose name matches this glob (repeatable)',
+        describe: 'Only include packages whose name matches this glob, or "/" for the root package (repeatable)',
         // Deliberately 'string', not 'array': an array-typed option greedily swallows every
         // following bare word as its own value, which would eat "exec"'s [command..] positional
         // whole. yargs still collects repeated "--scope a --scope b" into an array either way.
         type: 'string',
     })
         .option('ignore', {
-        describe: 'Exclude packages whose name matches this glob (repeatable) - applied after --scope',
+        describe: 'Exclude packages matching this glob (or "/" for the root) - applied after --scope',
+        type: 'string',
+    })
+        .option('platform', {
+        describe: 'Only include packages of these platforms, e.g. --platform=node,cargo (repeatable)',
         type: 'string',
     })
         .option('deps', {
@@ -27,6 +130,8 @@ export function readPackageFilterOptions(args) {
     return {
         scope: args.scope,
         ignore: args.ignore,
+        platform: args.platform,
+        commandPlatforms: args.commandPlatforms,
         deps: args.deps,
         dependents: args.dependents,
     };
@@ -34,7 +139,8 @@ export function readPackageFilterOptions(args) {
 /**
  * Narrows `packages` (the full, already-resolved list - toposort order, if any, is preserved)
  * down to what `options` selects. `scope`/`ignore` match against each package's bare name (glob
- * syntax via `micromatch` - `*`, `**`, `{a,b}`, ...); `ignore` is applied after `scope`, on
+ * syntax via `micromatch` - `*`, `**`, `{a,b}`, ...), plus `ROOT_SELECTOR` (`"/"`) for the root
+ * package, which is matched structurally rather than by name; `ignore` is applied after `scope`, on
  * whatever it left. `deps`/`dependents` then each independently expand *that* matched set along
  * `Package.dependencies` (already the full transitive closure - see
  * `Repository`'s own `_updateDependencies`) and their results are unioned in - so `--deps
@@ -57,12 +163,22 @@ export function filterPackages(packages, options,
 applySkip = true) {
     let matched = applySkip ? packages.filter(p => p.config?.skip !== true) : packages;
     if (options.scope) {
-        const patterns = toArray(options.scope);
-        matched = matched.filter(p => micromatch.isMatch(p.name, patterns));
+        const selects = selector(options.scope);
+        matched = matched.filter(p => selects(p));
     }
     if (options.ignore) {
-        const patterns = toArray(options.ignore);
-        matched = matched.filter(p => !micromatch.isMatch(p.name, patterns));
+        const selects = selector(options.ignore);
+        matched = matched.filter(p => !selects(p));
+    }
+    /** The command's own technologies, before the user's `--platform`: a declaration is the hard
+     *  limit and the flag narrows inside it. Silent where `--platform` is loud - see the field. */
+    if (options.commandPlatforms?.length) {
+        const wanted = new Set(options.commandPlatforms.map(n => n.toLowerCase()));
+        matched = matched.filter(p => wanted.has(p.provider.toLowerCase()));
+    }
+    if (options.platform !== undefined) {
+        const wanted = platformNames(options.platform, packages);
+        matched = matched.filter(p => wanted.has(p.provider.toLowerCase()));
     }
     if (!options.deps && !options.dependents)
         return matched;
@@ -83,11 +199,8 @@ applySkip = true) {
     }
     return packages.filter(p => included.has(p));
 }
-function toArray(value) {
-    return Array.isArray(value) ? value : [value];
-}
 /**
- * `--root`/`-r`, with one describe text instead of four near-identical ones.
+ * `--from-root`/`-r`, with one describe text instead of four near-identical ones.
  *
  * **It only means anything where a command scopes by the current directory** - `run`/`build`/`test`,
  * `exec`, `clean`, `changelog` and `diff` narrow to `Repository.currentPackage` when you stand
@@ -95,19 +208,94 @@ function toArray(value) {
  * repository (`version`, `publish`, `list`, `changed`) it would be a flag that does nothing, which
  * is worse than not offering it: a no-op flag reads as a promise.
  *
+ * That same rule is why there is no `--root-only` beside it, however naturally the pair reads: it
+ * would be a no-op on `run`/`build`/`test` (the root is not in `repository.packages` at all and
+ * contributes only `pre`/`post` bookends), identical to this flag on `diff`, already what this flag
+ * does on `config`, and on `clean` actively misleading - the root's own sweep recurses through
+ * `packages/*`, so a `--root-only` there deletes *more* than a package-scoped run, not less
+ * (measured). Where the root genuinely is a candidate, `--scope /` says so - see `ROOT_SELECTOR`.
+ *
  * `verb` is the command's own word for what it does, so the text stays the sentence each command was
  * already saying.
  */
-export function applyRootOption(cmd, verb) {
-    return cmd.option('root', {
+export function applyFromRootOption(cmd, verb) {
+    return cmd.option('from-root', {
         alias: 'r',
         describe: `${verb} across the whole repository even when the current directory is inside a single ` +
             'package (which otherwise scopes it to just that package). No effect elsewhere.',
         type: 'boolean',
     });
 }
-/** The `--root` flag as the services read it - beside `readPackageFilterOptions`, so a command
+/** The `--from-root` flag as the services read it - beside `readPackageFilterOptions`, so a command
  *  reads both the same way. */
-export function readRootOption(args) {
-    return args.root;
+export function readFromRootOption(args) {
+    return args.fromRoot;
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * One `--scope`/`--ignore` value list as a predicate, with `ROOT_SELECTOR` lifted out of the globs.
+ *
+ * Split once rather than per package. The root is answered by `wantsRoot` alone and everything else
+ * by the globs, so the two never consult each other - and `micromatch` is asked only when a glob is
+ * left, since an empty pattern list must match no member rather than all of them, which is what
+ * makes a bare `--scope /` select the root **and nothing else**.
+ *
+ * **A glob is never offered the root**, which is the other half of `ROOT_SELECTOR` and the reason it
+ * is not merely a second spelling. `.rmanrc`'s selectors state the same rule - `"[my-*]"` cannot
+ * pick up a repository whose root package is called `my-repo`, and `"[*]"` means the members - and
+ * the CLI disagreed with it: measured, `rman clean --scope 'rman*'` selected this repository's root.
+ * For `clean` that is destructive rather than merely surprising, since the root's own sweep recurses
+ * through `packages/*`. Globs are the members, `/` is the root, in both vocabularies.
+ */
+/**
+ * `--platform` as a set of lower-cased names, refusing one no package in the repository belongs to.
+ *
+ * **Comma-split, unlike `--scope`, and the asymmetry is the values' own.** A platform's name is a
+ * short identifier a plugin chose, so `--platform=node,cargo` cannot be ambiguous; a scope glob is
+ * arbitrary text, where splitting would take a character away from the pattern language. Repeating
+ * the flag works for both.
+ *
+ * **An unknown name is an error, where an unmatched `--scope` glob is not**, and the difference is
+ * whether rman knows the answer set. It does here: the platforms are the ones its packages belong
+ * to, so `--platform crago` is a typo rman can see, and left alone it is the silent empty result
+ * this whole codebase keeps ruling out. The message lists what the repository has - the same call
+ * `publish --target` makes against its registry.
+ *
+ * **Compared case-insensitively.** `Platform.name` is the authority on spelling and `--platform Node`
+ * is not a different request; refusing it would be pedantry with an empty result attached.
+ *
+ * Asked of the packages rather than of `app.platforms`, which `filterPackages` does not have and
+ * which would be the wrong set anyway: a registered platform that claimed no directory is not an
+ * answer to "what is in this repository".
+ */
+function platformNames(value, packages) {
+    const wanted = toArray(value)
+        .flatMap(entry => entry.split(','))
+        .map(name => name.trim().toLowerCase())
+        .filter(Boolean);
+    /** An empty `provider` is a package no technology claimed, and there is no spelling for it - a
+     *  flag selecting "none" would be `--platform ''`, which no shell makes pleasant. Left out of the
+     *  known set, so naming it is refused like any other unknown. */
+    const present = new Set(packages.map(p => p.provider.toLowerCase()).filter(Boolean));
+    for (const name of wanted) {
+        if (present.has(name))
+            continue;
+        throw new Error(`--platform "${name}" matches no package in this repository. ` +
+            (present.size
+                ? `It holds: ${[...present].sort().join(', ')}.`
+                : 'No package here belongs to a platform - its ".rmanrc" names no "plugins".'));
+    }
+    return new Set(wanted);
+}
+function selector(value) {
+    const patterns = toArray(value);
+    const wantsRoot = patterns.includes(ROOT_SELECTOR);
+    const globs = patterns.filter(p => p !== ROOT_SELECTOR);
+    /** Against `pkg.selector`, which is what `.rmanrc`'s `"[glob]"` matches - one vocabulary, as the
+     *  `/` above already is. It was `pkg.name`, and the two coincide for every Node repository; a
+     *  package having a name at all is an ecosystem's promise, and a repository can assign a selector
+     *  where its own does not offer one. */
+    return pkg => (pkg.isRoot ? wantsRoot : globs.length > 0 && micromatch.isMatch(pkg.selector, globs));
 }

package/utils/printable-config.d.ts

@@ -5,7 +5,7 @@
  * Needed because a config legitimately holds functions now: a `run.<script>` or `version.<slot>`
  * step written as JavaScript, and an `if` written the same way. It was already needed before that,
  * though, which is the better argument for doing it here rather than at one call site - a
- * `plugins` entry given in its object form carries the plugin's seams, and `rman config --root`
+ * `plugins` entry given in its object form carries the plugin's seams, and `rman config --from-root`
  * died on one with `unacceptable kind of an object to dump [object Function]` (measured, on a
  * repository whose shared config did nothing more unusual than `extends` a plugin package).
  *
@@ -13,3 +13,11 @@
  * reads as `[Function]`, which is itself worth seeing.
  */
 export declare function printableConfig<T>(config: T): T;
+/**
+ * A resolved config with the **contribution keys** dropped - `plugins`, `platforms`, `commands`,
+ * `publishTargets` - for `rman config` and `--config`, which exist to show what a repository is
+ * *configured* to do.
+ *
+ * Returns a copy; the config itself is what every command reads and is never touched.
+ */
+export declare function withoutContributions<T extends object>(config: T): T;

package/utils/printable-config.js

@@ -1,3 +1,4 @@
+import { CODE_SUBTREES } from '../core/config/config-paths.js';
 /**
  * A copy of a resolved config with every value a serializer cannot represent replaced by a short
  * description of it - for `rman config` and `--config`, which exist to be *looked at*.
@@ -5,7 +6,7 @@
  * Needed because a config legitimately holds functions now: a `run.<script>` or `version.<slot>`
  * step written as JavaScript, and an `if` written the same way. It was already needed before that,
  * though, which is the better argument for doing it here rather than at one call site - a
- * `plugins` entry given in its object form carries the plugin's seams, and `rman config --root`
+ * `plugins` entry given in its object form carries the plugin's seams, and `rman config --from-root`
  * died on one with `unacceptable kind of an object to dump [object Function]` (measured, on a
  * repository whose shared config did nothing more unusual than `extends` a plugin package).
  *
@@ -15,6 +16,50 @@
 export function printableConfig(config) {
     return walk(config, new WeakSet());
 }
+/**
+ * A resolved config with the **contribution keys** dropped - `plugins`, `platforms`, `commands`,
+ * `publishTargets` - for `rman config` and `--config`, which exist to show what a repository is
+ * *configured* to do.
+ *
+ * Returns a copy; the config itself is what every command reads and is never touched.
+ */
+/* **Those four are code, not settings** (`CODE_SUBTREES`), and printing them answers a question
+ * nobody asked: a platform dumps its manifest provider and version planner, a publish target its
+ * whole option table, and `commands` comes out as a list of `[Function]` - which is the clearest
+ * evidence of all that they do not belong in this output. Measured on this repository, where
+ * `rman config` printed forty lines of the npm target's flags above the two keys its `.rmanrc`
+ * actually sets.
+ *
+ * **And silently, which was argued the other way first.** The note that announced them read as the
+ * sibling of the `version.<slot>` one, and it is not: that note explains a *visible* oddity - an
+ * unresolved `${{ }}` sitting among resolved values, which without it reads as interpolation being
+ * broken - while this one announced an absence the reader was not looking for. The measurement that
+ * settled it: presets go under every root, so every config carries all four and the note was
+ * printed **every time**, which makes it a banner rather than a report. At this repository's root
+ * it was one of three lines. A reader asking which technologies are loaded is asking `rman info`,
+ * and one asking whether their command registered is asking `rman --help`.
+ *
+ * **`CODE_SUBTREES` itself, not a second copy of those four names.** `config-paths.ts` imports
+ * nothing, so there is no cycle to buy by reaching for it - and a printer quietly keeping its own
+ * list is how a key added to one side stops being dropped by the other. That exact shape was live
+ * in this tree an hour earlier: `presetNames()` held a hardcoded `['node']` beside a resolver that
+ * looked somewhere else, and the error message named the preset it had just failed to find.
+ *
+ * **Top level only, matching the runtime rule** (`ConfigInterpolator._isCodePath` checks
+ * `segments[0]`). `Resolved` skips these names at *every* level because the selector index
+ * re-enters the config, and the two have disagreed since - this is not the place to pick a side,
+ * and stripping them deeper would hide a script that happens to be called `commands`. By the time
+ * either printer runs the selector blocks are merged in anyway, so there is no deeper one to find.
+ *
+ * **Distinct from `printableConfig`, which makes a value serializable rather than deciding what is
+ * worth showing.** A step written as a function still prints as `[Function: copyDocs]` - that one
+ * *is* a setting. */
+export function withoutContributions(config) {
+    const result = { ...config };
+    for (const key of CODE_SUBTREES)
+        delete result[key];
+    return result;
+}
 function walk(value, seen) {
     if (typeof value === 'function')
         return `[Function${value.name ? `: ${value.name}` : ''}]`;

package/utils/progress-panel.d.ts

@@ -6,6 +6,15 @@ export interface ProgressItem {
     /** Label of the step currently running, for work with more than one step (e.g. `run`'s
      *  npm-script steps) - omit `stepsTotal` entirely for single-step work like a plain command. */
     currentStep?: string;
+    /**
+     * **What the current step actually runs** - the shell command, or a function step's name - shown
+     * beside the label so a silent step says what it is.
+     *
+     * The label alone answers "which slot", which is what a reader already knows; a step sitting at
+     * `before (2/9)` for ten seconds with nothing on stdout is the case this exists for, and it is
+     * the common one for a build.
+     */
+    currentCommand?: string;
     stepIndex?: number;
     stepsTotal?: number;
     /** Last captured output line, shown dimmed under the item while it's running. */

package/utils/progress-panel.js

@@ -76,7 +76,15 @@ export class ProgressPanel {
             const step = item.stepsTotal && item.stepsTotal > 1 && item.stepIndex != null
                 ? `${item.currentStep} (${item.stepIndex + 1}/${item.stepsTotal})`
                 : item.currentStep || '';
-            const group = [`${spinner} ${colors.bold(item.name)}  ${colors.gray(step)}  ${colors.yellow(elapsed)}`];
+            /** Measured against the *plain* text: every piece below is wrapped in escape sequences, and
+             *  `String.length` counts those, so budgeting on the rendered string wraps a row that fits. */
+            const fixed = `  ${item.name}  ${step}  ${elapsed}`.length;
+            const command = truncate(item.currentCommand ?? '', (process.stdout.columns || 80) - fixed - 2);
+            const group = [
+                `${spinner} ${colors.bold(item.name)}  ${colors.gray(step)}` +
+                    (command ? `  ${colors.cyan(command)}` : '') +
+                    `  ${colors.yellow(elapsed)}`,
+            ];
             if (item.lastLine)
                 group.push(`    ${colors.dim(item.lastLine)}`);
             if (used + group.length > budget)
@@ -141,6 +149,20 @@ export class ProgressPanel {
         return { successCount, failedCount, skippedCount };
     }
 }
+/**
+ * `text` cut to `width`, with a `…` in place of what was dropped.
+ *
+ * **Cut from the end, not the middle.** A command's information is front-loaded - `tsc -b
+ * packages/rman/tsconfig.json` says what it is in the first four characters, and a middle-ellipsis
+ * spends them on a tail nobody is reading at a glance. The one thing it must never do is wrap: a
+ * block taller than the terminal breaks the panel's cursor-up arithmetic, which is the same reason
+ * the row budget above exists.
+ */
+function truncate(text, width) {
+    if (!text || width <= 1)
+        return '';
+    return text.length <= width ? text : `${text.slice(0, width - 1)}…`;
+}
 /** Classic braille "dots" spinner (cli-spinners' default), one frame per render tick. */
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 function renderProgressBar(done, total, width = 24) {

package/utils/release-version.d.ts

@@ -1,4 +1,4 @@
-import type { Package } from '../core/package.js';
+import type { Package } from '../core/classes/package.js';
 import type { GitHelper } from './git.js';
 /**
  * A calendar release version: `YYYY.M.D-HHmm`, every part **unpadded** (`2026.9.5-930`, not

package/utils/run-bin.d.ts

@@ -1,5 +1,15 @@
+import type { RmanApplication } from '../core/application.js';
 import { type LogLevel } from './logger.js';
 export interface RunBinOptions {
+    /**
+     * The application whose technologies put a repository's locally installed binaries on PATH -
+     * `node_modules/.bin` for a Node repository, whatever another technology uses.
+     *
+     * Passed rather than looked up, so a command run against one repository can never pick up the
+     * binaries of another in the same process. Omitted (a caller outside any repository) leaves the
+     * inherited PATH exactly as it was, which is also what a repository naming no plugin gets.
+     */
+    app?: RmanApplication;
     /** Where to run it, and the directory `node_modules/.bin` is resolved from. Default `process.cwd()`. */
     cwd?: string;
     /** 'inherit' streams the child's output straight to the terminal; 'pipe' captures it and resolves

package/utils/run-bin.js

@@ -34,7 +34,7 @@ export async function runBin(bin, argv, options = {}) {
     const child = spawn(process.platform === 'win32' ? `${bin}.cmd` : bin, argv, {
         cwd,
         stdio: stdio === 'inherit' ? 'inherit' : 'pipe',
-        env: BinPath.env({ cwd, env: options.env }),
+        env: BinPath.env({ cwd, env: options.env, app: options.app }),
         windowsHide: true,
     });
     /** So an interrupted rman does not leave this running - `exec` always did this and this did not,

package/utils/run-options.d.ts

@@ -0,0 +1,97 @@
+import type { RunService } from '../services/run.service.js';
+/**
+ * Everything `run`, `build` and `test` accept - the package filter, the branch guard, `--from-root`, and
+ * the scheduling flags on top.
+ *
+ * **In `utils/` rather than in `run.command.ts`, which is where the `Argv` version lived.** `build`
+ * and `test` had to import it from a sibling command, which reads as a dependency between commands
+ * and is not one: they share a declaration, the way they already share `packageFilterOptions`.
+ *
+ * Every option is `target: 'cli'`. The `.rmanrc` half of these lives at `run.<script>.concurrency`,
+ * `.bail`, `.topo`, `.progress` - keyed by script name, so it is the one config shape that cannot be
+ * derived from a flat option map and stays hand-written in `RmanConfig`.
+ */
+export declare const runOptions: {
+    parallel: {
+        target: "cli";
+        describe: string;
+        /** No `type`: the flag takes a boolean *or* a number, and `coerce` is what says so - which is
+         *  also where `OptionValue` reads this option's type from. */
+        coerce: (v: unknown) => boolean | number | undefined;
+    };
+    bail: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    topo: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    progress: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    changed: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changedSince: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+        /** Declared on the option rather than as a separate `.conflicts()` call - one place says what
+         *  this flag is and what it cannot be combined with. */
+        conflicts: string;
+    };
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+export declare function readRunOptions(args: any): RunService.Options;

package/utils/run-options.js

@@ -0,0 +1,81 @@
+import { branchGuardOptions } from './branch-guard.js';
+import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from './package-filter.js';
+/**
+ * Everything `run`, `build` and `test` accept - the package filter, the branch guard, `--from-root`, and
+ * the scheduling flags on top.
+ *
+ * **In `utils/` rather than in `run.command.ts`, which is where the `Argv` version lived.** `build`
+ * and `test` had to import it from a sibling command, which reads as a dependency between commands
+ * and is not one: they share a declaration, the way they already share `packageFilterOptions`.
+ *
+ * Every option is `target: 'cli'`. The `.rmanrc` half of these lives at `run.<script>.concurrency`,
+ * `.bail`, `.topo`, `.progress` - keyed by script name, so it is the one config shape that cannot be
+ * derived from a flat option map and stays hand-written in `RmanConfig`.
+ */
+export const runOptions = {
+    ...packageFilterOptions,
+    ...branchGuardOptions,
+    ...fromRootOption('Run'),
+    parallel: {
+        target: 'cli',
+        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.',
+        /** No `type`: the flag takes a boolean *or* a number, and `coerce` is what says so - which is
+         *  also where `OptionValue` reads this option's type from. */
+        coerce: (v) => {
+            if (v === undefined)
+                return undefined;
+            if (v === 'false' || v === false)
+                return false;
+            if (v === 'true' || v === true)
+                return true;
+            const n = Number(v);
+            return Number.isFinite(n) ? n : true;
+        },
+    },
+    bail: {
+        target: 'cli',
+        describe: 'Stop on first failure (default: true, overridable per-package via .rmanrc run.<script>.bail)',
+        type: 'boolean',
+    },
+    topo: {
+        target: 'cli',
+        describe: 'Respect package dependency order: a package waits for its dependencies and is skipped if one ' +
+            'fails. Set false for independent scripts (e.g. lint/test) - order becomes alphabetical and ' +
+            'failures never skip other packages. Default: true, overridable per-package via .rmanrc run.<script>.topo.',
+        type: 'boolean',
+    },
+    progress: {
+        target: 'cli',
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY; .rmanrc run.<script>.progress)',
+        type: 'boolean',
+    },
+    changed: {
+        target: 'cli',
+        alias: 'c',
+        describe: 'Only run in packages you have touched but not pushed - uncommitted, or committed and not yet on the upstream branch. Not a release question; see "version --json" for that',
+        type: 'boolean',
+    },
+    changedSince: {
+        target: 'cli',
+        cliName: 'changed-since',
+        describe: 'Only run in packages that have changed since the given git commit/hash',
+        type: 'string',
+        /** Declared on the option rather than as a separate `.conflicts()` call - one place says what
+         *  this flag is and what it cannot be combined with. */
+        conflicts: 'changed',
+    },
+};
+export function readRunOptions(args) {
+    return {
+        ...readPackageFilterOptions(args),
+        parallel: args.parallel,
+        topo: args.topo,
+        bail: args.bail,
+        progress: args.progress,
+        changed: args.changed,
+        changedSince: args.changedSince,
+        logLevel: args.logLevel,
+        fromRoot: args.fromRoot,
+    };
+}