fireflyy 4.0.0-dev.a10ed44 → 4.0.0-dev.a8aacbe

package/dist/{program-Dqo9sQjU.js → program-BOk_0Q6Q.js}

@@ -1,9 +1,11 @@
 import { t as RuntimeEnv } from "./main.js";
-import { a as conflictErrAsync, c as notFoundErrAsync, d as validationErrAsync, f as conflictError, g as notFoundError, i as FireflyOkAsync, l as timeoutErrAsync, m as failedError, n as FireflyErrAsync, o as failedErrAsync, r as FireflyOk, s as invalidErr, t as FireflyErr, u as validationErr, v as validationError, y as wrapErrorMessage } from "./result.constructors-BMtOWD2-.js";
-import { n as wrapPromise, t as ensureNotAsync } from "./result.utilities-BTVU-GsT.js";
-import { t as logger } from "./logging-BuIkRrn1.js";
-import { n as parseSchema, t as formatZodErrors } from "./schema.utilities-BxiRR-GI.js";
-import { Command } from "commander";
+import { t as DebugFlags } from "./debug-flags-K3yK5B6O.js";
+import { _ as notFoundError, a as conflictErrAsync, b as wrapErrorMessage, c as invalidErrAsync, d as validationErr, f as validationErrAsync, h as failedError, i as FireflyOkAsync, l as notFoundErrAsync, n as FireflyErrAsync, o as failedErrAsync, p as conflictError, r as FireflyOk, s as invalidErr, t as FireflyErr, u as timeoutErrAsync, y as validationError } from "./result.constructors-DoAoYdfF.js";
+import { n as wrapPromise, t as ensureNotAsync } from "./result.utilities-DXSJU70_.js";
+import { t as logger } from "./logging-Bpk2RzGc.js";
+import { t as Version } from "./version-DJuocyXy.js";
+import { t as formatZodErrors } from "./schema.utilities-C1yimTtB.js";
+import { Command, InvalidArgumentError } from "commander";
 import { LogLevels } from "consola";
 import { colors } from "consola/utils";
 import { loadConfig } from "c12";
@@ -12,70 +14,6 @@ import z$1 from "zod";
 import { parse } from "semver";
 import * as path from "path";
 
