rman 1.2.5 → 2.0.0-beta.2

package/core/core-services.d.ts

@@ -0,0 +1,14 @@
+import type { RmanApplication } from './application.js';
+/**
+ * Every service the core brings, registered as an application is built.
+ *
+ * **Factories rather than instances**, so nothing is constructed until something asks: `rman info`
+ * has no business building the changelog or release services, and services reach each other through
+ * the application, so resolving at call time is also what keeps that from being a construction
+ * cycle.
+ *
+ * Here rather than inside `RmanApplication` so the composition list is one readable file, and so
+ * the application itself imports no service - only this does. A plugin adds its own the same way,
+ * from its own package, with `app.setService`.
+ */
+export declare function registerCoreServices(app: RmanApplication): void;

package/core/core-services.js

@@ -0,0 +1,30 @@
+import { ChangelogService } from '../services/changelog.service.js';
+import { DockerPublishService } from '../services/docker-publish.service.js';
+import { ExecService } from '../services/exec.service.js';
+import { GithubReleaseService } from '../services/github-release.service.js';
+import { ImportService } from '../services/import.service.js';
+import { ListService } from '../services/list.service.js';
+import { RunService } from '../services/run.service.js';
+import { VersionService } from '../services/version.service.js';
+/**
+ * Every service the core brings, registered as an application is built.
+ *
+ * **Factories rather than instances**, so nothing is constructed until something asks: `rman info`
+ * has no business building the changelog or release services, and services reach each other through
+ * the application, so resolving at call time is also what keeps that from being a construction
+ * cycle.
+ *
+ * Here rather than inside `RmanApplication` so the composition list is one readable file, and so
+ * the application itself imports no service - only this does. A plugin adds its own the same way,
+ * from its own package, with `app.setService`.
+ */
+export function registerCoreServices(app) {
+    app.setService('changelog', a => new ChangelogService(a));
+    app.setService('dockerPublish', a => new DockerPublishService(a));
+    app.setService('githubRelease', a => new GithubReleaseService(a));
+    app.setService('exec', a => new ExecService(a));
+    app.setService('import', a => new ImportService(a));
+    app.setService('list', a => new ListService(a));
+    app.setService('run', a => new RunService(a));
+    app.setService('version', a => new VersionService(a));
+}

package/core/core-targets.d.ts

@@ -0,0 +1,14 @@
+import type { RmanApplication } from './application.js';
+/**
+ * Every publish target the core brings, registered as an application is built - `registerCoreServices`
+ * for the other half of what a fresh application starts with.
+ *
+ * Exactly one today, and that is the point: `docker` is the target that belongs to no ecosystem, so
+ * it is the only one the core can honestly ship. `npm` arrives with the `node` built-in, and a Cargo or
+ * Maven target would arrive from its own plugin the same way.
+ *
+ * A separate file from `core-services.ts` rather than a second call inside it: a target is not a
+ * service (it is a contribution summed with others, not one replaceable answer), and a function
+ * called `registerCoreServices` that also registered targets would have to be read to be believed.
+ */
+export declare function registerCoreTargets(app: RmanApplication): void;

package/core/core-targets.js

@@ -0,0 +1,16 @@
+import { dockerPublishTarget } from '../targets/docker.target.js';
+/**
+ * Every publish target the core brings, registered as an application is built - `registerCoreServices`
+ * for the other half of what a fresh application starts with.
+ *
+ * Exactly one today, and that is the point: `docker` is the target that belongs to no ecosystem, so
+ * it is the only one the core can honestly ship. `npm` arrives with the `node` built-in, and a Cargo or
+ * Maven target would arrive from its own plugin the same way.
+ *
+ * A separate file from `core-services.ts` rather than a second call inside it: a target is not a
+ * service (it is a contribution summed with others, not one replaceable answer), and a function
+ * called `registerCoreServices` that also registered targets would have to be read to be believed.
+ */
+export function registerCoreTargets(app) {
+    app.publishTargets.add(dockerPublishTarget);
+}

package/core/custom-command.d.ts

@@ -1,4 +1,5 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
+import type { RmanConfig as CommandDeclaration } from '../interfaces/rman-config.interface.js';
 import type { Logger } from '../utils/logger.js';
 import type { RunBinOptions, RunBinResult } from '../utils/run-bin.js';
 import type { Package } from './package.js';
