rman 1.3.0 → 2.0.0-beta.2

package/core/config.js

@@ -2,13 +2,13 @@ import { DOMParser } from '@xmldom/xmldom';
 import fs from 'fs';
 import ini from 'ini';
 import * as yaml from 'js-yaml';
-import { createRequire } from 'module';
 import path from 'path';
 import semver from 'semver';
-import { pathToFileURL } from 'url';
 import vm from 'vm';
-import { assertNoSelectorExtends, EXTENDS_KEY, resolveExtends } from './extends-config.js';
-import { finalizeConfig, mergeConfig, ORIGINS, PREVIOUS_VALUES } from './merge-config.js';
+import { DETECTED_BUILTIN } from '../plugins/detect.js';
+import { assertSelectorBlocks, EXTENDS_KEY, resolveExtends } from './extends-config.js';
+import { loadConfigModule } from './load-config-module.js';
+import { mergeConfig, ORIGINS, PREVIOUS_VALUES } from './merge-config.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
@@ -31,35 +31,18 @@ export function defineConfig(config) {
  *  or a `.js` under a `"type": "commonjs"` package.json) and native ESM (`.mjs`, or a `.js` under
  *  `"type": "module"`) are supported - the reason `readDirConfig`/`resolveConfig` are async at all. */
 const JS_CONFIG_FILES = ['.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
-const requireJsConfig = createRequire(import.meta.url);
-/**
- * Loads `file`'s config object. Tries `require()` first - not just 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 (e.g. ts-node/swc-node-style transpilers
- * registered via `--import`) can end up short-circuiting into an empty object. `require()` throws
- * `ERR_REQUIRE_ESM` for a genuinely-ESM file (`.mjs`, or `.js` under `"type": "module"`) - only
- * then does this fall back to `import()`, the one case that actually needs it. Either path can
- * hand back an ES module namespace instead of a plain object (Node's `require(esm)` support does
- * this too, not just `import()`), so `.default` is preferred whenever present.
- */
-async function loadJsConfig(file) {
-    let mod;
-    try {
-        mod = requireJsConfig(file);
-    }
-    catch (e) {
-        if (e?.code !== 'ERR_REQUIRE_ESM')
-            throw e;
-        mod = await import(pathToFileURL(file).href);
-    }
-    return mod?.default ?? mod;
-}
 /**
  * Reads the rman configuration defined at a single directory level, merging
  * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
  * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
+ *
+ * `options.inject` supplies a built-in for a repository that declared no technology - **already
+ * decided**, rather than a "please detect" flag. The decision needs the application (a programmatic
+ * caller or a spec may have registered a technology without writing it in a config), which this
+ * function has no business knowing about; `Repository.create` makes it once and hands the answer
+ * to every read that has to agree with it. See `detectBuiltin`.
  */
-export async function readDirConfig(dirname) {
+export async function readDirConfig(dirname, options) {
     const result = {};
     /** The file an `extends` in this directory resolves relative to. The last form that actually
      *  declared one wins, which matters only for the unusual directory holding several. */
@@ -68,7 +51,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(pkgJsonFile)) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonFile, 'utf-8'));
         if (pkgJson && typeof pkgJson.rman === 'object') {
-            assertNoSelectorExtends(pkgJson.rman, pkgJsonFile);
+            assertSelectorBlocks(pkgJson.rman, pkgJsonFile);
             if (EXTENDS_KEY in pkgJson.rman)
                 extendsFrom = pkgJsonFile;
             mergeConfig(result, pkgJson.rman, pkgJsonFile);
@@ -78,7 +61,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(ymlFile)) {
         const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
         if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, ymlFile);
