@williamthorsen/release-kit 16.1.1 → 17.0.0

package/.meta/changelog.json

@@ -1,4 +1,83 @@
 [
+  {
+    "version": "17.0.0",
+    "date": "2026-11-08",
+    "sections": [
+      {
+        "title": "🎉 Features",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Routes `release-kit` commands through the `toolbelt.cli` command parser, which renders help from each command's options and makes a usage error, such as an invalid `RELEASE_KIT_OUTPUT_STYLE` or a stray argument to `sync-labels sync`, exit 2 with a `Try` line instead of exit 1, and makes a bare `release-kit`, `release-kit overrides`, or `release-kit sync-labels` exit 2 instead of printing help and exiting 0. (#1186)",
+            "breaking": true,
+            "migration": "Update any script that checks for exit code 1 from a `release-kit` usage error to check for 2, and replace a bare `release-kit`, `release-kit overrides`, or `release-kit sync-labels` with the same command followed by `--help`; note that `release-kit overrides validate` already exits 2 for a schema or parse error, so a script cannot tell that error from a usage error by its exit code alone.",
+            "hash": "343c0f97b212aa710c49baf61fce118256da6db7",
+            "entry": 1
+          },
+          {
+            "description": "Prefixes each handled error line written by `nmr` and its other bins, `release-kit`, and `v11y-check` with the name of the program that wrote it, as `<bin>: <message>` in place of `Error: <message>`, for usage errors such as an unknown command or option as well, and names `v11y` for both of the bins in `v11y-check`. (#1190)",
+            "hash": "b7634734032c508e45388b7752b7b6905071273e",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that the tarball refusal from `release-kit prepare` and `release-kit publish` pointed to a `prepack` script, even though the check builds the package through its `prepublishOnly` script, and makes the refusal and `docs/releasing.md` name `\"prepublishOnly\": \"nmr build\"` instead. (#1193)",
+            "hash": "916c4dcf90766d43721feaad4d6d443f89533902",
+            "entry": 1
+          }
+        ]
+      },
+      {
+        "title": "♻️ Refactoring",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Replaces nmr's `isObject`, release-kit's `isRecord`, and the private copies in nmr-core's `workspace.ts` and an nmr test with one `isRecord` guard exported from the root entry of `@williamthorsen/nmr-core`. (#1194)",
+            "hash": "6c66148170145ccf5628c95d27e7783ef26d97e9",
+            "entry": 1
+          },
+          {
+            "description": "Group nmr-core's source by role (#1196)",
+            "body": "Groups `nmr-core`'s source modules into `cache`, `errors`, `files`, `git`, `portable`, and `workspace` directories by role, retiring `helpers/`, and moves the write-outcome reporters out of `terminal.ts` into `files/report-write-outcomes.ts`. The package's exports, including the `./workspace` subpath, resolve to the same modules at their new paths.",
+            "hash": "bddeaf8cdad251c681808688be3d459c60fc2bdb"
+          }
+        ]
+      },
+      {
+        "title": "📚 Documentation",
+        "audience": "dev",
+        "items": [
+          {
+            "description": "Documents for each shipped JSON Schema the `node_modules` path, such as `../node_modules/v11y-check/schemas/config.json`, that a project listing the package as a direct dependency can use as `$schema`, and states that the path does not resolve when the package is installed through another package or run through `pnpm dlx` or `npx`. (#1206)",
+            "hash": "cf19a9037ab15a24548ecc9cebe27c06f262ad6a",
+            "entry": 3
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "version": "16.1.2",
+    "date": "2026-11-06",
+    "sections": [
+      {
+        "title": "🐛 Bug fixes",
+        "audience": "all",
+        "items": [
+          {
+            "description": "Fixes the issue that `release-kit` printed a bug in its own code as an ordinary `Error: <message>`, which it now prints as `release-kit: internal error: <message>` followed by the stack, while a failure in the user's input, config, or environment, including a failed `git`, `gh`, or `npm` call, keeps the `Error: <message>` form. (#1158)",
+            "hash": "3a62cc768b23f37156c846f32fd4acaa70f7f931",
+            "entry": 1
+          }
+        ]
+      }
+    ]
+  },
   {
     "version": "16.1.1",
     "date": "2026-11-05",

package/.readyup/kits/default.js

@@ -18,7 +18,7 @@ import {
 // src/init/detectRepoType.ts
 import { existsSync, readFileSync } from "node:fs";
 
-// src/typeGuards.ts
+// ../nmr-core/dist/esm/portable/isRecord.js
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -234,7 +234,7 @@ var CREATE_GITHUB_RELEASE_WORKFLOW_HASH_SINGLE = "d6de961de913c67b08dfa7e07f7349
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "16.1.1" };
+  const picked = { "version": "17.0.0" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }

package/.readyup/kits/npm-auto-publish.js

@@ -20,7 +20,7 @@ import {
 // src/npmRegistry.ts
 import { execFileSync } from "node:child_process";
 
-// src/typeGuards.ts
+// ../nmr-core/dist/esm/portable/isRecord.js
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/.readyup/manifest.json

@@ -2,12 +2,31 @@
   "version": 1,
   "kits": [
     {
+      "bundledDependencies": {
+        "@williamthorsen/toolbelt.datetime": "4.1.0",
+        "@williamthorsen/toolbelt.errors": "0.9.0",
+        "@williamthorsen/toolbelt.filesystem": "0.10.0",
+        "@williamthorsen/toolbelt.numbers": "7.3.0",
+        "@williamthorsen/toolbelt.objects": "4.4.0",
+        "@williamthorsen/toolbelt.packaging": "0.7.0",
+        "@williamthorsen/toolbelt.terminal": "0.3.0",
+        "ansi-regex": "6.5.0",
+        "ansi-styles": "6.2.3",
+        "cli-truncate": "6.1.1",
+        "diff": "9.0.0",
+        "get-east-asian-width": "1.7.0",
+        "is-fullwidth-code-point": "5.1.0",
+        "slice-ansi": "9.0.1",
+        "string-width": "8.3.0",
+        "strip-ansi": "7.2.0",
+        "wrap-ansi": "10.0.2"
+      },
       "checklistChecks": [
         {
           "checklist": "release-kit",
           "checks": [
             "@williamthorsen/release-kit in devDependencies",
-            "@williamthorsen/release-kit >= 16.1.1",
+            "@williamthorsen/release-kit >= 17.0.0",
             "release.yaml workflow exists",
             "release.yaml matches template",
             "release.yaml does not reference deprecated tag ref",
@@ -42,6 +61,86 @@
       ],
       "esbuildVersion": "0.28.2",
       "inputs": [
+        {
+          "hash": "bf29a9a3",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/cache/cache-store.js"
+        },
+        {
+          "hash": "6b7d0243",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/hasErrnoCode.js"
+        },
+        {
+          "hash": "85d76864",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/isAnticipatedFailure.js"
+        },
+        {
+          "hash": "e02e0a74",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/UserError.js"
+        },
+        {
+          "hash": "77aa59f7",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/report-write-outcomes.js"
+        },
+        {
+          "hash": "5ae3e980",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/updateManagedFile.js"
+        },
+        {
+          "hash": "d377c37c",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/writeFileWithCheck.js"
+        },
+        {
+          "hash": "bc0baa4a",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/collectChangedPaths.js"
+        },
+        {
+          "hash": "70d519e7",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/gitObjects.js"
+        },
+        {
+          "hash": "d5a89448",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/gitOutputLimit.js"
+        },
+        {
+          "hash": "62be92c4",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/hashWorkingTree.js"
+        },
+        {
+          "hash": "6734717f",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/runGit.js"
+        },
+        {
+          "hash": "fe9fd44c",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/index.js"
+        },
+        {
+          "hash": "1d74f646",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/portable/isRecord.js"
+        },
+        {
+          "hash": "b88a9126",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/terminal.js"
+        },
+        {
+          "hash": "85afaf3e",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/timer.js"
+        },
         {
           "hash": "56566d0b",
           "kind": "module",
@@ -63,7 +162,7 @@
           "path": "lib/workflow-hashes.ts"
         },
         {
-          "hash": "1c9904c3",
+          "hash": "8df94cba",
           "kind": "inline",
           "path": "../package.json",
           "paths": [
@@ -81,7 +180,7 @@
           "path": "../src/init/detectRepoType.ts"
         },
         {
-          "hash": "9ca0f6bf",
+          "hash": "133be525",
           "kind": "module",
           "path": "../src/init/parseJsonRecord.ts"
         },
@@ -89,11 +188,6 @@
           "hash": "2210df36",
           "kind": "module",
           "path": "../src/packsPath.ts"
-        },
-        {
-          "hash": "1424b343",
-          "kind": "module",
-          "path": "../src/typeGuards.ts"
         }
       ],
       "name": "default",
@@ -101,9 +195,28 @@
       "readyupVersion": "0.45.0",
       "source": "kits/default.ts",
       "sourceHash": "56566d0b",
-      "targetHash": "070a29f8"
+      "targetHash": "060f7720"
     },
     {
+      "bundledDependencies": {
+        "@williamthorsen/toolbelt.datetime": "4.1.0",
+        "@williamthorsen/toolbelt.errors": "0.9.0",
+        "@williamthorsen/toolbelt.filesystem": "0.10.0",
+        "@williamthorsen/toolbelt.numbers": "7.3.0",
+        "@williamthorsen/toolbelt.objects": "4.4.0",
+        "@williamthorsen/toolbelt.packaging": "0.7.0",
+        "@williamthorsen/toolbelt.terminal": "0.3.0",
+        "ansi-regex": "6.5.0",
+        "ansi-styles": "6.2.3",
+        "cli-truncate": "6.1.1",
+        "diff": "9.0.0",
+        "get-east-asian-width": "1.7.0",
+        "is-fullwidth-code-point": "5.1.0",
+        "slice-ansi": "9.0.1",
+        "string-width": "8.3.0",
+        "strip-ansi": "7.2.0",
+        "wrap-ansi": "10.0.2"
+      },
       "checklistChecks": [
         {
           "checklist": "repo",
@@ -129,6 +242,86 @@
       ],
       "esbuildVersion": "0.28.2",
       "inputs": [
+        {
+          "hash": "bf29a9a3",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/cache/cache-store.js"
+        },
+        {
+          "hash": "6b7d0243",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/hasErrnoCode.js"
+        },
+        {
+          "hash": "85d76864",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/isAnticipatedFailure.js"
+        },
+        {
+          "hash": "e02e0a74",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/errors/UserError.js"
+        },
+        {
+          "hash": "77aa59f7",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/report-write-outcomes.js"
+        },
+        {
+          "hash": "5ae3e980",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/updateManagedFile.js"
+        },
+        {
+          "hash": "d377c37c",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/files/writeFileWithCheck.js"
+        },
+        {
+          "hash": "bc0baa4a",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/collectChangedPaths.js"
+        },
+        {
+          "hash": "70d519e7",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/gitObjects.js"
+        },
+        {
+          "hash": "d5a89448",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/gitOutputLimit.js"
+        },
+        {
+          "hash": "62be92c4",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/hashWorkingTree.js"
+        },
+        {
+          "hash": "6734717f",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/git/runGit.js"
+        },
+        {
+          "hash": "fe9fd44c",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/index.js"
+        },
+        {
+          "hash": "1d74f646",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/portable/isRecord.js"
+        },
+        {
+          "hash": "b88a9126",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/terminal.js"
+        },
+        {
+          "hash": "85afaf3e",
+          "kind": "module",
+          "path": "../../nmr-core/dist/esm/timer.js"
+        },
         {
           "hash": "682fdd4a",
           "kind": "module",
@@ -145,14 +338,9 @@
           "path": "../src/init/hasProvenance.ts"
         },
         {
-          "hash": "bb8746b3",
+          "hash": "4f6456ae",
           "kind": "module",
           "path": "../src/npmRegistry.ts"
-        },
-        {
-          "hash": "1424b343",
-          "kind": "module",
-          "path": "../src/typeGuards.ts"
         }
       ],
       "name": "npm-auto-publish",
@@ -160,7 +348,7 @@
       "readyupVersion": "0.45.0",
       "source": "kits/npm-auto-publish.ts",
       "sourceHash": "682fdd4a",
-      "targetHash": "52d15648"
+      "targetHash": "bdd314ac"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## 17.0.0 — 2026-11-08
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Routes `release-kit` commands through the `toolbelt.cli` command parser, which renders help from each command's options and makes a usage error, such as an invalid `RELEASE_KIT_OUTPUT_STYLE` or a stray argument to `sync-labels sync`, exit 2 with a `Try` line instead of exit 1, and makes a bare `release-kit`, `release-kit overrides`, or `release-kit sync-labels` exit 2 instead of printing help and exiting 0. (#1186)
+- Prefixes each handled error line written by `nmr` and its other bins, `release-kit`, and `v11y-check` with the name of the program that wrote it, as `<bin>: <message>` in place of `Error: <message>`, for usage errors such as an unknown command or option as well, and names `v11y` for both of the bins in `v11y-check`. (#1190)
+
+### 🐛 Bug fixes
+
+- Fixes the issue that the tarball refusal from `release-kit prepare` and `release-kit publish` pointed to a `prepack` script, even though the check builds the package through its `prepublishOnly` script, and makes the refusal and `docs/releasing.md` name `"prepublishOnly": "nmr build"` instead. (#1193)
+
+### ♻️ Refactoring
+
+- Replaces nmr's `isObject`, release-kit's `isRecord`, and the private copies in nmr-core's `workspace.ts` and an nmr test with one `isRecord` guard exported from the root entry of `@williamthorsen/nmr-core`. (#1194)
+- Group nmr-core's source by role (#1196)
+
+  Groups `nmr-core`'s source modules into `cache`, `errors`, `files`, `git`, `portable`, and `workspace` directories by role, retiring `helpers/`, and moves the write-outcome reporters out of `terminal.ts` into `files/report-write-outcomes.ts`. The package's exports, including the `./workspace` subpath, resolve to the same modules at their new paths.
+
+### 📚 Documentation
+
+- Documents for each shipped JSON Schema the `node_modules` path, such as `../node_modules/v11y-check/schemas/config.json`, that a project listing the package as a direct dependency can use as `$schema`, and states that the path does not resolve when the package is installed through another package or run through `pnpm dlx` or `npx`. (#1206)
+
+## 16.1.2 — 2026-11-06
+
+### 🐛 Bug fixes
+
+- Fixes the issue that `release-kit` printed a bug in its own code as an ordinary `Error: <message>`, which it now prints as `release-kit: internal error: <message>` followed by the stack, while a failure in the user's input, config, or environment, including a failed `git`, `gh`, or `npm` call, keeps the `Error: <message>` form. (#1158)
+
 ## 16.1.1 — 2026-11-05
 
 ### 🐛 Bug fixes

package/README.md

@@ -7,11 +7,16 @@ Version-bumping and changelog-generation toolkit for release workflows.
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from the same commit history that decides each bump (with optional [editorial overrides](docs/editorial-overrides.md)).
 
 <!-- section:release-notes -->
-## Release notes — v16.1.1 (2026-11-05)
+## Release notes — v17.0.0 (2026-11-08)
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Routes `release-kit` commands through the `toolbelt.cli` command parser, which renders help from each command's options and makes a usage error, such as an invalid `RELEASE_KIT_OUTPUT_STYLE` or a stray argument to `sync-labels sync`, exit 2 with a `Try` line instead of exit 1, and makes a bare `release-kit`, `release-kit overrides`, or `release-kit sync-labels` exit 2 instead of printing help and exiting 0. (#1186)
+- Prefixes each handled error line written by `nmr` and its other bins, `release-kit`, and `v11y-check` with the name of the program that wrote it, as `<bin>: <message>` in place of `Error: <message>`, for usage errors such as an unknown command or option as well, and names `v11y` for both of the bins in `v11y-check`. (#1190)
 
 ### 🐛 Bug fixes
 
-- Fixes the issue that the bin scripts of `nmr`, `release-kit`, and `v11y-check` reported every error other than missing build output as `<bin>: failed to load: <message>` without a stack, which hid where the fault occurred. (#1157)
+- Fixes the issue that the tarball refusal from `release-kit prepare` and `release-kit publish` pointed to a `prepack` script, even though the check builds the package through its `prepublishOnly` script, and makes the refusal and `docs/releasing.md` name `"prepublishOnly": "nmr build"` instead. (#1193)
 <!-- /section:release-notes -->
 
 ## Installation

package/bin/release-kit.js

@@ -11,5 +11,5 @@ try {
     const frames = firstFrame === -1 ? '' : `${lines.slice(firstFrame).join('\n')}\n`;
     process.stderr.write(`release-kit: internal error: ${message}\n${frames}`);
   }
-  process.exit(1);
+  process.exitCode = 1;
 }

package/dist/esm/assertCleanWorkingTree.js

@@ -1,12 +1,19 @@
 import { execFileSync } from 'node:child_process';
-import { GIT_OUTPUT_LIMIT_BYTES } from '@williamthorsen/nmr-core';
+import { GIT_OUTPUT_LIMIT_BYTES, UserError } from '@williamthorsen/nmr-core';
+import { asUserError } from "./user-error-chaining.js";
 export function assertCleanWorkingTree() {
-    const status = execFileSync('git', ['status', '--porcelain'], {
-        encoding: 'utf8',
-        maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
-        stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    let status;
+    try {
+        status = execFileSync('git', ['status', '--porcelain'], {
+            encoding: 'utf8',
+            maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (error) {
+        throw asUserError(error);
+    }
     if (status.length > 0) {
-        throw new Error('Working tree has uncommitted changes. Commit or stash them, or use --no-git-checks to bypass this check.');
+        throw new UserError('Working tree has uncommitted changes. Commit or stash them, or use --no-git-checks to bypass this check.');
     }
 }

package/dist/esm/assertReleasesOnNpm.js

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isRecord, UserError } from '@williamthorsen/nmr-core';
 import { isPublishableManifest } from "./isPublishableManifest.js";
 import { lookUpNpmPackage } from "./npmRegistry.js";
-import { isRecord } from "./typeGuards.js";
+import { chainUserError } from "./user-error-chaining.js";
 export function assertReleasesOnNpm(workspacePaths) {
     const unpublishedCandidates = [];
     const unverifiableCandidates = [];
@@ -22,10 +23,17 @@ export function assertReleasesOnNpm(workspacePaths) {
     if (unpublishedCandidates.length === 0 && unverifiableCandidates.length === 0) {
         return;
     }
-    throw new Error(describeRefusal(unpublishedCandidates, unverifiableCandidates));
+    throw new UserError(describeRefusal(unpublishedCandidates, unverifiableCandidates));
 }
 function buildNpmCandidate(workspacePath) {
-    const manifest = JSON.parse(readFileSync(join(workspacePath, 'package.json'), 'utf8'));
+    const manifestPath = join(workspacePath, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw chainUserError(`Failed to parse ${manifestPath}`, error);
+    }
     if (!isRecord(manifest) || !isPublishableManifest(manifest) || typeof manifest['name'] !== 'string') {
         return undefined;
     }

package/dist/esm/assertTaggedBaseline.js

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 import { resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { readChangelogEntries } from "./changelogJsonUtils.js";
 import { readCurrentVersion } from "./planVersionBump.js";
@@ -8,7 +9,7 @@ export function assertTaggedBaseline(findings) {
     if (untaggedFindings.length === 0)
         return;
     const lines = untaggedFindings.map(({ label, version, tag }) => `  - ${label}: ${version} (create tag ${tag})`);
-    throw new Error([
+    throw new UserError([
         'The current version is recorded in the changelog, but its tag is not the previous tag reachable from HEAD:',
         ...lines,
         'Tag the commit that released each version, then run prepare again.',

package/dist/esm/assertTarballsComplete.js

@@ -1,11 +1,12 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isAnticipatedFailure, isRecord, UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { detectPackageManager } from "./detectPackageManager.js";
 import { findMissingManifestPaths } from "./findMissingManifestPaths.js";
 import { isPublishableManifest } from "./isPublishableManifest.js";
 import { packFromCleanCheckout } from "./packFromCleanCheckout.js";
-import { isRecord } from "./typeGuards.js";
+import { chainUserError } from "./user-error-chaining.js";
 export function assertTarballsComplete(workspacePaths, devExportConditions, pack = packFromCleanCheckout) {
     const candidates = workspacePaths
         .map((workspacePath) => ({ workspacePath, manifest: readManifest(workspacePath) }))
@@ -19,7 +20,10 @@ export function assertTarballsComplete(workspacePaths, devExportConditions, pack
         filesByWorkspace = pack(candidates.map(({ workspacePath }) => workspacePath), detectPackageManager());
     }
     catch (error) {
-        throw new Error(`Cannot release: The packages could not be packed from a clean checkout of HEAD.\n${describeError(error)}`, { cause: error });
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
+        throw new UserError(`Cannot release: The packages could not be packed from a clean checkout of HEAD.\n${describeError(error)}`, { cause: error });
     }
     const incompletePackages = candidates
         .map(({ workspacePath, manifest }) => ({
@@ -31,7 +35,7 @@ export function assertTarballsComplete(workspacePaths, devExportConditions, pack
     if (incompletePackages.length === 0) {
         return;
     }
-    throw new Error(describeRefusal(incompletePackages));
+    throw new UserError(describeRefusal(incompletePackages));
 }
 function describeRefusal(incompletePackages) {
     const sections = ['Cannot release: The tarball of every package must contain each file that its manifest names.'];
@@ -42,11 +46,18 @@ function describeRefusal(incompletePackages) {
             ...missingPaths.map(({ location, path }) => `  - ${path} (${location})`),
         ].join('\n'));
     }
-    sections.push('Build these files in the package\'s publish lifecycle, such as in a "prepack" script. ' +
+    sections.push('Build these files in the package\'s prepublishOnly script, usually "prepublishOnly": "nmr build". ' +
         'If an export condition is for development only, list it in the "devExportConditions" config key.');
     return sections.join('\n\n');
 }
 function readManifest(workspacePath) {
-    const manifest = JSON.parse(readFileSync(join(workspacePath, 'package.json'), 'utf8'));
+    const manifestPath = join(workspacePath, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw chainUserError(`Failed to parse ${manifestPath}`, error);
+    }
     return isRecord(manifest) ? manifest : {};
 }

package/dist/esm/bin.d.ts

@@ -0,0 +1,2 @@
+/** The program name that release-kit's errors and help name. */
+export declare const BIN = "release-kit";

package/dist/esm/bin.js

@@ -0,0 +1 @@
+export const BIN = 'release-kit';

package/dist/esm/buildChangelogEntries.js

@@ -1,4 +1,3 @@
-import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { buildEntryItem, buildTitleItem, hasRoutedEntry, } from "./buildChangelogItem.js";
 import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { extractVersion } from "./changelogJsonUtils.js";
@@ -8,6 +7,7 @@ import { determineBumpType } from "./determineBumpType.js";
 import { enumerateReleaseWindows } from "./enumerateReleaseWindows.js";
 import { parseChangeRecordBlock } from "./parseChangeRecordBlock.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
+import { prefixUserError } from "./user-error-chaining.js";
 const UNRELEASED_TAG = 'unreleased';
 const CANONICAL_SECTION_ORDER = new Map(Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index]));
 export function buildChangelogEntries(config, tag, options) {
@@ -49,7 +49,7 @@ export function readReleaseHistory(config, options) {
         return transformReleases(windows, context);
     }
     catch (error) {
-        throw chainError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
+        throw prefixUserError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
     }
 }
 export function stripGroupDecorations(group) {

package/dist/esm/buildDependencyGraph.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
-import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { UserError } from '@williamthorsen/nmr-core';
+import { chainUserError } from "./user-error-chaining.js";
 function isPackageJsonSubset(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -56,17 +57,17 @@ function readPackageJsonSubset(filePath) {
         content = readFileSync(filePath, 'utf8');
     }
     catch (error) {
-        throw chainError(`Failed to read ${filePath}`, error);
+        throw chainUserError(`Failed to read ${filePath}`, error);
     }
     let parsedJson;
     try {
         parsedJson = JSON.parse(content);
     }
     catch (error) {
-        throw chainError(`Failed to parse JSON in ${filePath}`, error);
+        throw chainUserError(`Failed to parse JSON in ${filePath}`, error);
     }
     if (!isPackageJsonSubset(parsedJson)) {
-        throw new Error(`Invalid package.json at ${filePath}`);
+        throw new UserError(`Invalid package.json at ${filePath}`);
     }
     return parsedJson;
 }