@williamthorsen/release-kit 5.0.0 → 5.1.0

package/dist/esm/decideRelease.d.ts

@@ -0,0 +1,25 @@
+import type { Commit, ReleaseType, VersionPatterns, WorkTypeConfig } from './types.ts';
+export interface DecideReleaseArgs {
+    commits: readonly Commit[];
+    force?: boolean | undefined;
+    bumpOverride: ReleaseType | undefined;
+    workTypes: Record<string, WorkTypeConfig>;
+    versionPatterns: VersionPatterns;
+    scopeAliases: Record<string, string> | undefined;
+    skipReasons: {
+        noCommits: string;
+        noBumpWorthy: string;
+    };
+}
+export type DecideReleaseResult = {
+    outcome: 'release';
+    releaseType: ReleaseType;
+    parsedCommitCount: number;
+    unparseableCommits: Commit[] | undefined;
+} | {
+    outcome: 'skip';
+    skipReason: string;
+    parsedCommitCount: number;
+    unparseableCommits: Commit[] | undefined;
+};
+export declare function decideRelease(args: DecideReleaseArgs): DecideReleaseResult;

package/dist/esm/decideRelease.js

@@ -0,0 +1,28 @@
+import { determineBumpType } from "./determineBumpType.js";
+import { parseCommitMessage } from "./parseCommitMessage.js";
+function decideRelease(args) {
+  const { commits, force = false, bumpOverride, workTypes, versionPatterns, scopeAliases, skipReasons } = args;
+  const parsedCommits = [];
+  const unparseable = [];
+  for (const commit of commits) {
+    const parsed = parseCommitMessage(commit.message, commit.hash, workTypes, scopeAliases);
+    if (parsed === void 0) {
+      unparseable.push(commit);
+    } else {
+      parsedCommits.push(parsed);
+    }
+  }
+  const parsedCommitCount = parsedCommits.length;
+  const unparseableCommits = unparseable.length > 0 ? unparseable : void 0;
+  const naturalBump = determineBumpType(parsedCommits, workTypes, versionPatterns);
+  const shouldRelease = naturalBump !== void 0 || force;
+  if (!shouldRelease) {
+    const skipReason = commits.length === 0 ? skipReasons.noCommits : skipReasons.noBumpWorthy;
+    return { outcome: "skip", skipReason, parsedCommitCount, unparseableCommits };
+  }
+  const releaseType = bumpOverride ?? naturalBump ?? "patch";
+  return { outcome: "release", releaseType, parsedCommitCount, unparseableCommits };
+}
+export {
+  decideRelease
+};

package/dist/esm/defaults.d.ts

@@ -3,3 +3,4 @@ export declare const DEFAULT_WORK_TYPES: Record<string, WorkTypeConfig>;
 export declare const DEFAULT_VERSION_PATTERNS: VersionPatterns;
 export declare const DEFAULT_CHANGELOG_JSON_CONFIG: ChangelogJsonConfig;
 export declare const DEFAULT_RELEASE_NOTES_CONFIG: ReleaseNotesConfig;
+export declare const DEFAULT_PROJECT_TAG_PREFIX = "v";

package/dist/esm/defaults.js

