@williamthorsen/release-kit 4.8.0 → 5.0.0

package/dist/esm/getCommitsSinceTarget.js

@@ -6,9 +6,13 @@ function isNoTagError(err) {
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function findLatestTag(tagPrefix) {
+function findLatestTag(tagPrefixes) {
+  if (tagPrefixes.length === 0) {
+    throw new Error("findLatestTag: tagPrefixes must contain at least one entry");
+  }
+  const matchArgs = tagPrefixes.map((prefix) => `--match=${prefix}*`);
   try {
-    const tagResult = execFileSync("git", ["describe", "--tags", "--abbrev=0", `--match=${tagPrefix}*`], {
+    const tagResult = execFileSync("git", ["describe", "--tags", "--abbrev=0", ...matchArgs], {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
@@ -35,8 +39,8 @@ function parseLogOutput(logOutput) {
   }
   return commits;
 }
-function getCommitsSinceTarget(tagPrefix, paths) {
-  const tag = findLatestTag(tagPrefix);
+function getCommitsSinceTarget(tagPrefixes, paths) {
+  const tag = findLatestTag(tagPrefixes);
   const range = tag === void 0 ? "HEAD" : `${tag}..HEAD`;
   const format = `%s${FIELD_SEPARATOR}%H`;
   const args = ["log", range, `--pretty=format:${format}`];

package/dist/esm/index.d.ts

@@ -1,28 +1,30 @@
 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, ComponentConfig, ComponentOverride, ComponentPrepareResult, MonorepoReleaseConfig, ParsedCommit, PrepareResult, ReleaseConfig, ReleaseKitConfig, ReleaseNotesConfig, ReleaseType, VersionPatterns, WorkTypeConfig, } from './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 { component } from './component.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 { injectReleaseNotesIntoReadme, resolveReadmePath } from './injectReleaseNotesIntoReadme.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';
@@ -37,3 +39,5 @@ 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';

package/dist/esm/index.js

@@ -8,17 +8,21 @@ import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { bumpAllVersions } from "./bumpAllVersions.js";
 import { bumpVersion } from "./bumpVersion.js";
 import { commitCommand } from "./commitCommand.js";
-import { component } from "./component.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, resolveReadmePath } from "./injectReleaseNotesIntoReadme.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";
@@ -31,6 +35,7 @@ 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,
@@ -43,11 +48,11 @@ export {
   bumpAllVersions,
   bumpVersion,
   commitCommand,
-  component,
   createGithubRelease,
   createGithubReleases,
   createTags,
   deleteFileIfExists,
+  deriveWorkspaceConfig,
   detectPackageManager,
   determineBumpType,
   discoverWorkspaces,
@@ -64,6 +69,7 @@ export {
   pushRelease,
   releasePrepare,
   releasePrepareMono,
+  renderInjectedReadme,
   renderReleaseNotesMulti,
   renderReleaseNotesSingle,
   reportPrepare,
@@ -71,5 +77,6 @@ export {
   resolveReadmePath,
   resolveReleaseTags,
   stripScope,
+  writeReleaseNotesPreviews,
   writeReleaseTags
 };

package/dist/esm/init/initCommand.js

@@ -1,4 +1,4 @@
-import { printError, printStep, printSuccess, reportWriteResult } from "@williamthorsen/node-monorepo-core";
+import { printError, printStep, printSuccess, reportWriteResult } from "@williamthorsen/nmr-core";
 import { hasPackageJson, isGitRepo, usesPnpm } from "./checks.js";
 import { detectRepoType } from "./detectRepoType.js";
 import { scaffoldFiles } from "./scaffold.js";

package/dist/esm/init/scaffold.d.ts

@@ -1,4 +1,4 @@
-import type { WriteResult } from '@williamthorsen/node-monorepo-core';
+import type { WriteResult } from '@williamthorsen/nmr-core';
 import type { RepoType } from './detectRepoType.ts';
 interface ScaffoldOptions {
     repoType: RepoType;

package/dist/esm/init/scaffold.js

@@ -1,8 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { writeFileWithCheck } from "@williamthorsen/node-monorepo-core";
-import { findPackageRoot } from "../findPackageRoot.js";
-import { publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
+import { findPackageRoot, writeFileWithCheck } from "@williamthorsen/nmr-core";
+import { createGithubReleaseWorkflow, publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
 function copyCliffTemplate(dryRun, overwrite) {
   const destPath = ".config/git-cliff.toml";
   const root = findPackageRoot(import.meta.url);
@@ -21,8 +20,12 @@ function copyCliffTemplate(dryRun, overwrite) {
 }
 function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }) {
   const results = [
-    writeFileWithCheck(".github/workflows/release.yaml", releaseWorkflow(repoType), { dryRun, overwrite }),
-    writeFileWithCheck(".github/workflows/publish.yaml", publishWorkflow(repoType), { dryRun, overwrite })
+    writeFileWithCheck(".github/workflows/create-github-release.yaml", createGithubReleaseWorkflow(repoType), {
+      dryRun,
+      overwrite
+    }),
+    writeFileWithCheck(".github/workflows/publish.yaml", publishWorkflow(repoType), { dryRun, overwrite }),
+    writeFileWithCheck(".github/workflows/release.yaml", releaseWorkflow(repoType), { dryRun, overwrite })
   ];
   if (withConfig) {
     results.push(

package/dist/esm/init/templates.d.ts

@@ -1,4 +1,5 @@
 import type { RepoType } from './detectRepoType.ts';
 export declare function releaseConfigScript(repoType: RepoType): string;
 export declare function publishWorkflow(repoType: RepoType): string;
+export declare function createGithubReleaseWorkflow(repoType: RepoType): string;
 export declare function releaseWorkflow(repoType: RepoType): string;

package/dist/esm/init/templates.js

@@ -3,8 +3,12 @@ function releaseConfigScript(repoType) {
     return `import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
 
 const config: ReleaseKitConfig = {
-  // Uncomment to exclude components from release processing:
-  // components: [
+  releaseNotes: {
+    shouldInjectIntoReadme: true,
+  },
+
+  // Uncomment to exclude workspaces from release processing:
+  // workspaces: [
   //   { dir: 'my-package', shouldExclude: true },
   // ],
 
@@ -23,6 +27,10 @@ export default config;
   return `import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
 
 const config: ReleaseKitConfig = {
+  releaseNotes: {
+    shouldInjectIntoReadme: true,
+  },
+
   // Formatting: prettier is auto-detected. Set formatCommand to override.
 
   // Uncomment to override the default version patterns:
@@ -54,6 +62,27 @@ jobs:
     uses: williamthorsen/node-monorepo-tools/.github/workflows/publish.reusable.yaml@workflow/publish-v1
     with:
       provenance: true
+      tags: \${{ github.ref_name }}
+`;
+}
+function createGithubReleaseWorkflow(repoType) {
+  const tagPattern = repoType === "monorepo" ? "'*-v[0-9]*.[0-9]*.[0-9]*'" : "'v[0-9]*.[0-9]*.[0-9]*'";
+  return `# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+name: Create GitHub Release
+
+on:
+  push:
+    tags:
+      - ${tagPattern}
+
+permissions:
+  contents: write
+
+jobs:
+  create-github-release:
+    uses: williamthorsen/node-monorepo-tools/.github/workflows/create-github-release.reusable.yaml@workflow/create-github-release-v1
+    with:
+      tag: \${{ github.ref_name }}
 `;
 }
 function releaseWorkflow(repoType) {
@@ -65,7 +94,7 @@ on:
   workflow_dispatch:
     inputs:
       only:
-        description: 'Components to release (comma-separated, leave empty for all)'
+        description: 'Workspaces to release (comma-separated, leave empty for all)'
         required: false
         type: string
       bump:
@@ -130,6 +159,7 @@ jobs:
 `;
 }
 export {
+  createGithubReleaseWorkflow,
   publishWorkflow,
   releaseConfigScript,
   releaseWorkflow

package/dist/esm/injectReleaseNotesIntoReadme.d.ts

@@ -1,2 +1,7 @@
-export declare function injectReleaseNotesIntoReadme(readmePath: string, changelogJsonPath: string, tag: string): string | undefined;
+export interface RenderedInjectedReadme {
+    injectedReadme: string;
+    releaseNotesMarkdown: string;
+}
+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

@@ -3,12 +3,11 @@ import { join } from "node:path";
 import { extractVersion, readChangelogEntries } from "./changelogJsonUtils.js";
 import { injectSection } from "./injectSection.js";
 import { matchesAudience, renderReleaseNotesSingle } from "./renderReleaseNotes.js";
-function injectReleaseNotesIntoReadme(readmePath, changelogJsonPath, tag) {
+function renderInjectedReadme(readme, changelogJsonPath, tag, sectionOrder) {
   if (!existsSync(changelogJsonPath)) {
     console.warn(`Warning: ${changelogJsonPath} not found; skipping README injection`);
     return void 0;
   }
-  const originalReadme = readFileSync(readmePath, "utf8");
   const version = extractVersion(tag);
   const entries = readChangelogEntries(changelogJsonPath);
   if (entries === void 0) {
@@ -20,16 +19,29 @@ function injectReleaseNotesIntoReadme(readmePath, changelogJsonPath, tag) {
     console.warn(`Warning: no changelog entry for version ${version}; skipping README injection`);
     return void 0;
   }
-  const releaseNotesMarkdown = renderReleaseNotesSingle(entry, {
+  const renderedSections = renderReleaseNotesSingle(entry, {
     filter: matchesAudience("all"),
-    includeHeading: false
+    includeHeading: false,
+    ...sectionOrder === void 0 ? {} : { sectionOrder }
   });
-  if (releaseNotesMarkdown.trimEnd().length === 0) {
+  if (renderedSections.trimEnd().length === 0) {
     console.warn(`Warning: no user-facing release notes for version ${version}; skipping README injection`);
     return void 0;
   }
-  const injected = injectSection(originalReadme, "release-notes", releaseNotesMarkdown.trimEnd());
-  writeFileSync(readmePath, injected, "utf8");
+  const labeledHeading = `## Release notes \u2014 v${version} (${entry.date})`;
+  const releaseNotesMarkdown = `${labeledHeading}
+
+${renderedSections.trimEnd()}`;
+  const injectedReadme = injectSection(readme, "release-notes", releaseNotesMarkdown);
+  return { injectedReadme, releaseNotesMarkdown };
+}
+function injectReleaseNotesIntoReadme(readmePath, changelogJsonPath, tag, sectionOrder) {
+  const originalReadme = readFileSync(readmePath, "utf8");
+  const rendered = renderInjectedReadme(originalReadme, changelogJsonPath, tag, sectionOrder);
+  if (rendered === void 0) {
+    return void 0;
+  }
+  writeFileSync(readmePath, rendered.injectedReadme, "utf8");
   return originalReadme;
 }
 function resolveReadmePath(workspacePath) {
@@ -38,5 +50,6 @@ function resolveReadmePath(workspacePath) {
 }
 export {
   injectReleaseNotesIntoReadme,
+  renderInjectedReadme,
   resolveReadmePath
 };

package/dist/esm/loadConfig.d.ts

@@ -1,5 +1,6 @@
-import type { MonorepoReleaseConfig, ReleaseConfig, ReleaseKitConfig } from './types.ts';
+import type { MonorepoReleaseConfig, ReleaseConfig, ReleaseKitConfig, WorkTypeConfig } from './types.ts';
 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 declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseConfig;
+export declare function resolveWorkTypes(userWorkTypes?: Record<string, WorkTypeConfig>): Record<string, WorkTypeConfig>;

package/dist/esm/loadConfig.js

@@ -1,12 +1,12 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { component } from "./component.js";
 import {
   DEFAULT_CHANGELOG_JSON_CONFIG,
   DEFAULT_RELEASE_NOTES_CONFIG,
   DEFAULT_VERSION_PATTERNS,
   DEFAULT_WORK_TYPES
 } from "./defaults.js";
+import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { isRecord } from "./typeGuards.js";
 const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
 async function loadConfig() {
@@ -29,20 +29,31 @@ async function loadConfig() {
   return resolved;
 }
 function mergeMonorepoConfig(discoveredPaths, userConfig) {
-  let components = discoveredPaths.map((workspacePath) => component(workspacePath));
-  if (userConfig?.components !== void 0) {
-    const overrides = new Map(userConfig.components.map((c) => [c.dir, c]));
-    components = components.filter((c) => {
-      const override = overrides.get(c.dir);
+  let workspaces = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
+  assertUniqueTagPrefixes(workspaces);
+  if (userConfig?.workspaces !== void 0) {
+    const overrides = new Map(userConfig.workspaces.map((w) => [w.dir, w]));
+    workspaces = workspaces.filter((w) => {
+      const override = overrides.get(w.dir);
       return override?.shouldExclude !== true;
+    }).map((w) => {
+      const override = overrides.get(w.dir);
+      if (override?.legacyIdentities === void 0) {
+        return w;
+      }
+      assertLegacyIdentityDoesNotMatchCurrent(w.dir, w.name, w.tagPrefix, override.legacyIdentities);
+      return { ...w, legacyIdentities: override.legacyIdentities.map((identity) => ({ ...identity })) };
     });
   }
-  const workTypes = userConfig?.workTypes === void 0 ? { ...DEFAULT_WORK_TYPES } : { ...DEFAULT_WORK_TYPES, ...userConfig.workTypes };
+  if (userConfig?.retiredPackages !== void 0) {
+    assertRetiredPackagesDoNotCollideWithActive(workspaces, userConfig.retiredPackages);
+  }
+  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);
   const result = {
-    components,
+    workspaces,
     workTypes,
     versionPatterns,
     changelogJson,
@@ -63,7 +74,7 @@ function mergeMonorepoConfig(discoveredPaths, userConfig) {
   return result;
 }
 function mergeSinglePackageConfig(userConfig) {
-  const workTypes = userConfig?.workTypes === void 0 ? { ...DEFAULT_WORK_TYPES } : { ...DEFAULT_WORK_TYPES, ...userConfig.workTypes };
+  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);
@@ -90,6 +101,9 @@ function mergeSinglePackageConfig(userConfig) {
   }
   return result;
 }
+function resolveWorkTypes(userWorkTypes) {
+  return userWorkTypes === void 0 ? { ...DEFAULT_WORK_TYPES } : { ...DEFAULT_WORK_TYPES, ...userWorkTypes };
+}
 function mergeChangelogJsonConfig(partial) {
   if (partial === void 0) {
     return { ...DEFAULT_CHANGELOG_JSON_CONFIG };
@@ -100,18 +114,57 @@ function mergeChangelogJsonConfig(partial) {
     devOnlySections: partial.devOnlySections ?? [...DEFAULT_CHANGELOG_JSON_CONFIG.devOnlySections]
   };
 }
+function assertLegacyIdentityDoesNotMatchCurrent(dir, currentName, currentTagPrefix, legacyIdentities) {
+  for (const identity of legacyIdentities) {
+    if (identity.name === currentName && identity.tagPrefix === currentTagPrefix) {
+      throw new Error(
+        `Workspace '${dir}': legacyIdentities must not match the current identity (name='${currentName}', tagPrefix='${currentTagPrefix}'). The current identity is always searched; listing it again is a no-op.`
+      );
+    }
+  }
+}
+function assertRetiredPackagesDoNotCollideWithActive(workspaces, retiredPackages) {
+  const workspaceByDerivedPrefix = /* @__PURE__ */ new Map();
+  for (const workspace of workspaces) {
+    workspaceByDerivedPrefix.set(workspace.tagPrefix, workspace);
+  }
+  for (const retired of retiredPackages) {
+    const active = workspaceByDerivedPrefix.get(retired.tagPrefix);
+    if (active !== void 0) {
+      throw new Error(
+        `retiredPackages: tagPrefix '${retired.tagPrefix}' collides with active workspace '${active.dir}' (derived prefix '${active.tagPrefix}'). A retired package's tagPrefix cannot belong to an active workspace.`
+      );
+    }
+  }
+}
+function assertUniqueTagPrefixes(workspaces) {
+  const pathsByPrefix = /* @__PURE__ */ new Map();
+  for (const workspace of workspaces) {
+    const existing = pathsByPrefix.get(workspace.tagPrefix);
+    if (existing === void 0) {
+      pathsByPrefix.set(workspace.tagPrefix, [workspace.workspacePath]);
+    } else {
+      existing.push(workspace.workspacePath);
+    }
+  }
+  for (const [prefix, paths] of pathsByPrefix) {
+    if (paths.length > 1) {
+      throw new Error(`Duplicate tag prefix '${prefix}' for workspaces: ${paths.join(", ")}`);
+    }
+  }
+}
 function mergeReleaseNotesConfig(partial) {
   if (partial === void 0) {
     return { ...DEFAULT_RELEASE_NOTES_CONFIG };
   }
   return {
-    shouldInjectIntoReadme: partial.shouldInjectIntoReadme ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldInjectIntoReadme,
-    shouldCreateGithubRelease: partial.shouldCreateGithubRelease ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldCreateGithubRelease
+    shouldInjectIntoReadme: partial.shouldInjectIntoReadme ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldInjectIntoReadme
   };
 }
 export {
   CONFIG_FILE_PATH,
   loadConfig,
   mergeMonorepoConfig,
-  mergeSinglePackageConfig
+  mergeSinglePackageConfig,
+  resolveWorkTypes
 };

package/dist/esm/parseRequestedTags.d.ts

@@ -0,0 +1 @@
+export declare function parseRequestedTags(flagValue: string | undefined): string[] | undefined;

package/dist/esm/parseRequestedTags.js

@@ -0,0 +1,10 @@
+function parseRequestedTags(flagValue) {
+  if (flagValue === void 0) {
+    return void 0;
+  }
+  const segments = flagValue.split(",").filter(Boolean);
+  return segments.length === 0 ? void 0 : segments;
+}
+export {
+  parseRequestedTags
+};

package/dist/esm/prepareCommand.d.ts

@@ -1,4 +1,4 @@
-import type { WriteResult } from '@williamthorsen/node-monorepo-core';
+import type { WriteResult } from '@williamthorsen/nmr-core';
 import type { ReleaseType } from './types.ts';
 export declare const RELEASE_TAGS_FILE = "tmp/.release-tags";
 export declare const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
@@ -8,6 +8,8 @@ export declare function parseArgs(argv: string[]): {
     noGitChecks: boolean;
     bumpOverride: ReleaseType | undefined;
     only: string[] | undefined;
+    setVersion: string | undefined;
+    withReleaseNotes: boolean;
 };
 export declare function writeReleaseTags(tags: string[], dryRun: boolean): WriteResult | undefined;
 export declare function prepareCommand(argv: string[]): Promise<void>;

package/dist/esm/prepareCommand.js

@@ -1,8 +1,4 @@
-import {
-  parseArgs as coreParseArgs,
-  translateParseError,
-  writeFileWithCheck
-} from "@williamthorsen/node-monorepo-core";
+import { parseArgs as coreParseArgs, translateParseError, writeFileWithCheck } from "@williamthorsen/nmr-core";
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
 import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { discoverWorkspaces } from "./discoverWorkspaces.js";
@@ -15,6 +11,7 @@ import { validateConfig } from "./validateConfig.js";
 const RELEASE_TAGS_FILE = "tmp/.release-tags";
 const RELEASE_SUMMARY_FILE = "tmp/.release-summary";
 const VALID_BUMP_TYPES = ["major", "minor", "patch"];
+const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 function isReleaseType(value) {
   return VALID_BUMP_TYPES.includes(value);
 }
@@ -24,10 +21,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 components
+  --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)
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Only process the named components (comma-separated, monorepo only)
+  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only)
+  --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).
   --help                Show this help message
 `);
 }
@@ -40,7 +41,9 @@ const prepareFlagSchema = {
     short: "-n"
   },
   bump: { long: "--bump", type: "string" },
+  setVersion: { long: "--set-version", type: "string" },
   only: { long: "--only", type: "string" },
+  withReleaseNotes: { long: "--with-release-notes", type: "boolean" },
   help: { long: "--help", type: "boolean", short: "-h" }
 };
 function parseArgs(argv) {
@@ -62,10 +65,25 @@ function parseArgs(argv) {
     }
     bumpOverride = flags.bump;
   }
+  let setVersion;
+  if (flags.setVersion !== void 0) {
+    if (!CANONICAL_SEMVER_PATTERN.test(flags.setVersion)) {
+      throw new Error(
+        `Invalid --set-version value "${flags.setVersion}". Must be canonical semver (N.N.N, no pre-release suffix).`
+      );
+    }
+    setVersion = flags.setVersion;
+  }
   let only;
   if (flags.only !== void 0) {
     only = flags.only.split(",");
   }
+  if (setVersion !== void 0 && bumpOverride !== void 0) {
+    throw new Error("--set-version cannot be combined with --bump");
+  }
+  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");
   }
@@ -74,7 +92,9 @@ function parseArgs(argv) {
     force: flags.force,
     noGitChecks: flags.noGitChecks,
     bumpOverride,
-    only
+    only,
+    setVersion,
+    withReleaseNotes: flags.withReleaseNotes
   };
 }
 function writeReleaseTags(tags, dryRun) {
@@ -92,8 +112,10 @@ async function prepareCommand(argv) {
   let noGitChecks;
   let bumpOverride;
   let only;
+  let setVersion;
+  let withReleaseNotes;
   try {
-    ({ dryRun, force, noGitChecks, bumpOverride, only } = parseArgs(argv));
+    ({ dryRun, force, noGitChecks, bumpOverride, only, setVersion, withReleaseNotes } = parseArgs(argv));
   } catch (error) {
     console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
     process.exit(1);
@@ -101,7 +123,9 @@ async function prepareCommand(argv) {
   const options = {
     dryRun,
     force,
-    ...bumpOverride === void 0 ? {} : { bumpOverride }
+    ...bumpOverride === void 0 ? {} : { bumpOverride },
+    ...setVersion === void 0 ? {} : { setVersion },
+    ...withReleaseNotes ? { withReleaseNotes: true } : {}
   };
   if (dryRun) {
     console.info("\n\u{1F50D} DRY RUN \u2014 no files will be modified\n");
@@ -123,26 +147,50 @@ async function prepareCommand(argv) {
     process.exit(1);
   }
   if (discoveredPaths === void 0) {
-    if (only !== void 0) {
-      console.error("Error: --only is only supported for monorepo configurations");
-      process.exit(1);
-    }
-    const config = mergeSinglePackageConfig(userConfig);
-    runAndReport(() => releasePrepare(config, options), dryRun);
+    runSinglePackageMode(userConfig, options, only, dryRun);
   } else {
-    const config = mergeMonorepoConfig(discoveredPaths, userConfig);
-    if (only !== void 0) {
-      const knownNames = config.components.map((c) => c.dir);
-      for (const name of only) {
-        if (!knownNames.includes(name)) {
-          console.error(`Error: Unknown component "${name}". Known components: ${knownNames.join(", ")}`);
-          process.exit(1);
-        }
+    runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion, dryRun);
+  }
+}
+function runSinglePackageMode(userConfig, options, only, dryRun) {
+  if (only !== void 0) {
+    console.error("Error: --only is only supported for monorepo configurations");
+    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);
+  } catch (error) {
+    console.error(`Error resolving workspaces: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+  if (only !== void 0) {
+    const knownNames = config.workspaces.map((w) => w.dir);
+    for (const name of only) {
+      if (!knownNames.includes(name)) {
+        console.error(`Error: Unknown workspace "${name}". Known workspaces: ${knownNames.join(", ")}`);
+        process.exit(1);
       }
-      config.components = config.components.filter((c) => only.includes(c.dir));
     }
-    runAndReport(() => releasePrepareMono(config, options), dryRun);
+    config.workspaces = config.workspaces.filter((w) => only.includes(w.dir));
+  }
+  if (setVersion !== void 0) {
+    if (only === void 0) {
+      console.error("Error: --set-version requires --only in monorepo mode");
+      process.exit(1);
+    }
+    if (config.workspaces.length !== 1) {
+      console.error(
+        `Error: --set-version requires --only to match exactly one workspace; matched ${config.workspaces.length}`
+      );
+      process.exit(1);
+    }
   }
+  runAndReport(() => releasePrepareMono(config, options), dryRun);
 }
 async function loadAndValidateConfig() {
   let rawConfig;