@williamthorsen/release-kit 10.3.2 → 10.4.1

package/.readyup/kits/default.js

@@ -1,6 +1,6 @@
 /** @noformat — @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.27.0";
+export const __readyupVersion = "0.29.0";
 
 
 // .readyup/kits/default.ts
@@ -52,7 +52,7 @@ function detectRepoType() {
 
 // .readyup/kits/default.ts
 function getMinVersion() {
-  const picked = { "version": "10.3.2" };
+  const picked = { "version": "10.4.1" };
   if (typeof picked["version"] !== "string") {
     throw new TypeError("release-kit/package.json: 'version' must be a string");
   }

package/.readyup/kits/npm-auto-publish.js

@@ -1,6 +1,6 @@
 /** @noformat — @generated. Do not edit. Compiled by rdy. */
 /* eslint-disable */
-export const __readyupVersion = "0.27.0";
+export const __readyupVersion = "0.29.0";
 
 
 // .readyup/kits/npm-auto-publish.ts

package/.readyup/manifest.json

@@ -5,24 +5,63 @@
       "checklists": [
         "release-kit"
       ],
+      "esbuildVersion": "0.28.1",
+      "inputs": [
+        {
+          "hash": "fe239d01",
+          "kind": "module",
+          "path": "kits/default.ts"
+        },
+        {
+          "hash": "bbdcc849",
+          "kind": "inline",
+          "path": "../package.json",
+          "paths": [
+            "version"
+          ]
+        },
+        {
+          "hash": "850b703f",
+          "kind": "module",
+          "path": "../src/init/detectRepoType.ts"
+        },
+        {
+          "hash": "b6873aba",
+          "kind": "module",
+          "path": "../src/init/parseJsonRecord.ts"
+        },
+        {
+          "hash": "646fe51b",
+          "kind": "module",
+          "path": "../src/typeGuards.ts"
+        }
+      ],
       "name": "default",
       "path": "kits/default.js",
-      "readyupVersion": "0.27.0",
+      "readyupVersion": "0.29.0",
       "source": "kits/default.ts",
       "sourceHash": "fe239d01",
-      "targetHash": "6b363809"
+      "targetHash": "6ba7f24f"
     },
     {
       "checklists": [
         "repo",
         "packages"
       ],
+      "esbuildVersion": "0.28.1",
+      "inputs": [
+        {
+          "hash": "ac484613",
+          "kind": "module",
+          "path": "kits/npm-auto-publish.ts"
+        }
+      ],
       "name": "npm-auto-publish",
       "path": "kits/npm-auto-publish.js",
-      "readyupVersion": "0.27.0",
+      "readyupVersion": "0.29.0",
       "source": "kits/npm-auto-publish.ts",
       "sourceHash": "ac484613",
-      "targetHash": "2e324215"
+      "targetHash": "c7b01e0b"
     }
   ]
 }

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to this project will be documented in this file.
 
