@williamthorsen/release-kit 4.0.0 → 4.4.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [release-kit-v4.4.0] - 2026-04-04
+
+### Documentation
+
+- #135 release-kit|docs: Refine README to match preflight documentation standard (#138)
+
+Restructures the release-kit README to match the documentation standard established by the preflight README (#114). Reorders sections to follow the cross-package convention, converts CLI flag listings from code blocks to tables, adds representative `prepare --dry-run` output to the quick start, and condenses ~90 lines of inline workflow YAML into a summary with an inputs table and trigger examples. Fixes several accuracy gaps found by verifying documentation against source.
+
+### Features
+
+- #142 feat: Add --version flag to nmr and release-kit (#143)
+
+Adds `--version` / `-V` support to the `nmr` and `release-kit` CLIs, matching the existing `preflight` behavior. Moves the build-time version generation script to the shared `config/` directory so all three packages use a single `generateVersion.ts`.
+
+- #150 feat: Detect and report missing build output in bin wrappers (#152)
+
+Adds try/catch with `ERR_MODULE_NOT_FOUND` detection to all six bin wrappers across `nmr`, `preflight`, and `release-kit`. Previously, five of the six wrappers used bare `import()` calls that produced cryptic unhandled rejections when `dist/` was missing, and `preflight`'s existing try/catch gave no actionable guidance.
+
+### Refactoring
+
+- #88 release-kit|refactor: Extract deleteFileIfExists helper (#136)
+
+Replaces the duplicate `deleteTagsFile` and `deleteSummaryFile` functions in `createTags.ts` with a single parameterized `deleteFileIfExists(path)` utility. The new helper lives in its own module and is exported from the package barrel for reuse.
+
+- #145 refactor: Extract shared CLI argument-parsing utility into core (#151)
+
+Add a schema-driven `parseArgs` function to `@williamthorsen/node-monorepo-core` that handles boolean flags, string flags (both `--flag=value` and `--flag value`), short aliases, positional collection, the `--` delimiter, and unknown-flag errors. Migrate all CLI argument-parsing sites in preflight (3 sites) and release-kit (5 sites) to use it. A companion `translateParseError` helper normalizes internal error messages for consistent user-facing output.
+
+## [release-kit-v4.0.0] - 2026-04-02
+
+### Features
+
+- #125 feat: Rename reusable workflows to .reusable.yaml convention (#129)
+
+Renames all three reusable GitHub Actions workflow files from the inconsistent `-workflow.yaml`/bare `.yaml` convention to a uniform `.reusable.yaml` suffix. Updates all references across caller workflows, release-kit templates, tests, preflight collection, and documentation. Scaffolds the sync-labels caller workflow and labels file for this repo. Deletes superseded legacy files.
+
 ## [release-kit-v3.0.0] - 2026-03-29
 
 ### Bug fixes
@@ -48,6 +84,10 @@ Prevents `releasePrepareMono` and `releasePrepare` from silently skipping compon
 
 ### Features
 
+- #8 feat: Add shared writeFileWithCheck utility and overwrite reporting (#66)
+
+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.
+
 - #11 release-kit|feat: Separate tag-write errors from release preparation errors (#67)
 
 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.
@@ -112,8 +152,18 @@ Removes the ability to customize `tagPrefix` per component, enforcing the determ
 
 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.
 
+- #59 feat: Extract nmr CLI from core package (#61)
+
+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.
+
+Scopes: core, nmr
+
 ### Refactoring
 
+- #43 refactor: Replace dist bin targets with thin wrapper scripts (#48)
+
+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.
+
 - #53 release-kit|refactor: Separate presentation from logic in prepare workflow (#57)
 
 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`.

package/README.md

@@ -20,6 +20,36 @@ npx @williamthorsen/release-kit init
 npx @williamthorsen/release-kit prepare --dry-run
 ```
 
+Example output from `prepare --dry-run` in a monorepo:
+
+```
+🔍 DRY RUN — no files will be modified
+
+── arrays ──────────────────────────────────────
+  Found 4 commits since arrays-v1.2.0
+  Parsed 3 typed commits
+  Bumping versions (minor)...
+  📦 1.2.0 → 1.3.0 (minor)
+  [dry-run] Would bump packages/arrays/package.json
+  Generating changelogs...
+  [dry-run] Would run: npx --yes git-cliff ... --output packages/arrays/CHANGELOG.md
+  🏷️  arrays-v1.3.0
+
+── strings ─────────────────────────────────────
+  Found 2 commits since strings-v0.5.1
+  Parsed 2 typed commits
+  Bumping versions (patch)...
+  📦 0.5.1 → 0.5.2 (patch)
+  [dry-run] Would bump packages/strings/package.json
+  Generating changelogs...
+  [dry-run] Would run: npx --yes git-cliff ... --output packages/strings/CHANGELOG.md
+  🏷️  strings-v0.5.2
+
+✅ Release preparation complete.
+   🏷️  arrays-v1.3.0
+   🏷️  strings-v0.5.2
+```
+
 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
@@ -30,58 +60,20 @@ That's it for most repos. The CLI auto-discovers workspaces and applies sensible
 4. **Version bump + changelog**: bumps `package.json` versions and generates changelogs via `git-cliff`.
 5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
-## CLI reference
-
-### `release-kit prepare`
-
-Run release preparation with automatic workspace discovery.
-
-```
-Usage: release-kit prepare [options]
-
-Options:
-  --dry-run                   Preview changes without writing files
-  --bump=major|minor|patch    Override the bump type for all components
-  --only=name1,name2          Only process the named components (monorepo only)
-  --help, -h                  Show help
-```
-
-Component names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
-
-### `release-kit init`
-
-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:
-  --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:
-
-- `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
-- `.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`)
-
-### `release-kit sync-labels`
+## Commit format
 
-Manage GitHub label definitions via config-driven YAML files.
+release-kit parses commits in these formats:
 
 ```
-Usage: release-kit sync-labels <command> [options]
-
-Commands:
-  init        Scaffold sync-labels config and caller workflow
-  generate    Generate .github/labels.yaml from config
-  sync        Generate labels and push to GitHub (runs generate + gh label sync)
+type: description              # e.g., feat: add utility
+scope|type: description        # e.g., arrays|feat: add compact function
+type(scope): description       # e.g., feat(arrays): add compact function
+type!: description             # breaking change (triggers major bump)
+scope|type!: description       # scoped breaking change
+type(scope)!: description      # conventional scoped breaking change
 ```
 
-`init` scaffolds `.config/sync-labels.config.ts` with auto-detected workspace scope labels and a `.github/workflows/sync-labels.yaml` caller workflow. `generate` reads the config and writes `.github/labels.yaml`. `sync` runs `generate` and then applies labels to the GitHub repo.
+The `scope|type:` format scopes a commit to a specific component in a monorepo. Use `scopeAliases` in your config to map shorthand names to canonical scope names.
 
 ## Configuration
 
@@ -144,7 +136,7 @@ interface VersionPatterns {
 }
 ```
 
-Default: `{ major: ['!'], minor: ['feat', 'feature'] }`
+Default: `{ major: ['!'], minor: ['feat'] }`
 
 ### Default work types
 
@@ -163,151 +155,70 @@ Default: `{ major: ['!'], minor: ['feat', 'feature'] }`
 
 Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set.
 
-## Commit format
+## CLI reference
 
-release-kit parses commits in these formats:
+### Global options
 
-```
-type: description              # e.g., feat: add utility
-scope|type: description        # e.g., arrays|feat: add compact function
-type(scope): description       # e.g., feat(arrays): add compact function
-type!: description             # breaking change (triggers major bump)
-scope|type!: description       # scoped breaking change
-type(scope)!: description      # conventional scoped breaking change
-```
+| Flag              | Description         |
+| ----------------- | ------------------- |
+| `--help`, `-h`    | Show help message   |
+| `--version`, `-V` | Show version number |
 
-The `scope|type:` format scopes a commit to a specific component in a monorepo. Use `scopeAliases` in your config to map shorthand names to canonical scope names.
+### `release-kit prepare`
 
-## Using `component()` for manual configuration
+Run release preparation with automatic workspace discovery.
 
-If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `component()` helper creates a `ComponentConfig` from a workspace-relative path:
+| Flag                         | Description                                                      |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `--dry-run`                  | Preview changes without writing files                            |
+| `--bump=major\|minor\|patch` | Override the bump type for all components                        |
+| `--force`                    | Bypass the "no commits since last tag" check (requires `--bump`) |
+| `--only=name1,name2`         | Only process the named components (monorepo only)                |
+| `--help`, `-h`               | Show help                                                        |
 
-```typescript
-import { component } from '@williamthorsen/release-kit';
+Component names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
-// Accepts the full workspace-relative path
-component('packages/arrays');
-// => {
-//   dir: 'arrays',
-//   tagPrefix: 'arrays-v',
-//   packageFiles: ['packages/arrays/package.json'],
-//   changelogPaths: ['packages/arrays'],
-//   paths: ['packages/arrays/**'],
-// }
-```
+### `release-kit init`
 
-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.
+Initialize release-kit in the current repository. By default, scaffolds only the GitHub Actions workflow file. Use `--with-config` to also scaffold configuration files.
 
-## GitHub Actions workflow
+| Flag            | Description                                                                |
+| --------------- | -------------------------------------------------------------------------- |
+| `--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                                                                  |
 
-The `init` command scaffolds a workflow that delegates to a reusable release workflow. For repos that need a self-contained workflow:
-
-### Monorepo
-
-```yaml
-name: Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      only:
-        description: 'Components to release (comma-separated, leave empty for all)'
-        required: false
-        type: string
-      bump:
-        description: 'Override bump type (leave empty to auto-detect)'
-        required: false
-        type: choice
-        options:
-          - ''
-          - patch
-          - minor
-          - major
-
-permissions:
-  contents: write
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-
-      - name: Run release preparation
-        run: |
-          ARGS=""
-          if [ -n "${{ inputs.only }}" ]; then
-            ARGS="$ARGS --only=${{ inputs.only }}"
-          fi
-          if [ -n "${{ inputs.bump }}" ]; then
-            ARGS="$ARGS --bump=${{ inputs.bump }}"
-          fi
-          npx @williamthorsen/release-kit prepare $ARGS
-
-      - name: Check for changes
-        id: check
-        run: |
-          if git diff --quiet; then
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-            echo "No release-worthy changes found."
-          else
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Read release tags
-        if: steps.check.outputs.changed == 'true'
-        id: tags
-        run: |
-          TAGS=$(cat tmp/.release-tags | tr '\n' ' ')
-          echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
-          echo "Releasing: $TAGS"
-
-      - name: Commit, tag, and push
-        if: steps.check.outputs.changed == 'true'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add -A
-          git commit -m "release: ${{ steps.tags.outputs.tags }}"
-          for TAG in ${{ steps.tags.outputs.tags }}; do
-            git tag "$TAG"
-          done
-          git push origin main ${{ steps.tags.outputs.tags }}
-```
+Scaffolded files:
 
-### Single-package repo
+- `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
+- `.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`)
 