-//#region src/core/environment/debug-flags.ts
-/**
-* Debug flags are environment variables prefixed with `FIREFLY_DEBUG_` that
-* enable diagnostic features during development and troubleshooting.
-*
-* @example
-* ```typescript
-* if (DebugFlags.showRawError) {
-*     logger.error(parseResult.error);
-* }
-* ```
-*/
-var DebugFlags = class {
-	constructor() {}
-	/**
-	* When enabled, displays raw Zod validation errors for configuration parsing.
-	*
-	* Useful for debugging configuration schema issues and understanding
-	* why validation failed at a granular level.
-	*/
-	static get showRawError() {
-		return Boolean(process.env.FIREFLY_DEBUG_SHOW_RAW_ERROR);
-	}
-	/**
-	* When enabled, logs the loaded configuration file contents.
-	*
-	* Useful for debugging configuration loading and understanding
-	* what values are being read from config files.
-	*/
-	static get showFileConfig() {
-		return Boolean(process.env.FIREFLY_DEBUG_SHOW_FILE_CONFIG);
-	}
-	/**
-	* When enabled, displays task graph statistics during release execution.
-	*
-	* Shows information about task dependencies, execution order,
-	* and graph structure for debugging workflow issues.
-	*/
-	static get showTaskGraphStats() {
-		return Boolean(process.env.FIREFLY_DEBUG_SHOW_TASK_GRAPH_STATS);
-	}
-	/**
-	* When enabled, prevents truncation of release notes in GitHub CLI logs.
-	*
-	* By default, release notes are truncated in logs to avoid pollution.
-	* Enable this flag to see full release notes content during debugging.
-	*/
-	static get dontTruncateReleaseNotes() {
-		return Boolean(process.env.FIREFLY_DEBUG_DONT_TRUNCATE_RELEASE_NOTES?.trim());
-	}
-	/**
-	* When enabled, prevents redaction of sensitive GitHub CLI arguments in logs.
-	*
-	* By default, sensitive values (tokens, passwords, etc.) are redacted.
-	* Enable this flag to see full argument values during debugging.
-	*
-	* WARNING: Use with caution as this may expose sensitive information.
-	*/
-	static get dontRedactGithubCliArgs() {
-		return Boolean(process.env.FIREFLY_DEBUG_DONT_REDACT_GITHUB_CLI_ARGS?.trim());
-	}
-};
-
-//#endregion
 //#region src/cli/config/config.loader.ts
 /**
 * Loads and resolves Firefly configuration from files.
@@ -185,6 +123,223 @@ function camelToKebab(str) {
 	return result.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/_/g, "-");
 }
 
+//#endregion
+//#region src/cli/options/options.validation.ts
+/**
+* Extracts enum values from a Zod schema (handles wrapped types like optional, default).
+*
+* @param schema - The Zod schema to extract enum values from
+* @returns Array of string values if it's an enum, or null if not
+*/
+function extractEnumValues(schema) {
+	const unwrapped = unwrapZodSchema(schema);
+	if (unwrapped instanceof z$1.ZodEnum) return getEnumValuesFromZodEnum(unwrapped);
+	if (unwrapped instanceof z$1.ZodUnion) {
+		const unionOptions = getZodDef(unwrapped).options;
+		if (!unionOptions) return null;
+		const values = [];
+		for (const option of unionOptions) {
+			if (typeof option === "string") continue;
+			const innerUnwrapped = unwrapZodSchema(option);
+			if (innerUnwrapped instanceof z$1.ZodEnum) {
+				const enumValues = getEnumValuesFromZodEnum(innerUnwrapped);
+				if (enumValues) values.push(...enumValues);
+			} else if (innerUnwrapped instanceof z$1.ZodLiteral) {
+				const literalValue = getZodDef(innerUnwrapped).value;
+				if (typeof literalValue === "string" && literalValue !== "") values.push(literalValue);
+			}
+		}
+		return values.length > 0 ? values : null;
+	}
+	return null;
+}
+/**
+* Extracts enum values from a ZodEnum type.
+* Handles both Zod v4 (options array or entries object) and legacy (values array) structures.
+*
+* @param enumSchema - The ZodEnum schema
+* @returns Array of string values, or null if not found
+*/
+function getEnumValuesFromZodEnum(enumSchema) {
+	const schemaAsAny = enumSchema;
+	if (Array.isArray(schemaAsAny.options)) return schemaAsAny.options;
+	const def = getZodDef(enumSchema);
+	if (def.entries && typeof def.entries === "object") return Object.values(def.entries);
+	if (def.values && Array.isArray(def.values)) return def.values;
+	return null;
+}
+/**
+* Extracts literal values from a Zod union schema (e.g., z.union([z.literal("0"), z.literal("1")])).
+*
+* @param schema - The Zod schema to extract literal values from
+* @returns Array of literal values if it's a union of literals, or null if not
+*/
+function extractLiteralValues(schema) {
+	const unwrapped = unwrapZodSchema(schema);
+	if (unwrapped instanceof z$1.ZodUnion) {
+		const options = getZodDef(unwrapped).options;
+		if (!options) return null;
+		const values = [];
+		for (const option of options) {
+			if (typeof option === "string" || typeof option === "number") continue;
+			const innerUnwrapped = unwrapZodSchema(option);
+			if (innerUnwrapped instanceof z$1.ZodLiteral) {
+				const value = getZodDef(innerUnwrapped).value;
+				if (typeof value === "string" || typeof value === "number") values.push(value);
+			}
+		}
+		return values.length > 0 ? values : null;
+	}
+	return null;
+}
+/**
+* Creates a CLI option validator for enum fields.
+*
+* Commander.js requires throwing InvalidArgumentError for validation errors.
+* This is a boundary where exceptions are appropriate for the CLI framework.
+*
+* @param schema - The Zod schema for validation
+* @param optionName - The CLI option name (for error messages)
+* @param choices - The valid enum choices
+* @returns A parser function that throws InvalidArgumentError on failure
+*/
+function createEnumValidator(schema, optionName, choices) {
+	return (input) => {
+		const result = schema.safeParse(input);
+		if (!result.success) throw new InvalidArgumentError(`Invalid value for --${optionName}: "${input}". Must be one of: ${choices.join(", ")}`);
+		return result.data;
+	};
+}
+/**
+* Creates a CLI option validator for number fields.
+*
+* Commander.js requires throwing InvalidArgumentError for validation errors.
+* This is a boundary where exceptions are appropriate for the CLI framework.
+*
+* @param schema - The Zod schema for validation
+* @param optionName - The CLI option name (for error messages)
+* @returns A parser function that throws InvalidArgumentError on failure
+*/
+function createNumberValidator(schema, optionName) {
+	return (input) => {
+		const num = Number(input);
+		if (Number.isNaN(num)) throw new InvalidArgumentError(`Invalid number for --${optionName}: "${input}". Expected a valid number.`);
+		const result = schema.safeParse(num);
+		if (!result.success) throw new InvalidArgumentError(`Invalid value for --${optionName}: "${input}". ${formatZodErrorMessage(result.error)}`);
+		return result.data;
+	};
+}
+/**
+* Creates a CLI option validator for string fields.
+*
+* Commander.js requires throwing InvalidArgumentError for validation errors.
+* This is a boundary where exceptions are appropriate for the CLI framework.
+*
+* @param schema - The Zod schema for validation
+* @param optionName - The CLI option name (for error messages)
+* @returns A parser function that throws InvalidArgumentError on failure
+*/
+function createStringValidator(schema, optionName) {
+	return (input) => {
+		const result = schema.safeParse(input);
+		if (!result.success) throw new InvalidArgumentError(`Invalid value for --${optionName}: "${input}". ${formatZodErrorMessage(result.error)}`);
+		return result.data;
+	};
+}
+/**
+* Creates a CLI option validator for union types with literal values.
+*
+* Commander.js requires throwing InvalidArgumentError for validation errors.
+* This is a boundary where exceptions are appropriate for the CLI framework.
+*
+* @param schema - The Zod schema for validation
+* @param optionName - The CLI option name (for error messages)
+* @param values - The valid literal values
+* @returns A parser function that throws InvalidArgumentError on failure
+*/
+function createLiteralUnionValidator(schema, optionName, values) {
+	return (input) => {
+		const numericValues = values.filter((v) => typeof v === "number");
+		let parsedInput = input;
+		if (numericValues.length > 0 && !Number.isNaN(Number(input))) parsedInput = Number(input);
+		const result = schema.safeParse(parsedInput);
+		if (!result.success) throw new InvalidArgumentError(`Invalid value for --${optionName}: "${input}". Must be one of: ${values.map((v) => typeof v === "string" ? `"${v}"` : String(v)).join(", ")}`);
+		return result.data;
+	};
+}
+/**
+* Creates a generic CLI option validator.
+*
+* Commander.js requires throwing InvalidArgumentError for validation errors.
+* This is a boundary where exceptions are appropriate for the CLI framework.
+*
+* @param schema - The Zod schema for validation
+* @param optionName - The CLI option name (for error messages)
+* @returns A parser function that throws InvalidArgumentError on failure
+*/
+function createGenericValidator(schema, optionName) {
+	return (input) => {
+		const result = schema.safeParse(input);
+		if (!result.success) throw new InvalidArgumentError(`Invalid value for --${optionName}: "${input}". ${formatZodErrorMessage(result.error)}`);
+		return result.data;
+	};
+}
+/**
+* Formats a Zod error into a user-friendly message.
+*
+* @param error - The Zod error object
+* @returns A formatted error message
+*/
+function formatZodErrorMessage(error) {
+	const firstIssue = error.issues[0];
+	if (!firstIssue) return "Validation failed.";
+	switch (firstIssue.code) {
+		case "invalid_value": {
+			const issue = firstIssue;
+			if (issue.values) return `Expected one of: ${issue.values.join(", ")}`;
+			return firstIssue.message;
+		}
+		case "invalid_type": return `Expected ${firstIssue.expected}`;
+		case "too_small":
+		case "too_big": return firstIssue.message;
+		default: return firstIssue.message;
+	}
+}
+/**
+* Gets the internal definition object from a Zod type.
+* Handles both modern Zod v4 (_zod.def) and legacy (_def) structures.
+*
+* @param field - The Zod type to get the definition from
+* @returns The internal definition object
+*/
+function getZodDef(field) {
+	const zodContainer = field._zod;
+	if (zodContainer?.def) return zodContainer.def;
+	return field._def ?? {};
+}
+/**
+* Unwraps Zod wrapper types (optional, default, etc.) to get the inner type.
+*
+* @param field - The Zod type to unwrap
+* @returns The unwrapped inner type
+*/
+function unwrapZodSchema(field) {
+	const def = getZodDef(field);
+	if (field instanceof z$1.ZodDefault) {
+		const inner = def.innerType;
+		return inner ? unwrapZodSchema(inner) : field;
+	}
+	if (field instanceof z$1.ZodOptional) {
+		const inner = def.innerType;
+		return inner ? unwrapZodSchema(inner) : field;
+	}
+	if (field instanceof z$1.ZodNullable) {
+		const inner = def.innerType;
+		return inner ? unwrapZodSchema(inner) : field;
+	}
+	return field;
+}
+
 //#endregion
 //#region src/cli/options/options.builder.ts
 /**
@@ -305,15 +460,14 @@ var OptionsBuilder = class {
 		this.registerGenericOption(ctx);
 	}
 	/**
-	* Registers a number option with numeric parsing.
+	* Registers a number option with numeric parsing and validation.
 	*
 	* @param ctx - The option context
 	*/
 	registerNumberOption(ctx) {
 		const { command, rawField, optionFlag, optionName, description, parsedDefault } = ctx;
-		const parser = this.createNumberParser(rawField, optionName);
-		const wrappedParser = this.wrapParser(parser);
-		command.option(`${optionFlag} <${optionName}>`, description, wrappedParser, parsedDefault);
+		const validator = createNumberValidator(rawField, optionName);
+		command.option(`${optionFlag} <${optionName}>`, description, validator, parsedDefault);
 	}
 	/**
 	* Registers an enum option with choice validation.
@@ -321,111 +475,46 @@ var OptionsBuilder = class {
 	* @param ctx - The option context
 	*/
 	registerEnumOption(ctx) {
-		const { command, rawField, field, optionFlag, optionName, description, parsedDefault } = ctx;
-		const choices = this.getEnumChoices(field);
-		const parser = this.createEnumParser(rawField, optionName, choices);
-		const wrappedParser = this.wrapParser(parser);
+		const { command, rawField, optionFlag, optionName, description, parsedDefault } = ctx;
+		const choices = extractEnumValues(rawField) ?? [];
+		const validator = createEnumValidator(rawField, optionName, choices);
 		const fullDescription = `${description}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}`;
-		command.option(`${optionFlag} <${optionName}>`, fullDescription, wrappedParser, parsedDefault);
+		command.option(`${optionFlag} <${optionName}>`, fullDescription, validator, parsedDefault);
 	}
 	/**
-	*  Registers a string option with validation.
+	* Registers a string option with validation.
 	*
 	* @param ctx - The option context
 	*/
 	registerStringOption(ctx) {
 		const { command, rawField, optionFlag, optionName, description, parsedDefault } = ctx;
-		const parser = this.createStringParser(rawField);
-		const wrappedParser = this.wrapParser(parser);
-		command.option(`${optionFlag} <${optionName}>`, description, wrappedParser, parsedDefault);
+		const validator = createStringValidator(rawField, optionName);
+		command.option(`${optionFlag} <${optionName}>`, description, validator, parsedDefault);
 	}
 	/**
 	* Registers a generic option for other Zod types.
+	* Handles union types with literal values specially for better error messages.
 	*
 	* @param ctx - The option context
 	*/
 	registerGenericOption(ctx) {
 		const { command, rawField, optionFlag, optionName, description, parsedDefault } = ctx;
-		const parser = this.createGenericParser(rawField);
-		const wrappedParser = this.wrapParser(parser);
-		command.option(`${optionFlag} <${optionName}>`, description, wrappedParser, parsedDefault);
-	}
-	/**
-	* Wraps a Result-returning parser into a Commander-compatible parser.
-	*
-	* Commander expects parsers to return values directly or throw on error.
-	* This wrapper converts our Result-based parsers to that pattern.
-	*
-	* @param parser - The Result-based parser function
-	* @returns A Commander-compatible parser function
-	*/
-	wrapParser(parser) {
-		return (input) => {
-			const result = parser(input);
-			if (result.isErr()) throw new Error(result.error);
-			return result.value;
-		};
-	}
-	/**
-	* Creates a parser for number options.
-	*
-	* @template T - The expected return type
-	* @param rawField - The raw Zod field
-	* @param optionName - The option name for error messages
-	* @returns A parser function that converts strings to numbers with validation
-	*/
-	createNumberParser(rawField, optionName) {
-		return (input) => {
-			const num = Number(input);
-			if (Number.isNaN(num)) return err(`Invalid number for --${optionName}: ${input}`);
-			const result = parseSchema(rawField, num);
-			if (result.isErr()) return err(result.error.message);
-			return ok(result.value);
-		};
-	}
-	/**
-	* Creates a parser for enum options.
-	*
-	* @template T - The expected return type
-	* @param rawField - The raw Zod field
-	* @param optionName - The option name for error messages
-	* @param choices - The valid enum choices
-	* @returns A parser function that validates input against the enum choices
-	*/
-	createEnumParser(rawField, optionName, choices) {
-		return (input) => {
-			const result = parseSchema(rawField, input);
-			if (result.isErr()) return err(`Invalid value for --${optionName}: ${input}. Allowed: ${choices.join(", ")}`);
-			return ok(result.value);
-		};
-	}
-	/**
-	* Creates a parser for string options.
-	*
-	* @template T - The expected return type
-	* @param rawField - The raw Zod field
-	* @returns A parser function that validates input against the schema
-	*/
-	createStringParser(rawField) {
-		return (input) => {
-			const result = parseSchema(rawField, input);
-			if (result.isErr()) return err(result.error.message);
-			return ok(result.value);
-		};
-	}
-	/**
-	* Creates a generic parser using Zod validation.
-	*
-	* @template T - The expected return type
-	* @param rawField - The raw Zod field
-	* @returns A parser function that validates input against the schema
-	*/
-	createGenericParser(rawField) {
-		return (input) => {
-			const result = parseSchema(rawField, input);
-			if (result.isErr()) return err(result.error.message);
-			return ok(result.value);
-		};
+		const literalValues = extractLiteralValues(rawField);
+		if (literalValues) {
+			const validator$1 = createLiteralUnionValidator(rawField, optionName, literalValues);
+			const fullDescription = `${description} (choices: ${literalValues.map((v) => typeof v === "string" ? v : String(v)).join(", ")})`;
+			command.option(`${optionFlag} <${optionName}>`, fullDescription, validator$1, parsedDefault);
+			return;
+		}
+		const enumValues = extractEnumValues(rawField);
+		if (enumValues) {
+			const validator$1 = createEnumValidator(rawField, optionName, enumValues);
+			const fullDescription = `${description} (choices: ${enumValues.join(", ")})`;
+			command.option(`${optionFlag} <${optionName}>`, fullDescription, validator$1, parsedDefault);
+			return;
+		}
+		const validator = createGenericValidator(rawField, optionName);
+		command.option(`${optionFlag} <${optionName}>`, description, validator, parsedDefault);
 	}
 	/**
 	* Gets the internal definition object from a Zod type.
@@ -470,15 +559,6 @@ var OptionsBuilder = class {
 		const def = this.getInternalDef(rawField);
 		return (def.innerType ?? def.schema) instanceof z$1.ZodBoolean;
 	}
-	/**
-	* Extracts enum choices from a ZodEnum field.
-	*
-	* @param field - The ZodEnum field
-	* @returns The array of valid enum choices
-	*/
-	getEnumChoices(field) {
-		return this.getInternalDef(field).values ?? [];
-	}
 };
 
 //#endregion
