@williamthorsen/release-kit 4.7.0 → 5.0.0

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
-  --force               Bypass the "no commits since last tag" check (monorepo only, requires --bump)
+  --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;

package/dist/esm/previewTagPrefixes.d.ts

@@ -0,0 +1,30 @@
+import type { UndeclaredTagPrefix } from './detectUndeclaredTagPrefixes.ts';
+export interface TagPrefixPreviewRow {
+    workspacePath: string;
+    dir: string;
+    derivedPrefix: string | null;
+    derivationError: string | null;
+    derivedTagCount: number;
+    legacyEntries: LegacyTagPrefixEntry[];
+}
+export interface LegacyTagPrefixEntry {
+    prefix: string;
+    tagCount: number;
+}
+export interface RetiredPackagePreviewEntry {
+    name: string;
+    tagPrefix: string;
+    successor?: string;
+    tagCount: number;
+}
+export interface TagPrefixCollision {
+    tagPrefix: string;
+    workspacePaths: string[];
+}
+export interface TagPrefixPreview {
+    workspaces: TagPrefixPreviewRow[];
+    collisions: TagPrefixCollision[];
+    undeclaredCandidates: UndeclaredTagPrefix[];
+    retiredPackages: RetiredPackagePreviewEntry[];
+}
+export declare function previewTagPrefixes(): Promise<TagPrefixPreview>;

package/dist/esm/previewTagPrefixes.js

@@ -0,0 +1,120 @@
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
+import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
+import { discoverWorkspaces } from "./discoverWorkspaces.js";
+import { loadConfig } from "./loadConfig.js";
+import { validateConfig } from "./validateConfig.js";
+async function previewTagPrefixes() {
+  const workspacePaths = await discoverWorkspaces() ?? [];
+  const userConfig = await loadUserConfig();
+  const overridesByDir = buildOverrideMap(userConfig);
+  const workspaces = [];
+  for (const workspacePath of workspacePaths) {
+    workspaces.push(buildPreviewRow(workspacePath, overridesByDir));
+  }
+  const retiredPackages = buildRetiredPreviewEntries(userConfig?.retiredPackages ?? []);
+  const collisions = detectCollisions(workspaces);
+  const knownPrefixes = collectKnownPrefixes(workspaces, retiredPackages);
+  const undeclaredCandidates = detectUndeclaredTagPrefixes(knownPrefixes);
+  return { workspaces, collisions, undeclaredCandidates, retiredPackages };
+}
+async function loadUserConfig() {
+  let raw;
+  try {
+    raw = await loadConfig();
+  } catch {
+    return void 0;
+  }
+  if (raw === void 0) return void 0;
+  const { config, errors } = validateConfig(raw);
+  return errors.length === 0 ? config : void 0;
+}
+function buildOverrideMap(userConfig) {
+  const map = /* @__PURE__ */ new Map();
+  if (userConfig?.workspaces === void 0) return map;
+  for (const entry of userConfig.workspaces) {
+    if (entry.legacyIdentities !== void 0) {
+      map.set(entry.dir, entry.legacyIdentities);
+    }
+  }
+  return map;
+}
+function buildPreviewRow(workspacePath, overridesByDir) {
+  const dir = basename(workspacePath);
+  let derivedPrefix = null;
+  let derivationError = null;
+  try {
+    derivedPrefix = deriveWorkspaceConfig(workspacePath).tagPrefix;
+  } catch (error) {
+    derivationError = error instanceof Error ? error.message : String(error);
+  }
+  const derivedTagCount = derivedPrefix === null ? 0 : countTagsMatching(derivedPrefix);
+  const declaredIdentities = overridesByDir.get(dir) ?? [];
+  const legacyEntries = declaredIdentities.map((identity) => ({
+    prefix: identity.tagPrefix,
+    tagCount: countTagsMatching(identity.tagPrefix)
+  }));
+  return {
+    workspacePath,
+    dir,
+    derivedPrefix,
+    derivationError,
+    derivedTagCount,
+    legacyEntries
+  };
+}
+function countTagsMatching(prefix) {
+  try {
+    const output = execFileSync("git", ["tag", "--list", `${prefix}*`], {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return output.split("\n").filter((line) => line.trim() !== "").length;
+  } catch {
+    return 0;
+  }
+}
+function detectCollisions(rows) {
+  const pathsByPrefix = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.derivedPrefix === null) continue;
+    const existing = pathsByPrefix.get(row.derivedPrefix);
+    if (existing === void 0) {
+      pathsByPrefix.set(row.derivedPrefix, [row.workspacePath]);
+    } else {
+      existing.push(row.workspacePath);
+    }
+  }
+  const collisions = [];
+  for (const [tagPrefix, workspacePaths] of pathsByPrefix) {
+    if (workspacePaths.length > 1) {
+      collisions.push({ tagPrefix, workspacePaths });
+    }
+  }
+  return collisions;
+}
+function collectKnownPrefixes(rows, retiredPackages) {
+  const known = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    if (row.derivedPrefix !== null) known.add(row.derivedPrefix);
+    for (const entry of row.legacyEntries) {
+      known.add(entry.prefix);
+    }
+  }
+  for (const retired of retiredPackages) {
+    known.add(retired.tagPrefix);
+  }
+  return [...known];
+}
+function buildRetiredPreviewEntries(retiredPackages) {
+  return retiredPackages.map((retired) => ({
+    name: retired.name,
+    tagPrefix: retired.tagPrefix,
+    tagCount: countTagsMatching(retired.tagPrefix),
+    ...retired.successor !== void 0 ? { successor: retired.successor } : {}
+  }));
+}
+export {
+  previewTagPrefixes
+};