-The same workflow without the `only` input. Replace the prepare step with:
+### `release-kit sync-labels`
 
-```yaml
-- name: Run release preparation
-  run: |
-    ARGS=""
-    if [ -n "${{ inputs.bump }}" ]; then
-      ARGS="--bump=${{ inputs.bump }}"
-    fi
-    npx @williamthorsen/release-kit prepare $ARGS
-```
+Manage GitHub label definitions via config-driven YAML files.
 
-And the tag step with:
+| Subcommand | Description                                                    | Flags                  |
+| ---------- | -------------------------------------------------------------- | ---------------------- |
+| `init`     | Scaffold config, caller workflow, and generate labels          | `--dry-run`, `--force` |
+| `generate` | Regenerate `.github/labels.yaml` from config                   | —                      |
+| `sync`     | Trigger the `sync-labels` GitHub Actions workflow via `gh` CLI | —                      |
 
-```yaml
-- name: Read release tag
-  if: steps.check.outputs.changed == 'true'
-  id: tags
-  run: |
-    TAG=$(cat tmp/.release-tags)
-    echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-```
+`init` scaffolds `.config/sync-labels.config.ts` with auto-detected workspace scope labels and a `.github/workflows/sync-labels.yaml` caller workflow, then generates `.github/labels.yaml`. `generate` reads the config and writes `.github/labels.yaml`. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
+
+## GitHub Actions workflow
+
+The `init` command scaffolds a release workflow at `.github/workflows/release.yaml` that delegates to a reusable release workflow. The scaffolded workflow accepts these inputs:
+
+| Input  | Type   | Description                                                         |
+| ------ | ------ | ------------------------------------------------------------------- |
+| `only` | string | Components to release (comma-separated, leave empty for all)        |
+| `bump` | choice | Override bump type: `patch`, `minor`, `major` (empty = auto-detect) |
+
+For repos that need a self-contained workflow instead of the reusable one, the scaffolded file can be expanded. The key steps are: checkout with full history (`fetch-depth: 0`), run `release-kit prepare` with optional `--only` and `--bump` flags, check for changes, read tags from `tmp/.release-tags`, then commit, tag, and push.
 