@@ -28,8 +28,10 @@ const DEFAULT_CHANGELOG_JSON_CONFIG = {
 const DEFAULT_RELEASE_NOTES_CONFIG = {
   shouldInjectIntoReadme: false
 };
+const DEFAULT_PROJECT_TAG_PREFIX = "v";
 export {
   DEFAULT_CHANGELOG_JSON_CONFIG,
+  DEFAULT_PROJECT_TAG_PREFIX,
   DEFAULT_RELEASE_NOTES_CONFIG,
   DEFAULT_VERSION_PATTERNS,
   DEFAULT_WORK_TYPES

package/dist/esm/index.d.ts

@@ -1,43 +1,2 @@
-export type { CreateTagsOptions } from './createTags.ts';
-export type { PackageManager } from './detectPackageManager.ts';
-export type { GenerateChangelogOptions } from './generateChangelogs.ts';
-export type { RetiredPackagePreviewEntry } from './previewTagPrefixes.ts';
-export type { PublishOptions } from './publish.ts';
-export type { ReleasePrepareOptions } from './releasePrepare.ts';
-export type { ResolvedTag } from './resolveReleaseTags.ts';
-export type { LabelDefinition, SyncLabelsConfig } from './sync-labels/types.ts';
-export type { BumpResult, ChangelogAudience, ChangelogEntry, ChangelogItem, ChangelogJsonConfig, ChangelogSection, Commit, LegacyIdentity, MonorepoReleaseConfig, ParsedCommit, PrepareResult, ReleaseConfig, ReleaseKitConfig, ReleaseNotesConfig, ReleaseType, RetiredPackage, VersionPatterns, WorkspaceConfig, WorkspaceOverride, WorkspacePrepareResult, WorkTypeConfig, } from './types.ts';
-export { DEFAULT_CHANGELOG_JSON_CONFIG, DEFAULT_RELEASE_NOTES_CONFIG, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES, } from './defaults.ts';
-export { buildReleaseSummary } from './buildReleaseSummary.ts';
-export { bumpAllVersions } from './bumpAllVersions.ts';
-export { bumpVersion } from './bumpVersion.ts';
-export { commitCommand } from './commitCommand.ts';
-export type { CreateGithubReleaseOptions } from './createGithubRelease.ts';
-export { createGithubRelease, createGithubReleases } from './createGithubRelease.ts';
-export { createTags } from './createTags.ts';
-export { deleteFileIfExists } from './deleteFileIfExists.ts';
-export { deriveWorkspaceConfig } from './deriveWorkspaceConfig.ts';
-export { detectPackageManager } from './detectPackageManager.ts';
-export { determineBumpType } from './determineBumpType.ts';
-export { discoverWorkspaces } from './discoverWorkspaces.ts';
-export { generateChangelogJson, generateSyntheticChangelogJson } from './generateChangelogJson.ts';
-export { generateChangelog, generateChangelogs } from './generateChangelogs.ts';
-export { getCommitsSinceTarget } from './getCommitsSinceTarget.ts';
-export type { RenderedInjectedReadme } from './injectReleaseNotesIntoReadme.ts';
-export { injectReleaseNotesIntoReadme, renderInjectedReadme, resolveReadmePath, } from './injectReleaseNotesIntoReadme.ts';
-export { injectSection } from './injectSection.ts';
-export { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage } from './parseCommitMessage.ts';
-export { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE, writeReleaseTags } from './prepareCommand.ts';
-export { publishPackage } from './publish.ts';
-export type { PushReleaseOptions } from './pushRelease.ts';
-export { pushRelease } from './pushRelease.ts';
-export { releasePrepare } from './releasePrepare.ts';
-export { releasePrepareMono } from './releasePrepareMono.ts';
-export type { RenderOptions } from './renderReleaseNotes.ts';
-export { matchesAudience, renderReleaseNotesMulti, renderReleaseNotesSingle } from './renderReleaseNotes.ts';
-export { reportPrepare } from './reportPrepare.ts';
-export { resolveCommandTags } from './resolveCommandTags.ts';
-export { resolveReleaseTags } from './resolveReleaseTags.ts';
-export { stripScope } from './stripScope.ts';
-export type { PreviewFileResult, WriteReleaseNotesPreviewsOptions, WriteReleaseNotesPreviewsResult, } from './writeReleaseNotesPreviews.ts';
-export { writeReleaseNotesPreviews } from './writeReleaseNotesPreviews.ts';
+export type { SyncLabelsConfig } from './sync-labels/types.ts';
+export type { ReleaseKitConfig } from './types.ts';

package/dist/esm/index.js

@@ -1,82 +0,0 @@
-import {
-  DEFAULT_CHANGELOG_JSON_CONFIG,
-  DEFAULT_RELEASE_NOTES_CONFIG,
-  DEFAULT_VERSION_PATTERNS,
-  DEFAULT_WORK_TYPES
-} from "./defaults.js";
-import { buildReleaseSummary } from "./buildReleaseSummary.js";
-import { bumpAllVersions } from "./bumpAllVersions.js";
-import { bumpVersion } from "./bumpVersion.js";
-import { commitCommand } from "./commitCommand.js";
-import { createGithubRelease, createGithubReleases } from "./createGithubRelease.js";
-import { createTags } from "./createTags.js";
-import { deleteFileIfExists } from "./deleteFileIfExists.js";
-import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
-import { detectPackageManager } from "./detectPackageManager.js";
-import { determineBumpType } from "./determineBumpType.js";
-import { discoverWorkspaces } from "./discoverWorkspaces.js";
-import { generateChangelogJson, generateSyntheticChangelogJson } from "./generateChangelogJson.js";
-import { generateChangelog, generateChangelogs } from "./generateChangelogs.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
-import {
-  injectReleaseNotesIntoReadme,
-  renderInjectedReadme,
-  resolveReadmePath
-} from "./injectReleaseNotesIntoReadme.js";
-import { injectSection } from "./injectSection.js";
-import { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage } from "./parseCommitMessage.js";
-import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE, writeReleaseTags } from "./prepareCommand.js";
-import { publishPackage } from "./publish.js";
-import { pushRelease } from "./pushRelease.js";
-import { releasePrepare } from "./releasePrepare.js";
-import { releasePrepareMono } from "./releasePrepareMono.js";
-import { matchesAudience, renderReleaseNotesMulti, renderReleaseNotesSingle } from "./renderReleaseNotes.js";
-import { reportPrepare } from "./reportPrepare.js";
-import { resolveCommandTags } from "./resolveCommandTags.js";
-import { resolveReleaseTags } from "./resolveReleaseTags.js";
-import { stripScope } from "./stripScope.js";
-import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
-export {
-  COMMIT_PREPROCESSOR_PATTERNS,
-  DEFAULT_CHANGELOG_JSON_CONFIG,
-  DEFAULT_RELEASE_NOTES_CONFIG,
-  DEFAULT_VERSION_PATTERNS,
-  DEFAULT_WORK_TYPES,
-  RELEASE_SUMMARY_FILE,
-  RELEASE_TAGS_FILE,
-  buildReleaseSummary,
-  bumpAllVersions,
-  bumpVersion,
-  commitCommand,
-  createGithubRelease,
-  createGithubReleases,
-  createTags,
-  deleteFileIfExists,
-  deriveWorkspaceConfig,
-  detectPackageManager,
-  determineBumpType,
-  discoverWorkspaces,
-  generateChangelog,
-  generateChangelogJson,
-  generateChangelogs,
-  generateSyntheticChangelogJson,
-  getCommitsSinceTarget,
-  injectReleaseNotesIntoReadme,
-  injectSection,
-  matchesAudience,
-  parseCommitMessage,
-  publishPackage,
-  pushRelease,
-  releasePrepare,
-  releasePrepareMono,
-  renderInjectedReadme,
-  renderReleaseNotesMulti,
-  renderReleaseNotesSingle,
-  reportPrepare,
-  resolveCommandTags,
-  resolveReadmePath,
-  resolveReleaseTags,
-  stripScope,
-  writeReleaseNotesPreviews,
-  writeReleaseTags
-};

package/dist/esm/init/templates.js

@@ -107,7 +107,7 @@ on:
           - minor
           - major
       force:
-        description: 'Force a release even when there are no commits since the last tag (requires --bump)'
+        description: 'Force a release even when no commits or no bump-worthy commits exist (defaults to patch; combine with --bump for a different level)'
         required: false
         type: boolean
         default: false
@@ -141,7 +141,7 @@ on:
           - minor
           - major
       force:
-        description: 'Force a release even when there are no commits since the last tag (requires --bump)'
+        description: 'Force a release even when no commits or no bump-worthy commits exist (defaults to patch; combine with --bump for a different level)'
         required: false
         type: boolean
         default: false

package/dist/esm/loadConfig.d.ts

@@ -1,6 +1,15 @@
 import type { MonorepoReleaseConfig, ReleaseConfig, ReleaseKitConfig, WorkTypeConfig } from './types.ts';
+export declare const ROOT_PACKAGE_JSON_PATH = "package.json";
+export declare function readRootPackageVersion(): {
+    exists: boolean;
+    version: string | undefined;
+};
 export declare const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
 export declare function loadConfig(): Promise<unknown>;
-export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfig: ReleaseKitConfig | undefined): MonorepoReleaseConfig;
+export interface RootPackageInfo {
+    exists: boolean;
+    version: string | undefined;
+}
+export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfig: ReleaseKitConfig | undefined, rootPackage?: RootPackageInfo): MonorepoReleaseConfig;
 export declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseConfig;
 export declare function resolveWorkTypes(userWorkTypes?: Record<string, WorkTypeConfig>): Record<string, WorkTypeConfig>;

