@ucdjs/release-scripts 0.1.0-beta.6 → 0.1.0-beta.60

package/dist/index.mjs

@@ -1,39 +1,101 @@
-import { t as Eta } from "./eta-Boh7yPZi.mjs";
-import { getCommits } from "commit-parser";
+import { t as Eta } from "./eta-DAZlmVBQ.mjs";
 import process from "node:process";
+import readline from "node:readline";
+import { parseArgs } from "node:util";
 import farver from "farver";
 import { exec } from "tinyexec";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { getCommits, groupByType } from "commit-parser";
 import { dedent } from "@luxass/utils";
-import { join } from "node:path";
-import { readFile, writeFile } from "node:fs/promises";
+import semver, { gt } from "semver";
 import prompts from "prompts";
 
-//#region src/publish.ts
-function publish(_options) {}
-
-//#endregion
-//#region src/utils.ts
-const globalOptions = {
-	dryRun: false,
-	verbose: false
-};
-const isCI = typeof process.env.CI === "string" && process.env.CI !== "" && process.env.CI.toLowerCase() !== "false";
+//#region src/shared/utils.ts
+const ucdjsReleaseOverridesPath = ".github/ucdjs-release.overrides.json";
+function parseCLIFlags() {
+	const { values } = parseArgs({
+		args: process.argv.slice(2),
+		options: {
+			dry: {
+				type: "boolean",
+				short: "d",
+				default: false
+			},
+			verbose: {
+				type: "boolean",
+				short: "v",
+				default: false
+			},
+			force: {
+				type: "boolean",
+				short: "f",
+				default: false
+			}
+		},
+		strict: false
+	});
+	return {
+		dry: !!values.dry,
+		verbose: !!values.verbose,
+		force: !!values.force
+	};
+}
+function getIsDryRun() {
+	return parseCLIFlags().dry;
+}
+function getIsVerbose() {
+	return parseCLIFlags().verbose;
+}
+function getIsCI() {
+	const ci = process.env.CI;
+	return typeof ci === "string" && ci !== "" && ci.toLowerCase() !== "false";
+}
 const logger = {
 	info: (...args) => {
-		console.info(farver.cyan("[info]:"), ...args);
-	},
-	debug: (...args) => {
-		console.debug(farver.gray("[debug]:"), ...args);
+		console.info(...args);
 	},
 	warn: (...args) => {
-		console.warn(farver.yellow("[warn]:"), ...args);
+		console.warn(`  ${farver.yellow("⚠")}`, ...args);
 	},
 	error: (...args) => {
-		console.error(farver.red("[error]:"), ...args);
+		console.error(`  ${farver.red("✖")}`, ...args);
 	},
-	log: (...args) => {
-		if (!globalOptions.verbose) return;
+	verbose: (...args) => {
+		if (!getIsVerbose()) return;
+		if (args.length === 0) {
+			console.log();
+			return;
+		}
+		if (args.length > 1 && typeof args[0] === "string") {
+			console.log(farver.dim(args[0]), ...args.slice(1));
+			return;
+		}
 		console.log(...args);
+	},
+	section: (title) => {
+		console.log();
+		console.log(`  ${farver.bold(title)}`);
+		console.log(`  ${farver.gray("─".repeat(title.length + 2))}`);
+	},
+	emptyLine: () => {
+		console.log();
+	},
+	item: (message, ...args) => {
+		console.log(`  ${message}`, ...args);
+	},
+	step: (message) => {
+		console.log(`  ${farver.blue("→")} ${message}`);
+	},
+	success: (message) => {
+		console.log(`  ${farver.green("✓")} ${message}`);
+	},
+	clearScreen: () => {
+		const repeatCount = process.stdout.rows - 2;
+		const blank = repeatCount > 0 ? "\n".repeat(repeatCount) : "";
+		console.log(blank);
+		readline.cursorTo(process.stdout, 0, 0);
+		readline.clearScreenDown(process.stdout);
 	}
 };
 async function run(bin, args, opts = {}) {
@@ -47,308 +109,224 @@ async function run(bin, args, opts = {}) {
 	});
 }
 async function dryRun(bin, args, opts) {
-	return logger.log(farver.blue(`[dryrun] ${bin} ${args.join(" ")}`), opts || "");
-}
-const runIfNotDry = globalOptions.dryRun ? dryRun : run;
-function exitWithError(message, hint) {
-	logger.error(farver.bold(message));
-	if (hint) console.error(farver.gray(`  ${hint}`));
-	process.exit(1);
-}
-function normalizeSharedOptions(options) {
-	const { workspaceRoot = process.cwd(), githubToken = "", verbose = false, repo, packages = true, prompts: prompts$1 = {
-		packages: true,
-		versions: true
-	},...rest } = options;
-	globalOptions.verbose = verbose;
-	if (!githubToken.trim()) exitWithError("GitHub token is required", "Set GITHUB_TOKEN environment variable or pass it in options");
-	if (!repo || !repo.trim() || !repo.includes("/")) exitWithError("Repository (repo) is required", "Specify the repository in 'owner/repo' format (e.g., 'octocat/hello-world')");
-	const [owner, name] = options.repo.split("/");
-	if (!owner || !name) exitWithError(`Invalid repo format: "${options.repo}"`, "Expected format: \"owner/repo\" (e.g., \"octocat/hello-world\")");
-	return {
-		...rest,
-		packages,
-		prompts: prompts$1,
-		workspaceRoot,
-		githubToken,
-		owner,
-		repo,
-		verbose
-	};
+	return logger.verbose(farver.blue(`[dryrun] ${bin} ${args.join(" ")}`), opts || "");
+}
+async function runIfNotDry(bin, args, opts) {
+	return getIsDryRun() ? dryRun(bin, args, opts) : run(bin, args, opts);
 }
 
 //#endregion
-//#region src/commits.ts
-async function getLastPackageTag(packageName, workspaceRoot) {
-	try {
-		const { stdout } = await run("git", ["tag", "--list"], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} });
-		return stdout.split("\n").map((tag) => tag.trim()).filter(Boolean).reverse().find((tag) => tag.startsWith(`${packageName}@`));
-	} catch (err) {
-		logger.warn(`Failed to get tags for package ${packageName}: ${err.message}`);
-		return;
+//#region src/shared/errors.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function toTrimmedString(value) {
+	if (typeof value === "string") {
+		const normalized = value.trim();
+		return normalized.length > 0 ? normalized : void 0;
+	}
+	if (value instanceof Uint8Array) {
+		const normalized = new TextDecoder().decode(value).trim();
+		return normalized.length > 0 ? normalized : void 0;
+	}
+	if (isRecord(value) && typeof value.toString === "function") {
+		const rendered = value.toString();
+		if (typeof rendered === "string" && rendered !== "[object Object]") {
+			const normalized = rendered.trim();
+			return normalized.length > 0 ? normalized : void 0;
+		}
 	}
 }
