@williamthorsen/release-kit 14.2.2 → 14.2.4

package/dist/esm/configSchema.d.ts

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+/**
+ * Schema for a single historical identity snapshot for a workspace.
+ *
+ * Captures what the package looked like at some earlier point: the full npm `name`
+ * (e.g., `'@williamthorsen/nmr-core'`) and the `tagPrefix` under which tags were
+ * published (e.g., `'core-v'`).
+ */
+export declare const legacyIdentitySchema: z.ZodObject<{
+    name: z.ZodString;
+    tagPrefix: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A single historical identity snapshot for a workspace. Both fields are required, because a full
+ * tuple stays unambiguous across any number of renames.
+ */
+export type LegacyIdentity = z.infer<typeof legacyIdentitySchema>;
+/**
+ * Schema for a package that once lived in this repo but has since been extracted or removed.
+ *
+ * Unlike `legacyIdentitySchema`, retired packages are never consulted for baseline lookup
+ * or changelog attribution; they acknowledge historical tag prefixes and suppress
+ * undeclared-candidate warnings.
+ */
+export declare const retiredPackageSchema: z.ZodObject<{
+    name: z.ZodString;
+    tagPrefix: z.ZodString;
+    successor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A package that once lived in this repo but has since been extracted or removed. */
+export type RetiredPackage = z.infer<typeof retiredPackageSchema>;
+/** Schema for a single workspace override entry in the config file. */
+export declare const workspaceOverrideSchema: z.ZodObject<{
+    dir: z.ZodString;
+    shouldExclude: z.ZodOptional<z.ZodBoolean>;
+    legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Override for a single workspace in the config file. Matches a discovered workspace by `dir`. */
+export type WorkspaceOverride = z.infer<typeof workspaceOverrideSchema>;
+/** Schema for the optional `project` block. */
+export declare const projectConfigSchema: z.ZodObject<{
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Consumer-facing project-release config (`project` block). Empty object opts in to project releases. */
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+/**
+ * Schema for a `releases` entry that names the target at `path`: the discovered workspace there, or otherwise the
+ * directory, whose `tagPrefix` defaults to its basename followed by `-v`.
+ */
+export declare const pathReleaseSchema: z.ZodObject<{
+    path: z.ZodString;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+    legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** A `releases` entry that names the discovered workspace or the directory at `path`. */
+export type PathRelease = z.infer<typeof pathReleaseSchema>;
+/** Schema for a `releases` entry that declares a composite of the named targets. */
+export declare const compositeReleaseSchema: z.ZodObject<{
+    includes: z.ZodArray<z.ZodString>;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A `releases` entry that declares a composite of the named targets, versioned by the root `package.json`. */
+export type CompositeRelease = z.infer<typeof compositeReleaseSchema>;
+/**
+ * Schema for one `releases` entry: `false` excludes the discovered workspace of that name, and the object shapes name
+ * a workspace or a directory, or declare the composite. `validateConfig` relies on this branch order to report a failed entry.
+ */
+export declare const releaseEntrySchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    path: z.ZodString;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+    legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodObject<{
+    includes: z.ZodArray<z.ZodString>;
+    tagPrefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+/** One `releases` entry, keyed in the config by the target's name. */
+export type ReleaseEntry = z.infer<typeof releaseEntrySchema>;
+/** Schema for the optional `changelogJson` block (input shape, all fields optional). */
+export declare const changelogJsonInputSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Schema for the optional `changelogMarkdown` block (input shape, all fields optional). */
+export declare const changelogMarkdownInputSchema: z.ZodObject<{
+    keepVersions: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Schema for the optional `releaseNotes` block (input shape, all fields optional). */
+export declare const releaseNotesInputSchema: z.ZodObject<{
+    shouldInjectIntoReadme: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Schema for a single `workTypes` entry. */
+export declare const workTypeConfigSchema: z.ZodObject<{
+    header: z.ZodString;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludedFromChangelog: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Schema for the `versionPatterns` block. Both arrays are required when the field is provided. */
+export declare const versionPatternsSchema: z.ZodObject<{
+    major: z.ZodArray<z.ZodString>;
+    minor: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** Schema for a single `breakingPolicies` value. */
+export declare const breakingPolicyValueSchema: z.ZodEnum<{
+    optional: "optional";
+    forbidden: "forbidden";
+}>;
+/** Schema for a single label's spec in the `repoLabels.labels` record. */
+export declare const labelSpecSchema: z.ZodObject<{
+    color: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    archived: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/**
+ * A label's color, optional description, optional aliases, and optional archived mark; the name is the record key in
+ * `repoLabels.labels`. An omitted description resolves to empty, which the generated labels file declares explicitly
+ * so that a sync clears whatever description the label has on the repo. Each alias names an existing label that the
+ * sync renames to this one in place, keeping it on the issues and pull requests that have it. `archived: true` retires
+ * the label: The sync archives it, keeping it on the issues and pull requests that have it.
+ */
+export type LabelSpec = z.infer<typeof labelSpecSchema>;
+/**
+ * Schema for the optional `repoLabels` block, which declares the repository's label registry (the labels defined on
+ * the GitHub repo, distinct from labels applied to PRs and issues).
+ *
+ * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
+ * in which an entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Names match
+ * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
+ * Three misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
+ * case, a `null` naming a label not defined by any earlier layer, and an alias that names a resolved label or repeats
+ * another alias.
+ */
+export declare const repoLabelsSchema: z.ZodObject<{
+    extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        color: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        archived: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>;
+/** Consumer-facing `repoLabels` block: bundled presets to extend plus per-name adjustments. */
+export type RepoLabelsConfig = z.infer<typeof repoLabelsSchema>;
+/** Schema for the consumer-facing config file shape (`.config/release-kit.config.ts`). */
+export declare const releaseKitConfigSchema: z.ZodObject<{
+    breakingPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        optional: "optional";
+        forbidden: "forbidden";
+    }>>>;
+    changelogJson: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        outputPath: z.ZodOptional<z.ZodString>;
+        devOnlySections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    changelogMarkdown: z.ZodOptional<z.ZodObject<{
+        keepVersions: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    formatCommand: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodObject<{
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tagPrefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    releaseNotes: z.ZodOptional<z.ZodObject<{
+        shouldInjectIntoReadme: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    releases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        path: z.ZodString;
+        tagPrefix: z.ZodOptional<z.ZodString>;
+        legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            tagPrefix: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        includes: z.ZodArray<z.ZodString>;
+        tagPrefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
+    repoLabels: z.ZodOptional<z.ZodObject<{
+        extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+            color: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            archived: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    retiredPackages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tagPrefix: z.ZodString;
+        successor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    scopeAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    versionPatterns: z.ZodOptional<z.ZodObject<{
+        major: z.ZodArray<z.ZodString>;
+        minor: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    workspaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        dir: z.ZodString;
+        shouldExclude: z.ZodOptional<z.ZodBoolean>;
+        legacyIdentities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            tagPrefix: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    workTypes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        header: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludedFromChangelog: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/**
+ * Consumer-facing config file shape (`.config/release-kit.config.ts`).
+ * All fields are optional; defaults are applied during config merging.
+ */
+export type ReleaseKitConfig = z.infer<typeof releaseKitConfigSchema>;

package/dist/esm/configSchema.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+export const legacyIdentitySchema = z
+    .object({
+    name: z.string().min(1),
+    tagPrefix: z.string().min(1),
+})
+    .strict();
+export const retiredPackageSchema = z
+    .object({
+    name: z.string().min(1),
+    tagPrefix: z.string().min(1),
+    successor: z.string().min(1).optional(),
+})
+    .strict();
+export const workspaceOverrideSchema = z
+    .object({
+    dir: z.string().min(1),
+    shouldExclude: z.boolean().optional(),
+    legacyIdentities: z.array(legacyIdentitySchema).optional(),
+})
+    .strict();
+export const projectConfigSchema = z
+    .object({
+    paths: z.array(z.string().min(1)).min(1).optional(),
+    tagPrefix: z.string().min(1).optional(),
+})
+    .strict();
+export const pathReleaseSchema = z
+    .object({
+    path: z.string().min(1),
+    tagPrefix: z.string().min(1).optional(),
+    legacyIdentities: z.array(legacyIdentitySchema).optional(),
+})
+    .strict();
+export const compositeReleaseSchema = z
+    .object({
+    includes: z.array(z.string().min(1)).min(1),
+    tagPrefix: z.string().min(1).optional(),
+})
+    .strict();
+export const releaseEntrySchema = z.union([z.literal(false), pathReleaseSchema, compositeReleaseSchema]);
+export const changelogJsonInputSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    outputPath: z.string().optional(),
+    devOnlySections: z.array(z.string()).optional(),
+})
+    .strict();
+export const changelogMarkdownInputSchema = z
+    .object({
+    keepVersions: z.number().int().min(1).optional(),
+})
+    .strict();
+export const releaseNotesInputSchema = z
+    .object({
+    shouldInjectIntoReadme: z.boolean().optional(),
+})
+    .strict();
+export const workTypeConfigSchema = z
+    .object({
+    header: z.string(),
+    aliases: z.array(z.string()).optional(),
+    excludedFromChangelog: z.boolean().optional(),
+})
+    .strict();
+export const versionPatternsSchema = z
+    .object({
+    major: z.array(z.string()),
+    minor: z.array(z.string()),
+})
+    .strict();
+export const breakingPolicyValueSchema = z.enum(['forbidden', 'optional']);
+export const labelSpecSchema = z
+    .object({
+    color: z.string().min(1),
+    description: z.string().optional(),
+    aliases: z.array(z.string().min(1)).min(1).optional(),
+    archived: z.literal(true).optional(),
+})
+    .strict();
+export const repoLabelsSchema = z
+    .object({
+    extends: z.array(z.string().min(1)).optional(),
+    labels: z.record(z.string().min(1), labelSpecSchema.nullable()).optional(),
+})
+    .strict();
+export const releaseKitConfigSchema = z
+    .object({
+    breakingPolicies: z.record(z.string(), breakingPolicyValueSchema).optional(),
+    changelogJson: changelogJsonInputSchema.optional(),
+    changelogMarkdown: changelogMarkdownInputSchema.optional(),
+    formatCommand: z.string().min(1).optional(),
+    project: projectConfigSchema.optional(),
+    releaseNotes: releaseNotesInputSchema.optional(),
+    releases: z.record(z.string().min(1), releaseEntrySchema).optional(),
+    repoLabels: repoLabelsSchema.optional(),
+    retiredPackages: z.array(retiredPackageSchema).optional(),
+    scopeAliases: z.record(z.string(), z.string()).optional(),
+    versionPatterns: versionPatternsSchema.optional(),
+    workspaces: z.array(workspaceOverrideSchema).optional(),
+    workTypes: z.record(z.string(), workTypeConfigSchema).optional(),
+})
+    .strict();

package/dist/esm/decideDirectReleases.d.ts

@@ -0,0 +1,30 @@
+import type { UntaggedBaseline } from './assertTaggedBaseline.js';
+import type { ReleaseHistory } from './buildChangelogEntries.js';
+import { type MemberTarget } from './prepareRunContext.js';
+import { type TargetDecision, type TargetPrepareSettings } from './prepareTarget.js';
+import type { ReleaseEntry } from './propagateBumps.js';
+import type { ReleaseType } from './types.js';
+/** The direct releases of the planned package targets, with the reads from which they were decided. */
+export interface DirectReleases {
+    readings: Map<string, ReleaseHistory>;
+    decisions: Map<string, TargetDecision>;
+    /** The bumps from which propagation starts: one per target whose decision releases. */
+    bumps: Map<string, ReleaseEntry>;
+    untaggedBaselines: Map<string, UntaggedBaseline>;
+}
+/**
+ * Reads each planned package and directory target's history and decides its direct release. `force` applies only to
+ * the targets from which the release starts.
+ */
+export declare function decideDirectReleases(planned: readonly MemberTarget[], settings: TargetPrepareSettings, options: {
+    force?: boolean;
+    bumpOverride?: ReleaseType;
+    setVersions?: ReadonlyMap<string, string>;
+}, startIds: ReadonlySet<string>): DirectReleases;
+/**
+ * Records on each planned workspace's and directory's history the entry scopes that route nowhere in its unreleased
+ * window, which only a pass across every target's window can find. The windows go to the finder with the releasing
+ * targets first, in planned order, which sets the order of each target's findings. The repo-root directory target
+ * renders every entry in its window, so it records none, but its window still routes the scope that names it.
+ */
+export declare function reportUnroutedEntryScopes(planned: readonly MemberTarget[], direct: DirectReleases, settings: TargetPrepareSettings, memberTargets: readonly MemberTarget[]): void;

package/dist/esm/decideDirectReleases.js

@@ -0,0 +1,66 @@
+import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
+import { findUnroutedEntryScopes } from "./findUnroutedEntryScopes.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
+import { describeStage, isRepoRootTarget, readHistory, runStage } from "./prepareRunContext.js";
+import { decideTargetRelease, readTargetHistory, } from "./prepareTarget.js";
+export function decideDirectReleases(planned, settings, options, startIds) {
+    const { force, bumpOverride, setVersions } = options;
+    const direct = {
+        readings: new Map(),
+        decisions: new Map(),
+        bumps: new Map(),
+        untaggedBaselines: new Map(),
+    };
+    const hintState = { emitted: false };
+    const knownPrefixes = planned.flatMap(getAllTagPrefixes);
+    for (const target of planned) {
+        const { history, untagged } = runStage(describeStage(target), () => readTargetHistory(target, settings));
+        direct.readings.set(target.id, history);
+        if (untagged !== undefined) {
+            direct.untaggedBaselines.set(target.id, untagged);
+        }
+        if (history.previousTag === undefined && target.kind === 'package' && target.isWorkspace) {
+            maybeEmitBaselineHint(target, knownPrefixes, hintState);
+        }
+        const setVersion = setVersions?.get(target.id);
+        const decision = decideTargetRelease(target, history, {
+            force: force === true && startIds.has(target.id),
+            bumpOverride,
+            setVersion,
+        });
+        direct.decisions.set(target.id, decision);
+        if (decision.outcome === 'skip') {
+            continue;
+        }
+        direct.bumps.set(target.id, decision.setVersion === undefined
+            ? { releaseType: decision.releaseType }
+            : { releaseType: 'patch', newVersionOverride: decision.setVersion });
+    }
+    return direct;
+}
+export function reportUnroutedEntryScopes(planned, direct, settings, memberTargets) {
+    const releasing = planned.filter((target) => direct.decisions.get(target.id)?.outcome === 'release');
+    const windows = [...releasing, ...planned.filter((target) => !releasing.includes(target))].map((target) => ({
+        target,
+        history: readHistory(direct.readings, target),
+    }));
+    const findings = findUnroutedEntryScopes(windows.map(({ target, history }) => ({ dir: target.id, commits: history.unreleased.commits })), memberTargets.map((target) => target.id), settings.scopeAliases ?? {});
+    for (const { target, history } of windows) {
+        history.unreleased.diagnostics.unroutedEntryScopes = isRepoRootTarget(target)
+            ? []
+            : (findings.get(target.id) ?? []);
+    }
+}
+function maybeEmitBaselineHint(target, knownPrefixes, state) {
+    if (state.emitted || (target.legacyIdentities?.length ?? 0) > 0)
+        return;
+    const candidates = detectUndeclaredTagPrefixes(knownPrefixes);
+    if (candidates.length === 0)
+        return;
+    const totalTags = candidates.reduce((sum, candidate) => sum + candidate.tagCount, 0);
+    const example = candidates[0]?.exampleTags[0] ?? `${candidates[0]?.prefix ?? ''}?`;
+    process.stderr.write(`Hint: no baseline tag found for ${target.id} under '${target.tagPrefix}', but ` +
+        `${totalTags} candidate-shaped tags exist (e.g., ${example}). ` +
+        "Run 'release-kit show-tag-prefixes' to check for undeclared legacy prefixes.\n");
+    state.emitted = true;
+}

package/dist/esm/defineConfig.d.ts

@@ -1,5 +1,5 @@
-import type { ReleaseKitConfig } from './types.js';
-export type { LabelSpec, ReleaseKitConfig, RepoLabelsConfig } from './types.js';
+import type { ReleaseKitConfig } from './configSchema.js';
+export type { LabelSpec, ReleaseKitConfig, RepoLabelsConfig } from './configSchema.js';
 /**
  * Returns a configuration unchanged, typing it as a `ReleaseKitConfig`.
  *

package/dist/esm/deriveReleaseNotesConfig.d.ts

@@ -1,4 +1,5 @@
-import type { ReleaseKitConfig, ReleaseNotesConfig } from './types.js';
+import type { ReleaseKitConfig } from './configSchema.js';
+import type { ReleaseNotesConfig } from './types.js';
 export interface ResolvedReleaseNotesConfig {
     releaseNotes: ReleaseNotesConfig;
     changelogJsonOutputPath: string;

package/dist/esm/deriveReleaseNotesConfig.js

@@ -1,5 +1,5 @@
 import { DEFAULT_CHANGELOG_JSON_CONFIG, DEFAULT_RELEASE_NOTES_CONFIG } from "./defaults.js";
-import { resolveWorkTypes } from "./loadConfig.js";
+import { resolveWorkTypes } from "./mergeConfig.js";
 export function deriveDependenciesHeader(workTypes) {
     const header = workTypes['deps']?.header;
     if (header === undefined) {

package/dist/esm/formatPrepareFiles.d.ts

@@ -0,0 +1,11 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { ReleasedPackageResult } from './types.js';
+/** Appends bump file detail lines. */
+export declare function formatBumpFiles(lines: string[], workspace: Pick<ReleasedPackageResult, 'bumpedFiles'>, dryRun: boolean, indent?: string): void;
+/**
+ * Appends a line per generated changelog file, each followed by the versions kept from the existing changelog and a
+ * warning naming the sections dropped for lacking a version, then a line per removed changelog archive file.
+ */
+export declare function formatChangelogFiles(lines: string[], release: Pick<ReleasedPackageResult, 'changelogFiles' | 'changelogPreservation' | 'removedChangelogFiles'>, dryRun: boolean, style: OutputStyle, indent?: string): void;
+/** Appends release-notes preview file lines, which are present only under `--with-release-notes`. */
+export declare function formatPreviewFiles(lines: string[], release: Pick<ReleasedPackageResult, 'previewFiles'>, dryRun: boolean, indent?: string): void;

package/dist/esm/formatPrepareFiles.js

@@ -0,0 +1,55 @@
+import { formatStatusLine } from '@williamthorsen/nmr-core';
+import { dim } from "./format.js";
+export function formatBumpFiles(lines, workspace, dryRun, indent = '') {
+    for (const file of workspace.bumpedFiles) {
+        if (dryRun) {
+            lines.push(dim(`${indent}  [dry-run] Would bump ${file}`));
+        }
+        else {
+            lines.push(dim(`${indent}  Bumped ${file}`));
+        }
+    }
+}
+export function formatChangelogFiles(lines, release, dryRun, style, indent = '') {
+    for (const file of release.changelogFiles) {
+        if (dryRun) {
+            lines.push(dim(`${indent}  [dry-run] Would generate changelog: ${file}`));
+        }
+        else {
+            lines.push(dim(`${indent}  Generating changelog: ${file}`));
+        }
+        const preservation = release.changelogPreservation?.find((candidate) => candidate.file === file);
+        if (preservation === undefined) {
+            continue;
+        }
+        if (preservation.preservedVersions.length > 0) {
+            lines.push(dim(`${indent}    Kept from the existing changelog: ${preservation.preservedVersions.join(', ')}`));
+        }
+        const dropped = preservation.droppedUnversionedHeadings;
+        if (dropped.length === 0) {
+            continue;
+        }
+        const message = `Dropped ${dropped.length} section${dropped.length === 1 ? '' : 's'} without a version: ${dropped.join(', ')}`;
+        lines.push(`${indent}    ${formatStatusLine(style, 'warning', message)}`);
+    }
+    const removedFiles = release.removedChangelogFiles ?? [];
+    for (const file of removedFiles) {
+        if (dryRun) {
+            lines.push(dim(`${indent}  [dry-run] Would remove changelog: ${file}`));
+        }
+        else {
+            lines.push(dim(`${indent}  Removing changelog: ${file}`));
+        }
+    }
+}
+export function formatPreviewFiles(lines, release, dryRun, indent = '') {
+    const previewFiles = release.previewFiles ?? [];
+    for (const file of previewFiles) {
+        if (dryRun) {
+            lines.push(dim(`${indent}  [dry-run] Would write ${file}`));
+        }
+        else {
+            lines.push(dim(`${indent}  Wrote ${file}`));
+        }
+    }
+}

package/dist/esm/formatPrepareWarnings.d.ts

@@ -0,0 +1,26 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { PolicyViolation, PrepareResult, ReleasedPackageResult } from './types.js';
+/**
+ * Appends warning lines for the change-record blocks that could not be read, the entries whose type is undeclared, and
+ * the entry scopes that don't match any workspace in the commit's window.
+ *
+ * `indent` follows the same convention as {@link formatUnparseableWarning}.
+ */
+export declare function formatChangeRecordWarnings(lines: string[], release: Pick<ReleasedPackageResult, 'malformedBlocks' | 'undeclaredEntryTypes' | 'unroutedEntryScopes'>, style: OutputStyle, indent?: string): void;
+/**
+ * Appends policy-violation lines when applicable: one header line plus one bullet per violation.
+ *
+ * `indent` follows the same convention as {@link formatUnparseableWarning}.
+ */
+export declare function formatPolicyViolations(lines: string[], violations: PolicyViolation[] | undefined, style: OutputStyle, indent?: string): void;
+/**
+ * Appends unparseable commit warning lines when applicable.
+ *
+ * `indent` is an additional outer indent prepended to both the header and bullet lines; base
+ * spacing (2 spaces for the header, 4 for bullets) is encoded in the format strings, so the
+ * caller passes only the section-level indent (e.g., `''` for single-package, `'  '` for
+ * multi-workspace).
+ */
+export declare function formatUnparseableWarning(lines: string[], release: Pick<ReleasedPackageResult, 'unparseableCommits'>, style: OutputStyle, indent?: string): void;
+/** Appends warning lines when the prepare result includes warnings. */
+export declare function formatWarnings(lines: string[], result: PrepareResult, style: OutputStyle): void;

package/dist/esm/formatPrepareWarnings.js

@@ -0,0 +1,72 @@
+import { formatStatusLine, truncateToWidth } from '@williamthorsen/nmr-core';
+const SUBJECT_COLUMN_BUDGET = 72;
+export function formatChangeRecordWarnings(lines, release, style, indent = '') {
+    const { malformedBlocks = [], undeclaredEntryTypes = [], unroutedEntryScopes = [] } = release;
+    if (malformedBlocks.length > 0) {
+        const count = malformedBlocks.length;
+        const header = `${count} change-record block${count === 1 ? '' : 's'} could not be read (item taken from the title)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const block of malformedBlocks) {
+            lines.push(`${indent}    · ${block.commitHash.slice(0, 7)} '${truncateSubject(block.commitSubject)}': ${block.reason}`);
+        }
+    }
+    if (undeclaredEntryTypes.length > 0) {
+        const count = undeclaredEntryTypes.length;
+        const header = `${count} change-record entr${count === 1 ? 'y has an' : 'ies have'} undeclared type${count === 1 ? '' : 's'} (no item)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const entry of undeclaredEntryTypes) {
+            const shortHash = entry.commitHash.slice(0, 7);
+            lines.push(`${indent}    · ${shortHash} '${truncateSubject(entry.commitSubject)}': type '${entry.type}' at entry ${entry.entryPosition}`);
+        }
+    }
+    if (unroutedEntryScopes.length === 0) {
+        return;
+    }
+    const count = unroutedEntryScopes.length;
+    const header = `${count} change-record entry scope${count === 1 ? ' does not match' : 's do not match'} any workspace in the commit's window (no item there)`;
+    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+    for (const finding of unroutedEntryScopes) {
+        const shortHash = finding.commitHash.slice(0, 7);
+        lines.push(`${indent}    · ${shortHash} '${truncateSubject(finding.commitSubject)}': scope '${finding.scope}' at entry ${finding.entryPosition}`);
+    }
+}
+export function formatPolicyViolations(lines, violations, style, indent = '') {
+    if (violations === undefined || violations.length === 0) {
+        return;
+    }
+    const count = violations.length;
+    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} policy violation${count === 1 ? '' : 's'}:`)}`);
+    for (const violation of violations) {
+        const shortHash = violation.commitHash.slice(0, 7);
+        const subject = violation.commitSubject;
+        const truncatedSubject = truncateSubject(subject);
+        const location = violation.surface === 'entry' ? `entry ${violation.entryPosition ?? '?'}` : `${violation.surface} surface`;
+        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}': type '${violation.type}' at ${location}`);
+    }
+}
+export function formatUnparseableWarning(lines, release, style, indent = '') {
+    const unparseable = release.unparseableCommits;
+    if (unparseable === undefined || unparseable.length === 0) {
+        return;
+    }
+    const count = unparseable.length;
+    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed`)}`);
+    for (const commit of unparseable) {
+        const shortHash = commit.hash.slice(0, 7);
+        const truncatedSubject = truncateSubject(commit.subject);
+        lines.push(`${indent}    · ${shortHash} ${truncatedSubject}`);
+    }
+}
+export function formatWarnings(lines, result, style) {
+    const { warnings } = result;
+    if (warnings === undefined || warnings.length === 0) {
+        return;
+    }
+    lines.push('');
+    for (const warning of warnings) {
+        lines.push(formatStatusLine(style, 'warning', warning));
+    }
+}
+function truncateSubject(subject) {
+    return truncateToWidth(subject, { width: SUBJECT_COLUMN_BUDGET });
+}

package/dist/esm/help/initHelp.d.ts

@@ -0,0 +1,4 @@
+/** Prints the `init` command's help text. */
+export declare function showInitHelp(): void;
+/** Prints the `update-templates` command's help text. */
+export declare function showUpdateTemplatesHelp(): void;

package/dist/esm/help/initHelp.js

@@ -0,0 +1,31 @@
+export function showInitHelp() {
+    console.info(`
+Usage: release-kit init [options]
+
+Initialize release-kit in the current repository.
+By default, scaffolds only the GitHub Actions workflow files. When every
+package is private, skips publish.yaml and create-github-release.yaml.
+
+Options:
+  --with-config   Also scaffold .config/release-kit.config.ts
+  --force         Overwrite existing files instead of skipping them
+  --dry-run       Preview changes without writing files
+  --help, -h      Show this help message
+`);
+}
+export function showUpdateTemplatesHelp() {
+    console.info(`
+Usage: release-kit update-templates [options]
+
+Update the GitHub Actions workflows that release-kit scaffolds to the templates
+of the installed version, showing what changed in each file. Creates a missing
+workflow that \`init\` would create, and refreshes sync-labels.yaml only when it
+exists. When every package is private, refreshes publish.yaml and
+create-github-release.yaml only when they exist. Keeps publish.yaml's provenance
+setting. Never touches config files.
+
+Options:
+  --dry-run       Preview changes without writing files
+  --help, -h      Show this help message
+`);
+}

package/dist/esm/help/overridesHelp.d.ts

@@ -0,0 +1,4 @@
+/** Prints the `overrides` command's help text. */
+export declare function showOverridesHelp(): void;
+/** Prints the `overrides validate` subcommand's help text. */
+export declare function showOverridesValidateHelp(): void;