package/dist/esm/loadConfig.js

@@ -1,13 +1,41 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import {
   DEFAULT_CHANGELOG_JSON_CONFIG,
+  DEFAULT_PROJECT_TAG_PREFIX,
   DEFAULT_RELEASE_NOTES_CONFIG,
   DEFAULT_VERSION_PATTERNS,
   DEFAULT_WORK_TYPES
 } from "./defaults.js";
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { isRecord } from "./typeGuards.js";
+const ROOT_PACKAGE_JSON_PATH = "package.json";
+function readRootPackageVersion() {
+  const absolutePath = path.resolve(process.cwd(), ROOT_PACKAGE_JSON_PATH);
+  if (!existsSync(absolutePath)) {
+    return { exists: false, version: void 0 };
+  }
+  let contents;
+  try {
+    contents = readFileSync(absolutePath, "utf8");
+  } catch (error) {
+    throw new Error(
+      `Failed to read root ${ROOT_PACKAGE_JSON_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse root ${ROOT_PACKAGE_JSON_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!isRecord(parsed)) {
+    return { exists: true, version: void 0 };
+  }
+  return { exists: true, version: typeof parsed.version === "string" ? parsed.version : void 0 };
+}
 const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
 async function loadConfig() {
   const absoluteConfigPath = path.resolve(process.cwd(), CONFIG_FILE_PATH);
@@ -28,7 +56,7 @@ async function loadConfig() {
   }
   return resolved;
 }
-function mergeMonorepoConfig(discoveredPaths, userConfig) {
+function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
   let workspaces = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
   assertUniqueTagPrefixes(workspaces);
   if (userConfig?.workspaces !== void 0) {
@@ -48,10 +76,12 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
   if (userConfig?.retiredPackages !== void 0) {
     assertRetiredPackagesDoNotCollideWithActive(workspaces, userConfig.retiredPackages);
   }
+  const project = resolveProjectConfig(userConfig?.project, rootPackage);
   const workTypes = resolveWorkTypes(userConfig?.workTypes);
   const versionPatterns = userConfig?.versionPatterns === void 0 ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
   const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
   const releaseNotes = mergeReleaseNotesConfig(userConfig?.releaseNotes);
+  assertNoTagPrefixCollisions(workspaces, userConfig?.retiredPackages, project);
   const result = {
     workspaces,
     workTypes,
@@ -59,6 +89,9 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
     changelogJson,
     releaseNotes
   };
+  if (project !== void 0) {
+    result.project = project;
+  }
   const formatCommand = userConfig?.formatCommand;
   if (formatCommand !== void 0) {
     result.formatCommand = formatCommand;
@@ -74,6 +107,9 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
   return result;
 }
 function mergeSinglePackageConfig(userConfig) {
+  if (userConfig?.project !== void 0) {
+    throw new Error("project block is not supported in single-package mode");
+  }
   const workTypes = resolveWorkTypes(userConfig?.workTypes);
   const versionPatterns = userConfig?.versionPatterns === void 0 ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
   const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
@@ -137,6 +173,62 @@ function assertRetiredPackagesDoNotCollideWithActive(workspaces, retiredPackages
     }
   }
 }
+function resolveProjectConfig(userProject, rootPackage) {
+  if (userProject === void 0) {
+    return void 0;
+  }
+  if (rootPackage === void 0 || !rootPackage.exists) {
+    throw new Error(
+      `project block requires a root ${ROOT_PACKAGE_JSON_PATH}; create one with a 'version' field at the repo root`
+    );
+  }
+  if (rootPackage.version === void 0) {
+    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 };
+}
+function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
+  const sources = [];
+  for (const workspace of workspaces) {
+    const owner = `ws:${workspace.dir}`;
+    sources.push({ prefix: workspace.tagPrefix, label: `workspace '${workspace.dir}'`, owner });
+    for (const identity of workspace.legacyIdentities ?? []) {
+      sources.push({
+        prefix: identity.tagPrefix,
+        label: `workspace '${workspace.dir}' legacyIdentities entry (name='${identity.name}')`,
+        owner
+      });
+    }
+  }
+  for (const [index, retired] of (retiredPackages ?? []).entries()) {
+    sources.push({
+      prefix: retired.tagPrefix,
+      label: `retiredPackages entry (name='${retired.name}')`,
+      owner: `retired:${index}`
+    });
+  }
+  if (project !== void 0) {
+    sources.push({ prefix: project.tagPrefix, label: "project", owner: "project" });
+  }
+  for (let i = 0; i < sources.length; i++) {
+    for (let j = i + 1; j < sources.length; j++) {
+      const a = sources[i];
+      const b = sources[j];
+      if (a === void 0 || b === void 0) continue;
+      if (a.owner === b.owner) continue;
+      if (isPrefixCollision(a.prefix, b.prefix)) {
+        throw new Error(
+          `Tag prefix collision: '${a.prefix}' (${a.label}) and '${b.prefix}' (${b.label}). One prefix is identical to or a strict prefix of the other; this would cause \`git describe --match=<prefix>*\` to return cross-matches.`
+        );
+      }
+    }
+  }
+}
+function isPrefixCollision(a, b) {
+  return a === b || a.startsWith(b) || b.startsWith(a);
+}
 function assertUniqueTagPrefixes(workspaces) {
   const pathsByPrefix = /* @__PURE__ */ new Map();
   for (const workspace of workspaces) {
@@ -163,8 +255,10 @@ function mergeReleaseNotesConfig(partial) {
 }
 export {
   CONFIG_FILE_PATH,
+  ROOT_PACKAGE_JSON_PATH,
   loadConfig,
   mergeMonorepoConfig,
   mergeSinglePackageConfig,
+  readRootPackageVersion,
   resolveWorkTypes
 };

package/dist/esm/prepareCommand.js

@@ -1,13 +1,16 @@
 import { parseArgs as coreParseArgs, translateParseError, writeFileWithCheck } from "@williamthorsen/nmr-core";
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
+import { buildDependencyGraph } from "./buildDependencyGraph.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
-import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig } from "./loadConfig.js";
+import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { releasePrepare } from "./releasePrepare.js";
 import { releasePrepareMono } from "./releasePrepareMono.js";
 import { reportPrepare } from "./reportPrepare.js";
 import { validateConfig } from "./validateConfig.js";
+import { validateOnlyExcludesStrandedDependents } from "./validateOnlyExcludesStrandedDependents.js";
 const RELEASE_TAGS_FILE = "tmp/.release-tags";
 const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
 const VALID_BUMP_TYPES = ["major", "minor", "patch"];
@@ -22,10 +25,14 @@ Usage: npx @williamthorsen/release-kit prepare [options]
 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.
-  --force               Force a release even when there are no commits since the last tag (requires --bump)
+  --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).
+  --force               Release even when no commits or no bump-worthy commits exist
+                         since the last tag. Defaults to patch when --bump is not given;
+                         use --bump=X to release at a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only)
+  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only;
+                         rejected when a 'project' block is configured)
   --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).
