rman 1.3.0 → 2.0.0-beta.2

package/interfaces/rman-config.interface.js

@@ -1 +1,61 @@
-export {};
+export const commandRegistry = [];
+/**
+ * Registers a command and hands the register function straight back.
+ *
+ * **It returns the function, not the command's config, and that is the point.** The function has
+ * not run yet - it runs during init, once there is a `Repository` - so at registration time no
+ * config object exists to return. Declaring one anyway is what made the old body
+ * (`return def['config']`) uncompilable: `def` is a function, and `config` belongs to what it
+ * *returns*.
+ *
+ * Nothing is lost by being honest, because the metadata type rides along on the return type:
+ * `ReturnType<typeof someCommand>` is the `CommandMetadata`, and `CommandConfigFromMetadata` maps
+ * it to the config object the command contributes. A phantom property carrying the config type was
+ * tried and is unnecessary for exactly this reason - and it would not have survived being stored in
+ * `commandRegistry`, whose element type erases it.
+ *
+ * **`M` is inferred from the metadata rather than from the function, so that the same position can
+ * check it.** With the plainer `<T extends CommandRegisterFunction>(def: T)`, `T` is inferred from
+ * the literal itself, so the constraint is a subtype check - and a subtype check does no
+ * excess-property checking. Measured: `anotherBogusTopLevelKey: true` and a `totallyBogusKey`
+ * inside an option both compiled silently, which is how `cliName` and `examples` went unnoticed in
+ * `version.command.ts`. `M & ValidMeta<M>` keeps the bare `M` as the inference site and puts the
+ * check beside it, so a misspelled key now errors on its own line and names itself.
+ *
+ * **A command's `command` string needs `as const`** for the config key to be derivable from it
+ * (`'version [bump]' as const` -> `'version'`). `type: 'string'` survives inference on its own,
+ * since `yargs.Options['type']` is a union of literals and a union suppresses widening; `command`
+ * is a plain `string`, so it widens without the assertion. Spelling it `` `${string}` `` does not
+ * help - measured; that trick only applies where the constraint sits on the generic parameter.
+ */
+export function registerCommand(def) {
+    /** The same cast `declareCommand` makes, rather than a call to it: passing `def` through would
+     *  re-infer `M` from a type that already carries `ValidMeta<M>`, and the check then compounds
+     *  onto itself (`Exact<M & Exact<M, …>, …>`) and fails on every command. Two lines, one cast
+     *  each, is the honest shape. */
+    const fn = def;
+    commandRegistry.push(fn);
+    return fn;
+}
+/**
+ * The same declaration, **without** the registration - for a command that must exist only when
+ * something asks for it.
+ *
+ * That is exactly a contributed command's situation: `commandRegistry` is a module-level array
+ * walked by every `runCli`, so a package pushing onto it would give its commands to repositories
+ * that never named it - the module is imported as soon as anything imports the package. A package
+ * puts the function in its config's `commands` instead, and `cli.ts` calls it once the repository
+ * exists.
+ *
+ * **Why a factory rather than the metadata itself**: the config is resolved *inside*
+ * `Repository.create`, before the packages are known (plugins are what find them), so
+ * `app.repository` throws at that point. The function is stored unrun and called later, in
+ * `cli.ts`, where the built-ins' own factories run.
+ *
+ * Everything `registerCommand` documents about inference - `M & ValidMeta<M>`, the `as const` on
+ * `command`, the metadata riding on the return type - applies here unchanged; the two differ in one
+ * line.
+ */
+export function declareCommand(def) {
+    return def;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.3.0",
+  "version": "2.0.0-beta.2",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
+    "@netlify/parse-npm-script": "^0.1.2",
     "@xmldom/xmldom": "^0.9.12",
     "ansi-colors": "^4.1.3",
     "cross-dirname": "^0.1.0",

package/plugins/builtins.d.ts

@@ -0,0 +1,44 @@
+import type { Platform } from '../core/plugin.js';
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
+/**
+ * **The plugins rman ships in the box, by the name a config calls them.**
+ *
+ * `plugins: ['node']` is the whole of it - no new key, because there is no new concept. A
+ * repository was always able to say which technologies it holds; this is that same statement with
+ * a name instead of an instance, which is the form a YAML config and a zero-config repository both
+ * need.
+ *
+ * **Bundled is not the same as always on, and keeping those apart is the point.** Nothing an entry
+ * contributes exists until a repository names it or detection finds it, so the core still assumes
+ * no ecosystem and `rman clean` is still `Unknown argument` in a repository that is not a Node one.
+ * What changed is only where the code is shipped from - one install instead of two, which is what
+ * `extends: 'rman-node'` was costing every Node repository for a benefit that belonged to polyglot
+ * ones.
+ *
+ * The key is `Plugin.name`, so what a config writes is what `${{ pkg.provider }}` reads back.
+ *
+ * **A published package is still not one of these.** `plugins: ['rman-node']` names a package, whose
+ * config reaches a repository through `extends`; it is refused, saying so. The two are different
+ * statements and a built-in name is neither of them - it is the plugin itself, called by name.
+ */
+export declare const BUILTIN_PLUGINS: Record<string, Builtin>;
+/**
+ * One built-in, in the two halves that must not be the same call.
+ *
+ * **`plugin` answers questions; `contribute` changes the run.** Detection asks a platform whether a
+ * directory is its own, which has to be possible without registering anything - and registering is
+ * what `contribute` does: it hands over commands, publish targets and (for `node`) an augmentation
+ * that rewrites the core's `SystemInfo` in place. One call for both would have "is this a Node
+ * repository?" print npm's tooling in a Cargo one, which is exactly the line between *bundled* and
+ * *on*.
+ */
+export interface Builtin {
+    /** The platform itself, for asking - constructed, registered nowhere, with no side effect. */
+    platform: () => Platform;
+    /** Everything this built-in adds to a repository that asked for it. */
+    contribute: () => RmanConfig;
+}
+/** Whether `name` is one rman ships - the check `plugins` makes before treating a string as a glob. */
+export declare function isBuiltinPlugin(name: string): boolean;
+/** The built-in names, for an error message that has to list what a repository could have meant. */
+export declare function builtinPluginNames(): string[];

package/plugins/builtins.js

@@ -0,0 +1,33 @@
+import { nodeBuiltin, nodePlatform } from './node/index.js';
+/**
+ * **The plugins rman ships in the box, by the name a config calls them.**
+ *
+ * `plugins: ['node']` is the whole of it - no new key, because there is no new concept. A
+ * repository was always able to say which technologies it holds; this is that same statement with
+ * a name instead of an instance, which is the form a YAML config and a zero-config repository both
+ * need.
+ *
+ * **Bundled is not the same as always on, and keeping those apart is the point.** Nothing an entry
+ * contributes exists until a repository names it or detection finds it, so the core still assumes
+ * no ecosystem and `rman clean` is still `Unknown argument` in a repository that is not a Node one.
+ * What changed is only where the code is shipped from - one install instead of two, which is what
+ * `extends: 'rman-node'` was costing every Node repository for a benefit that belonged to polyglot
+ * ones.
+ *
+ * The key is `Plugin.name`, so what a config writes is what `${{ pkg.provider }}` reads back.
+ *
+ * **A published package is still not one of these.** `plugins: ['rman-node']` names a package, whose
+ * config reaches a repository through `extends`; it is refused, saying so. The two are different
+ * statements and a built-in name is neither of them - it is the plugin itself, called by name.
+ */
+export const BUILTIN_PLUGINS = {
+    node: { platform: () => nodePlatform, contribute: nodeBuiltin },
+};
+/** Whether `name` is one rman ships - the check `plugins` makes before treating a string as a glob. */
+export function isBuiltinPlugin(name) {
+    return Object.hasOwn(BUILTIN_PLUGINS, name);
+}
+/** The built-in names, for an error message that has to list what a repository could have meant. */
+export function builtinPluginNames() {
+    return Object.keys(BUILTIN_PLUGINS).sort();
+}

package/plugins/detect.d.ts

@@ -0,0 +1,78 @@
+/**
+ * **Which platform a repository looks like, when it has not said.**
+ *
+ * The 2.0 split made every Node repository write a config file before `rman clean` would run, and
+ * the cost of that landed on exactly the repositories the split was not for. This is the other half
+ * of the fix: a repository that declares no technology gets the one its own files already imply.
+ *
+ * **The core does not know what any repository looks like, and must not.** It asks the *platforms*
+ * - `manifestProvider.read(dir)` has always meant "is this directory one of mine?", so there is no
+ * new seam and no list of filenames anywhere in `core/`. This file listed `package.json` for one
+ * commit, which is the same mistake as the hardcoded `['npm']` publish default that
+ * `PublishTarget.claims` exists to have replaced: true of npm, written in a place that speaks for
+ * every ecosystem, and invisible while only one platform ships.
+ *
+ * The platforms it can ask are the ones it has, which are the built-ins - by construction, not by
+ * choice: a third-party platform arrives through `plugins` or `extends`, and a repository that
+ * wrote either has declared its technology, so detection never runs for it.
+ *
+ * **Only ever consulted when nothing was declared** - see `Repository.create`, which checks both the
+ * config and the application. That boundary is the whole safety of it, because registering a
+ * platform changes *which directories are packages at all* (`Workspace.resolve` takes the first
+ * provider that answers), so guessing on top of an explicit statement could quietly change what
+ * `rman list` reports.
+ *
+ * **It is announced, not silent.** A guess the reader cannot see is one they cannot correct.
+ */
+export interface DetectedBuiltin {
+    /** The built-in's name - what `plugins: [...]` would have said. */
+    name: string;
+    /** The file that gave it away, for the message - the platform's own `manifestFile`. */
+    because: string;
+}
+/**
+ * Marks a config whose `plugins` was **detected rather than declared**, so the one caller that
+ * should say so can tell.
+ *
+ * A non-enumerable symbol, the way `ORIGINS` and `PREVIOUS_VALUES` already carry bookkeeping: it
+ * travels with the config through `mergeConfig`, `JSON.stringify` and `rman config` without any of
+ * them knowing it is there, and `expect`'s `toEqual` compares symbol properties - so a plain
+ * property would turn every config-shape spec into a diff about this.
+ *
+ * The alternative was re-deriving the answer where the message is printed, which means reading the
+ * config twice and two places that can disagree about what "declared" means.
+ */
+export declare const DETECTED_BUILTIN: unique symbol;
+/** What detection put on `config`, if anything. */
+export declare function detectedBuiltinOf(config: object): DetectedBuiltin | undefined;
+/**
+ * The first built-in platform that claims `dir`, or `undefined` for a repository none of them
+ * recognizes - which is the honest answer, not a default.
+ *
+ * **First match, in declaration order**, the same rule `Manifest.read` and `Workspace.resolve`
+ * already follow, so a repository two platforms both recognize resolves the same way here as it
+ * will once they are loaded.
+ *
+ * Memoized per directory: this is asked once per directory per package and each ask reads the disk.
+ * Nothing here writes, so the answer cannot change under a run in any way that matters.
+ *
+ * **Async only because `builtins.js` is imported dynamically, and that is a cycle rather than a
+ * style** - the same one `expandBuiltinPlugins` in `config.ts` already documents, reached from the
+ * other side. A built-in pulls in its commands and services; one of those services extends a core
+ * service, and the core's own module graph comes back through here:
+ *
+ * ```
+ * services/version-plan.service -> core/application -> core/core-services
+ *   -> services/github-release.service -> core/repository -> plugins/detect
+ *   -> plugins/builtins -> plugins/node/index -> plugins/node/node.platform
+ *   -> plugins/node/services/version-plan.service  (extends the first, still initialising)
+ * ```
+ *
+ * **Measured, and the suite could not see it**: the *built* CLI died on every command with
+ * `ReferenceError: Cannot access 'VersionPlanService' before initialization`, while `npm test`
+ * passed - mocha resolves `src` through `tsconfig-test.json`'s `paths`, which is a different module
+ * graph and happens to reach the two in the other order. `npm run smoke` is what looks now.
+ */
+export declare function detectBuiltin(dir: string): Promise<DetectedBuiltin | undefined>;
+/** Forgets what was detected - for a spec that writes a fixture, detects, then writes another. */
+export declare function clearDetectionCache(): void;

package/plugins/detect.js

@@ -0,0 +1,70 @@
+import path from 'node:path';
+/**
+ * Marks a config whose `plugins` was **detected rather than declared**, so the one caller that
+ * should say so can tell.
+ *
+ * A non-enumerable symbol, the way `ORIGINS` and `PREVIOUS_VALUES` already carry bookkeeping: it
+ * travels with the config through `mergeConfig`, `JSON.stringify` and `rman config` without any of
+ * them knowing it is there, and `expect`'s `toEqual` compares symbol properties - so a plain
+ * property would turn every config-shape spec into a diff about this.
+ *
+ * The alternative was re-deriving the answer where the message is printed, which means reading the
+ * config twice and two places that can disagree about what "declared" means.
+ */
+export const DETECTED_BUILTIN = Symbol('rman.detectedBuiltin');
+/** What detection put on `config`, if anything. */
+export function detectedBuiltinOf(config) {
+    return config[DETECTED_BUILTIN];
+}
+/**
+ * The first built-in platform that claims `dir`, or `undefined` for a repository none of them
+ * recognizes - which is the honest answer, not a default.
+ *
+ * **First match, in declaration order**, the same rule `Manifest.read` and `Workspace.resolve`
+ * already follow, so a repository two platforms both recognize resolves the same way here as it
+ * will once they are loaded.
+ *
+ * Memoized per directory: this is asked once per directory per package and each ask reads the disk.
+ * Nothing here writes, so the answer cannot change under a run in any way that matters.
+ *
+ * **Async only because `builtins.js` is imported dynamically, and that is a cycle rather than a
+ * style** - the same one `expandBuiltinPlugins` in `config.ts` already documents, reached from the
+ * other side. A built-in pulls in its commands and services; one of those services extends a core
+ * service, and the core's own module graph comes back through here:
+ *
+ * ```
+ * services/version-plan.service -> core/application -> core/core-services
+ *   -> services/github-release.service -> core/repository -> plugins/detect
+ *   -> plugins/builtins -> plugins/node/index -> plugins/node/node.platform
+ *   -> plugins/node/services/version-plan.service  (extends the first, still initialising)
+ * ```
+ *
+ * **Measured, and the suite could not see it**: the *built* CLI died on every command with
+ * `ReferenceError: Cannot access 'VersionPlanService' before initialization`, while `npm test`
+ * passed - mocha resolves `src` through `tsconfig-test.json`'s `paths`, which is a different module
+ * graph and happens to reach the two in the other order. `npm run smoke` is what looks now.
+ */
+export async function detectBuiltin(dir) {
+    const resolved = path.resolve(dir);
+    if (cache.has(resolved))
+        return cache.get(resolved);
+    const { BUILTIN_PLUGINS } = await import('./builtins.js');
+    let found;
+    for (const [name, builtin] of Object.entries(BUILTIN_PLUGINS)) {
+        const platform = builtin.platform();
+        /** `read` is the question. Its answer is thrown away - the manifest is read again for real once
+         *  the platform is registered, and reading it twice is cheaper than keeping a half-built
+         *  package around to decide whether it should exist. */
+        if (platform.manifestProvider.read(resolved)) {
+            found = { name, because: platform.manifestProvider.fileName };
+            break;
+        }
+    }
+    cache.set(resolved, found);
+    return found;
+}
+/** Forgets what was detected - for a spec that writes a fixture, detects, then writes another. */
+export function clearDetectionCache() {
+    cache.clear();
+}
+const cache = new Map();

package/plugins/node/augmentation/rman.augmentation.d.ts

@@ -0,0 +1,84 @@
+import type cleanCommand from '../commands/clean.command.js';
+import type { CleanExtraKeys } from '../commands/clean.command.js';
+import type { NodeConfigKeys, RmanNodeConfig } from '../node-config.interface.js';
+import type { CiService } from '../services/ci.service.js';
+/**
+ * **Every type this plugin adds to rman, in one `declare module` block.**
+ *
+ * **One block was once forced and is now only convenient.** While this shipped as its own package
+ * it augmented the *package name* `'rman'`, and a second such block anywhere silently disabled the
+ * first - measured, `SystemInfo.PackageManager` went unresolved at four call sites with nothing
+ * pointing at the cause. Bundled into rman, these augment a **module path** like every built-in
+ * command's own contribution does, and that limit is gone; they stay together because the plugin's
+ * types read better in one place, not because they have to.
+ *
+ * Type-only. The runtime half of each augmentation lives with its own subject
+ * (`augmentSystemInfo()`, `augmentManifest()`, ...); this file is imported by the plugin's entry
+ * point purely so a consumer's compiler loads it.
+ */
+declare module '../../../interfaces/rman-config.interface.js' {
+    /**
+     * The `.rmanrc` keys that only mean something in a Node repository - merged into the core's own
+     * key list, so `pkg.config.clean` is typed wherever it is read (`CleanService` included) without
+     * a cast, and without the core declaring a key it knows nothing about.
+     *
+     * The augmentation is evaluated where it is used, so `clean` is typed at the place it is read.
+     */
+    interface RmanConfigKeys extends NodeConfigKeys {
+    }
+    /**
+     * **`clean.*`, contributed by the command that reads it**, the way every built-in contributes its
+     * own key - `skip` derived from the command's `config` block, `include`/`exclude` hand-written in
+     * `CleanExtraKeys` because a `CommandOption` cannot say "a glob *or* a list of them".
+     *
+     * It is declared here rather than beside the command only because of the one-block rule above.
+     * rman's own commands put theirs next to themselves, augmenting a module path instead of a
+     * package name, which has no such limit.
+     */
+    namespace RmanConfig {
+        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof cleanCommand>, CleanExtraKeys> {
+        }
+    }
+}
+/**
+ * **The `npm` target's own `publish.*` block** - declared into the slot `publish` exports, exactly
+ * where the core's own `docker` target declares `publish.docker`.
+ *
+ * A *different* module from the block above, and that is the shape the fold made possible: while
+ * this shipped as `rman-node` everything had to augment the one package name `'rman'`, so a slot
+ * declared in `publish.command.ts` was reachable only by re-declaring it - which now reads as two
+ * interfaces of one name and is refused. Each interface is augmented where it lives.
+ */
+declare module '../../../commands/publish.command.js' {
+    /**
+     * The `npm` publish target's own `publish.*` block, declared the way the core's `docker` target
+     * declares `publish.docker` - through the slot `publish` contributes, rather than into a central
+     * `PublishOptionsKeys` that the core owned.
+     *
+     * That is the config half of a target being a contribution: this package brings the flags, the
+     * registry check, *and* the keys, and none of it is written down in rman.
+     */
+    interface PublishTargetConfigs {
+        /** The `npm` target's block, named after the target exactly as the core's `docker` one is. */
+        npm?: RmanNodeConfig.NpmPublishOptions;
+    }
+}
+/**
+ * **The npm half of `SystemInfo`** - what `rman info` reports once a repository is a Node one. The
+ * runtime half is `augmentSystemInfo()` in the file beside this one, called when the built-in is
+ * registered rather than at import, so a repository that never named it reports no npm.
+ */
+declare module '../../../services/system-info.js' {
+    namespace SystemInfo {
+        type PackageManager = CiService.PackageManager;
+        interface Options {
+            /**
+             * Report this package manager's version under `Binaries`, plus the `npmPackages` sections.
+             *
+             * Defaults to `.rmanrc "packageManager"` (read off `Options.repository`), then to `npm` -
+             * this package being installed is itself the statement that the repository is a Node one.
+             */
+            packageManager?: PackageManager;
+        }
+    }
+}

package/plugins/node/augmentation/rman.augmentation.js

@@ -0,0 +1 @@
+export {};

package/plugins/node/augmentation/system-info.augmentation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Adds the npm half of `SystemInfo` to rman's own types.
+ *
+ * The core's `Options` carries nothing language-specific on purpose, so `packageManager` is not a
+ * setting it hid behind a flag - it is a setting it does not have. Declaration merging is what lets
+ * this package add it as if it had always been there, `SystemInfo.PackageManager` included, without
+ * the core naming npm anywhere.
+ *
+ * The union itself is `CiService.PackageManager`, not a second copy: `ci` and `publish` already
+ * shell out to one of these, and two lists of the same four names drift the moment a fifth appears.
+ */
+/** The import above is aliased precisely so this block can use the real name: declaration merging
+ *  keys off the module specifier, not off any local binding, so `namespace SystemInfo` here *is*
+ *  rman's - and nothing shadows anything. */
+/** The `SystemInfo` types this file's wrapper relies on are declared in
+ *  [`rman.augmentation.ts`](rman.augmentation.ts), with the rest of this plugin's - one
+ *  `declare module` block per package, or the others stop applying. */
+/**
+ * Turns the npm half on at runtime.
+ *
+ * Applied by wrapping rather than by a flag on the core service: "is this a Node repository" is not
+ * a question rman's core should be able to ask, and a `nodejs: true` option there would be exactly
+ * that question wearing a different hat. The wrapper translates `packageManager` into the `envinfo`
+ * categories the core knows nothing about.
+ */
+export declare function augmentSystemInfo(): void;

package/plugins/node/augmentation/system-info.augmentation.js

@@ -0,0 +1,79 @@
+import { SystemInfo as OrgSystemInfo } from '../../../services/system-info.js';
+/**
+ * Adds the npm half of `SystemInfo` to rman's own types.
+ *
+ * The core's `Options` carries nothing language-specific on purpose, so `packageManager` is not a
+ * setting it hid behind a flag - it is a setting it does not have. Declaration merging is what lets
+ * this package add it as if it had always been there, `SystemInfo.PackageManager` included, without
+ * the core naming npm anywhere.
+ *
+ * The union itself is `CiService.PackageManager`, not a second copy: `ci` and `publish` already
+ * shell out to one of these, and two lists of the same four names drift the moment a fifth appears.
+ */
+/** The import above is aliased precisely so this block can use the real name: declaration merging
+ *  keys off the module specifier, not off any local binding, so `namespace SystemInfo` here *is*
+ *  rman's - and nothing shadows anything. */
+/** The `SystemInfo` types this file's wrapper relies on are declared in
+ *  [`rman.augmentation.ts`](rman.augmentation.ts), with the rest of this plugin's - one
+ *  `declare module` block per package, or the others stop applying. */
+/**
+ * Turns the npm half on at runtime.
+ *
+ * Applied by wrapping rather than by a flag on the core service: "is this a Node repository" is not
+ * a question rman's core should be able to ask, and a `nodejs: true` option there would be exactly
+ * that question wearing a different hat. The wrapper translates `packageManager` into the `envinfo`
+ * categories the core knows nothing about.
+ */
+export function augmentSystemInfo() {
+    const base = OrgSystemInfo.getSystemInfo;
+    /**
+     * Idempotent, and marked on **the function** rather than in a module-level flag: the flag made
+     * re-application impossible once anything had replaced `getSystemInfo` - a test substituting a
+     * stub, or a second augmentation layering on - so whether the wrapper was actually installed came
+     * down to import order. Asking the current implementation whether it is already wrapped cannot go
+     * stale that way.
+     */
+    if (base[AUGMENTED])
+        return;
+    /** A namespace's exported function is a property of a plain object at runtime, so this is an
+     *  ordinary assignment - the ESM *binding* is immutable, the object it points at is not. */
+    const wrapped = options => {
+        /** An explicit argument first, then the repository's own config, then npm. The config step is
+         *  why the core declares `Options.repository`: `rman info` passes only that, so without it a
+         *  pnpm repository would silently be reported as an npm one. */
+        const packageManager = options?.packageManager ?? asPackageManager(options?.repository?.config?.packageManager) ?? 'npm';
+        return base({
+            ...options,
+            envinfo: {
+                /** Replaces the core's `Binaries: ['Node']` - `envinfo` categories merge by key, not by
+                 *  concatenation, so the whole list has to be restated. */
+                Binaries: ['Node', PACKAGE_MANAGER_BINARY[packageManager]],
+                /** This package's own version alongside rman's - when `info` is being read to work out why
+                 *  a command behaved oddly, which plugin version is installed is half the answer. */
+                npmPackages: ['rman', 'typescript'],
+                npmGlobalPackages: ['typescript'],
+                ...options?.envinfo,
+            },
+        });
+    };
+    wrapped[AUGMENTED] = true;
+    OrgSystemInfo.getSystemInfo = wrapped;
+}
+/** `.rmanrc "packageManager"` value -> the `Binaries` key `envinfo` recognizes for it (`npm`/
+ *  `pnpm`/`bun` are lowercase, `Yarn` isn't - envinfo's own naming, not ours). */
+const PACKAGE_MANAGER_BINARY = {
+    npm: 'npm',
+    yarn: 'Yarn',
+    pnpm: 'pnpm',
+    bun: 'bun',
+};
+/** A config value is whatever the file said, so an unrecognized one is ignored rather than used to
+ *  index `PACKAGE_MANAGER_BINARY` and produce `Binaries: ['Node', undefined]`. */
+function asPackageManager(value) {
+    return typeof value === 'string' && value in PACKAGE_MANAGER_BINARY
+        ? value
+        : undefined;
+}
+/** Marks an implementation as already wrapped. A symbol rather than a property name so it cannot
+ *  collide with anything `envinfo` or a future core option carries. */
+const AUGMENTED = Symbol.for('rman.node.systemInfo.augmented');

package/plugins/node/commands/ci.command.d.ts

@@ -0,0 +1,131 @@
+import type { ArgsOf } from '../../../index.js';
+/** Hoisted out of the metadata literal so the handler can be annotated against them - see
+ *  `RmanConfig.ArgsOf` for why an inferred `argv` and the metadata's own typo checking cannot both
+ *  work in one signature. */
+declare const COMMAND: "ci";
+declare const config: {
+    packageManager: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        choices: readonly ["npm", "yarn", "pnpm", "bun"];
+    };
+    progress: {
+        target: "cli";
+        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 = ArgsOf<typeof config, typeof COMMAND>;
+/**
+ * `rman ci` - contributed by the `node` built-in rather than always present.
+ *
+ * **Declared, not built.** This was a `CustomCommand` with a hand-written `builder` chaining
+ * `applyBranchGuardOptions(applyPackageFilterOptions(cmd))`, which is the shape every built-in had
+ * before the options became data. A plugin's command uses the identical declaration now -
+ * `declareCommand` rather than `registerCommand`, which is the one difference and the reason for
+ * it: `registerCommand` pushes onto a module-level registry that `runCli` always walks, so a plugin
+ * using it would hand `ci` to repositories that are not Node ones.
+ *
+ * The repository arrives through `app` when the factory runs (in `cli.ts`, after `Repository.create`
+ * has attached one), rather than through a `CommandContext` per invocation.
+ */
+declare const ciCommand: (app: import("../../../index.js").RmanApplication) => {
+    command: "ci";
+    describe: string;
+    /** Read, not owned: `packageManager` is a root-level key this package declares in
+     *  `NodeConfigKeys`, and the `npm` publish target reads it too. */
+    configKeys: string[];
+    config: {
+        packageManager: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            choices: readonly ["npm", "yarn", "pnpm", "bun"];
+        };
+        progress: {
+            target: "cli";
+            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;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default ciCommand;