-## Triggering a release
+### Triggering a release
 
 ```sh
 # All components
@@ -322,12 +233,14 @@ Or use the GitHub UI: Actions > Release > Run workflow.
 
 ## cliff.toml setup
 
-The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order is:
+The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order:
 
-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)
+| Priority | Path                          | Notes                                           |
+| -------- | ----------------------------- | ----------------------------------------------- |
+| 1        | `cliffConfigPath` in config   | Explicit path, returned without existence check |
+| 2        | `.config/git-cliff.toml`      | Project-level override                          |
+| 3        | `cliff.toml`                  | Repo root fallback                              |
+| 4        | Bundled `cliff.toml.template` | Automatic fallback                              |
 
 The bundled template provides a generic git-cliff configuration that:
 
@@ -344,6 +257,26 @@ This package shells out to two external tools:
 - **`git`** — must be available on `PATH`. Used to find tags and retrieve commit history.
 - **`git-cliff`** — automatically downloaded and cached via `npx` on first invocation. No need to install it as a dev dependency.
 
+## Using `component()` for manual configuration
+
+If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `component()` helper creates a `ComponentConfig` from a workspace-relative path:
+
+```typescript
+import { component } from '@williamthorsen/release-kit';
+
+// Accepts the full workspace-relative path
+component('packages/arrays');
+// => {
+//   dir: 'arrays',
+//   tagPrefix: 'arrays-v',
+//   packageFiles: ['packages/arrays/package.json'],
+//   changelogPaths: ['packages/arrays'],
+//   paths: ['packages/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.
+
 ## Legacy script-based approach
 
 The CLI-driven approach is recommended for new setups. The script-based approach (using `runReleasePrepare` with a manually maintained config) is still supported for backward compatibility.