@@ -84,9 +91,6 @@ function parseArgs(argv) {
   if (setVersion !== void 0 && flags.force) {
     throw new Error("--set-version cannot be combined with --force");
   }
-  if (flags.force && bumpOverride === void 0) {
-    throw new Error("--force requires --bump to specify the version bump type");
-  }
   return {
     dryRun: flags.dryRun,
     force: flags.force,
@@ -157,17 +161,36 @@ function runSinglePackageMode(userConfig, options, only, dryRun) {
     console.error("Error: --only is only supported for monorepo configurations");
     process.exit(1);
   }
+  if (options.force && options.bumpOverride === void 0) {
+    console.error(
+      "Error: --force without --bump is only supported for monorepo configurations. Use --bump=major|minor|patch to set the level for a single-package release."
+    );
+    process.exit(1);
+  }
   const config = mergeSinglePackageConfig(userConfig);
   runAndReport(() => releasePrepare(config, options), dryRun);
 }
 function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion, dryRun) {
   let config;
   try {
-    config = mergeMonorepoConfig(discoveredPaths, userConfig);
+    const rootPackage = readRootPackageVersion();
+    config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
   } catch (error) {
     console.error(`Error resolving workspaces: ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
   }
+  if (setVersion !== void 0 && config.project !== void 0) {
+    console.error(
+      "Error: --set-version cannot be combined with a project release. --set-version operates on a single workspace; a project release rolls up every contributing workspace. To use --set-version, run on a config without a `project` block."
+    );
+    process.exit(1);
+  }
+  if (only !== void 0 && config.project !== void 0) {
+    console.error(
+      "Error: --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 !== void 0) {
     const knownNames = config.workspaces.map((w) => w.dir);
     for (const name of only) {
@@ -176,6 +199,25 @@ function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion,
         process.exit(1);
       }
     }
+    const graph = buildDependencyGraph(config.workspaces);
+    const violations = validateOnlyExcludesStrandedDependents(config.workspaces, only, graph, (workspace) => {
+      const tagPrefixes = [
+        workspace.tagPrefix,
+        ...workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? []
+      ];
+      const result = getCommitsSinceTarget(tagPrefixes, workspace.paths);
+      return { has: result.commits.length > 0, tag: result.tag };
+    });
+    if (violations !== void 0) {
+      console.error("Error: --only excludes packages with changes that would be stranded by the release.");
+      console.error("The following packages must be added to --only or have their dependencies removed:");
+      for (const violation of violations) {
+        const since = violation.tag ?? "the beginning";
+        console.error(`  - ${violation.dir} (downstream of ${violation.downstreamOf}; has commits since ${since})`);
+      }
+      console.error("Alternatively, run `release-kit prepare` without --only to release everything.");
+      process.exit(1);
+    }
     config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
   }
   if (setVersion !== void 0) {
@@ -221,7 +263,7 @@ function runAndReport(execute, dryRun) {
   try {
     result = execute();
   } catch (error) {
-    console.error("Error preparing release:", error instanceof Error ? error.message : String(error));
+    console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   }
   process.stdout.write(reportPrepare(result) + "\n");

package/dist/esm/publish.d.ts

@@ -2,7 +2,6 @@ import type { PackageManager } from './detectPackageManager.ts';
 import type { ResolvedTag } from './resolveReleaseTags.ts';
 export interface PublishOptions {
     dryRun: boolean;
-    noGitChecks: boolean;
     provenance: boolean;
 }
 export declare function publishPackage(resolvedTag: ResolvedTag, packageManager: PackageManager, options: PublishOptions): void;

package/dist/esm/publish.js

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 function publishPackage(resolvedTag, packageManager, options) {
-  const { dryRun, noGitChecks, provenance } = options;
+  const { dryRun, provenance } = options;
   const executable = resolveExecutable(packageManager);
-  const args = buildPublishArgs(packageManager, { dryRun, noGitChecks, provenance });
+  const args = buildPublishArgs(packageManager, { dryRun, provenance });
   console.info(
     `
 ${dryRun ? "[dry-run] " : ""}Running: ${executable} ${args.join(" ")} (cwd: ${resolvedTag.workspacePath})`
@@ -20,7 +20,7 @@ function buildPublishArgs(packageManager, options) {
   if (options.dryRun) {
     args.push("--dry-run");
   }
-  if (options.noGitChecks && packageManager === "pnpm") {
+  if (packageManager === "pnpm") {
     args.push("--no-git-checks");
   }
   if (options.provenance && packageManager !== "yarn") {

package/dist/esm/publishCommand.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseArgs, translateParseError } from "@williamthorsen/nmr-core";
+import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { injectReleaseNotesIntoReadme, resolveReadmePath } from "./injectReleaseNotesIntoReadme.js";
 import { parseRequestedTags } from "./parseRequestedTags.js";
@@ -22,6 +23,14 @@ async function publishCommand(argv) {
     process.exit(1);
   }
   const { dryRun, noGitChecks, provenance } = parsed.flags;
+  if (!dryRun && !noGitChecks) {
+    try {
+      assertCleanWorkingTree();
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  }
   const requestedTags = parseRequestedTags(parsed.flags.tags);
   const resolvedTags = await resolveCommandTags(requestedTags);
   if (resolvedTags.length === 0) {
@@ -51,7 +60,7 @@ async function publishCommand(argv) {
         }
       }
       try {
-        publishPackage(resolvedTag, packageManager, { dryRun, noGitChecks, provenance });
+        publishPackage(resolvedTag, packageManager, { dryRun, provenance });
         published.push(resolvedTag.tag);
       } finally {
         if (readmePath !== void 0 && originalReadme !== void 0) {