@williamthorsen/release-kit 2.0.0 → 2.3.0

package/CHANGELOG.md

@@ -2,129 +2,148 @@
 
 All notable changes to this project will be documented in this file.
 
-## [release-kit-v2.0.0] - 2026-03-16
+## [release-kit-v2.3.0] - 2026-03-28
 
 ### Features
 
-- #20 release-kit|feat!: Move reusable release workflow into repo (#26)
+- #8 feat: Add shared writeFileWithCheck utility and overwrite reporting (#66)
 
-Move the reusable release workflow from `williamthorsen/.github` into this repository as `.github/workflows/release-workflow.yaml`, versioned independently via `release-workflow-v{major}` tags. Update `release-kit init` templates to reference the new workflow location. The workflow no longer requires pnpm: it installs release-kit globally and runs it directly.
+Extracts three duplicated `writeIfAbsent` implementations and two duplicated terminal helper sets into shared utilities in `@williamthorsen/node-monorepo-core`, then migrates all consumers (`release-kit init`, `preflight init`, `sync-labels`) to use them. All init commands now report which files were created, overwritten, skipped, or failed — including when `--force` replaces existing files.
 
-- #22 release-kit|feat: Add --force flag to release-kit prepare (#25)
+- #11 release-kit|feat: Separate tag-write errors from release preparation errors (#67)
 
-Add a `--force` flag that allows release preparation to proceed even when no release-worthy commits are found.
+When tag-file writing fails, the error message now reads "Error writing release tags:" instead of the misleading "Error preparing release:", which only appeared because both operations shared a single try/catch.
 
-- #7 release-kit|feat!: Slim down release workflow by removing unnecessary pnpm install (#21)
+Refactors `writeReleaseTags` to use the shared `writeFileWithCheck` utility from `@node-monorepo-tools/core` instead of raw `mkdirSync`/`writeFileSync`. The function now returns a structured `WriteResult` instead of throwing, and contains no `console` calls — all presentation moves to `runAndReport`.
 
-Remove pnpm setup steps from the reusable release workflow. Release-kit is self-contained and invokes git-cliff and prettier via `npx`, so no local dependency installation is needed.
+### Tests
 
-### Refactoring
+- #14 release-kit|tests: Add eligibility check failure and short-circuit tests (#63)
 
-- #6 release-kit|refactor: Clean up release-kit post-migration issues (#19)
+Adds 4 unit tests to `initCommand.unit.test.ts` covering the remaining `checkEligibility` orchestration gaps: individual failure exit codes for `hasPackageJson` and `usesPnpm`, and short-circuit verification ensuring downstream checks are skipped when an earlier check fails.
 
-## [release-kit-v1.0.1] - 2026-03-12
+- #13 release-kit|tests: Add cliff.toml.template alignment test (#64)
 
-### Bug fixes
+Adds a unit test that enforces bidirectional alignment between `DEFAULT_WORK_TYPES` and the bundled `cliff.toml.template` commit parsers. The test parses the TOML template using `smol-toml`, then verifies that every canonical type name and alias is matched by a parser with the correct group heading, and that every parser group maps to a known work type header.
 
-- #34 release-kit|fix: Fix failure to find consumer's config (#35)
+- #12 release-kit|tests: Add releasePrepare coverage for bumpOverride, tagPrefix, and dry-run tags (#65)
 