package/bin/release-kit.js

@@ -1,2 +1,11 @@
 #!/usr/bin/env node
-import('../dist/esm/bin/release-kit.js');
+try {
+  await import('../dist/esm/bin/release-kit.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('release-kit: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`release-kit: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/.cache

@@ -1 +1 @@
-eda8d9c3d3574c46e1afbeccbda04ffac0675bd9d30270ab8644fc48477ace14
+89fa3a396cfa2f4f2cf5ce8827dbe171e310519ab3faa7325268a87693116335

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

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { parseArgs, translateParseError } from "@williamthorsen/node-monorepo-core";
 import { commitCommand } from "../commitCommand.js";
 import { initCommand } from "../init/initCommand.js";
 import { prepareCommand } from "../prepareCommand.js";
@@ -7,6 +8,7 @@ import { generateCommand } from "../sync-labels/generateCommand.js";
 import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
 import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { tagCommand } from "../tagCommand.js";
+import { VERSION } from "../version.js";
 function showUsage() {
   console.info(`
 Usage: release-kit <command> [options]
@@ -140,6 +142,10 @@ Options:
 const args = process.argv.slice(2);
 const command = args[0];
 const flags = args.slice(1);
+if (command === "--version" || command === "-V") {
+  console.info(VERSION);
+  process.exit(0);
+}
 if (command === "--help" || command === "-h" || command === void 0) {
   showUsage();
   process.exit(0);
@@ -186,15 +192,19 @@ if (command === "init") {
     showInitHelp();
     process.exit(0);
   }
-  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]}`);
+  const initFlagSchema = {
+    dryRun: { long: "--dry-run", type: "boolean" },
+    force: { long: "--force", type: "boolean" },
+    withConfig: { long: "--with-config", type: "boolean" }
+  };
+  let parsed;
+  try {
+    parsed = parseArgs(flags, initFlagSchema);
+  } catch (error) {
+    console.error(`Error: ${translateParseError(error)}`);
     process.exit(1);
   }
-  const dryRun = flags.includes("--dry-run");
-  const force = flags.includes("--force");
-  const withConfig = flags.includes("--with-config");
+  const { dryRun, force, withConfig } = parsed.flags;
   const exitCode = initCommand({ dryRun, force, withConfig });
   process.exit(exitCode);
 }
@@ -210,14 +220,18 @@ if (command === "sync-labels") {
       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]}`);