@@ -805,10 +885,63 @@ var TaskBuilder = class TaskBuilder {
 
 //#endregion
 //#region src/commands/release/tasks/bump-release-version.task.ts
+const PACKAGE_JSON_FILE$1 = "package.json";
+/**
+* Updates the configured package.json with the next version.
+*
+* @param ctx - The current release context
+* @returns A FireflyAsyncResult resolving to the release context after update
+*/
+function updatePackageJsonVersion(ctx) {
+	return ctx.services.packageJson.updateVersion(PACKAGE_JSON_FILE$1, ctx.data.nextVersion).map(() => ctx);
+}
+/**
+* Restores a previous version value in the configured package.json.
+*
+* @param ctx - The current release context
+* @param previousVersion - The previous version string to restore
+* @returns A FireflyAsyncResult resolving to the release context after restore
+*/
+function restorePackageJsonVersion(ctx, previousVersion) {
+	return ctx.services.packageJson.updateVersion(PACKAGE_JSON_FILE$1, previousVersion).map(() => ctx);
+}
+/**
+* Validates that the release context contains a next version value.
+*
+* @param ctx - The current release context
+* @returns A FireflyResult with the next version or a validation error
+*/
+function parseNextVersion(ctx) {
+	const nextVersion = ctx.data.nextVersion;
+	if (!nextVersion) return validationErr({ message: "Next version is undefined" });
+	return FireflyOk(nextVersion);
+}
+/**
+* Creates the Bump Release Version task.
+*
+* This task updates the version of the project to the next version determined
+* by earlier steps. Specifically, it:
+* 1. Validates that a `nextVersion` exists in the release context
+* 2. Writes the `nextVersion` into the configured package.json file
+* 3. Provides an undo operation that restores the original version
+*/
 function createBumpReleaseVersion() {
-	return TaskBuilder.create("bump-release-version").description("Applies the new version bump to relevant files").dependsOnAll("straight-version-bump", "determine-automatic-bump", "prompt-manual-version", "prompt-bump-strategy").skipWhenWithReason((ctx) => ctx.config.skipBump, "Skipped: skipBump is enabled").execute((ctx) => {
-		logger.info("bump-release-version");
-		return FireflyOkAsync(ctx);
+	/**
+	* Holds the previous version before bumping, for undo purposes if needed.
+	*/
+	let previousVersion;
+	return TaskBuilder.create("bump-release-version").description("Applies the new version bump to relevant files").dependsOnAll("straight-version-bump", "determine-automatic-bump", "prompt-manual-version", "prompt-bump-strategy").skipWhenWithReason((ctx) => ctx.config.skipBump || !ctx.data.nextVersion, "Skipped: skipBump is enabled or next version is not set").execute((ctx) => {
+		previousVersion = ctx.data.currentVersion;
+		const nextVersionRes = parseNextVersion(ctx);
+		if (nextVersionRes.isErr()) return FireflyErrAsync(nextVersionRes.error);
+		logger.info(`Next version to be released: ${colors.green(nextVersionRes.value)}`);
+		return updatePackageJsonVersion(ctx).andTee(() => logger.success("package.json version updated successfully."));
+	}).withUndo((ctx) => {
+		if (!previousVersion) {
+			logger.verbose("BumpReleaseVersionTask: Previous version is undefined, skipping undo operation.");
+			return FireflyOkAsync(void 0);
+		}
+		return restorePackageJsonVersion(ctx, previousVersion).map(() => void 0);
 	}).build();
 }
 
@@ -1029,22 +1162,60 @@ function createDelegateBumpStrategyTask() {
 			shouldSkip,
 			reason: shouldSkip ? getSkipReason(ctx) : void 0
 		});
-	}).execute((ctx) => {
-		logger.info("delegate-bump-strategy");
-		return FireflyOkAsync(ctx);
-	}).build();
+	}).execute((ctx) => FireflyOkAsync(ctx)).build();
 }
 
 //#endregion
 //#region src/commands/release/tasks/determine-automatic-bump.task.ts
