@reelout/core 0.1.1 → 0.2.0

package/dist/workflow-BoVmbvH6.js

@@ -0,0 +1,2342 @@
+import { colors } from "consola/utils";
+import semver from "semver";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import prettier from "prettier";
+import { minimatch } from "minimatch";
+import fs, { readFile } from "node:fs/promises";
+import { CommitParser } from "conventional-commits-parser";
+import { AsyncLocalStorage } from "node:async_hooks";
+import GitHost from "hosted-git-info";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import assert from "node:assert";
+import createPreset from "conventional-changelog-conventionalcommits";
+import { writeChangelogString } from "conventional-changelog-writer";
+import { toMarkdown } from "mdast-util-to-markdown";
+//#region src/workflow/versioning/bumpVersion.ts
+/**
+* Bump a semantic version according to release type and prerelease settings.
+*
+* Increments the version using the provided release type. When a prerelease ID
+* is provided, generates a prerelease version with that identifier. Throws an
+* error when the version is invalid or the initial version is missing.
+*
+* @param pkg Package object containing current version
+* @param releaseType Semantic version component to increment (`'major'`, `'minor'`, `'patch'`)
+* @param prereleaseId Optional prerelease identifier (e.g., `'alpha'`, `'beta'`)
+* @returns Next semantic version string, or `null` when `releaseType` is falsy
+* @throws If the version is invalid or initial version is missing
+*/
+function bumpVersion(pkg, releaseType, prereleaseId) {
+	if (!releaseType) return null;
+	if (!pkg.version) {
+		if (pkg.private) return null;
+		throw new Error("An initial version is required to compute the next version.");
+	}
+	const parsed = semver.parse(pkg.version);
+	if (!parsed) throw new Error(`The version "${colors.bold(pkg.version)}" is not a valid SemVer.`);
+	prereleaseId ||= void 0;
+	let type = releaseType;
+	if (prereleaseId) {
+		type = `pre${releaseType}`;
+		if (parsed.prerelease.length > 0) {
+			if (releaseType === "major" && parsed.minor === 0 && parsed.patch === 0 || releaseType === "minor" && parsed.patch === 0 || releaseType === "patch") type = "prerelease";
+		}
+	}
+	return semver.inc(parsed, type, { loose: void 0 }, prereleaseId, "0");
+}
+//#endregion
+//#region src/workflow/versioning/determineReleaseType.ts
+/**
+* Determine the release type for a single commit.
+*
+* Automatically returns `'major'` if the commit is marked as a breaking change.
+* Otherwise, routes the commit through the custom `classifier` and ensures the
+* resolved value is a valid semantic versioning release type.
+*
+* @param classifier Function mapping commits to release types
+* @param commit Parsed commit to evaluate
+* @returns `ReleaseType` string, or `null` when no matching rule applies
+*/
+function determineReleaseType(classifier, commit) {
+	if (commit.notes.length > 0) return "major";
+	const type = classifier(commit);
+	switch (type) {
+		case "major":
+		case "minor":
+		case "patch": return type;
+	}
+	return null;
+}
+//#endregion
+//#region src/workflow/versioning/pickPriorityReleaseType.ts
+/**
+* Determine the highest-priority release type between two candidates.
+*
+* Compares release types by precedence order: `major` > `minor` > `patch`.
+* Returns the higher-precedence type, or `null` if neither applies.
+*
+* @param curr Current accumulated release type
+* @param next Candidate release type to consider
+* @returns Highest-precedence `ReleaseType`, or `null` if neither applies
+*/
+function pickPriorityReleaseType(curr, next) {
+	for (const type of [
+		"major",
+		"minor",
+		"patch"
+	]) if (curr === type || next === type) return type;
+	return null;
+}
+//#endregion
+//#region src/workflow/versioning/deriveReleaseType.ts
+/**
+* Derive the combined release type from a commit history collection.
+*
+* Processes commits sequentially, accumulating the highest-precedence release
+* type found by evaluating each individual commit and comparing it against the
+* current maximum via `pickPriorityReleaseType`.
+*
+* @param classifier Function mapping commits to release types
+* @param history Array of parsed commits to evaluate
+* @returns `ReleaseType` string, or `null` when no matching rule applies
+*/
+function deriveReleaseType(classifier, history) {
+	let releaseType = null;
+	for (const commit of history) releaseType = pickPriorityReleaseType(releaseType, determineReleaseType(classifier, commit));
+	return releaseType;
+}
+//#endregion
+//#region src/workflow/versioning/isStableVersion.ts
+/**
+* Determine whether a version string represents a stable SemVer release.
+*
+* A version is considered stable when:
+* - It is a valid SemVer string.
+* - Its major version is greater than 0 (not 0.x.x).
+* - It contains no prerelease identifiers (no `-alpha`, `-beta`, `-rc`, etc.).
+*
+* Build metadata (the `+` suffix) does not affect stability.
+*
+* @param version Semantic version string to check
+* @returns `true` if `version` is a stable SemVer; otherwise `false`
+* @throws If `version` is not a valid SemVer string
+*/
+function isStableVersion(version) {
+	const parsed = semver.parse(version);
+	if (!parsed) throw new Error(`The version "${colors.bold(version)}" is not a valid SemVer.`);
+	return parsed.major > 0 && parsed.prerelease.length === 0;
+}
+//#endregion
+//#region src/config/const.ts
+var ALL_FILES = "**/*";
+var DEFAULT_CHANGELOG_FILE = "CHANGELOG.md";
+var GIT_TRAILER_RELEASE_AGENT = "Release-Agent";
+/**
+* 1. Primitive Building Blocks
+*
+* Base regular expression patterns for wildcards, alphanumeric strings with hyphens,
+* and standard non-negative integers.
+*/
+var WILDCARD = "\\*";
+var ALPHANUM_DASH = "[0-9a-zA-Z-]+";
+var NUMERIC_IDENTIFIER = "0|[1-9]\\d*";
+/**
+* 2. Package Name & Prefix Constructs
+*
+* Matches package name prefixes (unscoped or scoped) or a simple `v` prefix.
+*
+* Capture Groups:
+* - Group 1: Package name (e.g., `my-package` or `@scope/my-package`)
+*/
+var PKG_NAME_PART = `(?:${WILDCARD}|${ALPHANUM_DASH})`;
+var OPTIONAL_VERSION_PREFIX = `(?:v|${`(${PKG_NAME_PART}|@${PKG_NAME_PART}\\/${PKG_NAME_PART})`}@)`;
+/**
+* 3. Core SemVer Components
+*
+* Matches standard `MAJOR.MINOR.PATCH` versions or wildcard variants (e.g., `1.0.0`, `*.*.*`).
+*
+* Capture Groups:
+* - Group 3: Major version
+* - Group 4: Minor version
+* - Group 5: Patch version
+*/
+var CAPTURED_VERSION_DIGIT = `(${WILDCARD}|${NUMERIC_IDENTIFIER})`;
+var SEMVER_CORE = `${CAPTURED_VERSION_DIGIT}\\.${CAPTURED_VERSION_DIGIT}\\.${CAPTURED_VERSION_DIGIT}`;
+var PRERELEASE_IDENTIFIER = `(?:${WILDCARD}|${NUMERIC_IDENTIFIER}|(\\d*[a-zA-Z-][0-9a-zA-Z-]*))`;
+var FULL_SEMVER_PATTERN = `${OPTIONAL_VERSION_PREFIX}?${`(${SEMVER_CORE}${`(?:-(${PRERELEASE_IDENTIFIER}(?:\\.${PRERELEASE_IDENTIFIER})*))`}?${`(?:\\+(${ALPHANUM_DASH}(?:\\.${ALPHANUM_DASH})*))`}?)`}`;
+/**
+* Regular expression to match and capture Semantic Versioning (SemVer) strings,
+* including optional package prefixes (e.g., `@scope/pkg@`) and `v` prefixes.
+*
+* @example
+* ```ts
+* SEMVER_REGEX.test('1.0.0') // true
+* SEMVER_REGEX.test('v1.2.3-beta.1+sha.1234') // true
+* SEMVER_REGEX.test('@scope/package@1.0.0') // true
+* ```
+*
+* @see {@link https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string SemVer Specification}
+*/
+var SEMVER_REGEX = new RegExp(FULL_SEMVER_PATTERN);
+var RELEASE_LIFECYCLE_HOOK_LIST = [
+	"configure",
+	"discover",
+	"analyze",
+	"build",
+	"write",
+	"commit",
+	"publish",
+	"finalize"
+];
+//#endregion
+//#region src/config/isSemVerGitTag.ts
+/**
+* Determine whether a tag string is a valid SemVer-style Git tag.
+*
+* Anchors `SEMVER_REGEX.source` for full-string matching and applies the
+* repository's Git-tag acceptance rules.
+*
+* @param tag Tag string to validate
+* @returns `true` if `tag` is accepted as a SemVer-style Git tag; otherwise `false`
+*/
+function isSemVerGitTag(tag) {
+	const match = new RegExp(`^${SEMVER_REGEX.source}$`).exec(tag);
+	if (!match) return false;
+	const isScopedPackage = Boolean(match[1]);
+	const hasVersionPrefix = tag.startsWith("v");
+	return isScopedPackage || hasVersionPrefix;
+}
+//#endregion
+//#region src/util/buildTrailerPattern.ts
+/**
+* Build a regular expression to match trailer lines using custom markers.
+*
+* Combines the provided marker strings with a standard alphanumeric pattern
+* to construct a regular expression that matches trailer definitions.
+*
+* @param markers Optional array of custom trailer marker strings
+* @returns A regular expression matching trailer lines
+*/
+function buildTrailerPattern(markers = []) {
+	return new RegExp(`^(${markers.map(RegExp.escape).concat("[A-Za-z0-9_-]+").join("|")})[ \\t]*:[ \\t]*(.*)$`);
+}
+//#endregion
+//#region src/util/isDefined.ts
+/**
+* Type guard that asserts a value is neither `null` nor `undefined`.
+*
+* @param value Value to test
+* @returns `true` when `value` is not `null` or `undefined`
+*/
+function isDefined(value) {
+	return value != null;
+}
+//#endregion
+//#region src/util/compact.ts
+/**
+* Remove `null` and `undefined` values from an array.
+*
+* @param array The array to compact
+* @returns A new array that does not contain `null` or `undefined` values
+*/
+function compact(array) {
+	return array.filter(isDefined);
+}
+//#endregion
+//#region src/util/execCommand.ts
+(/* @__PURE__ */ new Date("2026-01-01T00:00:00Z")).valueOf();
+/**
+* Execute a command asynchronously and return its standard output.
+*
+* @param cwd Working directory for the command
+* @param command Binary to execute
+* @param args Command-line arguments
+* @returns Promise resolving to the stdout string
+*/
+function execCommand(cwd, command, args) {
+	const env = { ...process.env };
+	let childProcess;
+	const promise = new Promise((resolve, reject) => {
+		childProcess = spawn(command, args, {
+			cwd,
+			env
+		});
+		childProcess.stdout.setEncoding("utf-8");
+		childProcess.stderr.setEncoding("utf-8");
+		let stdout = "";
+		let stderr = "";
+		childProcess.stdout.on("data", (data) => {
+			stdout += data;
+		});
+		childProcess.stderr.on("data", (data) => {
+			stderr += data;
+		});
+		childProcess.on("error", (err) => {
+			reject(err);
+		});
+		childProcess.on("close", (code, signal) => {
+			if (code === 0) return resolve(stdout);
+			const errorMessage = `Command ${quoteCommandForMessage([command, ...args].join(" "))} failed (${code !== null ? `exit code ${code}` : signal ? `signal ${signal}` : "unknown status"})`;
+			const errorDiagnostics = (stderr || stdout).trim();
+			const err = new Error([errorMessage, errorDiagnostics].filter(Boolean).join(errorDiagnostics.includes("\n") ? "\n" : ": "), { cause: {
+				code,
+				signal,
+				diagnostics: errorDiagnostics
+			} });
+			Object.defineProperty(err, "code", { value: code });
+			reject(err);
+		});
+	});
+	promise.child = childProcess;
+	return promise;
+}
+function quoteCommandForMessage(command) {
+	if (!command.includes("'")) return `'${command}'`;
+	if (!command.includes("\"")) return `"${command}"`;
+	return JSON.stringify(command);
+}
+//#endregion
+//#region src/util/execGit.ts
+/**
+* Run a git command in a working directory and return its standard output.
+*
+* @param cwd Working directory for the git command
+* @param args Git CLI arguments
+* @returns Promise resolving to the stdout string
+*/
+function execGit(cwd, args) {
+	return execCommand(cwd, "git", args);
+}
+//#endregion
+//#region src/util/formatFile.ts
+/**
+* Format `content` for `filePath` using Prettier when possible.
+*
+* Resolves project/editorconfig settings and formats the provided content.
+* Returns the original content on error or when no parser is inferred.
+*
+* @param filePath Path used to infer parser and config
+* @param content Source content to format
+* @returns Formatted content or original content on failure
+*/
+async function formatFile(filePath, content) {
+	try {
+		const info = await prettier.getFileInfo(filePath, { resolveConfig: true });
+		const config = await prettier.resolveConfig(filePath, { editorconfig: true });
+		if (info.inferredParser == null) return content;
+		return await prettier.format(content, {
+			...config,
+			parser: info.inferredParser,
+			filepath: filePath
+		});
+	} catch {
+		return content;
+	}
+}
+//#endregion
+//#region src/util/interpolate.ts
+var BACKSLASH = "\\";
+var LEFT_BRACE = "{";
+var RIGHT_BRACE = "}";
+var DOT = ".";
+var ESCAPE_CHARS = [
+	BACKSLASH,
+	LEFT_BRACE,
+	RIGHT_BRACE
+];
+var BANNED_KEYS = [
+	"__proto__",
+	"constructor",
+	"prototype"
+];
+/**
+* Interpolate placeholders in `template` using values from `data`.
+*
+* - Placeholders use `{path.to.value}` (dot notation).
+* - Backslash escapes are supported for `{`, `}`, `\`, and `.` inside tokens.
+* - Tokens that reference banned keys (`__proto__`, `constructor`, `prototype`)
+*   are left unexpanded to avoid prototype pollution.
+* - Only own properties are followed when resolving paths; if any step is
+*   missing, the original token text is preserved.
+* - Resolved non-object, non-null values are stringified and inserted.
+* - Unclosed tokens and a trailing backslash are preserved verbatim.
+*
+* @param template Template string containing placeholders like `{user.name}`
+* @param data Object used to resolve placeholder paths
+* @returns The template with placeholders replaced by corresponding values
+*/
+function interpolate(template, data) {
+	let result = "";
+	let i = 0;
+	let char;
+	let nextChar;
+	while (char = template[i]) if (char === BACKSLASH) {
+		nextChar = template[i + 1];
+		if (nextChar !== void 0 && ESCAPE_CHARS.includes(nextChar)) {
+			result += nextChar;
+			i += 2;
+		} else {
+			result += char;
+			i += 1;
+		}
+	} else if (char === LEFT_BRACE) {
+		const keys = [];
+		let key = "";
+		let token = "";
+		let closed = false;
+		i += 1;
+		while (char = template[i]) {
+			if (char === RIGHT_BRACE) {
+				closed = true;
+				keys.push(key);
+				i += 1;
+				break;
+			}
+			if (char === BACKSLASH) {
+				nextChar = template[i + 1];
+				if (nextChar !== void 0 && [...ESCAPE_CHARS, DOT].includes(nextChar)) {
+					key += nextChar;
+					token += nextChar;
+					i += 2;
+				} else {
+					key += char;
+					token += char;
+					i += 1;
+				}
+			} else if (char === DOT) {
+				keys.push(key);
+				key = "";
+				token += char;
+				i += 1;
+			} else {
+				key += char;
+				token += char;
+				i += 1;
+			}
+		}
+		if (closed) {
+			let value = data;
+			for (const key of keys) {
+				const isSafeKey = !BANNED_KEYS.includes(key);
+				if (value !== null && typeof value === "object" && Object.hasOwn(value, key) && isSafeKey) value = value[key];
+				else {
+					value = void 0;
+					break;
+				}
+			}
+			if (value == null || typeof value === "object") result += LEFT_BRACE + token + RIGHT_BRACE;
+			else result += String(value);
+		} else result += LEFT_BRACE + token;
+	} else {
+		result += char;
+		i += 1;
+	}
+	return result;
+}
+//#endregion
+//#region src/util/isMatch.ts
+/**
+* Determine whether a target string matches glob patterns.
+*
+* Matches positive and negative glob patterns using dotfile support. Automatically
+* expands a single negative pattern by prepending a global wildcard match.
+*
+* @param target Target string to evaluate against glob patterns
+* @param patterns Single glob pattern or list of patterns to evaluate
+* @returns True if target matches positive patterns and satisfies negative patterns
+*/
+function isMatch(target, patterns) {
+	if (typeof patterns === "string") if (patterns.startsWith("!")) patterns = ["**/*", patterns];
+	else patterns = [patterns];
+	const positives = [];
+	const negatives = [];
+	for (const pattern of patterns) if (pattern.startsWith("!")) negatives.push(pattern);
+	else positives.push(pattern);
+	return positives.some((pattern) => minimatch(target, pattern, { dot: true })) && negatives.every((pattern) => minimatch(target, pattern, { dot: true }));
+}
+//#endregion
+//#region src/util/readJson.ts
+/**
+* Read and parse a JSON file.
+*
+* Throws a descriptive error when the file cannot be read or parsed, or when
+* the parsed value is not an object.
+*
+* @param filePath Path to the JSON file
+* @returns Parsed JSON object
+* @throws If the file cannot be read, parsed, or is not an object
+*/
+async function readJson(filePath) {
+	let content;
+	try {
+		content = await fs.readFile(filePath, "utf-8");
+	} catch (err) {
+		throw new Error(`JSON file at "${colors.bold(filePath)}" could not be read.`, { cause: err });
+	}
+	let json;
+	try {
+		json = JSON.parse(content);
+	} catch (err) {
+		throw new Error(`JSON file at "${colors.bold(filePath)}" could not be parsed.`, { cause: err });
+	}
+	if (typeof json !== "object" || json === null) throw new Error(`JSON file at "${colors.bold(filePath)}" does not contain a valid object.`);
+	return json;
+}
+//#endregion
+//#region src/util/writeJson.ts
+/**
+* Write a JSON `payload` to `filePath`, formatting the content first.
+*
+* Ensures the directory exists and writes the formatted JSON.
+*
+* @param filePath Path to write the JSON file
+* @param payload JSON-serializable object to write
+* @returns Promise that resolves when the file is written
+*/
+async function writeJson(filePath, payload) {
+	let content = JSON.stringify(payload, null, 2);
+	content = await formatFile(filePath, content);
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, content);
+}
+//#endregion
+//#region src/config/sanitizePrereleaseLabel.ts
+/**
+* Sanitize a string into a safe, semver-compliant prerelease label.
+*
+* Replaces sequential non-alphanumeric characters or consecutive hyphens
+* with a single hyphen, and strips leading or trailing hyphens.
+*
+* @param label Raw string to sanitize
+* @returns Safe string for a prerelease label
+*/
+function sanitizePrereleaseLabel(label) {
+	return label.replace(/[^a-zA-Z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
+//#endregion
+//#region src/config/resolveReleaseTarget.ts
+/**
+* Resolve prerelease label and release channel for a ref.
+*
+* Resolution priority for each key:
+* 1. Explicit `options` (string values are used verbatim; `false` disables the key).
+* 2. First matching `rule` (rules are checked in order).
+* 3. Fallback: derive and sanitize a label from `ref.name`.
+*
+* Resolved string values are interpolated with `data` before being returned.
+*
+* @param ref Reference context containing `type` and `name`
+* @param rules Ordered list of release rules to match against
+* @param options User overrides for `prereleaseLabel` and `releaseChannel`
+* @param data Values used to interpolate resolved template strings
+* @returns Partial release rule with resolved `prereleaseLabel` and/or `releaseChannel`
+*/
+function resolveReleaseTarget(ref, rules, options, data) {
+	const matchedRule = rules.find((rule) => rule.type === ref.type && isMatch(ref.name, rule.pattern));
+	const resolve = (key) => {
+		const value1 = options[key];
+		if (value1 === false) return;
+		if (value1 && typeof value1 === "string") return value1;
+		const value2 = matchedRule?.[key] || value1;
+		if (!value2) return;
+		if (typeof value2 === "string") return value2;
+		return sanitizePrereleaseLabel(ref.name);
+	};
+	const prereleaseLabel = resolve("prereleaseLabel");
+	const releaseChannel = resolve("releaseChannel");
+	return {
+		prereleaseLabel: prereleaseLabel && interpolate(prereleaseLabel, data),
+		releaseChannel: releaseChannel && interpolate(releaseChannel, data)
+	};
+}
+//#endregion
+//#region src/workflow/analysis/isCommitForPackage.ts
+/**
+* Test whether a commit modifies files in a package.
+*
+* @param pkg Package with an explicit file pattern or base directory
+* @param commit Parsed commit containing changed file paths
+* @returns `true` if any changed file matches the package pattern
+*/
+function isCommitForPackage(pkg, commit) {
+	return commit.files.some((file) => {
+		const { dir } = pkg;
+		return isMatch(file, pkg.files || path.join(dir, "**/*"));
+	});
+}
+//#endregion
+//#region src/workflow/analysis/analyzePackageChanges.ts
+/**
+* Analyze commit history and compute release types for each package plan.
+*
+* Iterates through commits, associates them with affected packages, and
+* calculates each package's release type using the provided classifier.
+*
+* @param classifier Function mapping commits to release types
+* @param plans Array of release plans to update
+* @param history Commit history as iterable or async iterable
+* @returns Updated array of plans with computed `releaseType`
+*/
+async function analyzePackageChanges(classifier, plans, history) {
+	for await (const commit of history) plans = plans.map((plan) => {
+		if (!isCommitForPackage(plan.package, commit)) return plan;
+		return {
+			...plan,
+			history: plan.history.concat(commit)
+		};
+	});
+	return plans.map((plan) => {
+		let { release } = plan;
+		const releaseType = pickPriorityReleaseType(release?.type, deriveReleaseType(classifier, plan.history));
+		if (releaseType) release = {
+			...release,
+			type: releaseType
+		};
+		return {
+			...plan,
+			release
+		};
+	});
+}
+//#endregion
+//#region src/workflow/analysis/promotePrereleaseVersions.ts
+/**
+* Promote prerelease versions when they have no explicit release type.
+*
+* Analyzes prerelease and zero-major versions to determine an appropriate
+* release type for graduation:
+* - Prerelease versions are promoted based on their highest incremented component
+*   (patch, minor, or major)
+* - Zero-major versions (0.y.z) are promoted to major
+* - Stable versions (1.0.0+) remain unchanged
+* - Plans with explicit releases are preserved as-is
+*
+* @param plans Release plans to analyze
+* @returns Plans with inferred release types for prerelease versions
+*/
+async function promotePrereleaseVersions(plans) {
+	return plans.map((plan) => {
+		if (plan.release) return plan;
+		if (!plan.package.tag) return plan;
+		const parsed = semver.parse(plan.package.version);
+		if (!parsed) return plan;
+		let type;
+		if (parsed.prerelease.length) if (parsed.patch !== 0) type = "patch";
+		else if (parsed.minor !== 0) type = "minor";
+		else if (parsed.major !== 0) type = "major";
+		else type = "major";
+		else if (parsed.major === 0) type = "major";
+		if (type) return {
+			...plan,
+			release: { type }
+		};
+		return plan;
+	});
+}
+//#endregion
+//#region src/git/branch/getCurrentGitBranch.ts
+/**
+* Get the current Git branch name.
+*
+* Uses `execGit` to run `git symbolic-ref -q --short HEAD` in the provided
+* working directory and trims the result. Returns an empty string when the
+* repository is in a detached HEAD state.
+*
+* @param cwd The working directory to run the Git command in
+* @returns The current branch name as a string
+*/
+async function getCurrentGitBranch(cwd) {
+	return (await execGit(cwd, [
+		"symbolic-ref",
+		"-q",
+		"--short",
+		"HEAD"
+	])).trim();
+}
+//#endregion
+//#region src/git/commit/createGitCommit.ts
+/**
+* Stage all changes and create a git commit with the specified message.
+*
+* Validates the commit message and working directory status before staging
+* all changes and executing the commit command.
+*
+* @param cwd The target directory path for executing git commands
+* @param message The message to associate with the commit
+* @returns A promise that resolves when the operation completes
+*/
+async function createGitCommit(cwd, message) {
+	if (!message) return;
+	await execGit(cwd, ["add", "."]);
+	if (!(await execGit(cwd, ["status", "--porcelain"])).trim()) return;
+	await execGit(cwd, [
+		"commit",
+		"--message",
+		message
+	]);
+}
+//#endregion
+//#region src/git/commit/extractMentions.ts
+var ALPHANUMERIC = "[a-zA-Z0-9]";
+var SEPARATOR = "[-_]";
+var USERNAME = `${ALPHANUMERIC}+(?:${SEPARATOR}+${ALPHANUMERIC}+)*`;
+var EMAIL_LOCAL = "[a-zA-Z0-9._%+-]";
+var DOMAIN_SUFFIX = "[a-zA-Z0-9.-]*\\.[a-zA-Z]{2,}";
+var SCOPED_PACKAGE_SPEC_SUFFIX = `/${USERNAME}@[0-9]+\\.[0-9]+\\.[0-9]+`;
+/**
+* Extract unique mention handles from the input text string.
+*
+* Evaluates `text` against boundary rules to isolate valid handles while
+* excluding email addresses, domain names, and scoped package specs, then
+* de-duplicates the resulting handles.
+*
+* @param text The input string to parse for mentions
+* @returns An array of unique mention handles
+*/
+function extractMentions(text) {
+	if (!text) return [];
+	const regex = new RegExp(`(?<!${EMAIL_LOCAL})@(${USERNAME})\\b(?!${SEPARATOR}|${DOMAIN_SUFFIX}|${SCOPED_PACKAGE_SPEC_SUFFIX})`, "g");
+	const matches = text.matchAll(regex);
+	const mentions = new Set(matches.map((match) => match[1]));
+	return Array.from(mentions);
+}
+//#endregion
+//#region src/git/revision/resolveGitRevision.ts
+/**
+* Resolve a Git revision or commit-ish expression to its full commit hash.
+*
+* Runs `git rev-parse --verify <revision>^{commit}` under the hood. Peels annotated
+* tags, branches, short SHAs, and relative expressions down to a verified commit object.
+*
+* @param cwd The repository working directory
+* @param revision The Git revision or expression to resolve
+* @returns A promise that resolves to the full, trimmed commit SHA-1 string
+*/
+async function resolveGitRevision(cwd, revision) {
+	return (await execGit(cwd, [
+		"rev-parse",
+		"--verify",
+		`${revision}^{commit}`
+	])).trim();
+}
+//#endregion
+//#region src/git/commit/getCurrentGitCommit.ts
+/**
+* Resolve the current commit hash for HEAD in the repository.
+*
+* @param cwd The repository working directory
+* @returns A promise that resolves to the full, trimmed commit SHA-1 string
+*/
+function getCurrentGitCommit(cwd) {
+	return resolveGitRevision(cwd, "HEAD");
+}
+//#endregion
+//#region src/cache/TTLCache.ts
+/**
+* A simple time-to-live cache that automatically evicts entries after a TTL.
+*
+* - Entries are removed automatically when their TTL expires.
+* - Reading an entry resets its TTL to the original value.
+* - Setting an existing key clears its previous timer and resets the TTL.
+*
+* @template K Type of cache keys
+* @template V Type of cache values
+*/
+var TTLCache = class {
+	constructor() {
+		this.cache = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Store a value under `key` for `ttl` milliseconds.
+	*
+	* If the key already exists its previous timer is cleared and the TTL is reset.
+	*
+	* @param key Cache key
+	* @param value Value to store
+	* @param ttl Time to live in milliseconds (default: 60_000)
+	*/
+	set(key, value, ttl = 6e4) {
+		const ref = this.cache.get(key);
+		if (ref) clearTimeout(ref.timer);
+		const timer = setTimeout(() => {
+			this.cache.delete(key);
+		}, ttl).unref();
+		this.cache.set(key, {
+			value,
+			timer,
+			ttl
+		});
+	}
+	/**
+	* Retrieve the value for `key`, or `undefined` if not present.
+	*
+	* Reading an entry resets its TTL to the original `ttl` provided when it was set.
+	*
+	* @param key Cache key
+	* @returns The stored value or `undefined` if not present
+	*/
+	get(key) {
+		const ref = this.cache.get(key);
+		if (!ref) return void 0;
+		this.set(key, ref.value, ref.ttl);
+		return ref.value;
+	}
+	/**
+	* Check whether `key` exists in the cache.
+	*
+	* @param key Cache key
+	* @returns `true` if present; otherwise `false`
+	*/
+	has(key) {
+		return this.cache.has(key);
+	}
+	/**
+	* Remove `key` from the cache and clear its eviction timer.
+	*
+	* @param key Cache key
+	* @returns `true` if the key was present and removed; otherwise `false`
+	*/
+	delete(key) {
+		const ref = this.cache.get(key);
+		if (!ref) return false;
+		clearTimeout(ref.timer);
+		return this.cache.delete(key);
+	}
+	/**
+	* Clear all entries and their timers.
+	*/
+	clear() {
+		for (const { timer } of this.cache.values()) clearTimeout(timer);
+		this.cache.clear();
+	}
+};
+//#endregion
+//#region src/git/commit/parseCommit.ts
+var BREAKING_HEADER_REGEX = /^([\w-]+)(?:\(([^)]+)\))?!: (.*)$/;
+var BREAKING_MARKERS = ["BREAKING CHANGE", "BREAKING-CHANGE"];
+/**
+* Parse a git log entry into a structured commit object.
+*
+* Combines the commit subject and body, extracts conventional commit metadata
+* using custom trailer markers and breaking header patterns, and normalizes
+* dates to ISO format strings.
+*
+* @param entry The raw git log entry to parse
+* @param markers Optional array of custom trailer marker strings
+* @returns A structured commit object containing parsed details, notes, and mentions
+*/
+async function parseCommit(entry, markers = []) {
+	const message = [entry.subject, entry.body].filter(Boolean).join("\n\n");
+	const commit = new CommitParser({
+		breakingHeaderPattern: BREAKING_HEADER_REGEX,
+		noteKeywords: [],
+		notesPattern: () => buildTrailerPattern(BREAKING_MARKERS.concat(markers))
+	}).parse(message);
+	const notes = [];
+	const trailers = [];
+	for (const note of commit.notes) {
+		if (BREAKING_MARKERS.includes(note.title.toUpperCase())) notes.push(note);
+		trailers.push({
+			key: note.title,
+			value: note.text
+		});
+	}
+	if (notes.length === 0 && BREAKING_HEADER_REGEX.test(commit.header)) {
+		const note = {
+			title: "BREAKING CHANGE",
+			text: commit.subject
+		};
+		notes.push(note);
+		trailers.push({
+			key: note.title,
+			value: note.text
+		});
+	}
+	const mentions = extractMentions(message);
+	return {
+		...commit,
+		hash: entry.hash,
+		parent: entry.parent,
+		authorDate: new Date(entry.authorDate).toISOString(),
+		committerDate: new Date(entry.committerDate).toISOString(),
+		type: commit.type?.toLowerCase() || null,
+		scope: commit.scope || null,
+		subject: commit.subject || null,
+		header: commit.header,
+		body: commit.body,
+		footer: commit.footer,
+		notes,
+		mentions,
+		trailers,
+		files: entry.files
+	};
+}
+//#endregion
+//#region src/git/commit/parseGitPrettyFormat.ts
+/**
+* Field separator used in the git pretty format to produce a single-line
+*, machine-parseable record.
+*/
+var GIT_PRETTY_FIELD_SEPARATOR = "";
+/**
+* Pretty format string passed to `git log --pretty=format:`. Produces seven
+* fields separated by `GIT_PRETTY_FIELD_SEPARATOR`:
+* hash, parents, author date, committer date, subject, body, files.
+*/
+var GIT_PRETTY_FORMAT = [
+	"%H",
+	"%P",
+	"%aI",
+	"%cI",
+	"%s",
+	"%b",
+	""
+].join("");
+/**
+* Parse a single line produced by `git log --pretty=format:${GIT_PRETTY_FORMAT}`.
+*
+* The input is expected to contain seven fields separated by
+* `GIT_PRETTY_FIELD_SEPARATOR`:
+* 1. `hash` (commit hash)
+* 2. `parent` (space-separated parent hashes)
+* 3. `authorDate` (ISO 8601)
+* 4. `committerDate` (ISO 8601)
+* 5. `subject`
+* 6. `body`
+* 7. `files` (newline-separated list)
+*
+* The function trims fields, converts parent hashes into an array, normalizes
+* dates to ISO strings, and splits `files` into an array. Missing optional
+* fields are normalized to sensible defaults.
+*
+* @param raw Raw pretty-format string produced by git
+* @returns Parsed `GitLogEntry` with `hash`, `parent`, `authorDate`, `committerDate`, `subject`, `body`, and `files`
+* @throws If required fields (hash, authorDate, committerDate, subject) are missing or malformed
+*/
+function parseGitPrettyFormat(raw) {
+	let [hash, parentHashes, authorDate, committerDate, subject, body, files] = raw.split("");
+	hash = hash?.trim();
+	parentHashes = parentHashes?.trim();
+	authorDate = authorDate?.trim();
+	committerDate = committerDate?.trim();
+	subject = subject?.trim();
+	body = body?.trim();
+	files = files?.trim();
+	if (!hash || !authorDate || !committerDate || typeof subject !== "string") throw new Error(`The input "${colors.bold(raw)}" is not in the expected pretty format.`);
+	return {
+		hash,
+		parent: parentHashes ? parentHashes.split(/\s+/) : [],
+		authorDate: new Date(authorDate).toISOString(),
+		committerDate: new Date(committerDate).toISOString(),
+		subject,
+		body: body ?? "",
+		files: files ? files.split("\n") : []
+	};
+}
+//#endregion
+//#region src/git/commit/getParsedCommit.ts
+var cache = new TTLCache();
+/**
+* Retrieve and parse a commit by its reference.
+*
+* Fetches the raw git log entry for the specified reference, checks the cache
+* for an existing entry, and parses the log data if a cache miss occurs.
+*
+* @param cwd The current working directory path
+* @param ref The git reference to fetch
+* @param markers Optional array of custom trailer marker strings
+* @returns A structured commit object or null if the operation fails
+*/
+async function getParsedCommit(cwd, ref, markers = []) {
+	try {
+		const entry = parseGitPrettyFormat(await execGit(cwd, [
+			"log",
+			"-1",
+			ref,
+			"--name-only",
+			`--pretty=format:${GIT_PRETTY_FORMAT}`
+		]));
+		const key = `${entry.hash}:${entry.parent}:${markers}`;
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const parsed = await parseCommit(entry, markers);
+		cache.set(key, parsed);
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/git/history/countGitHistory.ts
+/**
+* Count mainline commits reachable from a given reference.
+*
+* Uses `git rev-list --count --first-parent` to calculate the length of the
+* primary history trunk, excluding commits introduced by side-branch merges.
+*
+* @param cwd Repository working directory
+* @param ref Commit reference to count from (defaults to `HEAD`)
+* @returns Number of commits along the primary branch line up to `ref`
+*/
+async function countGitHistory(cwd, ref = "HEAD") {
+	const stdout = await execGit(cwd, [
+		"rev-list",
+		"--count",
+		"--first-parent",
+		ref
+	]);
+	return Number.parseInt(stdout.trim(), 10);
+}
+//#endregion
+//#region src/git/repository/isGitShallowRepository.ts
+/**
+* Determine whether the repository at `cwd` is a shallow clone.
+*
+* Runs `git rev-parse --is-shallow-repository` to detect shallow clones.
+* Useful before operations that require full history.
+*
+* @param cwd Repository working directory
+* @returns `true` if shallow, `false` if full clone, or `null` on error
+*/
+async function isGitShallowRepository(cwd) {
+	return (await execGit(cwd, ["rev-parse", "--is-shallow-repository"])).trim() === "true";
+}
+//#endregion
+//#region src/git/repository/withShallowLock.ts
+var lockQueue = /* @__PURE__ */ new Map();
+var context = new AsyncLocalStorage();
+/**
+* Serialize access to a shallow Git repository while running a callback.
+*
+* If `cwd` is a shallow clone, callers from different async contexts are
+* executed one at a time; nested calls within the same async context run
+* immediately without waiting. If the repository becomes non-shallow before
+* a queued turn runs, downstream waiters are released early.
+*
+* @param cwd Repository working directory path string
+* @param callback Function to execute while the lock is held
+* @returns Promise resolving to the result of `callback`
+*/
+async function withShallowLock(cwd, callback) {
+	if (!await isGitShallowRepository(cwd)) return callback();
+	const active = context.getStore();
+	if (active?.has(cwd)) return callback();
+	const { promise, resolve } = Promise.withResolvers();
+	const previous = lockQueue.get(cwd) ?? Promise.resolve();
+	const queued = previous.then(() => promise);
+	lockQueue.set(cwd, queued);
+	await previous;
+	if (!await isGitShallowRepository(cwd)) resolve();
+	try {
+		return await context.run(new Set(active).add(cwd), callback);
+	} finally {
+		resolve();
+		if (lockQueue.get(cwd) === queued) lockQueue.delete(cwd);
+	}
+}
+//#endregion
+//#region src/git/revision/isGitAncestor.ts
+/**
+* Determine whether `ancestor` is an ancestor of `descendant`.
+*
+* Runs `git merge-base --is-ancestor <ancestor> <descendant>` in the repository at `cwd`.
+* Resolves to `true` if `ancestor` is an ancestor, `false` if not.
+* Rethrows errors for invalid refs or other failures.
+*
+* @param cwd Repository working directory
+* @param ancestor Candidate ancestor ref
+* @param descendant Candidate descendant ref
+* @returns Resolves to `true` if `ancestor` is an ancestor of `descendant`, `false` otherwise
+* @throws If a ref is invalid or the Git command fails
+*/
+function isGitAncestor(cwd, ancestor, descendant) {
+	return execGit(cwd, [
+		"merge-base",
+		"--is-ancestor",
+		ancestor,
+		descendant
+	]).then(() => true).catch((err) => {
+		if (err?.code === 1) return false;
+		throw err;
+	});
+}
+//#endregion
+//#region src/git/history/expandGitHistory.ts
+/**
+* Deepen a shallow clone so additional commits become available.
+*
+* Attempts a single `--shallow-since` fetch to reach `until` (if provided),
+* otherwise deepens by `pageSize`, accounting for existing depth when `from`
+* is supplied. Operation is serialized to avoid concurrent deepens.
+*
+* @param cwd Repository working directory
+* @param options Options: { pageSize?, from?, until? }
+* @returns true if history was deepened or already sufficient, otherwise false
+*/
+async function expandGitHistory(cwd, options = {}) {
+	if (!await isGitShallowRepository(cwd)) return false;
+	return withShallowLock(cwd, async () => {
+		const { until } = options;
+		let { from } = options;
+		let { pageSize = 50 } = options;
+		if (until) {
+			if (await isGitAncestor(cwd, until, "HEAD")) return true;
+			const commitDate = (await execGit(cwd, [
+				"show",
+				"-s",
+				"--format=%cI",
+				`${until}^{commit}`
+			])).trim();
+			try {
+				await execGit(cwd, [
+					"fetch",
+					`--shallow-since=${commitDate}`,
+					"--update-shallow",
+					"--filter=blob:none"
+				]);
+				return true;
+			} catch {}
+		}
+		if (from) {
+			from = await resolveGitRevision(cwd, from);
+			const depth = await countGitHistory(cwd, from);
+			if (depth > pageSize) return true;
+			pageSize -= depth - 1;
+		}
+		try {
+			await execGit(cwd, [
+				"fetch",
+				`--deepen=${pageSize}`,
+				"--update-shallow",
+				"--filter=blob:none",
+				...from && !await isGitAncestor(cwd, from, "HEAD") ? [
+					"origin",
+					from,
+					"HEAD"
+				] : []
+			]);
+			return true;
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
+//#region src/git/revision/detectGitRelationship.ts
+var GIT_REL_FLAGS = {
+	NONE: 0,
+	IS_ANCESTOR: 1,
+	IS_DESCENDANT: 2,
+	IS_EQUAL: 3
+};
+/**
+* Determine the relationship between two git refs.
+*
+* Runs `git merge-base --is-ancestor` in both directions and returns a
+* numeric bitmask using `GIT_REL_FLAGS`. A successful check (exit code 0)
+* indicates an ancestor relationship; non-zero exit is treated as "not ancestor".
+*
+* @param cwd Repository working directory
+* @param refA First ref (candidate ancestor)
+* @param refB Second ref (candidate descendant)
+* @returns Bitmask of type `GitRelFlags`
+*/
+async function detectGitRelationship(cwd, refA, refB) {
+	let flags = GIT_REL_FLAGS.NONE;
+	const [aIsAncestor, bIsAncestor] = await Promise.all([isGitAncestor(cwd, refA, refB), isGitAncestor(cwd, refB, refA)]);
+	if (aIsAncestor) flags |= GIT_REL_FLAGS.IS_ANCESTOR;
+	if (bIsAncestor) flags |= GIT_REL_FLAGS.IS_DESCENDANT;
+	return flags;
+}
+//#endregion
+//#region src/git/history/mergeGitHistory.ts
+/**
+* Merge two newest-first commit lists into a single deduplicated newest-first list.
+*
+* Compares commits by hash, uses git relationship (ancestor/descendant) when needed,
+* and falls back to committerDate for unrelated commits.
+*
+* @param cwd Repository working directory used for relationship checks
+* @param a Commits from the first source (newest-first)
+* @param b Commits from the second source (newest-first)
+* @returns Merged commits in newest-first order with duplicates removed
+*/
+async function mergeGitHistory(cwd, a, b) {
+	const merged = [];
+	const a2 = [...a];
+	const b2 = [...b];
+	let i = a2.shift();
+	let j = b2.shift();
+	while (i && j) switch (i.hash === j.hash ? GIT_REL_FLAGS.IS_EQUAL : await detectGitRelationship(cwd, i.hash, j.hash)) {
+		case GIT_REL_FLAGS.IS_EQUAL:
+			merged.push(i);
+			i = a2.shift();
+			j = b2.shift();
+			break;
+		case GIT_REL_FLAGS.IS_ANCESTOR:
+			merged.push(j);
+			j = b2.shift();
+			break;
+		case GIT_REL_FLAGS.IS_DESCENDANT:
+			merged.push(i);
+			i = a2.shift();
+			break;
+		case GIT_REL_FLAGS.NONE: if (i.committerDate < j.committerDate) {
+			merged.push(j);
+			j = b2.shift();
+		} else {
+			merged.push(i);
+			i = a2.shift();
+		}
+	}
+	if (i) merged.push(i);
+	if (j) merged.push(j);
+	return merged.concat(a2).concat(b2);
+}
+//#endregion
+//#region src/git/history/restoreFullGitHistory.ts
+/**
+* Convert a shallow clone into a full clone by fetching additional history.
+*
+* Runs `git fetch --unshallow`. Returns `true` when the operation succeeds
+* and `false` on error.
+*
+* @param cwd Repository working directory
+* @returns `true` when the operation succeeded, otherwise `false`
+*/
+function restoreFullGitHistory(cwd) {
+	return execGit(cwd, ["fetch", "--unshallow"]).then(() => true).catch(() => false);
+}
+//#endregion
+//#region src/git/history/showGitHistory.ts
+/**
+* Yield commit SHAs from repository history in paginated order.
+*
+* Ensures commits are available via `expandGitHistory`, resolves `until` to a
+* commit id, and pages from `from` toward `until`, yielding each commit SHA.
+* If a git command fails the generator ends silently.
+*
+* @param cwd Repository working directory
+* @param options Supports `from`, `until`, `pageSize`, and `filePath`
+* @yields Commit SHA strings in paginated order
+*/
+async function* showGitHistory(cwd, options = {}) {
+	try {
+		const { filePath, pageSize = 50 } = options;
+		let from = options.from || "HEAD";
+		let until = options.until || void 0;
+		if (until) until = await resolveGitRevision(cwd, until);
+		while (true) {
+			await expandGitHistory(cwd, {
+				from,
+				until,
+				pageSize
+			});
+			const args = [
+				"rev-list",
+				`--max-count=${pageSize}`,
+				from
+			];
+			if (until) args.push(`^${until}`);
+			if (filePath) args.push("--", ...(Array.isArray(filePath) ? filePath : [filePath]).filter(Boolean));
+			const list = (await execGit(cwd, args)).trim().split("\n").filter(Boolean);
+			for (const item of list.slice(0, -1)) yield item;
+			const tail = list.at(-1);
+			if (!tail) return;
+			if (tail === from) {
+				yield tail;
+				from = `${tail}^`;
+				from = await resolveGitRevision(cwd, from);
+			} else from = tail;
+		}
+	} catch {}
+}
+//#endregion
+//#region src/git/history/showParsedGitHistory.ts
+/**
+* Yield parsed commits sequentially from repository history.
+*
+* Fetches commits using `showGitHistory` and parses each SHA with
+* `getParsedCommit`. Yields successfully parsed `Commit` objects on demand and
+* omits unparsable commits.
+*
+* @param cwd Repository working directory
+* @param options Filter and pagination options passed to `showGitHistory`
+* @yields Parsed `Commit` objects in historical order
+*/
+async function* showParsedGitHistory(cwd, options) {
+	for await (const commit of showGitHistory(cwd, options)) {
+		const parsed = await getParsedCommit(cwd, commit);
+		if (parsed) yield parsed;
+	}
+}
+//#endregion
+//#region src/git/repository/getGitConfigValue.ts
+/**
+* Get a local git configuration value for `key` in the repository at `cwd`.
+*
+* Returns the config value when present; otherwise `undefined`.
+*
+* @param cwd Repository working directory
+* @param key Git config key to read
+* @returns The config value or `undefined` if not set
+*/
+async function getGitConfigValue(cwd, key) {
+	try {
+		const value = (await execGit(cwd, [
+			"config",
+			"--local",
+			"--get",
+			key
+		])).trim();
+		return value ? value : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/git/repository/ensureGitUserConfig.ts
+/**
+* Ensure git `user.name` and `user.email` are configured for the repository at `cwd`.
+*
+* No-op when the values are already present.
+*
+* @param cwd Repository working directory
+* @param user Object containing `name` and `email` values to set when missing
+* @returns Promise that resolves when configuration is ensured
+*/
+async function ensureGitUserConfig(cwd, user) {
+	if (await getGitConfigValue(cwd, "user.name") && await getGitConfigValue(cwd, "user.email")) return;
+	await execGit(cwd, [
+		"config",
+		"user.name",
+		user.name
+	]);
+	await execGit(cwd, [
+		"config",
+		"user.email",
+		user.email
+	]);
+}
+//#endregion
+//#region src/git/repository/getGitRemote.ts
+/**
+* Get the URL for the named remote (defaults to `origin`).
+*
+* @param cwd Repository working directory
+* @param remoteName Remote name (defaults to `'origin'`)
+* @returns Remote URL string or `null` when unavailable
+*/
+function getGitRemote(cwd, remoteName = "origin") {
+	return execGit(cwd, [
+		"remote",
+		"get-url",
+		remoteName
+	]).then((stdout) => stdout.trim()).catch(() => null);
+}
+//#endregion
+//#region src/git/repository/pushGitChanges.ts
+/**
+* Push a branch and optional tags to the `origin` remote using an atomic push.
+*
+* @param cwd Repository working directory
+* @param branch Branch name to push
+* @param additionalTags Optional list of tag names to push alongside the branch
+* @returns Promise that resolves when the push completes
+*/
+async function pushGitChanges(cwd, branch, ...additionalTags) {
+	await execGit(cwd, [
+		"push",
+		"origin",
+		...compact([branch, ...additionalTags]),
+		"--atomic"
+	]);
+}
+//#endregion
+//#region src/git/repository/resolveGitRepository.ts
+/**
+* Resolve Git repository host, owner, and project metadata from the `origin` remote URL.
+*
+* @param cwd Repository working directory
+* @returns Promise that resolves to a `GitRepository` object, or `null` when unavailable
+*/
+async function resolveGitRepository(cwd) {
+	const origin = await getGitRemote(cwd);
+	if (!origin) return null;
+	const info = GitHost.fromUrl(origin);
+	if (info && typeof info.type === "string" && typeof info.user === "string" && typeof info.project === "string") return {
+		host: info.type,
+		owner: info.user,
+		repo: info.project,
+		url: info.browse()
+	};
+	return null;
+}
+//#endregion
+//#region src/git/revision/readGitFile.ts
+/**
+* Read a file's contents from a specific Git revision.
+*
+* Runs `git show <ref>:<filePath>` and returns the command output as a
+* string. If the file does not exist at the given revision or the Git
+* command fails for any reason, the function returns `null`.
+*
+* The returned string is the raw file contents as emitted by Git; callers
+* that need binary-safe handling should decode or process the bytes
+* accordingly. This function intentionally swallows Git errors and signals
+* absence via a `null` result rather than throwing.
+*
+* @param cwd Repository working directory
+* @param ref Commit-ish reference (commit SHA, tag, or branch) to read from
+* @param filePath Path to the file relative to the repository root
+* @returns File contents as a string, or `null` if the file is unavailable at the ref
+*/
+function readGitFile(cwd, ref, filePath) {
+	return execGit(cwd, ["show", `${ref}:${filePath}`]).catch(() => null);
+}
+//#endregion
+//#region src/git/tag/createGitTag.ts
+/**
+* Create a git tag in the repository at `cwd`.
+*
+* Creates an annotated tag when `message` is provided.
+*
+* @param cwd Repository working directory
+* @param tag Tag name to create
+* @param message Optional tag message (creates an annotated tag when present)
+* @returns Promise that resolves when the tag is created
+*/
+async function createGitTag(cwd, tag, message) {
+	await execGit(cwd, ["tag", ...message ? [
+		"-a",
+		tag,
+		"-m",
+		message,
+		"--cleanup=whitespace"
+	] : [tag]]);
+}
+//#endregion
+//#region src/git/tag/deleteGitTag.ts
+/**
+* Delete a local git tag in the repository at `cwd`.
+*
+* @param cwd Repository working directory
+* @param tag Tag name to delete
+* @returns `true` when deletion succeeded, otherwise `false`
+*/
+function deleteGitTag(cwd, tag) {
+	return execGit(cwd, [
+		"tag",
+		"-d",
+		tag
+	]).then(() => true).catch(() => false);
+}
+//#endregion
+//#region src/git/tag/isGitTagPresent.ts
+/**
+* Determine whether a specific git tag exists locally in the repository.
+*
+* @param cwd Working directory for the git command
+* @param tag Name of the tag to evaluate
+* @returns True if the tag reference exists locally, false otherwise
+*/
+function isGitTagPresent(cwd, tag) {
+	return resolveGitRevision(cwd, `refs/tags/${tag}`).then(() => true).catch(() => false);
+}
+//#endregion
+//#region src/git/tag/ensureGitTag.ts
+var MIN_HISTORY_DEPTH = 2;
+var ORIGIN_NOT_REPO = `fatal: 'origin' does not appear to be a git repository`;
+var REMOTE_REF_NOT_FOUND = `fatal: couldn't find remote ref`;
+/**
+* Ensure a tag exists locally, fetching it shallowly from `origin` if needed.
+*
+* Acquires a shallow-fetch lock, verifies local presence and history depth,
+* attempts a shallow fetch of `refs/tags/<tag>` when required, and removes a
+* local tag if the remote reports the tag is missing.
+*
+* @param cwd Working directory
+* @param tag Tag name (for example `v1.2.0`)
+* @returns `true` if the tag is present or was fetched; otherwise `false`
+*/
+function ensureGitTag(cwd, tag) {
+	return withShallowLock(cwd, async () => {
+		const tagRef = `refs/tags/${tag}`;
+		if (await isGitTagPresent(cwd, tag) && await countGitHistory(cwd, tagRef) >= MIN_HISTORY_DEPTH) return true;
+		try {
+			await execGit(cwd, [
+				"fetch",
+				"origin",
+				`${tagRef}:${tagRef}`,
+				`--depth=${MIN_HISTORY_DEPTH}`,
+				"--update-shallow",
+				"--force"
+			]);
+			return true;
+		} catch (err) {
+			const errorMessage = err?.message;
+			if (errorMessage?.includes(ORIGIN_NOT_REPO)) return await isGitTagPresent(cwd, tag);
+			if (errorMessage?.includes(REMOTE_REF_NOT_FOUND)) {
+				if (await isGitTagPresent(cwd, tag)) await deleteGitTag(cwd, tag);
+			}
+		}
+		return false;
+	});
+}
+//#endregion
+//#region src/git/tag/generateGitTagName.ts
+function generateGitTagName(entry, name, version) {
+	if (!version) return null;
+	if (entry) return `v${version}`;
+	if (!name) throw new Error("Package name is required to build a tag name.");
+	return `${name}@${version}`;
+}
+//#endregion
+//#region src/git/tag/getCurrentGitTag.ts
+/**
+* Get the tag name that exactly matches the current `HEAD`, if any.
+*
+* @param cwd Repository working directory
+* @returns Tag name or `null` when no exact tag matches HEAD
+*/
+async function getCurrentGitTag(cwd) {
+	try {
+		const tag = (await execGit(cwd, [
+			"describe",
+			"--tags",
+			"--exact-match"
+		])).trim();
+		/* istanbul ignore next */
+		return tag ? tag : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/git/tag/getGitTagMessage.ts
+/**
+* Get the message of an annotated git tag in the repository at `cwd`.
+*
+* @param cwd Repository working directory
+* @param tag Tag name to query
+* @returns The tag message string when found, otherwise `undefined`
+*/
+async function getGitTagMessage(cwd, tag) {
+	try {
+		const [objectType, message] = (await execGit(cwd, [
+			"tag",
+			"-l",
+			"--format=%(objecttype)%00%(contents)",
+			tag
+		])).split("\0");
+		if (objectType?.trim() !== "tag") return;
+		return message?.trim() || void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/git/tag/getLatestGitTag.ts
+/**
+* Get the most recent tag reachable from `HEAD`.
+*
+* @param cwd Repository working directory
+* @returns Latest tag string or `null` when none is found
+*/
+async function getLatestGitTag(cwd) {
+	try {
+		const tag = (await execGit(cwd, [
+			"describe",
+			"--tags",
+			"--abbrev=0"
+		])).trim();
+		/* istanbul ignore next */
+		return tag ? tag : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/git/tag/isGitTagConnected.ts
+/**
+* Determine whether a specific git tag commit is reachable from the current HEAD.
+*
+* Uses `git merge-base --is-ancestor refs/tags/<tag>^{commit} HEAD` to verify
+* that the tag's commit is an ancestor of the current reference. Any non-zero
+* exit status or execution error is treated as "not reachable".
+*
+* @param cwd Working directory where the git command will run
+* @param tag Tag name to evaluate (for example, "v1.2.0")
+* @returns True if the tag commit is reachable from HEAD, false otherwise
+*/
+async function isGitTagConnected(cwd, tag) {
+	try {
+		await execGit(cwd, [
+			"merge-base",
+			"--is-ancestor",
+			`refs/tags/${tag}^{commit}`,
+			"HEAD"
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/git/tag/isGitTagPointed.ts
+/**
+* Check whether a given tag points to the provided commit.
+*
+* @param cwd Repository working directory
+* @param tag Tag name to resolve
+* @param commit Commit hash to compare against
+* @returns `true` when the tag points at `commit`, otherwise `false`
+*/
+async function isGitTagPointed(cwd, tag, commit) {
+	try {
+		await execGit(cwd, [
+			"merge-base",
+			"--is-ancestor",
+			`refs/tags/${tag}^{commit}`,
+			commit
+		]);
+		await execGit(cwd, [
+			"merge-base",
+			"--is-ancestor",
+			commit,
+			`refs/tags/${tag}^{commit}`
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/workflow/discovery/buildDependencyGraph.ts
+/**
+* Build a dependency graph mapping package names to dependent release plans.
+*
+* Each key is a package name and the value is a set of `ReleasePlan`s that
+* list that package as a dependency.
+*
+* @param plans Array of release plans to analyze
+* @returns Dependency graph mapping package name -> set of dependent plans
+*/
+function buildDependencyGraph(plans) {
+	const graph = /* @__PURE__ */ new Map();
+	const packageNames = new Set(plans.map((plan) => plan.package.name).filter((name) => !!name));
+	for (const plan of plans) for (const depName of plan.package.dependencies) {
+		let set = graph.get(depName);
+		if (!set && packageNames.has(depName)) graph.set(depName, set = /* @__PURE__ */ new Set());
+		if (set) set.add(plan);
+	}
+	return graph;
+}
+//#endregion
+//#region src/workflow/changelog/extractPlainText.ts
+/**
+* Extract trimmed plain text from a Heading, Paragraph, or PhrasingContent node.
+*
+* Performs a depth-first traversal, concatenating string `value` tokens in
+* document order. Non-string values are ignored. Returns `null` for empty or
+* missing input.
+*
+* @param node Node to extract text from
+* @returns The trimmed plain-text string, or null if empty
+*/
+function extractPlainText(node) {
+	if (!node) return null;
+	const queue = [node];
+	let result = "";
+	while (node = queue.shift()) {
+		if ("value" in node && typeof node.value === "string") result += node.value;
+		/* istanbul ignore else */
+		if ("children" in node && Array.isArray(node.children)) queue.unshift(...node.children);
+	}
+	return result.trim() || null;
+}
+//#endregion
+//#region src/workflow/changelog/extractSemVer.ts
+var ANCHORED_SEMVER_REGEX = new RegExp(`^${SEMVER_REGEX.source}$`);
+var BRACKETED_SEMVER_REGEX = new RegExp(`\\[${SEMVER_REGEX.source}\\]`);
+/**
+* Extract SemVer core strings from a line.
+*
+* Splits the line on runs of spaces or tabs and on `..`/`...`. For each token,
+* first attempts an anchored SemVer match (must match the whole token), then
+* a bracketed match that finds a SemVer inside `[...]`. Returns the captured
+* SemVer core (capture group 2) for each successful match; falsy results are
+* filtered out.
+*
+* @param line Line to scan for SemVer cores
+* @returns Array of extracted SemVer core strings; empty if none
+*/
+function extractSemVer(line) {
+	return compact(line.split(/[ \t]+|\.{2,3}/).map((token) => {
+		return (ANCHORED_SEMVER_REGEX.exec(token) ?? BRACKETED_SEMVER_REGEX.exec(token))?.at(2);
+	}));
+}
+//#endregion
+//#region src/workflow/changelog/iterateChangelogVersions.ts
+var SENTENCE_TERMINAL_REGEX = /\p{Sentence_Terminal}$/u;
+/**
+* Iterate over Semantic Version strings extracted from a Markdown changelog.
+*
+* Parses `changelogContent` into an AST and evaluates nodes sequentially using
+* custom extractors. Evaluates heading nodes first before checking short
+* paragraph nodes. Stops execution after the first strategy yields valid
+* versions.
+*
+* @param changelogContent Raw Markdown text of the changelog
+* @yields Valid SemVer strings found in headings or candidate paragraphs
+*/
+function* iterateChangelogVersions(changelogContent) {
+	const root = fromMarkdown(changelogContent);
+	const nodeExtractors = [(node) => {
+		return node.type === "heading" ? extractPlainText(node) : null;
+	}, (node) => {
+		if (node.type !== "paragraph") return null;
+		const paragraphText = extractPlainText(node);
+		if (!paragraphText || paragraphText.length > 48 || SENTENCE_TERMINAL_REGEX.test(paragraphText)) return null;
+		return paragraphText;
+	}];
+	for (const extractText of nodeExtractors) {
+		let isVersionFound = false;
+		for (const node of root.children) {
+			const extractedText = extractText(node);
+			const candidateVersion = extractedText ? semver.sort(extractSemVer(extractedText)).pop() : null;
+			if (candidateVersion && semver.valid(candidateVersion)) {
+				isVersionFound = true;
+				yield candidateVersion;
+			}
+		}
+		if (isVersionFound) return;
+	}
+}
+//#endregion
+//#region src/workflow/changelog/extractLatestVersion.ts
+/**
+* Find the highest semantic version from the first version-bearing element.
+*
+* Pulls the first available version string from the parsed markdown iterator.
+* Short-circuits execution immediately upon locating a match to avoid passing
+* through the remaining document structure.
+*
+* @param changelogContent The raw markdown string representing the changelog
+* @returns The highest valid semantic version string found or null
+*/
+function extractLatestVersion(changelogContent) {
+	for (const version of iterateChangelogVersions(changelogContent)) return version;
+	return null;
+}
+//#endregion
+//#region src/workflow/discovery/verifyPackageTag.ts
+/**
+* Verify a Git tag against package specifications and history connection.
+*
+* Ensures the target tag exists locally before parsing its commit data. Rejects
+* tags that do not target a commit matching the given `pkg`. Expands the history
+* graph up to the tag reference before verifying structural connectivity.
+*
+* @param cwd Repository working directory
+* @param pkg Package descriptor containing version and location context
+* @param tagName The name of the Git tag to verify
+* @returns A promise resolving to true if the tag is valid and connected
+*/
+async function verifyPackageTag(cwd, pkg, tagName) {
+	await ensureGitTag(cwd, tagName);
+	const tagRef = `refs/tags/${tagName}`;
+	const tagCommit = await getParsedCommit(cwd, tagRef);
+	if (!tagCommit || !isCommitForPackage(pkg, tagCommit)) return false;
+	await expandGitHistory(cwd, { until: tagRef });
+	return isGitTagConnected(cwd, tagName);
+}
+//#endregion
+//#region src/workflow/discovery/discoverPackageTag.ts
+/**
+* Discover and validate the Git tag for a package.
+*
+* Returns the existing tag if already present on the `pkg` object. Resolves
+* the local changelog file path, extracts the current version, and generates
+* the expected Git tag name. Verifies the tag against the repository and
+* ensures its historical changelog version matches the current local version.
+*
+* @param cwd The current working directory
+* @param pkg The package configuration object
+* @returns The validated `Tag` object or null if validation fails
+*/
+async function discoverPackageTag(cwd, pkg) {
+	if (pkg.tag) return pkg.tag;
+	const changelogFile = pkg.changelogFile || "CHANGELOG.md";
+	const changelogFilePath = path.resolve(cwd, pkg.dir, changelogFile);
+	let localChangelogContent;
+	try {
+		localChangelogContent = await readFile(changelogFilePath, "utf-8");
+	} catch {}
+	if (!localChangelogContent) return null;
+	const currentVersion = extractLatestVersion(localChangelogContent);
+	if (!currentVersion) return null;
+	let expectedTagName;
+	try {
+		expectedTagName = generateGitTagName(pkg.entry, pkg.name, currentVersion);
+	} catch {}
+	if (!expectedTagName) return null;
+	if (!await verifyPackageTag(cwd, pkg, expectedTagName)) return null;
+	const historicalChangelogContent = await readGitFile(cwd, await resolveGitRevision(cwd, `refs/tags/${expectedTagName}`), path.relative(cwd, changelogFilePath));
+	if (!historicalChangelogContent) return null;
+	const historicalChangelogVersion = extractLatestVersion(historicalChangelogContent);
+	if (!historicalChangelogVersion || historicalChangelogVersion !== currentVersion) return null;
+	return {
+		name: expectedTagName,
+		message: await getGitTagMessage(cwd, expectedTagName)
+	};
+}
+//#endregion
+//#region src/workflow/discovery/resolvePackageStableTag.ts
+/**
+* Resolve the latest stable Git tag for a package.
+*
+* Reads changelog release versions for `pkg` and verifies strict descending
+* semver order. Ignores prerelease versions unless transitioning across major
+* or prerelease boundaries, and verifies that the matching Git tag exists.
+*
+* @param cwd Absolute path to the root working directory
+* @param pkg Package configuration object
+* @returns Verified tag metadata object or `null` if no stable tag is resolved
+* @throws If a version is invalid, versions are not in strict descending
+* order, or the corresponding Git tag is missing
+*/
+async function resolvePackageStableTag(cwd, pkg) {
+	const changelogFile = pkg.changelogFile || "CHANGELOG.md";
+	const changelogFilePath = path.resolve(cwd, pkg.dir, changelogFile);
+	let changelogContent;
+	try {
+		changelogContent = await readFile(changelogFilePath, "utf-8");
+	} catch (error) {
+		/* istanbul ignore else */
+		if (error?.code === "ENOENT") return null;
+		/* istanbul ignore next */
+		throw error;
+	}
+	let precedingVersion = null;
+	for (const version of iterateChangelogVersions(changelogContent)) {
+		const currentVersion = semver.parse(version);
+		assert(currentVersion, `Version "${version}" is not a valid semantic version.`);
+		if (precedingVersion && semver.gte(currentVersion, precedingVersion)) throw new Error(`Version "${version}" must be strictly lower than preceding version "${precedingVersion.raw}".`);
+		if (!semver.prerelease(currentVersion) && (currentVersion.major >= 1 || precedingVersion && semver.prerelease(precedingVersion))) {
+			const tagName = generateGitTagName(pkg.entry, pkg.name, version);
+			if (!await verifyPackageTag(cwd, pkg, tagName)) throw new Error(`Git tag "${tagName}" is not associated with package "${pkg.name ?? ""}" in directory "${pkg.dir}".`);
+			return {
+				name: tagName,
+				message: await getGitTagMessage(cwd, tagName)
+			};
+		}
+		precedingVersion = currentVersion;
+	}
+	return null;
+}
+//#endregion
+//#region src/workflow/discovery/resolvePackageTag.ts
+/**
+* Resolve the release tag for a single package version.
+*
+* Returns the cached `pkg.tag` immediately if it already exists. Generates an
+* expected tag name from the package metadata and verifies its integrity using
+* `verifyPackageTag`.
+*
+* @param cwd Repository working directory
+* @param pkg Package descriptor containing version and location context
+* @returns A promise resolving to the tag metadata or null when not found
+*/
+async function resolvePackageTag(cwd, pkg) {
+	if (pkg.tag) return pkg.tag;
+	let expectedTagName;
+	try {
+		expectedTagName = generateGitTagName(pkg.entry, pkg.name, pkg.version);
+	} catch {}
+	if (!expectedTagName) return null;
+	if (await verifyPackageTag(cwd, pkg, expectedTagName)) return {
+		name: expectedTagName,
+		message: await getGitTagMessage(cwd, expectedTagName)
+	};
+	return null;
+}
+//#endregion
+//#region src/workflow/analysis/propagateDependencyUpdates.ts
+/**
+* Propagate release updates through package dependencies.
+*
+* Marks packages that depend on a releasing package for a `patch` release
+* when they do not already have a release type.
+*
+* @param plans Array of release plans to update
+* @returns Updated array of release plans
+*/
+async function propagateDependencyUpdates(cwd, plans) {
+	const graph = buildDependencyGraph(plans);
+	const scheduled = /* @__PURE__ */ new Map();
+	const stack = [];
+	for (const plan of plans) if (plan.release?.type) {
+		const visited = /* @__PURE__ */ new Set([plan]);
+		stack.push(plan);
+		let curr;
+		while (curr = stack.pop()) if (curr.package.name) {
+			for (const dependent of graph.get(curr.package.name) ?? []) if (!visited.has(dependent)) {
+				visited.add(dependent);
+				stack.push(dependent);
+				scheduled.set(dependent, await mergeGitHistory(cwd, scheduled.get(dependent) ?? dependent.history, plan.history));
+			}
+		}
+	}
+	return plans.map((plan) => {
+		const history = scheduled.get(plan);
+		if (history) {
+			plan = {
+				...plan,
+				history
+			};
+			if (!plan.release?.type) plan.release = { type: "patch" };
+		}
+		return plan;
+	});
+}
+//#endregion
+//#region src/workflow/committing/isReleaseCommit.ts
+/**
+* Determine whether a commit represents a release or matches a release marker.
+*
+* Resolves string commit identifiers to parsed commit objects, checks if any
+* associated trailer matches the marker predicate, and falls back to verifying
+* exact tag matches for the `commit` hash.
+*
+* @param cwd The working directory path for Git commands
+* @param commit The commit object, hash string, or null/undefined
+* @param marker The trailer key string or a predicate function to evaluate
+* @returns True if the commit is a release commit, otherwise false
+*/
+async function isReleaseCommit(cwd, commit, marker = GIT_TRAILER_RELEASE_AGENT) {
+	if (typeof commit === "string") commit = await getParsedCommit(cwd, commit, typeof marker === "string" ? [marker] : []);
+	if (!commit) return false;
+	const predicate = typeof marker === "string" ? (trailer) => trailer.key === marker && !!trailer.value : marker;
+	if (commit.trailers.some(predicate)) return true;
+	return execGit(cwd, [
+		"describe",
+		"--tags",
+		"--exact-match",
+		commit.hash
+	]).then(() => true).catch(() => false);
+}
+//#endregion
+//#region src/workflow/analysis/sliceUnreleased.ts
+/**
+* Yield parsed commits from the workspace until a release commit is found.
+*
+* Iterates through parsed commit history and yields unreleased commits in
+* order. Stops processing upon reaching the first release commit.
+*
+* @param cwd Path to the working directory
+* @param options Options for configuring Git history retrieval
+* @yields Parsed `Commit` objects up to the most recent release commit
+*/
+async function* sliceUnreleased(cwd, options) {
+	for await (const commit of showParsedGitHistory(cwd, options)) {
+		if (await isReleaseCommit(cwd, commit, options?.marker)) break;
+		yield commit;
+	}
+}
+//#endregion
+//#region src/workflow/analysis/streamPackageCommits.ts
+/**
+* Yield commits from git history associated with a package.
+*
+* Filters git commit history to stream only entries relevant to the target
+* `pkg` directory.
+*
+* @param cwd Path to the working directory for git commands
+* @param pkg Package configuration containing the target directory
+* @param options Options for parsing and filtering git history
+* @yields Commits belonging to the specified package
+*/
+async function* streamPackageCommits(cwd, pkg, options = {}) {
+	options = {
+		...options,
+		filePath: options.filePath || pkg.dir
+	};
+	for await (const commit of showParsedGitHistory(cwd, options)) if (isCommitForPackage(pkg, commit)) yield commit;
+}
+//#endregion
+//#region src/workflow/changelog/buildChangelog.ts
+var preset = await createPreset();
+var headerPartial = (context) => {
+	return context.version ? preset.writer.headerPartial?.(context) : void 0;
+};
+/**
+* Build the changelog string for a release.
+*
+* Compiles commit history and release context into a formatted changelog using
+* conventional commits and writer configurations. Resolves file paths and handles
+* tag comparisons when repository URLs are available.
+*
+* @param context The release context containing repository and working directory details
+* @param history The iterable or async iterable collection of commits to process
+* @param options The build configuration options for the changelog
+* @returns The formatted changelog content string
+*/
+async function buildChangelog(context, history, options = {}) {
+	const repository = context.repository?.url || void 0;
+	const version = options.version || void 0;
+	const previousTag = options.previousTag || void 0;
+	const currentTag = options.currentTag || void 0;
+	return formatFile(path.join(context.cwd, options.packageDir || ".", options.changelogFile || "CHANGELOG.md"), await writeChangelogString(history, {
+		date: context.today,
+		version,
+		previousTag,
+		currentTag,
+		linkCompare: !!repository && !!previousTag && !!currentTag,
+		linkReferences: !!repository,
+		repoUrl: repository,
+		commit: "commit",
+		issue: "issues",
+		headerPartial
+	}, preset.writer));
+}
+//#endregion
+//#region src/workflow/changelog/buildReleaseNotes.ts
+/**
+* Build release notes from a release context and commit history.
+*
+* Generates changelog content from commits, parses it into an abstract syntax
+* tree, shifts heading depths, and formats the resulting markdown file.
+*
+* @param context The release context containing repository and configuration details
+* @param history The iterable or async iterable collection of commits to process
+* @returns The formatted release notes as a markdown string
+*/
+async function buildReleaseNotes(context, history) {
+	const changelogContent = await buildChangelog(context, history);
+	const root = fromMarkdown(changelogContent);
+	root.children = root.children.flatMap((node) => {
+		if (node.type === "heading") {
+			/* istanbul ignore next */
+			if (node.depth <= 2) return [];
+			node = {
+				...node,
+				depth: node.depth - 1
+			};
+		}
+		return node;
+	});
+	return formatFile(path.join(context.cwd, DEFAULT_CHANGELOG_FILE), toMarkdown(root));
+}
+//#endregion
+//#region src/workflow/changelog/extractPreviousVersion.ts
+/**
+* Find the latest stable version that precedes the current version.
+*
+* Parses markdown from top to bottom to extract semantic versions from headings
+* and paragraphs. Enforces that discovered versions appear in strict
+* descending order. Returns the first version that falls outside the current
+* version's major, minor, and patch boundaries if the current version is
+* `v1.0.0` or higher, or the first non-matching version for `v0.x.x` releases.
+*
+* @param currentVersion The version to evaluate against
+* @param changelogContent The raw markdown content to scan for versions
+* @returns The resolved stable version string or null when none is found
+* @throws If `currentVersion` is invalid or already stable, or if versions in the changelog are not listed in strict descending order
+*/
+async function extractPreviousVersion(currentVersion, changelogContent) {
+	const parsedCurrent = semver.parse(currentVersion);
+	if (!currentVersion || !parsedCurrent) throw new Error(`The current version "${colors.bold(String(currentVersion))}" is not a valid semantic version.`);
+	const currentMajor = parsedCurrent.major;
+	if (currentMajor >= 1 && parsedCurrent.prerelease.length === 0) throw new Error(`The current version "${colors.bold(currentVersion)}" is already a stable release.`);
+	const baseVersion = `${parsedCurrent.major}.${parsedCurrent.minor}.${parsedCurrent.patch}`;
+	let priorVersion = null;
+	for (const version of iterateChangelogVersions(changelogContent)) {
+		const parsedVersion = semver.parse(version);
+		/* istanbul ignore else */
+		if (parsedVersion) if (!priorVersion) {
+			if (version !== currentVersion) return version;
+			priorVersion = parsedVersion;
+		} else {
+			if (semver.gte(parsedVersion, priorVersion)) throw new Error(`Each newer release must have a higher version, but "${colors.bold(priorVersion.version)}" appears before "${colors.bold(version)}".`);
+			priorVersion = parsedVersion;
+			const { major, minor, patch } = parsedVersion;
+			if (currentMajor >= 1 && `${major}.${minor}.${patch}` !== baseVersion) return version;
+		}
+	}
+	return null;
+}
+//#endregion
+//#region src/workflow/changelog/prependChangelog.ts
+var defaultChangelogTitle = "Changelog";
+/**
+* Prepend changelog content to a markdown file, creating it if necessary.
+*
+* Reads the existing file if present, prepends the new content before the main heading,
+* formats and writes the result back.
+*
+* @param filePath Path to the changelog file
+* @param revision Changelog content to prepend
+* @returns Promise that resolves when the changelog is written
+*/
+async function prependChangelog(filePath, revision) {
+	let content = "";
+	try {
+		content = await fs.readFile(filePath, "utf-8");
+	} catch (err) {
+		/* istanbul ignore next */
+		if (err.code !== "ENOENT") throw err;
+	}
+	const root = fromMarkdown(content);
+	let index = root.children.findIndex((node) => node.type === "heading" && node.depth === 1);
+	if (index === -1) {
+		index = 0;
+		root.children.unshift({
+			type: "heading",
+			depth: 1,
+			children: [{
+				type: "text",
+				value: defaultChangelogTitle
+			}]
+		});
+	}
+	root.children.splice(index + 1, 0, ...fromMarkdown(revision).children);
+	content = toMarkdown(root);
+	content = await formatFile(filePath, content);
+	await fs.writeFile(filePath, content);
+}
+//#endregion
+//#region src/workflow/changelog/writeChangelog.ts
+/**
+* Write changelog content to the file system based on the release plan.
+*
+* @param cwd Repository working directory
+* @param plan Release plan containing package and changelog content
+* @returns Promise that resolves when the changelog file has been written
+*/
+async function writeChangelog(cwd, plan) {
+	if (plan.release?.changelog) {
+		const changelogFile = plan.package.changelogFile || "CHANGELOG.md";
+		await prependChangelog(path.join(cwd, plan.package.dir, changelogFile), plan.release.changelog);
+	}
+}
+//#endregion
+//#region package.json
+var version = "0.1.1";
+//#endregion
+//#region src/workflow/committing/generateReleaseCommitMessage.ts
+/**
+* Generate a formatted release commit message based on release plans and
+* custom trailers.
+*
+* Compiles package version updates and included commit logs into a standardized
+* conventional commit message body, appending configured release agent and
+* custom trailers. Returns null if no valid release subject can be derived.
+*
+* @param plans Readonly array of release plans containing package changes and commit history
+* @param trailers Optional record of custom git trailers to append to the commit
+* @returns The formatted release commit message string or null if the subject is empty
+*/
+async function generateReleaseCommitMessage(plans, trailers = {}) {
+	const standalone = plans.length === 1;
+	trailers = {
+		[GIT_TRAILER_RELEASE_AGENT]: `ReelOut/${/* istanbul ignore next */ version}`,
+		...trailers
+	};
+	plans = plans.filter((plan) => plan.release?.tag?.name).toSorted((a, b) => {
+		if (a.package.entry) return -1;
+		if (b.package.entry) return 1;
+		/* istanbul ignore next */
+		return (a.package.name ?? "").localeCompare(b.package.name ?? "");
+	});
+	let subject;
+	if (plans.length === 1) subject = standalone ? plans[0]?.release?.version : plans[0]?.release?.tag?.name;
+	else if (plans.length >= 2 && plans.length <= 3) subject = plans.map((plan) => plan.release?.tag?.name).join(", ");
+	else if (plans.length > 3) subject = `${plans.length} packages (${plans.slice(0, 2).map((plan) => plan.release?.tag?.name).join(", ")}, +${plans.length - 2} more)`;
+	if (!subject) return null;
+	const packages = plans.map((plan) => {
+		return `- ${plan.package.name || plan.package.dir}: ${plan.package.version} → ${plan.release?.version}`;
+	});
+	const commits = Array.from(new Map(plans.flatMap((plan) => plan.history).map((commit) => [commit.hash, commit])).values()).toSorted((a, b) => {
+		return new Date(a.committerDate).valueOf() - new Date(b.committerDate).valueOf();
+	}).map(({ header }) => `- ${header}`);
+	return [
+		`chore: release ${subject}`,
+		packages.length >= 2 ? ["## Version Updates", ...packages].join("\n") : void 0,
+		commits.length > 0 ? ["## Changes Included", ...commits].join("\n") : void 0,
+		Object.entries(trailers).map(([key, value]) => key && value != null ? `${key}: ${value}` : "").filter(Boolean).join("\n")
+	].filter(Boolean).join("\n\n");
+}
+//#endregion
+//#region src/workflow/report/generateReleaseReport.ts
+/**
+* Generate a release report from the current workflow state.
+*
+* Extracts relevant information from the context and organizes it into a report
+* containing workflow phase, status, plugin metadata, packages, and release plans.
+*
+* @param context Release context with workflow state and plans
+* @param plugin Name of the current plugin executing
+* @param hook Current workflow phase
+* @param status Workflow completion status (`'success'` or `'failure'`)
+* @param reason Error or failure reason (used only when status is `'failure'`)
+* @returns Release report object with structured workflow results
+*/
+function generateReleaseReport(context, plugin, hook, status, reason) {
+	return {
+		phase: plugin && hook ? {
+			plugin,
+			hook
+		} : void 0,
+		status,
+		reason: Error.isError(reason) ? reason.message : typeof reason === "string" ? reason : null,
+		prereleaseLabel: context.prereleaseLabel,
+		releaseChannel: context.releaseChannel,
+		plugins: context.plugins.map((plugin) => ({
+			name: plugin.name,
+			version: plugin.version,
+			hooks: Object.keys(plugin).filter((key) => key !== "name" && key !== "version")
+		})),
+		packages: context.packages.map((pkg) => ({
+			dir: pkg.dir,
+			name: pkg.name,
+			version: pkg.version
+		})),
+		plans: compact(context.plans.map((plan) => {
+			if (!plan.release?.version) return null;
+			return {
+				package: {
+					entry: plan.package.entry,
+					dir: plan.package.dir,
+					name: plan.package.name,
+					version: plan.package.version,
+					private: !!plan.package.private
+				},
+				release: {
+					type: plan.release.type,
+					version: plan.release.version,
+					tag: plan.release.tag?.name,
+					changelog: plan.release.changelog
+				}
+			};
+		}))
+	};
+}
+//#endregion
+//#region src/workflow/report/printReleaseReport.ts
+/**
+* Print a formatted release report to the logger.
+*
+* Logs the workflow status and details about released packages. On success,
+* displays released package names and version changes. On failure, displays
+* the error reason.
+*
+* @param context Release context for logging
+* @param report Release report to display
+* @returns void
+*/
+function printReleaseReport(context, report) {
+	const statusLabel = {
+		success: colors.green("SUCCESS"),
+		failure: colors.red("FAILURE")
+	}[report.status];
+	context.logger.info(`Status: ${statusLabel}`);
+	if (report.status === "failure") return context.logger.error(["Release complete:", colors.red(report.reason || "An unexpected error occurred during the release process.")].join(" "));
+	if (report.plans.length === 0) return context.logger.info(["Release complete:", colors.yellow("No packages are scheduled for release.")].join(" "));
+	const header = [
+		"Release complete:",
+		colors.bold(colors.green(`${report.plans.length} released`)),
+		colors.gray(`(${report.packages.length})`)
+	].join(" ");
+	const list = report.plans.toSorted((a, b) => (a.package.name || "").localeCompare(b.package.name || "")).map((plan) => {
+		let dir = path.normalize(path.join(plan.package.dir, "."));
+		dir = dir === "." ? dir : `./${dir}`;
+		const name = plan.package.name ? colors.bgBlue(` ${plan.package.name} `) : !plan.package.entry && colors.gray(` ${dir} `);
+		let version = [plan.release.version, plan.package.version].filter(Boolean).join(" ← ");
+		version = ` ${version} `;
+		const type = plan.release.type && colors.gray(` ${plan.release.type} `);
+		return [[
+			name,
+			plan.release.type === "major" ? colors.bgRed(version) : colors.bgGreen(version),
+			type
+		].filter(Boolean).join(""), plan.release.changelog?.replace(/^(#+ .+)$/gm, (_, header) => colors.cyan(header)).trim()].filter(Boolean).join("\n\n");
+	}).join("\n\n");
+	context.logger.info(`${header}\n\n${list}\n`);
+}
+//#endregion
+//#region src/workflow/runner/runWorkflow.ts
+/**
+* Execute the plugin-driven release workflow using the provided `ReleaseContext`.
+*
+* The workflow runs plugin stages in order: `configure`, `discover`,
+* `analyze`, `build`, `write`, `commit`, and `publish`. After a successful
+* run the function sets `context.status` to `'success'`. The workflow is
+* finalized in all cases; on success a release report is printed.
+*
+* The returned array contains all computed release plans, including plans
+* without releases. Side effects (file writes, commits, tags, publishing)
+* are performed by plugins and may be skipped when `context.dryRun` is true.
+*
+* @returns Promise that resolves when the workflow is complete.
+*/
+async function runWorkflow(createContext) {
+	const context = await createContext();
+	const stack = [];
+	let plugin;
+	let hook;
+	let status = "success";
+	let reason = null;
+	try {
+		const ordered = RELEASE_LIFECYCLE_HOOK_LIST.flatMap((hookName) => {
+			return compact(context.plugins.map((plugin) => {
+				let hook = plugin[hookName];
+				if (!hook) return void 0;
+				hook = typeof hook === "function" ? { handler: hook } : hook;
+				const { enforce, handler } = hook;
+				return {
+					plugin,
+					hook: hookName,
+					handler,
+					weight: enforce === "pre" ? -1 : enforce === "post" ? 1 : 0
+				};
+			})).sort((a, b) => a.weight - b.weight);
+		});
+		let handler;
+		for ({plugin, hook, handler} of ordered) {
+			const label = `${colors.gray(`[${hook}]`)} ${plugin.name}`;
+			let startedLogging = false;
+			let timer;
+			timer = setTimeout(() => {
+				startedLogging = true;
+				context.logger.start(label);
+			}, 10);
+			const startTime = performance.now();
+			try {
+				const rollback = await handler(context);
+				if (typeof rollback === "function") stack.push(rollback);
+			} finally {
+				clearTimeout(timer);
+			}
+			const duration = (performance.now() - startTime) / 1e3;
+			/* istanbul ignore next */
+			if (startedLogging) {
+				const time = (duration >= 5 ? colors.red : colors.cyan)(`${duration.toFixed(2)}s`);
+				context.logger.success(`${label} ${time}`);
+			}
+		}
+	} catch (err) {
+		status = "failure";
+		reason = err;
+		for (const rollback of stack.toReversed()) try {
+			await rollback(reason);
+		} catch {}
+		throw err;
+	} finally {
+		printReleaseReport(context, generateReleaseReport(context, plugin?.name, hook, status, reason));
+	}
+}
+//#endregion
+export { GIT_PRETTY_FORMAT as $, ensureGitTag as A, deriveReleaseType as At, showParsedGitHistory as B, buildDependencyGraph as C, isSemVerGitTag as Ct, getGitTagMessage as D, RELEASE_LIFECYCLE_HOOK_LIST as Dt, getLatestGitTag as E, GIT_TRAILER_RELEASE_AGENT as Et, resolveGitRepository as F, detectGitRelationship as G, restoreFullGitHistory as H, pushGitChanges as I, withShallowLock as J, expandGitHistory as K, getGitRemote as L, deleteGitTag as M, determineReleaseType as Mt, createGitTag as N, bumpVersion as Nt, getCurrentGitTag as O, SEMVER_REGEX as Ot, readGitFile as P, GIT_PRETTY_FIELD_SEPARATOR as Q, ensureGitUserConfig as R, extractPlainText as S, buildTrailerPattern as St, isGitTagConnected as T, DEFAULT_CHANGELOG_FILE as Tt, mergeGitHistory as U, showGitHistory as V, GIT_REL_FLAGS as W, countGitHistory as X, isGitShallowRepository as Y, getParsedCommit as Z, discoverPackageTag as _, formatFile as _t, version as a, extractMentions as at, iterateChangelogVersions as b, compact as bt, extractPreviousVersion as c, promotePrereleaseVersions as ct, streamPackageCommits as d, resolveReleaseTarget as dt, parseGitPrettyFormat as et, sliceUnreleased as f, sanitizePrereleaseLabel as ft, resolvePackageStableTag as g, interpolate as gt, resolvePackageTag as h, isMatch as ht, generateReleaseCommitMessage as i, resolveGitRevision as it, isGitTagPresent as j, pickPriorityReleaseType as jt, generateGitTagName as k, isStableVersion as kt, buildReleaseNotes as l, analyzePackageChanges as lt, propagateDependencyUpdates as m, readJson as mt, printReleaseReport as n, TTLCache as nt, writeChangelog as o, createGitCommit as ot, isReleaseCommit as p, writeJson as pt, isGitAncestor as q, generateReleaseReport as r, getCurrentGitCommit as rt, prependChangelog as s, getCurrentGitBranch as st, runWorkflow as t, parseCommit as tt, buildChangelog as u, isCommitForPackage as ut, verifyPackageTag as v, execGit as vt, isGitTagPointed as w, ALL_FILES as wt, extractSemVer as x, isDefined as xt, extractLatestVersion as y, execCommand as yt, getGitConfigValue as z };
+
+//# sourceMappingURL=workflow-BoVmbvH6.js.map