rman 2.14.0 → 2.15.1

package/README.md

@@ -88,6 +88,7 @@ worked examples of every single command, see **[docs/cli-rman.md](https://github
 | [`config`](#rman-config) | Prints the effective `.rmanrc` config for the current directory's package. |
 | [`diff [package]`](#rman-diff-package) | Shows the git diff since a package's (or the repo's) last release tag. |
 | [`changelog`](#rman-changelog) | Generates a changelog per package from unreleased commits. |
+| [`deps [names..]`](#rman-deps-names) | Lists dependencies with a newer version; `-u` upgrades them. |
 | [`version [bump]`](#rman-version-bump) | Bumps versions of changed packages (and their dependents). |
 | [`publish`](#rman-publish) | Publishes every package whose version isn't on its registry yet. |
 | [`github-release`](#rman-github-release) | Creates the repository's GitHub Release for its release tag. |
@@ -129,16 +130,17 @@ Options shared across several commands:
 
 - **`skip`** (`.rmanrc`, per package): leave this package alone - honoured by every command that
   *acts* on packages, ignored by `list`, which reports on them.
-- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `version`, `changelog`, and a
-  plugin's own commands): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
-  [Package filtering](https://github.com/panates/rman/blob/main/docs/rman.md#package-filtering-scopeignoredepsdependents)
+- **Package filtering** (`list`, `run`/`build`/`test`, `exec`, `version`, `changelog`, `publish`,
+  `deps`, `clean`, `ci`, and a plugin's own commands): `--scope <glob>`, `--ignore <glob>`, `--deps`, `--dependents` - see
+  [Package filtering](https://github.com/panates/rman/blob/main/docs/rman.md#package-filtering-scopeignoreplatformdepsdependents)
   for the full semantics. **`--scope /` is the repository's own root package** - the same `/`
   `.rmanrc`'s `"[/]"` block uses, and not a glob, so `--scope '*'` means the members and a glob
   never picks up the root by name.
 - **`--from-root`/`-r`** (every command that narrows to the package you are standing in -
-  `run`/`build`/`test`, `exec`, `changelog`, `diff`): run against the whole repository instead.
+  `run`/`build`/`test`, `exec`, `clean`, `changelog`, `diff`, `config`): run against the whole
+  repository instead.
 - **Branch guard** (every command that mutates state or runs scripts - `run`/`build`/`test`,
-  `exec`, `version`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
+  `exec`, `version`, `publish`, `github-release`, `clean`, `ci`): `--allow-branch <glob>`, `--ignore-branch <glob>` -
   refuses to run unless (or if) the current git branch matches, the same idea as GitHub Actions'
   own `branches`/`branches-ignore` workflow filters.
 
@@ -147,7 +149,7 @@ Options shared across several commands:
 Lists packages in the repository (alias: `ls`).
 
 ```bash
-rman list                       # table: Package / Version / Private / Changed / Path
+rman list                       # table: Package / Version / Group / Platform / Private / Publish / Changed / Path
 rman ls --short                 # just the bare package names
 rman list --json                # full detail as JSON
 rman list --parseable           # location::name::version::PRIVATE::STATUS lines, for scripting
@@ -158,12 +160,16 @@ rman list --changed-since HEAD~5
 rman list --scope '@myorg/*' --ignore '*-internal'
 ```
 
+The table keeps each release group together, in `version`'s plan order (root, then groups, then
+packages in no group), and indents a package by how deep it sits. `Group` appears only when it says
+something; `Publish` names the targets a package ships to, or `-` when none is left. `--toposort`
+orders by dependencies instead, and `--json` keeps the inventory's own order.
+
 ### `rman info`
 
 Prints local environment (OS/CPU/memory, Node, git) and repository information. A platform adds its
 own ecosystem's part - the `node` built-in reports whichever package manager
-`.rmanrc "packageManager"` names, plus the installed `rman` packages, and only in a repository that
-asked for it.
+`.rmanrc "packageManager"` names (`npm` by default), plus the installed `rman` and `typescript`.
 
 ```bash
 rman info
@@ -239,16 +245,38 @@ rman diff pkg-a          # since pkg-a's own last tag, scoped to its directory
 
 ### `rman changelog`
 
-Generates a changelog per package from unreleased commits, grouped into ✨ Features / 🐛 Bug Fixes
-/ 🔧 Other Changes.
+Generates a changelog per package from unreleased commits, with a section per Conventional Commits
+type (✨ Features, 🐛 Bug Fixes, ⚡ Performance, ...; anything else under 💬 General Changes) -
+renamed or extended with `.rmanrc "changelog.titles"`. With `changelog.groupBy: group`, one file per
+release group instead of per package.
 
 ```bash
 rman changelog                          # auto-detects each package's own last release
 rman changelog --from a1b2c3d           # since a specific commit, for every package
 rman changelog --write                  # prepend into each package's own CHANGELOG.md
 rman changelog --write --file-path docs/CHANGELOG.md
+rman changelog --rebuild                # regenerate the files from scratch instead of appending
+```
+
+### `rman deps [names..]`
+
+Lists the dependencies that have a newer version on their registry - every package, the monorepo
+root's own tooling included - and with `-u` writes the new ranges to the manifests, then checks that
+they still install.
+
+```bash
+rman deps                       # what could move, and what holds it back
+rman deps -u                    # write the new ranges, then check that they install
+rman deps --target major        # across a major too
+rman deps '@types/*'            # only the dependencies matching this glob
 ```
 
+**A dependency stays inside its major by default** (`deps.target: minor`). Taking a major is a
+decision a person makes: `--target major` for one run, `.rmanrc "deps.target"` for a standing
+answer, or `deps.targets` for one dependency. Only a caret or tilde range is rewritten; a version is
+offered only when every rule rman can see allows it. See
+[docs/cli/deps.md](https://github.com/panates/rman/blob/main/docs/cli/deps.md).
+
 ### `rman version [bump]`
 
 Bumps versions of changed packages (and their in-group dependents), grouped via `.rmanrc "group"`.
@@ -394,10 +422,11 @@ precedence: `package.json`'s own `"rman"` key, `.rmanrc.yml` (YAML), `.rmanrc` (
 the dotfile-style name), and `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` for config that needs real
 logic (a JS module's default export).
 
-**Who a declaration is about** follows one rule: unmarked keys configure the package of the
-directory declaring them, and a `"[selector]"` block configures the packages it names. So the
-repository root's own keys are the *root package's* - which is where repo-wide settings are read
-from anyway - and they reach the other packages only through a selector.
+**Who a declaration is about** follows one rule: what is written above reaches below, and a
+`"[selector]"` block narrows the audience. An unmarked key configures its directory's package and
+every package under it, so the repository root's own keys are the baseline for the whole repository.
+`"[/]"` is the root package alone, `"[platform:node]"` every package of that technology, and a glob
+such as `"[*]"` the packages below.
 
 ```yaml
 # .rmanrc.yml, at the repository root
@@ -405,6 +434,11 @@ packageManager: pnpm
 logLevel: info
 allowBranch: [main, release/*]
 
+'[/]': # the root package alone - run's scheduling keys are read from here
+  run:
+    build:
+      concurrency: 4
+
 version:
   commitMessage: 'chore(release): v{version}'
 
@@ -418,7 +452,6 @@ version:
   run:
     test: mocha # a bare string is shorthand for { exec: mocha }
     build:
-      concurrency: 4
       before: [rman run lint]
       exec: tsc -b tsconfig-build.json
       after: node ../../support/postbuild.cjs
@@ -462,15 +495,15 @@ used to cover them was removed.
 
 ## Programmatic API
 
-Every command above is a thin wrapper around an exported service function - call them directly
+Every command above is a thin wrapper around an exported service - call them directly
 from your own Node.js scripts without shelling out to the `rman` binary:
 
 ```ts
-import { Repository, VersionService } from 'rman';
+import { Repository, VersionPlanService } from 'rman';
 
 const repository = await Repository.create();
-const plan = await VersionService.getPlan(repository);
-await VersionService.applyPlan(repository, plan, { changelog: true, push: true });
+const plan = await VersionPlanService.getPlanner(repository.app).getPlan(repository);
+await repository.app.getService('version').applyPlan(plan, { changelog: true, push: true });
 ```
 
 Full reference, with detailed examples for every service (`VersionService`, `PublishService`,

package/builtins/platforms/node/services/version-plan.service.d.ts

@@ -9,7 +9,7 @@ import type { GitHelper } from '../../../../utils/git.js';
  * abstract because they are statements about an *ecosystem* rather than about releases. This is
  * npm's pair of answers.
  *
- * Registered through the plugin's `versionPlanner`, so `rman version`/`rman changed` work in a
+ * Registered through the plugin's `versionPlanner`, so `rman version` works in a
  * repository that registered the `node` built-in and say what is missing in one that did not.
  */
 export declare class NodeVersionPlanService extends VersionPlanService {

package/builtins/platforms/node/services/version-plan.service.js

@@ -8,7 +8,7 @@ import { VersionPlanService } from '../../../../services/version-plan.service.js
  * abstract because they are statements about an *ecosystem* rather than about releases. This is
  * npm's pair of answers.
  *
- * Registered through the plugin's `versionPlanner`, so `rman version`/`rman changed` work in a
+ * Registered through the plugin's `versionPlanner`, so `rman version` works in a
  * repository that registered the `node` built-in and say what is missing in one that did not.
  */
 export class NodeVersionPlanService extends VersionPlanService {

package/commands/changelog.command.js

@@ -13,7 +13,7 @@ const config = {
         target: 'cli',
         describe: 'Generate the changelog since this commit/hash, applied the same way to every package. ' +
             'Default (also "auto" explicitly): auto-detect per package from its own most recent release ' +
-            'tag - same as "version"/"changed" - falling back to the version its own ecosystem\'s ' +
+            'tag - same as "version" - falling back to the version its own ecosystem\'s ' +
             "registry reports (no tag yet), then to its whole history for a package that's never been " +
             'released at all',
         type: 'string',
@@ -43,7 +43,7 @@ const config = {
         cliName: 'release-version',
         describe: 'The version these notes are for - what the entry heading shows. Default: read back from ' +
             "each package's own latest release tag, which is only right once that release is tagged. " +
-            'Pass it when generating notes ahead of the bump (e.g. from "changed --json" in CI), ' +
+            'Pass it when generating notes ahead of the bump (e.g. from "version --json" in CI), ' +
             'otherwise the heading shows the previous release.',
         type: 'string',
     },
@@ -91,7 +91,8 @@ const config = {
         target: 'config',
         describe: "The release tag naming scheme each package's changelog boundary is detected from - " +
             '"{name}" is replaced with the package name (e.g. "{name}@*" for independent versioning). ' +
-            'Default "v*", one repo-wide tag resolved through git describe.',
+            'Default: "v*" (one repo-wide tag, resolved through git describe) while the repository has one ' +
+            'version line, "{name}@*" once it has several.',
         type: 'string',
     },
     /**

package/commands/info.command.js

@@ -60,13 +60,19 @@ function printSystemInfo(systemInfo) {
 }
 function printRepositoryInfo(info) {
     console.log('', colors.whiteBright('Repository') + ':');
-    console.log('    ' + colors.reset('Type') + '     :', colors.yellowBright(info.type === 'monorepo' ? 'Monorepo' : 'Single package'));
-    console.log('    ' + colors.reset('Name') + '     :', colors.yellowBright(info.name || '(none)'));
-    console.log('    ' + colors.reset('Version') + '  :', colors.yellowBright(info.version || '(none)'));
-    console.log('    ' + colors.reset('Root') + '     :', colors.yellowBright(info.root));
+    const rows = [
+        ['Type', colors.yellowBright(info.type === 'monorepo' ? 'Monorepo' : 'Single package')],
+        ['Name', colors.yellowBright(info.name || '(none)')],
+        ['Version', colors.yellowBright(info.version || '(none)')],
+        ['Root', colors.yellowBright(info.root)],
+        ['Platforms', colors.yellowBright(info.platforms.join(', ') || '(none)')],
+    ];
     if (info.type === 'monorepo') {
-        console.log('    ' + colors.reset('Packages') + ' :', colors.yellowBright(String(info.packageCount)), colors.gray('(run "list" to see them)'));
+        rows.push(['Packages', colors.yellowBright(String(info.packageCount)), colors.gray('(run "list" to see them)')]);
     }
+    const width = Math.max(...rows.map(([label]) => label.length));
+    for (const [label, ...values] of rows)
+        console.log('    ' + colors.reset(label.padEnd(width)) + ' :', ...values);
 }
 /**
  * `rman info` - environment and repository, and back in the core because most of what it reports

package/commands/version.command.js

@@ -210,6 +210,8 @@ const versionCommand = registerCommand(app => {
                     name: e.package.name,
                     selector: e.package.selector,
                     isRoot: e.package.isRoot,
+                    /** `rman list --json`'s spelling, so a consumer joins the two on it. */
+                    groupKey: e.groupKey,
                     group: e.group,
                     status: e.status,
                     from: e.from,
@@ -284,7 +286,8 @@ function printApplied(result) {
             console.log(`${colors.green('tags')}    ${release.map(label).join(', ')} ${colors.gray('(repository release)')}`);
     }
     console.log(result.pushed
-        ? `${colors.green('push')}    pushed, with tags`
+        ? `${colors.green('push')}    pushed the branch` +
+            (result.tags.length ? ` and ${result.tags.map(t => t.name).join(', ')}, together` : '')
         : `${colors.gray('push')}    ${colors.gray('not pushed - run with --push, or push it yourself')}`);
 }
 function printPlan(entries) {

package/constants.js

@@ -1 +1 @@
-export const version = '2.14.0';
+export const version = '2.15.1';

package/core/interfaces/manifest.js

@@ -53,7 +53,7 @@ export var Manifest;
             }
         }
         throw new Error(`No manifest provider recognizes "${dir}", so there is nowhere to write its version.\n` +
-            `  A repository's ".rmanrc" names its technologies - see "plugins" (e.g. ['node']).`);
+            `  A repository's ".rmanrc" names its technologies - see "platforms", or "extends" (e.g. "rman:node").`);
     }
     Manifest.write = write;
     /**

package/core/interfaces/plugin.d.ts

@@ -172,7 +172,7 @@ export declare function isPlugin(value: unknown): value is Plugin;
  * - no `getBinPaths` -> nothing is prepended to a child process's PATH, so the inherited one
  *   stands on its own rather than being guessed at;
  * - no `getRunSteps` -> a package's steps come from its `.rmanrc` alone, the core's only source;
- * - no `versionPlanner` -> `version`/`changed` fail naming the key, rather than releasing a
+ * - no `versionPlanner` -> `version` fails naming the key, rather than releasing a
  *   plausible but untrue set of packages from a default nobody chose.
  */
 export declare const basePlatform: Platform;

package/core/interfaces/plugin.js

@@ -73,7 +73,7 @@ export function isPlugin(value) {
  * - no `getBinPaths` -> nothing is prepended to a child process's PATH, so the inherited one
  *   stands on its own rather than being guessed at;
  * - no `getRunSteps` -> a package's steps come from its `.rmanrc` alone, the core's only source;
- * - no `versionPlanner` -> `version`/`changed` fail naming the key, rather than releasing a
+ * - no `versionPlanner` -> `version` fails naming the key, rather than releasing a
  *   plausible but untrue set of packages from a default nobody chose.
  */
 export const basePlatform = definePlatform({

package/package.json

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

package/services/change-hash.service.d.ts

@@ -106,8 +106,8 @@ export declare namespace ChangeHashService {
      * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
      * package". An explicit `options.from` (anything but `AUTO`) is returned as-is, applying the same
      * way to every package. Otherwise, it's auto-detected in order: (1) this package's own most recent
-     * release tag - the same network-free `findLatestTag` lookup `version`/`changed` themselves use,
-     * so all three commands agree on "since when" for any repo whose tags are the ones `rman version`
+     * release tag - the same network-free `findLatestTag` lookup `version` itself uses,
+     * so both commands agree on "since when" for any repo whose tags are the ones `rman version`
      * actually created; (2) failing that (no tag at all yet - e.g. onboarding `rman` onto a repo with
      * real release history but no `rman`-created tags), whatever this package's **own ecosystem**
      * reports as its published version (`Plugin.publishedVersion`), mapped to a git tag via

package/services/change-hash.service.js

@@ -134,8 +134,8 @@ export var ChangeHashService;
      * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
      * package". An explicit `options.from` (anything but `AUTO`) is returned as-is, applying the same
      * way to every package. Otherwise, it's auto-detected in order: (1) this package's own most recent
-     * release tag - the same network-free `findLatestTag` lookup `version`/`changed` themselves use,
-     * so all three commands agree on "since when" for any repo whose tags are the ones `rman version`
+     * release tag - the same network-free `findLatestTag` lookup `version` itself uses,
+     * so both commands agree on "since when" for any repo whose tags are the ones `rman version`
      * actually created; (2) failing that (no tag at all yet - e.g. onboarding `rman` onto a repo with
      * real release history but no `rman`-created tags), whatever this package's **own ecosystem**
      * reports as its published version (`Plugin.publishedVersion`), mapped to a git tag via

package/services/system-info.d.ts

@@ -7,6 +7,9 @@ export declare namespace SystemInfo {
         version: string;
         root: string;
         packageCount: number;
+        /** The technologies this run loaded, by `Platform.name`, in the order a directory is offered to
+         *  them - so `["cargo", "node"]` means a directory both recognize is a Cargo package. */
+        platforms: string[];
     }
     /** Whatever `envinfo` reports, grouped by category - shape is `envinfo`'s own, not ours. */
     type SystemInfo = Record<string, Record<string, unknown>>;

package/services/system-info.js

@@ -23,6 +23,7 @@ export var SystemInfo;
             version: repository.rootPackage.version,
             root: repository.dirname,
             packageCount: repository.getPackages().length,
+            platforms: [...repository.app.platforms].map(p => p.name),
         };
     }
     SystemInfo.getRepositoryInfo = getRepositoryInfo;

package/services/version-plan.service.d.ts

@@ -56,7 +56,8 @@ export declare abstract class VersionPlanService {
      * Across groups: a package depending on another group's bumped package always gets its scheme's
      * **smallest** bump of its own (never inheriting the source's) - the dependency reference itself
      * is the only thing that changed for it. Whether that re-triggers its own group's cascade is
-     * `cascade`'s answer for that smallest bump (`'changed'` under npm, so it does not), but it can
+     * `cascade`'s answer for that smallest bump (`'dependents'` under npm, so its own in-group
+     * dependents move with it), and it can
      * itself ripple into a third group, and so on, until nothing new is affected - see
      * `rippleCrossGroup`.
      *

package/services/version-plan.service.js

@@ -58,7 +58,8 @@ export class VersionPlanService {
      * Across groups: a package depending on another group's bumped package always gets its scheme's
      * **smallest** bump of its own (never inheriting the source's) - the dependency reference itself
      * is the only thing that changed for it. Whether that re-triggers its own group's cascade is
-     * `cascade`'s answer for that smallest bump (`'changed'` under npm, so it does not), but it can
+     * `cascade`'s answer for that smallest bump (`'dependents'` under npm, so its own in-group
+     * dependents move with it), and it can
      * itself ripple into a third group, and so on, until nothing new is affected - see
      * `rippleCrossGroup`.
      *
@@ -174,8 +175,8 @@ export class VersionPlanService {
          * The abort case, marked **after** the root entry so the whole table reads as one coherent
          * "if this were committed" preview rather than a mixture of two.
          *
-         * `to` survives the overwrite; `status` is what every writer filters on (`VersionService`,
-         * `changed`), so an `'error'` entry carrying a version cannot be applied by any of them - and
+         * `to` survives the overwrite; `status` is what every writer filters on (`VersionService`),
+         * so an `'error'` entry carrying a version cannot be applied by any of them - and
          * `version` throws on the first error before it would reach `applyPlan` anyway. The reason
          * keeps the boundary it was computed from, because the status column already says `error` and
          * a reader losing `changed since <tag>` loses the only thing that explains the number.
@@ -523,8 +524,9 @@ export class VersionPlanService {
     function getPlanner(app) {
         const planner = app.versionPlanner;
         if (!planner) {
-            throw new Error('No version planner is registered, so no version plan can be computed. Name a plugin that ' +
-                'contributes one in .rmanrc "plugins" - "rman-node" for a Node repository.');
+            throw new Error('No version planner is registered, so no version plan can be computed. Name a technology ' +
+                'that contributes one in .rmanrc "platforms", or reach it through "extends" - "rman:node" ' +
+                'for a Node repository, which is laid down by default unless presets were turned off.');
         }
         return planner;
     }

package/services/version.service.js

@@ -254,8 +254,21 @@ export class VersionService extends Service {
             tagged.push({ name: releaseTag, created: true, release: true });
         }
         const pushed = !!options.push && bumped.length > 0;
-        if (pushed)
-            await git.push();
+        if (pushed) {
+            /** Every tag this release names, including one that was already there: it is this release's
+             *  tag all the same, and a remote that lacks it is missing part of the release. */
+            const tags = tagged.map(t => t.name);
+            try {
+                await git.push({ tags });
+            }
+            catch (e) {
+                throw new Error(`${e.message}\n\n` +
+                    `  Nothing was pushed - the branch and its tags go up together or not at all. Left behind ` +
+                    `locally: ${commits.map(c => c.sha).join(', ') || 'no commit'}` +
+                    (tags.length ? `, tagged ${tags.join(', ')}` : '') +
+                    `.\n  Once the cause is fixed, push them with: git push --atomic origin HEAD ${tags.join(' ')}`.trimEnd(), { cause: e });
+            }
+        }
         return { entries: plan, updated: bumped, commits, tags: tagged, pushed };
     }
 }
@@ -361,8 +374,8 @@ export class VersionService extends Service {
                     (pkg.provider
                         ? `  The "${pkg.provider}" provider looked and found no version to change. Name the ` +
                             `identifier with { file, constant } if it is not "version", or drop the entry.`
-                        : `  This package belongs to no ecosystem (no plugin claimed it), so nothing knows how ` +
-                            `a version is declared in it. Name a plugin in .rmanrc "plugins".`));
+                        : `  This package belongs to no ecosystem (no platform claimed it), so nothing knows how ` +
+                            `a version is declared in it. Name the technology in .rmanrc "platforms", or reach it through "extends" (e.g. "rman:node").`));
             }
             /** Matched, but already reads the target - nothing to write and nothing to report. Distinct
              *  from the `undefined` above, which is "nothing here to rewrite at all". */
@@ -447,8 +460,8 @@ function assertStampable(pkg, version) {
             (pkg.provider
                 ? `  The "${pkg.provider}" provider looked and found no version to change. Name the ` +
                     `identifier with { file, constant } if it is not "version", or drop the entry.`
-                : `  This package belongs to no ecosystem (no plugin claimed it), so nothing knows how a ` +
-                    `version is declared in it. Name a plugin in .rmanrc "plugins".`));
+                : `  This package belongs to no ecosystem (no platform claimed it), so nothing knows how a ` +
+                    `version is declared in it. Name the technology in .rmanrc "platforms", or reach it through "extends" (e.g. "rman:node").`));
     }
 }
 /**

package/utils/git.d.ts

@@ -121,11 +121,13 @@ export declare class GitHelper {
      *  Throws if a tag with that name already exists - callers wanting idempotent tagging should
      *  check `tagExists` first. */
     createTag(name: string, message?: string): Promise<void>;
-    /** Pushes the current branch to `remote` (default `"origin"`), and its tags too unless
-     *  `options.tags` is `false`. */
+    /**
+     * Pushes the current branch to `remote` (default `"origin"`) together with `options.tags`, by
+     * name, in **one atomic push**: the branch and every tag go up, or none of them does.
+     */
     push(options?: {
         remote?: string;
-        tags?: boolean;
+        tags?: readonly string[];
     }): Promise<void>;
     /** `git remote get-url <remote>` (default `"origin"`) - `undefined` when that remote isn't
      *  configured at all, which is a perfectly normal state for a local-only repository. */

package/utils/git.js

@@ -394,14 +394,24 @@ export class GitHelper {
             throw new Error(`Unable to create tag "${name}": ${e.message}`, { cause: e });
         }
     }
-    /** Pushes the current branch to `remote` (default `"origin"`), and its tags too unless
-     *  `options.tags` is `false`. */
+    /**
+     * Pushes the current branch to `remote` (default `"origin"`) together with `options.tags`, by
+     * name, in **one atomic push**: the branch and every tag go up, or none of them does.
+     */
+    /* **Named tags, not `--tags`.** `git push <remote> --tags` sends every tag in the clone, so one
+     * stale tag from months ago - re-created locally, diverged from the remote's - failed every
+     * release from then on, and failed it *after* the new tag had already gone up. Measured on
+     * `postgrejs` with 2.15.0: `v3.13.0` pushed, `v3.10.0` rejected, exit 1, and in CI the publish
+     * step after it never ran.
+     *
+     * **One command, `--atomic`.** The branch used to go first and the tags second, so a failure in
+     * the second - GitHub's own `fatal error in commit_refs` did it to the same repository an hour
+     * earlier - left a pushed version bump with no tag, which a re-run cannot repair because it has
+     * nothing left to bump. Atomic, a failure leaves the remote exactly as it was. */
     async push(options) {
         const remote = options?.remote ?? 'origin';
         try {
-            await execFileAsync('git', ['push', remote], { cwd: this.cwd });
-            if (options?.tags !== false)
-                await execFileAsync('git', ['push', remote, '--tags'], { cwd: this.cwd });
+            await execFileAsync('git', ['push', '--atomic', remote, 'HEAD', ...(options?.tags ?? [])], { cwd: this.cwd });
         }
         catch (e) {
             throw new Error(`Unable to push to "${remote}": ${e.message}`, { cause: e });

package/utils/package-filter.d.ts

@@ -176,7 +176,7 @@ applySkip?: boolean): Package[];
  * **It only means anything where a command scopes by the current directory** - `run`/`build`/`test`,
  * `exec`, `clean`, `changelog` and `diff` narrow to `Repository.currentPackage` when you stand
  * inside a package, and this is the escape hatch. On a command that already works across the whole
- * repository (`version`, `publish`, `list`, `changed`) it would be a flag that does nothing, which
+ * repository (`version`, `publish`, `list`) it would be a flag that does nothing, which
  * is worse than not offering it: a no-op flag reads as a promise.
  *
  * That same rule is why there is no `--root-only` beside it, however naturally the pair reads: it

package/utils/package-filter.js

@@ -210,7 +210,7 @@ applySkip = true) {
  * **It only means anything where a command scopes by the current directory** - `run`/`build`/`test`,
  * `exec`, `clean`, `changelog` and `diff` narrow to `Repository.currentPackage` when you stand
  * inside a package, and this is the escape hatch. On a command that already works across the whole
- * repository (`version`, `publish`, `list`, `changed`) it would be a flag that does nothing, which
+ * repository (`version`, `publish`, `list`) it would be a flag that does nothing, which
  * is worse than not offering it: a no-op flag reads as a promise.
  *
  * That same rule is why there is no `--root-only` beside it, however naturally the pair reads: it