+            assertSelectorBlocks(obj, ymlFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = ymlFile;
             mergeConfig(result, obj, ymlFile);
@@ -88,7 +71,7 @@ export async function readDirConfig(dirname) {
     if (fs.existsSync(rcFile)) {
         const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
         if (obj && typeof obj === 'object') {
-            assertNoSelectorExtends(obj, rcFile);
+            assertSelectorBlocks(obj, rcFile);
             if (EXTENDS_KEY in obj)
                 extendsFrom = rcFile;
             mergeConfig(result, obj, rcFile);
@@ -97,9 +80,9 @@ export async function readDirConfig(dirname) {
     for (const jsFileName of JS_CONFIG_FILES) {
         const jsFile = path.join(dirname, jsFileName);
         if (fs.existsSync(jsFile)) {
-            const obj = await loadJsConfig(jsFile);
+            const obj = await loadConfigModule(jsFile);
             if (obj && typeof obj === 'object') {
-                assertNoSelectorExtends(obj, jsFile);
+                assertSelectorBlocks(obj, jsFile);
                 if (EXTENDS_KEY in obj)
                     extendsFrom = jsFile;
                 mergeConfig(result, obj, jsFile);
@@ -110,7 +93,107 @@ export async function readDirConfig(dirname) {
      *  one of them sits on, and the directory chain then layers on top as it always did. Each form
      *  was checked for a misplaced `extends` as it was read, so that error can name the file holding
      *  it rather than whichever form happened to declare the real one. */
-    return resolveExtends(result, extendsFrom);
+    const resolved = await resolveExtends(result, extendsFrom);
+    /**
+     * **After `extends`, because a base may be what declares the technology** - a shared config
+     * naming `plugins` is a statement, and detecting on top of it would be guessing over an answer.
+     * `plugins` being *present* is what counts, so `plugins: []` is a repository saying "none".
+     */
+    const detected = options?.inject && resolved.plugins === undefined ? options.inject : undefined;
+    if (detected)
+        resolved.plugins = [detected.name];
+    const expanded = await expandBuiltinPlugins(resolved);
+    /**
+     * **Marked after the expansion, not before, because the expansion rebuilds the object.**
+     * `expandBuiltinPlugins` merges the built-in's config underneath and returns a *new* config, so a
+     * symbol set on the way in is simply gone on the way out - measured: detection worked and the
+     * "detected" line never printed. The same trap `PREVIOUS_VALUES` and `ORIGINS` document from the
+     * other side, where `mergeConfig` has to copy them across by hand.
+     */
+    if (detected) {
+        Object.defineProperty(expanded, DETECTED_BUILTIN, { value: detected, enumerable: false, configurable: true });
+    }
+    return expanded;
+}
+/**
+ * Turns a built-in **name** in `plugins` into what that built-in contributes - `['node']` into the
+ * node plugin, its two commands and its publish target.
+ *
+ * **Here, beside `extends`, because it is the same operation**: something named brings a config,
+ * and that config sits *underneath* the one naming it. Doing it anywhere later would not reach far
+ * enough - `commands` is read off the resolved root package by `cli.ts`, not off the raw config
+ * `Repository.create` hands to `loadPlugins`, so a built-in expanded only there would register its
+ * technology and silently lose its commands.
+ *
+ * **The name is consumed.** `plugins` always appends, so leaving the string beside the instance it
+ * expanded into would hand `loadPlugins` a glob that matches no file - the built-in would load and
+ * then the run would fail saying it did not.
+ *
+ * Runs per directory, like `extends`, but only the root's `plugins` is ever read (`loadPlugins`
+ * needs the technologies before any package exists). The cost of walking a key that is almost
+ * always absent is one `Array.isArray`.
+ */
+async function expandBuiltinPlugins(config) {
+    const declared = config.plugins;
+    const own = Array.isArray(declared) ? declared : declared === undefined ? [] : [declared];
+    const platform = declaredPlatform(config);
+    if (!own.some(e => typeof e === 'string') && platform === undefined)
+        return config;
+    /**
+     * **Imported here rather than at the top, and that is a cycle rather than a style.** A built-in
+     * pulls in its commands and services, which read config - so a static import would have
+     * `config.ts` and the plugin subtree initialising each other, which in ESM half-works and fails
+     * silently. Node caches the module, so the cost is one resolution on a config that names one.
+     */
+    const { BUILTIN_PLUGINS, isBuiltinPlugin } = await import('../plugins/builtins.js');
+    /**
+     * **A `platform` naming a built-in puts it at the front of `plugins`.**
+     *
+     * Saying which technology this repository is *is* saying it has it, so making the author write
+     * both was a distinction only rman could see. Measured on the repository this was noticed in:
+     * `platform: 'node'` alone gave a working `rman list` with a `node` column and
+     * `Unknown arguments: clean`, because the technology had loaded and its commands had not.
+     *
+     * **At the front, not the back**, and that is what makes it a statement rather than an addition:
+     * `platformFor` takes the first registered platform that recognizes a directory, so the one this
+     * repository says it *is* should win over anything a shared config brought along.
+     *
+     * **Only a built-in**, checked after the import above for exactly this reason: a `platform` naming
+     * a third-party technology is answered by the `plugins` entry that loads it, and pushing the bare
+     * name in here would hand `loadPlugins` a glob matching no file - the failure would read as the
+     * plugin being missing when it is registered perfectly well.
+     *
+     * Already named, and nothing happens: `plugins` de-duplicates, and this keeps the author's own
+     * ordering rather than promoting an entry they placed deliberately.
+     */
+    const entries = platform !== undefined && isBuiltinPlugin(platform) && !own.includes(platform) ? [platform, ...own] : own;
+    const named = entries.filter((e) => typeof e === 'string' && isBuiltinPlugin(e));
+    if (!named.length)
+        return config;
+    const base = {};
+    /** De-duplicated first: two layers naming the same built-in is ordinary (a shared config and the
+     *  repository that inherits it), and registering a plugin twice defines its commands twice. */
+    for (const name of [...new Set(named)])
+        mergeConfig(base, BUILTIN_PLUGINS[name].contribute());
+    const result = { ...config };
+    result.plugins = entries.filter(e => !(typeof e === 'string' && isBuiltinPlugin(e)));
+    return mergeConfig(base, result);
+}
+/**
+ * The **root's** declared platform, however it was spelled - unmarked, or inside a `"[/]"` block.
+ *
+ * Both, because both are the root saying what it is and a reader would not expect one to bring the
+ * built-in and the other not. `"[/]"` is the precise spelling (it speaks for the root package
+ * alone, where an unmarked key also cascades to every package below), so leaving it out would have
+ * punished the more careful author.
+ *
+ * A glob block is not consulted and cannot be: `assertSelectorBlocks` refuses `platform` there,
+ * since the glob matches a selector the key is upstream of.
+ */
+function declaredPlatform(config) {
+    const root = config[`[${ROOT_SELECTOR_INNER}]`];
+    const declared = config.platform ?? (root && typeof root === 'object' ? root.platform : undefined);
+    return typeof declared === 'string' && declared.trim() ? declared.trim() : undefined;
 }
 /**
  * Resolves the effective config for the package at `targetDir`, cascading from `rootDir` down to
@@ -139,10 +222,27 @@ export async function readDirConfig(dirname) {
  * repo-wide bookend therefore belongs under `"[/]"`, where its audience is visible; that is the
  * migration this change asks for, and the only one that is not mechanical.
  *
- * `packageName` is what selectors match against; without it, selector blocks contribute nothing at
- * all. The root package passes its own, since `"[/]"` speaks to it.
+ * **`selector` is what a `"[glob]"` block matches** - `Package.selector`, which is the package's
+ * `.rmanrc "name"` if it declares one and its platform's answer otherwise. Without it, glob blocks
+ * contribute nothing: the walk resolves config for a directory *before* the package exists, since
+ * that is where `platform` and `name` are read from, and a glob has nothing to match against yet.
+ *
+ * **`"[/]"` needs no selector, and that is the documented rule rather than an exception.** The root
+ * is addressed structurally - its directory *is* the repository root - which is the whole reason it
+ * is `/` and not a name. So a root block applies whenever the target is the root, named or not, and
+ * `platform` under `"[/]"` therefore works during the walk. It did not until this was noticed: the
+ * gate was `if (packageName)`, so the walk skipped every selector block including that one, and the
+ * key documented as "keeps it on the root package alone" silently did nothing.
+ *
+ * It was called `packageName`, which was wrong twice over: a package is not guaranteed to have a
+ * name (that is an ecosystem's promise, not rman's), and what this matches is the selector, which a
+ * repository can assign itself.
  */
-export async function resolveConfig(rootDir, targetDir, cache = new Map(), packageName) {
+export async function resolveConfig(rootDir, targetDir, cache = new Map(), selector, 
+/** The built-in `Repository.create` decided on, for a repository that declared no technology.
+ *  Applied at the **root level only** - `plugins` is read nowhere else, and this is the read whose
+ *  result becomes `pkg.config`, which is where `cli.ts` finds a built-in's `commands`. */
+inject) {
     const result = {};
     const target = path.resolve(targetDir);
     /** The root *package* is the one whose directory is the repository root - no other test is
@@ -152,7 +252,9 @@ export async function resolveConfig(rootDir, targetDir, cache = new Map(), packa
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
         if (!local) {
-            local = await readDirConfig(dir);
+            local = await readDirConfig(dir, {
+                inject: path.resolve(dir) === path.resolve(rootDir) ? inject : undefined,
+            });
             cache.set(dir, local);
         }
         /**
@@ -167,16 +269,14 @@ export async function resolveConfig(rootDir, targetDir, cache = new Map(), packa
          * layer that feeds the directories below it.
          */
         mergeConfig(result, stripSelectors(local));
-        /** Then the selector blocks, **in the order they were written** - see `matchingSelectors`. */
-        if (packageName) {
-            for (const block of matchingSelectors(local, packageName, isRoot))
+        /** Then the selector blocks, **in the order they were written** - see `matchingSelectors`.
+         *  Reached for the root even with no selector, since `"[/]"` is structural. */
+        if (selector !== undefined || isRoot) {
+            for (const block of matchingSelectors(local, selector, isRoot))
                 mergeConfig(result, block);
         }
     }
-    /** Every layer has had its turn, so an append still outstanding has nothing left to attach to
-     *  and becomes the value itself. Done here rather than per layer: until the chain is finished,
-     *  the key it appends to may still be coming. */
-    return finalizeConfig(result);
+    return result;
 }
 /** A config key naming packages rather than settings: `"[*]"`, `"[/]"`, `"[pkg-a]"`. The
  *  brackets are what keep this space from colliding with real config keys - no setting starts with
@@ -236,13 +336,15 @@ export function selectorToRegExp(key) {
  * The cost, which the docs state rather than hide: a catch-all written *below* a narrower block now
  * overrides it. Writing catch-alls first is a convention, not a rule - the file reads top to bottom.
  */
-function matchingSelectors(config, packageName, isRoot) {
+function matchingSelectors(config, selector, isRoot) {
     const matches = [];
     for (const [key, value] of Object.entries(config)) {
         if (!isSelectorKey(key) || !value || typeof value !== 'object')
             continue;
         const { scope, test } = parseSelector(key);
-        if (scope === 'root' ? !isRoot : isRoot || !test(packageName))
+        /** A root block asks only whether this *is* the root - no selector needed, which is what makes
+         *  `/` structural. A glob has to have something to match, and during the walk it does not. */
+        if (scope === 'root' ? !isRoot : isRoot || selector === undefined || !test(selector))
             continue;
         matches.push(value);
     }
@@ -287,6 +389,11 @@ function dirChain(rootDir, targetDir) {
     }
     return dirs;
 }
+/**
+ * **Returns `Resolved<T>`, not `T`, because resolving is what it does.** Calling every value
+ * function is half this function's job, so the type it hands back is the one where they are gone -
+ * which is what makes `pkg.config` a `ResolvedConfig` without a cast anywhere between.
+ */
 export function interpolateConfig(config, scope, options) {
     const skip = options?.skip ?? [];
     /**
@@ -313,8 +420,8 @@ export function interpolateConfig(config, scope, options) {
     if (!config || typeof config !== 'object' || Array.isArray(config))
         return walk(config, scope, context, base, skip);
     /**
-     * The config's own top-level keys, readable bare: `${{ publish.directory }}`. So a value that
-     * restates another - `after: "cp README.md ${{ publish.directory }}/"` - stops being a second
+     * The config's own top-level keys, readable bare: `${{ changelog.filePath }}`. So a value that
+     * restates another - `after: "cp README.md ${{ changelog.filePath }}/"` - stops being a second
      * copy that drifts when the first one changes.
      *
      * Resolved **on demand**, one key at a time, and memoized. Interpolating the config in tree order
@@ -374,6 +481,13 @@ export function interpolateConfig(config, scope, options) {
     const result = {};
     for (const key of Object.keys(config))
         result[key] = resolve(key);
+    /**
+     * **The one cast in the whole two-view split, and it is here rather than at every read.** No type
+     * can prove that a runtime walk turned `T` into `Resolved<T>`; this walk is what makes it true.
+     * Putting it at this single return is what keeps `pkg.config` honest without a cast in any of the
+     * commands - which is the arrangement the alternative (widening `RmanConfig` alone) gave up, six
+     * read sites at a time.
+     */
     return result;
 }
 /**
@@ -401,7 +515,7 @@ export const DEFERRED_PATHS = ['version.before', 'version.exec', 'version.after'
  * ```
  *
  * **The key decides, and it already did.** `run.build.exec: 'tsc -b'` is a shell command and
- * `publish.directory: 'build'` is a path - not because of anything about the strings, but because of
+ * `publish.npm.directory: 'build'` is a path - not because of anything about the strings, but because of
  * where they sit. A function inherits the same rule, so nothing new has to be learned and no marker
  * has to be remembered. The alternative was inspecting the function (arity, parameter names), which
  * is the kind of guess `loadPlugins` refuses to make about a module's export for the same reason:
@@ -429,16 +543,23 @@ export const STEP_PATHS = [
 ];
 /**
  * Keys whose **whole subtree** is code rather than config, so no function under them is a value to
- * compute. `plugins` is the only one, and it has to be here: an entry may be the plugin *object*
- * itself, and an `RmanPlugin` is almost entirely functions - `manifest.read`, `workspace.resolve`,
- * `versionPlanner`, `binPaths`, and every command's `builder` and `handler`.
- *
- * Measured, and it is why this exists: with `plugins` walked like any other key, resolving the
- * config of a repository that named a plugin called that plugin's yargs builder with the config
- * scope - `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a
- * function`. A `plugins` entry is loaded by `loadPlugins`, never read as a setting.
+ * compute.
+ *
+ * The three contribution keys, and each has to be here: an entry may be the *instance* itself, and
+ * a `Plugin` is almost entirely functions - `manifestProvider.read`, `getWorkspace`,
+ * `getBinPaths`, `versionPlanner` - while a command is often a bare factory and a publish target
+ * carries `getPlan`/`applyPlan`.
+ *
+ * Measured twice, once per shape. With `plugins` walked like any other key, resolving the config
+ * of a repository that named a plugin called that plugin's yargs builder with the config scope:
+ * `Config function in "plugins[0].commands[0].builder" failed: cmd.option is not a function`. And
+ * with `commands` left out of this list, a declarative command - which *is* a function - was
+ * invoked with the interpolation scope instead of the application, so its handler closed over a
+ * repository that was not one: `repository.getPackages is not a function`, from inside `clean`.
+ *
+ * These entries are loaded by `loadPlugins` and `cli.ts`, never read as settings.
  */
-export const CODE_SUBTREES = ['plugins'];
+export const CODE_SUBTREES = ['plugins', 'commands', 'publishTargets'];
 const EXPRESSION = /\$\{\{([\s\S]*?)\}\}/g;
 /** A config key an expression could actually name. Anything else - a `"[selector]"` block, a
  *  `"lint:fix"` - is unreachable as a bare identifier anyway, so it is not bound. */
@@ -656,13 +777,14 @@ function shortenOrigin(file) {
  *
  * **Always bound, even with nothing underneath.** Left unbound, an expression naming it fails with
  * V8's `value is not defined`, which reads as "there is no such thing" rather than "nothing below
- * this layer set it" - two different mistakes needing two different fixes.
+ * this layer set it" - two different mistakes needing two different fixes. With nothing underneath
+ * it is `unsetValue()` rather than `undefined` - see there.
  *
  * The chain resolves bottom-up, so a layer deriving from a layer that itself derived from something
  * is handed the finished value rather than a half-resolved expression.
  */
 function walkWithPrevious(item, previous, scope, context, at, skip) {
-    const resolved = previous === undefined ? undefined : walkWithPrevious(previous.value, previous.previous, scope, context, at, skip);
+    const resolved = previousValue(previous === undefined ? undefined : walkWithPrevious(previous.value, previous.previous, scope, context, at, skip), at);
     const outer = Object.getOwnPropertyDescriptor(context, VALUE_KEY);
     /** A getter, so the catch below can tell whether the value **actually read `value`**: the hint is
      *  irrelevant to any other failure, and attaching it anyway is the send-the-reader-to-the-wrong-
@@ -681,22 +803,18 @@ function walkWithPrevious(item, previous, scope, context, at, skip) {
     }
     catch (e) {
         /**
-         * **`value` is `undefined` when no layer underneath set this key**, and a value written to
-         * extend an inherited list is also the *first* layer in a repository that inherits nothing.
-         * V8 reports that as `value is not iterable`, naming neither the key nor the reason.
-         *
-         * Here rather than in `callValueFn`, so the expression and the function spelling get the same
-         * sentence from the same place. `rmanValueHint` keeps a rethrow from stacking it twice as the
-         * error passes back up through the enclosing keys.
+         * **The hint is only about *reading* `value`**, so it is attached only when the value did -
+         * recorded through the getter above, never matched on V8's wording. Attaching it to any other
+         * failure is the send-the-reader-to-the-wrong-place mistake it exists to prevent.
          *
-         * Not papered over by defaulting `value` to `[]`: that would be a guess about the key's type,
-         * and wrong for every key that is not a list.
+         * The sentence itself comes from `unsetValue`, which knows the key and throws at the exact
+         * point of misuse; all this adds is the case the sentinel cannot catch, where a value reads
+         * `value` and fails for a reason of its own. `rmanValueHint` keeps a rethrow from stacking it
+         * twice as the error passes back up through the enclosing keys.
          */
-        if (wasRead && resolved === undefined && !e?.rmanValueHint) {
+        if (wasRead && isUnsetValue(resolved) && !e?.rmanValueHint) {
             e.rmanValueHint = true;
-            e.message =
-                `${e.message}\n  \`value\` is undefined here - nothing below this layer sets "${describeAt(at)}.` +
-                    `\n  Write \`value ?? []\` (or \`?? ''\`) if it has to work as the first layer too.`;
+            e.message = `${e.message}\n  Note: nothing below this layer sets "${describeAt(at)}, so \`value\` is empty.`;
         }
         throw e;
     }
@@ -937,3 +1055,69 @@ function deepFreeze(value) {
     for (const item of Object.values(value))
         deepFreeze(item);
 }
+/**
+ * What a layer is handed as `value`: **the list form of whatever is underneath it.**
+ *
+ * `value` exists for one job - extending what a closer layer inherited, the general form of `+key`,
+ * and `+key` only ever meant append. So the shape a spread wants is the shape to hand over:
+ * `[...value, 'x']` works with no guard whether the layers below said nothing, said `'build'`, or
+ * said `['build']`.
+ *
+ * **Coercing a scalar into a one-element list is not a guess about the key's type.** Every key this
+ * is reached for is declared `X | X[]` - `clean.include`, `clean.exclude`, `version.stamp`,
+ * `version.before`/`.exec`/`.after` - where the list is the type and the scalar is *shorthand*.
+ * `CleanService` and `RunService` already normalize it; doing it here as well decides nothing new.
+ * And spreading a string into its characters, which is what handing the raw value over did, is not
+ * something any key wants.
+ *
+ * It reads as the scalar wherever a scalar is what makes sense, through `Symbol.toPrimitive`:
+ * `` `${value}-x` `` is `'build-x'` and `value + 1` is `6`. A *list* underneath refuses both, since
+ * splicing `a,b` into a sentence is a mistake worth naming; so does nothing-underneath.
+ *
+ * **A boolean is handed over as itself**, the one carve-out, because it is never a list nor a
+ * list's shorthand - and an object cannot be fixed up for it: `!value` and `value ? :` use
+ * ToBoolean, which has no hook and answers `true` for every object, so a wrapped `false` would read
+ * as `true`. Measured. `[...value]` on one then throws, which is right - spreading a boolean means
+ * nothing.
+ *
+ * **The cost, stated rather than hidden: strict equality and string methods on an inherited
+ * scalar.** `value === 'build'` is `false` and `value.includes('bui')` is `false` (an array's
+ * `includes` matches elements, not substrings). `value == 'build'`, `` `${value}` === 'build' `` and
+ * `String(value).includes('bui')` all work, and `value.length` is the number of layers' worth of
+ * entries rather than a string's length. That is the trade for the append case never needing a
+ * guard; `value` was introduced for the append case.
+ */
+function previousValue(raw, at) {
+    /** Never a list, and unfixable as one - see above. */
+    if (typeof raw === 'boolean')
+        return raw;
+    const list = raw === undefined ? [] : Array.isArray(raw) ? [...raw] : [raw];
+    Object.defineProperty(list, UNSET_MARKER, { value: raw === undefined });
+    return Object.defineProperty(list, Symbol.toPrimitive, {
+        value: (hint) => {
+            if (raw === undefined) {
+                throw unusable(at, 'nothing below this layer sets it, so it is empty', "`value ?? ''`, `value ?? 0`");
+            }
+            if (typeof raw !== 'string' && typeof raw !== 'number') {
+                throw unusable(at, `the layer below it is ${Array.isArray(raw) ? 'a list' : 'an object'}`, '`value.join(", ")` for a list');
+            }
+            return hint === 'string' ? String(raw) : raw;
+        },
+    });
+}
+/** The one sentence both refusals share: what was asked for, why it cannot be done, what to write
+ *  instead. Marked `rmanValueHint` so `walkWithPrevious`'s catch leaves it alone - that note exists
+ *  to explain an empty `value` to an error that does not mention it, and this error *is* that
+ *  explanation. */
+function unusable(at, because, instead) {
+    const error = new Error(`\`value\` cannot be used as a string or a number here - ${because}, for "${describeAt(at)}. ` +
+        `It spreads as a list (\`[...value, x]\`); to use it as something else, say what it should be - ${instead}.`);
+    error.rmanValueHint = true;
+    return error;
+}
+/** Whether `value` stands for "no layer underneath set this key" - by the marker `previousValue`
+ *  puts on it, never by emptiness, since a layer may legitimately resolve to `[]`. */
+function isUnsetValue(value) {
+    return Array.isArray(value) && value[UNSET_MARKER] === true;
+}
+const UNSET_MARKER = Symbol('rman.valueUnset');

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;