@williamthorsen/release-kit 10.4.4 → 10.6.0

package/dist/esm/releaseFiles.d.ts

@@ -1,4 +1,26 @@
+/**
+ * File written by the release preparation step, containing one tag per line.
+ *
+ * Relative to the project root so it works identically in CI and local runs. The reusable
+ * release workflow reads it at this path, so the path and the line-delimited format are a
+ * published contract rather than an internal detail.
+ */
 export declare const RELEASE_TAGS_FILE = "tmp/.release-tags";
+/**
+ * File written by the release preparation step, containing the commit body summary.
+ * Relative to the project root so it works identically in CI and local runs.
+ */
 export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
+/** Resolves the tags file against the current working directory, for use in diagnostics. */
 export declare function resolveReleaseTagsPath(): string;
+/**
+ * Reads the tag names written by `prepare`, one per line, discarding blank lines.
+ *
+ * Both consumers — `commit` and `tag` — share this reader so their diagnostics cannot drift.
+ * Failure messages name the path as resolved against `process.cwd()`, which is what separates
+ * a genuinely absent file from one the command looked for under a different worktree, and
+ * they preserve the underlying errno instead of reporting every failure as a missing file.
+ *
+ * An empty or blank file yields an empty array; callers decide whether that is an error.
+ */
 export declare function readReleaseTags(): string[];

package/dist/esm/releasePlan.d.ts

@@ -1,10 +1,33 @@
 import type { PrepareResult } from './types.js';
+/** One file a release will write, carried as its complete intended content. */
 export interface PlannedWrite {
     path: string;
     content: string;
 }
+/**
+ * A release computed in full but not yet written.
+ *
+ * Holding every intended file up front is what lets `prepare` fail during computation without
+ * leaving anything on disk. {@link applyReleasePlan} is the only step that mutates the tree, so
+ * a dry run is this same plan with the apply step skipped rather than a separate code path.
+ *
+ * Extends the reporting view with the two fields only the apply step needs, so `reportPrepare`
+ * can render a plan without knowing about file content.
+ */
 export interface ReleasePlan extends PrepareResult {
     writes: readonly PlannedWrite[];
+    /** Body of the release commit message, written alongside the tags file. */
     summary: string;
 }
+/**
+ * Writes every file a plan describes: content files first, then the summary, then the tags file.
+ *
+ * The tags file goes last so its presence means the whole plan landed. Both `release-kit commit`
+ * and the reusable release workflow read it as the signal that a release is ready to commit, so
+ * writing it earlier would let a failure produce a tree that claims to be releasable.
+ *
+ * Returns the paths written, in order.
+ *
+ * @throws If any write fails, naming what reached disk and what did not.
+ */
 export declare function applyReleasePlan(plan: ReleasePlan): string[];

package/dist/esm/releasePrepare.d.ts

@@ -1,10 +1,50 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleaseConfig, ReleaseType } from './types.js';
+/**
+ * Options for the release preparation workflow.
+ *
+ * Carries no dry-run flag: preparation only ever computes a plan, and whether that plan is
+ * applied is the caller's decision.
+ */
 export interface ReleasePrepareOptions {
+    /**
+     * Release even when no commits or no bump-worthy commits exist since the last tag
+     * (monorepo only). Orthogonal to `bumpOverride`: when `bumpOverride` is not given,
+     * the release falls back to `patch`.
+     */
     force?: boolean;
+    /** Override the bump type instead of determining it from commits. */
     bumpOverride?: ReleaseType;
+    /**
+     * Explicit target version (canonical `N.N.N`) that bypasses commit-derived bump logic.
+     * Mutually exclusive with `bumpOverride`. In monorepo mode the caller must narrow
+     * `config.workspaces` to a single workspace before invoking.
+     */
     setVersion?: string;
+    /**
+     * Workspace directories the run was narrowed to by `--only` (monorepo only), with
+     * `config.workspaces` already filtered to match. Present only for a narrowed run, which
+     * skips the project release: the project tier rolls up every contributing workspace, and
+     * the narrowing has changed which workspaces those are.
+     */
     only?: string[];
+    /**
+     * If true, write per-workspace release-notes previews under `{workspacePath}/docs/`
+     * (`README.v{version}.md` and `RELEASE_NOTES.v{version}.md`) after each workspace's
+     * `changelog.json` is produced. Requires `config.changelogJson.enabled`; when disabled,
+     * a warning is recorded on the plan and no previews are generated.
+     */
     withReleaseNotes?: boolean;
 }