+    const syncLabelsInitFlagSchema = {
+      dryRun: { long: "--dry-run", type: "boolean" },
+      force: { long: "--force", type: "boolean" }
+    };
+    let syncParsed;
+    try {
+      syncParsed = parseArgs(subflags, syncLabelsInitFlagSchema);
+    } catch (error) {
+      console.error(`Error: ${translateParseError(error)}`);
       process.exit(1);
     }
-    const dryRun = subflags.includes("--dry-run");
-    const force = subflags.includes("--force");
+    const { dryRun, force } = syncParsed.flags;
     const exitCode = await syncLabelsInitCommand({ dryRun, force });
     process.exit(exitCode);
   }

package/dist/esm/commitCommand.js

@@ -1,14 +1,19 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { parseArgs, translateParseError } from "@williamthorsen/node-monorepo-core";
 import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./prepareCommand.js";
+const commitFlagSchema = {
+  dryRun: { long: "--dry-run", type: "boolean" }
+};
 function commitCommand(argv) {
-  const knownFlags = /* @__PURE__ */ new Set(["--dry-run"]);
-  const unknownFlags = argv.filter((f) => !knownFlags.has(f));
-  if (unknownFlags.length > 0) {
-    console.error(`Error: Unknown option: ${unknownFlags[0]}`);
+  let parsed;
+  try {
+    parsed = parseArgs(argv, commitFlagSchema);
+  } catch (error) {
+    console.error(`Error: ${translateParseError(error)}`);
     process.exit(1);
   }
-  const dryRun = argv.includes("--dry-run");
+  const dryRun = parsed.flags.dryRun;
   let tagsContent;
   try {
     tagsContent = readFileSync(RELEASE_TAGS_FILE, "utf8");

package/dist/esm/createTags.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { readFileSync, unlinkSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { deleteFileIfExists } from "./deleteFileIfExists.js";
 import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./prepareCommand.js";
 function createTags(options) {
   const { dryRun, noGitChecks } = options;
@@ -42,30 +43,10 @@ function createTags(options) {
   for (const tag of tags) {
     console.info(`\u{1F3F7}\uFE0F ${tag}`);
   }
-  deleteTagsFile();
-  deleteSummaryFile();
+  deleteFileIfExists(RELEASE_TAGS_FILE);
+  deleteFileIfExists(RELEASE_SUMMARY_FILE);
   return tags;
 }
-function deleteTagsFile() {
-  try {
-    unlinkSync(RELEASE_TAGS_FILE);
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return;
-    }
-    throw error;
-  }
-}
-function deleteSummaryFile() {
-  try {
-    unlinkSync(RELEASE_SUMMARY_FILE);
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return;
-    }
-    throw error;
-  }
-}
 function assertCleanWorkingTree() {
   try {
     execFileSync("git", ["diff", "--quiet"]);

package/dist/esm/deleteFileIfExists.d.ts

@@ -0,0 +1 @@
+export declare function deleteFileIfExists(filePath: string): void;

package/dist/esm/deleteFileIfExists.js

@@ -0,0 +1,14 @@
+import { unlinkSync } from "node:fs";
+function deleteFileIfExists(filePath) {
+  try {
+    unlinkSync(filePath);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+export {
+  deleteFileIfExists
+};

package/dist/esm/index.d.ts

@@ -13,6 +13,7 @@ export { bumpVersion } from './bumpVersion.ts';
 export { commitCommand } from './commitCommand.ts';
 export { component } from './component.ts';
 export { createTags } from './createTags.ts';
+export { deleteFileIfExists } from './deleteFileIfExists.ts';
 export { detectPackageManager } from './detectPackageManager.ts';
 export { determineBumpType } from './determineBumpType.ts';
 export { discoverWorkspaces } from './discoverWorkspaces.ts';

package/dist/esm/index.js

@@ -5,6 +5,7 @@ import { bumpVersion } from "./bumpVersion.js";
 import { commitCommand } from "./commitCommand.js";
 import { component } from "./component.js";
 import { createTags } from "./createTags.js";
+import { deleteFileIfExists } from "./deleteFileIfExists.js";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { determineBumpType } from "./determineBumpType.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
@@ -30,6 +31,7 @@ export {
   commitCommand,
   component,
   createTags,
+  deleteFileIfExists,
   detectPackageManager,
   determineBumpType,
   discoverWorkspaces,

package/dist/esm/prepareCommand.js

@@ -1,4 +1,8 @@
-import { writeFileWithCheck } from "@williamthorsen/node-monorepo-core";
+import {
+  parseArgs as coreParseArgs,
+  translateParseError,
+  writeFileWithCheck
+} from "@williamthorsen/node-monorepo-core";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
@@ -25,43 +29,40 @@ Options:
   --help                Show this help message
 `);
 }
+const prepareFlagSchema = {
+  dryRun: { long: "--dry-run", type: "boolean" },
+  force: { long: "--force", type: "boolean" },
+  bump: { long: "--bump", type: "string" },
+  only: { long: "--only", type: "string" },
+  help: { long: "--help", type: "boolean", short: "-h" }
+};
 function parseArgs(argv) {
-  let dryRun = false;
-  let force = false;
+  let parsed;
+  try {
+    parsed = coreParseArgs(argv, prepareFlagSchema);
+  } catch (error) {
+    throw new Error(translateParseError(error));
+  }
+  const { flags } = parsed;
+  if (flags.help) {
+    showHelp();
+    process.exit(0);
+  }
   let bumpOverride;
-  let only;
-  for (const arg of argv) {
-    if (arg === "--dry-run") {
-      dryRun = true;
-    } else if (arg === "--force") {
-      force = true;
-    } else if (arg.startsWith("--bump=")) {
-      const value = arg.slice("--bump=".length);
-      if (!isReleaseType(value)) {
-        console.error(`Error: Invalid bump type "${value}". Must be one of: ${VALID_BUMP_TYPES.join(", ")}`);
-        process.exit(1);
-      }
-      bumpOverride = value;
-    } else if (arg.startsWith("--only=")) {
-      const value = arg.slice("--only=".length);
-      if (!value) {
-        console.error("Error: --only requires a comma-separated list of component names");
-        process.exit(1);
-      }
-      only = value.split(",");
-    } else if (arg === "--help" || arg === "-h") {
-      showHelp();
-      process.exit(0);
-    } else {
-      console.error(`Error: Unknown argument: ${arg}`);
-      process.exit(1);
+  if (flags.bump !== void 0) {
+    if (!isReleaseType(flags.bump)) {
+      throw new Error(`Invalid bump type "${flags.bump}". Must be one of: ${VALID_BUMP_TYPES.join(", ")}`);
     }
+    bumpOverride = flags.bump;
   }
-  if (force && bumpOverride === void 0) {
-    console.error("Error: --force requires --bump to specify the version bump type");
-    process.exit(1);
+  let only;
+  if (flags.only !== void 0) {
+    only = flags.only.split(",");
+  }
+  if (flags.force && bumpOverride === void 0) {
+    throw new Error("--force requires --bump to specify the version bump type");
   }
-  return { dryRun, force, bumpOverride, only };
+  return { dryRun: flags.dryRun, force: flags.force, bumpOverride, only };
 }
 function writeReleaseTags(tags, dryRun) {
   if (tags.length === 0) {
@@ -70,7 +71,16 @@ function writeReleaseTags(tags, dryRun) {
   return writeFileWithCheck(RELEASE_TAGS_FILE, tags.join("\n"), { dryRun, overwrite: true });
 }
 async function prepareCommand(argv) {
-  const { dryRun, force, bumpOverride, only } = parseArgs(argv);
+  let dryRun;
+  let force;
+  let bumpOverride;
+  let only;
+  try {
+    ({ dryRun, force, bumpOverride, only } = parseArgs(argv));
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
   const options = {
     dryRun,
     force,

package/dist/esm/publishCommand.js

@@ -1,20 +1,25 @@
 import { basename } from "node:path";
+import { parseArgs, translateParseError } from "@williamthorsen/node-monorepo-core";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
 import { publish } from "./publish.js";
 import { resolveReleaseTags } from "./resolveReleaseTags.js";
+const publishFlagSchema = {
+  dryRun: { long: "--dry-run", type: "boolean" },
+  noGitChecks: { long: "--no-git-checks", type: "boolean" },
+  provenance: { long: "--provenance", type: "boolean" },
+  only: { long: "--only", type: "string" }
+};
 async function publishCommand(argv) {
-  const knownFlags = /* @__PURE__ */ new Set(["--dry-run", "--no-git-checks", "--provenance"]);
-  const unknownFlags = argv.filter((f) => !f.startsWith("--only=") && !knownFlags.has(f));
-  if (unknownFlags.length > 0) {
-    console.error(`Error: Unknown option: ${unknownFlags[0]}`);
+  let parsed;
+  try {
+    parsed = parseArgs(argv, publishFlagSchema);
+  } catch (error) {
+    console.error(`Error: ${translateParseError(error)}`);
     process.exit(1);
   }
-  const dryRun = argv.includes("--dry-run");
-  const noGitChecks = argv.includes("--no-git-checks");
-  const provenance = argv.includes("--provenance");
-  const onlyArg = argv.find((f) => f.startsWith("--only="));
-  const only = onlyArg?.slice("--only=".length).split(",");
+  const { dryRun, noGitChecks, provenance } = parsed.flags;
+  const only = parsed.flags.only?.split(",");
   let discoveredPaths;
   try {
     discoveredPaths = await discoverWorkspaces();

package/dist/esm/tagCommand.js

@@ -1,13 +1,18 @@
+import { parseArgs, translateParseError } from "@williamthorsen/node-monorepo-core";
 import { createTags } from "./createTags.js";
+const tagFlagSchema = {
+  dryRun: { long: "--dry-run", type: "boolean" },
+  noGitChecks: { long: "--no-git-checks", type: "boolean" }
+};
 function tagCommand(argv) {
-  const knownFlags = /* @__PURE__ */ new Set(["--dry-run", "--no-git-checks"]);
-  const unknownFlags = argv.filter((f) => !knownFlags.has(f));
-  if (unknownFlags.length > 0) {
-    console.error(`Error: Unknown option: ${unknownFlags[0]}`);
+  let parsed;
+  try {
+    parsed = parseArgs(argv, tagFlagSchema);
+  } catch (error) {
+    console.error(`Error: ${translateParseError(error)}`);
     process.exit(1);
   }
-  const dryRun = argv.includes("--dry-run");
-  const noGitChecks = argv.includes("--no-git-checks");
+  const { dryRun, noGitChecks } = parsed.flags;
   try {
     createTags({ dryRun, noGitChecks });
   } catch (error) {

package/dist/esm/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "4.4.0";

package/dist/esm/version.js

@@ -0,0 +1,4 @@
+const VERSION = "4.4.0";
+export {
+  VERSION
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "4.0.0",
+  "version": "4.4.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [],
   "homepage": "https://github.com/williamthorsen/node-monorepo-tools/tree/main/packages/release-kit#readme",
@@ -34,7 +34,7 @@
     "glob": "13.0.6",
     "jiti": "2.6.1",
     "js-yaml": "4.1.1",
-    "@williamthorsen/node-monorepo-core": "0.2.1"
+    "@williamthorsen/node-monorepo-core": "0.2.5"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",