@williamthorsen/release-kit 16.1.1 → 17.0.0

package/dist/esm/pushRelease.js

@@ -1,14 +1,21 @@
 import { execFileSync } from 'node:child_process';
 import { GIT_OUTPUT_LIMIT_BYTES } from '@williamthorsen/nmr-core';
+import { asUserError } from "./user-error-chaining.js";
 export function pushRelease(resolvedTags, options = {}) {
     const { isDryRun = false, tagsOnly = false } = options;
     const steps = [];
     if (!tagsOnly) {
-        const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-            encoding: 'utf8',
-            maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
+        let branch;
+        try {
+            branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+                encoding: 'utf8',
+                maxBuffer: GIT_OUTPUT_LIMIT_BYTES,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+        }
+        catch (error) {
+            throw asUserError(error);
+        }
         const command = ['git', 'push', 'origin', branch];
         steps.push({ type: 'branch', ref: branch, command });
     }
@@ -18,7 +25,12 @@ export function pushRelease(resolvedTags, options = {}) {
     }
     if (!isDryRun) {
         for (const step of steps) {
-            execFileSync(step.command[0], step.command.slice(1), { stdio: 'inherit' });
+            try {
+                execFileSync(step.command[0], step.command.slice(1), { stdio: 'inherit' });
+            }
+            catch (error) {
+                throw asUserError(error);
+            }
         }
     }
     return steps;

package/dist/esm/releaseFiles.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { hasErrnoCode } from '@williamthorsen/nmr-core';
+import { hasErrnoCode, UserError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 export const RELEASE_TAGS_FILE = 'tmp/.release-tags';
 export const RELEASE_SUMMARY_FILE = 'tmp/.release-summary';
@@ -13,7 +13,7 @@ export function readReleaseTags() {
         content = readFileSync(RELEASE_TAGS_FILE, 'utf8');
     }
     catch (error) {
-        throw new Error(describeTagsReadFailure(error), { cause: error });
+        throw new UserError(describeTagsReadFailure(error), { cause: error });
     }
     return content
         .split('\n')

package/dist/esm/releasePlan.js

@@ -1,4 +1,4 @@
-import { writeFileWithCheck } from '@williamthorsen/nmr-core';
+import { UserError, writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deleteFileIfExists } from "./deleteFileIfExists.js";
 import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
@@ -10,7 +10,7 @@ export function applyReleasePlan(plan) {
         const outcome = applyStep(step);
         if (outcome.outcome === 'failed') {
             const unwrittenPaths = orderedSteps.slice(index).map((pending) => pending.path);
-            throw new Error(describeApplyFailure({ failedStep: step, error: outcome.error, appliedWrites, unwrittenPaths }));
+            throw new UserError(describeApplyFailure({ failedStep: step, error: outcome.error, appliedWrites, unwrittenPaths }));
         }
         appliedWrites.push({ path: step.path, created: outcome.outcome === 'created' });
     }

package/dist/esm/resolveCommandTags.d.ts

@@ -2,10 +2,10 @@ import type { ReleaseKitConfig } from './configSchema.js';
 import { type ResolvedTag } from './resolveReleaseTags.js';
 /**
  * Discovers workspaces, resolves release tags from HEAD, validates `--tags` names against the full resolved tag
- * names (e.g., `nmr-core-v1.3.0`), and returns the filtered tag list. Exits with an error message on any validation
- * failure, including a workspace whose `package.json` does not have a `name` field, a config that
- * `mergeMonorepoConfig` rejects, and a workspace that does not resolve to any package, which is not single-package
- * mode.
+ * names (e.g., `nmr-core-v1.3.0`), and returns the filtered tag list. Throws a `UserError` when workspace discovery
+ * fails, when a workspace's `package.json` does not have a `name` field, when `mergeMonorepoConfig` rejects the
+ * config, when the workspace does not resolve to any package (which is not single-package mode), and when HEAD does
+ * not have any release tags; throws a `UsageError` for a `--tags` name that HEAD lacks.
  *
  * In monorepo mode the workspace list is `userConfig` merged over the discovered workspaces, as `prepare` builds it,
  * and each directory target and a declared composite (a `project` block or a `releases` composite) contribute their

package/dist/esm/resolveCommandTags.js

@@ -1,23 +1,22 @@
-import { reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { UserError } from '@williamthorsen/nmr-core';
+import { UsageError } from '@williamthorsen/nmr-core/cli';
 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)}`);
-        process.exit(1);
+        throw new UserError(`No workspace package to tag. ${describeEmptyWorkspace(workspace)}`);
     }
     let workspaces;
     let directories = [];
@@ -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) {
@@ -52,8 +50,7 @@ export function resolveCommandTags(tags, userConfig) {
         throw new Error('resolveCommandTags: invariant violated; neither workspaces nor singleWorkspace was derived');
     }
     if (resolvedTags.length === 0) {
-        reportError('HEAD does not have any release tags. Create tags with `release-kit tag` first.');
-        process.exit(1);
+        throw new UserError('HEAD does not have any release tags. Create tags with `release-kit tag` first.');
     }
     if (tags !== undefined) {
         const availableTagNames = resolvedTags.map((t) => t.tag);
@@ -61,8 +58,7 @@ export function resolveCommandTags(tags, userConfig) {
             if (availableTagNames.includes(name)) {
                 continue;
             }
-            reportError(`Unknown tag "${name}" in --tags. Available: ${availableTagNames.join(', ')}`);
-            process.exit(1);
+            throw new UsageError(`Unknown tag "${name}" in --tags. Available: ${availableTagNames.join(', ')}`);
         }
         resolvedTags = resolvedTags.filter((t) => tags.includes(t.tag));
     }

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/{resolveStylesOrExit.d.ts → resolveStyles.d.ts}

@@ -6,5 +6,5 @@ export interface ResolveStylesOptions {
     readonly stderrIsTty: boolean;
     readonly stdoutIsTty: boolean;
 }
-/** Resolves the style of each output stream, exiting with a usage error when the variable does not name a setting. */
-export declare function resolveStylesOrExit(options: ResolveStylesOptions): StreamStyles;
+/** Resolves the style of each output stream, throwing a `UsageError` when the variable doesn't name a setting. */
+export declare function resolveStyles(options: ResolveStylesOptions): StreamStyles;

package/dist/esm/resolveStyles.js

@@ -0,0 +1,10 @@
+import { describeInvalidOutputStyle, resolveStreamStyles } from '@williamthorsen/nmr-core';
+import { UsageError } from '@williamthorsen/nmr-core/cli';
+export const OUTPUT_STYLE_ENV_VAR = 'RELEASE_KIT_OUTPUT_STYLE';
+export function resolveStyles(options) {
+    const { invalid, styles } = resolveStreamStyles({ ...options, envVar: OUTPUT_STYLE_ENV_VAR });
+    if (invalid !== undefined) {
+        throw new UsageError(describeInvalidOutputStyle(invalid));
+    }
+    return styles;
+}

package/dist/esm/route.d.ts

@@ -0,0 +1,2 @@
+/** Runs the `release-kit` command tree against the arguments and resolves to the exit code. */
+export declare function routeCommand(args: string[]): Promise<number>;

package/dist/esm/route.js

@@ -0,0 +1,39 @@
+import process from 'node:process';
+import { resolveSelfVersion } from '@williamthorsen/nmr-core';
+import { createCli, runCli } from '@williamthorsen/nmr-core/cli';
+import { BIN } from "./bin.js";
+import { init, overrides, showTagPrefixes, syncLabels, updateTemplates } from "./cli/maintenanceCommands.js";
+import { commit, createGithubRelease, prepare, publish, push, tag } from "./cli/releaseCommands.js";
+import { OUTPUT_STYLE_ENV_VAR, resolveStyles } from "./resolveStyles.js";
+const VERSION = resolveSelfVersion(import.meta.url);
+export async function routeCommand(args) {
+    return runCli(args, ROOT, {
+        name: BIN,
+        context: { env: process.env, stderrIsTty: process.stderr.isTTY, stdoutIsTty: process.stdout.isTTY },
+        stdout: process.stdout,
+        stderr: process.stderr,
+        version: () => VERSION,
+    });
+}
+const { defineGroup } = createCli();
+const ROOT = defineGroup({
+    summary: 'Version-bumping and changelog-generation toolkit for release workflows',
+    deriveContext: (_flags, context) => ({ styles: resolveStyles(context) }),
+    commands: {
+        prepare,
+        commit,
+        tag,
+        push,
+        publish,
+        'create-github-release': createGithubRelease,
+        'show-tag-prefixes': showTagPrefixes,
+        init,
+        'update-templates': updateTemplates,
+        overrides,
+        'sync-labels': syncLabels,
+    },
+    epilog: `Environment:
+  ${OUTPUT_STYLE_ENV_VAR}
+      Output style: auto (default), plain, or rich. auto prints plain, without emoji,
+      when CI is set or the stream is not a terminal.`,
+});

package/dist/esm/showTagPrefixesCommand.js

@@ -1,5 +1,5 @@
-import { formatStatusLine, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { formatStatusLine, isAnticipatedFailure, reportError, } from '@williamthorsen/nmr-core';
+import { BIN } from "./bin.js";
 import { detectRepoType } from "./init/detectRepoType.js";
 import { loadValidatedConfig, reportConfigProblem } from "./loadValidatedConfig.js";
 import { previewTagPrefixes } from "./previewTagPrefixes.js";
@@ -18,7 +18,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(BIN, error.message);
         return 1;
     }
     process.stdout.write(renderMonorepo(preview, styles.stdout));

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

@@ -1,8 +1,9 @@
 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 { BIN } from "../bin.js";
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
 import { loadValidatedConfig, reportConfigProblem } from "../loadValidatedConfig.js";
 import { hashPreset } from "./presets.js";
@@ -28,7 +29,7 @@ export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_F
 export async function loadRepoLabelsConfig(stderrStyle, configPath) {
     const result = await loadValidatedConfig(configPath);
     if (result.status === 'missing') {
-        reportError(`Config file not found at ${result.configFilePath}. Run \`release-kit sync-labels init\` first.`);
+        reportError(BIN, `Config file not found at ${result.configFilePath}. Run \`release-kit sync-labels init\` first.`);
         return undefined;
     }
     if (result.status === 'invalid') {
@@ -36,7 +37,7 @@ export async function loadRepoLabelsConfig(stderrStyle, configPath) {
         return undefined;
     }
     if (result.config.repoLabels === undefined) {
-        reportError(`The \`repoLabels\` block is missing from ${result.configFilePath}. Run \`release-kit sync-labels init\` to seed one.`);
+        reportError(BIN, `The \`repoLabels\` block is missing from ${result.configFilePath}. Run \`release-kit sync-labels init\` to seed one.`);
         return undefined;
     }
     return result.config.repoLabels;
@@ -54,8 +55,11 @@ 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}`);
+        reportError(BIN, `Failed to resolve labels: ${message}`);
         return 1;
     }
     const presetHashes = new Map();
@@ -73,7 +77,7 @@ export async function generateCommand({ shouldCheck = false, configPath, styles
     }
     catch (error) {
         const message = describeError(error);
-        reportError(`Failed to write ${LABELS_OUTPUT_PATH}: ${message}`);
+        reportError(BIN, `Failed to write ${LABELS_OUTPUT_PATH}: ${message}`);
         return 1;
     }
     console.info(`Generated ${LABELS_OUTPUT_PATH} with ${String(labels.length)} labels.`);
@@ -85,11 +89,11 @@ function compareAgainstCommittedFile(expectedContent) {
         existingContent = readFileSync(LABELS_OUTPUT_PATH, 'utf8');
     }
     catch {
-        reportError(`${LABELS_OUTPUT_PATH} is missing. Run \`release-kit sync-labels generate\` and commit the result.`);
+        reportError(BIN, `${LABELS_OUTPUT_PATH} is missing. Run \`release-kit sync-labels generate\` and commit the result.`);
         return 1;
     }
     if (existingContent !== expectedContent) {
-        reportError(`${LABELS_OUTPUT_PATH} is stale. Run \`release-kit sync-labels generate\` and commit the result.`);
+        reportError(BIN, `${LABELS_OUTPUT_PATH} is stale. Run \`release-kit sync-labels generate\` and commit the result.`);
         return 1;
     }
     console.info(`${LABELS_OUTPUT_PATH} is up to date.`);

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,9 @@ 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, isRecord, 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 +15,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/retiredConfig.js

@@ -1,11 +1,12 @@
 import { existsSync } from 'node:fs';
 import { reportError } from '@williamthorsen/nmr-core';
+import { BIN } from "../bin.js";
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
 export const RETIRED_SYNC_LABELS_CONFIG_PATH = '.config/sync-labels.config.ts';
 export function checkRetiredSyncLabelsConfig(configPath = CONFIG_FILE_PATH) {
     if (!existsSync(RETIRED_SYNC_LABELS_CONFIG_PATH)) {
         return false;
     }
-    reportError(`${RETIRED_SYNC_LABELS_CONFIG_PATH} is no longer read. Move its labels into the \`repoLabels\` block of ${configPath} (presets move to \`repoLabels.extends\`; each label becomes a \`'name': { color, description }\` entry under \`repoLabels.labels\`), then delete the file.`);
+    reportError(BIN, `${RETIRED_SYNC_LABELS_CONFIG_PATH} is no longer read. Move its labels into the \`repoLabels\` block of ${configPath} (presets move to \`repoLabels.extends\`; each label becomes a \`'name': { color, description }\` entry under \`repoLabels.labels\`), then delete the file.`);
     return true;
 }

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

@@ -2,6 +2,7 @@ import { execSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { GIT_OUTPUT_LIMIT_BYTES, reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
+import { BIN } from "../bin.js";
 import { checkRetiredSyncLabelsConfig } from "./retiredConfig.js";
 const WORKFLOW_FILE = '.github/workflows/sync-labels.yaml';
 function checkGhAvailable() {
@@ -18,11 +19,11 @@ export function syncLabelsCommand() {
         return 1;
     }
     if (!checkGhAvailable()) {
-        reportError('The `gh` CLI is not installed or not in PATH. Install it from https://cli.github.com/');
+        reportError(BIN, 'The `gh` CLI is not installed or not in PATH. Install it from https://cli.github.com/');
         return 1;
     }
     if (!existsSync(WORKFLOW_FILE)) {
-        reportError(`${WORKFLOW_FILE} not found. Run \`release-kit sync-labels init\` first.`);
+        reportError(BIN, `${WORKFLOW_FILE} not found. Run \`release-kit sync-labels init\` first.`);
         return 1;
     }
     try {
@@ -30,7 +31,7 @@ export function syncLabelsCommand() {
     }
     catch (error) {
         const message = describeError(error);
-        reportError(`Failed to trigger workflow: ${message}`);
+        reportError(BIN, `Failed to trigger workflow: ${message}`);
         return 1;
     }
     console.info('Workflow triggered successfully. View runs at: gh run list --workflow=sync-labels.yaml');

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.d.ts

@@ -1,3 +1,8 @@
-import { type StreamStyles } from '@williamthorsen/nmr-core';
-/** Runs the CLI `tag` command: parses flags and delegates to `createTags`. */
-export declare function tagCommand(argv: string[], styles: StreamStyles): void;
+import type { StreamStyles } from '@williamthorsen/nmr-core';
+export interface TagCommandOptions {
+    isDryRun: boolean;
+    shouldSkipGitChecks: boolean;
+    styles: StreamStyles;
+}
+/** Runs the CLI `tag` command by delegating to `createTags`. */
+export declare function tagCommand({ isDryRun, shouldSkipGitChecks, styles }: TagCommandOptions): void;

package/dist/esm/tagCommand.js

@@ -1,17 +1,4 @@
-import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createTags } from "./createTags.js";
-const tagFlagSchema = {
-    isDryRun: { long: '--dry-run', type: 'boolean' },
-    shouldSkipGitChecks: { long: '--no-git-checks', type: 'boolean' },
-};
-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);
-    }
+export function tagCommand({ isDryRun, shouldSkipGitChecks, styles }) {
+    createTags({ isDryRun, shouldSkipGitChecks, style: styles.stdout });
 }

package/dist/esm/typeGuards.d.ts

@@ -1,4 +1,2 @@
-/** Checks whether a value is a plain object (non-null, non-array). */
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /** Narrows an `unknown` value to `unknown[]` via `Array.isArray`, avoiding `any[]`. */
 export declare function isUnknownArray(value: unknown): value is unknown[];

package/dist/esm/typeGuards.js

@@ -1,6 +1,3 @@
-export function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 export function isUnknownArray(value) {
     return Array.isArray(value);
 }