rman 2.0.0-beta.3 → 2.0.0-beta.5

package/README.md

@@ -94,17 +94,30 @@ worked examples of every single command, see **[docs/cli-rman.md](https://github
 | [`import <path>`](#rman-import-path) | Imports an external git repository as a new package, with history. |
 
 **`ci` and `clean` come from the `node` built-in**, which ships inside this package - each is about
-npm or TypeScript rather than about repositories, so nothing it contributes exists until a
-repository asks for it:
+npm or TypeScript rather than about repositories. It needs no declaration: rman lays its own `node`
+preset under every repository, so a clone with no `.rmanrc` at all already has them, plus the `node`
+technology itself and the npm publish target. It used to take a second package (`rman-node`) and a
+`.rmanrc` before anything worked.
+
+A preset is an ordinary rman config rather than a type of its own, so another technology arrives the
+same way and a polyglot repository asks for both:
+
+```yaml
+extends: ['rman:node', 'rman:cargo']
+```
+
+**`plugins: ['node']` is not a way to name a technology and is refused**, with a message saying so.
+That key takes a plugin instance or a glob naming modules that export one; a name is what `extends`
+resolves. The keys that do exist:
 
 ```yaml
-plugins: ['node']   # by name
-platform: node      # the same statement at a repository root, plus which technology its packages are
+platform: node      # which technology claims *this directory* - it does not load anything
+platforms: [...]    # contributes technologies: an instance, or a glob naming modules exporting one
 ```
 
-Or say nothing: a repository that declares no technology gets the one its own files imply, announced
-on stderr rather than guessed silently. It used to take a second package (`rman-node`) and a
-`.rmanrc` before anything worked at all.
+Whatever a repository declares is asked about a directory **before** the default preset, so
+`extends: 'rman:cargo'` in a root holding both a `Cargo.toml` and a tooling `package.json` resolves
+to what it declared.
 
 **`publish` is here, but *where* a package ships is a plugin's to say.** A **publish target** is
 one answer to "is this version on the registry, and how do I push it" - rman ships `docker`

package/builtins/platforms/node/node-config.interface.d.ts

@@ -48,6 +48,19 @@ export declare namespace RmanNodeConfig {
          *  Publishing from such a directory means the manifest there is **generated by `publish`**,
          *  from the package's own - see `PublishService`. There is nothing to configure about it. */
         directory?: ConfigValue<string>;
+        /**
+         * Publish into npm's **staging queue** (`npm stage publish`) instead of straight to the
+         * registry: the version is held pending until a maintainer approves it with `npm stage approve`,
+         * which is the step that carries the 2FA challenge.
+         *
+         * Per package like every other key here, so a repository can stage the one package that matters
+         * and publish the rest directly.
+         *
+         * Requires npm >= 11.15.0 and Node >= 22.14.0 on whatever runs the publish. rman does not check
+         * either: the version that matters is the runner's, not the one resolving the config, and npm's
+         * own "Unknown command: stage" is a better message than a guess made somewhere else.
+         */
+        staged?: ConfigValue<boolean>;
     }
 }
 /**

package/builtins/platforms/node/services/publish.service.d.ts

@@ -32,6 +32,17 @@ export declare namespace PublishService {
          * a release pipeline gates on both show where a version is going.
          */
         tag?: string;
+        /**
+         * `npm stage publish` instead of `npm publish` - the version goes into npm's staging queue and
+         * is not on the registry until a maintainer runs `npm stage approve`, which is where the 2FA
+         * challenge moves to. `false` forces a direct publish even where the config asks for staging;
+         * `undefined` leaves the decision to each package's `.rmanrc "publish.npm.staged"`.
+         *
+         * **A plan option, for the same reason `tag` is one**: what a run is about to do is the thing a
+         * reader confirms and a pipeline gates on, and "this release will not be live when the workflow
+         * goes green" is the most important sentence in the plan when it applies.
+         */
+        staged?: boolean;
     }
     interface ApplyOptions extends Options {
         packageManager?: CiService.PackageManager;
@@ -63,6 +74,21 @@ export declare namespace PublishService {
          * says; recomputing at publish time would let the two disagree about where a package is going.
          */
         distTag?: string;
+        /**
+         * Whether this entry goes into npm's staging queue rather than straight to the registry -
+         * `--staged`, or the package's own `.rmanrc "publish.npm.staged"`.
+         *
+         * Decided in the plan and read back by `applyPlan`, exactly as `distTag` is: a plan that said
+         * "staged" while the command published directly would be the one disagreement that cannot be
+         * undone, since a live version cannot be unpublished after 72 hours.
+         *
+         * **A staged entry still reads `publish`, not a status of its own**, and that is a limitation
+         * rather than a decision: rman's question is "is this version on the registry", and a pending
+         * version is not - `npm view` does not report the queue. So a second run proposes the same
+         * package again, and whether npm accepts a duplicate stage is npm's answer to give, not rman's
+         * to guess. Watch this if a run is ever repeated before an approval.
+         */
+        staged?: boolean;
         /** `PublishTarget.Entry`'s own field - what the core's `publish` prints beside the package
          *  name. Carries the dist-tag, so where a version is going is visible in the plan and in
          *  `--dry-run --json` without the core knowing anything about npm. */

package/builtins/platforms/node/services/publish.service.js

@@ -72,8 +72,14 @@ function preparePublishManifest(pkg, publishDir, packagesByName) {
  *   builds a native module on install. The rest (`build`, `test`, `prepare`, ...) never reach the
  *   consumer - `prepare` runs for a git dependency, which builds from the repository, not from this
  *   tarball.
- * - `private` - rman refuses to publish a private package in the first place, so carrying the flag
- *   into a manifest that is being published can only be wrong.
+ * - `private` - it is a statement about the **source tree**, not about the artifact derived from it,
+ *   and a manifest being published is by definition not private. rman's own gate normally stops a
+ *   private package before this runs, so the line looks unreachable; it is not, because `private`
+ *   is also how a repository keeps a stray `npm publish` out of the package directory while
+ *   publishing `build/` on purpose. That is a real configuration - this repository ran it until
+ *   `rman publish` became its own release path and the gate started refusing the thing it ships.
+ *   A narrower guard (`prepublishOnly`, which never reaches a consumer either) says the same thing
+ *   without claiming the artifact is unpublishable.
  * - `publishConfig.directory` - it pointed *here*; kept, it would point one level deeper again.
  */
 function derivePublishManifest(pkg, packagesByName) {
@@ -201,14 +207,20 @@ export var PublishService;
              *  out. Asking it kept proposing an already-published version until npm answered 403. */
             const published = !!view?.versions.includes(pkg.version);
             const distTag = distTagFor(pkg, options.tag).tag;
+            const staged = resolveStaged(pkg, options.staged);
             entries.set(pkg.name, {
                 package: pkg,
                 version: pkg.version,
                 registryVersion,
                 distTag,
+                staged,
                 /** Printed beside the package in the plan, so where a version is going is something the
-                 *  reader confirms rather than something they have to infer from the version string. */
-                detail: distTag ? `-> dist-tag "${distTag}"` : undefined,
+                 *  reader confirms rather than something they have to infer from the version string.
+                 *  Staging is named first because it changes what the run *does* - a reader who reads
+                 *  only the dist-tag would take a staged entry for one that goes live. */
+                detail: [staged ? 'staged for approval' : undefined, distTag ? `-> dist-tag "${distTag}"` : undefined]
+                    .filter(Boolean)
+                    .join(', ') || undefined,
                 status: published ? 'up-to-date' : 'publish',
                 reason: published
                     ? `registry already has ${pkg.version}`
@@ -256,10 +268,14 @@ export var PublishService;
             const publishDir = resolvePublishDir(pkg, options.contents);
             const restore = preparePublishManifest(pkg, publishDir, packagesByName);
             try {
-                /** The plan's own tag, not a recomputed one: `getPlan` decided where this package goes,
-                 *  the reader confirmed that, and `applyPlan` is here to carry it out. `options.tag` is
-                 *  the fallback only for a plan built by something other than `getPlan`. */
-                await exec(buildPublishCommand(packageManager, { ...options, tag: entry.distTag ?? options.tag }), {
+                /** The plan's own tag and staging decision, not recomputed ones: `getPlan` decided where
+                 *  this package goes, the reader confirmed that, and `applyPlan` is here to carry it out.
+                 *  `options.*` is the fallback only for a plan built by something other than `getPlan`. */
+                await exec(buildPublishCommand(packageManager, {
+                    ...options,
+                    tag: entry.distTag ?? options.tag,
+                    staged: entry.staged ?? options.staged,
+                }), {
                     cwd: publishDir,
                     app: pkg.repository.app,
                     stdio: 'inherit',
@@ -355,8 +371,17 @@ function distTagFor(pkg, tag) {
             'no --tag npm would put it on "latest" - pass --tag <name>',
     };
 }
+/* **`stage publish`, not a `--staged` flag**, because that is npm's own spelling: `npm stage` is a
+ * command with `publish`/`list`/`view`/`download`/`approve`/`reject` under it, and rman only ever
+ * drives the first. The rest is a maintainer's, at a terminal with a 2FA prompt - which is the whole
+ * point of staging, and the reason rman must not grow an `approve`.
+ *
+ * The publish flags are passed through unchanged. `--otp` is the one that reads oddly beside it,
+ * since staging is what *defers* the 2FA challenge to approval time - it is passed anyway rather
+ * than refused, because whether npm accepts it there is npm's to answer and a guess here would be a
+ * rule rman invented. */
 function buildPublishCommand(packageManager, options) {
-    const args = ['publish'];
+    const args = options.staged ? ['stage', 'publish'] : ['publish'];
     if (options.access)
         args.push('--access', options.access);
     if (options.tag)
@@ -369,3 +394,13 @@ function buildPublishCommand(packageManager, options) {
         args.push('--userconfig', options.userconfig);
     return `${packageManager} ${args.join(' ')}`;
 }
+/** Whether this package stages: `--staged`/`--no-staged` when given, else its own
+ *  `.rmanrc "publish.npm.staged"`. */
+/* Per package rather than per run, like `directory` beside it - a repository may well want its one
+ * widely-depended-on package held for approval and the rest published directly, and the cascade
+ * already makes "all of them" a single `"[*]"` line. */
+function resolveStaged(pkg, override) {
+    if (override !== undefined)
+        return override;
+    return !!pkg.config?.publish?.npm?.staged;
+}

package/builtins/publish-targets/npm/npm-publish-target.d.ts

@@ -49,6 +49,11 @@ export declare class NpmPublishTarget implements PublishTarget {
             describe: string;
             type: "string";
         };
+        staged: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
         registry: {
             target: "cli";
             describe: string;

package/builtins/publish-targets/npm/npm-publish-target.js

@@ -50,6 +50,13 @@ export class NpmPublishTarget {
             describe: 'npm publish --otp <otp> - a 2FA one-time password, for registries that require it',
             type: 'string',
         },
+        staged: {
+            target: 'cli',
+            describe: "npm stage publish - hold each version in npm's staging queue instead of publishing it, " +
+                'until a maintainer runs "npm stage approve" with 2FA. --no-staged forces a direct publish ' +
+                'over .rmanrc "publish.npm.staged"',
+            type: 'boolean',
+        },
         registry: {
             target: 'cli',
             describe: 'Registry to check against and publish to (default: whatever .npmrc already configures)',
@@ -90,6 +97,11 @@ export class NpmPublishTarget {
              *  decides the dist-tag and refuses the two cases with nothing to derive, so `--dry-run` and
              *  the JSON a pipeline gates on have to see the flag. */
             tag: ctx.args.tag,
+            /** Plan-time for the same reason, and a stronger one: whether a run leaves the version live
+             *  or waiting for an approval is the thing a reader is confirming. Left `undefined` when the
+             *  flag was not given, so each package's own `publish.npm.staged` still decides - `false`
+             *  here would mean `--no-staged` and silently overrule the config. */
+            staged: ctx.args.staged,
         };
     }
 }

package/cli.js

@@ -13,7 +13,7 @@ import { version } from './constants.js';
 import { RmanApplication } from './core/application.js';
 import { Repository } from './core/classes/repository.js';
 import { commandName, toYargsCommand } from './core/command-builder.js';
-import { assertNoBuiltinShadowing, defaultCommandGlobs, loadCustomCommands, } from './core/interfaces/custom-command.js';
+import { assertNoBuiltinShadowing, defaultCommandGlobs, describeCommandSource, loadCustomCommands, } from './core/interfaces/custom-command.js';
 import { checkCustomCommand } from './core/plugin-loader.js';
 import { commandRegistry } from './interfaces/rman-config.interface.js';
 import { colorYaml } from './utils/color-yaml.js';
@@ -141,7 +141,7 @@ export async function runCli(options) {
             if (!c.register)
                 return { name: c.name, file: c.file, module: toCustomModule(c.custom, repository, app) };
             const declared = c.register(app);
-            const meta = checkCustomCommand({ ...declared, command: declared.command?.trim() || c.name }, c.file);
+            const meta = checkCustomCommand({ ...declared, command: declared.command?.trim() || c.name }, describeCommandSource(c.file));
             return { name: commandName(meta.command), file: c.file, module: toYargsCommand(meta) };
         });
         /**
@@ -179,7 +179,8 @@ export async function runCli(options) {
             const survivors = new Set(commands);
             for (const lost of localModules.filter(c => !survivors.has(c))) {
                 const winner = byName.get(lost.name);
-                logger.verbose(`"${lost.name}" from ${lost.file} is overridden by ${winner.file}.`);
+                logger.verbose(`"${lost.name}" from ${describeCommandSource(lost.file)} is overridden by ` +
+                    `${describeCommandSource(winner.file)}.`);
             }
         }
         assertNoBuiltinShadowing(commands, builtInNames(builtIns));
@@ -265,17 +266,21 @@ function commandEntries(repository) {
             if (!entry || seen.has(entry))
                 continue;
             seen.add(entry);
-            /** No file to fall back on, so the metadata has to name itself - `checkCustomCommand` says
-             *  so when it does not. `"commands"` stands in for the file in that message. */
+            /** **No file, and `file: ''` says so** - `describeCommandSource` turns that into
+             *  `.rmanrc "commands"` wherever a message needs to name the origin. It used to be the
+             *  literal string `'"commands"'`, which is not a path: `path.relative` mangled it and its
+             *  own quotes doubled in every message that added a pair.
+             *
+             *  The metadata therefore has to name itself, since there is no basename to fall back on,
+             *  and `checkCustomCommand` is what says so when it does not. */
             if (typeof entry === 'function') {
-                direct.push({ name: '', file: '"commands"', register: entry });
+                direct.push({ name: '', file: '', register: entry });
             }
             else {
-                /** `checkCustomCommand` is what refuses a nameless one, with the message that names the
-                 *  omission - reached here rather than at registration so an inline command is checked
-                 *  the same way a plugin's used to be. */
-                const custom = checkCustomCommand(entry, '"commands"');
-                direct.push({ name: commandName(custom.command), file: '"commands"', custom });
+                /** Reached here rather than at registration, so an inline command is checked the same way
+                 *  one loaded from a file is. */
+                const custom = checkCustomCommand(entry, describeCommandSource(''));
+                direct.push({ name: commandName(custom.command), file: '', custom });
             }
         }
     }

package/commands.d.ts

@@ -20,7 +20,6 @@ import './commands/exec.command.js';
 import './commands/github-release.command.js';
 import './commands/import.command.js';
 import './commands/info.command.js';
-import './commands/lint.command.js';
 import './commands/list.command.js';
 import './commands/publish.command.js';
 import './commands/run.command.js';

package/commands.js

@@ -20,7 +20,6 @@ import './commands/exec.command.js';
 import './commands/github-release.command.js';
 import './commands/import.command.js';
 import './commands/info.command.js';
-import './commands/lint.command.js';
 import './commands/list.command.js';
 import './commands/publish.command.js';
 import './commands/run.command.js';

package/constants.js

@@ -1 +1 @@
-export const version = '2.0.0-beta.3';
+export const version = '2.0.0-beta.5';

package/core/classes/workspace.d.ts

@@ -95,13 +95,15 @@ export declare class Workspace {
     /** Root, then every directory down to `targetDir`, inclusive. A target outside the root is the
      *  root alone. */
     protected _dirChain(targetDir: string): string[];
-    /** A level's own settings - everything that is not a `"[...]"` block. */
+    /** One config object's own settings - everything that is not a `"[...]"` block. Shallow: a block
+     *  is dropped whole, and what is inside it is the caller's business. */
     protected _stripSelectors(config: RmanConfig): RmanConfig;
     /**
-     * The blocks in `config` that speak for this package, in declaration order.
+     * The layers in `config` that speak for this package, in the order they are merged.
      *
      * `"[/]"` matches the root and nothing else; a glob matches a package's selector and never the
-     * root.
+     * root. **A block may hold further selector blocks**, which narrow it: a nested one applies only
+     * where its own audience and every audience it sits inside all match.
      */
     protected _matchingSelectors(config: RmanConfig, audience: Workspace.Audience): RmanConfig[];
     /**

package/core/classes/workspace.js

@@ -290,24 +290,68 @@ export class Workspace {
         }
         return dirs;
     }
-    /** A level's own settings - everything that is not a `"[...]"` block. */
+    /** One config object's own settings - everything that is not a `"[...]"` block. Shallow: a block
+     *  is dropped whole, and what is inside it is the caller's business. */
+    /* **The symbols travel with it, and leaving them behind was a measured loss.** `mergeConfig` reads
+     * a key's origin and its `value` chain off the *source* object under `ORIGINS` / `PREVIOUS_VALUES`,
+     * so a copy that carries only string keys arrives with neither. Measured on one repository before
+     * this line existed: a bad expression in an unmarked key reported `Invalid expression in "group"`
+     * with no file, while the identical expression inside a `"[*]"` block reported
+     * `... ("group" (.rmanrc.yml))` - because a selector block was merged as itself and only the
+     * unmarked layer came through here. Nesting would have spread that to the blocks too. */
     _stripSelectors(config) {
         const result = {};
         for (const [key, value] of Object.entries(config))
             if (!ConfigReader.isSelectorKey(key))
                 result[key] = value;
+        for (const symbol of Object.getOwnPropertySymbols(config)) {
+            Object.defineProperty(result, symbol, Object.getOwnPropertyDescriptor(config, symbol));
+        }
         return result;
     }
     /**
-     * The blocks in `config` that speak for this package, in declaration order.
+     * The layers in `config` that speak for this package, in the order they are merged.
      *
      * `"[/]"` matches the root and nothing else; a glob matches a package's selector and never the
-     * root.
+     * root. **A block may hold further selector blocks**, which narrow it: a nested one applies only
+     * where its own audience and every audience it sits inside all match.
      */
     /* **A glob never matching the root removes two traps at once**: `"[my-*]"` cannot quietly pick up
      * a repository whose root package is called `my-repo`, and `"[*]"` cannot hand a package-shaped
      * setting to a root with no build directory to apply it to. A root block needs no selector, which
-     * is what makes `/` structural. */
+     * is what makes `/` structural.
+     *
+     * **Nesting is depth-first pre-order, which is the level's own rule applied again rather than a
+     * new one**: a block's own keys are its floor, then the blocks written inside it in declaration
+     * order, then the next block beside it. So the layer order for
+     * `"[platform:node]" { a, "[pkg-*]" { b } }, "[*]" { c }` is `a, b, c` - and the last word is
+     * still whatever was written last, *not* whatever is most specific. That is the same cost the
+     * dropped specificity ranking already documents (a catch-all written below a narrower block
+     * overrides it), and nesting neither adds to it nor asks the tiebreak question again: two blocks
+     * that both match are siblings whatever depth they sit at, and declaration order answers them.
+     *
+     * **A matching block is contributed *stripped*, not whole.** Merging it as it stands put its
+     * nested keys into the resolved config as literal `'[pkg-*]'` entries, which is precisely how the
+     * old no-op showed up in `rman config` looking as though it had worked.
+     *
+     * **A platform block speaks for the root too, and only a glob is held off it.** `"[platform:node]"`
+     * asks `pkg.platform.name` and the root is a package with a platform, so
+     * `"[platform:node]" > "[/]"` is *the root, when the root is a node package* and
+     * `"[platform:node]" > "[*]"` is *its packages* - which is the whole of a technology's shared
+     * config in one block, `vars` included.
+     *
+     * A narrower rule was tried first and measured wrong: let a chain reach the root only where it
+     * *names* `"[/]"`, keeping a plain `"[platform:node]"` off the root as before. It answers the pair
+     * correctly and still breaks the case it was written for - the nested `"[/]"` could not read the
+     * `vars` its parent declared (`vars is not defined`), because those are the parent's own keys.
+     * Narrowing an audience and hiding the enclosing block's settings from it are different things,
+     * and only the first is what nesting means.
+     *
+     * The cost, stated rather than hidden: a package-shaped setting written **directly** under a
+     * platform block now reaches the root as well - the trap that keeps globs off it. It is not the
+     * same trap, because neither half of that one applies here: `platform:node` is not a name and
+     * cannot match by accident, and it is not a catch-all. And with nesting the spelling for
+     * package-shaped settings is `"[platform:node]" > "[*]"`, which says so. */
     _matchingSelectors(config, audience) {
         const matches = [];
         for (const [key, value] of Object.entries(config)) {
@@ -316,7 +360,9 @@ export class Workspace {
             const { scope, test } = ConfigReader.parseSelector(key);
             if (!this._speaksFor(scope, test, audience))
                 continue;
-            matches.push(value);
+            const block = value;
+            matches.push(this._stripSelectors(block));
+            matches.push(...this._matchingSelectors(block, audience));
         }
         return matches;
     }
@@ -328,8 +374,12 @@ export class Workspace {
      */
     /* **A glob never matching the root removes two traps at once**: `"[my-*]"` cannot quietly pick up
      * a repository whose root package is called `my-repo`, and `"[*]"` cannot hand a package-shaped
-     * setting to a root with no build directory to apply it to. A platform block is held to the same
-     * line for consistency - the root has a platform, but it also has `"[/]"`.
+     * setting to a root with no build directory to apply it to. Neither trap exists for a platform
+     * block - `platform:node` is not a name and cannot match by accident, and it is not a catch-all -
+     * so **a platform link answers about the root like any other package**, and what keeps a plain
+     * `"[platform:node]"` off the root is `_matchingSelectors`' chain rule rather than a refusal here.
+     * Asking `isRoot` first was what made `"[platform:node]" > "[/]"` unanswerable: the pair says *the
+     * root, when it is a node package*, and the short-circuit never let the platform question be put.
      *
      * A package no technology claimed carries `basePlatform`, whose name is `''`, so it matches no
      * platform block at all - `parseSelector`'s test refuses an empty name rather than letting an
@@ -337,11 +387,9 @@ export class Workspace {
     _speaksFor(scope, test, audience) {
         if (scope === 'root')
             return audience.isRoot;
-        if (audience.isRoot)
-            return false;
         if (scope === 'platform')
             return test(audience.platform);
-        return audience.selector !== undefined && test(audience.selector);
+        return !audience.isRoot && audience.selector !== undefined && test(audience.selector);
     }
     /**
      * The platform that claims a directory - the one its config names, or the first loaded platform

package/core/config/config-reader.d.ts

@@ -13,7 +13,8 @@ export declare class ConfigReader {
      */
     static isSelectorKey(key: string): boolean;
     /**
-     * **Which packages a selector key speaks for.** Two audiences, and the second is a glob:
+     * **Which packages a selector key speaks for.** Three audiences, and what each is matched
+     * against:
      *
      * | | matches | `test` is given |
      * | --- | --- | --- |
@@ -58,7 +59,27 @@ export declare class ConfigReader {
      * default export when there is one, the module's own exports object otherwise.
      */
     protected _loadConfigModule(file: string): Promise<any>;
+    /**
+     * Checks every `"[...]"` key in a config: where it sits, what it carries, and - for a nested one -
+     * whether the pair could ever match a package.
+     */
     protected _assertSelectorBlocks(config: RmanConfig, file: string): void;
+    /**
+     * One walk, refusing a selector key under a *setting* and checking each legal one's contents.
+     *
+     * @param at the key path to `node`.
+     * @param enclosing the selector keys `node` sits inside, outermost first.
+     */
+    protected _assertSelectorKeys(node: unknown, file: string, at: string[], enclosing: string[]): void;
+    /** What one selector block may carry, and - given `outer` - whether it can match anything. */
+    protected _assertSelectorBlock(key: string, value: unknown, file: string, outer: string | undefined): void;
+    /**
+     * Refuses a nested pair that could never match a package together.
+     *
+     * @param outer the enclosing selector key.
+     * @param inner the key written inside it.
+     */
+    protected _assertNestable(outer: string, inner: string, file: string): void;
     protected _resolveExtends(context: ConfigReader.Context, config: RmanConfig, from: string, seen?: string[]): Promise<RmanConfig>;
     /**
      * Lays `options.presets` underneath this level's own config, exactly as an `extends` naming them
@@ -152,6 +173,8 @@ export declare namespace ConfigReader {
         /** Whether a package's selector is one this key speaks for. Always `true` for a root key, which
          *  is matched by *being* the root rather than by name. */
         test(name: string): boolean;
+        /** The technologies a `"[platform:...]"` key names, and nothing for the other two scopes. */
+        names?: readonly string[];
     }
     interface Options {
         /** Plugins to start with - the application's. Optional like `platforms`, which it was not: a

package/core/config/config-reader.js

@@ -6,6 +6,7 @@ import fastGlob from 'fast-glob';
 import * as yaml from 'js-yaml';
 import { presetNames, PRESETS_DIR } from '../../builtins/presets/index.js';
 import { declaredKind, isDeclared, isPlatform } from '../interfaces/plugin.js';
+import { CODE_SUBTREES } from './config-paths.js';
 import { mergeConfig } from './merge-config.js';
 const requireConfigModule = createRequire(import.meta.url);
 const IDENTITY_KEYS = ['platform', 'name'];
@@ -21,6 +22,8 @@ const PRESET_EXTENSIONS = ['.js', '.ts'];
 /** What an error about a default preset names itself as - there is no config key to quote, since
  *  these are laid down by the caller rather than written by anybody. */
 const PRESETS_LABEL = 'presets';
+/** Free-form by contract - see `_assertSelectorKeys`. */
+const VARS_KEY = 'vars';
 /** Keys that only an rman **config** has, for telling one from a contribution once it has already
  *  been refused - see `_assertLoaded`. `name` is not among them: a plugin has one too. */
 const CONFIG_SHAPED = ['extends', PLUGINS_KEY, PLATFORMS_KEY, 'commands', 'publishTargets'];
@@ -46,7 +49,8 @@ export class ConfigReader {
         return key.length > 2 && key.startsWith('[') && key.endsWith(']');
     }
     /**
-     * **Which packages a selector key speaks for.** Two audiences, and the second is a glob:
+     * **Which packages a selector key speaks for.** Three audiences, and what each is matched
+     * against:
      *
      * | | matches | `test` is given |
      * | --- | --- | --- |
@@ -82,7 +86,7 @@ export class ConfigReader {
                 .split(',')
                 .map(n => n.trim())
                 .filter(Boolean);
-            return { scope: 'platform', test: (name) => !!name && names.includes(name) };
+            return { scope: 'platform', test: (name) => !!name && names.includes(name), names };
         }
         const re = globToRegExp(stripWorkspacePrefix(inner));
         return { scope: 'package', test: (name) => re.test(name) };
@@ -292,38 +296,158 @@ export class ConfigReader {
         }
         return mod?.default ?? mod;
     }
+    /**
+     * Checks every `"[...]"` key in a config: where it sits, what it carries, and - for a nested one -
+     * whether the pair could ever match a package.
+     */
     _assertSelectorBlocks(config, file) {
-        for (const [key, value] of Object.entries(config)) {
-            if (!ConfigReader.isSelectorKey(key) || !value || typeof value !== 'object')
+        this._assertSelectorKeys(config, file, [], []);
+    }
+    /**
+     * One walk, refusing a selector key under a *setting* and checking each legal one's contents.
+     *
+     * @param at the key path to `node`.
+     * @param enclosing the selector keys `node` sits inside, outermost first.
+     */
+    /* **A selector key is legal at the top level of a config and directly inside another selector
+     * key, and nowhere else** - which is the whole of the placement rule, and `at.length >
+     * enclosing.length` is the whole of the test: the two arrays stay equal for as long as every
+     * ancestor is a selector, and `at` runs ahead the moment one is not.
+     *
+     * ```yaml
+     * "[platform:node]":
+     *   "[pkg-*]": { group: x }     # an intersection
+     *   run:
+     *     "[pkg-*]": { ... }        # refused - a setting is not an audience
+     * ```
+     *
+     * **The nested form used to be refused outright and that was the wrong call**, on a reason that
+     * does not survive being written out: "selectors do not intersect, because specificity ranking was
+     * dropped". Ranking answers which of two *siblings* wins, and nesting asks nothing of the sort -
+     * a nested block is resolved depth-first in declaration order, which is the rule already in force
+     * one level up (`Workspace._matchingSelectors`). What the refusal cost was the only way to say
+     * "these packages, but only the ones that are also X" for a whole block: `if:` is per key and
+     * reaches neither `vars` nor any key that is not a run step.
+     *
+     * What the refusal *did* get right was that silence is unacceptable - before it, the inner block
+     * reached every package the outer one did, as a literal `'[pkg-*]'` key sitting in the resolved
+     * config where `rman config` showed it looking as though it had worked. Both halves are answered
+     * now: the shape works, and the shapes that could never work are refused here rather than
+     * quietly matching nothing.
+     *
+     * **`vars` and the contribution keys are skipped**, and both for the same reason: their contents
+     * are not config keys. `vars` is free-form by contract and `CODE_SUBTREES` hold plugins, commands
+     * and publish targets - arbitrary objects whose key space rman does not own. A bracketed name in
+     * either is data. */
+    _assertSelectorKeys(node, file, at, enclosing) {
+        if (!node || typeof node !== 'object' || Array.isArray(node))
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (ConfigReader.isSelectorKey(key)) {
+                if (at.length > enclosing.length) {
+                    throw new Error(`"${key}" in "${file}" is nested under "${at.join('.')}", which is a setting rather ` +
+                        `than an audience - a selector is read at the top level of a config and inside ` +
+                        `another selector, so this one would never be applied. Move it out, or use an ` +
+                        `expression where the value itself depends on the package.`);
+                }
+                this._assertSelectorBlock(key, value, file, enclosing.at(-1));
+                this._assertSelectorKeys(value, file, [...at, key], [...enclosing, key]);
                 continue;
-            if (EXTENDS_KEY in value) {
-                throw new Error(`"${key}" in "${file}" cannot use "extends" - it belongs at the top level, where it is a ` +
-                    `statement about this config rather than about the packages the selector names.`);
             }
-            /**
-             * **The two keys a selector cannot carry, because the selector is downstream of them.**
-             *
-             * A `"[glob]"` matches `Package.selector`, which comes from `name` - and which package a
-             * directory even holds comes from `platform`. Both are read from the *unmarked* cascade, while
-             * the packages are still being found, so a glob block setting either would need its own answer
-             * in order to be matched at all. Typed as a whole `RmanConfig`, both look valid there and both
-             * would simply never be read.
-             *
-             * `"[/]"` is exempt and keeps working: the root is addressed structurally - its directory *is*
-             * the repository root - so a root block needs no selector and is applied during the walk.
-             */
-            if (ConfigReader.parseSelector(key).scope === 'root')
+            if (key === VARS_KEY || CODE_SUBTREES.includes(key))
                 continue;
-            for (const identity of IDENTITY_KEYS) {
-                if (identity in value) {
-                    throw new Error(`"${key}" in "${file}" cannot set "${identity}" - a glob matches a package's selector, ` +
-                        `and "${identity}" is what the selector is derived from, so the block could never be ` +
-                        `matched in order to apply it. Write it unmarked, in the package's own ".rmanrc", or ` +
-                        `under "[/]" for the root package.`);
-                }
+            this._assertSelectorKeys(value, file, [...at, key], enclosing);
+        }
+    }
+    /** What one selector block may carry, and - given `outer` - whether it can match anything. */
+    _assertSelectorBlock(key, value, file, outer) {
+        if (!value || typeof value !== 'object')
+            return;
+        if (outer !== undefined)
+            this._assertNestable(outer, key, file);
+        if (EXTENDS_KEY in value) {
+            throw new Error(`"${key}" in "${file}" cannot use "extends" - it belongs at the top level, where it is a ` +
+                `statement about this config rather than about the packages the selector names.`);
+        }
+        /**
+         * **The two keys a selector cannot carry, because the selector is downstream of them.**
+         *
+         * A `"[glob]"` matches `Package.selector`, which comes from `name` - and which package a
+         * directory even holds comes from `platform`. Both are read from the *unmarked* cascade, while
+         * the packages are still being found, so a glob block setting either would need its own answer
+         * in order to be matched at all. Typed as a whole `RmanConfig`, both look valid there and both
+         * would simply never be read.
+         *
+         * `"[/]"` is exempt and keeps working: the root is addressed structurally - its directory *is*
+         * the repository root - so a root block needs no selector and is applied during the walk.
+         */
+        if (ConfigReader.parseSelector(key).scope === 'root') {
+            /** **Except for `platform` in a *nested* `"[/]"`, which is read nowhere.**
+             *  `Workspace._declaredPlatformName` looks at a level's own `platform` and at a **top-level**
+             *  `"[/]"`, because which technology claims a directory has to be settled before any block is
+             *  matched. Inside `"[platform:node]"` it is also circular - the answer decides whether the
+             *  block that declares it applies at all. */
+            if (outer !== undefined && 'platform' in value) {
+                throw new Error(`"${key}" in "${file}" is nested inside "${outer}" and cannot set "platform" - which ` +
+                    `technology claims a directory is settled before any selector is matched, so it is ` +
+                    `read from the level's own keys or a top-level "[/]" and nowhere else. Write it there.`);
+            }
+            return;
+        }
+        for (const identity of IDENTITY_KEYS) {
+            if (identity in value) {
+                throw new Error(`"${key}" in "${file}" cannot set "${identity}" - a glob matches a package's selector, ` +
+                    `and "${identity}" is what the selector is derived from, so the block could never be ` +
+                    `matched in order to apply it. Write it unmarked, in the package's own ".rmanrc", or ` +
+                    `under "[/]" for the root package.`);
             }
         }
     }
+    /**
+     * Refuses a nested pair that could never match a package together.
+     *
+     * @param outer the enclosing selector key.
+     * @param inner the key written inside it.
+     */
+    /* **Nesting is an AND, so a pair naming disjoint sets is a block that runs for nobody** - which is
+     * the silence worth refusing. Two pairs are decidable and both are:
+     *
+     * - **`"[/]"` paired with a glob**, either way round. A glob matches a package's name and the root
+     *   is nobody's child, so it never matches the root whatever it is written beside;  `"[/]"`
+     *   matches nothing else. The pair is empty in both directions.
+     * - **Two platform blocks naming nothing in common.** A package carries one `platform.name`, so
+     *   `"[platform:node]" > "[platform:cargo]"` is empty; `"[platform:node,cargo]" > "[platform:node]"`
+     *   narrows and is fine.
+     *
+     * **`"[/]"` inside a platform block is the pair this deliberately allows**, and getting that wrong
+     * once is why the reasoning is written out. It reads as *the root, when the root is a node
+     * package*, which is a perfectly well-defined audience - it was unreachable only because
+     * `_speaksFor` asked `isRoot` before it asked the platform question. Refusing it took the natural
+     * shape of a technology's shared config away: a preset wanting `vars` over a whole node
+     * repository, the root's own settings, and the packages' settings had to hoist `vars` to the top
+     * level, where they also reach packages of every other technology.
+     *
+     * **A glob pair is deliberately not checked**, and the asymmetry is the point rather than an
+     * omission: whether two globs intersect is a real computation with a wrong answer available in
+     * both directions, while a platform set is `includes`. `"[pkg-*]" > "[lib-*]"` therefore loads and
+     * matches nothing - the same thing a top-level `"[lib-*]"` does in a repository with no such
+     * package, which nothing reports either. */
+    _assertNestable(outer, inner, file) {
+        const a = ConfigReader.parseSelector(outer);
+        const b = ConfigReader.parseSelector(inner);
+        const [root, glob] = a.scope === 'root' ? [outer, b.scope === 'package' && inner] : [inner, a.scope === 'package' && outer];
+        if ((a.scope === 'root' || b.scope === 'root') && glob) {
+            throw new Error(`"${inner}" in "${file}" is nested inside "${outer}", and "${glob}" can never match the ` +
+                `same package "${root}" does - a glob matches a package's name and the root is nobody's ` +
+                `child, so the pair is empty. A platform block nests with "[/]" ("the root, when it is ` +
+                `of that technology"); a glob does not.`);
+        }
+        if (a.scope === 'platform' && b.scope === 'platform' && !b.names?.some(name => a.test(name))) {
+            throw new Error(`"${inner}" in "${file}" is nested inside "${outer}", which names no technology in common ` +
+                `with it - a package carries one platform, so this block could never be applied. Nesting ` +
+                `narrows: name a technology the outer block already speaks for.`);
+        }
+    }
     async _resolveExtends(context, config, from, seen = []) {
         const declared = config[EXTENDS_KEY];
         if (declared === undefined)

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

@@ -157,9 +157,16 @@ export declare function loadCustomCommands(patterns: string[]): Promise<{
     commands: LoadedCommand[];
     errors: CommandLoadError[];
 }>;
+/**
+ * How to name a command's origin in a message: the file it came from, or the config key that
+ * declared it.
+ *
+ * @param file a `LoadedCommand.file` - `''` for a command written into `.rmanrc "commands"`.
+ */
+export declare function describeCommandSource(file: string): string;
 /**
  * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
- * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * this one is thrown: the source is fine, the *name* is the mistake, and there is no reading of
  * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
  * it unable to tell which ran.
  */

package/core/interfaces/custom-command.js

@@ -111,16 +111,35 @@ export async function loadCustomCommands(patterns) {
     }
     return { commands, errors };
 }
+/**
+ * How to name a command's origin in a message: the file it came from, or the config key that
+ * declared it.
+ *
+ * @param file a `LoadedCommand.file` - `''` for a command written into `.rmanrc "commands"`.
+ */
+/* **A command loaded from a config key has no file, and saying so beats inventing one.** `file` was
+ * `'"commands"'` for those - a string that is not a path, carrying its own quotes - and every
+ * message that formatted it got something wrong: `path.relative` mangled it, the quotes doubled
+ * (`""commands""` in the shadowing error), and `checkCustomCommand` announced it as a plugin name.
+ * One empty string and one helper is the whole fix. */
+export function describeCommandSource(file) {
+    return file ? `"${path.relative(process.cwd(), file)}"` : '.rmanrc "commands"';
+}
 /**
  * Refuses a command that would take a built-in's name. Unlike a module that simply fails to load,
- * this one is thrown: the file is fine, the *name* is the mistake, and there is no reading of
+ * this one is thrown: the source is fine, the *name* is the mistake, and there is no reading of
  * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
  * it unable to tell which ran.
  */
+/* The remedy differs by where the command came from, which is the other half of why the origin has
+ * to be honest: "rename the file" is the answer for a `.rman/*.mjs` and no answer at all for an
+ * entry in a config, where there is no file to rename. */
 export function assertNoBuiltinShadowing(commands, builtins) {
     const clash = commands.find(c => builtins.includes(c.name));
     if (!clash)
         return;
-    throw new Error(`"${path.relative(process.cwd(), clash.file)}" would shadow rman's built-in "${clash.name}" command.\n` +
-        `  Rename the file, or give it its own name with \`command: '<name>'\`.`);
+    const remedy = clash.file
+        ? `Rename the file, or give it its own name with \`command: '<name>'\`.`
+        : `Give it its own name with \`command: '<name>'\`.`;
+    throw new Error(`${describeCommandSource(clash.file)} would shadow rman's built-in "${clash.name}" command.\n  ${remedy}`);
 }

package/core/plugin-loader.d.ts

@@ -20,6 +20,6 @@ export declare function checkCustomCommand<T extends {
     command?: string;
     describe?: unknown;
     handler?: unknown;
-}>(command: T, pluginName: string): T & {
+}>(command: T, source: string): T & {
     command: string;
 };

package/core/plugin-loader.js

@@ -37,17 +37,21 @@ export function registerPlugin(app, entry) {
     }
     app.plugins.add(entry);
 }
-export function checkCustomCommand(command, pluginName) {
+/* **`source` is where the command came from, already worded for a message** - a file in quotes, or
+ * `.rmanrc "commands"` - and `describeCommandSource` is what produces it. It was called
+ * `pluginName` and the messages said `Plugin "..."`, which neither caller ever passed: both hand
+ * over a command's *origin*, so a repository's own `.rman/deploy.mjs` was announced as a plugin and
+ * a config entry came out as `Plugin """commands"""`. */
+export function checkCustomCommand(command, source) {
     const declared = command?.command?.trim();
     if (!declared) {
-        throw new Error(`Plugin "${pluginName}" has a command with no "command" name - it cannot be registered.`);
+        throw new Error(`${source} has a command with no "command" name - it cannot be registered.`);
     }
     if (typeof command.handler !== 'function') {
-        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "handler" function.`);
+        throw new Error(`${source} command "${declared}" has no "handler" function.`);
     }
     if (typeof command.describe !== 'string' || !command.describe) {
-        throw new Error(`Plugin "${pluginName}" command "${declared}" has no "describe" - \`rman --help\` would have ` +
-            `nothing to list it by.`);
+        throw new Error(`${source} command "${declared}" has no "describe" - \`rman --help\` would have nothing to ` + `list it by.`);
     }
     return { ...command, command: declared };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.5",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
@@ -71,4 +71,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/commands/lint.command.d.ts

@@ -1,176 +0,0 @@
-import { type RmanConfig } from '../interfaces/rman-config.interface.js';
-declare const COMMAND: "lint";
-declare const config: {
-    parallel: {
-        target: "cli";
-        describe: string;
-        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";
-        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";
-    };
-};
-type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
-/**
- * `rman lint` - an alias for `rman run lint`, the third of the trio beside `build` and `test`.
- */
-declare const lintCommand: (app: import("../index.js").RmanApplication) => {
-    command: "lint";
-    describe: string;
-    /** Read, not owned - see the note above. */
-    configKeys: string[];
-    config: {
-        parallel: {
-            target: "cli";
-            describe: string;
-            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";
-            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";
-        };
-    };
-    examples: {
-        command: string;
-        description: string;
-    }[];
-    handler: (args: Args) => Promise<void>;
-};
-export default lintCommand;

package/commands/lint.command.js

@@ -1,34 +0,0 @@
-import { registerCommand } from '../interfaces/rman-config.interface.js';
-import { assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { readRunOptions, runOptions } from '../utils/run-options.js';
-const COMMAND = 'lint';
-const config = runOptions;
-/**
- * `rman lint` - an alias for `rman run lint`, the third of the trio beside `build` and `test`.
- */
-/* **Core, not the `node` preset, and the test is what the command *knows*.** It knows a script
- * name and nothing else: a Cargo repository declaring `lint: 'cargo clippy'` and a Go one
- * declaring `golangci-lint run` are served by exactly this file. That is the line `clean` is on the
- * other side of - everything `clean` knows how to delete is a TypeScript fact - and it is why
- * `build` and `test` are here too.
- *
- * **It owns no config key**, for the reason `build` documents: `lint` is `run lint` under another
- * name, so its settings are `run.lint`, which belongs to `run`. Two commands cannot contribute
- * under one top-level key - interface merging is not a deep merge - and these three never needed
- * to. */
-const lintCommand = registerCommand(app => {
-    const repository = app.repository;
-    return {
-        command: COMMAND,
-        describe: 'Alias for "run lint"',
-        /** Read, not owned - see the note above. */
-        configKeys: ['run.lint'],
-        config,
-        examples: [{ command: '$0 lint', description: '# Lints packages' }],
-        handler: async (args) => {
-            await assertAllowedBranch(repository, readBranchGuardOptions(args));
-            await app.getService('run').runScript('lint', { ...readRunOptions(args), commandName: 'lint' });
-        },
-    };
-});
-export default lintCommand;