+## 10.4.1 — 2026-08-18
+
+### 🐛 Bug fixes
+
+- Accept `--only` under a project block, skipping the project release (#702)
+
+  Fixes an issue where `release-kit prepare --only` exited with an error in any repo whose config declares a `project` block, which left the `only` dispatch input that `release-kit init` scaffolds into `release.yaml` unusable. A narrowed run now releases the named workspaces and skips the project release, reporting the skip and the selection that caused it as a warning.
+
+- Route release-notes preview warnings through the prepare plan (#705)
+
+  Fixes an issue where `release-kit prepare --with-release-notes` printed its diagnostics to stderr ahead of the release report, and described a skipped release-notes preview as a skipped README injection. The messages now render as `⚠️` lines inside the report and are worded for release-notes previews; a skip belonging to one workspace names that workspace.
+
+## 10.4.0 — 2026-08-17
+
+### 🎉 Features
+
+- Let a project release cover repo-root paths (#685)
+
+  Extends `release-kit`'s project release to a repo whose content lives at the root. Such a repo declares `project: { paths: ['**'] }` and gets the root `CHANGELOG.md`, the root `.meta/changelog.json`, the `--with-release-notes` previews under root `docs/`, the root `package.json` bump, and the project tag that the stage produces.
+
+  `paths` scopes any project release's window, not only the whole-tree case, and the project tier of `release-kit validate-overrides` with it. A declared value replaces the workspace union rather than extending it; omitting `paths` resolves to that union, so existing consumers see no change.
+
+### ♻️ Refactoring
+
+- Adopt silenceConsole across the test suites (#677)
+
+  Adopts `silenceConsole` from `@williamthorsen/toolbelt.vitest` to replace all hand-rolled `vi.spyOn(console, …)` spies and reduce boilerplate across the repo's test suites. The function returns a disposable, allowing the caller to use `using` to enable restoration of the console method at the end of the test scope.
+
+- Adopt `isError` and consolidate errno narrowing on a shared helper (#697)
+
+  Replaces every hand-rolled `instanceof Error` narrowing with `hasErrnoCode`, a new predicate exported from `@williamthorsen/nmr-core`, or with `isError` from `@williamthorsen/toolbelt.errors`. Previously the errno question was answered by inline copies alongside two private helpers of differing shape; both helpers are removed.
+
+  Separately, `eslint.config.ts` now bans `instanceof Error` in every position rather than in a ternary alone.
+
+### 🧪 Tests
+
+- Replace the stdio spies with captureStdio (#678)
+
+  Replaces every `process.stdout` and `process.stderr` spy in the test suites with `captureStdio` from `@williamthorsen/toolbelt.testing` and deletes the obviated local capture helpers. `captureStdio` buffers writes rather than recording calls, so assertions that previously used `toHaveBeenCalledWith` instead check `stderr`/`stdout` strings and their chunk arrays.
+
+  Separately, `unicorn/no-nonstandard-builtin-properties` is off for test files. Its hand-maintained symbol table omits `Symbol.dispose`, which a suite-scoped capture calls to restore the streams, and `schema: []` offers no way to extend the table.
+
+- Adopt throwOnProcessExit and captureError across the test suites (#690)
+
+  Adopts `throwOnProcessExit` from `@williamthorsen/toolbelt.vitest`, replacing every hand-rolled `process.exit` mock in the `release-kit` and `nmr-core` test suites, and `captureError` from `@williamthorsen/toolbelt.testing`, replacing inline try/catch/`instanceof` blocks.
+
+  Separately, `@williamthorsen/toolbelt.vitest` is now listed in the ReadyUp config, so that its kit is run by `rdy run --packages`.
+
 ## 10.3.2 — 2026-08-13
 
 ### ♻️ Refactoring

package/README.md

@@ -4,7 +4,19 @@ Version-bumping and changelog-generation toolkit for release workflows.
 
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs from `git-cliff --context` output rendered in-process (with optional [editorial overrides](#editorial-overrides)).
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v10.4.1 (2026-08-18)
+
+### 🐛 Bug fixes
+
+- Accept `--only` under a project block, skipping the project release (#702)
+
+  Fixes an issue where `release-kit prepare --only` exited with an error in any repo whose config declares a `project` block, which left the `only` dispatch input that `release-kit init` scaffolds into `release.yaml` unusable. A narrowed run now releases the named workspaces and skips the project release, reporting the skip and the selection that caused it as a warning.
+
+- Route release-notes preview warnings through the prepare plan (#705)
+
+  Fixes an issue where `release-kit prepare --with-release-notes` printed its diagnostics to stderr ahead of the release report, and described a skipped release-notes preview as a skipped README injection. The messages now render as `⚠️` lines inside the report and are worded for release-notes previews; a skip belonging to one workspace names that workspace.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -201,33 +213,50 @@ export default config;
 
 When configured, each `release-kit prepare` run additionally:
 
-- Computes commits since the last project tag (`<tagPrefix><version>`), filtered to the union of every contributing workspace's paths.
+- Computes commits since the last project tag (`<tagPrefix><version>`), filtered to `paths` (by default, the union of every contributing workspace's paths).
 - Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
-- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and contributing paths) and any matching editorial overrides.
+- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
 - Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
 - With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
 - Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
 
-If no contributing workspace has commits since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+If no commit under `paths` has landed since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
 
 #### `ProjectConfig`
 
 ```typescript
 interface ProjectConfig {
+  paths?: string[]; // Defaults to the union of every contributing workspace's paths
   tagPrefix?: string; // Defaults to 'v'
 }
 ```
 
-| Field       | Default | Description                                                          |
-| ----------- | ------- | -------------------------------------------------------------------- |
-| `tagPrefix` | `'v'`   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+| Field       | Default                 | Description                                                          |
+| ----------- | ----------------------- | -------------------------------------------------------------------- |
+| `paths`     | Contributing-path union | Patterns selecting the commits the project release considers         |
+| `tagPrefix` | `'v'`                   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+
+By default the contributing workspaces are implicit: every non-excluded discovered workspace contributes its `<dir>/**` glob, and the project release considers commits under their union.
+
+Declare `paths` to choose the window yourself. Each entry reaches two matchers: `git log` as a pathspec, and `git-cliff --include-path` as a glob. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
+
+A repo whose content lives at the root — where no commit matches any `<dir>/**` glob, so the project release would skip every run — declares the whole tree:
+
+```typescript
+const config: ReleaseKitConfig = {
+  project: { paths: ['**'] },
+};
+```
+
+`'**'` is the whole-tree pattern, matching root-level files, dotfiles, and nested paths alike.
 
-Contributing workspaces are implicit: every non-excluded discovered workspace contributes. There is no field to override the contributing set in this initial release; if a future consumer needs to release a workspace as a component but exclude it from the project release, that override can be added then.
+Terminate a directory scope with `/**`. The two matchers agree on `'aws/**'` but diverge on a bare `'aws'`, which git reads as the whole subtree and git-cliff matches against nothing; `'.'` is the same trap for the repo root. A release under such an entry finds commits, bumps the version, and writes the tag, while its changelog gains no entry for them — and nothing reports an error.
 
 Validation rules:
 
 - The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
-- The `project` block is rejected in single-package mode (the implicit "all non-excluded workspaces contribute" rule is meaningless in a single-package repo).
+- The `project` block is rejected in single-package mode (the package's own release already covers the whole repo, so a project tier would only duplicate it).
+- `paths`, when declared, must hold at least one non-empty string. An empty array is rejected: it reaches git and git-cliff as no filter at all, which is the inverse of how it reads.
 - Unknown fields inside `project` are rejected.
 
 CLI flag interactions:
@@ -235,7 +264,7 @@ CLI flag interactions:
 - `--dry-run` previews project artifacts alongside workspace artifacts; no files are written.
 - `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when there are no commits or no bump-worthy commits.
 - `--force` runs the project release even when no commits or no bump-worthy commits exist since the last project tag. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
-- `--only` is rejected with an error when `project` is configured. `--only` is a surgical, single-workspace operation; combining it with a project release that rolls up every contributing workspace would create ambiguous semantics. To release a single workspace, use a config without a `project` block, or run a full `prepare` (no `--only`) to include the project release.
+- `--only` narrows the run to the named workspaces and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work the run excluded. Run a full `prepare` (no `--only`) to include the project release.
 - `--set-version` is rejected with an error when `project` is configured. `--set-version` operates on a single workspace, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
 
 `--bump` and `--force` are orthogonal: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
@@ -441,7 +470,7 @@ Per-entry fields are all optional, but at least one must be present per entry:
 Keys can be either the full 40-character commit SHA or a non-ambiguous prefix. The matcher walks every `ChangelogItem.hash` value present in the entry tree and resolves each override key to its set of matching hashes:
 
 - **Exact prefix match (1 hit)** — the override applies. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
-- **No matches (0 hits)** — the override is treated as a stale reference (probably from a rebase or branch deletion) and a warning is logged. The release continues.
+- **No matches (0 hits)** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues.
 - **Ambiguous prefix (2+ hits)** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
 
 Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
@@ -554,9 +583,9 @@ Run release preparation with automatic workspace discovery.
 | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--dry-run`                  | Preview changes without writing files                                                                                                                                                                                                                                   |
 | `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                                                                                                                                                                               |
-| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode (rejected when a `project` block is configured).                                                                                                            |
+| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. In monorepo mode it requires `--only`, and is rejected when a `project` block is configured.                                                                                                   |
 | `--force`                    | Release even when no commits or no bump-worthy commits exist since the last tag. In monorepo/project mode, defaults to patch (combine with `--bump=X` for a different level); in single-package mode, a bare `--force` is rejected — pass `--bump=major\|minor\|patch`. |
-| `--only=name1,name2`         | Only process the named workspaces (monorepo only; rejected when a `project` block is configured)                                                                                                                                                                        |
+| `--only=name1,name2`         | Only process the named workspaces (monorepo only). When a `project` block is configured, the project release is skipped.                                                                                                                                                |
 | `--with-release-notes`       | Write per-workspace release-notes previews under `<workspacePath>/docs/`                                                                                                                                                                                                |
 | `--help`, `-h`               | Show help                                                                                                                                                                                                                                                               |
 
@@ -569,7 +598,7 @@ Workspace names for `--only` match the package directory name (e.g., `arrays`, `
 - `<workspacePath>/docs/README.v<version>.md` — the workspace `README.md` with release notes injected at the `<!-- section:release-notes -->` marker.
 - `<workspacePath>/docs/RELEASE_NOTES.v<version>.md` — the standalone release notes for this version.
 
-The publish-time inject-and-revert lifecycle is unchanged; previews are additive, deterministic, and safe to regenerate. When `changelogJson.enabled` is `false`, the flag logs a warning and skips preview generation. In dry-run mode, planned writes are logged and no files are created.
+The publish-time inject-and-revert lifecycle is unchanged; previews are additive, deterministic, and safe to regenerate. When `changelogJson.enabled` is `false`, prepare reports a warning and skips preview generation. In dry-run mode, planned writes are logged and no files are created.
 
 Because preview filenames are versioned, committing them will accumulate files over time. The recommended `.gitignore` entry for monorepos is:
 

package/dist/esm/commitCommand.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { GIT_OUTPUT_LIMIT, parseArgsOrExit } from '@williamthorsen/nmr-core';
+import { GIT_OUTPUT_LIMIT, hasErrnoCode, parseArgsOrExit } from '@williamthorsen/nmr-core';
 import { readReleaseTags, RELEASE_SUMMARY_FILE, resolveReleaseTagsPath } from "./releaseFiles.js";
 const commitFlagSchema = {
     dryRun: { long: '--dry-run', type: 'boolean' },
@@ -16,7 +16,7 @@ export function commitCommand(argv) {
         summary = readFileSync(RELEASE_SUMMARY_FILE, 'utf8').trim();
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (hasErrnoCode(error, 'ENOENT')) {
         }
         else {
             throw error;

package/dist/esm/createTags.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+import { GIT_OUTPUT_LIMIT, hasErrnoCode } from '@williamthorsen/nmr-core';
 import { deleteFileIfExists } from "./deleteFileIfExists.js";
 import { readReleaseTags, RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
 export function createTags(options) {
@@ -48,7 +48,7 @@ function assertCleanWorkingTree() {
         execFileSync('git', ['diff', '--quiet', '--cached'], { maxBuffer: GIT_OUTPUT_LIMIT });
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (hasErrnoCode(error, 'ENOENT')) {
             throw error;
         }
         throw new Error('Working tree is dirty. Commit or stash changes before tagging, or use `--no-git-checks` to skip this check.', { cause: error });

package/dist/esm/deleteFileIfExists.js

@@ -1,10 +1,11 @@
 import { unlinkSync } from 'node:fs';
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
 export function deleteFileIfExists(filePath) {
     try {
         unlinkSync(filePath);
     }
     catch (error) {
-        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        if (hasErrnoCode(error, 'ENOENT')) {
             return;
         }
         throw error;

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

@@ -1,2 +1,2 @@
-export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Override the bump type for all workspaces\n  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps.\n                         Requires --only in monorepo mode (rejected when a 'project' block is configured).\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. In monorepo and project mode, defaults to\n                         patch when --bump is not given; use --bump=X for a different\n                         level. In single-package mode, a bare --force is rejected \u2014\n                         pass --bump=major|minor|patch.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only;\n                         rejected when a 'project' block is configured)\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Override the bump type for all workspaces\n  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. In monorepo and project mode, defaults to\n                         patch when --bump is not given; use --bump=X for a different\n                         level. In single-package mode, a bare --force is rejected \u2014\n                         pass --bump=major|minor|patch.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
 export declare function showPrepareHelp(): void;

package/dist/esm/help/prepareHelp.js

@@ -6,16 +6,16 @@ Run release preparation with automatic workspace discovery.
 Options:
   --dry-run             Run without modifying any files
   --bump=major|minor|patch  Override the bump type for all workspaces
-  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps.
-                         Requires --only in monorepo mode (rejected when a 'project' block is configured).
+  --set-version=X.Y.Z   Set an explicit version; bypasses commit-derived bumps. In monorepo
+                         mode it requires --only, and is rejected when a 'project' block is configured.
   --force               Release even when no commits or no bump-worthy commits exist
                          since the last tag. In monorepo and project mode, defaults to
                          patch when --bump is not given; use --bump=X for a different
                          level. In single-package mode, a bare --force is rejected —
                          pass --bump=major|minor|patch.
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only;
-                         rejected when a 'project' block is configured)
+  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).
+                         When a 'project' block is configured, the project release is skipped.
   --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/
                          (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).
                          Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).

package/dist/esm/injectReleaseNotesIntoReadme.d.ts

@@ -3,7 +3,16 @@ export interface RenderedInjectedReadme {
     injectedReadme: string;
     releaseNotesMarkdown: string;
 }
-export declare function renderInjectedReadmeFromEntries(readme: string, entries: readonly ChangelogEntry[], tag: string, sectionOrder?: string[]): RenderedInjectedReadme | undefined;
+export type RenderInjectedReadmeSkipReason = 'no-entry' | 'empty-body';
+export type RenderInjectedReadmeResult = {
+    status: 'rendered';
+    rendered: RenderedInjectedReadme;
+} | {
+    status: 'skipped';
+    reason: RenderInjectedReadmeSkipReason;
+    version: string;
+};
+export declare function renderInjectedReadmeFromEntries(readme: string, entries: readonly ChangelogEntry[], tag: string, sectionOrder?: string[]): RenderInjectedReadmeResult;
 export declare function renderInjectedReadme(readme: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): RenderedInjectedReadme | undefined;
 export declare function injectReleaseNotesIntoReadme(readmePath: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): string | undefined;
 export declare function resolveReadmePath(workspacePath: string): string | undefined;

package/dist/esm/injectReleaseNotesIntoReadme.js

@@ -7,8 +7,7 @@ export function renderInjectedReadmeFromEntries(readme, entries, tag, sectionOrd
     const version = extractVersion(tag);
     const entry = entries.find((e) => e.version === version);
     if (entry === undefined) {
-        console.warn(`Warning: no changelog entry for version ${version}; skipping README injection`);
-        return undefined;
+        return { status: 'skipped', reason: 'no-entry', version };
     }
     const renderedSections = renderReleaseNotesSingle(entry, {
         filter: matchesAudience('all'),
@@ -16,13 +15,12 @@ export function renderInjectedReadmeFromEntries(readme, entries, tag, sectionOrd
         ...(sectionOrder !== undefined && { sectionOrder }),
     });
     if (renderedSections.trimEnd().length === 0) {
-        console.warn(`Warning: no user-facing release notes for version ${version}; skipping README injection`);
-        return undefined;
+        return { status: 'skipped', reason: 'empty-body', version };
     }
     const labeledHeading = `## Release notes — v${version} (${entry.date})`;
     const releaseNotesMarkdown = `${labeledHeading}\n\n${renderedSections.trimEnd()}`;
     const injectedReadme = injectSection(readme, 'release-notes', releaseNotesMarkdown);
-    return { injectedReadme, releaseNotesMarkdown };
+    return { status: 'rendered', rendered: { injectedReadme, releaseNotesMarkdown } };
 }
 export function renderInjectedReadme(readme, changelogJsonPath, tag, sectionOrder) {
     if (!existsSync(changelogJsonPath)) {
@@ -34,7 +32,12 @@ export function renderInjectedReadme(readme, changelogJsonPath, tag, sectionOrde
         console.warn(`Warning: could not parse ${changelogJsonPath}; skipping README injection`);
         return undefined;
     }
-    return renderInjectedReadmeFromEntries(readme, entries, tag, sectionOrder);
+    const result = renderInjectedReadmeFromEntries(readme, entries, tag, sectionOrder);
+    if (result.status === 'skipped') {
+        console.warn(`Warning: ${describeRenderSkip(result.reason, result.version)}; skipping README injection`);
+        return undefined;
+    }
+    return result.rendered;
 }
 export function injectReleaseNotesIntoReadme(readmePath, changelogJsonPath, tag, sectionOrder) {
     const originalReadme = readFileSync(readmePath, 'utf8');
@@ -49,3 +52,8 @@ export function resolveReadmePath(workspacePath) {
     const readmePath = join(workspacePath, 'README.md');
     return existsSync(readmePath) ? readmePath : undefined;
 }
+function describeRenderSkip(reason, version) {
+    return reason === 'no-entry'
+        ? `no changelog entry for version ${version}`
+        : `no user-facing release notes for version ${version}`;
+}

package/dist/esm/loadConfig.js

@@ -73,7 +73,7 @@ export function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
     if (userConfig?.retiredPackages !== undefined) {
         assertRetiredPackagesDoNotCollideWithActive(workspaces, userConfig.retiredPackages);
     }
-    const project = resolveProjectConfig(userConfig?.project, rootPackage);
+    const project = resolveProjectConfig(userConfig?.project, rootPackage, workspaces);
     const workTypes = resolveWorkTypes(userConfig?.workTypes);
     const versionPatterns = userConfig?.versionPatterns === undefined ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
     const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
@@ -161,7 +161,7 @@ function assertRetiredPackagesDoNotCollideWithActive(workspaces, retiredPackages
         }
     }
 }
-function resolveProjectConfig(userProject, rootPackage) {
+function resolveProjectConfig(userProject, rootPackage, workspaces) {
     if (userProject === undefined) {
         return undefined;
     }
@@ -171,7 +171,10 @@ function resolveProjectConfig(userProject, rootPackage) {
     if (rootPackage.version === undefined) {
         throw new Error(`project block requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to your root package.json`);
     }
-    return { tagPrefix: userProject.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX };
+    return {
+        paths: userProject.paths ?? workspaces.flatMap((workspace) => workspace.paths),
+        tagPrefix: userProject.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX,
+    };
 }
 function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
     const sources = [];

package/dist/esm/planReleaseNotesPreviews.js

@@ -2,16 +2,18 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { extractVersion } from "./changelogJsonUtils.js";
-import { renderInjectedReadmeFromEntries } from "./injectReleaseNotesIntoReadme.js";
+import { renderInjectedReadmeFromEntries, } from "./injectReleaseNotesIntoReadme.js";
 export function planReleaseNotesPreviews(options) {
     const { workspacePath, tag, entries, sectionOrder } = options;
     const warnings = [];
     const readmePath = path.join(workspacePath, 'README.md');
     const readme = readWorkspaceReadme(readmePath, warnings);
-    const rendered = renderInjectedReadmeFromEntries(readme.content, entries, tag, sectionOrder);
-    if (rendered === undefined) {
+    const result = renderInjectedReadmeFromEntries(readme.content, entries, tag, sectionOrder);
+    if (result.status === 'skipped') {
+        warnings.push(describePreviewSkip(workspacePath, result.reason, result.version));
         return { writes: [], warnings };
     }
+    const { rendered } = result;
     if (!readme.exists && !readme.unreadable) {
         warnings.push(`${readmePath} not found; skipping injected-README preview but still writing standalone release notes`);
     }
@@ -29,6 +31,12 @@ export function planReleaseNotesPreviews(options) {
     });
     return { writes, warnings };
 }
+function describePreviewSkip(workspacePath, reason, version) {
+    const cause = reason === 'no-entry'
+        ? `no changelog entry for version ${version}`
+        : `no user-facing release notes for version ${version}`;
+    return `${workspacePath}: ${cause}; skipping release-notes previews`;
+}
 function readWorkspaceReadme(readmePath, warnings) {
     if (!existsSync(readmePath)) {
         return { content: '', exists: false, unreadable: false };

package/dist/esm/prepareCommand.js

@@ -137,12 +137,6 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             'contributing workspace. To use --set-version, run on a config without a `project` block.');
         process.exit(1);
     }
-    if (only !== undefined && config.project !== undefined) {
-        reportError('--only cannot be combined with a project release. ' +
-            'To release a single workspace, use a config without a `project` block, ' +
-            'or run a full `prepare` (no --only) to include the project release.');
-        process.exit(1);
-    }
     if (only !== undefined) {
         const knownNames = config.workspaces.map((w) => w.dir);
         for (const name of only) {
@@ -183,7 +177,7 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
             process.exit(1);
         }
     }
-    runAndReport(() => releasePrepareMono(config, options), dryRun);
+    runAndReport(() => releasePrepareMono(config, { ...options, ...(only !== undefined && { only }) }), dryRun);
 }
 async function loadAndValidateConfig() {
     let rawConfig;

package/dist/esm/releaseFiles.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 export const RELEASE_TAGS_FILE = 'tmp/.release-tags';
 export const RELEASE_SUMMARY_FILE = 'tmp/.release-summary';
@@ -21,15 +22,9 @@ export function readReleaseTags() {
 }
 function describeTagsReadFailure(error) {
     const tagsPath = resolveReleaseTagsPath();
-    if (getErrnoCode(error) === 'ENOENT') {
+    if (hasErrnoCode(error, 'ENOENT')) {
         return `No tags file found at ${tagsPath}. Run \`release-kit prepare\` first.`;
     }
     const detail = describeError(error);
     return `Cannot read the tags file at ${tagsPath}: ${detail}`;
 }
-function getErrnoCode(error) {
-    if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
-        return error.code;
-    }
-    return undefined;
-}

package/dist/esm/releasePrepare.d.ts

@@ -4,6 +4,7 @@ export interface ReleasePrepareOptions {
     force?: boolean;
     bumpOverride?: ReleaseType;
     setVersion?: string;
+    only?: string[];
     withReleaseNotes?: boolean;
 }
 export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): ReleasePlan;

package/dist/esm/releasePrepare.js

@@ -83,17 +83,17 @@ export function releasePrepare(config, options) {
     }
     writes.push(...bump.writes);
     const newTag = `${config.tagPrefix}${bump.newVersion}`;
-    const overrideWarnings = [];
+    const planWarnings = [];
     const changelogs = planSinglePackageChangelogs({
         config,
         commits,
         newTag,
         newVersion: bump.newVersion,
         overrides,
-        overrideWarnings,
+        overrideWarnings: planWarnings,
     });
     const { changelogFiles, changelogJsonFiles } = changelogs;
-    const previewWrites = planSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogs.entries, overrideWarnings);
+    const previewWrites = planSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogs.entries, planWarnings);
     writes.push(...changelogs.writes, ...previewWrites);
     const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? 'npx prettier --write' : undefined);
     let formatCommand;
@@ -125,8 +125,8 @@ export function releasePrepare(config, options) {
         summary: buildReleaseSummary({ workspaces: [released] }),
         formatCommand,
     };
-    if (overrideWarnings.length > 0) {
-        plan.warnings = overrideWarnings;
+    if (planWarnings.length > 0) {
+        plan.warnings = planWarnings;
     }
     return plan;
 }
@@ -229,7 +229,7 @@ function planSinglePackagePreviews(withReleaseNotes, config, newTag, entries, wa
         return [];
     }
     if (!config.changelogJson.enabled) {
-        console.warn('Warning: --with-release-notes requires changelogJson.enabled; skipping preview generation');
+        warnings.push('--with-release-notes requires changelogJson.enabled; skipping preview generation');
         return [];
     }
     if (config.changelogPaths.length === 0) {

package/dist/esm/releasePrepareMono.js

@@ -25,10 +25,11 @@ import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 import { refreshGitCliffCache } from "./runGitCliff.js";
 export function releasePrepareMono(config, options) {
-    const { withReleaseNotes } = options;
+    const { only, withReleaseNotes } = options;
     const writes = [];
+    const warnings = [];
     if (withReleaseNotes === true && !config.changelogJson.enabled) {
-        console.warn('Warning: --with-release-notes requires changelogJson.enabled; skipping preview generation');
+        warnings.push('--with-release-notes requires changelogJson.enabled; skipping preview generation');
     }
     const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
     const overrideContext = createOverrideContext(config.workspaces);
@@ -43,7 +44,6 @@ export function releasePrepareMono(config, options) {
     const graph = buildDependencyGraph(config.workspaces);
     const fullReleaseSet = propagateBumps(directBumps, graph, currentVersions);
     const { sorted: sortedDirs, cyclicDirs } = topologicalSort(fullReleaseSet, graph);
-    const warnings = [];
     if (cyclicDirs.length > 0) {
         warnings.push(`Circular workspace dependencies detected among: ${cyclicDirs.join(', ')}. ` +
             'Propagation metadata may be incomplete for these workspaces.');
@@ -77,17 +77,23 @@ export function releasePrepareMono(config, options) {
     });
     let project;
     if (config.project !== undefined) {
-        project = tryStage('project release stage', () => releasePrepareProject({
-            config,
-            options,
-            modifiedFiles,
-            writes,
-            tags,
-            warnings,
-            rootOverrides: overrideContext.project,
-            overrideWarnings: overrideContext.overrideWarnings,
-            globalMatchedRootKeys: overrideContext.globalMatchedRootKeys,
-        }));
+        if (only === undefined) {
+            project = tryStage('project release stage', () => releasePrepareProject({
+                config,
+                options,
+                modifiedFiles,
+                writes,
+                tags,
+                warnings,
+                rootOverrides: overrideContext.project,
+                overrideWarnings: overrideContext.overrideWarnings,
+                globalMatchedRootKeys: overrideContext.globalMatchedRootKeys,
+            }));
+        }
+        else {
+            warnings.push(`Project release skipped: --only narrows this run to ${only.join(', ')}. ` +
+                'Run `release-kit prepare` without --only to include the project release.');
+        }
     }
     const formatCommand = planFormatCommand(config, tags, modifiedFiles);
     for (const overrideKey of overrideContext.project.keys()) {

package/dist/esm/releasePrepareProject.js

@@ -25,7 +25,7 @@ export function releasePrepareProject(args) {
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
     const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
     const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
-    const contributingPaths = config.workspaces.flatMap((workspace) => workspace.paths);
+    const contributingPaths = project.paths;
     const { tag, commits } = getCommitsSinceTarget([project.tagPrefix], contributingPaths);
     const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
     const collector = createPolicyViolationCollector();

package/dist/esm/reportPrepare.js

@@ -22,6 +22,7 @@ function formatSingleWorkspace(result, options) {
     formatPolicyViolations(lines, workspace.policyViolations);
     if (workspace.status === 'skipped') {
         lines.push(`⏭️  ${workspace.skipReason}`);
+        formatWarnings(lines, result);
         return lines.join('\n');
     }
     if (workspace.setVersion !== undefined) {

package/dist/esm/types.d.ts

@@ -33,6 +33,7 @@ export interface ReleaseNotesConfig {
     shouldInjectIntoReadme: boolean;
 }
 export interface ResolvedProjectConfig {
+    paths: string[];
     tagPrefix: string;
 }
 export interface PropagationSource {
@@ -142,6 +143,7 @@ export declare const workspaceOverrideSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type WorkspaceOverride = z.infer<typeof workspaceOverrideSchema>;
 export declare const projectConfigSchema: z.ZodObject<{
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tagPrefix: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type ProjectConfig = z.infer<typeof projectConfigSchema>;
@@ -193,6 +195,7 @@ export declare const releaseKitConfigSchema: z.ZodObject<{
     cliffConfigPath: z.ZodOptional<z.ZodString>;
     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<{

package/dist/esm/types.js

@@ -21,6 +21,7 @@ export const workspaceOverrideSchema = z
     .strict();
 export const projectConfigSchema = z
     .object({
+    paths: z.array(z.string().min(1)).min(1).optional(),
     tagPrefix: z.string().min(1).optional(),
 })
     .strict();

package/dist/esm/validateOverridesCommand.js

@@ -126,9 +126,8 @@ function buildMonorepoInputs(discoveredPaths, userConfig, buildEntries) {
         filePath: resolveOverridePath('.'),
     };
     if (project !== undefined) {
-        const contributingPaths = config.workspaces.flatMap((workspace) => workspace.paths);
         const projectTagPattern = buildTagPattern([project.tagPrefix]);
-        projectScope.hashes = flattenEntriesToHashes(buildEntries(config, projectTagPattern, contributingPaths));
+        projectScope.hashes = flattenEntriesToHashes(buildEntries(config, projectTagPattern, project.paths));
     }
     return { project: projectScope, workspaces };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "10.3.2",
+  "version": "10.4.1",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -48,17 +48,19 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.4.0",
+    "@williamthorsen/toolbelt.errors": "0.5.0",
     "glob": "13.0.6",
     "json-stringify-pretty-compact": "4.0.0",
     "semver": "7.8.5",
     "yaml": "2.9.0",
     "zod": "4.4.3",
-    "@williamthorsen/nmr-core": "0.10.0"
+    "@williamthorsen/nmr-core": "0.10.1"
   },
   "devDependencies": {
     "@types/semver": "7.8.0",
-    "readyup": "0.27.0",
+    "@williamthorsen/toolbelt.testing": "0.3.0",
+    "@williamthorsen/toolbelt.vitest": "0.4.0",
+    "readyup": "0.29.0",
     "smol-toml": "1.7.1"
   },
   "engines": {