+/**
+* Parses the current version from a raw string.
+*
+* @param currentVersionRaw - The raw string representing the current version
+* @returns A FireflyResult containing the parsed Version or a validation error
+*/
+function parseCurrentVersion$2(currentVersionRaw) {
+	if (!currentVersionRaw) return validationErr({ message: "Current version is undefined" });
+	return Version.from(currentVersionRaw);
+}
+/**
+* Logs the analysis recommendation with formatting.
+*
+* @param reason - The reason string from the recommendation
+*/
+function logRecommendation(reason) {
+	if (!reason) return;
+	if (reason.startsWith("Analysis found:")) {
+		const prefix = "Analysis found:";
+		const details = reason.slice(15).trim();
+		logger.info(`${prefix} ${colors.green(details)}`);
+	} else logger.info(reason);
+}
+/**
+* Performs the automatic bump by analyzing commits and resolving version strategy.
+*/
+function executeAutomaticBump(ctx) {
+	const currentVersionResult = parseCurrentVersion$2(ctx.data.currentVersion);
+	if (currentVersionResult.isErr()) return FireflyErrAsync(currentVersionResult.error);
+	const currentVersion = currentVersionResult.value;
+	return ctx.services.commitAnalysis.analyzeForVersion().andThen((recommendation) => {
+		logRecommendation(recommendation.reason);
+		const options = {
+			currentVersion,
+			preReleaseId: ctx.config.preReleaseId,
+			preReleaseBase: ctx.config.preReleaseBase
+		};
+		return ctx.services.versionStrategy.resolveVersion(options, recommendation);
+	}).andThen((newVersion) => {
+		const from = ctx.data.currentVersion || "unknown";
+		logger.info(`Determined version: ${colors.green(from)} -> ${colors.green(newVersion.raw)}`);
+		return FireflyOkAsync(ctx.fork("nextVersion", newVersion.toString()));
+	});
+}
 function createDetermineAutomaticBump() {
 	return TaskBuilder.create("determine-automatic-bump").description("Automatically determines the version bump from commit messages").dependsOn("delegate-bump-strategy").skipWhenWithReason((ctx) => {
 		const bumpStrategy = ctx.data.selectedBumpStrategy ?? ctx.config.bumpStrategy;
 		return ctx.config.skipBump || bumpStrategy !== BUMP_STRATEGY_AUTO;
-	}, "Skipped: skipBump enabled or bumpStrategy is not 'auto'").execute((ctx) => {
-		logger.info("determine-automatic-bump");
-		return FireflyOkAsync(ctx);
-	}).build();
+	}, "Skipped: skipBump enabled or bumpStrategy is not 'auto'").execute((ctx) => executeAutomaticBump(ctx)).build();
 }
 
 //#endregion
@@ -1091,29 +1262,108 @@ function promptBumpStrategy() {
 		return FireflyOkAsync(selected);
 	});
 }
+/**
+* Creates the Prompt Bump Strategy Task.
+*
+* This task prompts the user to select a version bump strategy (automatic or manual) and
+* stores it in the release context. It depends on `initialize-release-version` and will be
+* skipped when `skipBump` is enabled or a `bumpStrategy`/`releaseType` is already provided.
+*
+* This task:
+* 1. Prompts the user to select a bump strategy
+*/
 function createPromptBumpStrategyTask() {
 	return TaskBuilder.create("prompt-bump-strategy").description("Prompts the user for a version bump strategy").dependsOn("initialize-release-version").skipWhenWithReason((ctx) => ctx.config.skipBump || Boolean(ctx.config.bumpStrategy) || Boolean(ctx.config.releaseType), "Skipped: skipBump enabled, or bumpStrategy/releaseType already specified").execute((ctx) => promptBumpStrategy().andThen((strategy) => FireflyOkAsync(ctx.fork("selectedBumpStrategy", strategy)))).build();
 }
 
 //#endregion
 //#region src/commands/release/tasks/prompt-manual-bump.task.ts
+/**
+* Parses the current version from a raw string.
+*
+* @param currentVersionRaw - The raw string representing the current version
+* @returns A FireflyResult containing the parsed Version or a validation error
+*/
+function parseCurrentVersion$1(currentVersionRaw) {
+	if (!currentVersionRaw) return validationErr({ message: "Current version is undefined" });
+	return Version.from(currentVersionRaw);
+}
+/**
+* Generates version choices and prompts the user to select one.
+*/
+function promptForManualVersion(ctx) {
+	const currentVersionResult = parseCurrentVersion$1(ctx.data.currentVersion);
+	if (currentVersionResult.isErr()) return FireflyErrAsync(currentVersionResult.error);
+	const currentVersion = currentVersionResult.value;
+	logger.verbose("PromptManualVersionTask: Generating version choices...");
+	return ctx.services.versionStrategy.generateChoices({
+		currentVersion,
+		preReleaseId: ctx.config.preReleaseId,
+		preReleaseBase: ctx.config.preReleaseBase
+	}).andThen((choices) => {
+		if (!choices || choices.length === 0) return validationErrAsync({ message: "No version choices available" });
+		logger.verbose(`PromptManualVersionTask: Generated ${choices.length} version choices.`);
+		const defaultChoice = choices[0];
+		return wrapPromise(logger.prompt("Select version to release", {
+			type: "select",
+			options: choices,
+			initial: defaultChoice?.value,
+			cancel: "undefined"
+		})).andThen((selected) => {
+			if (!selected || selected === "") return failedErrAsync({ message: "Operation cancelled by user" });
+			if (logger.level === LogLevels.verbose) logger.log("");
+			if (logger.level !== LogLevels.verbose) logger.log("");
+			logger.verbose(`PromptManualVersionTask: Selected version: '${selected}'`);
+			return FireflyOkAsync(selected);
+		});
+	});
+}
 function createPromptManualVersionTask() {
-	return TaskBuilder.create("prompt-manual-version").description("Prompts the user for a manual version bump selections").dependsOn("delegate-bump-strategy").skipWhenWithReason((ctx) => {
+	return TaskBuilder.create("prompt-manual-version").description("Prompts the user to manually select the next version").dependsOn("delegate-bump-strategy").skipWhenWithReason((ctx) => {
 		const bumpStrategy = ctx.data.selectedBumpStrategy ?? ctx.config.bumpStrategy;
 		return ctx.config.skipBump || bumpStrategy !== BUMP_STRATEGY_MANUAL;
-	}, "Skipped: skipBump enabled or bumpStrategy is not 'manual'").execute((ctx) => {
-		logger.info("prompt-manual-version");
-		return FireflyOkAsync(ctx);
-	}).build();
+	}, "Skipped: skipBump enabled or bumpStrategy is not 'manual'").execute((ctx) => promptForManualVersion(ctx).andThen((selectedVersion) => FireflyOkAsync(ctx.fork("nextVersion", selectedVersion)))).build();
 }
 
 //#endregion
 //#region src/commands/release/tasks/straight-version-bump.task.ts