@@ -100,10 +101,25 @@ declare module 'yargs' {
  * that come with it; reimplementing that loop here would only lose them.
  */
 export declare function defineCommand(command: CustomCommand): CustomCommand;
-export interface LoadedCommand extends CustomCommand {
+/**
+ * One command module that loaded, in whichever form it exported.
+ *
+ * Both forms are accepted, and the same pair is accepted for a command written straight into
+ * `.rmanrc "commands"` - one key, one set of rules. The declarative factory is what rman asks a
+ * command author to write; a repository's own command should not be stuck on the older object
+ * shape just because it lives in a file rather than in a config.
+ */
+export interface LoadedCommand {
     /** The command's name - its file's basename, or the first word of an explicit `command`. */
     name: string;
     file: string;
+    /** The declarative form (`app => ({ ... })`). `cli.ts` runs it where a plugin's and a built-in's
+     *  own factories run, because it wants `app.repository` and loading happens before one exists. */
+    register?: CommandDeclaration.CommandRegisterFunction;
+    /** The `defineCommand({ ... })` object form, already checked and named. */
+    custom?: CustomCommand & {
+        command: string;
+    };
 }
 /** A module that couldn't be loaded or doesn't look like a command. Reported, never thrown: one
  *  unparseable file must not take `rman publish` down with it. */
@@ -112,15 +128,32 @@ export interface CommandLoadError {
     reason: string;
 }
 /**
- * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
- * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
- * included.
+ * The globs a repository's own commands are loaded from when it names none: `.rman/*.{js,mjs,cjs}`
+ * under the repository root.
+ *
+ * **`.rman/` is this default, not a second mechanism.** It used to be a hardcoded directory scan
+ * beside which `commands` would have been a third source of repository-level commands - and a
+ * third precedence question. Making it the default value instead leaves one source, one slot, and
+ * a zero-config path that behaves exactly as it did.
+ */
+export declare function defaultCommandGlobs(rootDir: string): string[];
+/**
+ * Loads every command module matching `patterns` - absolute globs, already anchored to whichever
+ * config file declared them (see `anchorContributions`).
+ *
+ * A repository matching nothing pays for one glob and no imports, which matters because this runs
+ * on *every* rman invocation, `info` included.
+ *
+ * **Deduplicated by resolved path**, because `commands` appends at every level and cascades: the
+ * root's glob reaches each package's resolved config too, so the same file is named more than once
+ * as a matter of course rather than as a mistake. Loading it twice would register the command
+ * twice, which yargs does not survive.
  *
  * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
  * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
  * `assertNoBuiltinShadowing`.
  */
-export declare function loadCustomCommands(rootDir: string): Promise<{
+export declare function loadCustomCommands(patterns: string[]): Promise<{
     commands: LoadedCommand[];
     errors: CommandLoadError[];
 }>;
@@ -130,4 +163,7 @@ export declare function loadCustomCommands(rootDir: string): Promise<{
  * `rman publish` that is safe to guess at. Silently preferring either one would leave whoever typed
  * it unable to tell which ran.
  */
-export declare function assertNoBuiltinShadowing(commands: LoadedCommand[], builtins: readonly string[]): void;
+export declare function assertNoBuiltinShadowing(commands: readonly {
+    name: string;
+    file: string;
+}[], builtins: readonly string[]): void;

package/core/custom-command.js

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import fastGlob from 'fast-glob';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export const CUSTOM_COMMAND_DIR = '.rman';
 /** Loadable module forms, matching what a `.rmanrc.cjs`/`.mjs`/`.js` config already accepts. A
@@ -41,30 +41,58 @@ export function defineCommand(command) {
     return command;
 }
 /**
- * Loads every command module in `<root>/.rman`. A repository without that directory pays nothing -
- * no scan, no imports - which matters because this runs on *every* rman invocation, `info`
- * included.
+ * The globs a repository's own commands are loaded from when it names none: `.rman/*.{js,mjs,cjs}`
+ * under the repository root.
+ *
+ * **`.rman/` is this default, not a second mechanism.** It used to be a hardcoded directory scan
+ * beside which `commands` would have been a third source of repository-level commands - and a
+ * third precedence question. Making it the default value instead leaves one source, one slot, and
+ * a zero-config path that behaves exactly as it did.
+ */
+export function defaultCommandGlobs(rootDir) {
+    return [path.join(rootDir, CUSTOM_COMMAND_DIR, `*{${EXTENSIONS.join(',')}}`)];
+}
+/**
+ * Loads every command module matching `patterns` - absolute globs, already anchored to whichever
+ * config file declared them (see `anchorContributions`).
+ *
+ * A repository matching nothing pays for one glob and no imports, which matters because this runs
+ * on *every* rman invocation, `info` included.
+ *
+ * **Deduplicated by resolved path**, because `commands` appends at every level and cascades: the
+ * root's glob reaches each package's resolved config too, so the same file is named more than once
+ * as a matter of course rather than as a mistake. Loading it twice would register the command
+ * twice, which yargs does not survive.
  *
  * Each failure is collected rather than thrown, so the rest of the CLI keeps working; the caller
  * warns about them. What is *not* tolerated is a module that would shadow a built-in - see
  * `assertNoBuiltinShadowing`.
  */
-export async function loadCustomCommands(rootDir) {
-    const dir = path.join(rootDir, CUSTOM_COMMAND_DIR);
+export async function loadCustomCommands(patterns) {
     const commands = [];
     const errors = [];
-    if (!fs.existsSync(dir))
+    if (!patterns.length)
         return { commands, errors };
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !EXTENSIONS.includes(path.extname(entry.name)))
-            continue;
-        const file = path.join(dir, entry.name);
+    /** Sorted so the order a command is registered in does not depend on the filesystem, and
+     *  `absolute` because a pattern may name a directory outside the repository entirely - which is
+     *  exactly what a shared config shipping its own commands does. */
+    const files = await fastGlob(patterns.map(p => p.split(path.sep).join('/')), { absolute: true, onlyFiles: true });
+    for (const file of [...new Set(files.map(f => path.resolve(f)))].sort()) {
         try {
             const mod = await import(pathToFileURL(file).href);
-            const command = mod?.default ?? mod?.command;
-            if (!command || typeof command !== 'object') {
-                throw new Error('no default export - end the module with `export default defineCommand({ ... })`');
+            const exported = mod?.default ?? mod?.command;
+            const basename = path.basename(file, path.extname(file));
+            /** The declarative form. Nothing to check here beyond its shape - the factory has not run,
+             *  so there is no metadata to validate yet; `cli.ts` checks what it returns. */
+            if (typeof exported === 'function') {
+                commands.push({ name: basename, file, register: exported });
+                continue;
+            }
+            if (!exported || typeof exported !== 'object') {
+                throw new Error('no command exported - end the module with `export default defineCommand({ ... })`, or with ' +
+                    'the declarative `export default app => ({ ... })`');
             }
+            const command = exported;
             if (typeof command.handler !== 'function')
                 throw new Error('"handler" is missing, or is not a function');
             if (typeof command.describe !== 'string' || !command.describe) {
@@ -72,10 +100,9 @@ export async function loadCustomCommands(rootDir) {
             }
             const declared = command.command?.trim();
             commands.push({
-                ...command,
-                command: declared || path.basename(entry.name, path.extname(entry.name)),
-                name: (declared || path.basename(entry.name, path.extname(entry.name))).split(/\s+/)[0],
+                name: (declared || basename).split(/\s+/)[0],
                 file,
+                custom: { ...command, command: declared || basename },
             });
         }
         catch (e) {

package/core/extends-config.d.ts

@@ -19,9 +19,17 @@ export declare const EXTENDS_KEY = "extends";
  */
 export declare function resolveExtends(config: RmanConfig, from: string, seen?: string[]): Promise<RmanConfig>;
 /**
- * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
- * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
- * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
- * the file, not about the packages it happens to name.
+ * **Refuses the keys a `"[selector]"` block cannot carry** - each for its own reason, and the
+ * reason is the same shape every time: a selector block is typed as a whole `RmanConfig`, so any
+ * key looks valid there, and one that can never be read is a config that quietly does nothing.
+ * That is worse than one that will not load.
+ *
+ * - **`extends`** is a statement about the *file*, not about the packages a selector happens to
+ *   name, and it belongs at the top level where it would actually be resolved.
+ * - **`platform` and `name`** are what the selector is derived *from*, so a glob block setting
+ *   either would need its own answer in order to be matched. See below; `"[/]"` is exempt.
+ *
+ * Called on every config form a directory can hold and on every `extends` base, so the file in the
+ * message is the one the line was written in.
  */
-export declare function assertNoSelectorExtends(config: RmanConfig, file: string): void;
+export declare function assertSelectorBlocks(config: RmanConfig, file: string): void;

package/core/extends-config.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import * as yaml from 'js-yaml';
-import { isSelectorKey } from './config.js';
+import { isSelectorKey, parseSelector } from './config.js';
+import { loadConfigModule } from './load-config-module.js';
 import { mergeConfig } from './merge-config.js';
 import { resolveConfigTarget } from './resolve-target.js';
 /** The key naming configs to inherit from, the way eslint and tsconfig spell it. */
@@ -40,7 +40,7 @@ export async function resolveExtends(config, from, seen = []) {
             throw new Error(`"extends" forms a cycle: ${[...seen, file].map(f => path.basename(f)).join(' -> ')}`);
         }
         const loaded = await loadConfigFile(file);
-        assertNoSelectorExtends(loaded, file);
+        assertSelectorBlocks(loaded, file);
         // Recursive: a shared config may itself be built on another.
         mergeConfig(base, await resolveExtends(loaded, file, [...seen, file]), file);
     }
@@ -49,12 +49,20 @@ export async function resolveExtends(config, from, seen = []) {
     return mergeConfig(base, own);
 }
 /**
- * Refuses `extends` inside a `"[selector]"` block. A selector block is typed as a whole
- * `RmanConfig`, so writing one there looks valid and would simply never be resolved - and a config
- * that quietly does nothing is worse than one that won't load. Inheritance is a statement about
- * the file, not about the packages it happens to name.
+ * **Refuses the keys a `"[selector]"` block cannot carry** - each for its own reason, and the
+ * reason is the same shape every time: a selector block is typed as a whole `RmanConfig`, so any
+ * key looks valid there, and one that can never be read is a config that quietly does nothing.
+ * That is worse than one that will not load.
+ *
+ * - **`extends`** is a statement about the *file*, not about the packages a selector happens to
+ *   name, and it belongs at the top level where it would actually be resolved.
+ * - **`platform` and `name`** are what the selector is derived *from*, so a glob block setting
+ *   either would need its own answer in order to be matched. See below; `"[/]"` is exempt.
+ *
+ * Called on every config form a directory can hold and on every `extends` base, so the file in the
+ * message is the one the line was written in.
  */
-export function assertNoSelectorExtends(config, file) {
+export function assertSelectorBlocks(config, file) {
     for (const [key, value] of Object.entries(config)) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
@@ -62,10 +70,40 @@ export function assertNoSelectorExtends(config, file) {
             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 (parseSelector(key).scope === 'root')
+            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.`);
+            }
+        }
     }
 }
-/** Loads one resolved target. YAML and JSON are read directly; anything else goes through the
- *  module loader, so a shared config can be a `defineConfig` module with real logic in it. */
+/**
+ * Loads one resolved target. YAML and JSON are read directly; anything else goes through
+ * `loadConfigModule`, so a shared config can be a `defineConfig` module with real logic in it.
+ *
+ * **Through that function rather than a bare `await import()`, which is what this used to do.**
+ * The two are not equivalent under an ESM loader hook: a `.cjs` base came back as an empty object,
+ * and an empty object is a valid config, so it contributed nothing and said nothing. See there for
+ * the measurement - the same file loaded correctly when it was a *directory's* own `.rmanrc.cjs`,
+ * because that path always used the careful loader.
+ */
 async function loadConfigFile(file) {
     const ext = path.extname(file);
     if (ext === '.yml' || ext === '.yaml') {
@@ -74,8 +112,7 @@ async function loadConfigFile(file) {
     }
     if (ext === '.json')
         return asConfig(JSON.parse(fs.readFileSync(file, 'utf-8')), file);
-    const mod = await import(pathToFileURL(file).href);
-    return asConfig(mod?.default ?? mod, file);
+    return asConfig(await loadConfigModule(file), file);
 }
 function asConfig(value, file) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -87,3 +124,6 @@ function asConfig(value, file) {
     delete config.$schema;
     return config;
 }
+/** The keys that decide *what a package is* and *what addresses it*, read from the unmarked
+ *  cascade before any package exists - see `assertSelectorBlocks`. */
+const IDENTITY_KEYS = ['platform', 'name'];

package/core/load-config-module.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Loads a config module - a `.rmanrc.cjs`/`.mjs`/`.js`, or an `extends` target that is one.
+ *
+ * **`require()` first, and that is not an optimization.** A CommonJS module's `module.exports` is
+ * more reliably observed this way than through dynamic `import()`'s CJS-interop synthesis, which
+ * some ESM loader hooks - ts-node/swc-node-style transpilers registered via `--import` - can
+ * short-circuit into an **empty object**. `require()` throws `ERR_REQUIRE_ESM` for a genuinely-ESM
+ * file (`.mjs`, or `.js` under `"type": "module"`), and only then does this fall back to
+ * `import()`, the one case that actually needs it.
+ *
+ * Either path can hand back an ES module namespace rather than a plain object - Node's
+ * `require(esm)` support does this too, not just `import()` - so `.default` is preferred whenever
+ * present.
+ *
+ * **It lives here because `extends` needs it too, and did not have it.** A directory's own
+ * `.rmanrc.cjs` went through this while `extends-config.ts` used a bare `await import()`, so the
+ * *same file* loaded correctly as a directory's config and came back empty when another config
+ * named it - and an empty object is a valid config, so nothing was reported. Measured under mocha:
+ * a base declaring `"[*]": { version: { stamp: ['build'] } }`, reached by
+ * `extends: './base.cjs'`, contributed nothing; the identical fixture with `base.json` contributed
+ * normally, and the same `.cjs` worked from the CLI, where no loader hook is registered.
+ *
+ * `createRequire` is based on this module's own URL rather than on the config file. That is right
+ * here and *not* right for resolving a bare specifier - see `resolveConfigTarget`, which is based
+ * on the config file so a package name resolves through the repository's `node_modules` rather than
+ * rman's own. By the time a file reaches this function it is already an absolute path.
+ */
+export declare function loadConfigModule(file: string): Promise<any>;

package/core/load-config-module.js

@@ -0,0 +1,42 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+/**
+ * Loads a config module - a `.rmanrc.cjs`/`.mjs`/`.js`, or an `extends` target that is one.
+ *
+ * **`require()` first, and that is not an optimization.** A CommonJS module's `module.exports` is
+ * more reliably observed this way than through dynamic `import()`'s CJS-interop synthesis, which
+ * some ESM loader hooks - ts-node/swc-node-style transpilers registered via `--import` - can
+ * short-circuit into an **empty object**. `require()` throws `ERR_REQUIRE_ESM` for a genuinely-ESM
+ * file (`.mjs`, or `.js` under `"type": "module"`), and only then does this fall back to
+ * `import()`, the one case that actually needs it.
+ *
+ * Either path can hand back an ES module namespace rather than a plain object - Node's
+ * `require(esm)` support does this too, not just `import()` - so `.default` is preferred whenever
+ * present.
+ *
+ * **It lives here because `extends` needs it too, and did not have it.** A directory's own
+ * `.rmanrc.cjs` went through this while `extends-config.ts` used a bare `await import()`, so the
+ * *same file* loaded correctly as a directory's config and came back empty when another config
+ * named it - and an empty object is a valid config, so nothing was reported. Measured under mocha:
+ * a base declaring `"[*]": { version: { stamp: ['build'] } }`, reached by
+ * `extends: './base.cjs'`, contributed nothing; the identical fixture with `base.json` contributed
+ * normally, and the same `.cjs` worked from the CLI, where no loader hook is registered.
+ *
+ * `createRequire` is based on this module's own URL rather than on the config file. That is right
+ * here and *not* right for resolving a bare specifier - see `resolveConfigTarget`, which is based
+ * on the config file so a package name resolves through the repository's `node_modules` rather than
+ * rman's own. By the time a file reaches this function it is already an absolute path.
+ */
+export async function loadConfigModule(file) {
+    let mod;
+    try {
+        mod = requireConfigModule(file);
+    }
+    catch (e) {
+        if (e?.code !== 'ERR_REQUIRE_ESM')
+            throw e;
+        mod = await import(pathToFileURL(file).href);
+    }
+    return mod?.default ?? mod;
+}
+const requireConfigModule = createRequire(import.meta.url);

package/core/manifest.d.ts

@@ -1,4 +1,6 @@
+import { RmanApplication } from './application.js';
 import type { Package } from './package.js';
+import type { Platform } from './plugin.js';
 import { type VersionScheme } from './version-scheme.js';
 /**
  * A package's identity, however its ecosystem happens to record it.
@@ -13,7 +15,7 @@ export interface Manifest {
     /** Excluded from publishing by the package's own declaration (`package.json#private`). Not the
      *  same as `.rmanrc "publish.skip"`, which is the *repository's* declaration about it. */
     private?: boolean;
-    /** The document as the ecosystem wrote it. `rman-node`'s own commands read `package.json` fields
+    /** The document as the ecosystem wrote it. The `node` built-in's own commands read `package.json` fields
      *  the core has no opinion about (`scripts`, `publishConfig`, `engines`) off this. */
     raw: any;
 }
@@ -23,7 +25,7 @@ export interface Manifest {
  * **The core has no provider.** "The name and version live in a `package.json`" is true of npm and
  * of nothing else - a `Cargo.toml`, a `pyproject.toml` and a `go.mod` each say the same thing
  * differently, and the version is not even in the same *kind* of place in all of them.
- * `rman-node` contributes the `package.json` one.
+ * The `node` built-in contributes the `package.json` one.
  *
  * Paired with `VersionScheme` on purpose: the ecosystem that decides *where* a version is written
  * is the one that decides *how* it is numbered, so a provider supplies both and a package gets a
@@ -32,7 +34,7 @@ export interface Manifest {
 export interface ManifestProvider {
     /**
      * **The ecosystem this provider speaks for**, surfaced on every package it reads as
-     * `Package.provider` - `'node'` for `rman-node`. Short and about the technology, not about the
+     * `Package.provider` - `'node'` for the built-in of that name. Short and about the technology, not about the
      * file: `fileName` already says `package.json`, and a name repeating it would tell a caller
      * nothing it did not have.
      *
@@ -124,6 +126,23 @@ export interface ManifestProvider {
         scope?: string;
         unscopedName: string;
     };
+    /**
+     * **What addresses this package** - what a `"[glob]"` block and `--scope`/`--ignore` match
+     * against, and what has to be unique within a repository.
+     *
+     * **The platform's job, because a name is an ecosystem's promise and not rman's.** npm guarantees
+     * `package.json#name` exists and identifies the package, so the node built-in has nothing to do
+     * here and the default - the manifest's own name - is already its answer. An ecosystem where a
+     * package need not be named, or where the name is not unique, returns `undefined` and the
+     * repository assigns one with `.rmanrc "name"`.
+     *
+     * Separate from `Manifest.name`, which is what the package *calls itself*: those coincide for npm
+     * and need not anywhere else. A Go module's name is an import path, and `--scope github.com/x/y`
+     * is not how anyone would want to address it.
+     *
+     * Omit it and the manifest's name is used, so this seam existing changes nothing.
+     */
+    selector?(manifest: Manifest, dir: string): string | undefined;
     /**
      * Rewrites this manifest's references to in-repo packages that just got a new version.
      *
@@ -147,35 +166,37 @@ export interface ManifestProvider {
  *
  * A namespace rather than loose `addManifestProvider`/`readManifest` functions because a namespace
  * is what a plugin can *augment*: `declare module 'rman' { namespace Manifest { ... } }` is how
- * `rman-node` already adds to `SystemInfo`, and anything this seam grows later can arrive the
+ * the `node` built-in already adds to `SystemInfo`, and anything this seam grows later can arrive the
  * same way instead of as another top-level export.
  */
 export declare namespace Manifest {
-    /** Registers a provider. Called by `loadPlugins` for each plugin's `manifest`, in `plugins`
-     *  declaration order - so which one answers is a function of the repository's own config. */
-    function addProvider(provider: ManifestProvider): void;
-    /** For tests, which would otherwise leak a provider into every later case in the process. */
-    function clearProviders(): void;
     /**
-     * Reads `dir`'s manifest through the first provider that recognizes it, with the scheme that
-     * provider brings.
-     *
-     * **With no provider registered, or none recognizing the directory**, the fallback is a package
-     * named after its own directory at version `0.0.0`. That is deliberately the least it can claim:
-     * the directory name is a fact, and `0.0.0` is the version a thing has when nothing says
-     * otherwise. The alternative - refusing to construct a package at all - would make `rman info` and
-     * `rman list` fail in a repository whose `.rmanrc` simply names no plugin yet, which is exactly
-     * when someone needs to run them.
+     * Reads `dir`'s manifest through **the platform that already claimed it**, with the scheme that
+     * platform brings.
+     *
+     * **It takes a platform rather than searching for one**, and that is where the walk changed
+     * things. This used to loop over every registered platform, once per `Package` constructed - so a
+     * package asked "who am I?" and the answer was whoever recognized it first, re-derived at every
+     * construction. The walk decides it once per directory now (`Workspace.walk` ->
+     * `app.platformFor`) and hands it to the package, which is also what lets a nested Cargo package
+     * sit inside a Node monorepo: the platform is a fact about the directory, established by whoever
+     * found it, not re-guessed by whoever reads it.
+     *
+     * **When that platform reads nothing** - `basePlatform`, or a provider that claimed the directory
+     * and then found nothing in it - the fallback is a package named after its own directory at
+     * version `0.0.0`. Deliberately the least it can claim: the directory name is a fact, and `0.0.0`
+     * is the version a thing has when nothing says otherwise. The alternative - refusing to construct
+     * a package at all - would make `rman info` and `rman list` fail in a repository whose `.rmanrc`
+     * simply names no plugin yet, which is exactly when someone needs to run them.
      */
-    function read(dir: string): {
+    function read(platform: Platform, dir: string): {
         manifest: Manifest;
         versionScheme: VersionScheme;
         fileName: string;
-        provider: string;
     };
     /** Writes through whichever provider recognizes `dir`. Throws when none does: a write that lands
      *  nowhere is worse than one that fails, since the caller has already decided the new version. */
-    function write(dir: string, manifest: Manifest): void;
+    function write(app: RmanApplication, dir: string, manifest: Manifest): void;
     /**
      * The packages `pkg` declares a dependency on, via whichever provider recognizes it.
      *
@@ -186,7 +207,7 @@ export declare namespace Manifest {
     function dependenciesOf(pkg: Package, candidates: readonly Package[]): Package[];
     /** `${{ pkg.scope }}`/`${{ pkg.unscopedName }}`, by whichever provider recognizes `dir` - and
      *  "no scope, the name is its own unscoped form" when none has an opinion. */
-    function splitName(dir: string, name: string): {
+    function splitName(app: RmanApplication, dir: string, name: string): {
         scope?: string;
         unscopedName: string;
     };
@@ -199,7 +220,7 @@ export declare namespace Manifest {
     function updateDependencyVersions(pkg: Package, bumped: ReadonlyMap<Package, string>): void;
     /**
      * Rewrites a hard-coded version in `content` through `pkg`'s own ecosystem - see
-     * `ManifestProvider.stampVersion`.
+     * `Plugin.stampVersion`.
      *
      * `undefined` covers three cases the caller has to tell apart from each other, and cannot: no
      * provider claimed the package, the provider has no opinion about stamping, or it looked and found
@@ -217,6 +238,7 @@ export declare namespace Manifest {
      * plugin: git tags then answer the boundary question alone.
      */
     function publishedVersion(pkg: Package): Promise<string | undefined>;
-    /** The file names providers look for, for an error message that can say what was expected. */
-    function fileNames(): string[];
+    /** The file names the registered technologies look for, for an error message that can say what
+     *  was expected. */
+    function fileNames(app: RmanApplication): string[];
 }