package/dist/esm/propagateBumps.d.ts

@@ -3,6 +3,7 @@ import type { PropagationSource, ReleaseType } from './types.ts';
 export interface ReleaseEntry {
     releaseType: ReleaseType;
     propagatedFrom?: PropagationSource[];
+    newVersionOverride?: string;
 }
 export type CurrentVersions = Map<string, string>;
 export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph, currentVersions: CurrentVersions): Map<string, ReleaseEntry>;

package/dist/esm/propagateBumps.js

@@ -24,7 +24,7 @@ function propagateBumps(directBumps, graph, currentVersions) {
     if (currentVersion === void 0 || entry === void 0) {
       continue;
     }
-    const newVersion = bumpVersion(currentVersion, entry.releaseType);
+    const newVersion = entry.newVersionOverride ?? bumpVersion(currentVersion, entry.releaseType);
     const dependents = graph.dependentsOf.get(packageName);
     if (dependents === void 0) {
       continue;

package/dist/esm/publishCommand.js

@@ -1,9 +1,9 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { parseArgs, translateParseError } from "@williamthorsen/node-monorepo-core";
-import { createGithubReleases } from "./createGithubRelease.js";
+import { parseArgs, translateParseError } from "@williamthorsen/nmr-core";
 import { detectPackageManager } from "./detectPackageManager.js";
 import { injectReleaseNotesIntoReadme, resolveReadmePath } from "./injectReleaseNotesIntoReadme.js";
+import { parseRequestedTags } from "./parseRequestedTags.js";
 import { publishPackage } from "./publish.js";
 import { resolveCommandTags } from "./resolveCommandTags.js";
 import { resolveReleaseNotesConfig } from "./resolveReleaseNotesConfig.js";
@@ -11,7 +11,7 @@ const publishFlagSchema = {
   dryRun: { long: "--dry-run", type: "boolean" },
   noGitChecks: { long: "--no-git-checks", type: "boolean" },
   provenance: { long: "--provenance", type: "boolean" },
-  only: { long: "--only", type: "string" }
+  tags: { long: "--tags", type: "string" }
 };
 async function publishCommand(argv) {
   let parsed;
@@ -22,13 +22,13 @@ async function publishCommand(argv) {
     process.exit(1);
   }
   const { dryRun, noGitChecks, provenance } = parsed.flags;
-  const only = parsed.flags.only?.split(",");
-  const resolvedTags = await resolveCommandTags(only);
+  const requestedTags = parseRequestedTags(parsed.flags.tags);
+  const resolvedTags = await resolveCommandTags(requestedTags);
   if (resolvedTags.length === 0) {
     return;
   }
   const packageManager = detectPackageManager();
-  const { releaseNotes, changelogJsonOutputPath } = await resolveReleaseNotesConfig();
+  const { releaseNotes, changelogJsonOutputPath, sectionOrder } = await resolveReleaseNotesConfig();
   const shouldInject = releaseNotes.shouldInjectIntoReadme;
   console.info(dryRun ? "[dry-run] Would publish:" : "Publishing:");
   for (const { tag, workspacePath } of resolvedTags) {
@@ -45,7 +45,8 @@ async function publishCommand(argv) {
           originalReadme = injectReleaseNotesIntoReadme(
             readmePath,
             join(resolvedTag.workspacePath, changelogJsonOutputPath),
-            resolvedTag.tag
+            resolvedTag.tag,
+            sectionOrder
           );
         }
       }
@@ -68,12 +69,6 @@ async function publishCommand(argv) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
   }
-  try {
-    createGithubReleases(resolvedTags, releaseNotes, changelogJsonOutputPath, dryRun);
-  } catch (error) {
-    console.error(`Error creating GitHub Releases: ${error instanceof Error ? error.message : String(error)}`);
-    process.exit(1);
-  }
 }
 export {
   publishCommand

package/dist/esm/pushCommand.d.ts

@@ -0,0 +1 @@
+export declare function pushCommand(argv: string[]): Promise<void>;

package/dist/esm/pushCommand.js

@@ -0,0 +1,47 @@
+import { parseArgs, translateParseError } from "@williamthorsen/nmr-core";
+import { parseRequestedTags } from "./parseRequestedTags.js";
+import { pushRelease } from "./pushRelease.js";
+import { resolveCommandTags } from "./resolveCommandTags.js";
+const pushFlagSchema = {
+  dryRun: { long: "--dry-run", type: "boolean" },
+  tags: { long: "--tags", type: "string" },
+  tagsOnly: { long: "--tags-only", type: "boolean" }
+};
+async function pushCommand(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv, pushFlagSchema);
+  } catch (error) {
+    console.error(`Error: ${translateParseError(error)}`);
+    process.exit(1);
+  }
+  const { dryRun, tagsOnly } = parsed.flags;
+  const requestedTags = parseRequestedTags(parsed.flags.tags);
+  const resolvedTags = await resolveCommandTags(requestedTags);
+  if (resolvedTags.length === 0) {
+    return;
+  }
+  const prefix = dryRun ? "[dry-run] Would push" : "Pushing";
+  if (!tagsOnly) {
+    console.info(`${prefix} branch and ${resolvedTags.length} tag(s):`);
+  } else {
+    console.info(`${prefix} ${resolvedTags.length} tag(s):`);
+  }
+  for (const { tag } of resolvedTags) {
+    console.info(`  ${tag}`);
+  }
+  try {
+    const steps = pushRelease(resolvedTags, { dryRun, tagsOnly });
+    if (dryRun) {
+      for (const step of steps) {
+        console.info(`[dry-run] ${step.command.join(" ")}`);
+      }
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+export {
+  pushCommand
+};

package/dist/esm/pushRelease.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedTag } from './resolveReleaseTags.ts';
+export interface PushReleaseOptions {
+    dryRun?: boolean;
+    tagsOnly?: boolean;
+}
+export interface PushStep {
+    type: 'branch' | 'tag';
+    ref: string;
+    command: readonly [string, ...string[]];
+}
+export declare function pushRelease(resolvedTags: ResolvedTag[], options?: PushReleaseOptions): PushStep[];

package/dist/esm/pushRelease.js

@@ -0,0 +1,26 @@
+import { execFileSync } from "node:child_process";
+function pushRelease(resolvedTags, options = {}) {
+  const { dryRun = false, tagsOnly = false } = options;
+  const steps = [];
+  if (!tagsOnly) {
+    const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const command = ["git", "push", "origin", branch];
+    steps.push({ type: "branch", ref: branch, command });
+  }
+  for (const { tag } of resolvedTags) {
+    const command = ["git", "push", "--no-follow-tags", "origin", tag];
+    steps.push({ type: "tag", ref: tag, command });
+  }
+  if (!dryRun) {
+    for (const step of steps) {
+      execFileSync(step.command[0], step.command.slice(1), { stdio: "inherit" });
+    }
+  }
+  return steps;
+}
+export {
+  pushRelease
+};

package/dist/esm/readCurrentVersion.d.ts

@@ -0,0 +1 @@
+export declare function readCurrentVersion(filePath: string): string | undefined;

package/dist/esm/readCurrentVersion.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+function hasVersionField(value) {
+  return typeof value === "object" && value !== null && "version" in value && typeof value.version === "string";
+}
+function readCurrentVersion(filePath) {
+  try {
+    const content = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(content);
+    if (hasVersionField(parsed)) {
+      return parsed.version;
+    }
+  } catch (error) {
+    console.warn(
+      `Failed to read current version from ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  return void 0;
+}
+export {
+  readCurrentVersion
+};

package/dist/esm/releasePrepare.d.ts

@@ -3,5 +3,7 @@ export interface ReleasePrepareOptions {
     dryRun: boolean;
     force?: boolean;
     bumpOverride?: ReleaseType;
+    setVersion?: string;
+    withReleaseNotes?: boolean;
 }
 export declare function releasePrepare(config: ReleaseConfig, options: ReleasePrepareOptions): PrepareResult;

package/dist/esm/releasePrepare.js

@@ -1,46 +1,67 @@
 import { execSync } from "node:child_process";
-import { bumpAllVersions } from "./bumpAllVersions.js";
+import { bumpAllVersions, setAllVersions } from "./bumpAllVersions.js";
+import { isForwardVersion } from "./compareVersions.js";
 import { DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
 import { generateChangelogJson } from "./generateChangelogJson.js";
 import { generateChangelogs } from "./generateChangelogs.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
 import { hasPrettierConfig } from "./hasPrettierConfig.js";
+import { resolveWorkTypes } from "./loadConfig.js";
+import { readCurrentVersion } from "./readCurrentVersion.js";
+import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
+import { writeReleaseNotesPreviews } from "./writeReleaseNotesPreviews.js";
 function releasePrepare(config, options) {
-  const { dryRun, bumpOverride } = options;
+  const { dryRun, bumpOverride, setVersion, withReleaseNotes } = options;
   const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
   const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
-  const { tag, commits } = getCommitsSinceTarget(config.tagPrefix);
+  const { tag, commits } = getCommitsSinceTarget([config.tagPrefix]);
   let releaseType;
   let parsedCommitCount;
   let unparseableCommits;
-  if (bumpOverride === void 0) {
-    const determination = determineBumpFromCommits(commits, workTypes, versionPatterns, config.scopeAliases);
-    parsedCommitCount = determination.parsedCommitCount;
-    unparseableCommits = determination.unparseableCommits;
-    releaseType = determination.releaseType;
+  let bump;
+  if (setVersion !== void 0) {
+    const primaryPackageFile = config.packageFiles[0];
+    if (primaryPackageFile === void 0) {
+      throw new Error("No package files specified");
+    }
+    const currentVersion = readCurrentVersion(primaryPackageFile);
+    if (currentVersion === void 0) {
+      throw new Error(`Cannot validate --set-version: failed to read current version from ${primaryPackageFile}`);
+    }
+    if (!isForwardVersion(currentVersion, setVersion)) {
+      throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
+    }
+    bump = setAllVersions(config.packageFiles, setVersion, dryRun);
   } else {
-    releaseType = bumpOverride;
-  }
-  if (releaseType === void 0) {
-    return {
-      components: [
-        {
-          status: "skipped",
-          previousTag: tag,
-          commitCount: commits.length,
-          parsedCommitCount,
-          unparseableCommits,
-          bumpedFiles: [],
-          changelogFiles: [],
-          skipReason: "No release-worthy changes found. Skipping."
-        }
-      ],
-      tags: [],
-      dryRun
-    };
+    if (bumpOverride === void 0) {
+      const determination = determineBumpFromCommits(commits, workTypes, versionPatterns, config.scopeAliases);
+      parsedCommitCount = determination.parsedCommitCount;
+      unparseableCommits = determination.unparseableCommits;
+      releaseType = determination.releaseType;
+    } else {
+      releaseType = bumpOverride;
+    }
+    if (releaseType === void 0) {
+      return {
+        workspaces: [
+          {
+            status: "skipped",
+            previousTag: tag,
+            commitCount: commits.length,
+            parsedCommitCount,
+            unparseableCommits,
+            bumpedFiles: [],
+            changelogFiles: [],
+            skipReason: "No release-worthy changes found. Skipping."
+          }
+        ],
+        tags: [],
+        dryRun
+      };
+    }
+    bump = bumpAllVersions(config.packageFiles, releaseType, dryRun);
   }
-  const bump = bumpAllVersions(config.packageFiles, releaseType, dryRun);
   const newTag = `${config.tagPrefix}${bump.newVersion}`;
   const changelogFiles = generateChangelogs(config, newTag, dryRun);
   const changelogJsonFiles = [];
@@ -49,6 +70,7 @@ function releasePrepare(config, options) {
       changelogJsonFiles.push(...generateChangelogJson(config, changelogPath, newTag, dryRun));
     }
   }
+  maybeWriteSinglePackagePreviews(withReleaseNotes === true, config, newTag, changelogJsonFiles[0], dryRun);
   const formatCommandStr = config.formatCommand ?? (hasPrettierConfig() ? "npx prettier --write" : void 0);
   let formatCommand;
   if (formatCommandStr !== void 0) {
@@ -72,7 +94,7 @@ function releasePrepare(config, options) {
     }
   }
   return {
-    components: [
+    workspaces: [
       {
         status: "released",
         previousTag: tag,
@@ -85,7 +107,8 @@ function releasePrepare(config, options) {
         bumpedFiles: bump.files,
         changelogFiles,
         commits,
-        unparseableCommits
+        unparseableCommits,
+        ...setVersion === void 0 ? {} : { setVersion }
       }
     ],
     tags: [newTag],
@@ -93,6 +116,25 @@ function releasePrepare(config, options) {
     dryRun
   };
 }
+function maybeWriteSinglePackagePreviews(withReleaseNotes, config, newTag, changelogJsonPath, dryRun) {
+  if (!withReleaseNotes) {
+    return;
+  }
+  if (!config.changelogJson.enabled) {
+    console.warn("Warning: --with-release-notes requires changelogJson.enabled; skipping preview generation");
+    return;
+  }
+  if (changelogJsonPath === void 0) {
+    return;
+  }
+  writeReleaseNotesPreviews({
+    workspacePath: process.cwd(),
+    tag: newTag,
+    changelogJsonPath,
+    sectionOrder: deriveSectionOrder(resolveWorkTypes(config.workTypes)),
+    dryRun
+  });
+}
 export {
   releasePrepare
 };