rman 2.0.0-beta.4 → 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

@@ -207,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}`
@@ -262,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',
@@ -361,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)
@@ -375,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/constants.js

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

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.4",
+  "version": "2.0.0-beta.5",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {