@williamthorsen/release-kit 16.1.0 → 16.1.2

package/dist/esm/resolveCommandTags.js

@@ -1,19 +1,18 @@
 import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { formatExcludedSkip } from "./formatExcludedSkip.js";
 import { readRootPackageVersion } from "./loadConfig.js";
 import { mergeMonorepoConfig } from "./mergeConfig.js";
 import { resolveReleaseTags } from "./resolveReleaseTags.js";
+import { prefixUserError } from "./user-error-chaining.js";
 export function resolveCommandTags(tags, userConfig) {
     let workspace;
     try {
         workspace = discoverWorkspaces();
     }
     catch (error) {
-        reportError(`Failed to discover workspaces: ${describeError(error)}`);
-        process.exit(1);
+        throw prefixUserError('Failed to discover workspaces', error);
     }
     if (workspace.kind === 'empty') {
         reportError(`No workspace package to tag. ${describeEmptyWorkspace(workspace)}`);
@@ -38,8 +37,7 @@ export function resolveCommandTags(tags, userConfig) {
         }
     }
     catch (error) {
-        reportError(`Failed to resolve workspaces: ${describeError(error)}`);
-        process.exit(1);
+        throw prefixUserError('Failed to resolve workspaces', error);
     }
     let resolvedTags;
     if (workspaces !== undefined) {

package/dist/esm/resolveReleaseDeclaration.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { UserError } from '@williamthorsen/nmr-core';
 export function getTargetName(workspace) {
     return workspace.targetName ?? workspace.dir;
 }
@@ -21,13 +22,13 @@ function applyLegacyIdentities(workspace, legacyIdentities) {
 function claimPath(entryByPath, name, claimedPath, kind) {
     const claimingEntryName = entryByPath.get(claimedPath);
     if (claimingEntryName !== undefined) {
-        throw new Error(`releases.${name}: ${kind} '${claimedPath}' is already declared by releases.${claimingEntryName}; declare each ${kind} once`);
+        throw new UserError(`releases.${name}: ${kind} '${claimedPath}' is already declared by releases.${claimingEntryName}; declare each ${kind} once`);
     }
     entryByPath.set(claimedPath, name);
 }
 function declareDirectory(name, entry, normalizedPath) {
     if (path.posix.isAbsolute(normalizedPath) || normalizedPath === '..' || normalizedPath.startsWith('../')) {
-        throw new Error(`releases.${name}: path '${entry.path}' is outside the repo; declare a repo-relative directory`);
+        throw new UserError(`releases.${name}: path '${entry.path}' is outside the repo; declare a repo-relative directory`);
     }
     const isRoot = normalizedPath === '.' || normalizedPath === '';
     return {
@@ -52,12 +53,12 @@ function resolveCompositeMembers(composite, retainedWorkspaces, excludedWorkspac
         }
         const label = `releases.${composite.name}.includes: '${memberName}'`;
         if (memberName === composite.name) {
-            throw new Error(`${label} is the composite itself; a composite includes package and directory targets only`);
+            throw new UserError(`${label} is the composite itself; a composite includes package and directory targets only`);
         }
         if (excludedWorkspaces.some((workspace) => workspace.dir === memberName)) {
-            throw new Error(`${label} is excluded, so the composite cannot include it`);
+            throw new UserError(`${label} is excluded, so the composite cannot include it`);
         }
-        throw new Error(`${label} is not a release target. Known targets: ${membersByName.keys().toArray().join(', ')}`);
+        throw new UserError(`${label} is not a release target. Known targets: ${membersByName.keys().toArray().join(', ')}`);
     });
 }
 function resolveLegacyBlocks(workspaces, overrides, project) {
@@ -93,7 +94,7 @@ function resolveReleasesBlock(workspaces, releases) {
     for (const [name, entry] of Object.entries(releases)) {
         if (entry !== false && 'includes' in entry) {
             if (composite !== undefined) {
-                throw new Error(`releases declares more than one composite ('${composite.name}', '${name}'); ` +
+                throw new UserError(`releases declares more than one composite ('${composite.name}', '${name}'); ` +
                     'a composite is versioned by the root package.json, which only one composite can own');
             }
             composite = {
@@ -106,7 +107,7 @@ function resolveReleasesBlock(workspaces, releases) {
         if (entry === false) {
             const workspace = workspaceByDir.get(name);
             if (workspace === undefined) {
-                throw new Error(`releases.${name}: false excludes a discovered workspace by its directory name, and no workspace is named '${name}'. ` +
+                throw new UserError(`releases.${name}: false excludes a discovered workspace by its directory name, and no workspace is named '${name}'. ` +
                     `Known workspaces: ${workspaceByDir.keys().toArray().join(', ')}`);
             }
             claimPath(entryByPath, name, workspace.workspacePath, 'workspace');
@@ -122,7 +123,7 @@ function resolveReleasesBlock(workspaces, releases) {
             continue;
         }
         if (entry.tagPrefix !== undefined) {
-            throw new Error(`releases.${name}: tagPrefix applies only to a directory target, and '${workspace.workspacePath}' is a workspace, ` +
+            throw new UserError(`releases.${name}: tagPrefix applies only to a directory target, and '${workspace.workspacePath}' is a workspace, ` +
                 "whose tag prefix derives from its package name; declare the workspace's earlier prefixes in legacyIdentities");
         }
         claimPath(entryByPath, name, workspace.workspacePath, 'workspace');

package/dist/esm/resolveReleaseTags.js

@@ -2,13 +2,20 @@ import { execFileSync } from 'node:child_process';
 import { GIT_OUTPUT_LIMIT_BYTES } from '@williamthorsen/nmr-core';
 import { getTargetName } from "./resolveReleaseDeclaration.js";
 import { PROJECT_TARGET_ID } from "./resolveReleaseTargets.js";
+import { asUserError } from "./user-error-chaining.js";
 const VERSION_PATTERN = /^v\d+\.\d+\.\d+/;
 const SEMVER_SUFFIX_PATTERN = /^\d+\.\d+\.\d+/;
 export function resolveReleaseTags(args) {
-    const output = execFileSync('git', ['tag', '--points-at', 'HEAD'], {
-        encoding: 'utf8',
-        maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
-    });
+    let output;
+    try {
+        output = execFileSync('git', ['tag', '--points-at', 'HEAD'], {
+            encoding: 'utf8',
+            maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
+        });
+    }
+    catch (error) {
+        throw asUserError(error);
+    }
     const tags = output
         .split('\n')
         .map((line) => line.trim())

package/dist/esm/resolveReleaseTargets.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { UserError } from '@williamthorsen/nmr-core';
 import { isPublishableManifest } from "./isPublishableManifest.js";
 import { readRootPackageVersion } from "./loadConfig.js";
 import { mergeMonorepoConfig, mergeSinglePackageConfig } from "./mergeConfig.js";
@@ -35,7 +36,7 @@ function assertUniqueTargetIds(targets) {
     }
     for (const [id, paths] of pathsById) {
         if (paths.length > 1) {
-            throw new Error(`Duplicate release target id '${id}' for workspaces: ${paths.join(', ')}`);
+            throw new UserError(`Duplicate release target id '${id}' for workspaces: ${paths.join(', ')}`);
         }
     }
 }

package/dist/esm/runCli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dispatches the `release-kit` command named by `args[0]`. A command exits the process itself; a failure that it throws
+ * propagates to the caller.
+ */
+export declare function runCli(args: string[]): Promise<void>;

package/dist/esm/runCli.js

@@ -0,0 +1,224 @@
+import { parseArgsOrExit, reportError, resolveSelfVersion } from '@williamthorsen/nmr-core';
+import { commitCommand } from "./commitCommand.js";
+import { configFlagSchema } from "./configFlagSchema.js";
+import { createGithubReleaseCommand } from "./createGithubReleaseCommand.js";
+import { enterRepoRoot } from "./enterRepoRoot.js";
+import { showInitHelp, showUpdateTemplatesHelp } from "./help/initHelp.js";
+import { showOverridesHelp, showOverridesValidateHelp } from "./help/overridesHelp.js";
+import { showPrepareHelp } from "./help/prepareHelp.js";
+import { showCommitHelp, showCreateGithubReleaseHelp, showPublishHelp, showPushHelp, showShowTagPrefixesHelp, showTagHelp, } from "./help/releaseStepsHelp.js";
+import { showSyncLabelsGenerateHelp, showSyncLabelsHelp, showSyncLabelsInitHelp, showSyncLabelsSyncHelp, } from "./help/syncLabelsHelp.js";
+import { showUsage } from "./help/usage.js";
+import { initCommand } from "./init/initCommand.js";
+import { updateTemplatesCommand } from "./init/updateTemplatesCommand.js";
+import { prepareCommand } from "./prepareCommand.js";
+import { publishCommand } from "./publishCommand.js";
+import { pushCommand } from "./pushCommand.js";
+import { resolveConfigFlag } from "./resolveConfigFlag.js";
+import { resolveStylesOrExit } from "./resolveStylesOrExit.js";
+import { showTagPrefixesCommand } from "./showTagPrefixesCommand.js";
+import { generateCommand } from "./sync-labels/generateCommand.js";
+import { syncLabelsInitCommand } from "./sync-labels/initCommand.js";
+import { syncLabelsCommand } from "./sync-labels/syncCommand.js";
+import { tagCommand } from "./tagCommand.js";
+import { validateOverridesCommand } from "./validateOverridesCommand.js";
+const VERSION = resolveSelfVersion(import.meta.url);
+export async function runCli(args) {
+    const command = args[0];
+    if (command === '--version' || command === '-V') {
+        console.info(VERSION);
+        process.exit(0);
+    }
+    if (command === undefined || ['--help', '-h'].includes(command)) {
+        showUsage();
+        process.exit(0);
+    }
+    const flags = args.slice(1);
+    const styles = resolveStylesOrExit({
+        env: process.env,
+        stderrIsTty: process.stderr.isTTY,
+        stdoutIsTty: process.stdout.isTTY,
+    });
+    if (command === 'prepare') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showPrepareHelp();
+            process.exit(0);
+        }
+        const { invocationDir } = enterRepoRoot();
+        await prepareCommand(flags, styles, invocationDir);
+        process.exit(0);
+    }
+    if (command === 'commit') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showCommitHelp();
+            process.exit(0);
+        }
+        enterRepoRoot();
+        commitCommand(flags);
+        process.exit(0);
+    }
+    if (command === 'tag') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showTagHelp();
+            process.exit(0);
+        }
+        enterRepoRoot();
+        tagCommand(flags, styles);
+        process.exit(0);
+    }
+    if (command === 'push') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showPushHelp();
+            process.exit(0);
+        }
+        const { invocationDir } = enterRepoRoot();
+        await pushCommand(flags, styles, invocationDir);
+        process.exit(0);
+    }
+    if (command === 'create-github-release') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showCreateGithubReleaseHelp();
+            process.exit(0);
+        }
+        const { invocationDir } = enterRepoRoot();
+        await createGithubReleaseCommand(flags, styles, invocationDir);
+        process.exit(0);
+    }
+    if (command === 'publish') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showPublishHelp();
+            process.exit(0);
+        }
+        const { invocationDir } = enterRepoRoot();
+        await publishCommand(flags, styles, invocationDir);
+        process.exit(0);
+    }
+    if (command === 'show-tag-prefixes') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showShowTagPrefixesHelp();
+            process.exit(0);
+        }
+        const { invocationDir } = enterRepoRoot();
+        const { config } = parseArgsOrExit(flags, configFlagSchema).flags;
+        const exitCode = await showTagPrefixesCommand(styles, resolveConfigFlag(config, invocationDir));
+        process.exit(exitCode);
+    }
+    if (command === 'init') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showInitHelp();
+            process.exit(0);
+        }
+        enterRepoRoot();
+        const initFlagSchema = {
+            isDryRun: { long: '--dry-run', type: 'boolean' },
+            shouldForce: { long: '--force', type: 'boolean' },
+            shouldScaffoldConfig: { long: '--with-config', type: 'boolean' },
+        };
+        const { isDryRun, shouldForce, shouldScaffoldConfig } = parseArgsOrExit(flags, initFlagSchema).flags;
+        const exitCode = initCommand({ isDryRun, shouldForce, styles, shouldScaffoldConfig });
+        process.exit(exitCode);
+    }
+    if (command === 'update-templates') {
+        if (flags.some((f) => f === '--help' || f === '-h')) {
+            showUpdateTemplatesHelp();
+            process.exit(0);
+        }
+        enterRepoRoot();
+        const updateTemplatesFlagSchema = {
+            isDryRun: { long: '--dry-run', type: 'boolean' },
+        };
+        const { isDryRun } = parseArgsOrExit(flags, updateTemplatesFlagSchema).flags;
+        const exitCode = updateTemplatesCommand({ isDryRun, styles });
+        process.exit(exitCode);
+    }
+    if (command === 'sync-labels') {
+        const subcommand = flags[0];
+        if (subcommand === undefined || ['--help', '-h'].includes(subcommand)) {
+            showSyncLabelsHelp();
+            process.exit(0);
+        }
+        const subflags = flags.slice(1);
+        if (subcommand === 'init') {
+            if (subflags.some((f) => f === '--help' || f === '-h')) {
+                showSyncLabelsInitHelp();
+                process.exit(0);
+            }
+            const { invocationDir } = enterRepoRoot();
+            const syncLabelsInitFlagSchema = {
+                ...configFlagSchema,
+                isDryRun: { long: '--dry-run', type: 'boolean' },
+                shouldForce: { long: '--force', type: 'boolean' },
+            };
+            const { config, isDryRun, shouldForce } = parseArgsOrExit(subflags, syncLabelsInitFlagSchema).flags;
+            const configPath = resolveConfigFlag(config, invocationDir);
+            const exitCode = await syncLabelsInitCommand({
+                ...(configPath !== undefined && { configPath }),
+                isDryRun,
+                shouldForce,
+                styles,
+            });
+            process.exit(exitCode);
+        }
+        if (subcommand === 'generate') {
+            if (subflags.some((f) => f === '--help' || f === '-h')) {
+                showSyncLabelsGenerateHelp();
+                process.exit(0);
+            }
+            const { invocationDir } = enterRepoRoot();
+            const generateFlagSchema = {
+                ...configFlagSchema,
+                shouldCheck: { long: '--check', type: 'boolean' },
+            };
+            const { shouldCheck, config } = parseArgsOrExit(subflags, generateFlagSchema).flags;
+            const configPath = resolveConfigFlag(config, invocationDir);
+            const exitCode = await generateCommand({ shouldCheck, ...(configPath !== undefined && { configPath }), styles });
+            process.exit(exitCode);
+        }
+        if (subcommand === 'sync') {
+            if (subflags.some((f) => f === '--help' || f === '-h')) {
+                showSyncLabelsSyncHelp();
+                process.exit(0);
+            }
+            if (subflags.length > 0) {
+                reportError(`Unknown option: ${subflags[0]}`);
+                process.exit(1);
+            }
+            enterRepoRoot();
+            const exitCode = syncLabelsCommand();
+            process.exit(exitCode);
+        }
+        reportError(`Unknown subcommand: ${subcommand}`);
+        showSyncLabelsHelp();
+        process.exit(1);
+    }
+    if (command === 'overrides') {
+        const subcommand = flags[0];
+        if (subcommand === undefined || ['--help', '-h'].includes(subcommand)) {
+            showOverridesHelp();
+            process.exit(0);
+        }
+        const subflags = flags.slice(1);
+        if (subcommand === 'validate') {
+            if (subflags.some((f) => f === '--help' || f === '-h')) {
+                showOverridesValidateHelp();
+                process.exit(0);
+            }
+            const { invocationDir } = enterRepoRoot();
+            const { config } = parseArgsOrExit(subflags, configFlagSchema).flags;
+            const result = await validateOverridesCommand(styles, resolveConfigFlag(config, invocationDir));
+            if (result.exitCode === 0) {
+                console.info(result.message);
+            }
+            else {
+                process.stderr.write(`${result.message}\n`);
+            }
+            process.exit(result.exitCode);
+        }
+        reportError(`Unknown subcommand: ${subcommand}`);
+        showOverridesHelp();
+        process.exit(1);
+    }
+    reportError(`Unknown command: ${command}`);
+    showUsage();
+    process.exit(1);
+}

package/dist/esm/showTagPrefixesCommand.js

@@ -1,5 +1,4 @@
-import { formatStatusLine, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { formatStatusLine, isAnticipatedFailure, reportError, } from '@williamthorsen/nmr-core';
 import { detectRepoType } from "./init/detectRepoType.js";
 import { loadValidatedConfig, reportConfigProblem } from "./loadValidatedConfig.js";
 import { previewTagPrefixes } from "./previewTagPrefixes.js";
@@ -18,7 +17,10 @@ export async function showTagPrefixesCommand(styles, configPath) {
         preview = previewTagPrefixes(result.status === 'ok' ? result.config : undefined);
     }
     catch (error) {
-        reportError(describeError(error));
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
+        reportError(error.message);
         return 1;
     }
     process.stdout.write(renderMonorepo(preview, styles.stdout));

package/dist/esm/sync-labels/generateCommand.js

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { reportError } from '@williamthorsen/nmr-core';
+import { isAnticipatedFailure, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { stringify } from 'yaml';
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
@@ -54,6 +54,9 @@ export async function generateCommand({ shouldCheck = false, configPath, styles
         labels = resolveLabels(repoLabels);
     }
     catch (error) {
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
         const message = describeError(error);
         reportError(`Failed to resolve labels: ${message}`);
         return 1;

package/dist/esm/sync-labels/initCommand.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { reportWriteResult, writeFileWithCheck } from '@williamthorsen/nmr-core';
+import { isAnticipatedFailure, reportWriteResult, writeFileWithCheck, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { describeEmptyWorkspace, discoverWorkspaces } from "../discoverWorkspaces.js";
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
@@ -22,6 +22,9 @@ export async function syncLabelsInitCommand({ configPath, isDryRun, shouldForce,
         workspace = discoverWorkspaces();
     }
     catch (error) {
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
         const message = describeError(error);
         process.stderr.write(`  Failed to discover workspaces: ${message}\n`);
         return 1;
@@ -48,6 +51,9 @@ export async function syncLabelsInitCommand({ configPath, isDryRun, shouldForce,
         workflow = readSyncLabelsWorkflowTemplate();
     }
     catch (error) {
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
         process.stderr.write(`  ${describeError(error)}\n`);
         return 1;
     }

package/dist/esm/sync-labels/presets.js

@@ -2,10 +2,10 @@ import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { CANONICAL_TAXONOMY } from '@williamthorsen/change-grammar';
-import { findPackageRoot } from '@williamthorsen/nmr-core';
-import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { findPackageRoot, UserError } from '@williamthorsen/nmr-core';
 import { parse } from 'yaml';
 import { isRecord } from "../typeGuards.js";
+import { chainUserError } from "../user-error-chaining.js";
 import { deriveTypeLabels } from "./typeLabels.js";
 const TYPE_LABELS_PRESET = 'common';
 export function hashPreset(presetName) {
@@ -16,29 +16,29 @@ export function hashPreset(presetName) {
 export function loadPreset(presetName) {
     const presetPath = resolvePresetPath(presetName);
     if (!existsSync(presetPath)) {
-        throw new Error(`Unknown preset "${presetName}". The file ${presetPath} does not exist`);
+        throw new UserError(`Unknown preset "${presetName}". The file ${presetPath} does not exist`);
     }
     let content;
     try {
         content = readFileSync(presetPath, 'utf8');
     }
     catch (error) {
-        throw chainError(`Failed to read preset "${presetName}"`, error);
+        throw chainUserError(`Failed to read preset "${presetName}"`, error);
     }
     const parsedYaml = parse(content);
     if (!Array.isArray(parsedYaml)) {
-        throw new TypeError(`Preset "${presetName}" must be a YAML array of label definitions`);
+        throw new UserError(`Preset "${presetName}" must be a YAML array of label definitions`);
     }
     const labels = [];
     for (const entry of parsedYaml) {
         if (!isRecord(entry)) {
-            throw new Error(`Preset "${presetName}" contains an invalid label entry: ${JSON.stringify(entry)}`);
+            throw new UserError(`Preset "${presetName}" contains an invalid label entry: ${JSON.stringify(entry)}`);
         }
         const { color, description, name } = entry;
         if (typeof name !== 'string' ||
             typeof color !== 'string' ||
             (description !== undefined && typeof description !== 'string')) {
-            throw new TypeError(`Preset "${presetName}" contains a label with invalid fields: ${JSON.stringify(entry)}`);
+            throw new UserError(`Preset "${presetName}" contains a label with invalid fields: ${JSON.stringify(entry)}`);
         }
         labels.push({ name, color, ...(description !== undefined && { description }) });
     }

package/dist/esm/sync-labels/resolveLabels.js

@@ -1,10 +1,11 @@
+import { UserError } from '@williamthorsen/nmr-core';
 import { loadPreset } from "./presets.js";
 export function resolveLabels(config) {
     const labelEntries = Object.entries(config.labels ?? {});
     const caseVariantGroups = findCaseVariantGroups(labelEntries.map(([name]) => name));
     if (caseVariantGroups.length > 0) {
         const groupList = caseVariantGroups.map((group) => group.map((name) => `'${name}'`).join(' and ')).join('; ');
-        throw new Error(`Keys in 'labels' differ only in case, which GitHub treats as the same label: ${groupList}. Keep one entry per label.`);
+        throw new UserError(`Keys in 'labels' differ only in case, which GitHub treats as the same label: ${groupList}. Keep one entry per label.`);
     }
     const resolvedLabels = new Map();
     const presetNames = config.extends ?? [];
@@ -17,7 +18,7 @@ export function resolveLabels(config) {
         const key = getLabelKey(name);
         if (spec === null) {
             if (!resolvedLabels.has(key)) {
-                throw new Error(`Label '${name}' is set to null (remove), but the presets in 'extends' don't define it. Fix the name or delete the entry.`);
+                throw new UserError(`Label '${name}' is set to null (remove), but the presets in 'extends' don't define it. Fix the name or delete the entry.`);
             }
             resolvedLabels.delete(key);
         }
@@ -34,7 +35,7 @@ export function resolveLabels(config) {
     const labels = sortLabels(resolvedLabels.values().toArray());
     const aliasCollisions = findAliasCollisions(labels);
     if (aliasCollisions.length > 0) {
-        throw new Error(`Aliases must name labels that are not declared and must not repeat, or the sync merges one label into another and deletes it: ${aliasCollisions.join('; ')}.`);
+        throw new UserError(`Aliases must name labels that are not declared and must not repeat, or the sync merges one label into another and deletes it: ${aliasCollisions.join('; ')}.`);
     }
     return labels;
 }

package/dist/esm/sync-labels/templates.js

@@ -1,14 +1,14 @@
 import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { findPackageRoot } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { chainUserError } from "../user-error-chaining.js";
 export function readSyncLabelsWorkflowTemplate() {
     const templatePath = resolve(findPackageRoot(import.meta.url), 'templates', 'sync-labels.yaml.template');
     try {
         return readFileSync(templatePath, 'utf8');
     }
     catch (error) {
-        throw new Error(`Failed to read bundled template at ${templatePath}: ${describeError(error)}`, { cause: error });
+        throw chainUserError(`Failed to read bundled template at ${templatePath}`, error);
     }
 }
 export function buildScopeLabels(workspacePaths, retiredNames = []) {

package/dist/esm/tagCommand.js

@@ -1,5 +1,4 @@
-import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { parseArgsOrExit } from '@williamthorsen/nmr-core';
 import { createTags } from "./createTags.js";
 const tagFlagSchema = {
     isDryRun: { long: '--dry-run', type: 'boolean' },
@@ -7,11 +6,5 @@ const tagFlagSchema = {
 };
 export function tagCommand(argv, styles) {
     const { isDryRun, shouldSkipGitChecks } = parseArgsOrExit(argv, tagFlagSchema).flags;
-    try {
-        createTags({ isDryRun, shouldSkipGitChecks, style: styles.stdout });
-    }
-    catch (error) {
-        reportError(describeError(error));
-        process.exit(1);
-    }
+    createTags({ isDryRun, shouldSkipGitChecks, style: styles.stdout });
 }

package/dist/esm/user-error-chaining.d.ts

@@ -0,0 +1,13 @@
+import { UserError } from '@williamthorsen/nmr-core';
+/**
+ * Returns `error` as a `UserError` with the same message, for a failure that the tool anticipates, such as a failed
+ * external command.
+ */
+export declare function asUserError(error: unknown): UserError;
+/** Wraps an anticipated failure as a `UserError` that reads `<message>: <cause's message>`. */
+export declare function chainUserError(message: string, cause: unknown): UserError;
+/**
+ * Prefixes an anticipated failure (see `isAnticipatedFailure`) with `<message>: ` as a `UserError`, and returns any
+ * other value unchanged, so that a crash keeps its own stack when rethrown.
+ */
+export declare function prefixUserError(message: string, error: unknown): unknown;

package/dist/esm/user-error-chaining.js

@@ -0,0 +1,11 @@
+import { isAnticipatedFailure, UserError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+export function asUserError(error) {
+    return error instanceof UserError ? error : new UserError(describeError(error), { cause: error });
+}
+export function chainUserError(message, cause) {
+    return new UserError(`${message}: ${describeError(cause)}`, { cause });
+}
+export function prefixUserError(message, error) {
+    return isAnticipatedFailure(error) ? chainUserError(message, error) : error;
+}

package/dist/esm/validateOverridesCommand.js

@@ -1,4 +1,4 @@
-import { formatErrorLine, formatStatusLine } from '@williamthorsen/nmr-core';
+import { formatErrorLine, formatStatusLine, isAnticipatedFailure, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath } from "./changelogOverrides.js";
@@ -23,6 +23,9 @@ export async function validateOverridesCommand(styles, configPath, dependencies
         workspace = discover();
     }
     catch (error) {
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
         return { exitCode: 2, message: formatErrorLine(`Failed to discover workspaces: ${describeError(error)}`) };
     }
     if (workspace.kind === 'empty') {
@@ -36,6 +39,9 @@ export async function validateOverridesCommand(styles, configPath, dependencies
         inputs = buildValidationInputs(resolveReleaseTargets(userConfig, workspace), buildEntries);
     }
     catch (error) {
+        if (!isAnticipatedFailure(error)) {
+            throw error;
+        }
         return { exitCode: 2, message: formatErrorLine(`Failed to resolve overrides scope: ${describeError(error)}`) };
     }
     const result = validate(inputs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "16.1.0",
+  "version": "16.1.2",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -21,7 +21,7 @@
   "license": "ISC",
   "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
   "sideEffects": [
-    "./dist/esm/bin/*.js"
+    "./dist/esm/cli.js"
   ],
   "type": "module",
   "exports": {
@@ -52,10 +52,10 @@
   ],
   "dependencies": {
     "@williamthorsen/change-grammar": "0.3.0",
-    "@williamthorsen/nmr-core": "0.14.0",
+    "@williamthorsen/nmr-core": "0.15.1",
     "@williamthorsen/toolbelt.errors": "0.9.0",
     "json-stringify-pretty-compact": "4.0.0",
-    "semver": "7.8.5",
+    "semver": "7.8.6",
     "yaml": "2.9.1",
     "zod": "4.6.7"
   },
@@ -66,9 +66,9 @@
     "@williamthorsen/toolbelt.vitest": "0.13.1",
     "actionlint": "2.0.6",
     "esbuild": "0.28.2",
-    "readyup": "0.44.0",
+    "readyup": "0.45.0",
     "smol-toml": "1.9.1",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0"
   },
   "engines": {
     "node": ">=24.16.0"