+/**
+ * Orchestrate the release preparation workflow for a single package.
+ *
+ * 1. Gets commits since the last tag.
+ * 2. Determines the bump type from commits (or uses the override).
+ * 3. Bumps all configured package.json version fields.
+ * 4. Generates changelogs via git-cliff.
+ * 5. Runs the optional format command.
+ *
+ * Returns a structured `PrepareResult` with all data needed for presentation.
+ */
 export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepare.js

@@ -16,7 +16,6 @@ import { planVersionBump, planVersionSet } from "./planVersionBump.js";
 import { readCurrentVersion } from "./readCurrentVersion.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
-import { refreshGitCliffCache } from "./runGitCliff.js";
 export function releasePrepare(config, options) {
     const { bumpOverride, setVersion, withReleaseNotes } = options;
     const writes = [];
@@ -46,7 +45,6 @@ export function releasePrepare(config, options) {
         if (!isForwardVersion(currentVersion, setVersion)) {
             throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
         }
-        refreshGitCliffCache();
         bump = planVersionSet(config.packageFiles, setVersion);
     }
     else {
@@ -78,7 +76,6 @@ export function releasePrepare(config, options) {
                 formatCommand: undefined,
             };
         }
-        refreshGitCliffCache();
         bump = planVersionBump(config.packageFiles, releaseType);
     }
     writes.push(...bump.writes);

package/dist/esm/releasePrepareMono.d.ts

@@ -1,4 +1,12 @@
 import type { ReleasePlan } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
 import type { MonorepoReleaseConfig } from './types.js';
