rman 1.0.10 → 1.0.12

package/interfaces/rman-config.interface.d.ts

@@ -17,10 +17,44 @@ export interface RmanConfig {
     clean?: RmanConfig.CleanOptions;
     publish?: RmanConfig.PublishOptions;
     githubRelease?: RmanConfig.GithubReleaseOptions;
-    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). */
-    run?: Record<string, RmanConfig.RunScriptOptions>;
-    /** Keyed by the in-repo package's own name. */
-    packages?: Record<string, RmanConfig.PackageOptions>;
+    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). A bare string (or array of
+     *  them) is shorthand for `{ exec: ... }` - `test: "mocha"` and `test: { exec: "mocha" }` mean
+     *  exactly the same thing. */
+    run?: Record<string, string | string[] | RmanConfig.RunScriptOptions>;
+    /** In-repo packages this one depends on beyond what its real `package.json` declares - purely
+     *  for rman's own dependency graph (topo-sort, `--deps`/`--dependents`, `run`'s scheduling). An
+     *  array defaults each entry's range to `"*"`; an object gives an explicit name -> range map.
+     *  Declared from the root via a selector (`"[pkg-a]": { dependencies: [...] }`) or in the
+     *  package's own `.rmanrc`. */
+    dependencies?: string[] | Record<string, string>;
+    /**
+     * Config for **other** packages, keyed by a `"[selector]"` naming them - `"[*]"` for every
+     * package in the repository, `"[*-dialect]"` for a glob over package names, `"[pkg-a]"` for one.
+     * Everything else in this object configures the package of the directory declaring it, so this
+     * is the only way a `.rmanrc` speaks about anything but its own package - most usefully the
+     * repository root's, which otherwise configures the root package alone.
+     *
+     * ```yaml
+     * # the repository root's own .rmanrc.yml
+     * run:
+     *   build:
+     *     before: node support/generate.cjs   # a repo-wide bookend, run once at the root
+     * "[*]":
+     *   run:
+     *     build:
+     *       after: node ../../support/postbuild.cjs   # run in each package's own directory
+     * ```
+     *
+     * In YAML the quotes are **required**: a bare `[*]` parses as a flow sequence, and `*` as an
+     * alias indicator. Precedence, lowest first: `"[*]"`, then other selectors in declaration order,
+     * then the package's own unmarked config.
+     *
+     * Recursive, mirroring the schema's own `"$ref": "#"`: whatever a `.rmanrc` may say about its own
+     * package it may say here about the ones it names - nested selectors included. Typed as
+     * `RmanConfig` rather than `unknown` so the contents are actually checked; `unknown` let any
+     * shape through, which is the opposite of the point.
+     */
+    [selector: `[${string}]`]: RmanConfig;
 }
 export declare namespace RmanConfig {
     interface VersionOptions {
@@ -36,9 +70,29 @@ export declare namespace RmanConfig {
          *  any package's own `changelog.tagPattern`, or that package's changelog boundary will resolve
          *  to the repository release instead of its own last release. */
         releaseTagPattern?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
+        /** Keep this package's Dockerfile `org.opencontainers.image.version` label in step with the
+         *  version being written. Per-package cascaded. Default `true` - the label's value is, by
+         *  specification, the version of the packaged software, so there is only ever one correct
+         *  value for it, and `version` is what knows it. Only ever *rewrites* a label the Dockerfile
+         *  already declares (never inserts one), and reads the same path `publish --target docker`
+         *  builds from (`publish.docker.dockerfile`), so a package without one is a no-op. */
+        stampDockerfile?: boolean;
+        /** Source files whose `version` constant is rewritten to the version being written, in the same
+         *  commit as the bump - paths relative to the package's own directory (e.g.
+         *  `["src/constants.ts"]`). Per-package cascaded; a listed file a package doesn't have is a
+         *  silent no-op, so one `"[*]"` declaration covers a repo where only some packages carry one.
+         *
+         *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
+         *  claiming a placeholder, so anything running from source reports that placeholder, git never
+         *  records the released version, and the rewrite has to be redone on every build. */
+        stamp?: string | string[];
+        /** Command(s) run as this package's own `version` npm-lifecycle step, when its `package.json`
+         *  doesn't define one itself. An array runs them in sequence. */
+        exec?: string | string[];
+        /** Same, for `preversion`. */
+        before?: string | string[];
+        /** Same, for `postversion`. */
+        after?: string | string[];
     }
     interface ChangelogOptions {
         ignoreTypes?: string[];
@@ -60,14 +114,15 @@ export declare namespace RmanConfig {
         changedSince?: string;
         skip?: boolean;
         if?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
+        /** Command(s) to run as this script itself, when the package's `package.json` doesn't define
+         *  it. An array runs them in sequence. */
+        exec?: string | string[];
+        /** Same, for this script's `pre<script>` hook. */
+        before?: string | string[];
+        /** Same, for its `post<script>` hook. */
+        after?: string | string[];
         override?: boolean;
     }
-    interface PackageOptions {
-        dependencies?: string[] | Record<string, string>;
-    }
     interface PublishOptions {
         /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
          *  keeps working unchanged). A package that only ever wants Docker images (typically also
@@ -80,6 +135,14 @@ export declare namespace RmanConfig {
          *  a release happened, and it is never opted into: see `githubRelease` and the
          *  `github-release` command. */
         target?: PublishTarget | PublishTarget[];
+        /** Where this package's publishable output lives, relative to its own directory (e.g.
+         *  `"build"`). Per-package cascaded, so a root `"[*]"` block can say it once for the whole
+         *  repository instead of repeating `publishConfig.directory` in every `package.json` - which
+         *  still wins when a package declares it, being the more specific statement.
+         *
+         *  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?: string;
         docker?: DockerPublishOptions;
         /** Excludes this package from `publish` entirely (every target), regardless of
          *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/rmanrc.schema.json

@@ -2,8 +2,15 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/panates/rman/main/schemas/rmanrc.schema.json",
   "title": "rman configuration",
-  "description": "Schema for rman's .rmanrc (JSON) and .rmanrc.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanrcyml for the full reference.",
+  "description": "Schema for rman's .rmanrc (JSON) and .rmanrc.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanrcyml for the full reference. Any string value may embed ${{ ... }} expressions - real JavaScript, evaluated per package against pkg, repository, env and semver - so one declaration at the root can still say something package-specific (\"../../coverage/${{ pkg.basename }}\", \"panates/${{ pkg.basename }}:${{ semver.major(pkg.version) }}\"). A string that is nothing but one expression keeps that value's own type. A bare {{ ... }} is left alone, so a command carrying someone else's template survives untouched.",
   "type": "object",
+  "additionalProperties": false,
+  "patternProperties": {
+    "^\\[.+\\]$": {
+      "$ref": "#",
+      "description": "Config for the packages this selector names, rather than for the package of the directory declaring it - \"[*]\" for every package in the repository, \"[*-dialect]\" for a glob over package names, \"[pkg-a]\" for one. In YAML the quotes are REQUIRED: a bare [*] parses as a flow sequence and * as an alias indicator. Precedence, lowest first: \"[*]\", then other selectors in declaration order, then the package's own unmarked config."
+    }
+  },
   "properties": {
     "$schema": {
       "type": "string",
@@ -66,15 +73,24 @@
           "default": "release-*",
           "description": "Root-level. Tag naming the repository's own release, as opposed to the per-package/group tags \"changelog.tagPattern\" names - only created when the root is on a calendar version (a repo with more than one version line). Must NOT match any package's \"changelog.tagPattern\", or that package's changelog boundary resolves to the repository release instead of its own."
         },
-        "script": {
+        "stampDockerfile": {
+          "type": "boolean",
+          "default": true,
+          "description": "Per-package cascaded. Keep this package's Dockerfile \"org.opencontainers.image.version\" label in step with the version being written, in the same commit as the bump. The label's value is by specification the version of the packaged software, so there is only one correct value for it. Only ever rewrites a label the Dockerfile already declares (never inserts one), and reads the same path \"publish --target docker\" builds from (\"publish.docker.dockerfile\")."
+        },
+        "stamp": {
           "$ref": "#/definitions/stringOrStringArray",
-          "description": "Command(s) to run as this package's own \"version\" npm-lifecycle step, when its package.json does not define one itself."
+          "description": "Source files whose \"version\" constant is rewritten to the version being written, in the same commit as the bump - paths relative to the package's own directory (e.g. [\"src/constants.ts\"]). Per-package cascaded; a listed file a package doesn't have is a silent no-op. Stamps the source rather than the build output, so anything running from source reports the real version and git records it."
         },
-        "preScript": {
+        "before": {
           "$ref": "#/definitions/stringOrStringArray",
           "description": "Command(s) to run as this package's own \"preversion\" step, when its package.json does not define one itself."
         },
-        "postScript": {
+        "exec": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"version\" npm-lifecycle step, when its package.json does not define one itself."
+        },
+        "after": {
           "$ref": "#/definitions/stringOrStringArray",
           "description": "Command(s) to run as this package's own \"postversion\" step, when its package.json does not define one itself."
         }
@@ -151,6 +167,10 @@
             }
           ]
         },
+        "directory": {
+          "type": "string",
+          "description": "Where this package's publishable output lives, relative to its own directory (e.g. \"build\"). Per-package cascaded, so a root \"[*]\" block can say it once instead of repeating publishConfig.directory in every package.json - which still wins when a package declares it. Publishing from such a directory means the manifest there is GENERATED by publish, from the package's own, with devDependencies, non-install scripts, \"private\" and publishConfig.directory removed and \"workspace:\" ranges resolved. There is nothing to configure about it."
+        },
         "docker": {
           "$ref": "#/definitions/dockerPublishConfig",
           "description": "Required once \"docker\" is one of this package's \"publish.target\"s."
@@ -168,37 +188,34 @@
     },
     "run": {
       "type": "object",
-      "description": "Per-script options for \"run\"/\"build\"/\"test\"/RunService, keyed by npm script name (e.g. \"build\", \"lint\", \"test\").",
+      "description": "Per-script options for \"run\"/\"build\"/\"test\"/RunService, keyed by npm script name (e.g. \"build\", \"lint\", \"test\"). A bare string (or array of them) is shorthand for { \"exec\": ... } - \"test\": \"mocha\" and \"test\": { \"exec\": \"mocha\" } mean exactly the same thing.",
       "additionalProperties": {
-        "$ref": "#/definitions/runScriptConfig"
+        "oneOf": [
+          {
+            "$ref": "#/definitions/stringOrStringArray"
+          },
+          {
+            "$ref": "#/definitions/runScriptConfig"
+          }
+        ]
       }
     },
-    "packages": {
-      "type": "object",
-      "description": "Per-package overrides, keyed by the in-repo package's own name.",
-      "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "dependencies": {
-            "description": "Extra in-repo \"dependencies\" not present in this package's real package.json, purely for rman's own dependency graph (topo-sort, --deps/--dependents, run's task scheduling). An array defaults each entry's range to \"*\"; an object gives an explicit name -> range map.",
-            "oneOf": [
-              {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                }
-              },
-              {
-                "type": "object",
-                "additionalProperties": {
-                  "type": "string"
-                }
-              }
-            ]
+    "dependencies": {
+      "description": "In-repo packages this one depends on beyond what its real package.json declares, purely for rman's own dependency graph (topo-sort, --deps/--dependents, run's task scheduling). An array defaults each entry's range to \"*\"; an object gives an explicit name -> range map. Declare it from the root through a selector (\"[pkg-a]\": { \"dependencies\": [...] }) or in the package's own .rmanrc.",
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
           }
         }
-      }
+      ]
     }
   },
   "definitions": {
@@ -352,22 +369,22 @@
           "type": "string",
           "description": "Conditional-execution expression: atoms \"changed\"/\"dirty\"/\"committed\" (optionally \"= <hash>\" or \"= {ENV_VAR}\"), combined with and/or/not/(...). E.g. \"changed\", \"(changed or dirty) and not committed\"."
         },
-        "script": {
+        "before": {
           "$ref": "#/definitions/stringOrStringArray",
-          "description": "Command(s) to run as this package's own script, when its package.json does not define one for this script name."
+          "description": "Command(s) to run as this package's own \"pre<script>\" hook, when its package.json does not define one."
         },
-        "preScript": {
+        "exec": {
           "$ref": "#/definitions/stringOrStringArray",
-          "description": "Command(s) to run as this package's own \"pre<script>\" hook, when its package.json does not define one."
+          "description": "Command(s) to run as this package's own script, when its package.json does not define one for this script name."
         },
-        "postScript": {
+        "after": {
           "$ref": "#/definitions/stringOrStringArray",
           "description": "Command(s) to run as this package's own \"post<script>\" hook, when its package.json does not define one."
         },
         "override": {
           "type": "boolean",
           "default": false,
-          "description": "When true, \"script\"/\"preScript\"/\"postScript\" above replace the package's own package.json definition even when it already has one."
+          "description": "When true, \"before\"/\"exec\"/\"after\" above replace the package's own package.json definition even when it already has one."
         }
       }
     }

package/services/publish.service.js

@@ -1,3 +1,19 @@
+/**
+ * Prepares the `package.json` that `npm publish` will actually read, and returns a function that
+ * undoes it - always call that from a `finally`, so a failed publish leaves nothing behind.
+ *
+ * Which file that is depends on where the output lives:
+ *
+ * - **Publishing the package directory itself** - its own `package.json` is the manifest, rewritten
+ *   in place: every `"workspace:"` range becomes a real, registry-consumable one (the same
+ *   substitution pnpm/yarn's own publish performs - see `resolveWorkspaceRange`), since `npm
+ *   publish` reads what is on disk rather than packing from a staging tarball.
+ * - **Publishing a build directory** - there is no manifest there until something writes one, and
+ *   that something is this: see `derivePublishManifest`.
+ *
+ * Returns `undefined` when there is nothing to do at all (the package directory, with no
+ * `"workspace:"` range in it) - no disk write, nothing to restore.
+ */
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -8,6 +24,94 @@ import { filterPackages } from '../utils/package-filter.js';
 import { parseWorkspaceRange, resolveWorkspaceRange } from '../utils/workspace-range.js';
 import { CiService } from './ci.service.js';
 import { DEPENDENCY_KEYS } from './version.service.js';
+function preparePublishManifest(pkg, publishDir, packagesByName) {
+    if (path.resolve(publishDir) !== path.resolve(pkg.dirname)) {
+        const file = path.join(publishDir, 'package.json');
+        const previous = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : undefined;
+        fs.mkdirSync(publishDir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(derivePublishManifest(pkg, packagesByName), undefined, 2) + '\n', 'utf-8');
+        return () => {
+            if (previous === undefined)
+                fs.rmSync(file, { force: true });
+            else
+                fs.writeFileSync(file, previous, 'utf-8');
+        };
+    }
+    const hasWorkspaceRange = DEPENDENCY_KEYS.some(depKey => {
+        const deps = pkg.json[depKey];
+        return deps && Object.values(deps).some(v => parseWorkspaceRange(v));
+    });
+    if (!hasWorkspaceRange)
+        return undefined;
+    const original = fs.readFileSync(pkg.jsonFileName, 'utf-8');
+    resolveWorkspaceRanges(pkg.json, packagesByName);
+    pkg.writeJson();
+    return () => {
+        fs.writeFileSync(pkg.jsonFileName, original, 'utf-8');
+        pkg.reloadJson();
+    };
+}
+/**
+ * The manifest to publish from a build directory, derived from the package's own - generated here
+ * rather than by a build script, and deliberately with nothing to configure.
+ *
+ * Generated at *publish* time, which is the whole point: a build script writes it when the build
+ * runs, so bumping the version afterwards (or building before a bump) publishes a manifest that
+ * disagrees with the package - and the `"workspace:"` rewrite above, which only ever touched the
+ * package's own file, never reached the copy at all.
+ *
+ * What comes out is the package's `package.json` minus what a consumer of the tarball can neither
+ * see nor use:
+ *
+ * - `devDependencies` - npm never installs a dependency's own, so they are pure noise.
+ * - `scripts`, **except** `preinstall`/`install`/`postinstall`. Those three are the only ones a
+ *   consumer's install actually runs, and dropping them would silently break every package that
+ *   builds a native module on install. The rest (`build`, `test`, `prepare`, ...) never reach the
+ *   consumer - `prepare` runs for a git dependency, which builds from the repository, not from this
+ *   tarball.
+ * - `private` - rman refuses to publish a private package in the first place, so carrying the flag
+ *   into a manifest that is being published can only be wrong.
+ * - `publishConfig.directory` - it pointed *here*; kept, it would point one level deeper again.
+ */
+function derivePublishManifest(pkg, packagesByName) {
+    const json = structuredClone(pkg.json);
+    resolveWorkspaceRanges(json, packagesByName);
+    delete json.devDependencies;
+    delete json.private;
+    if (json.scripts) {
+        const kept = Object.fromEntries(Object.entries(json.scripts).filter(([name]) => CONSUMER_SCRIPTS.has(name)));
+        if (Object.keys(kept).length)
+            json.scripts = kept;
+        else
+            delete json.scripts;
+    }
+    if (json.publishConfig) {
+        delete json.publishConfig.directory;
+        if (!Object.keys(json.publishConfig).length)
+            delete json.publishConfig;
+    }
+    return json;
+}
+/** The only lifecycle scripts a consumer's `npm install` of this package runs - see
+ *  https://docs.npmjs.com/cli/using-npm/scripts. */
+const CONSUMER_SCRIPTS = new Set(['preinstall', 'install', 'postinstall']);
+/** Rewrites `json`'s `"workspace:"` ranges in place, resolving each against the in-repo package it
+ *  names. Shared by both manifest paths, so they can never disagree about the substitution. */
+function resolveWorkspaceRanges(json, packagesByName) {
+    for (const depKey of DEPENDENCY_KEYS) {
+        const deps = json[depKey];
+        if (!deps)
+            continue;
+        for (const depName of Object.keys(deps)) {
+            const parsed = parseWorkspaceRange(deps[depName]);
+            if (!parsed)
+                continue;
+            const depPkg = packagesByName.get(depName);
+            if (depPkg)
+                deps[depName] = resolveWorkspaceRange(parsed, depPkg.version);
+        }
+    }
+}
 export var PublishService;
 (function (PublishService) {
     /**
@@ -106,12 +210,10 @@ export var PublishService;
                 result.push({ ...entry, status: 'error', reason: `dependency "${blocker}" failed to publish` });
                 continue;
             }
-            const restore = rewriteWorkspaceRangesForPublish(pkg, packagesByName);
+            const publishDir = resolvePublishDir(pkg, options.contents);
+            const restore = preparePublishManifest(pkg, publishDir, packagesByName);
             try {
-                await exec(buildPublishCommand(packageManager, options), {
-                    cwd: resolvePublishDir(pkg, options.contents),
-                    stdio: 'inherit',
-                });
+                await exec(buildPublishCommand(packageManager, options), { cwd: publishDir, stdio: 'inherit' });
                 result.push(entry);
             }
             catch (e) {
@@ -145,13 +247,14 @@ async function defaultNpmViewVersion(name, cwd, options) {
         return undefined;
     }
 }
-/** npm's own native `publishConfig.directory` (if the package declares one) always wins over
- *  `options.contents` - the package's own package.json is the more authoritative, persistent
- *  statement of "this is where the publishable output lives", `--contents` is just a fallback for
- *  when it doesn't declare one at all. */
+/** Where the publishable output lives, most specific statement first: the package's own
+ *  `publishConfig.directory` (npm/pnpm's native spelling, and a statement about that one package),
+ *  then `.rmanrc "publish.directory"` (which a `"[*]"` block can say once for a whole repository
+ *  instead of repeating in every `package.json`), then `--contents` for a single run. */
 function resolvePublishDir(pkg, contentsOverride) {
     const native = pkg.json.publishConfig?.directory;
-    const rel = (typeof native === 'string' && native) || contentsOverride;
+    const configured = pkg.config?.publish?.directory;
+    const rel = (typeof native === 'string' && native) || configured || contentsOverride;
     return rel ? path.resolve(pkg.dirname, rel) : pkg.dirname;
 }
 function buildPublishCommand(packageManager, options) {
@@ -168,40 +271,3 @@ function buildPublishCommand(packageManager, options) {
         args.push('--userconfig', options.userconfig);
     return `${packageManager} ${args.join(' ')}`;
 }
-/**
- * Rewrites every `"workspace:"` dependency range in `pkg`'s `package.json` to a real,
- * registry-publishable range (the same substitution pnpm/yarn's own publish performs - see
- * `resolveWorkspaceRange`), just before shelling out to `npm publish` - which reads whatever is
- * actually on disk, unlike pnpm/yarn's own publish this never packs into a staging tarball first.
- * Returns a function that restores the file's original bytes (and `pkg`'s in-memory state)
- * verbatim; always invoke it from a `finally`, so a failed publish never leaves a rewritten
- * `package.json` behind. Returns `undefined` (nothing to restore, no disk write at all) when `pkg`
- * has no `"workspace:"` ranges to begin with.
- */
-function rewriteWorkspaceRangesForPublish(pkg, packagesByName) {
-    const hasWorkspaceRange = DEPENDENCY_KEYS.some(depKey => {
-        const deps = pkg.json[depKey];
-        return deps && Object.values(deps).some(v => parseWorkspaceRange(v));
-    });
-    if (!hasWorkspaceRange)
-        return undefined;
-    const original = fs.readFileSync(pkg.jsonFileName, 'utf-8');
-    for (const depKey of DEPENDENCY_KEYS) {
-        const deps = pkg.json[depKey];
-        if (!deps)
-            continue;
-        for (const depName of Object.keys(deps)) {
-            const parsed = parseWorkspaceRange(deps[depName]);
-            if (!parsed)
-                continue;
-            const depPkg = packagesByName.get(depName);
-            if (depPkg)
-                deps[depName] = resolveWorkspaceRange(parsed, depPkg.version);
-        }
-    }
-    pkg.writeJson();
-    return () => {
-        fs.writeFileSync(pkg.jsonFileName, original, 'utf-8');
-        pkg.reloadJson();
-    };
-}

package/services/run.service.d.ts

@@ -42,10 +42,15 @@ export declare namespace RunService {
      * `getScriptSteps`:
      *   run:
      *     build:
-     *       script: tsc -b
-     *       preScript: [node ./generate.js, node ./validate.js]
-     *       postScript: node ./copy-assets.js
+     *       before: [node ./generate.js, node ./validate.js]
+     *       exec: tsc -b
+     *       after: node ./copy-assets.js
      *       override: true   # use these even if the package *does* define its own
+     *
+     * A bare string is shorthand for `exec`, which is by far the common case - a script that is just
+     * a command, with nothing to configure about how it runs:
+     *   run:
+     *     test: mocha          # same as   test: { exec: mocha }
      */
     function getConfig(pkg: Package, script: string): Record<string, unknown>;
     /**

package/services/run.service.js

@@ -26,14 +26,21 @@ export var RunService;
      * `getScriptSteps`:
      *   run:
      *     build:
-     *       script: tsc -b
-     *       preScript: [node ./generate.js, node ./validate.js]
-     *       postScript: node ./copy-assets.js
+     *       before: [node ./generate.js, node ./validate.js]
+     *       exec: tsc -b
+     *       after: node ./copy-assets.js
      *       override: true   # use these even if the package *does* define its own
+     *
+     * A bare string is shorthand for `exec`, which is by far the common case - a script that is just
+     * a command, with nothing to configure about how it runs:
+     *   run:
+     *     test: mocha          # same as   test: { exec: mocha }
      */
     function getConfig(pkg, script) {
         const runCfg = pkg.config?.run;
         const cfg = runCfg && typeof runCfg === 'object' ? runCfg[script] : undefined;
+        if (typeof cfg === 'string' || Array.isArray(cfg))
+            return { exec: cfg };
         return cfg && typeof cfg === 'object' ? cfg : {};
     }
     RunService.getConfig = getConfig;
@@ -197,10 +204,14 @@ export var RunService;
         const ifStatusCache = new Map();
         /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
          *  (unless root itself opts out via `run.<script>.skip`, fails its own `run.<script>.if`, or the
-         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there). */
-        const rootIf = !cwdScope && parseIfExpr(rootCfg.if);
+         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there).
+         *
+         *  Only in a monorepo. Without one the root *is* the single package, already in the loop below
+         *  with the same hooks and the same directory - a bookend would simply run each of them a
+         *  second time. */
+        const rootIf = !cwdScope && repository.monorepo && parseIfExpr(rootCfg.if);
         const rootIfPasses = rootIf ? await evaluateIf(repository, repository.rootPackage, rootIf, ifStatusCache) : true;
-        const rootSkipped = !!cwdScope || rootCfg.skip === true || !rootIfPasses;
+        const rootSkipped = !!cwdScope || !repository.monorepo || rootCfg.skip === true || !rootIfPasses;
         const rootSteps = rootSkipped ? [] : getScriptSteps(repository.rootPackage, script);
         const rootPre = rootSteps.filter(s => s.name === 'pre' + script);
         const rootPost = rootSteps.filter(s => s.name === 'post' + script);
@@ -255,11 +266,36 @@ export var RunService;
             }));
         }
         if (!children.length) {
-            console.log(colors.gray(`No package defines a "${script}" script.`));
-            return;
+            /**
+             * Two different nothings, and only one of them is fine.
+             *
+             * Nobody in the repository defines this script at all: the name is a mistake - a typo, or a
+             * script that used to exist - and `npm run` fails on exactly this. Staying silent is how
+             * `rman run qc` sat in a CI pipeline for months reporting success while running nothing, with
+             * `qc` defined only on the root (whose own scripts a monorepo never runs, only its
+             * `pre`/`post` bookends).
+             *
+             * Everything was filtered out instead - `--scope`, `--changed`, `run.<script>.skip`, an
+             * `if:` that didn't match: zero is the correct answer to what was asked, and asking "build
+             * only what changed" when nothing changed must not fail a pipeline.
+             */
+            /** `getPackages()` and nothing else - in a monorepo that excludes the root, which is the
+             *  point: the root contributes only `pre`/`post` bookends, never the script itself, so a
+             *  `qc` defined *only* there is exactly the mistake above rather than an excuse for it. (And
+             *  had the root contributed a bookend, `children` wouldn't be empty.) In a single-package
+             *  repository the root *is* the one package, and is covered. */
+            const definedSomewhere = repository.getPackages().some(pkg => getScriptSteps(pkg, script).length > 0);
+            if (definedSomewhere) {
+                console.log(colors.gray(`Nothing to run - every package was filtered out of "${script}".`));
+                return;
+            }
+            const message = `No package defines a "${script}" script.`;
+            console.log(colors.red(message));
+            const err = new Error(message);
+            err.logged = true;
+            throw err;
         }
         panel.start();
-        let failed = false;
         try {
             /** bail:false here - each package's own resolved bail setting decides whether to call
              *  `rootTask.abort()` itself (see `runSteps`), since power-tasks' own `bail` can't vary per package. */
@@ -267,13 +303,25 @@ export var RunService;
             await rootTask.toPromise();
         }
         catch {
-            failed = true;
+            // Swallowed on purpose: whether the root promise rejected says nothing reliable about the
+            // run - see below. The per-package tallies are what decide.
         }
         finally {
+            /** A package's own `bail` aborts the root task, which settles its promise *immediately* while
+             *  the packages already in flight keep running. Waiting for every child here is what makes
+             *  the summary below describe a finished run rather than a snapshot of one still going -
+             *  measured: it printed "0 succeeded, 1 failed, 3 skipped" and then three of those "skipped"
+             *  packages went on to succeed. */
+            await Promise.allSettled(children.map(child => child.toPromise()));
             panel.stop();
         }
-        panel.printSummary();
-        if (failed) {
+        const summary = panel.printSummary();
+        /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
+         *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
+         *  run it had just reported as failed - non-deterministically, since it came down to which
+         *  packages happened to still be running (measured: `1 0 1 1 0` across five identical runs).
+         *  A single failed package must fail the command, every time. */
+        if (summary.failedCount > 0) {
             const err = new Error(`"${script}" failed`);
             err.logged = true;
             throw err;
@@ -336,9 +384,9 @@ function getScriptSteps(pkg, script) {
         if (cfg.override === true || !hasOwn)
             json.scripts[key] = value;
     };
-    applyConfigScript(script, cfg.script);
-    applyConfigScript('pre' + script, cfg.preScript);
-    applyConfigScript('post' + script, cfg.postScript);
+    applyConfigScript(script, cfg.exec);
+    applyConfigScript('pre' + script, cfg.before);
+    applyConfigScript('post' + script, cfg.after);
     json.scripts[script] = json.scripts[script] || '#';
     const info = parseNpmScript(json, 'npm run ' + script);
     if (!info?.raw?.length)