+/**
+* Parses the current version from a raw string.
+*
+* @param currentVersionRaw - The raw string representing the current version
+* @returns A FireflyResult containing the parsed Version or a validation error
+*/
+function parseCurrentVersion(currentVersionRaw) {
+	if (!currentVersionRaw) return validationErr({ message: "Current version is undefined" });
+	return Version.from(currentVersionRaw);
+}
+/**
+* Builds the bump options from the release context.
+*/
+function buildBumpOptionsFromContext(ctx) {
+	const currentVersionResult = parseCurrentVersion(ctx.data.currentVersion);
+	if (currentVersionResult.isErr()) return FireflyErrAsync(currentVersionResult.error);
+	const releaseType = ctx.config.releaseType;
+	if (releaseType === void 0) return invalidErrAsync({ message: "Release type is required for straight bump" });
+	return FireflyOkAsync({
+		currentVersion: currentVersionResult.value,
+		releaseType,
+		preReleaseId: ctx.config.preReleaseId,
+		preReleaseBase: ctx.config.preReleaseBase
+	});
+}
+/**
+* Performs the straight bump by delegating to the version bumper service.
+*/
+function executeStraightVersionBump(ctx) {
+	return buildBumpOptionsFromContext(ctx).andThen((options) => ctx.services.versionBumper.bump(options)).andThen((newVersion) => {
+		const from = ctx.data.currentVersion || "unknown";
+		logger.info(`Bumped version: ${colors.green(from)} -> ${colors.green(newVersion.raw)}`);
+		return FireflyOkAsync(ctx.fork("nextVersion", newVersion.toString()));
+	});
+}
 function createStraightVersionBump() {
-	return TaskBuilder.create("straight-version-bump").description("Performs a direct version bump based on the configured release type").dependsOn("initialize-release-version").skipWhenWithReason((ctx) => ctx.config.skipBump || ctx.config.releaseType === void 0, "Skipped: skipBump is enabled or no release type specified").execute((ctx) => {
-		logger.info("straight-version-bump");
-		return FireflyOkAsync(ctx);
-	}).build();
+	return TaskBuilder.create("straight-version-bump").description("Performs a direct version bump based on the configured release type").dependsOn("initialize-release-version").skipWhenWithReason((ctx) => ctx.config.skipBump || ctx.config.releaseType === void 0, "Skipped: skipBump is enabled or no release type specified").execute((ctx) => executeStraightVersionBump(ctx)).build();
 }
 
 //#endregion