-function determineHighestBump(commits) {
-	if (commits.length === 0) return "none";
-	let highestBump = "none";
-	for (const commit of commits) {
-		const bump = determineBumpType(commit);
-		if (bump === "major") return "major";
-		if (bump === "minor") highestBump = "minor";
-		else if (bump === "patch" && highestBump === "none") highestBump = "patch";
+function getNestedField(record, keys) {
+	let current = record;
+	for (const key of keys) {
+		if (!isRecord(current) || !(key in current)) return;
+		current = current[key];
 	}
-	return highestBump;
+	return current;
 }
-/**
-* Retrieves commits that affect a specific workspace package since its last tag.
-*
-* @param {string} workspaceRoot - The root directory of the workspace.
-* @param {WorkspacePackage} pkg - The workspace package to analyze.
-* @returns {Promise<GitCommit[]>} A promise that resolves to an array of GitCommit objects affecting the package.
-*/
-async function getCommitsForWorkspacePackage(workspaceRoot, pkg) {
-	const lastTag = await getLastPackageTag(pkg.name, workspaceRoot);
-	const allCommits = getCommits({
-		from: lastTag,
-		to: "HEAD",
-		cwd: workspaceRoot
-	});
-	logger.log(`Found ${allCommits.length} commits for ${pkg.name} since ${lastTag || "beginning"}`);
-	const touchedCommitHashes = getCommits({
-		from: lastTag,
-		to: "HEAD",
-		cwd: workspaceRoot,
-		folder: pkg.path
-	});
-	const touchedSet = new Set(touchedCommitHashes);
-	const packageCommits = allCommits.filter((commit) => touchedSet.has(commit));
-	logger.log(`${packageCommits.length} commits affect ${pkg.name}`);
-	return packageCommits;
+function extractStderrLike(record) {
+	const candidates = [
+		record.stderr,
+		record.stdout,
+		record.shortMessage,
+		record.originalMessage,
+		getNestedField(record, ["result", "stderr"]),
+		getNestedField(record, ["result", "stdout"]),
+		getNestedField(record, ["output", "stderr"]),
+		getNestedField(record, ["output", "stdout"]),
+		getNestedField(record, ["cause", "stderr"]),
+		getNestedField(record, ["cause", "stdout"]),
+		getNestedField(record, ["cause", "shortMessage"]),
+		getNestedField(record, ["cause", "originalMessage"])
+	];
+	for (const candidate of candidates) {
+		const rendered = toTrimmedString(candidate);
+		if (rendered) return rendered;
+	}
 }
-async function getWorkspacePackageCommits(workspaceRoot, packages) {
-	const changedPackages = /* @__PURE__ */ new Map();
-	const promises = packages.map(async (pkg) => {
-		return {
-			pkgName: pkg.name,
-			commits: await getCommitsForWorkspacePackage(workspaceRoot, pkg)
+function formatUnknownError(error) {
+	if (error instanceof Error) {
+		const base = {
+			message: error.message || error.name,
+			stack: error.stack
 		};
-	});
-	const results = await Promise.all(promises);
-	for (const { pkgName, commits } of results) changedPackages.set(pkgName, commits);
-	return changedPackages;
-}
-function determineBumpType(commit) {
-	if (commit.isBreaking) return "major";
-	if (!commit.isConventional || !commit.type) return "none";
-	switch (commit.type) {
-		case "feat": return "minor";
-		case "fix":
-		case "perf": return "patch";
-		case "docs":
-		case "style":
-		case "refactor":
-		case "test":
-		case "build":
-		case "ci":
-		case "chore":
-		case "revert": return "none";
-		default: return "none";
+		const maybeError = error;
+		if (typeof maybeError.code === "string") base.code = maybeError.code;
+		if (typeof maybeError.status === "number") base.status = maybeError.status;
+		base.stderr = extractStderrLike(maybeError);
+		if (typeof maybeError.shortMessage === "string" && maybeError.shortMessage.trim() && base.message.startsWith("Process exited with non-zero status")) base.message = maybeError.shortMessage.trim();
+		if (!base.stderr && typeof maybeError.cause === "string" && maybeError.cause.trim()) base.stderr = maybeError.cause.trim();
+		return base;
 	}
-}
-
-//#endregion
-//#region src/git.ts
-/**
-* Check if the working directory is clean (no uncommitted changes)
-* @param {string} workspaceRoot - The root directory of the workspace
-* @returns {Promise<boolean>} A Promise resolving to true if clean, false otherwise
-*/
-async function isWorkingDirectoryClean(workspaceRoot) {
-	try {
-		if ((await run("git", ["status", "--porcelain"], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} })).stdout.trim() !== "") return false;
-		return true;
-	} catch (err) {
-		logger.error("Error checking git status:", err);
-		return false;
+	if (typeof error === "string") return { message: error };
+	if (isRecord(error)) {
+		const formatted = { message: typeof error.message === "string" ? error.message : typeof error.error === "string" ? error.error : JSON.stringify(error) };
+		if (typeof error.code === "string") formatted.code = error.code;
+		if (typeof error.status === "number") formatted.status = error.status;
+		formatted.stderr = extractStderrLike(error);
+		return formatted;
 	}
+	return { message: String(error) };
 }
-/**
-* Check if a git branch exists locally
-* @param {string} branch - The branch name to check
-* @param {string} workspaceRoot - The root directory of the workspace
-* @returns {Promise<boolean>} Promise resolving to true if branch exists, false otherwise
-*/
-async function doesBranchExist(branch, workspaceRoot) {
-	try {
-		await run("git", [
-			"rev-parse",
-			"--verify",
-			branch
-		], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} });
-		return true;
-	} catch {
-		return false;
+var ReleaseError = class extends Error {
+	hint;
+	constructor(message, hint, cause) {
+		super(message);
+		this.name = "ReleaseError";
+		this.hint = hint;
+		this.cause = cause;
 	}
-}
-/**
-* Pull latest changes from remote branch
-* @param branch - The branch name to pull from
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to true if pull succeeded, false otherwise
-*/
-async function pullLatestChanges(branch, workspaceRoot) {
-	try {
-		await run("git", [
-			"pull",
-			"origin",
-			branch
-		], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} });
-		return true;
-	} catch {
-		return false;
+};
+function printReleaseError(error) {
+	console.error(`  ${farver.red("✖")} ${farver.bold(error.message)}`);
+	if (error.cause !== void 0) {
+		const formatted = formatUnknownError(error.cause);
+		if (formatted.message && formatted.message !== error.message) console.error(farver.gray(`  Cause: ${formatted.message}`));
+		if (formatted.code) console.error(farver.gray(`  Code: ${formatted.code}`));
+		if (typeof formatted.status === "number") console.error(farver.gray(`  Status: ${formatted.status}`));
+		if (formatted.stderr) {
+			console.error(farver.gray("  Stderr:"));
+			console.error(farver.gray(`  ${formatted.stderr}`));
+		}
+		if (getIsVerbose() && formatted.stack) {
+			console.error(farver.gray("  Stack:"));
+			console.error(farver.gray(`  ${formatted.stack}`));
+		}
 	}
+	if (error.hint) console.error(farver.gray(`  ${error.hint}`));
 }
-/**
-* Create a new git branch
-* @param branch - The new branch name
-* @param base - The base branch to create from
-* @param workspaceRoot - The root directory of the workspace
-*/
-async function createBranch(branch, base, workspaceRoot) {
-	await runIfNotDry("git", [
-		"checkout",
-		"-b",
-		branch,
-		base
-	], { nodeOptions: { cwd: workspaceRoot } });
+function exitWithError(message, hint, cause) {
+	throw new ReleaseError(message, hint, cause);
 }
-/**
-* Checkout a git branch
-* @param branch - The branch name to checkout
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to true if checkout succeeded, false otherwise
-*/
-async function checkoutBranch(branch, workspaceRoot) {
-	try {
-		await run("git", ["checkout", branch], { nodeOptions: { cwd: workspaceRoot } });
-		return true;
-	} catch {
-		return false;
+
+//#endregion
+//#region src/operations/changelog-format.ts
+function formatCommitLine({ commit, owner, repo, authors }) {
+	const commitUrl = `https://github.com/${owner}/${repo}/commit/${commit.hash}`;
+	let line = `${commit.description}`;
+	const references = commit.references ?? [];
+	for (const ref of references) {
+		if (!ref.value) continue;
+		const number = Number.parseInt(ref.value.replace(/^#/, ""), 10);
+		if (Number.isNaN(number)) continue;
+		if (ref.type === "issue") {
+			line += ` ([Issue ${ref.value}](https://github.com/${owner}/${repo}/issues/${number}))`;
+			continue;
+		}
+		line += ` ([PR ${ref.value}](https://github.com/${owner}/${repo}/pull/${number}))`;
 	}
-}
-/**
-* Get the current branch name
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to the current branch name
-*/
-async function getCurrentBranch(workspaceRoot) {
-	return (await run("git", [
-		"rev-parse",
-		"--abbrev-ref",
-		"HEAD"
-	], { nodeOptions: {
-		cwd: workspaceRoot,
-		stdio: "pipe"
-	} })).stdout.trim();
-}
-/**
-* Rebase current branch onto another branch
-* @param ontoBranch - The target branch to rebase onto
-* @param workspaceRoot - The root directory of the workspace
-*/
-async function rebaseBranch(ontoBranch, workspaceRoot) {
-	await run("git", ["rebase", ontoBranch], { nodeOptions: { cwd: workspaceRoot } });
-}
-/**
-* Check if local branch is ahead of remote (has commits to push)
-* @param branch - The branch name to check
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to true if local is ahead, false otherwise
-*/
-async function isBranchAheadOfRemote(branch, workspaceRoot) {
-	try {
-		const result = await run("git", [
-			"rev-list",
-			`origin/${branch}..${branch}`,
-			"--count"
-		], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} });
-		return Number.parseInt(result.stdout.trim(), 10) > 0;
-	} catch {
-		return true;
+	line += ` ([${commit.shortHash}](${commitUrl}))`;
+	if (authors.length > 0) {
+		const authorList = authors.map((author) => author.login ? `[@${author.login}](https://github.com/${author.login})` : author.name).join(", ");
+		line += ` (by ${authorList})`;
 	}
+	return line;
 }
-/**
-* Check if there are any changes to commit (staged or unstaged)
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to true if there are changes, false otherwise
-*/
-async function hasChangesToCommit(workspaceRoot) {
-	return (await run("git", ["status", "--porcelain"], { nodeOptions: {
-		cwd: workspaceRoot,
-		stdio: "pipe"
-	} })).stdout.trim() !== "";
-}
-/**
-* Commit changes with a message
-* @param message - The commit message
-* @param workspaceRoot - The root directory of the workspace
-* @returns Promise resolving to true if commit was made, false if there were no changes
-*/
-async function commitChanges(message, workspaceRoot) {
-	await run("git", ["add", "."], { nodeOptions: { cwd: workspaceRoot } });
-	if (!await hasChangesToCommit(workspaceRoot)) return false;
-	await run("git", [
-		"commit",
-		"-m",
-		message
-	], { nodeOptions: { cwd: workspaceRoot } });
-	return true;
-}
-/**
-* Push branch to remote
-* @param branch - The branch name to push
-* @param workspaceRoot - The root directory of the workspace
-* @param options - Push options
-* @param options.force - Force push (overwrite remote)
-* @param options.forceWithLease - Force push with safety check (won't overwrite unexpected changes)
-*/
-async function pushBranch(branch, workspaceRoot, options) {
-	const args = [
-		"push",
-		"origin",
-		branch
-	];
-	if (options?.forceWithLease) args.push("--force-with-lease");
-	else if (options?.force) args.push("--force");
-	await run("git", args, { nodeOptions: { cwd: workspaceRoot } });
+function buildTemplateGroups(options) {
+	const { commits, owner, repo, types, commitAuthors } = options;
+	const grouped = groupByType(commits, {
+		includeNonConventional: false,
+		mergeKeys: Object.fromEntries(Object.entries(types).map(([key, value]) => [key, value.types ?? [key]]))
+	});
+	return Object.entries(types).map(([key, value]) => {
+		const formattedCommits = (grouped.get(key) ?? []).map((commit) => ({ line: formatCommitLine({
+			commit,
+			owner,
+			repo,
+			authors: commitAuthors.get(commit.hash) ?? []
+		}) }));
+		return {
+			name: key,
+			title: value.title,
+			commits: formattedCommits
+		};
+	});
 }
 
 //#endregion
-//#region src/github.ts
-async function getExistingPullRequest({ owner, repo, branch, githubToken }) {
-	try {
-		const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls?state=open&head=${branch}`, { headers: {
-			Accept: "application/vnd.github.v3+json",
-			Authorization: `token ${githubToken}`
-		} });
-		if (!res.ok) throw new Error(`GitHub API request failed with status ${res.status}`);
-		const pulls = await res.json();
-		if (pulls == null || !Array.isArray(pulls) || pulls.length === 0) return null;
+//#region src/core/github.ts
+function toGitHubError(operation, error) {
+	const formatted = formatUnknownError(error);
+	return {
+		type: "github",
+		operation,
+		message: formatted.message,
+		status: formatted.status
+	};
+}
+var GitHubClient = class {
+	owner;
+	repo;
+	githubToken;
+	apiBase = "https://api.github.com";
+	constructor({ owner, repo, githubToken }) {
+		this.owner = owner;
+		this.repo = repo;
+		this.githubToken = githubToken;
+	}
+	async request(path, init = {}) {
+		const url = path.startsWith("http") ? path : `${this.apiBase}${path}`;
+		const method = init.method ?? "GET";
+		let res;
+		try {
+			res = await fetch(url, {
+				...init,
+				headers: {
+					...init.headers,
+					"Accept": "application/vnd.github.v3+json",
+					"Authorization": `token ${this.githubToken}`,
+					"User-Agent": "ucdjs-release-scripts (+https://github.com/ucdjs/ucdjs-release-scripts)"
+				}
+			});
+		} catch (error) {
+			throw Object.assign(/* @__PURE__ */ new Error(`[${method} ${path}] GitHub request failed: ${formatUnknownError(error).message}`), { status: void 0 });
+		}
+		if (!res.ok) {
+			const errorText = await res.text();
+			const parsedMessage = (() => {
+				try {
+					const parsed = JSON.parse(errorText);
+					if (typeof parsed.message === "string" && parsed.message.trim()) {
+						if (Array.isArray(parsed.errors) && parsed.errors.length > 0) return `${parsed.message} (${JSON.stringify(parsed.errors)})`;
+						return parsed.message;
+					}
+					return errorText;
+				} catch {
+					return errorText;
+				}
+			})();
+			throw Object.assign(/* @__PURE__ */ new Error(`[${method} ${path}] GitHub API request failed (${res.status} ${res.statusText}): ${parsedMessage || "No response body"}`), { status: res.status });
+		}
+		if (res.status === 204) return;
+		return res.json();
+	}
+	async getExistingPullRequest(branch) {
+		const head = branch.includes(":") ? branch : `${this.owner}:${branch}`;
+		const endpoint = `/repos/${this.owner}/${this.repo}/pulls?state=open&head=${encodeURIComponent(head)}`;
+		logger.verbose(`Requesting pull request for branch: ${branch} (url: ${this.apiBase}${endpoint})`);
+		const pulls = await this.request(endpoint);
+		if (!Array.isArray(pulls) || pulls.length === 0) return null;
 		const firstPullRequest = pulls[0];
 		if (typeof firstPullRequest !== "object" || firstPullRequest === null || !("number" in firstPullRequest) || typeof firstPullRequest.number !== "number" || !("title" in firstPullRequest) || typeof firstPullRequest.title !== "string" || !("body" in firstPullRequest) || typeof firstPullRequest.body !== "string" || !("draft" in firstPullRequest) || typeof firstPullRequest.draft !== "boolean" || !("html_url" in firstPullRequest) || typeof firstPullRequest.html_url !== "string") throw new TypeError("Pull request data validation failed");
 		const pullRequest = {
@@ -356,20 +334,15 @@ async function getExistingPullRequest({ owner, repo, branch, githubToken }) {
 			title: firstPullRequest.title,
 			body: firstPullRequest.body,
 			draft: firstPullRequest.draft,
-			html_url: firstPullRequest.html_url
+			html_url: firstPullRequest.html_url,
+			head: "head" in firstPullRequest && typeof firstPullRequest.head === "object" && firstPullRequest.head !== null && "sha" in firstPullRequest.head && typeof firstPullRequest.head.sha === "string" ? { sha: firstPullRequest.head.sha } : void 0
 		};
 		logger.info(`Found existing pull request: ${farver.yellow(`#${pullRequest.number}`)}`);
 		return pullRequest;
-	} catch (err) {
-		logger.error("Error fetching pull request:", err);
-		return null;
 	}
-}
-async function upsertPullRequest({ owner, repo, title, body, head, base, pullNumber, githubToken }) {
-	try {
-		const isUpdate = pullNumber != null;
-		const url = isUpdate ? `https://api.github.com/repos/${owner}/${repo}/pulls/${pullNumber}` : `https://api.github.com/repos/${owner}/${repo}/pulls`;
-		const method = isUpdate ? "PATCH" : "POST";
+	async upsertPullRequest({ title, body, head, base, pullNumber }) {
+		const isUpdate = typeof pullNumber === "number";
+		const endpoint = isUpdate ? `/repos/${this.owner}/${this.repo}/pulls/${pullNumber}` : `/repos/${this.owner}/${this.repo}/pulls`;
 		const requestBody = isUpdate ? {
 			title,
 			body
@@ -377,18 +350,14 @@ async function upsertPullRequest({ owner, repo, title, body, head, base, pullNum
 			title,
 			body,
 			head,
-			base
+			base,
+			draft: true
 		};
-		const res = await fetch(url, {
-			method,
-			headers: {
-				Accept: "application/vnd.github.v3+json",
-				Authorization: `token ${githubToken}`
-			},
+		logger.verbose(`${isUpdate ? "Updating" : "Creating"} pull request (url: ${this.apiBase}${endpoint})`);
+		const pr = await this.request(endpoint, {
+			method: isUpdate ? "PATCH" : "POST",
 			body: JSON.stringify(requestBody)
 		});
-		if (!res.ok) throw new Error(`GitHub API request failed with status ${res.status}`);
-		const pr = await res.json();
 		if (typeof pr !== "object" || pr === null || !("number" in pr) || typeof pr.number !== "number" || !("title" in pr) || typeof pr.title !== "string" || !("body" in pr) || typeof pr.body !== "string" || !("draft" in pr) || typeof pr.draft !== "boolean" || !("html_url" in pr) || typeof pr.html_url !== "string") throw new TypeError("Pull request data validation failed");
 		const action = isUpdate ? "Updated" : "Created";
 		logger.info(`${action} pull request: ${farver.yellow(`#${pr.number}`)}`);
@@ -399,27 +368,97 @@ async function upsertPullRequest({ owner, repo, title, body, head, base, pullNum
 			draft: pr.draft,
 			html_url: pr.html_url
 		};
-	} catch (err) {
-		logger.error(`Error upserting pull request:`, err);
-		throw err;
 	}
+	async setCommitStatus({ sha, state, targetUrl, description, context }) {
+		const endpoint = `/repos/${this.owner}/${this.repo}/statuses/${sha}`;
+		logger.verbose(`Setting commit status on ${sha} to ${state} (url: ${this.apiBase}${endpoint})`);
+		await this.request(endpoint, {
+			method: "POST",
+			body: JSON.stringify({
+				state,
+				target_url: targetUrl,
+				description: description || "",
+				context
+			})
+		});
+		logger.info(`Commit status set to ${farver.cyan(state)} for ${farver.gray(sha.substring(0, 7))}`);
+	}
+	async upsertReleaseByTag({ tagName, name, body, prerelease = false }) {
+		const encodedTag = encodeURIComponent(tagName);
+		let existingRelease = null;
+		try {
+			existingRelease = await this.request(`/repos/${this.owner}/${this.repo}/releases/tags/${encodedTag}`);
+		} catch (error) {
+			if (formatUnknownError(error).status !== 404) throw error;
+		}
+		if (existingRelease) {
+			logger.verbose(`Updating release for tag ${farver.cyan(tagName)}`);
+			const updated = await this.request(`/repos/${this.owner}/${this.repo}/releases/${existingRelease.id}`, {
+				method: "PATCH",
+				body: JSON.stringify({
+					name,
+					body,
+					prerelease,
+					draft: false
+				})
+			});
+			logger.info(`Updated GitHub release for ${farver.cyan(tagName)}`);
+			return {
+				release: {
+					id: updated.id,
+					tagName: updated.tag_name,
+					name: updated.name ?? name,
+					htmlUrl: updated.html_url
+				},
+				created: false
+			};
+		}
+		logger.verbose(`Creating release for tag ${farver.cyan(tagName)}`);
+		const created = await this.request(`/repos/${this.owner}/${this.repo}/releases`, {
+			method: "POST",
+			body: JSON.stringify({
+				tag_name: tagName,
+				name,
+				body,
+				prerelease,
+				draft: false,
+				generate_release_notes: body == null
+			})
+		});
+		logger.info(`Created GitHub release for ${farver.cyan(tagName)}`);
+		return {
+			release: {
+				id: created.id,
+				tagName: created.tag_name,
+				name: created.name ?? name,
+				htmlUrl: created.html_url
+			},
+			created: true
+		};
+	}
+	async resolveAuthorInfo(info) {
+		if (info.login) return info;
+		try {
+			const q = encodeURIComponent(`${info.email} type:user in:email`);
+			const data = await this.request(`/search/users?q=${q}`);
+			if (!data.items || data.items.length === 0) return info;
+			info.login = data.items[0].login;
+		} catch (err) {
+			logger.warn(`Failed to resolve author info for email ${info.email}: ${formatUnknownError(err).message}`);
+		}
+		if (info.login) return info;
+		if (info.commits.length > 0) try {
+			const data = await this.request(`/repos/${this.owner}/${this.repo}/commits/${info.commits[0]}`);
+			if (data.author && data.author.login) info.login = data.author.login;
+		} catch (err) {
+			logger.warn(`Failed to resolve author info from commits for email ${info.email}: ${formatUnknownError(err).message}`);
+		}
+		return info;
+	}
+};
+function createGitHubClient(options) {
+	return new GitHubClient(options);
 }
-const defaultTemplate = dedent`
-  This PR was automatically generated by the release script.
-
-  The following packages have been prepared for release:
-
-  <% it.packages.forEach((pkg) => { %>
-  - **<%= pkg.name %>**: <%= pkg.currentVersion %> → <%= pkg.newVersion %> (<%= pkg.bumpType %>)
-  <% }) %>
-
-  Please review the changes and merge when ready.
-
-  For a more in-depth look at the changes, please refer to the individual package changelogs.
-
-  > [!NOTE]
-  > When this PR is merged, the release process will be triggered automatically, publishing the new package versions to the registry.
-`;
 function dedentString(str) {
 	const lines = str.split("\n");
 	const minIndent = lines.filter((line) => line.trim().length > 0).reduce((min, line) => Math.min(min, line.search(/\S/)), Infinity);
@@ -427,7 +466,7 @@ function dedentString(str) {
 }
 function generatePullRequestBody(updates, body) {
 	const eta = new Eta();
-	const bodyTemplate = body ? dedentString(body) : defaultTemplate;
+	const bodyTemplate = body ? dedentString(body) : DEFAULT_PR_BODY_TEMPLATE;
 	return eta.renderString(bodyTemplate, { packages: updates.map((u) => ({
 		name: u.package.name,
 		currentVersion: u.currentVersion,
@@ -438,100 +477,1255 @@ function generatePullRequestBody(updates, body) {
 }
 
 //#endregion
-//#region src/prompts.ts
-async function selectPackagePrompt(packages) {
-	const response = await prompts({
-		type: "multiselect",
-		name: "selectedPackages",
-		message: "Select packages to release",
-		choices: packages.map((pkg) => ({
-			title: `${pkg.name} (${farver.bold(pkg.version)})`,
-			value: pkg.name,
-			selected: true
-		})),
-		min: 1,
-		hint: "Space to select/deselect. Return to submit.",
-		instructions: false
-	});
-	if (!response.selectedPackages || response.selectedPackages.length === 0) return [];
-	return response.selectedPackages;
-}
-async function promptVersionOverride(pkg, workspaceRoot, currentVersion, suggestedVersion, suggestedBumpType) {
-	const choices = [{
-		title: `Use suggested: ${suggestedVersion} (${suggestedBumpType})`,
-		value: "suggested"
-	}];
-	for (const bumpType of [
-		"patch",
-		"minor",
-		"major"
-	]) if (bumpType !== suggestedBumpType) {
-		const version = getNextVersion(currentVersion, bumpType);
-		choices.push({
-			title: `${bumpType}: ${version}`,
-			value: bumpType
-		});
+//#region src/options.ts
+const DEFAULT_PR_BODY_TEMPLATE = dedent`
+  This PR was automatically generated by the UCD release scripts.
+
+  The following packages have been prepared for release:
+
+  <% if (it.packages.length > 0) { %>
+  <% it.packages.forEach((pkg) => { %>
+  - **<%= pkg.name %>**: <%= pkg.currentVersion %> → <%= pkg.newVersion %> (<%= pkg.bumpType %>)
+  <% }) %>
+  <% } else { %>
+  There are no packages to release.
+  <% } %>
+
+  Please review the changes and merge when ready.
+
+  > [!NOTE]
+  > When this PR is merged, the release process will be triggered automatically, publishing the new package versions to the registry.
+`;
+const DEFAULT_CHANGELOG_TEMPLATE = dedent`
+  <% if (it.previousVersion) { -%>
+  ## [<%= it.version %>](<%= it.compareUrl %>) (<%= it.date %>)
+  <% } else { -%>
+  ## <%= it.version %> (<%= it.date %>)
+  <% } %>
+  <% let hasCommits = false; %>
+
+  <% it.groups.forEach((group) => { %>
+  <% if (group.commits.length > 0) { %>
+  <% hasCommits = true; %>
+
+  ### <%= group.title %>
+  <% group.commits.forEach((commit) => { %>
+
+  * <%= commit.line %>
+  <% }); %>
+
+  <% } %>
+  <% }); %>
+
+  <% if (!hasCommits) { %>
+  *No significant changes*
+
+  ##### &nbsp;&nbsp;&nbsp;&nbsp;[View changes on GitHub](<%= it.compareUrl %>)
+  <% } %>
+`;
+const DEFAULT_TYPES = {
+	feat: { title: "🚀 Features" },
+	fix: { title: "🐞 Bug Fixes" },
+	perf: { title: "🏎 Performance" },
+	docs: { title: "📚 Documentation" },
+	style: { title: "🎨 Styles" }
+};
+function normalizeReleaseScriptsOptions(options) {
+	const { workspaceRoot = process.cwd(), githubToken = "", repo: fullRepo, packages = true, branch = {}, globalCommitMode = "dependencies", pullRequest = {}, changelog = {}, types, safeguards = true, dryRun = false, npm = {}, prompts = {} } = options;
+	const token = githubToken.trim();
+	if (!token) throw new Error("GitHub token is required. Pass it in via options.");
+	if (!fullRepo || !fullRepo.trim() || !fullRepo.includes("/")) throw new Error("Repository (repo) is required. Specify in 'owner/repo' format (e.g., 'octocat/hello-world').");
+	const [owner, repo] = fullRepo.split("/");
+	if (!owner || !repo) throw new Error(`Invalid repo format: "${fullRepo}". Expected format: "owner/repo" (e.g., "octocat/hello-world").`);
+	const normalizedPackages = typeof packages === "object" && !Array.isArray(packages) ? {
+		exclude: packages.exclude ?? [],
+		include: packages.include ?? [],
+		excludePrivate: packages.excludePrivate ?? false
+	} : packages;
+	const isCI = process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true";
+	return {
+		dryRun,
+		workspaceRoot,
+		githubToken: token,
+		owner,
+		repo,
+		githubClient: createGitHubClient({
+			owner,
+			repo,
+			githubToken: token
+		}),
+		packages: normalizedPackages,
+		branch: {
+			release: branch.release ?? "release/next",
+			default: branch.default ?? "main"
+		},
+		globalCommitMode,
+		safeguards,
+		pullRequest: {
+			title: pullRequest.title ?? "chore: release new version",
+			body: pullRequest.body ?? DEFAULT_PR_BODY_TEMPLATE
+		},
+		changelog: {
+			enabled: changelog.enabled ?? true,
+			template: changelog.template ?? DEFAULT_CHANGELOG_TEMPLATE,
+			emojis: changelog.emojis ?? true,
+			combinePrereleaseIntoFirstStable: changelog.combinePrereleaseIntoFirstStable ?? false
+		},
+		types: types ? {
+			...DEFAULT_TYPES,
+			...types
+		} : DEFAULT_TYPES,
+		npm: {
+			otp: npm.otp,
+			provenance: npm.provenance ?? true,
+			access: npm.access ?? "public"
+		},
+		prompts: {
+			versions: prompts.versions ?? !isCI,
+			packages: prompts.packages ?? !isCI
+		}
+	};
+}
+
+//#endregion
+//#region src/types.ts
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+
+//#endregion
+//#region src/core/git.ts
+function toGitError(operation, error) {
+	const formatted = formatUnknownError(error);
+	return {
+		type: "git",
+		operation,
+		message: formatted.message,
+		stderr: formatted.stderr
+	};
+}
+function isMissingGitIdentityError(error) {
+	const formatted = formatUnknownError(error);
+	const combined = `${formatted.message}\n${formatted.stderr ?? ""}`;
+	return combined.includes("Author identity unknown") || combined.includes("empty ident name") || combined.includes("Please tell me who you are");
+}
+async function ensureLocalGitIdentity(workspaceRoot) {
+	try {
+		const actor = process.env.GITHUB_ACTOR?.trim();
+		const name = process.env.GIT_AUTHOR_NAME?.trim() || process.env.GIT_COMMITTER_NAME?.trim() || actor || "github-actions[bot]";
+		const email = process.env.GIT_AUTHOR_EMAIL?.trim() || process.env.GIT_COMMITTER_EMAIL?.trim() || (actor ? `${actor}@users.noreply.github.com` : "github-actions[bot]@users.noreply.github.com");
+		logger.warn("Git author identity missing. Configuring repository-local git identity for this run.");
+		await runIfNotDry("git", [
+			"config",
+			"user.name",
+			name
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		await runIfNotDry("git", [
+			"config",
+			"user.email",
+			email
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		logger.info(`Configured git identity: ${farver.dim(`${name} <${email}>`)}`);
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("ensureLocalGitIdentity", error));
+	}
+}
+async function commitWithRetryOnMissingIdentity(message, workspaceRoot, operation) {
+	const runCommit = async () => runIfNotDry("git", [
+		"commit",
+		"-m",
+		message
+	], { nodeOptions: {
+		cwd: workspaceRoot,
+		stdio: "pipe"
+	} });
+	try {
+		await runCommit();
+		return ok(void 0);
+	} catch (error) {
+		if (!isMissingGitIdentityError(error)) return err(toGitError(operation, error));
+		const configured = await ensureLocalGitIdentity(workspaceRoot);
+		if (!configured.ok) return configured;
+		try {
+			await runCommit();
+			return ok(void 0);
+		} catch (retryError) {
+			return err(toGitError(operation, retryError));
+		}
+	}
+}
+async function isWorkingDirectoryClean(workspaceRoot) {
+	try {
+		return ok((await run("git", ["status", "--porcelain"], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} })).stdout.trim() === "");
+	} catch (error) {
+		return err(toGitError("isWorkingDirectoryClean", error));
+	}
+}
+/**
+* Check if a git branch exists locally
+* @param {string} branch - The branch name to check
+* @param {string} workspaceRoot - The root directory of the workspace
+* @returns {Promise<boolean>} Promise resolving to true if branch exists, false otherwise
+*/
+async function doesBranchExist(branch, workspaceRoot) {
+	try {
+		await run("git", [
+			"rev-parse",
+			"--verify",
+			branch
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(true);
+	} catch (error) {
+		logger.verbose(`Failed to verify branch "${branch}": ${formatUnknownError(error).message}`);
+		return ok(false);
+	}
+}
+/**
+* Retrieves the name of the current branch in the repository.
+* @param {string} workspaceRoot - The root directory of the workspace
+* @returns {Promise<string>} A Promise resolving to the current branch name as a string
+*/
+async function getCurrentBranch(workspaceRoot) {
+	try {
+		return ok((await run("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} })).stdout.trim());
+	} catch (error) {
+		return err(toGitError("getCurrentBranch", error));
+	}
+}
+/**
+* Creates a new branch from the specified base branch.
+* @param {string} branch - The name of the new branch to create
+* @param {string} base - The base branch to create the new branch from
+* @param {string} workspaceRoot - The root directory of the workspace
+* @returns {Promise<void>} A Promise that resolves when the branch is created
+*/
+async function createBranch(branch, base, workspaceRoot) {
+	try {
+		logger.info(`Creating branch: ${farver.green(branch)} from ${farver.cyan(base)}`);
+		await runIfNotDry("git", [
+			"branch",
+			branch,
+			base
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("createBranch", error));
+	}
+}
+async function checkoutBranch(branch, workspaceRoot) {
+	try {
+		logger.info(`Switching to branch: ${farver.green(branch)}`);
+		const output = (await run("git", ["checkout", branch], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} })).stderr.trim();
+		const match = output.match(/Switched to (?:a new )?branch '(.+)'/);
+		if (match && match[1] === branch) {
+			logger.info(`Successfully switched to branch: ${farver.green(branch)}`);
+			return ok(true);
+		}
+		logger.warn(`Unexpected git checkout output: ${output}`);
+		return ok(false);
+	} catch (error) {
+		const gitError = toGitError("checkoutBranch", error);
+		logger.error(`Git checkout failed: ${gitError.message}`);
+		if (gitError.stderr) logger.error(`Git stderr: ${gitError.stderr}`);
+		try {
+			const branchResult = await run("git", ["branch", "-a"], { nodeOptions: {
+				cwd: workspaceRoot,
+				stdio: "pipe"
+			} });
+			logger.verbose(`Available branches:\n${branchResult.stdout}`);
+		} catch (error) {
+			logger.verbose(`Could not list available branches: ${formatUnknownError(error).message}`);
+		}
+		return err(gitError);
+	}
+}
+async function pullLatestChanges(branch, workspaceRoot) {
+	try {
+		await run("git", [
+			"pull",
+			"origin",
+			branch
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(true);
+	} catch (error) {
+		return err(toGitError("pullLatestChanges", error));
+	}
+}
+async function rebaseBranch(ontoBranch, workspaceRoot) {
+	try {
+		logger.info(`Rebasing onto: ${farver.cyan(ontoBranch)}`);
+		await runIfNotDry("git", ["rebase", ontoBranch], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("rebaseBranch", error));
+	}
+}
+async function isBranchAheadOfRemote(branch, workspaceRoot) {
+	try {
+		const result = await run("git", [
+			"rev-list",
+			`origin/${branch}..${branch}`,
+			"--count"
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(Number.parseInt(result.stdout.trim(), 10) > 0);
+	} catch (error) {
+		logger.verbose(`Failed to compare branch "${branch}" with remote: ${formatUnknownError(error).message}`);
+		return ok(true);
+	}
+}
+async function commitChanges(message, workspaceRoot) {
+	try {
+		await run("git", ["add", "."], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		const isClean = await isWorkingDirectoryClean(workspaceRoot);
+		if (!isClean.ok || isClean.value) return ok(false);
+		logger.info(`Committing changes: ${farver.dim(message)}`);
+		const committed = await commitWithRetryOnMissingIdentity(message, workspaceRoot, "commitChanges");
+		if (!committed.ok) return committed;
+		return ok(true);
+	} catch (error) {
+		const gitError = toGitError("commitChanges", error);
+		logger.error(`Git commit failed: ${gitError.message}`);
+		if (gitError.stderr) logger.error(`Git stderr: ${gitError.stderr}`);
+		return err(gitError);
+	}
+}
+async function commitPaths(paths, message, workspaceRoot) {
+	try {
+		if (paths.length === 0) return ok(false);
+		await run("git", [
+			"add",
+			"--",
+			...paths
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		if ((await run("git", [
+			"diff",
+			"--cached",
+			"--name-only"
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} })).stdout.trim() === "") return ok(false);
+		logger.info(`Committing changes: ${farver.dim(message)}`);
+		const committed = await commitWithRetryOnMissingIdentity(message, workspaceRoot, "commitPaths");
+		if (!committed.ok) return committed;
+		return ok(true);
+	} catch (error) {
+		const gitError = toGitError("commitPaths", error);
+		logger.error(`Git commit failed: ${gitError.message}`);
+		if (gitError.stderr) logger.error(`Git stderr: ${gitError.stderr}`);
+		return err(gitError);
+	}
+}
+async function pushBranch(branch, workspaceRoot, options) {
+	try {
+		const args = [
+			"push",
+			"origin",
+			branch
+		];
+		if (options?.forceWithLease) try {
+			await run("git", [
+				"fetch",
+				"origin",
+				branch
+			], { nodeOptions: {
+				cwd: workspaceRoot,
+				stdio: "pipe"
+			} });
+			args.push("--force-with-lease");
+			logger.info(`Pushing branch: ${farver.green(branch)} ${farver.dim("(with lease)")}`);
+		} catch (error) {
+			const fetchError = toGitError("pushBranch.fetch", error);
+			if (fetchError.stderr?.includes("couldn't find remote ref") || fetchError.message.includes("couldn't find remote ref")) logger.verbose(`Remote branch origin/${branch} does not exist yet, falling back to regular push without --force-with-lease.`);
+			else return err(fetchError);
+		}
+		else if (options?.force) {
+			args.push("--force");
+			logger.info(`Force pushing branch: ${farver.green(branch)}`);
+		} else logger.info(`Pushing branch: ${farver.green(branch)}`);
+		await runIfNotDry("git", args, { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(true);
+	} catch (error) {
+		return err(toGitError("pushBranch", error));
+	}
+}
+async function readFileFromGit(workspaceRoot, ref, filePath) {
+	try {
+		return ok((await run("git", ["show", `${ref}:${filePath}`], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} })).stdout);
+	} catch (error) {
+		logger.verbose(`Failed to read ${filePath} from ${ref}: ${formatUnknownError(error).message}`);
+		return ok(null);
+	}
+}
+async function getMostRecentPackageTag(workspaceRoot, packageName) {
+	try {
+		const { stdout } = await run("git", [
+			"tag",
+			"--list",
+			`${packageName}@*`
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		const tags = stdout.split("\n").map((tag) => tag.trim()).filter(Boolean);
+		if (tags.length === 0) return ok(void 0);
+		return ok(tags.reverse()[0]);
+	} catch (error) {
+		return err(toGitError("getMostRecentPackageTag", error));
+	}
+}
+async function getMostRecentPackageStableTag(workspaceRoot, packageName) {
+	try {
+		const { stdout } = await run("git", [
+			"tag",
+			"--list",
+			`${packageName}@*`
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		const tags = stdout.split("\n").map((tag) => tag.trim()).filter(Boolean).reverse();
+		for (const tag of tags) {
+			const atIndex = tag.lastIndexOf("@");
+			if (atIndex === -1) continue;
+			const version = tag.slice(atIndex + 1);
+			if (semver.valid(version) && semver.prerelease(version) == null) return ok(tag);
+		}
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("getMostRecentPackageStableTag", error));
+	}
+}
+/**
+* Builds a mapping of commit SHAs to the list of files changed in each commit
+* within a given inclusive range.
+*
+* Internally runs:
+*   git log --name-only --format=%H <from>^..<to>
+*
+* Notes
+* - This includes the commit identified by `from` (via `from^..to`).
+* - Order of commits in the resulting Map follows `git log` output
+*   (reverse chronological, newest first).
+* - On failure (e.g., invalid refs), the function returns null.
+*
+* @param {string} workspaceRoot Absolute path to the git repository root used as cwd.
+* @param {string} from          Starting commit/ref (inclusive).
+* @param {string} to            Ending commit/ref (inclusive).
+* @returns {Promise<Map<string, string[]> | null>} Promise resolving to a Map where keys are commit SHAs and values are
+*          arrays of file paths changed by that commit, or null on error.
+*/
+async function getGroupedFilesByCommitSha(workspaceRoot, from, to) {
+	const commitsMap = /* @__PURE__ */ new Map();
+	try {
+		const { stdout } = await run("git", [
+			"log",
+			"--name-only",
+			"--format=%H",
+			`${from}^..${to}`
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		const lines = stdout.trim().split("\n").filter((line) => line.trim() !== "");
+		let currentSha = null;
+		const HASH_REGEX = /^[0-9a-f]{40}$/i;
+		for (const line of lines) {
+			const trimmedLine = line.trim();
+			if (HASH_REGEX.test(trimmedLine)) {
+				currentSha = trimmedLine;
+				commitsMap.set(currentSha, []);
+				continue;
+			}
+			if (currentSha === null) continue;
+			commitsMap.get(currentSha).push(trimmedLine);
+		}
+		return ok(commitsMap);
+	} catch (error) {
+		return err(toGitError("getGroupedFilesByCommitSha", error));
+	}
+}
+/**
+* Create a git tag for a package release
+* @param packageName - The package name (e.g., "@scope/name")
+* @param version - The version to tag (e.g., "1.2.3")
+* @param workspaceRoot - The root directory of the workspace
+* @returns Result indicating success or failure
+*/
+async function createPackageTag(packageName, version, workspaceRoot) {
+	const tagName = `${packageName}@${version}`;
+	try {
+		logger.info(`Creating tag: ${farver.green(tagName)}`);
+		await runIfNotDry("git", ["tag", tagName], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("createPackageTag", error));
+	}
+}
+/**
+* Push a specific tag to the remote repository
+* @param tagName - The tag name to push
+* @param workspaceRoot - The root directory of the workspace
+* @returns Result indicating success or failure
+*/
+async function pushTag(tagName, workspaceRoot) {
+	try {
+		logger.info(`Pushing tag: ${farver.green(tagName)}`);
+		await runIfNotDry("git", [
+			"push",
+			"origin",
+			tagName
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		return ok(void 0);
+	} catch (error) {
+		return err(toGitError("pushTag", error));
+	}
+}
+/**
+* Create and push a package tag in one operation
+* @param packageName - The package name
+* @param version - The version to tag
+* @param workspaceRoot - The root directory of the workspace
+* @returns Result indicating success or failure
+*/
+async function createAndPushPackageTag(packageName, version, workspaceRoot) {
+	const createResult = await createPackageTag(packageName, version, workspaceRoot);
+	if (!createResult.ok) return createResult;
+	return pushTag(`${packageName}@${version}`, workspaceRoot);
+}
+
+//#endregion
+//#region src/core/changelog.ts
+const excludeAuthors = [
+	/\[bot\]/i,
+	/dependabot/i,
+	/\(bot\)/i
+];
+async function generateChangelogEntry(options) {
+	const { packageName, version, previousVersion, date, commits, owner, repo, types, template, githubClient } = options;
+	const templateData = {
+		packageName,
+		version,
+		previousVersion,
+		date,
+		compareUrl: previousVersion ? `https://github.com/${owner}/${repo}/compare/${packageName}@${previousVersion}...${packageName}@${version}` : void 0,
+		owner,
+		repo,
+		groups: buildTemplateGroups({
+			commits,
+			owner,
+			repo,
+			types,
+			commitAuthors: await resolveCommitAuthors(commits, githubClient)
+		})
+	};
+	const eta = new Eta();
+	const templateToUse = template || DEFAULT_CHANGELOG_TEMPLATE;
+	return eta.renderString(templateToUse, templateData).trim();
+}
+async function updateChangelog(options) {
+	const { version, previousVersion, commits, date, normalizedOptions, workspacePackage, githubClient } = options;
+	const changelogPath = join(workspacePackage.path, "CHANGELOG.md");
+	const changelogRelativePath = relative(normalizedOptions.workspaceRoot, join(workspacePackage.path, "CHANGELOG.md"));
+	const existingContent = await readFileFromGit(normalizedOptions.workspaceRoot, normalizedOptions.branch.default, changelogRelativePath);
+	logger.verbose("Existing content found: ", existingContent.ok && Boolean(existingContent.value));
+	const newEntry = await generateChangelogEntry({
+		packageName: workspacePackage.name,
+		version,
+		previousVersion,
+		date,
+		commits,
+		owner: normalizedOptions.owner,
+		repo: normalizedOptions.repo,
+		types: normalizedOptions.types,
+		template: normalizedOptions.changelog?.template,
+		githubClient
+	});
+	let updatedContent;
+	if (!existingContent.ok || !existingContent.value) {
+		updatedContent = `# ${workspacePackage.name}\n\n${newEntry}\n`;
+		await writeFile(changelogPath, updatedContent, "utf-8");
+		return;
+	}
+	const parsed = parseChangelog(existingContent.value);
+	const lines = existingContent.value.split("\n");
+	const existingVersionIndex = parsed.versions.findIndex((v) => v.version === version);
+	if (existingVersionIndex !== -1) {
+		const existingVersion = parsed.versions[existingVersionIndex];
+		const before = lines.slice(0, existingVersion.lineStart);
+		const after = lines.slice(existingVersion.lineEnd + 1);
+		updatedContent = [
+			...before,
+			newEntry,
+			...after
+		].join("\n");
+	} else {
+		const insertAt = parsed.headerLineEnd + 1;
+		const before = lines.slice(0, insertAt);
+		const after = lines.slice(insertAt);
+		if (before.length > 0 && before[before.length - 1] !== "") before.push("");
+		updatedContent = [
+			...before,
+			newEntry,
+			"",
+			...after
+		].join("\n");
+	}
+	await writeFile(changelogPath, updatedContent, "utf-8");
+}
+async function resolveCommitAuthors(commits, githubClient) {
+	const authorMap = /* @__PURE__ */ new Map();
+	const commitAuthors = /* @__PURE__ */ new Map();
+	for (const commit of commits) {
+		const authorsForCommit = [];
+		commit.authors.forEach((author, idx) => {
+			if (!author.email || !author.name) return;
+			if (excludeAuthors.some((re) => re.test(author.name))) return;
+			if (!authorMap.has(author.email)) authorMap.set(author.email, {
+				commits: [],
+				name: author.name,
+				email: author.email
+			});
+			const info = authorMap.get(author.email);
+			if (idx === 0) info.commits.push(commit.shortHash);
+			authorsForCommit.push(info);
+		});
+		commitAuthors.set(commit.hash, authorsForCommit);
+	}
+	const authors = Array.from(authorMap.values());
+	await Promise.all(authors.map((info) => githubClient.resolveAuthorInfo(info)));
+	return commitAuthors;
+}
+function parseChangelog(content) {
+	const lines = content.split("\n");
+	let packageName = null;
+	let headerLineEnd = -1;
+	const versions = [];
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i].trim();
+		if (line.startsWith("# ")) {
+			packageName = line.slice(2).trim();
+			headerLineEnd = i;
+			break;
+		}
+	}
+	for (let i = headerLineEnd + 1; i < lines.length; i++) {
+		const line = lines[i].trim();
+		if (line.startsWith("## ")) {
+			const versionMatch = line.match(/##\s+(?:<small>)?\[?([^\](\s<]+)/);
+			if (versionMatch) {
+				const version = versionMatch[1];
+				const lineStart = i;
+				let lineEnd = lines.length - 1;
+				for (let j = i + 1; j < lines.length; j++) if (lines[j].trim().startsWith("## ")) {
+					lineEnd = j - 1;
+					break;
+				}
+				const versionContent = lines.slice(lineStart, lineEnd + 1).join("\n");
+				versions.push({
+					version,
+					lineStart,
+					lineEnd,
+					content: versionContent
+				});
+			}
+		}
+	}
+	return {
+		packageName,
+		versions,
+		headerLineEnd
+	};
+}
+
+//#endregion
+//#region src/operations/semver.ts
+function isValidSemver(version) {
+	return semver.valid(version) != null;
+}
+function getNextVersion(currentVersion, bump) {
+	if (bump === "none") return currentVersion;
+	if (!isValidSemver(currentVersion)) throw new Error(`Cannot bump version for invalid semver: ${currentVersion}`);
+	const next = semver.inc(currentVersion, bump);
+	if (!next) throw new Error(`Failed to bump version ${currentVersion} with bump ${bump}`);
+	return next;
+}
+function calculateBumpType(oldVersion, newVersion) {
+	if (!isValidSemver(oldVersion) || !isValidSemver(newVersion)) throw new Error(`Cannot calculate bump type for invalid semver: ${oldVersion} or ${newVersion}`);
+	const diff = semver.diff(oldVersion, newVersion);
+	if (!diff) return "none";
+	if (diff === "major" || diff === "premajor") return "major";
+	if (diff === "minor" || diff === "preminor") return "minor";
+	if (diff === "patch" || diff === "prepatch" || diff === "prerelease") return "patch";
+	if (semver.gt(newVersion, oldVersion)) return "patch";
+	return "none";
+}
+function getPrereleaseIdentifier(version) {
+	const parsed = semver.parse(version);
+	if (!parsed || parsed.prerelease.length === 0) return;
+	const identifier = parsed.prerelease[0];
+	return typeof identifier === "string" ? identifier : void 0;
+}
+function getNextPrereleaseVersion(currentVersion, mode, identifier) {
+	if (!isValidSemver(currentVersion)) throw new Error(`Cannot bump prerelease for invalid semver: ${currentVersion}`);
+	const releaseType = mode === "next" ? "prerelease" : mode;
+	const next = identifier ? semver.inc(currentVersion, releaseType, identifier) : semver.inc(currentVersion, releaseType);
+	if (!next) throw new Error(`Failed to compute prerelease version for ${currentVersion}`);
+	return next;
+}
+
+//#endregion
+//#region src/core/prompts.ts
+async function selectPackagePrompt(packages) {
+	const response = await prompts({
+		type: "multiselect",
+		name: "selectedPackages",
+		message: "Select packages to release",
+		choices: packages.map((pkg) => ({
+			title: `${pkg.name} (${farver.bold(pkg.version)})`,
+			value: pkg.name,
+			selected: true
+		})),
+		min: 1,
+		hint: "Space to select/deselect. Return to submit.",
+		instructions: false
+	});
+	if (!response.selectedPackages || response.selectedPackages.length === 0) return [];
+	return response.selectedPackages;
+}
+async function selectVersionPrompt(workspaceRoot, pkg, currentVersion, suggestedVersion, options) {
+	const defaultChoice = options?.defaultChoice ?? "auto";
+	const suggestedSuffix = options?.suggestedHint ? farver.dim(` (${options.suggestedHint})`) : "";
+	const prereleaseIdentifier = getPrereleaseIdentifier(currentVersion);
+	const nextDefaultPrerelease = getNextPrereleaseVersion(currentVersion, "next", prereleaseIdentifier === "alpha" || prereleaseIdentifier === "beta" ? prereleaseIdentifier : "beta");
+	const nextBeta = getNextPrereleaseVersion(currentVersion, "next", "beta");
+	const nextAlpha = getNextPrereleaseVersion(currentVersion, "next", "alpha");
+	const prePatchBeta = getNextPrereleaseVersion(currentVersion, "prepatch", "beta");
+	const preMinorBeta = getNextPrereleaseVersion(currentVersion, "preminor", "beta");
+	const preMajorBeta = getNextPrereleaseVersion(currentVersion, "premajor", "beta");
+	const prePatchAlpha = getNextPrereleaseVersion(currentVersion, "prepatch", "alpha");
+	const preMinorAlpha = getNextPrereleaseVersion(currentVersion, "preminor", "alpha");
+	const preMajorAlpha = getNextPrereleaseVersion(currentVersion, "premajor", "alpha");
+	const isCurrentPrerelease = prereleaseIdentifier != null;
+	const choices = [
+		{
+			value: "skip",
+			title: `skip ${farver.dim("(no change)")}`
+		},
+		{
+			value: "suggested",
+			title: `suggested ${farver.bold(suggestedVersion)}${suggestedSuffix}`
+		},
+		{
+			value: "as-is",
+			title: `as-is ${farver.dim("(keep current version)")}`
+		},
+		...isCurrentPrerelease ? [{
+			value: "next-prerelease",
+			title: `next prerelease ${farver.bold(nextDefaultPrerelease)}`
+		}] : [],
+		{
+			value: "patch",
+			title: `patch ${farver.bold(getNextVersion(pkg.version, "patch"))}`
+		},
+		{
+			value: "minor",
+			title: `minor ${farver.bold(getNextVersion(pkg.version, "minor"))}`
+		},
+		{
+			value: "major",
+			title: `major ${farver.bold(getNextVersion(pkg.version, "major"))}`
+		},
+		{
+			value: "prerelease",
+			title: `prerelease ${farver.dim("(choose strategy)")}`
+		},
+		{
+			value: "custom",
+			title: "custom"
+		}
+	];
+	const initialValue = defaultChoice === "auto" ? suggestedVersion === currentVersion ? "skip" : "suggested" : defaultChoice;
+	const initial = Math.max(0, choices.findIndex((choice) => choice.value === initialValue));
+	const prereleaseVersionByChoice = {
+		"next-prerelease": nextDefaultPrerelease,
+		"next": nextDefaultPrerelease,
+		"next-beta": nextBeta,
+		"next-alpha": nextAlpha,
+		"prepatch-beta": prePatchBeta,
+		"preminor-beta": preMinorBeta,
+		"premajor-beta": preMajorBeta,
+		"prepatch-alpha": prePatchAlpha,
+		"preminor-alpha": preMinorAlpha,
+		"premajor-alpha": preMajorAlpha
+	};
+	const answers = await prompts({
+		type: "autocomplete",
+		name: "version",
+		message: `${pkg.name}: ${farver.green(pkg.version)}`,
+		choices,
+		limit: choices.length,
+		initial
+	});
+	if (!answers.version) return null;
+	if (answers.version === "skip") return null;
+	else if (answers.version === "suggested") return suggestedVersion;
+	else if (answers.version === "custom") {
+		const customAnswer = await prompts({
+			type: "text",
+			name: "custom",
+			message: "Enter the new version number:",
+			initial: suggestedVersion,
+			validate: (custom) => {
+				if (isValidSemver(custom)) return true;
+				return "That's not a valid version number";
+			}
+		});
+		if (!customAnswer.custom) return null;
+		return customAnswer.custom;
+	} else if (answers.version === "as-is") return currentVersion;
+	else if (answers.version === "prerelease") {
+		const prereleaseChoices = [
+			{
+				value: "next",
+				title: `next ${farver.bold(nextDefaultPrerelease)}`
+			},
+			{
+				value: "next-beta",
+				title: `next beta ${farver.bold(nextBeta)}`
+			},
+			{
+				value: "next-alpha",
+				title: `next alpha ${farver.bold(nextAlpha)}`
+			},
+			{
+				value: "prepatch-beta",
+				title: `pre-patch (beta) ${farver.bold(prePatchBeta)}`
+			},
+			{
+				value: "prepatch-alpha",
+				title: `pre-patch (alpha) ${farver.bold(prePatchAlpha)}`
+			},
+			{
+				value: "preminor-beta",
+				title: `pre-minor (beta) ${farver.bold(preMinorBeta)}`
+			},
+			{
+				value: "preminor-alpha",
+				title: `pre-minor (alpha) ${farver.bold(preMinorAlpha)}`
+			},
+			{
+				value: "premajor-beta",
+				title: `pre-major (beta) ${farver.bold(preMajorBeta)}`
+			},
+			{
+				value: "premajor-alpha",
+				title: `pre-major (alpha) ${farver.bold(preMajorAlpha)}`
+			}
+		];
+		const prereleaseAnswer = await prompts({
+			type: "autocomplete",
+			name: "prerelease",
+			message: `${pkg.name}: select prerelease strategy`,
+			choices: prereleaseChoices,
+			limit: prereleaseChoices.length,
+			initial: 0
+		});
+		if (!prereleaseAnswer.prerelease) return null;
+		return prereleaseVersionByChoice[prereleaseAnswer.prerelease];
+	}
+	const prereleaseVersion = prereleaseVersionByChoice[answers.version];
+	if (prereleaseVersion) return prereleaseVersion;
+	return getNextVersion(pkg.version, answers.version);
+}
+async function confirmOverridePrompt(pkg, overrideVersion) {
+	const response = await prompts({
+		type: "select",
+		name: "choice",
+		message: `${pkg.name}: use override version ${farver.bold(overrideVersion)}?`,
+		choices: [{
+			title: "use override",
+			value: "use"
+		}, {
+			title: "pick another version",
+			value: "pick"
+		}],
+		initial: 0
+	});
+	if (!response.choice) return null;
+	return response.choice;
+}
+
+//#endregion
+//#region src/core/workspace.ts
+function toWorkspaceError(operation, error) {
+	return {
+		type: "workspace",
+		operation,
+		message: error instanceof Error ? error.message : String(error)
+	};
+}
+async function discoverWorkspacePackages(workspaceRoot, options) {
+	let workspaceOptions;
+	let explicitPackages;
+	if (options.packages == null || options.packages === true) workspaceOptions = { excludePrivate: false };
+	else if (Array.isArray(options.packages)) {
+		workspaceOptions = {
+			excludePrivate: false,
+			include: options.packages
+		};
+		explicitPackages = options.packages;
+	} else {
+		workspaceOptions = options.packages;
+		if (options.packages.include) explicitPackages = options.packages.include;
+	}
+	let workspacePackages;
+	try {
+		workspacePackages = await findWorkspacePackages(workspaceRoot, workspaceOptions);
+	} catch (error) {
+		return err(toWorkspaceError("discoverWorkspacePackages", error));
+	}
+	if (explicitPackages) {
+		const foundNames = new Set(workspacePackages.map((p) => p.name));
+		const missing = explicitPackages.filter((p) => !foundNames.has(p));
+		if (missing.length > 0) return err(toWorkspaceError("discoverWorkspacePackages", `Package${missing.length > 1 ? "s" : ""} not found in workspace: ${missing.join(", ")}. Check your package names or run 'pnpm ls' to see available packages`));
+	}
+	const isPackagePromptEnabled = options.prompts?.packages !== false;
+	logger.verbose("Package prompt gating", {
+		isCI: getIsCI(),
+		isPackagePromptEnabled,
+		hasExplicitPackages: Boolean(explicitPackages),
+		include: workspaceOptions.include ?? [],
+		exclude: workspaceOptions.exclude ?? [],
+		excludePrivate: workspaceOptions.excludePrivate ?? false
+	});
+	if (!getIsCI() && isPackagePromptEnabled && !explicitPackages) {
+		const selectedNames = await selectPackagePrompt(workspacePackages);
+		workspacePackages = workspacePackages.filter((pkg) => selectedNames.includes(pkg.name));
+	}
+	return ok(workspacePackages);
+}
+async function findWorkspacePackages(workspaceRoot, options) {
+	try {
+		const result = await run("pnpm", [
+			"-r",
+			"ls",
+			"--json"
+		], { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe"
+		} });
+		const rawProjects = JSON.parse(result.stdout);
+		const allPackageNames = new Set(rawProjects.map((p) => p.name));
+		const excludedPackages = /* @__PURE__ */ new Set();
+		const promises = rawProjects.map(async (rawProject) => {
+			const content = await readFile(join(rawProject.path, "package.json"), "utf-8");
+			const packageJson = JSON.parse(content);
+			if (!shouldIncludePackage(packageJson, options)) {
+				excludedPackages.add(rawProject.name);
+				return null;
+			}
+			return {
+				name: rawProject.name,
+				version: rawProject.version,
+				path: rawProject.path,
+				packageJson,
+				workspaceDependencies: Object.keys(rawProject.dependencies || []).filter((dep) => {
+					return allPackageNames.has(dep);
+				}),
+				workspaceDevDependencies: Object.keys(rawProject.devDependencies || []).filter((dep) => {
+					return allPackageNames.has(dep);
+				})
+			};
+		});
+		const packages = await Promise.all(promises);
+		if (excludedPackages.size > 0) logger.info(`Excluded packages: ${farver.green(Array.from(excludedPackages).join(", "))}`);
+		return packages.filter((pkg) => pkg !== null);
+	} catch (err) {
+		logger.error("Error discovering workspace packages:", err);
+		throw err;
+	}
+}
+function shouldIncludePackage(pkg, options) {
+	if (!options) return true;
+	if (options.excludePrivate && pkg.private) return false;
+	if (options.include && options.include.length > 0) {
+		if (!options.include.includes(pkg.name)) return false;
 	}
-	choices.push({
-		title: "Custom version",
-		value: "custom"
+	if (options.exclude?.includes(pkg.name)) return false;
+	return true;
+}
+
+//#endregion
+//#region src/operations/branch.ts
+async function prepareReleaseBranch(options) {
+	const { workspaceRoot, releaseBranch, defaultBranch } = options;
+	const currentBranch = await getCurrentBranch(workspaceRoot);
+	if (!currentBranch.ok) return currentBranch;
+	if (currentBranch.value !== defaultBranch) return err({
+		type: "git",
+		operation: "validateBranch",
+		message: `Current branch is '${currentBranch.value}'. Please switch to '${defaultBranch}'.`
 	});
-	const response = await prompts([{
-		type: "select",
-		name: "choice",
-		message: `${pkg.name} (${currentVersion}):`,
-		choices,
-		initial: 0
-	}, {
-		type: (prev) => prev === "custom" ? "text" : null,
-		name: "customVersion",
-		message: "Enter custom version:",
-		initial: suggestedVersion,
-		validate: (value) => {
-			return /^\d+\.\d+\.\d+(?:[-+].+)?$/.test(value) || "Invalid semver version (e.g., 1.0.0)";
-		}
-	}]);
-	if (response.choice === "suggested") return suggestedVersion;
-	else if (response.choice === "custom") return response.customVersion;
-	else return getNextVersion(currentVersion, response.choice);
+	const branchExists = await doesBranchExist(releaseBranch, workspaceRoot);
+	if (!branchExists.ok) return branchExists;
+	if (!branchExists.value) {
+		const created = await createBranch(releaseBranch, defaultBranch, workspaceRoot);
+		if (!created.ok) return created;
+	}
+	const checkedOut = await checkoutBranch(releaseBranch, workspaceRoot);
+	if (!checkedOut.ok) return checkedOut;
+	if (branchExists.value) {
+		const pulled = await pullLatestChanges(releaseBranch, workspaceRoot);
+		if (!pulled.ok) return pulled;
+		if (!pulled.value) logger.warn("Failed to pull latest changes, continuing anyway.");
+	}
+	const rebased = await rebaseBranch(defaultBranch, workspaceRoot);
+	if (!rebased.ok) return rebased;
+	return ok(void 0);
+}
+async function syncReleaseChanges(options) {
+	const { workspaceRoot, releaseBranch, commitMessage, hasChanges } = options;
+	const committed = hasChanges ? await commitChanges(commitMessage, workspaceRoot) : ok(false);
+	if (!committed.ok) return committed;
+	const isAhead = await isBranchAheadOfRemote(releaseBranch, workspaceRoot);
+	if (!isAhead.ok) return isAhead;
+	if (!committed.value && !isAhead.value) return ok(false);
+	const pushed = await pushBranch(releaseBranch, workspaceRoot, { forceWithLease: true });
+	if (!pushed.ok) return pushed;
+	return ok(true);
 }
 
 //#endregion
-//#region src/version.ts
-function isValidSemver(version) {
-	return /^\d+\.\d+\.\d+(?:[-+].+)?$/.test(version);
+//#region src/versioning/commits.ts
+/**
+* Get commits grouped by workspace package.
+* For each package, retrieves all commits since its last release tag that affect that package.
+*
+* @param {string} workspaceRoot - The root directory of the workspace
+* @param {WorkspacePackage[]} packages - Array of workspace packages to analyze
+* @returns {Promise<Map<string, GitCommit[]>>} A map of package names to their commits since their last release
+*/
+async function getWorkspacePackageGroupedCommits(workspaceRoot, packages) {
+	const changedPackages = /* @__PURE__ */ new Map();
+	const promises = packages.map(async (pkg) => {
+		const lastTagResult = await getMostRecentPackageTag(workspaceRoot, pkg.name);
+		const lastTag = lastTagResult.ok ? lastTagResult.value : void 0;
+		const allCommits = await getCommits({
+			from: lastTag,
+			to: "HEAD",
+			cwd: workspaceRoot,
+			folder: pkg.path
+		});
+		logger.verbose(`Found ${farver.cyan(allCommits.length)} commits for package ${farver.bold(pkg.name)} since tag ${farver.cyan(lastTag ?? "N/A")}`);
+		return {
+			pkgName: pkg.name,
+			commits: allCommits
+		};
+	});
+	const results = await Promise.all(promises);
+	for (const { pkgName, commits } of results) changedPackages.set(pkgName, commits);
+	return changedPackages;
+}
+async function getPackageCommitsSinceTag(workspaceRoot, pkg, fromTag) {
+	const allCommits = await getCommits({
+		from: fromTag,
+		to: "HEAD",
+		cwd: workspaceRoot,
+		folder: pkg.path
+	});
+	logger.verbose(`Found ${farver.cyan(allCommits.length)} commits for package ${farver.bold(pkg.name)} since ${farver.cyan(fromTag ?? "start")}`);
+	return allCommits;
 }
-function validateSemver(version) {
-	if (!isValidSemver(version)) throw new Error(`Invalid semver version: ${version}`);
+/**
+* Check if a file path touches any package folder.
+* @param file - The file path to check
+* @param packagePaths - Set of normalized package paths
+* @param workspaceRoot - The workspace root for path normalization
+* @returns true if the file is inside a package folder
+*/
+function fileMatchesPackageFolder(file, packagePaths, workspaceRoot) {
+	const normalizedFile = file.startsWith("./") ? file.slice(2) : file;
+	for (const pkgPath of packagePaths) {
+		const normalizedPkgPath = pkgPath.startsWith(workspaceRoot) ? pkgPath.slice(workspaceRoot.length + 1) : pkgPath;
+		if (normalizedFile.startsWith(`${normalizedPkgPath}/`) || normalizedFile === normalizedPkgPath) return true;
+	}
+	return false;
 }
-function getNextVersion(currentVersion, bump) {
-	if (bump === "none") return currentVersion;
-	validateSemver(currentVersion);
-	const match = currentVersion.match(/^(\d+)\.(\d+)\.(\d+)(.*)$/);
-	if (!match) throw new Error(`Invalid semver version: ${currentVersion}`);
-	const [, major, minor, patch] = match;
-	let newMajor = Number.parseInt(major, 10);
-	let newMinor = Number.parseInt(minor, 10);
-	let newPatch = Number.parseInt(patch, 10);
-	switch (bump) {
-		case "major":
-			newMajor += 1;
-			newMinor = 0;
-			newPatch = 0;
-			break;
-		case "minor":
-			newMinor += 1;
-			newPatch = 0;
-			break;
-		case "patch":
-			newPatch += 1;
-			break;
+/**
+* Check if a commit is a "global" commit (doesn't touch any package folder).
+* @param workspaceRoot - The workspace root
+* @param files - Array of files changed in the commit
+* @param packagePaths - Set of normalized package paths
+* @returns true if this is a global commit
+*/
+function isGlobalCommit(workspaceRoot, files, packagePaths) {
+	if (!files || files.length === 0) return false;
+	return !files.some((file) => fileMatchesPackageFolder(file, packagePaths, workspaceRoot));
+}
+const DEPENDENCY_FILES = [
+	"package.json",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml",
+	"yarn.lock",
+	"package-lock.json"
+];
+/**
+* Find the oldest and newest commits across all packages.
+* @param packageCommits - Map of package commits
+* @returns Object with oldest and newest commit SHAs, or null if no commits
+*/
+function findCommitRange(packageCommits) {
+	let oldestCommit = null;
+	let newestCommit = null;
+	for (const commits of packageCommits.values()) {
+		if (commits.length === 0) continue;
+		const firstCommit = commits[0].shortHash;
+		const lastCommit = commits[commits.length - 1].shortHash;
+		if (!newestCommit) newestCommit = firstCommit;
+		oldestCommit = lastCommit;
 	}
-	return `${newMajor}.${newMinor}.${newPatch}`;
+	if (!oldestCommit || !newestCommit) return null;
+	return {
+		oldest: oldestCommit,
+		newest: newestCommit
+	};
+}
+/**
+* Filters commits to find global commits (those not touching any package folder),
+* optionally further filtered to only dependency-related files.
+*/
+function filterGlobalCommits(commits, commitFilesMap, packagePaths, workspaceRoot, mode) {
+	const globalCommits = commits.filter((commit) => {
+		const files = commitFilesMap.get(commit.shortHash);
+		return files ? isGlobalCommit(workspaceRoot, files, packagePaths) : false;
+	});
+	if (mode === "all") return globalCommits;
+	return globalCommits.filter((commit) => {
+		const files = commitFilesMap.get(commit.shortHash);
+		if (!files) return false;
+		return files.some((file) => DEPENDENCY_FILES.includes(file.startsWith("./") ? file.slice(2) : file));
+	});
 }
 /**
-* Create a version update object
+* Get global commits for each package based on their individual commit timelines.
+* This solves the problem where packages with different release histories need different global commits.
+*
+* A "global commit" is a commit that doesn't touch any package folder but may affect all packages
+* (e.g., root package.json, CI config, README).
+*
+* Performance: Makes ONE batched git call to get files for all commits across all packages.
+*
+* @param workspaceRoot - The root directory of the workspace
+* @param packageCommits - Map of package name to their commits (from getWorkspacePackageCommits)
+* @param allPackages - All workspace packages (used to identify package folders)
+* @param mode - Filter mode: false (disabled), "all" (all global commits), or "dependencies" (only dependency-related)
+* @returns Map of package name to their global commits
 */
+async function getGlobalCommitsPerPackage(workspaceRoot, packageCommits, allPackages, mode) {
+	const result = /* @__PURE__ */ new Map();
+	if (!mode) {
+		logger.verbose("Global commits mode disabled");
+		return result;
+	}
+	logger.verbose(`Computing global commits per-package (mode: ${farver.cyan(mode)})`);
+	const commitRange = findCommitRange(packageCommits);
+	if (!commitRange) {
+		logger.verbose("No commits found across packages");
+		return result;
+	}
+	logger.verbose("Fetching files for commits range", `${farver.cyan(commitRange.oldest)}..${farver.cyan(commitRange.newest)}`);
+	const commitFilesMap = await getGroupedFilesByCommitSha(workspaceRoot, commitRange.oldest, commitRange.newest);
+	if (!commitFilesMap.ok) {
+		logger.warn("Failed to get commit file list, returning empty global commits");
+		return result;
+	}
+	logger.verbose("Got file lists for commits", `${farver.cyan(commitFilesMap.value.size)} commits in ONE git call`);
+	const packagePaths = new Set(allPackages.map((p) => p.path));
+	for (const [pkgName, commits] of packageCommits) {
+		logger.verbose("Filtering global commits for package", `${farver.bold(pkgName)} from ${farver.cyan(commits.length)} commits`);
+		const filtered = filterGlobalCommits(commits, commitFilesMap.value, packagePaths, workspaceRoot, mode);
+		logger.verbose("Package global commits found", `${farver.bold(pkgName)}: ${farver.cyan(filtered.length)} global commits`);
+		result.set(pkgName, filtered);
+	}
+	return result;
+}
+
+//#endregion
+//#region src/operations/version.ts
+function determineHighestBump(commits) {
+	if (commits.length === 0) return "none";
+	let highestBump = "none";
+	for (const commit of commits) {
+		const bump = determineBumpType(commit);
+		if (bump === "major") return "major";
+		if (bump === "minor") highestBump = "minor";
+		else if (bump === "patch" && highestBump === "none") highestBump = "patch";
+	}
+	return highestBump;
+}
 function createVersionUpdate(pkg, bump, hasDirectChanges) {
 	const newVersion = getNextVersion(pkg.version, bump);
 	return {
@@ -539,61 +1733,404 @@ function createVersionUpdate(pkg, bump, hasDirectChanges) {
 		currentVersion: pkg.version,
 		newVersion,
 		bumpType: bump,
-		hasDirectChanges
+		hasDirectChanges,
+		changeKind: "dependent"
+	};
+}
+function determineBumpType(commit) {
+	if (!commit.isConventional) return "none";
+	if (commit.isBreaking) return "major";
+	if (commit.type === "feat") return "minor";
+	if (commit.type === "fix" || commit.type === "perf") return "patch";
+	return "none";
+}
+
+//#endregion
+//#region src/versioning/package.ts
+/**
+* Build a dependency graph from workspace packages
+*
+* Creates a bidirectional graph that maps:
+* - packages: Map of package name → WorkspacePackage
+* - dependents: Map of package name → Set of packages that depend on it
+*
+* @param packages - All workspace packages
+* @returns Dependency graph with packages and dependents maps
+*/
+function buildPackageDependencyGraph(packages) {
+	const packagesMap = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		packagesMap.set(pkg.name, pkg);
+		dependents.set(pkg.name, /* @__PURE__ */ new Set());
+	}
+	for (const pkg of packages) {
+		const allDeps = [...pkg.workspaceDependencies, ...pkg.workspaceDevDependencies];
+		for (const dep of allDeps) {
+			const depSet = dependents.get(dep);
+			if (depSet) depSet.add(pkg.name);
+		}
+	}
+	return {
+		packages: packagesMap,
+		dependents
 	};
 }
 /**
-* Infer version updates from package commits with optional interactive overrides
+* Get all packages affected by changes (including transitive dependents)
+*
+* Uses graph traversal to find all packages that need updates:
+* - Packages with direct changes
+* - All packages that depend on changed packages (transitively)
+*
+* @param graph - Dependency graph
+* @param changedPackages - Set of package names with direct changes
+* @returns Set of all package names that need updates
+*/
+function getAllAffectedPackages(graph, changedPackages) {
+	const affected = /* @__PURE__ */ new Set();
+	function visitDependents(pkgName) {
+		if (affected.has(pkgName)) return;
+		affected.add(pkgName);
+		const dependents = graph.dependents.get(pkgName);
+		if (dependents) for (const dependent of dependents) visitDependents(dependent);
+	}
+	for (const pkg of changedPackages) visitDependents(pkg);
+	return affected;
+}
+/**
+* Calculate the order in which packages should be published
+*
+* Performs topological sorting to ensure dependencies are published before dependents.
+* Assigns a "level" to each package based on its depth in the dependency tree.
+*
+* This is used by the publish command to publish packages in the correct order.
+*
+* @param graph - Dependency graph
+* @param packagesToPublish - Set of package names to publish
+* @returns Array of packages in publish order with their dependency level
+*/
+function getPackagePublishOrder(graph, packagesToPublish) {
+	const result = [];
+	const visited = /* @__PURE__ */ new Set();
+	const toUpdate = new Set(packagesToPublish);
+	const packagesToProcess = new Set(packagesToPublish);
+	for (const pkg of packagesToPublish) {
+		const deps = graph.dependents.get(pkg);
+		if (deps) for (const dep of deps) {
+			packagesToProcess.add(dep);
+			toUpdate.add(dep);
+		}
+	}
+	function visit(pkgName, level) {
+		if (visited.has(pkgName)) return;
+		visited.add(pkgName);
+		const pkg = graph.packages.get(pkgName);
+		if (!pkg) return;
+		const allDeps = [...pkg.workspaceDependencies, ...pkg.workspaceDevDependencies];
+		let maxDepLevel = level;
+		for (const dep of allDeps) if (toUpdate.has(dep)) {
+			visit(dep, level);
+			const depResult = result.find((r) => r.package.name === dep);
+			if (depResult && depResult.level >= maxDepLevel) maxDepLevel = depResult.level + 1;
+		}
+		result.push({
+			package: pkg,
+			level: maxDepLevel
+		});
+	}
+	for (const pkg of toUpdate) visit(pkg, 0);
+	result.sort((a, b) => a.level - b.level);
+	return result;
+}
+/**
+* Create version updates for all packages affected by dependency changes
 *
+* When a package is updated, all packages that depend on it should also be updated.
+* This function calculates which additional packages need patch bumps due to dependency changes.
+*
+* @param graph - Dependency graph
 * @param workspacePackages - All workspace packages
-* @param packageCommits - Map of package names to their commits
-* @param workspaceRoot - Root directory for prompts
-* @param showPrompt - Whether to show prompts for version overrides
-* @returns Version updates for packages with changes
+* @param directUpdates - Packages with direct code changes
+* @returns All updates including dependent packages that need patch bumps
 */
-async function inferVersionUpdates(workspacePackages, packageCommits, workspaceRoot, showPrompt) {
-	const versionUpdates = [];
-	for (const [pkgName, commits] of packageCommits) {
-		if (commits.length === 0) continue;
+function createDependentUpdates(graph, workspacePackages, directUpdates, excludedPackages = /* @__PURE__ */ new Set()) {
+	const allUpdates = [...directUpdates];
+	const directUpdateMap = new Map(directUpdates.map((u) => [u.package.name, u]));
+	const affectedPackages = getAllAffectedPackages(graph, new Set(directUpdates.map((u) => u.package.name)));
+	for (const pkgName of affectedPackages) {
+		logger.verbose(`Processing affected package: ${pkgName}`);
+		if (excludedPackages.has(pkgName)) {
+			logger.verbose(`Skipping ${pkgName}, explicitly excluded from dependent bumps`);
+			continue;
+		}
+		if (directUpdateMap.has(pkgName)) {
+			logger.verbose(`Skipping ${pkgName}, already has a direct update`);
+			continue;
+		}
 		const pkg = workspacePackages.find((p) => p.name === pkgName);
 		if (!pkg) continue;
-		const bump = determineHighestBump(commits);
-		if (bump === "none") {
-			logger.info(`No version bump needed for package ${pkg.name}`);
+		allUpdates.push(createVersionUpdate(pkg, "patch", false));
+	}
+	return allUpdates;
+}
+
+//#endregion
+//#region src/versioning/version.ts
+const messageColorMap = {
+	feat: farver.green,
+	feature: farver.green,
+	refactor: farver.cyan,
+	style: farver.cyan,
+	docs: farver.blue,
+	doc: farver.blue,
+	types: farver.blue,
+	type: farver.blue,
+	chore: farver.gray,
+	ci: farver.gray,
+	build: farver.gray,
+	deps: farver.gray,
+	dev: farver.gray,
+	fix: farver.yellow,
+	test: farver.yellow,
+	perf: farver.magenta,
+	revert: farver.red,
+	breaking: farver.red
+};
+function formatCommitsForDisplay(commits) {
+	if (commits.length === 0) return farver.dim("No commits found");
+	const maxCommitsToShow = 10;
+	const commitsToShow = commits.slice(0, maxCommitsToShow);
+	const hasMore = commits.length > maxCommitsToShow;
+	const typeLength = commits.map(({ type }) => type.length).reduce((a, b) => Math.max(a, b), 0);
+	const scopeLength = commits.map(({ scope }) => scope?.length).reduce((a, b) => Math.max(a || 0, b || 0), 0) || 0;
+	const formattedCommits = commitsToShow.map((commit) => {
+		let color = messageColorMap[commit.type] || ((c) => c);
+		if (commit.isBreaking) color = (s) => farver.inverse.red(s);
+		const paddedType = commit.type.padStart(typeLength + 1, " ");
+		const paddedScope = !commit.scope ? " ".repeat(scopeLength ? scopeLength + 2 : 0) : farver.dim("(") + commit.scope + farver.dim(")") + " ".repeat(scopeLength - commit.scope.length);
+		return [
+			farver.dim(commit.shortHash),
+			" ",
+			color === farver.gray ? color(paddedType) : farver.bold(color(paddedType)),
+			" ",
+			paddedScope,
+			farver.dim(":"),
+			" ",
+			color === farver.gray ? color(commit.description) : commit.description
+		].join("");
+	}).join("\n");
+	if (hasMore) return `${formattedCommits}\n  ${farver.dim(`... and ${commits.length - maxCommitsToShow} more commits`)}`;
+	return formattedCommits;
+}
+/**
+* Pure function that resolves version bump from commits and overrides.
+* No IO, no prompts - fully testable in isolation.
+*/
+function resolveAutoVersion(pkg, packageCommits, globalCommits, override) {
+	const determinedBump = determineHighestBump([...packageCommits, ...globalCommits]);
+	const effectiveBump = override?.type || determinedBump;
+	const autoVersion = getNextVersion(pkg.version, determinedBump);
+	return {
+		determinedBump,
+		effectiveBump,
+		autoVersion,
+		resolvedVersion: override?.version || autoVersion
+	};
+}
+/**
+* Pure function that computes the new dependency range.
+* Returns null if the dependency should not be updated (e.g. workspace:*).
+*/
+function computeDependencyRange(currentRange, newVersion, isPeerDependency) {
+	if (currentRange === "workspace:*") return null;
+	if (isPeerDependency) {
+		const majorVersion = newVersion.split(".")[0];
+		return `>=${newVersion} <${Number(majorVersion) + 1}.0.0`;
+	}
+	return `^${newVersion}`;
+}
+async function calculateVersionUpdates({ workspacePackages, packageCommits, workspaceRoot, showPrompt, globalCommitsPerPackage, overrides: initialOverrides = {} }) {
+	const versionUpdates = [];
+	const processedPackages = /* @__PURE__ */ new Set();
+	const newOverrides = { ...initialOverrides };
+	const excludedPackages = /* @__PURE__ */ new Set();
+	logger.verbose(`Starting version inference for ${packageCommits.size} packages with commits`);
+	for (const [pkgName, pkgCommits] of packageCommits) {
+		const pkg = workspacePackages.find((p) => p.name === pkgName);
+		if (!pkg) {
+			logger.error(`Package ${pkgName} not found in workspace packages, skipping`);
+			continue;
+		}
+		processedPackages.add(pkgName);
+		const globalCommits = globalCommitsPerPackage.get(pkgName) || [];
+		const allCommitsForPackage = [...pkgCommits, ...globalCommits];
+		const override = newOverrides[pkgName];
+		const { determinedBump, effectiveBump, autoVersion, resolvedVersion } = resolveAutoVersion(pkg, pkgCommits, globalCommits, override);
+		const canPrompt = !getIsCI() && showPrompt;
+		if (effectiveBump === "none" && !canPrompt) continue;
+		let newVersion = resolvedVersion;
+		let finalBumpType = effectiveBump;
+		if (canPrompt) {
+			logger.clearScreen();
+			logger.section(`📝 Commits for ${farver.cyan(pkg.name)}`);
+			formatCommitsForDisplay(allCommitsForPackage).split("\n").forEach((line) => logger.item(line));
+			logger.item(farver.dim(`Auto bump: ${determinedBump} → ${autoVersion}`));
+			logger.emptyLine();
+			if (override) {
+				const overrideChoice = await confirmOverridePrompt(pkg, override.version);
+				if (overrideChoice === null) continue;
+				if (overrideChoice === "use") {
+					newOverrides[pkgName] = {
+						type: override.type,
+						version: override.version
+					};
+					if (override.version === pkg.version) excludedPackages.add(pkgName);
+					versionUpdates.push({
+						package: pkg,
+						currentVersion: pkg.version,
+						newVersion: override.version,
+						bumpType: override.type,
+						hasDirectChanges: allCommitsForPackage.length > 0,
+						changeKind: override.version === pkg.version ? "as-is" : "manual"
+					});
+					continue;
+				}
+				newVersion = autoVersion;
+			}
+			const selectedVersion = await selectVersionPrompt(workspaceRoot, pkg, pkg.version, newVersion, {
+				defaultChoice: override ? "suggested" : "auto",
+				suggestedHint: `auto: ${determinedBump} → ${autoVersion}`
+			});
+			if (selectedVersion === null) continue;
+			const userBump = calculateBumpType(pkg.version, selectedVersion);
+			finalBumpType = userBump;
+			if (selectedVersion === pkg.version) {
+				excludedPackages.add(pkgName);
+				newOverrides[pkgName] = {
+					type: "none",
+					version: pkg.version
+				};
+				logger.info(`Override set for ${pkgName}: manual as-is (${pkg.version})`);
+				versionUpdates.push({
+					package: pkg,
+					currentVersion: pkg.version,
+					newVersion: pkg.version,
+					bumpType: "none",
+					hasDirectChanges: allCommitsForPackage.length > 0,
+					changeKind: "as-is"
+				});
+				continue;
+			}
+			newOverrides[pkgName] = {
+				type: userBump,
+				version: selectedVersion
+			};
+			logger.info(`Override set for ${pkgName}: manual ${userBump} (${selectedVersion})`);
+			newVersion = selectedVersion;
+		}
+		versionUpdates.push({
+			package: pkg,
+			currentVersion: pkg.version,
+			newVersion,
+			bumpType: finalBumpType,
+			hasDirectChanges: allCommitsForPackage.length > 0,
+			changeKind: canPrompt ? "manual" : "auto"
+		});
+	}
+	if (!getIsCI() && showPrompt) for (const pkg of workspacePackages) {
+		if (processedPackages.has(pkg.name)) continue;
+		logger.clearScreen();
+		logger.section(`📦 Package: ${pkg.name}`);
+		logger.item("No direct commits found");
+		logger.item(farver.dim(`Auto bump: none → ${pkg.version}`));
+		const newVersion = await selectVersionPrompt(workspaceRoot, pkg, pkg.version, pkg.version, {
+			defaultChoice: "auto",
+			suggestedHint: `auto: none → ${pkg.version}`
+		});
+		if (newVersion === null) break;
+		if (newVersion === pkg.version) {
+			excludedPackages.add(pkg.name);
+			newOverrides[pkg.name] = {
+				type: "none",
+				version: pkg.version
+			};
+			logger.info(`Override set for ${pkg.name}: manual as-is (${pkg.version})`);
 			continue;
 		}
-		let newVersion = getNextVersion(pkg.version, bump);
-		if (!isCI && showPrompt) newVersion = await promptVersionOverride(pkg, workspaceRoot, pkg.version, newVersion, bump);
+		const bumpType = calculateBumpType(pkg.version, newVersion);
+		newOverrides[pkg.name] = {
+			type: bumpType,
+			version: newVersion
+		};
+		logger.info(`Override set for ${pkg.name}: manual ${bumpType} (${newVersion})`);
 		versionUpdates.push({
 			package: pkg,
 			currentVersion: pkg.version,
 			newVersion,
-			bumpType: bump,
-			hasDirectChanges: true
+			bumpType,
+			hasDirectChanges: false,
+			changeKind: "manual"
 		});
 	}
-	return versionUpdates;
+	return {
+		updates: versionUpdates,
+		overrides: newOverrides,
+		excludedPackages
+	};
+}
+/**
+* Calculate version updates and prepare dependent updates
+* Returns both the updates and a function to apply them
+*/
+async function calculateAndPrepareVersionUpdates({ workspacePackages, packageCommits, workspaceRoot, showPrompt, globalCommitsPerPackage, overrides }) {
+	const { updates: directUpdates, overrides: newOverrides, excludedPackages: promptExcludedPackages } = await calculateVersionUpdates({
+		workspacePackages,
+		packageCommits,
+		workspaceRoot,
+		showPrompt,
+		globalCommitsPerPackage,
+		overrides
+	});
+	const graph = buildPackageDependencyGraph(workspacePackages);
+	const overrideExcludedPackages = new Set(Object.entries(newOverrides).filter(([, override]) => override.type === "none").map(([pkgName]) => pkgName));
+	const allUpdates = createDependentUpdates(graph, workspacePackages, directUpdates, new Set([...overrideExcludedPackages, ...promptExcludedPackages]));
+	const applyUpdates = async () => {
+		await Promise.all(allUpdates.map(async (update) => {
+			const depUpdates = getDependencyUpdates(update.package, allUpdates);
+			await updatePackageJson(update.package, update.newVersion, depUpdates);
+		}));
+	};
+	return {
+		allUpdates,
+		applyUpdates,
+		overrides: newOverrides
+	};
 }
 async function updatePackageJson(pkg, newVersion, dependencyUpdates) {
 	const packageJsonPath = join(pkg.path, "package.json");
 	const content = await readFile(packageJsonPath, "utf-8");
 	const packageJson = JSON.parse(content);
 	packageJson.version = newVersion;
-	for (const [depName, depVersion] of dependencyUpdates) {
-		if (packageJson.dependencies?.[depName]) {
-			if (packageJson.dependencies[depName] === "workspace:*") continue;
-			packageJson.dependencies[depName] = `^${depVersion}`;
-		}
-		if (packageJson.devDependencies?.[depName]) {
-			if (packageJson.devDependencies[depName] === "workspace:*") continue;
-			packageJson.devDependencies[depName] = `^${depVersion}`;
-		}
-		if (packageJson.peerDependencies?.[depName]) {
-			if (packageJson.peerDependencies[depName] === "workspace:*") continue;
-			packageJson.peerDependencies[depName] = `^${depVersion}`;
+	function updateDependency(deps, depName, depVersion, isPeerDependency = false) {
+		if (!deps) return;
+		const oldVersion = deps[depName];
+		if (!oldVersion) return;
+		const newRange = computeDependencyRange(oldVersion, depVersion, isPeerDependency);
+		if (newRange === null) {
+			logger.verbose(`  - Skipping workspace:* dependency: ${depName}`);
+			return;
 		}
+		deps[depName] = newRange;
+		logger.verbose(`  - Updated dependency ${depName}: ${oldVersion} → ${newRange}`);
+	}
+	for (const [depName, depVersion] of dependencyUpdates) {
+		updateDependency(packageJson.dependencies, depName, depVersion);
+		updateDependency(packageJson.devDependencies, depName, depVersion);
+		updateDependency(packageJson.peerDependencies, depName, depVersion, true);
 	}
 	await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf-8");
+	logger.verbose(`  - Successfully wrote updated package.json`);
 }
 /**
 * Get all dependency updates needed for a package
@@ -603,261 +2140,697 @@ function getDependencyUpdates(pkg, allUpdates) {
 	const allDeps = [...pkg.workspaceDependencies, ...pkg.workspaceDevDependencies];
 	for (const dep of allDeps) {
 		const update = allUpdates.find((u) => u.package.name === dep);
-		if (update) updates.set(dep, update.newVersion);
+		if (update) {
+			logger.verbose(`  - Dependency ${dep} will be updated: ${update.currentVersion} → ${update.newVersion} (${update.bumpType})`);
+			updates.set(dep, update.newVersion);
+		}
 	}
+	if (updates.size === 0) logger.verbose(`  - No dependency updates needed`);
 	return updates;
 }
 
 //#endregion
-//#region src/package.ts
-/**
-* Build a dependency graph from workspace packages
-*
-* Creates a bidirectional graph that maps:
-* - packages: Map of package name → WorkspacePackage
-* - dependents: Map of package name → Set of packages that depend on it
-*
-* @param packages - All workspace packages
-* @returns Dependency graph with packages and dependents maps
-*/
-function buildPackageDependencyGraph(packages) {
-	const packagesMap = /* @__PURE__ */ new Map();
-	const dependents = /* @__PURE__ */ new Map();
-	for (const pkg of packages) {
-		packagesMap.set(pkg.name, pkg);
-		dependents.set(pkg.name, /* @__PURE__ */ new Set());
+//#region src/operations/calculate.ts
+async function calculateUpdates(options) {
+	const { workspacePackages, workspaceRoot, showPrompt, overrides, globalCommitMode } = options;
+	try {
+		const grouped = await getWorkspacePackageGroupedCommits(workspaceRoot, workspacePackages);
+		return ok(await calculateAndPrepareVersionUpdates({
+			workspacePackages,
+			packageCommits: grouped,
+			workspaceRoot,
+			showPrompt,
+			globalCommitsPerPackage: await getGlobalCommitsPerPackage(workspaceRoot, grouped, workspacePackages, globalCommitMode),
+			overrides
+		}));
+	} catch (error) {
+		const formatted = formatUnknownError(error);
+		return err({
+			type: "git",
+			operation: "calculateUpdates",
+			message: formatted.message,
+			stderr: formatted.stderr
+		});
 	}
-	for (const pkg of packages) {
-		const allDeps = [...pkg.workspaceDependencies, ...pkg.workspaceDevDependencies];
-		for (const dep of allDeps) {
-			const depSet = dependents.get(dep);
-			if (depSet) depSet.add(pkg.name);
+}
+function ensureHasPackages(packages) {
+	if (packages.length === 0) return err({
+		type: "git",
+		operation: "discoverWorkspacePackages",
+		message: "No packages found to release"
+	});
+	return ok(packages);
+}
+
+//#endregion
+//#region src/operations/pr.ts
+async function syncPullRequest(options) {
+	const { github, releaseBranch, defaultBranch, pullRequestTitle, pullRequestBody, updates } = options;
+	let existing = null;
+	try {
+		existing = await github.getExistingPullRequest(releaseBranch);
+	} catch (error) {
+		return {
+			ok: false,
+			error: toGitHubError("getExistingPullRequest", error)
+		};
+	}
+	const doesExist = !!existing;
+	const title = existing?.title || pullRequestTitle || "chore: update package versions";
+	const body = generatePullRequestBody(updates, pullRequestBody);
+	let pr = null;
+	try {
+		pr = await github.upsertPullRequest({
+			pullNumber: existing?.number,
+			title,
+			body,
+			head: releaseBranch,
+			base: defaultBranch
+		});
+	} catch (error) {
+		return {
+			ok: false,
+			error: toGitHubError("upsertPullRequest", error)
+		};
+	}
+	return ok({
+		pullRequest: pr,
+		created: !doesExist
+	});
+}
+
+//#endregion
+//#region src/workflows/prepare.ts
+async function prepareWorkflow(options) {
+	if (options.safeguards) {
+		const clean = await isWorkingDirectoryClean(options.workspaceRoot);
+		if (!clean.ok) exitWithError("Failed to verify working directory state.", "Ensure this is a valid git repository and try again.", clean.error);
+		if (!clean.value) exitWithError("Working directory is not clean. Please commit or stash your changes before proceeding.");
+	}
+	const discovered = await discoverWorkspacePackages(options.workspaceRoot, options);
+	if (!discovered.ok) exitWithError("Failed to discover packages.", void 0, discovered.error);
+	const ensured = ensureHasPackages(discovered.value);
+	if (!ensured.ok) {
+		logger.warn(ensured.error.message);
+		return null;
+	}
+	const workspacePackages = ensured.value;
+	logger.section("📦 Workspace Packages");
+	logger.item(`Found ${workspacePackages.length} packages`);
+	for (const pkg of workspacePackages) {
+		logger.item(`${farver.cyan(pkg.name)} (${farver.bold(pkg.version)})`);
+		logger.item(`  ${farver.gray("→")} ${farver.gray(pkg.path)}`);
+	}
+	logger.emptyLine();
+	const prepareBranchResult = await prepareReleaseBranch({
+		workspaceRoot: options.workspaceRoot,
+		releaseBranch: options.branch.release,
+		defaultBranch: options.branch.default
+	});
+	if (!prepareBranchResult.ok) exitWithError("Failed to prepare release branch.", void 0, prepareBranchResult.error);
+	const overridesPath = join(options.workspaceRoot, ucdjsReleaseOverridesPath);
+	let existingOverrides = {};
+	try {
+		const overridesContent = await readFile(overridesPath, "utf-8");
+		existingOverrides = JSON.parse(overridesContent);
+		logger.info("Found existing version overrides file.");
+	} catch (error) {
+		logger.info("No existing version overrides file found. Continuing...");
+		logger.verbose(`Reading overrides file failed: ${formatUnknownError(error).message}`);
+	}
+	const updatesResult = await calculateUpdates({
+		workspacePackages,
+		workspaceRoot: options.workspaceRoot,
+		showPrompt: options.prompts?.versions !== false,
+		globalCommitMode: options.globalCommitMode === "none" ? false : options.globalCommitMode,
+		overrides: existingOverrides
+	});
+	if (!updatesResult.ok) exitWithError("Failed to calculate package updates.", void 0, updatesResult.error);
+	const { allUpdates, applyUpdates, overrides: newOverrides } = updatesResult.value;
+	const hasOverrideChanges = JSON.stringify(existingOverrides) !== JSON.stringify(newOverrides);
+	if (Object.keys(newOverrides).length > 0 && hasOverrideChanges) {
+		logger.step("Writing version overrides file...");
+		try {
+			await mkdir(join(options.workspaceRoot, ".github"), { recursive: true });
+			await writeFile(overridesPath, JSON.stringify(newOverrides, null, 2), "utf-8");
+			logger.success("Successfully wrote version overrides file.");
+		} catch (e) {
+			logger.error("Failed to write version overrides file:", e);
+		}
+	} else if (Object.keys(newOverrides).length > 0) logger.step("Version overrides unchanged. Skipping write.");
+	if (Object.keys(newOverrides).length === 0 && hasOverrideChanges) {
+		logger.info("Removing obsolete version overrides file...");
+		try {
+			await rm(overridesPath);
+			logger.success("Successfully removed obsolete version overrides file.");
+		} catch (e) {
+			if (formatUnknownError(e).code !== "ENOENT") logger.error("Failed to remove obsolete version overrides file:", e);
+		}
+	}
+	if (allUpdates.filter((u) => u.hasDirectChanges).length === 0) logger.warn("No packages have changes requiring a release");
+	logger.section("🔄 Version Updates");
+	logger.item(`Updating ${allUpdates.length} packages (including dependents)`);
+	for (const update of allUpdates) {
+		const suffix = update.changeKind === "as-is" ? farver.dim(" (as-is)") : "";
+		logger.item(`${update.package.name}: ${update.currentVersion} → ${update.newVersion}${suffix}`);
+	}
+	await applyUpdates();
+	if (options.changelog?.enabled) {
+		logger.step("Updating changelogs");
+		const groupedPackageCommits = await getWorkspacePackageGroupedCommits(options.workspaceRoot, workspacePackages);
+		const globalCommitsPerPackage = await getGlobalCommitsPerPackage(options.workspaceRoot, groupedPackageCommits, workspacePackages, options.globalCommitMode === "none" ? false : options.globalCommitMode);
+		const changelogPromises = allUpdates.map((update) => {
+			return (async () => {
+				let pkgCommits = groupedPackageCommits.get(update.package.name) || [];
+				let globalCommits = globalCommitsPerPackage.get(update.package.name) || [];
+				let previousVersionForChangelog = update.currentVersion !== "0.0.0" ? update.currentVersion : void 0;
+				if (options.changelog.combinePrereleaseIntoFirstStable && semver.prerelease(update.currentVersion) != null && semver.prerelease(update.newVersion) == null) {
+					const stableTagResult = await getMostRecentPackageStableTag(options.workspaceRoot, update.package.name);
+					if (!stableTagResult.ok) logger.warn(`Failed to resolve stable tag for ${update.package.name}: ${stableTagResult.error.message}`);
+					else {
+						const stableTag = stableTagResult.value;
+						if (stableTag) {
+							logger.verbose(`Combining prerelease changelog entries into stable release for ${update.package.name} using base tag ${stableTag}`);
+							const stableBaseCommits = await getPackageCommitsSinceTag(options.workspaceRoot, update.package, stableTag);
+							pkgCommits = stableBaseCommits;
+							globalCommits = (await getGlobalCommitsPerPackage(options.workspaceRoot, new Map([[update.package.name, stableBaseCommits]]), workspacePackages, options.globalCommitMode === "none" ? false : options.globalCommitMode)).get(update.package.name) || [];
+							const atIndex = stableTag.lastIndexOf("@");
+							if (atIndex !== -1) previousVersionForChangelog = stableTag.slice(atIndex + 1);
+						}
+					}
+				}
+				const allCommits = [...pkgCommits, ...globalCommits];
+				if (allCommits.length === 0) logger.verbose(`No commits for ${update.package.name}, writing changelog entry with no-significant-commits note`);
+				logger.verbose(`Updating changelog for ${farver.cyan(update.package.name)}`);
+				await updateChangelog({
+					normalizedOptions: {
+						...options,
+						workspaceRoot: options.workspaceRoot
+					},
+					githubClient: options.githubClient,
+					workspacePackage: update.package,
+					version: update.newVersion,
+					previousVersion: previousVersionForChangelog,
+					commits: allCommits,
+					date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+				});
+			})();
+		}).filter((p) => p != null);
+		const updates = await Promise.all(changelogPromises);
+		logger.success(`Updated ${updates.length} changelog(s)`);
+	}
+	const hasChangesToPush = await syncReleaseChanges({
+		workspaceRoot: options.workspaceRoot,
+		releaseBranch: options.branch.release,
+		commitMessage: "chore: update release versions",
+		hasChanges: true
+	});
+	if (!hasChangesToPush.ok) exitWithError("Failed to sync release changes.", void 0, hasChangesToPush.error);
+	if (!hasChangesToPush.value) {
+		const prResult = await syncPullRequest({
+			github: options.githubClient,
+			releaseBranch: options.branch.release,
+			defaultBranch: options.branch.default,
+			pullRequestTitle: options.pullRequest?.title,
+			pullRequestBody: options.pullRequest?.body,
+			updates: allUpdates
+		});
+		if (!prResult.ok) exitWithError("Failed to sync release pull request.", void 0, prResult.error);
+		if (prResult.value.pullRequest) {
+			logger.item("No updates needed, PR is already up to date");
+			const checkoutResult = await checkoutBranch(options.branch.default, options.workspaceRoot);
+			if (!checkoutResult.ok) exitWithError(`Failed to checkout branch: ${options.branch.default}`, void 0, checkoutResult.error);
+			return {
+				updates: allUpdates,
+				prUrl: prResult.value.pullRequest.html_url,
+				created: prResult.value.created
+			};
 		}
+		logger.error("No changes to commit, and no existing PR. Nothing to do.");
+		return null;
+	}
+	const prResult = await syncPullRequest({
+		github: options.githubClient,
+		releaseBranch: options.branch.release,
+		defaultBranch: options.branch.default,
+		pullRequestTitle: options.pullRequest?.title,
+		pullRequestBody: options.pullRequest?.body,
+		updates: allUpdates
+	});
+	if (!prResult.ok) exitWithError("Failed to sync release pull request.", void 0, prResult.error);
+	if (prResult.value.pullRequest?.html_url) {
+		logger.section("🚀 Pull Request");
+		logger.success(`Pull request ${prResult.value.created ? "created" : "updated"}: ${prResult.value.pullRequest.html_url}`);
 	}
+	const returnToDefault = await checkoutBranch(options.branch.default, options.workspaceRoot);
+	if (!returnToDefault.ok) exitWithError(`Failed to checkout branch: ${options.branch.default}`, void 0, returnToDefault.error);
+	if (!returnToDefault.value) exitWithError(`Failed to checkout branch: ${options.branch.default}`);
 	return {
-		packages: packagesMap,
-		dependents
+		updates: allUpdates,
+		prUrl: prResult.value.pullRequest?.html_url,
+		created: prResult.value.created
+	};
+}
+
+//#endregion
+//#region src/core/npm.ts
+function toNPMError(operation, error, code) {
+	const formatted = formatUnknownError(error);
+	return {
+		type: "npm",
+		operation,
+		message: formatted.message,
+		code: code || formatted.code,
+		stderr: formatted.stderr,
+		status: formatted.status
 	};
 }
+function classifyPublishErrorCode(error) {
+	const formatted = formatUnknownError(error);
+	const combined = [formatted.message, formatted.stderr].filter(Boolean).join("\n");
+	if (combined.includes("E403") || combined.toLowerCase().includes("access token expired or revoked")) return "E403";
+	if (combined.includes("EPUBLISHCONFLICT") || combined.includes("E409") || combined.includes("409 Conflict") || combined.includes("Failed to save packument")) return "EPUBLISHCONFLICT";
+	if (combined.includes("EOTP")) return "EOTP";
+}
+function wait(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
-* Get all packages affected by changes (including transitive dependents)
-*
-* Uses graph traversal to find all packages that need updates:
-* - Packages with direct changes
-* - All packages that depend on changed packages (transitively)
-*
-* @param graph - Dependency graph
-* @param changedPackages - Set of package names with direct changes
-* @returns Set of all package names that need updates
+* Get the NPM registry URL
+* Respects NPM_CONFIG_REGISTRY environment variable, defaults to npmjs.org
 */
-function getAllAffectedPackages(graph, changedPackages) {
-	const affected = /* @__PURE__ */ new Set();
-	function visitDependents(pkgName) {
-		if (affected.has(pkgName)) return;
-		affected.add(pkgName);
-		const dependents = graph.dependents.get(pkgName);
-		if (dependents) for (const dependent of dependents) visitDependents(dependent);
+function getRegistryURL() {
+	return process.env.NPM_CONFIG_REGISTRY || "https://registry.npmjs.org";
+}
+/**
+* Fetch package metadata from NPM registry
+* @param packageName - The package name (e.g., "lodash" or "@scope/name")
+* @returns Result with package metadata or error
+*/
+async function getPackageMetadata(packageName) {
+	try {
+		const registry = getRegistryURL();
+		const encodedName = packageName.startsWith("@") ? `@${encodeURIComponent(packageName.slice(1))}` : encodeURIComponent(packageName);
+		const response = await fetch(`${registry}/${encodedName}`, { headers: { Accept: "application/json" } });
+		if (!response.ok) {
+			if (response.status === 404) return err(toNPMError("getPackageMetadata", `Package not found: ${packageName}`, "E404"));
+			return err(toNPMError("getPackageMetadata", `HTTP ${response.status}: ${response.statusText}`));
+		}
+		return ok(await response.json());
+	} catch (error) {
+		return err(toNPMError("getPackageMetadata", error, "ENETWORK"));
 	}
-	for (const pkg of changedPackages) visitDependents(pkg);
-	return affected;
 }
 /**
-* Create version updates for all packages affected by dependency changes
-*
-* When a package is updated, all packages that depend on it should also be updated.
-* This function calculates which additional packages need patch bumps due to dependency changes.
-*
-* @param graph - Dependency graph
-* @param workspacePackages - All workspace packages
-* @param directUpdates - Packages with direct code changes
-* @returns All updates including dependent packages that need patch bumps
+* Check if a specific package version exists on NPM
+* @param packageName - The package name
+* @param version - The version to check (e.g., "1.2.3")
+* @returns Result with boolean (true if version exists) or error
 */
-function createDependentUpdates(graph, workspacePackages, directUpdates) {
-	const allUpdates = [...directUpdates];
-	const directUpdateMap = new Map(directUpdates.map((u) => [u.package.name, u]));
-	const affectedPackages = getAllAffectedPackages(graph, new Set(directUpdates.map((u) => u.package.name)));
-	for (const pkgName of affectedPackages) {
-		if (directUpdateMap.has(pkgName)) continue;
-		const pkg = workspacePackages.find((p) => p.name === pkgName);
-		if (!pkg) continue;
-		allUpdates.push(createVersionUpdate(pkg, "patch", false));
+async function checkVersionExists(packageName, version) {
+	const metadataResult = await getPackageMetadata(packageName);
+	if (!metadataResult.ok) {
+		if (metadataResult.error.code === "E404") return ok(false);
+		return err(metadataResult.error);
 	}
-	return allUpdates;
+	return ok(version in metadataResult.value.versions);
 }
 /**
-* Update all package.json files with new versions and dependency updates
-*
-* Updates are performed in parallel for better performance.
-*
-* @param updates - Version updates to apply
+* Publish a package to NPM
+* Uses pnpm to handle workspace protocol and catalog: resolution automatically
+* @param packageName - The package name to publish
+* @param version - The package version to publish
+* @param workspaceRoot - Path to the workspace root
+* @param options - Normalized release scripts options
+* @returns Result indicating success or failure
 */
-async function updateAllPackageJsonFiles(updates) {
-	await Promise.all(updates.map(async (update) => {
-		const depUpdates = getDependencyUpdates(update.package, updates);
-		await updatePackageJson(update.package, update.newVersion, depUpdates);
-	}));
+async function publishPackage(packageName, version, workspaceRoot, options) {
+	const args = [
+		"--filter",
+		packageName,
+		"publish",
+		"--access",
+		options.npm.access,
+		"--no-git-checks"
+	];
+	if (options.npm.otp) args.push("--otp", options.npm.otp);
+	const explicitTag = process.env.NPM_CONFIG_TAG;
+	const prereleaseTag = (() => {
+		const prerelease = semver.prerelease(version);
+		if (!prerelease || prerelease.length === 0) return;
+		const identifier = prerelease[0];
+		if (identifier === "alpha" || identifier === "beta") return identifier;
+		return "next";
+	})();
+	const publishTag = explicitTag || prereleaseTag;
+	if (publishTag) args.push("--tag", publishTag);
+	const env = { ...process.env };
+	if (options.npm.provenance) env.NPM_CONFIG_PROVENANCE = "true";
+	const maxAttempts = 4;
+	const backoffMs = [
+		3e3,
+		8e3,
+		15e3
+	];
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) try {
+		const result = await runIfNotDry("pnpm", args, { nodeOptions: {
+			cwd: workspaceRoot,
+			stdio: "pipe",
+			env
+		} });
+		if (result?.stdout && result.stdout.trim()) logger.verbose(result.stdout.trim());
+		if (result?.stderr && result.stderr.trim()) logger.verbose(result.stderr.trim());
+		return ok(void 0);
+	} catch (error) {
+		const code = classifyPublishErrorCode(error);
+		if (code === "EPUBLISHCONFLICT" && attempt < maxAttempts) {
+			const delay = backoffMs[attempt - 1] ?? backoffMs[backoffMs.length - 1];
+			logger.warn(`Publish conflict for ${packageName}@${version} (attempt ${attempt}/${maxAttempts}). Retrying in ${Math.ceil(delay / 1e3)}s...`);
+			await wait(delay);
+			continue;
+		}
+		return err(toNPMError("publishPackage", error, code));
+	}
+	return err(toNPMError("publishPackage", /* @__PURE__ */ new Error(`Failed to publish ${packageName}@${version} after ${maxAttempts} attempts`), "EPUBLISHCONFLICT"));
 }
 
 //#endregion
-//#region src/workspace.ts
-async function discoverWorkspacePackages(workspaceRoot, options) {
-	let workspaceOptions;
-	let explicitPackages;
-	if (options.packages == null || options.packages === true) workspaceOptions = { excludePrivate: false };
-	else if (Array.isArray(options.packages)) {
-		workspaceOptions = {
-			excludePrivate: false,
-			include: options.packages
-		};
-		explicitPackages = options.packages;
-	} else {
-		workspaceOptions = options.packages;
-		if (options.packages.include) explicitPackages = options.packages.include;
-	}
-	let workspacePackages = await findWorkspacePackages(workspaceRoot, workspaceOptions);
-	if (explicitPackages) {
-		const foundNames = new Set(workspacePackages.map((p) => p.name));
-		const missing = explicitPackages.filter((p) => !foundNames.has(p));
-		if (missing.length > 0) exitWithError(`Package${missing.length > 1 ? "s" : ""} not found in workspace: ${missing.join(", ")}`, "Check your package names or run 'pnpm ls' to see available packages");
-	}
-	const isPackagePromptEnabled = options.prompts?.packages !== false;
-	if (!isCI && isPackagePromptEnabled && !explicitPackages) {
-		const selectedNames = await selectPackagePrompt(workspacePackages);
-		workspacePackages = workspacePackages.filter((pkg) => selectedNames.includes(pkg.name));
+//#region src/workflows/publish.ts
+async function getReleaseBodyFromChangelog(workspaceRoot, packageName, packagePath, version) {
+	const changelogPath = join(packagePath, "CHANGELOG.md");
+	try {
+		const entry = parseChangelog(await readFile(changelogPath, "utf-8")).versions.find((v) => v.version === version);
+		if (!entry) return [
+			`## ${packageName}@${version}`,
+			"",
+			"⚠️ Could not find a matching changelog entry for this version.",
+			"",
+			`Expected version ${version} in ${changelogPath}.`
+		].join("\n");
+		const lines = entry.content.trim().split("\n");
+		if (lines[0]?.trim().startsWith("## ")) return lines.slice(1).join("\n").trim();
+		return entry.content.trim();
+	} catch {
+		logger.verbose(`Could not read changelog entry for ${version} at ${changelogPath}`);
+		return [
+			`## ${packageName}@${version}`,
+			"",
+			"⚠️ Could not read package changelog while creating this release.",
+			"",
+			`Expected changelog file: ${changelogPath}`
+		].join("\n");
 	}
-	return workspacePackages;
 }
-async function findWorkspacePackages(workspaceRoot, options) {
+async function cleanupPublishedOverrides(options, workspacePackages, publishedPackageNames) {
+	if (publishedPackageNames.length === 0) return false;
+	if (options.dryRun) {
+		logger.verbose("Dry-run: skipping override cleanup");
+		return false;
+	}
+	const overridesPath = join(options.workspaceRoot, ucdjsReleaseOverridesPath);
+	let overrides;
 	try {
-		const result = await run("pnpm", [
-			"-r",
-			"ls",
-			"--json"
-		], { nodeOptions: {
-			cwd: workspaceRoot,
-			stdio: "pipe"
-		} });
-		const rawProjects = JSON.parse(result.stdout);
-		const allPackageNames = new Set(rawProjects.map((p) => p.name));
-		const excludedPackages = /* @__PURE__ */ new Set();
-		const promises = rawProjects.map(async (rawProject) => {
-			const content = await readFile(join(rawProject.path, "package.json"), "utf-8");
-			const packageJson = JSON.parse(content);
-			if (!shouldIncludePackage(packageJson, options)) {
-				excludedPackages.add(rawProject.name);
-				return null;
-			}
-			return {
-				name: rawProject.name,
-				version: rawProject.version,
-				path: rawProject.path,
-				packageJson,
-				workspaceDependencies: Object.keys(rawProject.dependencies || []).filter((dep) => {
-					return allPackageNames.has(dep);
-				}),
-				workspaceDevDependencies: Object.keys(rawProject.devDependencies || []).filter((dep) => {
-					return allPackageNames.has(dep);
-				})
-			};
-		});
-		const packages = await Promise.all(promises);
-		if (excludedPackages.size > 0) logger.info(`Excluded packages: ${farver.green(Array.from(excludedPackages).join(", "))}`);
-		return packages.filter((pkg) => pkg !== null);
-	} catch (err) {
-		logger.error("Error discovering workspace packages:", err);
-		throw err;
+		overrides = JSON.parse(await readFile(overridesPath, "utf-8"));
+	} catch {
+		return false;
 	}
-}
-function shouldIncludePackage(pkg, options) {
-	if (!options) return true;
-	if (options.excludePrivate && pkg.private) return false;
-	if (options.include && options.include.length > 0) {
-		if (!options.include.includes(pkg.name)) return false;
+	const versionsByPackage = new Map(workspacePackages.map((pkg) => [pkg.name, pkg.version]));
+	const publishedSet = new Set(publishedPackageNames);
+	const removed = [];
+	for (const [pkgName, override] of Object.entries(overrides)) {
+		if (!publishedSet.has(pkgName)) continue;
+		const currentVersion = versionsByPackage.get(pkgName);
+		const current = currentVersion ? semver.valid(currentVersion) : null;
+		const target = semver.valid(override.version);
+		if (current && target && semver.gte(current, target)) {
+			delete overrides[pkgName];
+			removed.push(pkgName);
+		}
 	}
-	if (options.exclude?.includes(pkg.name)) return false;
+	if (removed.length === 0) return false;
+	logger.step(`Cleaning up satisfied overrides (${removed.length})...`);
+	if (Object.keys(overrides).length === 0) {
+		await rm(overridesPath, { force: true });
+		logger.success("Removed release override file (all entries satisfied)");
+		return true;
+	}
+	await writeFile(overridesPath, JSON.stringify(overrides, null, 2), "utf-8");
+	logger.success(`Removed satisfied overrides: ${removed.join(", ")}`);
 	return true;
 }
+async function publishWorkflow(options) {
+	logger.section("📦 Publishing Packages");
+	const discovered = await discoverWorkspacePackages(options.workspaceRoot, options);
+	if (!discovered.ok) exitWithError("Failed to discover packages.", void 0, discovered.error);
+	const workspacePackages = discovered.value;
+	logger.item(`Found ${workspacePackages.length} packages in workspace`);
+	const graph = buildPackageDependencyGraph(workspacePackages);
+	const publicPackages = workspacePackages.filter((pkg) => !pkg.packageJson.private);
+	logger.item(`Publishing ${publicPackages.length} public packages (private packages excluded)`);
+	if (publicPackages.length === 0) {
+		logger.warn("No public packages to publish");
+		return;
+	}
+	const publishOrder = getPackagePublishOrder(graph, new Set(publicPackages.map((p) => p.name)));
+	const status = {
+		published: [],
+		skipped: [],
+		failed: []
+	};
+	for (const order of publishOrder) {
+		const pkg = order.package;
+		const version = pkg.version;
+		const packageName = pkg.name;
+		logger.section(`📦 ${farver.cyan(packageName)} ${farver.gray(`(level ${order.level})`)}`);
+		logger.step(`Checking if ${farver.cyan(`${packageName}@${version}`)} exists on NPM...`);
+		const existsResult = await checkVersionExists(packageName, version);
+		if (!existsResult.ok) {
+			logger.error(`Failed to check version: ${existsResult.error.message}`);
+			status.failed.push(packageName);
+			exitWithError(`Publishing failed for ${packageName}.`, "Check your network connection and NPM registry access", existsResult.error);
+		}
+		if (existsResult.value) {
+			logger.info(`Version ${farver.cyan(version)} already exists on NPM, skipping`);
+			status.skipped.push(packageName);
+			continue;
+		}
+		logger.step(`Publishing ${farver.cyan(`${packageName}@${version}`)} to NPM...`);
+		const publishResult = await publishPackage(packageName, version, options.workspaceRoot, options);
+		if (!publishResult.ok) {
+			logger.error(`Failed to publish: ${publishResult.error.message}`);
+			status.failed.push(packageName);
+			let hint;
+			if (publishResult.error.code === "E403") hint = "Authentication failed. Ensure your NPM token or OIDC configuration is correct";
+			else if (publishResult.error.code === "EPUBLISHCONFLICT") hint = "Version conflict. The version may have been published recently";
+			else if (publishResult.error.code === "EOTP") hint = "2FA/OTP required. Provide the otp option or use OIDC authentication";
+			exitWithError(`Publishing failed for ${packageName}`, hint, publishResult.error);
+		}
+		logger.success(`Published ${farver.cyan(`${packageName}@${version}`)}`);
+		status.published.push(packageName);
+		logger.step(`Creating git tag ${farver.cyan(`${packageName}@${version}`)}...`);
+		const tagResult = await createAndPushPackageTag(packageName, version, options.workspaceRoot);
+		const tagName = `${packageName}@${version}`;
+		if (!tagResult.ok) {
+			logger.error(`Failed to create/push tag: ${tagResult.error.message}`);
+			status.failed.push(packageName);
+			exitWithError(`Publishing failed for ${packageName}: could not create git tag`, "Ensure the workflow token can push tags (contents: write) and git credentials are configured", tagResult.error);
+		}
+		logger.success(`Created and pushed tag ${farver.cyan(tagName)}`);
+		logger.step(`Creating GitHub release for ${farver.cyan(tagName)}...`);
+		try {
+			const releaseBody = await getReleaseBodyFromChangelog(options.workspaceRoot, packageName, pkg.path, version);
+			const releaseResult = await options.githubClient.upsertReleaseByTag({
+				tagName,
+				name: tagName,
+				body: releaseBody,
+				prerelease: Boolean(semver.prerelease(version))
+			});
+			if (releaseResult.release.htmlUrl) logger.success(`${releaseResult.created ? "Created" : "Updated"} GitHub release: ${releaseResult.release.htmlUrl}`);
+			else logger.success(`${releaseResult.created ? "Created" : "Updated"} GitHub release for ${farver.cyan(tagName)}`);
+		} catch (error) {
+			status.failed.push(packageName);
+			exitWithError(`Publishing failed for ${packageName}: could not create GitHub release`, "Ensure the workflow token can write repository contents and releases", error);
+		}
+	}
+	logger.section("📊 Publishing Summary");
+	logger.item(`${farver.green("✓")} Published: ${status.published.length} package(s)`);
+	if (status.published.length > 0) for (const pkg of status.published) logger.item(`  ${farver.green("•")} ${pkg}`);
+	if (status.skipped.length > 0) {
+		logger.item(`${farver.yellow("⚠")} Skipped (already exists): ${status.skipped.length} package(s)`);
+		for (const pkg of status.skipped) logger.item(`  ${farver.yellow("•")} ${pkg}`);
+	}
+	if (status.failed.length > 0) {
+		logger.item(`${farver.red("✖")} Failed: ${status.failed.length} package(s)`);
+		for (const pkg of status.failed) logger.item(`  ${farver.red("•")} ${pkg}`);
+	}
+	if (status.failed.length > 0) exitWithError(`Publishing completed with ${status.failed.length} failure(s)`);
+	if (await cleanupPublishedOverrides(options, workspacePackages, status.published) && !options.dryRun) {
+		logger.step("Committing override cleanup...");
+		const commitResult = await commitPaths([ucdjsReleaseOverridesPath], "chore: cleanup release overrides", options.workspaceRoot);
+		if (!commitResult.ok) exitWithError("Failed to commit override cleanup.", void 0, commitResult.error);
+		if (commitResult.value) {
+			const currentBranch = await getCurrentBranch(options.workspaceRoot);
+			if (!currentBranch.ok) exitWithError("Failed to detect current branch for override cleanup push.", void 0, currentBranch.error);
+			const pushResult = await pushBranch(currentBranch.value, options.workspaceRoot);
+			if (!pushResult.ok) exitWithError("Failed to push override cleanup commit.", void 0, pushResult.error);
+			logger.success(`Pushed override cleanup commit to ${farver.cyan(currentBranch.value)}`);
+		}
+	}
+	logger.success("All packages published successfully!");
+}
 
 //#endregion
-//#region src/release.ts
-async function release(options) {
-	const normalizedOptions = normalizeSharedOptions(options);
-	normalizedOptions.dryRun ??= false;
-	normalizedOptions.releaseBranch ??= "release/next";
-	normalizedOptions.safeguards ??= true;
-	globalOptions.dryRun = normalizedOptions.dryRun;
-	const workspaceRoot = normalizedOptions.workspaceRoot;
-	if (normalizedOptions.safeguards && !await isWorkingDirectoryClean(workspaceRoot)) exitWithError("Working directory is not clean. Please commit or stash your changes before proceeding.");
-	const workspacePackages = await discoverWorkspacePackages(workspaceRoot, options);
-	if (workspacePackages.length === 0) {
-		logger.log("No packages found to analyze for release.");
-		return null;
+//#region src/workflows/verify.ts
+async function verifyWorkflow(options) {
+	if (options.safeguards) {
+		const clean = await isWorkingDirectoryClean(options.workspaceRoot);
+		if (!clean.ok) exitWithError("Failed to verify working directory state.", "Ensure this is a valid git repository and try again.", clean.error);
+		if (!clean.value) exitWithError("Working directory is not clean. Please commit or stash your changes before proceeding.");
 	}
-	const versionUpdates = await inferVersionUpdates(workspacePackages, await getWorkspacePackageCommits(workspaceRoot, workspacePackages), workspaceRoot, options.prompts?.versions !== false);
-	if (versionUpdates.length === 0) exitWithError("No packages have changes requiring a release", "Make sure you have commits since the last release");
-	const allUpdates = createDependentUpdates(buildPackageDependencyGraph(workspacePackages), workspacePackages, versionUpdates);
-	const currentBranch = await getCurrentBranch(workspaceRoot);
-	const existingPullRequest = await getExistingPullRequest({
-		owner: normalizedOptions.owner,
-		repo: normalizedOptions.repo,
-		branch: normalizedOptions.releaseBranch,
-		githubToken: normalizedOptions.githubToken
+	const releaseBranch = options.branch.release;
+	const defaultBranch = options.branch.default;
+	const releasePr = await options.githubClient.getExistingPullRequest(releaseBranch);
+	if (!releasePr || !releasePr.head) {
+		logger.warn(`No open release pull request found for branch "${releaseBranch}". Nothing to verify.`);
+		return;
+	}
+	logger.info(`Found release PR #${releasePr.number}. Verifying against default branch "${defaultBranch}"...`);
+	const originalBranch = await getCurrentBranch(options.workspaceRoot);
+	if (!originalBranch.ok) exitWithError("Failed to detect current branch.", void 0, originalBranch.error);
+	if (originalBranch.value !== defaultBranch) {
+		const checkout = await checkoutBranch(defaultBranch, options.workspaceRoot);
+		if (!checkout.ok) exitWithError(`Failed to checkout branch: ${defaultBranch}`, void 0, checkout.error);
+		if (!checkout.value) exitWithError(`Failed to checkout branch: ${defaultBranch}`);
+	}
+	let existingOverrides = {};
+	try {
+		const overridesContent = await readFileFromGit(options.workspaceRoot, releasePr.head.sha, ucdjsReleaseOverridesPath);
+		if (overridesContent.ok && overridesContent.value) {
+			existingOverrides = JSON.parse(overridesContent.value);
+			logger.info("Found existing version overrides file on release branch.");
+		}
+	} catch (error) {
+		logger.info("No version overrides file found on release branch. Continuing...");
+		logger.verbose(`Reading release overrides failed: ${formatUnknownError(error).message}`);
+	}
+	const discovered = await discoverWorkspacePackages(options.workspaceRoot, options);
+	if (!discovered.ok) exitWithError("Failed to discover packages.", void 0, discovered.error);
+	const ensured = ensureHasPackages(discovered.value);
+	if (!ensured.ok) {
+		logger.warn(ensured.error.message);
+		return;
+	}
+	const mainPackages = ensured.value;
+	const updatesResult = await calculateUpdates({
+		workspacePackages: mainPackages,
+		workspaceRoot: options.workspaceRoot,
+		showPrompt: false,
+		globalCommitMode: options.globalCommitMode === "none" ? false : options.globalCommitMode,
+		overrides: existingOverrides
 	});
-	const prExists = !!existingPullRequest;
-	if (prExists) logger.log("Existing pull request found:", existingPullRequest.html_url);
-	else logger.log("No existing pull request found, will create new one");
-	const branchExists = await doesBranchExist(normalizedOptions.releaseBranch, workspaceRoot);
-	if (!branchExists) {
-		logger.log("Creating release branch:", normalizedOptions.releaseBranch);
-		await createBranch(normalizedOptions.releaseBranch, currentBranch, workspaceRoot);
-	}
-	if (!await checkoutBranch(normalizedOptions.releaseBranch, workspaceRoot)) throw new Error(`Failed to checkout branch: ${normalizedOptions.releaseBranch}`);
-	if (branchExists) {
-		logger.log("Pulling latest changes from remote");
-		if (!await pullLatestChanges(normalizedOptions.releaseBranch, workspaceRoot)) logger.log("Warning: Failed to pull latest changes, continuing anyway");
-	}
-	logger.log("Rebasing release branch onto", currentBranch);
-	await rebaseBranch(currentBranch, workspaceRoot);
-	await updateAllPackageJsonFiles(allUpdates);
-	const hasCommitted = await commitChanges("chore: update release versions", workspaceRoot);
-	const isBranchAhead = await isBranchAheadOfRemote(normalizedOptions.releaseBranch, workspaceRoot);
-	if (!hasCommitted && !isBranchAhead) {
-		logger.log("No changes to commit and branch is in sync with remote");
-		await checkoutBranch(currentBranch, workspaceRoot);
-		if (prExists) {
-			logger.log("No updates needed, PR is already up to date");
-			return {
-				updates: allUpdates,
-				prUrl: existingPullRequest.html_url,
-				created: false
-			};
-		} else {
-			logger.error("No changes to commit, and no existing PR. Nothing to do.");
-			return null;
+	if (!updatesResult.ok) exitWithError("Failed to calculate expected package updates.", void 0, updatesResult.error);
+	const expectedUpdates = updatesResult.value.allUpdates;
+	const expectedVersionMap = new Map(expectedUpdates.map((u) => [u.package.name, u.newVersion]));
+	const prVersionMap = /* @__PURE__ */ new Map();
+	for (const pkg of mainPackages) {
+		const pkgJsonPath = relative(options.workspaceRoot, join(pkg.path, "package.json"));
+		const pkgJsonContent = await readFileFromGit(options.workspaceRoot, releasePr.head.sha, pkgJsonPath);
+		if (pkgJsonContent.ok && pkgJsonContent.value) {
+			const pkgJson = JSON.parse(pkgJsonContent.value);
+			prVersionMap.set(pkg.name, pkgJson.version);
 		}
 	}
-	logger.log("Pushing changes to remote");
-	await pushBranch(normalizedOptions.releaseBranch, workspaceRoot, { forceWithLease: true });
-	const prTitle = existingPullRequest?.title || options.pullRequest?.title || "chore: update package versions";
-	const prBody = generatePullRequestBody(allUpdates, options.pullRequest?.body);
-	const pullRequest = await upsertPullRequest({
-		owner: normalizedOptions.owner,
-		repo: normalizedOptions.repo,
-		pullNumber: existingPullRequest?.number,
-		title: prTitle,
-		body: prBody,
-		head: normalizedOptions.releaseBranch,
-		base: currentBranch,
-		githubToken: normalizedOptions.githubToken
+	if (originalBranch.value !== defaultBranch) await checkoutBranch(originalBranch.value, options.workspaceRoot);
+	let isOutOfSync = false;
+	for (const [pkgName, expectedVersion] of expectedVersionMap.entries()) {
+		const prVersion = prVersionMap.get(pkgName);
+		if (!prVersion) {
+			logger.warn(`Package "${pkgName}" found in default branch but not in release branch. Skipping.`);
+			continue;
+		}
+		if (gt(expectedVersion, prVersion)) {
+			logger.error(`Package "${pkgName}" is out of sync. Expected version >= ${expectedVersion}, but PR has ${prVersion}.`);
+			isOutOfSync = true;
+		} else logger.success(`Package "${pkgName}" is up to date (PR version: ${prVersion}, Expected: ${expectedVersion})`);
+	}
+	const statusContext = "ucdjs/release-verify";
+	if (isOutOfSync) {
+		await options.githubClient.setCommitStatus({
+			sha: releasePr.head.sha,
+			state: "failure",
+			context: statusContext,
+			description: "Release PR is out of sync with the default branch. Please re-run the release process."
+		});
+		logger.error("Verification failed. Commit status set to 'failure'.");
+	} else {
+		await options.githubClient.setCommitStatus({
+			sha: releasePr.head.sha,
+			state: "success",
+			context: statusContext,
+			description: "Release PR is up to date.",
+			targetUrl: `https://github.com/${options.owner}/${options.repo}/pull/${releasePr.number}`
+		});
+		logger.success("Verification successful. Commit status set to 'success'.");
+	}
+}
+
+//#endregion
+//#region src/index.ts
+function withErrorBoundary(fn) {
+	return fn().catch((e) => {
+		if (e instanceof ReleaseError) {
+			printReleaseError(e);
+			process.exit(1);
+		}
+		throw e;
+	});
+}
+async function createReleaseScripts(options) {
+	const normalizedOptions = normalizeReleaseScriptsOptions(options);
+	logger.verbose("Release scripts config", {
+		repo: `${normalizedOptions.owner}/${normalizedOptions.repo}`,
+		workspaceRoot: normalizedOptions.workspaceRoot,
+		dryRun: normalizedOptions.dryRun,
+		safeguards: normalizedOptions.safeguards,
+		branch: normalizedOptions.branch,
+		globalCommitMode: normalizedOptions.globalCommitMode,
+		prompts: normalizedOptions.prompts,
+		packages: normalizedOptions.packages,
+		npm: {
+			access: normalizedOptions.npm.access,
+			provenance: normalizedOptions.npm.provenance,
+			otp: normalizedOptions.npm.otp ? "set" : "unset"
+		},
+		changelog: normalizedOptions.changelog
 	});
-	logger.log(prExists ? "Updated pull request:" : "Created pull request:", pullRequest?.html_url);
-	await checkoutBranch(currentBranch, workspaceRoot);
 	return {
-		updates: allUpdates,
-		prUrl: pullRequest?.html_url,
-		created: !prExists
+		async verify() {
+			return withErrorBoundary(() => verifyWorkflow(normalizedOptions));
+		},
+		async prepare() {
+			return withErrorBoundary(() => prepareWorkflow(normalizedOptions));
+		},
+		async publish() {
+			return withErrorBoundary(() => publishWorkflow(normalizedOptions));
+		},
+		packages: {
+			async list() {
+				return withErrorBoundary(async () => {
+					const result = await discoverWorkspacePackages(normalizedOptions.workspaceRoot, normalizedOptions);
+					if (!result.ok) throw new Error(result.error.message);
+					return result.value;
+				});
+			},
+			async get(packageName) {
+				return withErrorBoundary(async () => {
+					const result = await discoverWorkspacePackages(normalizedOptions.workspaceRoot, normalizedOptions);
+					if (!result.ok) throw new Error(result.error.message);
+					return result.value.find((p) => p.name === packageName);
+				});
+			}
+		}
 	};
 }
 
 //#endregion
-export { publish, release };
+export { createReleaseScripts };