-Resolves the config file path to an absolute path using `process.cwd()` before passing it to both `existsSync` and `jiti.import()`. Previously, `jiti.import()` received a bare relative path which it resolved against `import.meta.url` (the package's install location), making it impossible for consumers to load their config files. Also fixes root tsconfig includes to cover `.config/` and removes a stale duplicate comment.
+Adds three unit tests to `releasePrepare.unit.test.ts` covering previously untested code paths: the `bumpOverride` bypass of commit-based bump detection, custom `tagPrefix` propagation into tags, and tag computation in dry-run mode.
 
-## [release-kit-v1.0.0] - 2026-03-12
+## [release-kit-v2.2.0] - 2026-03-27
 
 ### Features
 
-- #28 release-kit|feat!: Migrate to CLI-driven release preparation with auto-discovery (#31)
+- #27 release-kit|feat: Auto-detect Prettier for CHANGELOG formatting (#36)
 
-Replaces release-kit's script-based release preparation with a self-contained CLI (`npx @williamthorsen/release-kit prepare`) that auto-discovers workspaces from `pnpm-workspace.yaml`. Adds workspace auto-discovery, TypeScript config loading via jiti, config validation, and a `component()` factory that accepts full workspace-relative paths. Refactors the type system: `WorkTypeConfig` becomes a record keyed by type name, version-bump rules move to a separate `VersionPatterns` structure, and `ComponentConfig` gains a `dir` field for canonical directory identity.
+When `formatCommand` is not configured, release-kit now auto-detects whether the repo uses Prettier by checking for config files (`.prettierrc*`, `prettier.config.*`) or a `"prettier"` key in root `package.json`. If found, it defaults to `npx prettier --write` on generated files. If not found, formatting is skipped.
 
-### Refactoring
+- #28 release-kit|feat: Add tag-creation command (#40)
 
-- #28 release-kit|refactor: Adjust location of config & tags file
+Adds a `release-kit tag` CLI command that reads computed tag names from the `tmp/.release-tags` file produced by `prepare` and creates annotated git tags. The command supports `--dry-run` (preview without creating tags) and `--no-git-checks` (skip dirty working tree validation). The `createTags` function and its options type are exported for programmatic use.
 
-### Tooling
+- #29 release-kit|feat: Add publish command (#42)
 
-- #28 release-kit|tooling: Remove legacy release-kit scripts
+Adds a `release-kit publish` subcommand that derives packages to publish from git tags on HEAD and delegates to the repo's detected package manager. Also cleans up the `.release-tags` file after tag creation.
 
-## [release-kit-v0.3.0] - 2026-03-11
+- #41 release-kit|feat: Remove tagPrefix customization from component config (#49)
 
-### Features
+Removes the ability to customize `tagPrefix` per component, enforcing the deterministic `{dir}-v` convention universally. The internal `tagPrefix` property on `ComponentConfig` and `ReleaseConfig` is preserved — only the override/customization entry points are removed. Existing configs that still include `tagPrefix` now receive a clear deprecation error.
 
-- Release-kit|feat: Extract CLI runner into release-kit and co-locate scripts with workflow
+- #54 release-kit|feat: Add styled terminal output to prepare command (#55)
 
-Move release script logic (arg parsing, validation, component filtering) into a reusable `runReleasePrepare` function in the release-kit package. Consuming repos now provide only their config and call `runReleasePrepare(config)`.
+Adds ANSI formatting and emoji markers to the `release-kit prepare` command output. Progress chatter is dimmed, key results (version bumps, release tags, completion status) are highlighted with bold text and emoji, and monorepo components are separated by box-drawing section headers.
 
-Relocate release-prepare.ts and release.config.ts from scripts/ to .github/scripts/ so they live alongside the workflow they serve.
+- #59 feat: Extract nmr CLI from core package (#61)
 
-- #20 release-kit|feat: Add release-kit init CLI command for automated repo setup (#22)
+Extracts all nmr CLI code from `packages/core` into a new `packages/nmr` package (`@williamthorsen/nmr`). Core is reduced to an empty shared-library shell ready for cross-cutting utilities. All internal references are rewired and the full build/test pipeline passes.
 
-Add an interactive `npx release-kit init` CLI command that checks repo eligibility, detects monorepo vs single-package layout, scaffolds workflow/scripts/config files, and updates `package.json` with release scripts.
+Scopes: core, nmr
 
-Also expand `runReleasePrepare` to polymorphically handle both `MonorepoReleaseConfig` and `ReleaseConfig`, and update the esbuild plugin to preserve shebangs during compilation.
+### Refactoring
 
-- #24 release-kit|feat: Return computed tags from release prepare and write .release-tags (#27)
+- #43 refactor: Replace dist bin targets with thin wrapper scripts (#48)
 
-`releasePrepare` and `releasePrepareMono` now return `string[]` of computed tag names instead of `void`. `runReleasePrepare` writes these tags to a `.release-tags` file (one tag per line) so the CI workflow can read them instead of independently deriving tag names from `git diff`. In dry-run mode the file is not written. This makes `tagPrefix` the single source of truth for tag names, eliminating the mismatch between TypeScript-computed tags and workflow-derived tags.
+The `bin` entries in `packages/core` and `packages/release-kit` pointed directly into `dist/esm/`, causing `pnpm install` to emit "Failed to create bin" warnings in fresh worktrees where `dist/` does not yet exist. Each bin entry now points to a committed wrapper script in `bin/` that dynamically imports the real entry point. The `files` field in both packages includes `bin` so the wrappers are published.
 
-## [strings-v3.1.1] - 2026-03-10
+- #53 release-kit|refactor: Separate presentation from logic in prepare workflow (#57)
 
-### Tooling
+Extracts all `console.info` calls from the prepare workflow's logic functions (`bumpAllVersions`, `generateChangelogs`, `releasePrepare`, `releasePrepareMono`) into a dedicated `reportPrepare` formatter. Logic functions now return structured result types (`BumpResult`, `ComponentPrepareResult`, `PrepareResult`). The legacy `runReleasePrepare` entry point is retired, with its utilities absorbed into `prepareCommand`.
 
-- \*|tooling: Change package registry from github to npmjs
+### Tests
 
-## [tools-v3.0.1] - 2026-03-10
+- #17 release-kit|tests: Cover multi-changelogPaths and error paths (#44)
 
-### Tooling
+Add three tests for previously untested code paths:
 
-- \*|tooling: Change package registry from github to npmjs
+- `releasePrepareMono`: component with two `changelogPaths` entries, asserting `git-cliff` is invoked once per path with the correct `--output` target.
+- `getCommitsSinceTarget`: `git describe` failure with a non-128 exit status propagates as a wrapped error instead of being swallowed.
+- `getCommitsSinceTarget`: `git log` failure is wrapped and re-thrown with the commit range in the message.
 
-## [release-kit-v0.2.1] - 2026-03-09
+Also adds a `findAllCliffOutputPaths()` test helper that collects the `--output` arg from every `git-cliff` mock call.
 
 ### Tooling
 
-- Root|tooling: Make release-kit public
+- #37 root|tooling: Adopt nmr to run monorepo and workspace scripts (#38)
 
-## [release-kit-v0.2.0] - 2026-03-09
+Replaces the legacy workspace script runner and ~25 root `package.json` scripts with `nmr`, the monorepo's own context-aware script runner. Root scripts are reduced to 4 (`prepare`, `postinstall`, `ci`, `bootstrap`), packages use direct build commands for bootstrap, and release-kit declares tier-3 test overrides for its integration test configs.
 
-### Documentation
+## [release-workflow-v1] - 2026-03-19
 
-- Release-kit|docs: Rewrite README as adoption guide
+### Dependencies
 
-Replace minimal API docs with end-to-end adoption guide covering single-package and monorepo configurations, release scripts, GitHub Actions workflows that commit directly to `main`.
+- Root|deps: Add release-kit as root devDependency
 
-### Tooling
+Make `npx release-kit` and `pnpm exec release-kit` resolve within
+this repo by adding a `workspace:*` dependency that symlinks the bin.
+
+### Features
+
+- #23 release-kit|feat: Add sync-labels command (#33)
 
-- #13 root|tooling: Migrate from changesets to release-kit (#16)
+Add a `release-kit sync-labels` command group with three subcommands (`init`, `generate`, `sync`) for declarative GitHub label management in monorepos. Bundle a reusable GitHub Actions workflow and composable label presets with the release-kit package. Introduce a `findPackageRoot` utility to replace fragile hardcoded path resolutions across the codebase.
 
-Replaces the `@changesets/cli`-based release workflow with the in-house `release-kit` package, adding `git-cliff` for changelog generation, a monorepo release config for all 13 packages, and a CLI wrapper script. Removes all changeset infrastructure and creates per-package baseline version tags.
+- #34 release-kit|feat: Report up-to-date status for unchanged init files (#35)
 
-- #10 root|tooling: Publish release-kit to GitHub Package Registry (#17)
+`release-kit init` now compares existing file content against the default before reporting status. When an existing file is identical to the default (after normalizing trailing whitespace), it reports `✅ (up to date)` instead of the misleading `⚠️ (already exists)`.
 
-Adds release infrastructure for the toolbelt monorepo: a GitHub Actions `workflow_dispatch` workflow that automates the full release cycle (prepare, commit, tag, push) on `main`, convenience `release:prepare` scripts in the release-kit package, and a `RELEASING.md` documenting the workflow-based release process.
+- Release-workflow|feat: Accept force input
 
-- #10 root|tooling: Streamline release-kit adoption
+Pass `--force` to the prepare command so callers can force a version
+bump even when there are no release-worthy changes.
 
-## [tools-v3.0.0] - 2026-03-08
+## [release-kit-v2.1.0] - 2026-03-17
 
 ### Features
 
-- #7 release|feat: Create release-kit package (#9)
+- #7 release-kit|feat!: Slim down release workflow by removing unnecessary pnpm install (#21)
 
-Creates the `@williamthorsen/release-kit` package in the `toolbelt` monorepo, extracting version-bumping and changelog-generation logic from `skypilot-site` and `devtools/afg` into a reusable library. The package provides functions for parsing conventional commits, determining semver bump types, updating `package.json` versions across workspaces, and generating changelogs via `git-cliff`.
+Make release-kit self-contained by invoking git-cliff via `npx --yes` instead of requiring it on PATH, and by appending modified file paths to the format command so lightweight formatters like `npx prettier --write` work without a full `pnpm install`. Update init templates, README, and consuming repo config/workflow to reference workflow v3.
 
-Add contextual error messages to all I/O operations: file reads/writes in bumpAllVersions, execSync calls in generateChangelogs and releasePrepare, and git commands in getCommitsSinceTarget.
+- #22 release-kit|feat: Add --force flag to release-kit prepare (#25)
 
-Differentiate expected "no tag" errors from real failures in git describe. Replace string-based commit separator with null-byte to prevent collisions with commit message content. Log git log failures before returning empty results.
+Add a `--force` flag to `release-kit prepare` that bypasses the "no commits since last tag" check in monorepo mode, allowing version bumping and changelog generation to proceed even when no new commits are found since the last release tag. The flag requires `--bump` since there are no commits to infer bump type from. The local release workflow gains a `force` boolean input for future use.
 
-Add tests for uppercase/mixed-case type resolution, workspace+breaking combo parsing, breaking-on-first-commit early return, and empty workTypes. Strengthen alias tests to use toStrictEqual for full shape
-verification.
+- #20 release-kit|feat!: Move reusable release workflow into repo (#26)
+
+Moves the reusable release workflow from `williamthorsen/.github` into this repo as `release-workflow.yaml`, stripping all pnpm-related steps since release-kit now runs git-cliff and prettier via `npx` internally. Updates this repo's caller workflow to use a relative path and update init templates to reference the new location. Establishes a naming convention (`{name}-workflow.yaml` for reusable, `{name}.yaml` for callers) and independent versioning strategy (`{name}-workflow-v{major}` tags), documented in `.github/workflows/README.md`.
 
-Simplify determineBumpType by replacing the redundant isKeyOf guard on RELEASE_PRIORITY with a direct lookup, since bump is already typed as ReleaseType. Simplify parseCommitMessage by replacing mutable object construction with a conditional spread for the optional workspace field.
+- #30 release-kit|feat: Allow git-cliff to be used without config (#31)
 
-Add workspaceAliases field to ReleaseConfig and integrate into parseCommitMessage for resolving workspace shorthand names to canonical names. Replace execSync with execFileSync using argument arrays in generateChangelogs and getCommitsSinceTarget to prevent shell injection from paths with special characters. Remove redundant length-check guard in bumpAllVersions, keeping the undefined guard that also narrows the type.
+Adds a `resolveCliffConfigPath()` function that searches for a git-cliff config in a 4-step cascade (explicit path → `.config/git-cliff.toml` → `cliff.toml` → bundled `cliff.toml.template`), eliminating the requirement for consuming repos to maintain a cliff config copy. Restructures the `init` command to scaffold only the workflow file by default, with new `--with-config` and `--force` flags. Moves `.release-tags` from `/tmp/release-kit/` to project-local `tmp/` for predictable behavior in local runs.
 
 ### Refactoring
 
-- Release-kit|refactor: Inline isKeyOf and remove toolbelt.objects dependency
+- #6 release-kit|refactor: Clean up release-kit post-migration issues (#19)
+
+Addresses five code quality issues and a test coverage gap identified during the release-kit migration (#5). Extracts a duplicated `isRecord` type guard into a shared module, eliminates a double-read in `bumpAllVersions`, improves error handling in `usesPnpm` by replacing a silent catch with a structured error boundary, removes an unreachable `'feature'` pattern from version defaults, and adds an integration test for scaffold template path resolution.
+
+## [release-kit-v1.0.1] - 2026-03-14
+
+### Features
+
+- #5 release-kit|feat: Migrate release-kit from toolbelt (#18)
+
+Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
 
 <!-- generated by git-cliff -->

package/README.md

@@ -13,17 +13,14 @@ pnpm add -D @williamthorsen/release-kit
 ## Quick start
 
 ```bash
-# 1. Set up release-kit in your repo (scaffolds workflow + optional config)
+# 1. Set up release-kit in your repo (scaffolds the release workflow)
 npx @williamthorsen/release-kit init
 
 # 2. Preview what a release would do
 npx @williamthorsen/release-kit prepare --dry-run
-
-# 3. Copy cliff.toml.template to your repo root (if init didn't create one)
-cp node_modules/@williamthorsen/release-kit/cliff.toml.template cliff.toml
 ```
 
-That's it for most repos. The CLI auto-discovers workspaces and applies sensible defaults. Customize only what you need via `.config/release-kit.config.ts`.
+That's it for most repos. The CLI auto-discovers workspaces and applies sensible defaults. The bundled `cliff.toml.template` is used automatically — no need to copy it. Customize only what you need via `.config/release-kit.config.ts`.
 
 ## How it works
 
@@ -31,7 +28,7 @@ That's it for most repos. The CLI auto-discovers workspaces and applies sensible
 2. **Config loading**: loads `.config/release-kit.config.ts` (if present) via [jiti](https://github.com/unjs/jiti) and merges it with discovered defaults.
 3. **Commit analysis**: for each component, finds commits since the last version tag, parses them for type and scope, and determines the appropriate version bump.
 4. **Version bump + changelog**: bumps `package.json` versions and generates changelogs via `git-cliff`.
-5. **Release tags file**: writes computed tags to `/tmp/release-kit/.release-tags` for CI consumption.
+5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
 ## CLI reference
 
@@ -51,29 +48,25 @@ Options:
 
 Component names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
-**Self-hosting note**: in a repo where `release-kit` is a workspace package (e.g., this monorepo), `npx` and `pnpm exec` may not resolve the binary. Run the built entry point directly:
-
-```bash
-node packages/release-kit/dist/esm/bin/release-kit.js prepare --dry-run
-```
-
 ### `release-kit init`
 
-Initialize release-kit in the current repository. Scaffolds a GitHub Actions workflow and an optional config file.
+Initialize release-kit in the current repository. By default, scaffolds only the GitHub Actions workflow file. Use `--with-config` to also scaffold configuration files.
 
 ```
 Usage: release-kit init [options]
 
 Options:
-  --dry-run     Preview changes without writing files
-  --help, -h    Show help
+  --with-config    Also scaffold .config/release-kit.config.ts and .config/git-cliff.toml
+  --force          Overwrite existing files instead of skipping them
+  --dry-run        Preview changes without writing files
+  --help, -h       Show help
 ```
 
 Scaffolded files:
 
-- `.config/release-kit.config.ts` — starter config with commented-out customization examples
 - `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
-- `cliff.toml` — copied from the bundled template (prompted if missing)
+- `.config/release-kit.config.ts` — starter config with commented-out customization examples (with `--with-config`)
+- `.config/git-cliff.toml` — copied from the bundled template (with `--with-config`)
 
 ## Configuration
 
@@ -105,14 +98,14 @@ The config file supports both `export default config` and `export const config =
 
 ### `ReleaseKitConfig` reference
 
-| Field              | Type                             | Description                                                                                    |
-| ------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `cliffConfigPath`  | `string`                         | Path to `cliff.toml` (defaults to `'cliff.toml'`)                                              |
-| `components`       | `ComponentOverride[]`            | Override or exclude discovered components (matched by `dir`)                                   |
-| `formatCommand`    | `string`                         | Shell command to run after changelog generation; modified file paths are appended as arguments |
-| `versionPatterns`  | `VersionPatterns`                | Rules for which commit types trigger major/minor bumps                                         |
-| `workspaceAliases` | `Record<string, string>`         | Maps shorthand workspace names to canonical names in commits                                   |
-| `workTypes`        | `Record<string, WorkTypeConfig>` | Work type definitions, merged with defaults by key                                             |
+| Field              | Type                             | Description                                                                                                                   |
+| ------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `cliffConfigPath`  | `string`                         | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template |
+| `components`       | `ComponentOverride[]`            | Override or exclude discovered components (matched by `dir`)                                                                  |
+| `formatCommand`    | `string`                         | Shell command to run after changelog generation; modified file paths are appended as arguments                                |
+| `versionPatterns`  | `VersionPatterns`                | Rules for which commit types trigger major/minor bumps                                                                        |
+| `workspaceAliases` | `Record<string, string>`         | Maps shorthand workspace names to canonical names in commits                                                                  |
+| `workTypes`        | `Record<string, WorkTypeConfig>` | Work type definitions, merged with defaults by key                                                                            |
 
 All fields are optional.
 
@@ -121,7 +114,6 @@ All fields are optional.
 ```typescript
 interface ComponentOverride {
   dir: string; // Package directory name (e.g., 'arrays')
-  tagPrefix?: string; // Custom git tag prefix (defaults to '${dir}-v')
   shouldExclude?: boolean; // If true, exclude from release processing
 }
 ```
@@ -185,12 +177,9 @@ component('packages/arrays');
 //   changelogPaths: ['packages/arrays'],
 //   paths: ['packages/arrays/**'],
 // }
-
-// Custom tag prefix
-component('libs/core', 'core-v');
 ```
 
-The `dir` field is derived from `path.basename()`, so `packages/arrays` and `libs/arrays` both produce `dir: 'arrays'`.
+The `dir` field is derived from `path.basename()`, so `packages/arrays` and `libs/arrays` both produce `dir: 'arrays'`. The `tagPrefix` is always `${dir}-v` — it cannot be customized.
 
 ## GitHub Actions workflow
 
@@ -259,7 +248,7 @@ jobs:
         if: steps.check.outputs.changed == 'true'
         id: tags
         run: |
-          TAGS=$(cat /tmp/release-kit/.release-tags | tr '\n' ' ')
+          TAGS=$(cat tmp/.release-tags | tr '\n' ' ')
           echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
           echo "Releasing: $TAGS"
 
@@ -297,7 +286,7 @@ And the tag step with:
   if: steps.check.outputs.changed == 'true'
   id: tags
   run: |
-    TAG=$(cat /tmp/release-kit/.release-tags)
+    TAG=$(cat tmp/.release-tags)
     echo "tag=$TAG" >> "$GITHUB_OUTPUT"
 ```
 
@@ -316,19 +305,20 @@ Or use the GitHub UI: Actions > Release > Run workflow.
 
 ## cliff.toml setup
 
-The package includes a `cliff.toml.template` with a generic git-cliff configuration that:
+The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order is:
+
+1. Explicit `cliffConfigPath` in `.config/release-kit.config.ts`
+2. `.config/git-cliff.toml`
+3. `cliff.toml` (repo root)
+4. Bundled `cliff.toml.template` (automatic fallback)
+
+The bundled template provides a generic git-cliff configuration that:
 
 - Strips issue-ticket prefixes matching `^[A-Z]+-\d+\s+` (e.g., `TOOL-123 `, `AFG-456 `)
 - Handles both `type: description` and `workspace|type: description` commit formats
 - Groups commits by work type into changelog sections
 
-Copy it to your repo root:
-
-```bash
-cp node_modules/@williamthorsen/release-kit/cliff.toml.template cliff.toml
-```
-
-Then customize as needed for your project.
+To customize, scaffold a local copy with `release-kit init --with-config` and edit `.config/git-cliff.toml`.
 
 ## External dependencies
 
@@ -386,5 +376,6 @@ If your format command does not accept file arguments, update it to one that doe
 3. Delete the `.changeset/` directory.
 4. Run `npx @williamthorsen/release-kit init` to scaffold workflow and config files.
 5. Remove `changeset:*` scripts from `package.json` (no replacement needed — the CLI handles everything).
-6. Copy `cliff.toml.template` to your repo root as `cliff.toml` (if `init` didn't create one).
-7. Create an initial version tag for each package (e.g., `git tag v1.0.0` or `git tag arrays-v1.0.0`).
+6. Create an initial version tag for each package (e.g., `git tag v1.0.0` or `git tag arrays-v1.0.0`).
+
+No cliff config copy is needed — the bundled template is used automatically. To customize, run `release-kit init --with-config`.

package/bin/release-kit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/esm/bin/release-kit.js');

package/dist/esm/.cache

@@ -1 +1 @@
-f3265b81405ed17fde593f32d16e47fc2fc43f6a87805009ff7d808d5c61a2af
+a59da8f9c8d7a95b776af266dfb8998307bdabf5e0cb68c9ca2a17b9655a5524

package/dist/esm/bin/release-kit.js

@@ -1,29 +1,87 @@
 #!/usr/bin/env node
 import { initCommand } from "../init/initCommand.js";
 import { prepareCommand } from "../prepareCommand.js";
+import { publishCommand } from "../publishCommand.js";
+import { generateCommand } from "../sync-labels/generateCommand.js";
+import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
+import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
+import { tagCommand } from "../tagCommand.js";
 function showUsage() {
   console.info(`
 Usage: release-kit <command> [options]
 
 Commands:
   prepare       Run release preparation (auto-discovers workspaces)
+  tag           Create annotated git tags from the tags file
+  publish       Publish packages with release tags on HEAD
   init          Initialize release-kit in the current repository
+  sync-labels   Manage GitHub label synchronization
 
 Options:
   --dry-run     Preview changes without writing files
   --help, -h    Show this help message
 `);
 }
+function showSyncLabelsHelp() {
+  console.info(`
+Usage: release-kit sync-labels <subcommand> [options]
+
+Manage GitHub label synchronization via preset and custom label definitions.
+
+Subcommands:
+  init          Scaffold caller workflow and config, then generate labels
+  generate      Regenerate .github/labels.yaml from config
+  sync          Trigger the sync-labels workflow via gh CLI
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showSyncLabelsInitHelp() {
+  console.info(`
+Usage: release-kit sync-labels init [options]
+
+Scaffold the sync-labels caller workflow and config file, auto-discover workspaces
+for scope labels, then generate .github/labels.yaml.
+
+Options:
+  --dry-run     Preview changes without writing files
+  --force       Overwrite existing files instead of skipping them
+  --help, -h    Show this help message
+`);
+}
+function showSyncLabelsGenerateHelp() {
+  console.info(`
+Usage: release-kit sync-labels generate
+
+Regenerate .github/labels.yaml from .config/sync-labels.config.ts.
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+function showSyncLabelsSyncHelp() {
+  console.info(`
+Usage: release-kit sync-labels sync
+
+Trigger the sync-labels GitHub Actions workflow via the gh CLI.
+
+Options:
+  --help, -h    Show this help message
+`);
+}
 function showInitHelp() {
   console.info(`
 Usage: release-kit init [options]
 
 Initialize release-kit in the current repository.
-Scaffolds workflow and config files.
+By default, scaffolds only the GitHub Actions workflow file.
 
 Options:
-  --dry-run     Preview changes without writing files
-  --help, -h    Show this help message
+  --with-config   Also scaffold .config/release-kit.config.ts and .config/git-cliff.toml
+  --force         Overwrite existing files instead of skipping them
+  --dry-run       Preview changes without writing files
+  --help, -h      Show this help message
 `);
 }
 function showPrepareHelp() {
@@ -39,6 +97,31 @@ Options:
   --help, -h            Show this help message
 `);
 }
+function showTagHelp() {
+  console.info(`
+Usage: release-kit tag [options]
+
+Create annotated git tags from the tags file produced by \`prepare\`.
+
+Options:
+  --dry-run          Preview without creating tags
+  --no-git-checks    Skip dirty working tree check
+  --help, -h         Show this help message
+`);
+}
+function showPublishHelp() {
+  console.info(`
+Usage: release-kit publish [options]
+
+Publish packages that have release tags on HEAD.
+
+Options:
+  --dry-run              Preview without publishing
+  --no-git-checks        Skip git checks (pnpm only)
+  --only=name1,name2     Only publish the named packages (comma-separated, monorepo only)
+  --help, -h             Show this help message
+`);
+}
 const args = process.argv.slice(2);
 const command = args[0];
 const flags = args.slice(1);
@@ -54,20 +137,90 @@ if (command === "prepare") {
   await prepareCommand(flags);
   process.exit(0);
 }
+if (command === "tag") {
+  if (flags.some((f) => f === "--help" || f === "-h")) {
+    showTagHelp();
+    process.exit(0);
+  }
+  tagCommand(flags);
+  process.exit(0);
+}
+if (command === "publish") {
+  if (flags.some((f) => f === "--help" || f === "-h")) {
+    showPublishHelp();
+    process.exit(0);
+  }
+  await publishCommand(flags);
+  process.exit(0);
+}
 if (command === "init") {
   if (flags.some((f) => f === "--help" || f === "-h")) {
     showInitHelp();
     process.exit(0);
   }
-  const unknownFlags = flags.filter((f) => f !== "--dry-run" && f !== "--help" && f !== "-h");
+  const knownInitFlags = /* @__PURE__ */ new Set(["--dry-run", "--force", "--with-config", "--help", "-h"]);
+  const unknownFlags = flags.filter((f) => !knownInitFlags.has(f));
   if (unknownFlags.length > 0) {
     console.error(`Error: Unknown option: ${unknownFlags[0]}`);
     process.exit(1);
   }
   const dryRun = flags.includes("--dry-run");
-  const exitCode = await initCommand({ dryRun });
+  const force = flags.includes("--force");
+  const withConfig = flags.includes("--with-config");
+  const exitCode = initCommand({ dryRun, force, withConfig });
   process.exit(exitCode);
 }
+if (command === "sync-labels") {
+  const subcommand = flags[0];
+  const subflags = flags.slice(1);
+  if (subcommand === "--help" || subcommand === "-h" || subcommand === void 0) {
+    showSyncLabelsHelp();
+    process.exit(0);
+  }
+  if (subcommand === "init") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showSyncLabelsInitHelp();
+      process.exit(0);
+    }
+    const knownFlags = /* @__PURE__ */ new Set(["--dry-run", "--force", "--help", "-h"]);
+    const unknownFlags = subflags.filter((f) => !knownFlags.has(f));
+    if (unknownFlags.length > 0) {
+      console.error(`Error: Unknown option: ${unknownFlags[0]}`);
+      process.exit(1);
+    }
+    const dryRun = subflags.includes("--dry-run");
+    const force = subflags.includes("--force");
+    const exitCode = await syncLabelsInitCommand({ dryRun, force });
+    process.exit(exitCode);
+  }
+  if (subcommand === "generate") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showSyncLabelsGenerateHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const exitCode = await generateCommand();
+    process.exit(exitCode);
+  }
+  if (subcommand === "sync") {
+    if (subflags.some((f) => f === "--help" || f === "-h")) {
+      showSyncLabelsSyncHelp();
+      process.exit(0);
+    }
+    if (subflags.length > 0) {
+      console.error(`Error: Unknown option: ${subflags[0]}`);
+      process.exit(1);
+    }
+    const exitCode = syncLabelsCommand();
+    process.exit(exitCode);
+  }
+  console.error(`Error: Unknown subcommand: ${subcommand}`);
+  showSyncLabelsHelp();
+  process.exit(1);
+}
 console.error(`Error: Unknown command: ${command}`);
 showUsage();
 process.exit(1);

package/dist/esm/bumpAllVersions.d.ts

@@ -1,2 +1,2 @@
-import type { ReleaseType } from './types.ts';
-export declare function bumpAllVersions(packageFiles: readonly string[], releaseType: ReleaseType, dryRun: boolean): string;
+import type { BumpResult, ReleaseType } from './types.ts';
+export declare function bumpAllVersions(packageFiles: readonly string[], releaseType: ReleaseType, dryRun: boolean): BumpResult;