@@ -1167,7 +1417,7 @@ function getVersionFromPackageJson(ctx) {
 */
 function createInitializeReleaseVersion() {
 	return TaskBuilder.create("initialize-release-version").description("Initialize current release version from package.json").dependsOn("prepare-release-config").execute((ctx) => getVersionFromPackageJson(ctx).andThen((currentVersion) => {
-		logger.info(`Current version is ${currentVersion}`);
+		logger.info(`Current version is ${colors.green(currentVersion)}`);
 		return FireflyOkAsync(ctx.fork("currentVersion", currentVersion));
 	})).build();
 }
@@ -1280,7 +1530,7 @@ function hydrateScopeFromPackageJson(ctx, packageJson) {
 * 3. Otherwise the function defaults to "alpha".
 */
 function hydratePreReleaseIdFromPackageJson(ctx, packageJson) {
-	if (ctx.config.preReleaseId !== void 0 && ctx.config.preReleaseId.trim() !== "") {
+	if (Object.hasOwn(ctx.config, "preReleaseId") && ctx.config.preReleaseId !== void 0) {
 		logger.verbose(`PrepareReleaseConfigTask: Using provided preReleaseId: "${ctx.config.preReleaseId}" as it is explicitly set`);
 		return FireflyOkAsync(ctx.config.preReleaseId);
 	}
@@ -1297,26 +1547,47 @@ function hydratePreReleaseIdFromPackageJson(ctx, packageJson) {
 	return FireflyOkAsync("alpha");
 }
 /**
+* Hydrates the `preReleaseBase` field.
+*
+* Behavior:
+* - If explicitly provided in config (key exists and value is not undefined) use as-is.
+* - Otherwise default to 0.
+*
+* Note: we do NOT infer `preReleaseBase` from package.json anymore.
+*/
+function hydratePreReleaseBase(ctx) {
+	const baseMaybe = ctx.config.preReleaseBase;
+	if (Object.hasOwn(ctx.config, "preReleaseBase") && baseMaybe !== void 0) {
+		logger.verbose(`PrepareReleaseConfigTask: Using provided preReleaseBase: "${ctx.config.preReleaseBase}" as it is explicitly set`);
+		return FireflyOkAsync(baseMaybe);
+	}
+	logger.verbose("PrepareReleaseConfigTask: No preReleaseBase explicitly provided, defaulting to 0");
+	return FireflyOkAsync(0);
+}
+/**
 * Hydrates name, scope, and preReleaseId from package.json.
 *
 * Behavior:
 * - If package.json does not exist, returns all values as undefined.
 * - If it exists, reads package.json and returns parsed results for name, scope and preReleaseId.
+* - If preReleaseBase is explicitly provided in config, it is used as-is, if not, it defaults to 0.
 */
 function hydrateFromPackageJson(ctx) {
 	return ctx.services.fs.exists("package.json").andThen((exists) => {
 		if (!exists) return FireflyOkAsync({
 			name: void 0,
 			scope: void 0,
-			preReleaseId: void 0
+			preReleaseId: void 0,
+			preReleaseBase: void 0
 		});
-		return ctx.services.packageJson.read("package.json").andThen((pkg) => hydrateNameFromPackageJson(ctx, pkg).andThen((name) => hydrateScopeFromPackageJson(ctx, pkg).andThen((scope) => hydratePreReleaseIdFromPackageJson(ctx, pkg).map((preReleaseId) => {
+		return ctx.services.packageJson.read("package.json").andThen((pkg) => hydrateNameFromPackageJson(ctx, pkg).andThen((name) => hydrateScopeFromPackageJson(ctx, pkg).andThen((scope) => hydratePreReleaseIdFromPackageJson(ctx, pkg).andThen((preReleaseId) => hydratePreReleaseBase(ctx).map((preReleaseBase) => {
 			const result = {};
 			if (name) result.name = name;
 			if (scope) result.scope = scope;
 			if (preReleaseId) result.preReleaseId = preReleaseId;
+			if (preReleaseBase !== void 0) result.preReleaseBase = preReleaseBase;
 			return result;
-		}))));
+		})))));
 	});
 }
 /**
@@ -1447,12 +1718,13 @@ function createPrepareReleaseConfigTask() {
 			if (pkgData.name) hydrated.name = pkgData.name;
 			if (pkgData.scope) hydrated.scope = pkgData.scope;
 			if (pkgData.preReleaseId) hydrated.preReleaseId = pkgData.preReleaseId;
+			if (pkgData.preReleaseBase !== void 0) hydrated.preReleaseBase = pkgData.preReleaseBase;
 			return hydrateReleaseFlags(ctx);
 		}).map((releaseFlags) => {
 			hydrated.releaseLatest = releaseFlags.releaseLatest;
 			hydrated.releasePreRelease = releaseFlags.releasePreRelease;
 			hydrated.releaseDraft = releaseFlags.releaseDraft;
-			return ctx.fork("hydratedConfig", hydrated);
+			return ctx.forkConfig(hydrated);
 		});
 	}).build();
 }
@@ -1662,17 +1934,23 @@ function validateSkipFlagCombinations(ctx) {
 		input: ctx.value
 	});
 }
-const ReleaseConfigSchema = z$1.object({
+/**
+* Base release configuration schema without refinements.
+* Use this schema for JSON schema generation and `.partial()` operations.
+* Zod v4 does not allow `.partial()` on schemas with refinements.
+*/
+const ReleaseConfigBaseSchema = z$1.object({
 	name: z$1.string().optional().describe("Unscoped project name. Auto-detected from package.json."),
 	scope: z$1.string().optional().describe("Org/user scope without '@'. Auto-detected from package.json."),
-	base: z$1.string().default("").describe("Relative path from repository root to project root."),
+	repository: z$1.string().optional().describe("GitHub repository in 'owner/repo' format."),
+	base: z$1.string().optional().describe("Relative path from repository root to project root."),
 	branch: z$1.string().optional().describe("Git branch to release from."),
 	changelogPath: z$1.string().default("CHANGELOG.md").describe("Changelog file path, relative to project root."),
 	bumpStrategy: BumpStrategySchema.describe("\"auto\" (from commits) or \"manual\" (user-specified)."),
 	releaseType: ReleaseTypeSchema.optional().describe("The release type to bump."),
 	preReleaseId: z$1.string().optional().describe("Pre-release ID (e.g., \"alpha\", \"beta\")."),
 	preReleaseBase: PreReleaseBaseSchema.describe("Starting version for pre-releases."),
-	releaseNotes: z$1.string().default("").describe("Custom release notes for changelog."),
+	releaseNotes: z$1.string().optional().describe("Custom release notes for changelog."),
 	commitMessage: z$1.string().default(COMMIT_MSG_TEMPLATE).describe("Commit message template with placeholders."),
 	tagName: z$1.string().default(TAG_NAME_TEMPLATE).describe("Tag name template with placeholders."),
 	skipBump: z$1.coerce.boolean().default(false).describe("Skip version bump step."),
@@ -1685,7 +1963,12 @@ const ReleaseConfigSchema = z$1.object({
 	releaseLatest: z$1.coerce.boolean().optional().describe("Mark as latest release."),
 	releasePreRelease: z$1.coerce.boolean().optional().describe("Mark as pre-release."),
 	releaseDraft: z$1.coerce.boolean().optional().describe("Release as draft version.")
-}).check((ctx) => {
+});
+/**
+* Release configuration schema with runtime validation refinements.
+* Use this schema for parsing and validating user input.
+*/
+const ReleaseConfigSchema = ReleaseConfigBaseSchema.check((ctx) => {
 	validateReleaseFlagExclusivity(ctx);
 	validateSkipGitRedundancy(ctx);
 	validateBumpStrategyCompatibility(ctx);
@@ -1738,30 +2021,30 @@ function defineService(definition) {
 */
 const SERVICE_DEFINITIONS = {
 	fs: defineService({ factory: async ({ basePath }) => {
-		const { createFileSystemService } = await import("./filesystem.service-B8qg87n-.js");
+		const { createFileSystemService } = await import("./filesystem.service-DS2AQGNq.js");
 		return createFileSystemService(basePath);
 	} }),
 	packageJson: defineService({
 		dependencies: ["fs"],
 		factory: async ({ getService }) => {
 			const fs = await getService("fs");
-			const { createPackageJsonService } = await import("./package-json.service-CHmtIoQQ.js");
+			const { createPackageJsonService } = await import("./package-json.service-BlMNgPGQ.js");
 			return createPackageJsonService(fs);
 		}
 	}),
 	git: defineService({ factory: async ({ basePath }) => {
-		const { createGitService } = await import("./git.service-BBqDH7qx.js");
+		const { createGitService } = await import("./git.service-B6RdTilO.js");
 		return createGitService(basePath);
 	} }),
 	versionBumper: defineService({ factory: async () => {
-		const { createVersionBumperService } = await import("./version-bumper.service-DMYR0npB.js");
+		const { createVersionBumperService } = await import("./version-bumper.service-glxzf9Qm.js");
 		return createVersionBumperService();
 	} }),
 	versionStrategy: defineService({
 		dependencies: ["versionBumper"],
 		factory: async ({ getService }) => {
 			const versionBumper = await getService("versionBumper");
-			const { createVersionStrategyService } = await import("./version-strategy.service-CmfeZLYC.js");
+			const { createVersionStrategyService } = await import("./version-strategy.service-Dln42gxC.js");
 			return createVersionStrategyService(versionBumper);
 		}
 	}),
@@ -1769,7 +2052,7 @@ const SERVICE_DEFINITIONS = {
 		dependencies: ["git"],
 		factory: async ({ getService }) => {
 			const git = await getService("git");
-			const { createCommitAnalysisService } = await import("./commit-analysis.service-Ba6hLgsr.js");
+			const { createCommitAnalysisService } = await import("./commit-analysis.service-B2Z128t8.js");
 			return createCommitAnalysisService(git);
 		}
 	})
@@ -2033,7 +2316,7 @@ function logGraphStatistics(stats) {
 
 //#endregion
 //#region src/commands/release/release.command.ts
-const RELEASE_SERVICES = defineServiceKeys("fs", "packageJson", "git");
+const RELEASE_SERVICES = defineServiceKeys("fs", "packageJson", "git", "commitAnalysis", "versionBumper", "versionStrategy");
 const releaseCommand = createCommand({
 	meta: {
 		name: "release",
@@ -2353,6 +2636,30 @@ var ImmutableWorkflowContext = class ImmutableWorkflowContext {
 			services: this.services
 		});
 	}
+	/**
+	* @example Merging hydrated config values
+	* ```typescript
+	* const updatedCtx = ctx.forkConfig({
+	*   repository: "owner/repo",
+	*   branch: "main"
+	* });
+	* ```
+	*/
+	forkConfig(updates) {
+		if (Object.keys(updates).length === 0) return this;
+		const mergedConfig = {
+			...this.config,
+			...updates
+		};
+		const frozenConfig = Object.freeze(mergedConfig);
+		return new ImmutableWorkflowContext({
+			startTime: this.startTime,
+			workspace: this.workspace,
+			config: frozenConfig,
+			data: this.#data,
+			services: this.services
+		});
+	}
 	has(key) {
 		return key in this.#data;
 	}
@@ -3191,6 +3498,18 @@ async function resolveServiceWithContext(key, context) {
 /**
 * Creates a lazy proxy that defers async service instantiation until first access.
 *
+* IMPORTANT:
+* This proxy always defers instantiation and wraps calls in a ResultAsync chain
+* in order to safely await the real service instance before invoking the method.
+*
+* At runtime the proxy therefore returns ResultAsync even if the concrete service
+* method returns a synchronous Result.
+*
+* Because of this behavior, service interfaces should return FireflyAsyncResult<T>
+* from their public methods to avoid type mismatches and confusion. Implementations
+* that have purely synchronous behavior should return FireflyOkAsync / FireflyErrAsync
+* so they still conform to the async contract expected by the proxy.
+*
 * @template T - The service interface type
 * @param factory - Async function that creates the actual service instance
 * @returns A proxy that behaves like the service but instantiates lazily