+/**
+ * Orchestrate release preparation for a monorepo with multiple workspaces.
+ *
+ * Phase 1: Determine direct bumps from commits for each workspace.
+ * Phase 2: Build the dependency graph and propagate bumps to dependents.
+ * Phase 2b: Topologically sort the full release set.
+ * Phase 3: Execute bumps and generate changelogs in dependency order.
+ */
 export declare function releasePrepareMono(config: MonorepoReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepareMono.js

@@ -23,7 +23,6 @@ import { readCurrentVersion } from "./readCurrentVersion.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
-import { refreshGitCliffCache } from "./runGitCliff.js";
 export function releasePrepareMono(config, options) {
     const { only, withReleaseNotes } = options;
     const writes = [];
@@ -53,9 +52,6 @@ export function releasePrepareMono(config, options) {
         enabled: withReleaseNotes === true && config.changelogJson.enabled,
         sectionOrder,
     };
-    if (fullReleaseSet.size > 0) {
-        refreshGitCliffCache();
-    }
     const { tags, modifiedFiles } = executeReleaseSet({
         sortedDirs,
         fullReleaseSet,

package/dist/esm/releasePrepareProject.d.ts

@@ -1,15 +1,57 @@
 import type { PlannedWrite } from './releasePlan.js';
 import type { ReleasePrepareOptions } from './releasePrepare.js';
 import type { ChangelogOverride, MonorepoReleaseConfig, ProjectPrepareResult } from './types.js';
+/** Inputs to the project-release stage. */
 export interface ReleasePrepareProjectArgs {
+    /** Resolved monorepo config; `config.project` must be defined when this function is called. */
     config: MonorepoReleaseConfig;
     options: ReleasePrepareOptions;
+    /** Mutated in-place to append project-level files (root package.json, root CHANGELOG.md, root changelog.json). */
     modifiedFiles: string[];
+    /** Mutated in-place to append every file this stage intends to write. */
     writes: PlannedWrite[];
+    /** Mutated in-place to append the project tag. */
     tags: string[];
+    /**
+     * Mutated in-place to surface warnings this stage raises that are not override-specific
+     * (currently the release-notes previews' skip reasons). Defaults to a discardable sink.
+     */
     warnings?: string[];
+    /**
+     * Root-tier editorial overrides loaded once at the top of the prepare run. Defaults to an
+     * empty map when omitted (no overrides applied). The project changelog applies only the
+     * root-tier file — per-workspace files describe per-workspace editorial intent and have no
+     * meaning at the aggregated project tier.
+     */
     rootOverrides?: Map<string, ChangelogOverride>;
+    /**
+     * Mutated in-place to surface override warnings (currently empty by design — stale-key
+     * warnings are emitted by the orchestrator after aggregating across batches). Defaults to
+     * a discardable sink when omitted.
+     */
     overrideWarnings?: string[];
+    /**
+     * Mutated in-place: every root-tier override key matched in this stage is added so the
+     * orchestrator can dedupe stale-key warnings across the run. Defaults to a discardable
+     * sink when omitted.
+     */
     globalMatchedRootKeys?: Set<string>;
 }
+/**
+ * Run the project-level release stage.
+ *
+ * Mirrors the per-workspace pipeline shape — find baseline tag → derive bump → bump version →
+ * regenerate CHANGELOG → optionally emit changelog.json and release-notes previews — but
+ * targets the root `package.json` and the root `CHANGELOG.md`. Contributing paths come from
+ * the resolved `project.paths`, which defaults to the union of every (already-filtered)
+ * workspace's `paths`.
+ *
+ * Returns a structured `{ status: 'skipped', skipReason, ... }` result when neither
+ * commits nor `--force` provide a release signal. The caller should attach the returned
+ * result to `PrepareResult.project`. `undefined` is returned only when there is no
+ * configured `project` block — handled at the call site, not here.
+ *
+ * Caller contract: `prepareCommand` rejects `--only` upstream when a project block is
+ * configured, so this orchestrator never has to reason about workspace-narrowing flags.
+ */
 export declare function releasePrepareProject(args: ReleasePrepareProjectArgs): ProjectPrepareResult;

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -1,5 +1,22 @@
 import type { ChangelogEntry } from './types.js';
+/** Options for `renderChangelogMarkdown`. */
 export interface RenderChangelogMarkdownOptions {
+    /** Section titles in canonical order; passed through to `renderReleaseNotesMulti`. */
     sectionOrder?: string[];
 }
+/**
+ * Render `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
+ *
+ * Format:
+ *   `# Changelog`
+ *   blank line
+ *   `All notable changes …`
+ *   blank line
+ *   per-entry sections (delegated to `renderReleaseNotesMulti`)
+ *   blank line
+ *   footer comment
+ *
+ * Entries are rendered in the order provided; the caller sorts (typically newest-first via
+ * `changelogJsonFile`'s SemVer-aware comparator).
+ */
 export declare function renderChangelogMarkdown(entries: ChangelogEntry[], options?: RenderChangelogMarkdownOptions): string;

package/dist/esm/renderReleaseNotes.d.ts

@@ -1,9 +1,34 @@
 import type { ChangelogAudience, ChangelogEntry, ChangelogSection } from './types.js';
+/** Options for rendering a single changelog entry to markdown. */
 export interface RenderOptions {
+    /** Predicate to filter sections. When absent, all sections are included. */
     filter?: (section: ChangelogSection) => boolean;
+    /** Whether to include the version/date heading. Defaults to `true`. */
     includeHeading?: boolean;
+    /**
+     * Section titles in desired priority order. Known titles are emitted first in this order;
+     * titles not listed preserve their relative position after known ones. When absent, section
+     * order is preserved from the entry.
+     */
     sectionOrder?: string[];
 }
+/**
+ * Create a predicate that matches sections visible to the given audience.
+ *
+ * `"all"` matches only sections with `audience: "all"` (public-facing).
+ * `"dev"` matches all sections (developers see everything).
+ */
 export declare function matchesAudience(audience: ChangelogAudience): (section: ChangelogSection) => boolean;
+/**
+ * Render a single `ChangelogEntry` to markdown.
+ *
+ * Output format mirrors the existing CHANGELOG.md style: an H2 version heading followed by
+ * H3 section headings with bulleted items.
+ */
 export declare function renderReleaseNotesSingle(entry: ChangelogEntry, options?: RenderOptions): string;
+/**
+ * Render multiple `ChangelogEntry` values to a single markdown document.
+ *
+ * Entries are rendered in the order provided; the caller is responsible for sorting.
+ */
 export declare function renderReleaseNotesMulti(entries: ChangelogEntry[], options?: RenderOptions): string;

package/dist/esm/reportPrepare.d.ts

@@ -1,6 +1,20 @@
 import type { PrepareResult } from './types.js';
+/** How the plan was carried out, which decides the tense the report is rendered in. */
 export interface ReportPrepareOptions {
+    /** True when the plan was written to disk; false for a dry run. */
     applied: boolean;
+    /** The format command's failure message, when it ran and failed. */
     formatError?: string;
 }
+/**
+ * Format a release plan into styled terminal output.
+ *
+ * Pure function: accepts structured data, returns a string. Never writes to stdout.
+ * Single-workspace mode (no `name` field) renders flat output; multi-workspace mode
+ * renders section headers per workspace, an optional project section, and a tag summary
+ * at the end.
+ *
+ * Whether the plan was applied is a property of the render, not of the plan: the same plan
+ * produces the dry-run report and the applied report.
+ */
 export declare function reportPrepare(plan: PrepareResult, options: ReportPrepareOptions): string;

package/dist/esm/reportPrepare.js

@@ -1,4 +1,6 @@
 import { bold, dim, sectionHeader } from "./format.js";
+import { GIT_CLIFF_NPX_ARGS } from "./runGitCliff.js";
+const CLIFF_DRY_RUN_COMMAND = `npx ${GIT_CLIFF_NPX_ARGS.join(' ')} ...`;
 export function reportPrepare(plan, options) {
     const isMultiWorkspace = plan.workspaces.some((w) => w.name !== undefined) || plan.project !== undefined;
     if (isMultiWorkspace) {
@@ -103,7 +105,7 @@ function formatProjectSection(lines, project, dryRun) {
     lines.push(dim('  Generating changelogs...'));
     for (const file of project.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`    [dry-run] Would run: npx --yes git-cliff ... --output ${file}`));
+            lines.push(dim(`    [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
         }
         else {
             lines.push(dim(`    Generating changelog: ${file}`));
@@ -195,7 +197,7 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
 function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
     for (const file of workspace.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`${indent}  [dry-run] Would run: npx --yes git-cliff ... --output ${file}`));
+            lines.push(dim(`${indent}  [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
         }
         else {
             lines.push(dim(`${indent}  Generating changelog: ${file}`));

package/dist/esm/resolveCliffConfigPath.d.ts

@@ -1 +1,11 @@
+/**
+ * Resolve the git-cliff configuration file path.
+ *
+ * Checks candidates in order: explicit `cliffConfigPath` -> `.config/git-cliff.toml` ->
+ * `cliff.toml` -> bundled `cliff.toml.template`. Returns the first path that exists,
+ * or throws if even the bundled template cannot be found.
+ *
+ * When an explicit `cliffConfigPath` is provided, it is returned as-is without checking
+ * existence, preserving current behavior (git-cliff reports the error if the file is missing).
+ */
 export declare function resolveCliffConfigPath(cliffConfigPath: string | undefined, metaUrl: string): string;

package/dist/esm/resolveCommandTags.d.ts

@@ -1,2 +1,14 @@
-import type { ResolvedTag } from './resolveReleaseTags.js';
+import { type ResolvedTag } from './resolveReleaseTags.js';
+/**
+ * Discover workspaces, resolve release tags from HEAD, validate `--tags` names against the
+ * full resolved tag names (e.g., `nmr-core-v1.3.0`), and return the filtered tag list.
+ * Works in both single-package and monorepo modes. Exits with an error message on any validation
+ * failure — including `deriveWorkspaceConfig()` throws for workspaces missing a `package.json` `name` field.
+ *
+ * In both modes `deriveWorkspaceConfig` is called so `WorkspaceConfig.isPublishable` (read
+ * from `package.json#private`) propagates onto each `ResolvedTag`. Single-package mode now
+ * derives `./package.json`'s workspace config too — consumers that previously relied on
+ * single-package mode skipping the derive step need a `name` field on `./package.json`,
+ * but in practice every npm/pnpm package already has one.
+ */
 export declare function resolveCommandTags(tags: string[] | undefined): Promise<ResolvedTag[]>;

package/dist/esm/resolveReleaseNotesConfig.d.ts

@@ -2,12 +2,26 @@ import type { ReleaseNotesConfig } from './types.js';
 export interface ResolvedReleaseNotesConfig {
     releaseNotes: ReleaseNotesConfig;
     changelogJsonOutputPath: string;
+    /** Section titles in priority order, derived from the merged workTypes record. */
     sectionOrder: string[];
 }
 export interface ResolveReleaseNotesConfigOptions {
+    /**
+     * When `true`, a `loadConfig()` rejection causes `process.exit(1)` rather than a fallback to
+     * defaults. Use from CLI commands whose entire behavior depends on the resolved config (e.g.
+     * `create-github-release`), so a corrupt or unreadable config cannot silently send the command
+     * to the wrong changelog path.
+     */
     strictLoad?: boolean;
 }
+/**
+ * Load and validate the release-kit config.
+ *
+ * By default, falls back to defaults when `loadConfig()` rejects (legacy publish behavior).
+ * When `strictLoad` is `true`, a load failure prints an error and calls `process.exit(1)`.
+ */
 export declare function resolveReleaseNotesConfig(options?: ResolveReleaseNotesConfigOptions): Promise<ResolvedReleaseNotesConfig>;
+/** Extract section headers in declaration order from a merged workTypes record. */
 export declare function deriveSectionOrder(workTypes: Record<string, {
     header: string;
 }>): string[];

package/dist/esm/resolveReleaseTags.d.ts

@@ -3,12 +3,34 @@ export interface ResolvedTag {
     tag: string;
     dir: string;
     workspacePath: string;
+    /**
+     * Whether the workspace this tag belongs to can be published to a registry. Propagated
+     * from the matched `WorkspaceConfig.isPublishable` (monorepo) or from the single-package
+     * workspace config (single-package mode). Consumed by `release-kit publish` to filter the
+     * tag set; other commands ignore it.
+     */
     isPublishable: boolean;
 }
+/** Discriminated argument to `resolveReleaseTags`: exactly one of the two keys is meaningful. */
 type ResolveReleaseTagsArgs = {
     workspaces: readonly WorkspaceConfig[];
 } | {
     singleWorkspace: WorkspaceConfig;
 };
+/**
+ * Resolve release tags pointing at HEAD into publishable package descriptors.
+ *
+ * Pass `{ workspaces }` for monorepo mode: each tag is matched against the workspace
+ * whose `tagPrefix` it starts with, and that workspace's `isPublishable` propagates onto
+ * the `ResolvedTag`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
+ * same source that produced the tag), encoding and decoding stay colocated.
+ *
+ * Pass `{ singleWorkspace }` for single-package mode: tags like `v1.2.3` are matched and
+ * each carries the workspace's `isPublishable` bit derived from `./package.json#private`.
+ *
+ * The no-arg form is a test-isolation convenience for unit tests that exercise tag
+ * matching without needing `isPublishable` propagation; resolved tags default to
+ * `isPublishable: true`. Production callers should pass one of the named forms.
+ */
 export declare function resolveReleaseTags(args?: ResolveReleaseTagsArgs): ResolvedTag[];
 export {};

package/dist/esm/runGitCliff.d.ts

@@ -1,2 +1,38 @@
+/**
+ * The exact `git-cliff` version every invocation resolves.
+ *
+ * npm's `git-cliff` trails the upstream release, so this pin normally sits behind the newest version cliff
+ * itself reports. Bumping it is an edit to this line, once npm publishes the version you want.
+ */
+export declare const GIT_CLIFF_VERSION = "2.13.1";
+/** The npx arguments that precede the cliff args at every invocation, and that the dry-run report renders. */
+export declare const GIT_CLIFF_NPX_ARGS: readonly string[];
+/**
+ * Invokes `git-cliff` via `npx` and returns the output it produced.
+ *
+ * Single entry point for `git-cliff` invocations from `release-kit`. Owns three pieces of shared lifecycle
+ * that would otherwise duplicate (and silently drift) across call sites: the npx flags, the spawned-process
+ * environment, and the temp dir holding both the `.template`→`.toml` config copy and cliff's output file.
+ *
+ * Output is routed through `--output` to a temp file and read back. `--context` emits a workspace's
+ * entire matching tag history on every run, so its size grows without bound with the repo;
+ * a file accommodates that, while a pipe is bounded by `maxBuffer`.
+ *
+ * The npx spec names an exact version, which leaves npm no staleness to check, so `--prefer-offline` skips the
+ * per-call registry revalidation round-trip (~2.5 s per invocation on a warm cache) without stranding the run
+ * on whatever the cache happens to hold.
+ *
+ * Two env entries are set for the child. `npm_config_progress=false` suppresses npx's animated stderr spinner,
+ * which otherwise renders as a transient flicker. `RUST_LOG=warn` drops cliff's INFO lines, among them the
+ * crates.io update notice it emits on every invocation while npm trails upstream, and leaves warnings and errors
+ * in place; an inherited `RUST_LOG` wins, so raising the level for debugging still works.
+ *
+ * The helper injects `--config <path>` and `--output <path>` itself — callers must NOT include either in `cliffArgs`.
+ * `--output` is appended last so a caller that passes one anyway cannot redirect the output the helper then reads.
+ * The caller is responsible for resolving the cliff config path (via `resolveCliffConfigPath`) before calling,
+ * since the resolution depends on the caller's `import.meta.url`.
+ *
+ * Errors from `execFileSync` are not caught: callers wrap with site-specific messages.
+ * The temp-dir cleanup runs in a `finally` so it still happens on throw.
+ */
 export declare function runGitCliff(cliffConfigPath: string, cliffArgs: readonly string[]): string;
-export declare function refreshGitCliffCache(): void;

package/dist/esm/runGitCliff.js

@@ -2,7 +2,8 @@ import { execFileSync } from 'node:child_process';
 import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+export const GIT_CLIFF_VERSION = '2.13.1';
+export const GIT_CLIFF_NPX_ARGS = ['--prefer-offline', '--yes', `git-cliff@${GIT_CLIFF_VERSION}`];
 export function runGitCliff(cliffConfigPath, cliffArgs) {
     const tempDir = mkdtempSync(join(tmpdir(), 'cliff-'));
     try {
@@ -12,9 +13,9 @@ export function runGitCliff(cliffConfigPath, cliffArgs) {
             copyFileSync(cliffConfigPath, configPath);
         }
         const outputPath = join(tempDir, 'output.json');
-        execFileSync('npx', ['--prefer-offline', '--yes', 'git-cliff', '--config', configPath, ...cliffArgs, '--output', outputPath], {
+        execFileSync('npx', [...GIT_CLIFF_NPX_ARGS, '--config', configPath, ...cliffArgs, '--output', outputPath], {
             stdio: ['ignore', 'ignore', 'inherit'],
-            env: { ...process.env, npm_config_progress: 'false' },
+            env: { ...process.env, npm_config_progress: 'false', RUST_LOG: process.env['RUST_LOG'] ?? 'warn' },
         });
         return readFileSync(outputPath, 'utf8');
     }
@@ -22,10 +23,3 @@ export function runGitCliff(cliffConfigPath, cliffArgs) {
         rmSync(tempDir, { recursive: true, force: true });
     }
 }
-export function refreshGitCliffCache() {
-    execFileSync('npx', ['--yes', 'git-cliff', '--version'], {
-        maxBuffer: GIT_OUTPUT_LIMIT,
-        stdio: ['ignore', 'pipe', 'inherit'],
-        env: { ...process.env, npm_config_progress: 'false' },
-    });
-}

package/dist/esm/showTagPrefixesCommand.d.ts

@@ -1 +1,12 @@
+/**
+ * Orchestrate the CLI `show-tag-prefixes` command.
+ *
+ * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy
+ * entries, followed by an "Undeclared tag prefixes" section when candidate-shaped tags
+ * exist outside the known set. Exits `0` on full derivation success and no collisions;
+ * `1` on any derivation failure or collision. Undeclared candidates do not affect the
+ * exit code.
+ *
+ * @returns The exit code the caller should use.
+ */
 export declare function showTagPrefixesCommand(): Promise<number>;

package/dist/esm/stripScope.d.ts

@@ -1 +1,8 @@
+/**
+ * Strip scope indicators from a raw commit message.
+ *
+ * Handles `scope|type: desc`, `type(scope): desc`, and messages with
+ * ticket prefixes (e.g., `#72 release-kit|fix: ...`). Returns the
+ * message unchanged when no scope is detected.
+ */
 export declare function stripScope(message: string): string;

package/dist/esm/sync-labels/generateCommand.d.ts

@@ -1,10 +1,27 @@
 import type { RepoLabelsConfig } from '../types.js';
 import type { LabelDefinition } from './types.js';
+/** Output path for the generated labels file. */
 export declare const LABELS_OUTPUT_PATH = ".github/labels.yaml";
+/** Formats resolved labels as YAML with generated header including preset hashes. */
 export declare function formatLabelsYaml(labels: LabelDefinition[], presetHashes: Map<string, string>): string;
+/**
+ * Loads `.config/release-kit.config.ts` and returns its `repoLabels` block.
+ *
+ * Reports an actionable error and returns `undefined` when the config file is missing,
+ * fails to load or validate, or carries no `repoLabels` block.
+ */
 export declare function loadRepoLabelsConfig(): Promise<RepoLabelsConfig | undefined>;
+/** Options for the `sync-labels generate` subcommand. */
 interface GenerateOptions {
+    /** Compare the regenerated content against the committed file instead of writing. */
     check?: boolean;
 }
+/**
+ * Runs the `sync-labels generate` command.
+ *
+ * Loads the `repoLabels` block from `.config/release-kit.config.ts`, resolves presets and label adjustments,
+ * and writes `.github/labels.yaml` -- or, with `check`, regenerates in memory and reports whether the committed file
+ * is stale, writing nothing. Returns 0 on success, 1 on failure.
+ */
 export declare function generateCommand({ check }?: GenerateOptions): Promise<number>;
 export {};

package/dist/esm/sync-labels/initCommand.d.ts

@@ -1,6 +1,15 @@
+/** Options for the `sync-labels init` subcommand. */
 interface InitOptions {
     dryRun: boolean;
     force: boolean;
 }
+/**
+ * Run the `sync-labels init` subcommand.
+ *
+ * Discovers workspaces and retired packages, scaffolds the caller workflow, then seeds the
+ * `repoLabels` block: into a new `.config/release-kit.config.ts` when none exists, or
+ * printed to stdout for manual paste when the file is already there — an existing,
+ * hand-authored config is never rewritten. Returns 0 on success, 1 on failure.
+ */
 export declare function syncLabelsInitCommand({ dryRun, force }: InitOptions): Promise<number>;
 export {};

package/dist/esm/sync-labels/presets.d.ts

@@ -1,3 +1,9 @@
 import type { LabelDefinition } from './types.js';
+/** Computes SHA-256 hex digest of a preset file's raw content. Throws if the preset does not exist. */
 export declare function hashPresetFile(presetName: string): string;
+/**
+ * Loads a named preset from the bundled YAML files.
+ *
+ * Returns the parsed label definitions. Throws if the preset does not exist or has invalid content.
+ */
 export declare function loadPreset(presetName: string): LabelDefinition[];

package/dist/esm/sync-labels/resolveLabels.d.ts

@@ -1,3 +1,13 @@
 import type { RepoLabelsConfig } from '../types.js';
 import type { LabelDefinition } from './types.js';
+/**
+ * Resolves the repository's label set from a `repoLabels` config block.
+ *
+ * Resolution is an ordered fold with last-writer-wins: presets are loaded in `extends` order (a later preset replaces
+ * an earlier preset's label of the same name), then the `labels` record is applied: An entry adds a label, replaces
+ * one an earlier layer defined, or removes it (`null`). Replacement is wholesale, so an entry omitting `description`
+ * drops the one an earlier layer supplied rather than inheriting it.
+ * Throws only on a dangling `null`: a removal naming a label no preset defined, which is a stale reference that
+ * would otherwise produce no output diff to review.
+ */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];

package/dist/esm/sync-labels/retiredConfig.d.ts

@@ -1,2 +1,10 @@
+/** Path of the retired standalone sync-labels config file. */
 export declare const RETIRED_SYNC_LABELS_CONFIG_PATH = ".config/sync-labels.config.ts";
+/**
+ * Report an actionable migration error when the retired standalone config file is present.
+ *
+ * Returns `true` when the file exists, in which case the caller must abort. The check is
+ * unconditional on config content: file presence alone triggers it, so a half-migrated
+ * repo cannot silently lose its custom labels.
+ */
 export declare function checkRetiredSyncLabelsConfig(): boolean;

package/dist/esm/sync-labels/syncCommand.d.ts

@@ -1 +1,7 @@
+/**
+ * Run the `sync-labels sync` subcommand.
+ *
+ * Validates prerequisites (gh CLI, workflow file), then triggers the sync-labels workflow
+ * via `gh workflow run`. Returns 0 on success, 1 on failure.
+ */
 export declare function syncLabelsCommand(): number;

package/dist/esm/sync-labels/templates.d.ts

@@ -1,5 +1,19 @@
 import type { LabelDefinition } from './types.js';
+/** Generates the caller workflow YAML for `sync-labels`. */
 export declare function syncLabelsWorkflow(): string;
+/**
+ * Generates scope labels from workspace paths and retired-package names.
+ *
+ * Workspace labels are named after the path basename; retired-package labels after the unscoped package name.
+ * None carries a description: GitHub renders a described label taller and more prominently than a bare one, and
+ * the scope labels are meant to read as a compact group.
+ * Describing only the retired scopes would single them out for that prominence.
+ */
 export declare function buildScopeLabels(workspacePaths: string[], retiredNames?: string[]): LabelDefinition[];
+/**
+ * Renders the `repoLabels` config block, indented for pasting into the object passed to `defineConfig` in
+ * `.config/release-kit.config.ts`.
+ */
 export declare function renderRepoLabelsBlock(scopeLabels: LabelDefinition[]): string;
+/** Generates a new `.config/release-kit.config.ts` carrying the `repoLabels` block. */
 export declare function repoLabelsConfigScript(scopeLabels: LabelDefinition[]): string;

package/dist/esm/sync-labels/types.d.ts

@@ -1,5 +1,9 @@
+/** A single GitHub label definition compatible with EndBug/label-sync. */
 export interface LabelDefinition {
+    /** Display name of the label. */
     name: string;
+    /** Hex color code without the leading `#`. */
     color: string;
+    /** Short description shown in the GitHub UI. Absent when the label carries none. */
     description?: string;
 }