rman 1.3.0 → 2.0.0-beta.2

package/utils/package-filter.d.ts

@@ -6,10 +6,29 @@ import type { Package } from '../core/package.js';
  *  `.rmanrc "skip"`, is applied by `filterPackages` itself rather than being an option here: it is
  *  the repository's statement, not the caller's. */
 export interface PackageFilterOptions {
-    /** Only include packages whose name matches at least one of these globs (e.g. `@scope/*`). */
+    /** Only include packages whose name matches at least one of these globs (e.g. `@scope/*`), or
+     *  **`"/"`** for the repository's own root package - see `ROOT_SELECTOR`. */
     scope?: string | string[];
-    /** Exclude packages whose name matches at least one of these globs - applied after `scope`. */
+    /** Exclude packages whose name matches at least one of these globs (or `"/"`) - applied after
+     *  `scope`. */
     ignore?: string | string[];
+    /**
+     * Only include packages belonging to one of these **platforms** (`Package.provider`) - `['node']`,
+     * or `'node,cargo'` as one comma-separated value.
+     *
+     * **Which technology a package belongs to only became a per-package question when the walk
+     * started finding nested packages of another platform**, and this is the filter that question
+     * needs: in a polyglot repository `rman run build --platform node` is the whole npm half of it,
+     * and there was no way to say that. Where every package is one technology it selects everything
+     * or nothing, which is the honest answer rather than a flag that does nothing.
+     *
+     * **Names, not globs.** A platform's name is a short identifier a plugin chose (`'node'`), so the
+     * set of valid values is known and finite - which is also why a name that no package in the
+     * repository belongs to is an **error** listing the ones that are there, the same call
+     * `publish --target` makes. A glob would put this back to guessing, and a typo back to a silent
+     * empty result.
+     */
+    platform?: string | string[];
     /** Also include every package the matched set depends on (transitively) - e.g. to build
      *  everything a scoped app actually needs. */
     deps?: boolean;
@@ -17,6 +36,99 @@ export interface PackageFilterOptions {
      *  everything that could be affected by a scoped library's change. */
     dependents?: boolean;
 }
+/**
+ * **`--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 declare 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 declare const packageFilterOptions: {
+    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";
+    };
+};
+/**
+ * `--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 declare function fromRootOption(verb: string): {
+    fromRoot: {
+        target: "cli";
+        cliName: string;
+        alias: string;
+        describe: string;
+        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 declare function applyPackageFilterOptions<T>(cmd: Argv<T>): Argv<T>;
@@ -24,7 +136,8 @@ export declare function readPackageFilterOptions(args: any): PackageFilterOption
 /**
  * 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
@@ -46,7 +159,7 @@ export declare function filterPackages(packages: Package[], options: PackageFilt
  */
 applySkip?: boolean): Package[];
 /**
- * `--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
@@ -54,10 +167,17 @@ applySkip?: boolean): Package[];
  * 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 declare function applyRootOption<T>(cmd: Argv<T>, verb: string): Argv<T>;
-/** The `--root` flag as the services read it - beside `readPackageFilterOptions`, so a command
+export declare function applyFromRootOption<T>(cmd: Argv<T>, verb: string): Argv<T>;
+/** The `--from-root` flag as the services read it - beside `readPackageFilterOptions`, so a command
  *  reads both the same way. */
-export declare function readRootOption(args: any): boolean | undefined;
+export declare function readFromRootOption(args: any): boolean | undefined;

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,7 @@ export function readPackageFilterOptions(args) {
     return {
         scope: args.scope,
         ignore: args.ignore,
+        platform: args.platform,
         deps: args.deps,
         dependents: args.dependents,
     };
@@ -34,7 +138,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 +162,16 @@ 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));
+    }
+    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 +192,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 +201,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).
  *

package/utils/printable-config.js

@@ -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).
  *

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;