fireflyy 3.0.11 → 4.0.0-dev.fd79cb3

package/dist/program-DSPj4l5A.js

@@ -0,0 +1,3457 @@
+import { n as RuntimeEnv, t as logger } from "./main.js";
+import { _ as validationError, a as conflictErrAsync, c as notFoundErrAsync, d as validationErrAsync, f as conflictError, h as notFoundError, i as FireflyOkAsync, l as timeoutErrAsync, m as failedError, n as FireflyErrAsync, r as FireflyOk, s as invalidErr, t as FireflyErr, u as validationErr, v as wrapErrorMessage } from "./result.constructors-C9M1MP3_.js";
+import { n as wrapPromise, r as zip3Async, t as ensureNotAsync } from "./result.utilities-B03Jkhlx.js";
+import { n as parseSchema, t as formatZodErrors } from "./schema.utilities-BGd9t1wm.js";
+import { LogLevels } from "consola";
+import { colors } from "consola/utils";
+import { Command } from "commander";
+import { loadConfig } from "c12";
+import { Result, ResultAsync, err, ok } from "neverthrow";
+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.
+*
+* Supports multiple config file formats:
+* - .js, .ts, .mjs, .cjs, .mts, .cts .json, .jsonrc, .json5, .yaml, .yml, .toml
+*
+* Configuration is merged in the following order (later overrides earlier):
+* 1. Default values from schemas
+* 2. Config file values
+* 3. CLI option overrides (handled by commander.ts)
+*
+* @example
+* ```ts
+* const loader = new ConfigLoader({
+*     commandName: "release",
+*     configFile: "./custom.config.ts",
+* });
+*
+* const configResult = await loader.load();
+* if (configResult.isOk()) {
+*     console.log(configResult.value);
+* }
+* ```
+*/
+var ConfigLoader = class {
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/**
+	* Loads and validates the configuration.
+	*
+	* @returns Async result containing the merged configuration or an error
+	*/
+	load() {
+		const { cwd = process.cwd(), configFile } = this.options;
+		return wrapPromise(loadConfig({
+			name: "firefly",
+			cwd,
+			configFile: configFile || "firefly.config",
+			packageJson: false
+		})).andThen((result) => {
+			this.logConfigFile(result.configFile);
+			if (DebugFlags.showFileConfig) logger.verbose(JSON.stringify(result.config, null, 2));
+			return FireflyOkAsync(this.extractCommandConfig(result.config ?? {}));
+		});
+	}
+	logConfigFile(configFile) {
+		if (configFile && configFile !== "firefly.config") logger.info(`Using firefly config: ${colors.underline(configFile)}`);
+	}
+	/**
+	* Extracts command-specific configuration from the full config.
+	*
+	* If a commandName is specified, this merges the command's nested config
+	* (e.g., `release: { ... }`) with the root config.
+	*
+	* @param config - The full runtime configuration
+	* @returns The extracted and merged configuration
+	*/
+	extractCommandConfig(config) {
+		const commandName = this.options.commandName;
+		if (!commandName) return config;
+		const commandSpecificConfig = config[commandName];
+		if (!(commandSpecificConfig && typeof commandSpecificConfig === "object")) return config;
+		const baseConfig = { ...config };
+		delete baseConfig[commandName];
+		return {
+			...baseConfig,
+			...commandSpecificConfig
+		};
+	}
+};
+
+//#endregion
+//#region src/cli/options/options.utilities.ts
+/**
+* Compound words that should be treated as single units in kebab-case.
+* These are typically brand names or technical terms that shouldn't be split.
+*/
+const COMPOUND_WORDS = [
+	"GitHub",
+	"GitLab",
+	"BitBucket"
+];
+/**
+* Converts a camelCase string to kebab-case.
+*
+* Handles compound words (e.g., "GitHub", "GitLab") as single units
+* to ensure consistent CLI flag naming.
+*
+* @param str - The camelCase string to convert
+* @returns The kebab-case equivalent
+*
+* @example
+* ```ts
+* camelToKebab("bumpStrategy") // "bump-strategy"
+* camelToKebab("skipGitHubRelease") // "skip-github-release"
+* camelToKebab("skipGitLabRelease") // "skip-gitlab-release"
+* ```
+*/
+function camelToKebab(str) {
+	let result = str;
+	for (const word of COMPOUND_WORDS) {
+		result = result.replace(new RegExp(`([a-z])${word}`, "g"), `$1-${word.toLowerCase()}`);
+		result = result.replace(new RegExp(`^${word}`, "g"), word.toLowerCase());
+	}
+	return result.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/_/g, "-");
+}
+
+//#endregion
+//#region src/cli/options/options.builder.ts
+/**
+* Builds and registers Commander.js CLI options from Zod schemas.
+*
+* Automatically converts Zod schema definitions into Commander options with:
+* - Appropriate type parsing (string, number, enum, boolean)
+* - Default value extraction
+* - Description from schema metadata
+* - Shorthand aliases for common options
+*
+* @example
+* ```ts
+* const builder = new OptionsBuilder();
+* builder.registerGlobalOptions(program);
+* builder.registerCommandOptions(releaseCmd, ReleaseConfigSchema);
+* ```
+*/
+var OptionsBuilder = class {
+	/**
+	* Mapping of schema keys to their shorthand CLI flags.
+	*/
+	shorthandMap = new Map([["bumpStrategy", "bt"], ["releaseType", "rt"]]);
+	/**
+	* Fields that are handled by global options and should be skipped for command options.
+	*/
+	skipFields = new Set([
+		"cwd",
+		"dryRun",
+		"verbose",
+		"enableRollback"
+	]);
+	/**
+	* Registers global options that apply to all commands.
+	*
+	* @param program - The root Commander program instance
+	*/
+	registerGlobalOptions(program) {
+		program.option("-C, --cwd <path>", "The working directory for all operations").option("--dry-run", "Run without making actual changes").option("--verbose", "Enable verbose logging").option("--no-enable-rollback", "Disable automatic rollback on failure");
+	}
+	/**
+	* Registers command-specific options from a Zod schema.
+	*
+	* Iterates through the schema shape and creates Commander options
+	* for each field, skipping global options.
+	*
+	* @param command - The Commander command to register options on
+	* @param schema - The Zod schema defining the command's options
+	*/
+	registerCommandOptions(command, schema) {
+		for (const [key, rawField] of Object.entries(schema.shape)) {
+			if (!rawField || this.skipFields.has(key)) continue;
+			const ctx = this.buildOptionContext(command, key, rawField);
+			if (ctx) this.registerOption(ctx);
+		}
+	}
+	/**
+	* Builds the context object for registering a single option.
+	*
+	* @param command - The Commander command
+	* @param key - The schema key
+	* @param rawField - The raw Zod field
+	* @returns The option context, or null if the option already exists
+	*/
+	buildOptionContext(command, key, rawField) {
+		const field = this.unwrapSchema(rawField);
+		const optionName = camelToKebab(key);
+		const shorthand = this.shorthandMap.get(key);
+		const shorthandPrefix = shorthand && shorthand.length === 1 ? "-" : "--";
+		const optionFlag = shorthand ? `${shorthandPrefix}${shorthand}, --${optionName}` : `--${optionName}`;
+		if (command.options.some((opt) => opt.long === `--${optionName}` || shorthand && opt.short === `${shorthandPrefix}${shorthand}`)) return null;
+		const parsedDefault = this.extractDefaultValue(key, rawField);
+		return {
+			command,
+			key,
+			rawField,
+			field,
+			optionFlag,
+			optionName,
+			description: rawField.description ?? "",
+			parsedDefault
+		};
+	}
+	/**
+	* Extracts the default value from a Zod field by parsing an empty object.
+	*
+	* @param key - The schema key
+	* @param rawField - The raw Zod field
+	* @returns The default value, or undefined if none
+	*/
+	extractDefaultValue(key, rawField) {
+		const parseResult = z$1.object({ [key]: rawField }).partial().safeParse({});
+		return parseResult.success ? parseResult.data[key] : void 0;
+	}
+	/**
+	* Registers a single option based on its type.
+	*
+	* @param ctx - The option context
+	*/
+	registerOption(ctx) {
+		const { command, rawField, field, optionFlag, description } = ctx;
+		if (this.isBooleanField(rawField)) {
+			command.option(optionFlag, description);
+			return;
+		}
+		if (field instanceof z$1.ZodNumber) {
+			this.registerNumberOption(ctx);
+			return;
+		}
+		if (field instanceof z$1.ZodEnum) {
+			this.registerEnumOption(ctx);
+			return;
+		}
+		if (field instanceof z$1.ZodString) {
+			this.registerStringOption(ctx);
+			return;
+		}
+		this.registerGenericOption(ctx);
+	}
+	/**
+	* Registers a number option with numeric parsing.
+	*
+	* @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);
+	}
+	/**
+	* Registers an enum option with choice validation.
+	*
+	* @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 fullDescription = `${description}${choices.length ? ` (choices: ${choices.join(", ")})` : ""}`;
+		command.option(`${optionFlag} <${optionName}>`, fullDescription, wrappedParser, parsedDefault);
+	}
+	/**
+	*  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);
+	}
+	/**
+	* Registers a generic option for other Zod types.
+	*
+	* @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);
+		};
+	}
+	/**
+	* Gets the internal definition object from a Zod type.
+	* Handles both modern Zod v4 (_zod.def) and legacy (_def) structures.
+	*
+	* @param field - The raw Zod field
+	* @returns The internal definition object
+	*/
+	getInternalDef(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 raw Zod field
+	* @returns The unwrapped Zod type
+	*/
+	unwrapSchema(field) {
+		if (field instanceof z$1.ZodDefault) {
+			const inner = this.getInternalDef(field).innerType;
+			return inner ? this.unwrapSchema(inner) : field;
+		}
+		if (field instanceof z$1.ZodOptional) {
+			const inner = this.getInternalDef(field).innerType;
+			return inner ? this.unwrapSchema(inner) : field;
+		}
+		if (field instanceof z$1.ZodUnknown) {
+			const schema = this.getInternalDef(field).schema;
+			return schema ? this.unwrapSchema(schema) : field;
+		}
+		return field;
+	}
+	/**
+	* Checks if a field is a boolean type (possibly wrapped).
+	*
+	* @param rawField - The raw Zod field
+	* @returns True if the field is boolean, false otherwise
+	*/
+	isBooleanField(rawField) {
+		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
+//#region src/cli/options/options.normalizer.ts
+/**
+* Normalizes CLI option names between Commander.js and Zod schema conventions.
+*
+* Commander.js converts kebab-case flags (e.g., `--dry-run`) to camelCase keys
+* in the parsed options object. However, the internal representation may differ
+* from the schema keys. This class ensures all option keys match the schema.
+*
+* @example
+* ```ts
+* const normalizer = new OptionsNormalizer();
+* const normalized = normalizer.normalize(cliOptions, ReleaseConfigSchema);
+* // Ensures all keys match the schema's camelCase keys
+* ```
+*/
+var OptionsNormalizer = class {
+	/**
+	* Normalizes parsed CLI options to match Zod schema keys.
+	*
+	* Converts any Commander-style keys to their corresponding schema keys.
+	* For example, if Commander produces `enableRollback` but the schema
+	* expects `enableRollback`, this ensures consistency.
+	*
+	* @param options - Raw options from Commander.js
+	* @param schema - The Zod schema defining expected option keys
+	* @returns Normalized options with keys matching the schema
+	*/
+	normalize(options, schema) {
+		const mappings = this.buildMappingFromSchema(schema);
+		const normalized = { ...options };
+		for (const [commanderKey, schemaKey] of mappings) if (commanderKey in normalized && !(schemaKey in normalized)) {
+			normalized[schemaKey] = normalized[commanderKey];
+			delete normalized[commanderKey];
+		}
+		return normalized;
+	}
+	/**
+	* Builds a mapping from Commander keys to schema keys.
+	*
+	* Analyzes the schema shape and creates a map for any keys that
+	* would be transformed by Commander's kebab-to-camel conversion.
+	*
+	* @param schema - The Zod schema to extract keys from
+	* @returns Map of Commander keys to schema keys
+	*/
+	buildMappingFromSchema(schema) {
+		const mappings = /* @__PURE__ */ new Map();
+		const shape = schema.shape;
+		for (const camelKey of Object.keys(shape)) {
+			const kebabKey = camelToKebab(camelKey);
+			if (kebabKey !== camelKey) {
+				const commanderKey = kebabKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+				mappings.set(commanderKey, camelKey);
+			}
+		}
+		return mappings;
+	}
+};
+
+//#endregion
+//#region src/domain/semver/semver.strategies.ts
+/**
+* The bump strategy determines which versioning strategy to use when bumping versions.
+* - "auto": Automatically determine the version bump based on commit messages.
+* - "manual": Manually specify the version bump, will generate selection options based on current version.
+*/
+const BUMP_STRATEGY_AUTO = "auto";
+const BUMP_STRATEGY_MANUAL = "manual";
+const BumpStrategyValues = [BUMP_STRATEGY_AUTO, BUMP_STRATEGY_MANUAL];
+const BumpStrategySchema = z$1.enum(BumpStrategyValues).or(z$1.literal("")).default("");
+
+//#endregion
+//#region src/commands/release/groups/skip-predicates.ts
+const releaseSkipPredicates = {
+	skipBump: (ctx) => ctx.config.skipBump,
+	skipChangelog: (ctx) => ctx.config.skipChangelog,
+	skipGit: (ctx) => ctx.config.skipGit,
+	skipPush: (ctx) => ctx.config.skipPush,
+	skipGitHubRelease: (ctx) => ctx.config.skipGitHubRelease,
+	skipBumpAndChangelog: (ctx) => ctx.config.skipBump && ctx.config.skipChangelog,
+	skipBumpAndGit: (ctx) => ctx.config.skipBump && ctx.config.skipGit,
+	skipGitOrNoChanges: (ctx) => ctx.config.skipGit || ctx.config.skipBump && ctx.config.skipChangelog,
+	skipPushOrNoChanges: (ctx) => ctx.config.skipGit || ctx.config.skipPush || ctx.config.skipBump && ctx.config.skipChangelog,
+	skipGitHubReleaseOrNoTag: (ctx) => ctx.config.skipGitHubRelease || ctx.config.skipGit || ctx.config.skipBump && ctx.config.skipChangelog,
+	bumpStrategyIsAuto: (ctx) => ctx.config.bumpStrategy === BUMP_STRATEGY_AUTO,
+	bumpStrategyIsManual: (ctx) => ctx.config.bumpStrategy === BUMP_STRATEGY_MANUAL,
+	hasReleaseType: (ctx) => Boolean(ctx.config.releaseType),
+	hasBumpStrategy: (ctx) => Boolean(ctx.config.bumpStrategy)
+};
+
+//#endregion
+//#region src/core/task/skip-conditions.ts
+/**
+* Converts a simple predicate into a full SkipCondition result function.
+*
+* @param predicate - Predicate to convert
+* @param reason - Human-readable reason shown in logs
+* @returns Function returning FireflyResult<SkipCondition>
+*
+* @example
+* ```typescript
+* const skipFn = toSkipCondition(
+*   (ctx) => ctx.config.skipValidation,
+*   "Validation disabled in config"
+* );
+*
+* TaskBuilder.create("validate")
+*   .shouldSkip(skipFn)
+* ```
+*/
+function toSkipCondition(predicate, reason) {
+	return (ctx) => FireflyOk({
+		shouldSkip: predicate(ctx),
+		reason
+	});
+}
+/**
+* Converts a predicate to a SkipCondition with a default reason.
+*
+* This is a convenience function for internal use when a specific reason
+* is not required. For user-facing code, prefer `toSkipCondition` with
+* an explicit reason.
+*
+* @param predicate - Predicate to convert
+* @param defaultReason - Optional reason (defaults to "Skip condition met")
+* @returns Function returning FireflyResult<SkipCondition>
+*
+* @internal
+*/
+function predicateToSkipFn(predicate, defaultReason = "Skip condition met") {
+	return toSkipCondition(predicate, defaultReason);
+}
+/**
+* Converts a predicate into a SkipCondition with jump targets.
+*
+* When the predicate returns true, the task is skipped and execution
+* jumps to the specified tasks.
+*
+* @param predicate - Predicate to evaluate
+* @param skipToTasks - Task IDs to jump to when skipping
+* @param reason - Optional reason message
+* @returns Function returning FireflyResult<SkipCondition>
+*
+* @example
+* ```typescript
+* const skipAndJump = toSkipConditionWithJump(
+*   (ctx) => ctx.config.fastMode,
+*   ["finalize"],
+*   "Fast mode enabled, skipping to finalize"
+* );
+* ```
+*/
+function toSkipConditionWithJump(predicate, skipToTasks, reason) {
+	return (ctx) => FireflyOk({
+		shouldSkip: predicate(ctx),
+		reason: reason ?? "Skip condition met",
+		skipToTasks
+	});
+}
+
+//#endregion
+//#region src/core/task/task.builder.ts
+/**
+* Fluent builder for constructing validated tasks.
+* Provides a chainable API for defining task properties.
+*
+* @template TContext - The workflow context type this task operates on
+*
+* @example
+* ```typescript
+* const taskResult = TaskBuilder.create<MyContext>("validate-input")
+*   .description("Validates user input against schema")
+*   .dependsOn("load-config")
+*   .skipWhen((ctx) => ctx.data.skipValidation)
+*   .execute((ctx) => {
+*     const validated = validateInput(ctx.data.input);
+*     return FireflyOkAsync(ctx.fork("validatedInput", validated));
+*   })
+*   .withUndo((ctx) => {
+*     logger.info("Rolling back validation");
+*     return FireflyOkAsync(undefined);
+*   })
+*   .build();
+*
+* if (taskResult.isErr()) {
+*   console.error("Invalid task:", taskResult.error.message);
+* }
+* ```
+*/
+var TaskBuilder = class TaskBuilder {
+	taskId;
+	taskDescription;
+	taskDependencies = [];
+	taskConfigSchema;
+	skipFn;
+	executeFn;
+	undoFn;
+	constructor(id) {
+		this.taskId = id;
+	}
+	/**
+	* Creates a new TaskBuilder instance.
+	* @template TCtx - The workflow context type
+	* @param id - Unique identifier for the task
+	*/
+	static create(id) {
+		return new TaskBuilder(id);
+	}
+	/**
+	* Sets the task's human-readable description.
+	* Required - build() will fail without a description.
+	* @param desc - Description of what the task does
+	*/
+	description(desc) {
+		this.taskDescription = desc;
+		return this;
+	}
+	/**
+	* Adds a single dependency on another task.
+	* The dependency must be registered before this task.
+	* @param taskId - ID of the task this depends on
+	*/
+	dependsOn(taskId) {
+		this.taskDependencies.push(taskId);
+		return this;
+	}
+	/**
+	* Adds multiple dependencies on other tasks.
+	* @param taskIds - IDs of tasks this depends on
+	*/
+	dependsOnAll(...taskIds) {
+		this.taskDependencies.push(...taskIds);
+		return this;
+	}
+	/**
+	* Sets a Zod schema for configuration validation.
+	* @param schema - Zod schema to validate task config against
+	*/
+	withConfigSchema(schema) {
+		this.taskConfigSchema = schema;
+		return this;
+	}
+	/**
+	* Sets a simple skip condition based on a boolean predicate.
+	* @param predicate - Function returning true if task should be skipped
+	*/
+	skipWhen(predicate) {
+		this.skipFn = predicateToSkipFn(predicate);
+		return this;
+	}
+	/**
+	* Sets a skip condition with a custom reason message.
+	* @param predicate - Function returning true if task should be skipped
+	* @param reason - Human-readable reason shown in logs
+	*/
+	skipWhenWithReason(predicate, reason) {
+		this.skipFn = toSkipCondition(predicate, reason);
+		return this;
+	}
+	/**
+	* Sets a skip condition that jumps to specific tasks.
+	* @param predicate - Function returning true if task should be skipped
+	* @param skipToTasks - Task IDs to jump to when skipping
+	*/
+	skipWhenAndJumpTo(predicate, skipToTasks) {
+		this.skipFn = toSkipConditionWithJump(predicate, skipToTasks);
+		return this;
+	}
+	/**
+	* Sets a custom skip condition with full control over the result.
+	* @param fn - Function returning a SkipCondition result
+	*/
+	shouldSkip(fn) {
+		this.skipFn = fn;
+		return this;
+	}
+	/**
+	* Sets the task's execute function.
+	* Required - build() will fail without an execute function.
+	* @param fn - Async function that performs the task's work
+	*/
+	execute(fn) {
+		this.executeFn = fn;
+		return this;
+	}
+	/**
+	* Sets an optional undo function for rollback support.
+	* Called in reverse order when a later task fails.
+	* @param fn - Async function that undoes the task's effects
+	*/
+	withUndo(fn) {
+		this.undoFn = fn;
+		return this;
+	}
+	/**
+	* Builds the task, validating that required properties are set.
+	* @returns `FireflyOk(Task)` if valid, `Err(FireflyError)` if missing required properties
+	*/
+	build() {
+		if (!this.executeFn) return invalidErr({
+			message: `Task "${this.taskId}" must have an execute function`,
+			source: "TaskBuilder.build"
+		});
+		if (!this.taskDescription) return invalidErr({
+			message: `Task "${this.taskId}" must have a description`,
+			source: "TaskBuilder.build"
+		});
+		return FireflyOk({
+			meta: {
+				id: this.taskId,
+				description: this.taskDescription,
+				dependencies: this.taskDependencies.length > 0 ? this.taskDependencies : void 0,
+				configSchema: this.taskConfigSchema
+			},
+			shouldSkip: this.skipFn,
+			execute: this.executeFn,
+			undo: this.undoFn
+		});
+	}
+};
+
+//#endregion
+//#region src/commands/release/tasks/bump-release-version.task.ts
+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);
+	}).build();
+}
+
+//#endregion
+//#region src/core/task/task-group.builder.ts
+/**
+* Fluent builder for constructing validated task groups.
+* Provides a chainable API for defining group properties.
+*
+* @template TContext - The workflow context type for tasks in this group
+*
+* @example
+* ```typescript
+* const gitGroupResult = TaskGroupBuilder.create<ReleaseContext>("git")
+*   .description("Git operations for release")
+*   .dependsOnGroup("changelog")
+*   .skipWhen((ctx) => ctx.config.skipGit)
+*   .skipReason("Git operations disabled")
+*   .tasks([stageTask, commitTask, tagTask])
+*   .build();
+*
+* if (gitGroupResult.isErr()) {
+*   console.error("Invalid group:", gitGroupResult.error.message);
+* }
+* ```
+*/
+var TaskGroupBuilder = class TaskGroupBuilder {
+	groupId;
+	groupDescription;
+	groupDependencies = [];
+	skipConditionFn;
+	skipPredicateFn;
+	skipReasonText;
+	groupTasks = [];
+	constructor(id) {
+		this.groupId = id;
+	}
+	/**
+	* Creates a new TaskGroupBuilder instance.
+	* @template TCtx - The workflow context type
+	* @param id - Unique identifier for the group
+	*/
+	static create(id) {
+		return new TaskGroupBuilder(id);
+	}
+	/**
+	* Sets the group's human-readable description.
+	* Required - build() will fail without a description.
+	* @param desc - Description of what the group does
+	*/
+	description(desc) {
+		this.groupDescription = desc;
+		return this;
+	}
+	/**
+	* Adds a dependency on another group.
+	* The dependency group must be registered before this group.
+	* @param groupId - ID of the group this depends on
+	*/
+	dependsOnGroup(groupId) {
+		this.groupDependencies.push(groupId);
+		return this;
+	}
+	/**
+	* Adds dependencies on multiple groups.
+	* @param groupIds - IDs of groups this depends on
+	*/
+	dependsOnGroups(...groupIds) {
+		this.groupDependencies.push(...groupIds);
+		return this;
+	}
+	/**
+	* Sets a simple skip condition based on a boolean predicate.
+	* When true, all tasks in the group are skipped.
+	* @param predicate - Function returning true if group should be skipped
+	*/
+	skipWhen(predicate) {
+		this.skipPredicateFn = predicate;
+		return this;
+	}
+	/**
+	* Sets the reason shown in logs when the group is skipped.
+	* @param reason - Human-readable reason
+	*/
+	skipReason(reason) {
+		this.skipReasonText = reason;
+		return this;
+	}
+	/**
+	* Sets a custom skip condition with full control over the result.
+	* @param fn - Function returning a SkipCondition result
+	*/
+	shouldSkip(fn) {
+		this.skipConditionFn = fn;
+		return this;
+	}
+	/**
+	* Sets the tasks belonging to this group.
+	* @param tasks - Array of tasks to include in the group
+	*/
+	tasks(tasks) {
+		this.groupTasks = tasks;
+		return this;
+	}
+	/**
+	* Adds a single task to the group.
+	* @param task - Task to add
+	*/
+	addTask(task) {
+		this.groupTasks.push(task);
+		return this;
+	}
+	/**
+	* Adds a task result to the group.
+	* If the result is an error, the error is stored and will cause build() to fail.
+	* @param taskResult - Result containing a task or error
+	*/
+	addTaskResult(taskResult) {
+		if (taskResult.isOk()) this.groupTasks.push(taskResult.value);
+		return this;
+	}
+	/**
+	* Builds the task group, validating that required properties are set.
+	* @returns `Ok(TaskGroup)` if valid, `Err(FireflyError)` if missing required properties
+	*/
+	build() {
+		if (!this.groupDescription) return invalidErr({
+			message: `Task group "${this.groupId}" must have a description`,
+			source: "TaskGroupBuilder.build"
+		});
+		if (this.groupTasks.length === 0) return invalidErr({
+			message: `Task group "${this.groupId}" must have at least one task`,
+			source: "TaskGroupBuilder.build"
+		});
+		const meta = {
+			id: this.groupId,
+			description: this.groupDescription,
+			dependsOnGroups: this.groupDependencies.length > 0 ? [...this.groupDependencies] : void 0
+		};
+		const options = {};
+		if (this.skipConditionFn) options.skipCondition = this.skipConditionFn;
+		if (this.skipPredicateFn) options.skipWhen = this.skipPredicateFn;
+		if (this.skipReasonText) options.skipReason = this.skipReasonText;
+		return FireflyOk({
+			meta,
+			options: Object.keys(options).length > 0 ? options : void 0,
+			tasks: [...this.groupTasks]
+		});
+	}
+};
+/**
+* Convenience function to create a new TaskGroupBuilder.
+* Equivalent to `TaskGroupBuilder.create(id)`.
+*
+* @template TContext - The workflow context type
+* @param id - Unique identifier for the group
+*
+* @example
+* ```typescript
+* const group = buildTaskGroup<MyContext>("my-group")
+*   .description("Does something")
+*   .tasks([task1, task2])
+*   .build();
+* ```
+*/
+function buildTaskGroup(id) {
+	return TaskGroupBuilder.create(id);
+}
+
+//#endregion
+//#region src/commands/release/groups/bump-execution.group.ts
+/**
+* Creates the bump execution group containing the actual version bump task.
+*
+* This group executes the version bump in package.json after the strategy
+* has been determined. It is skipped when skipBump is enabled.
+*/
+function createBumpExecutionGroup() {
+	const taskResult = createBumpReleaseVersion();
+	if (taskResult.isErr()) return taskResult.map(() => ({}));
+	return buildTaskGroup("bump-execution").description("Version bump execution").dependsOnGroup("bump-strategy").skipWhen(releaseSkipPredicates.skipBump).skipReason("Skipped: skipBump is enabled").tasks([taskResult.value]).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/delegate-bump-strategy.task.ts
+/**
+* Determines if the execute-bump-strategy task should be skipped.
+*
+* The task should execute when:
+* - No explicit releaseType is set (need to determine version bump)
+* - A bumpStrategy is configured (auto or manual)
+* - skipBump is not enabled
+*/
+function shouldSkipBumpStrategy(ctx) {
+	const { skipBump, releaseType, bumpStrategy } = ctx.config;
+	if (skipBump) return true;
+	if (releaseType) return true;
+	if (!bumpStrategy) return true;
+	return false;
+}
+/**
+* Generates a skip reason based on the current context.
+*/
+function getSkipReason(ctx) {
+	const { skipBump, releaseType, bumpStrategy } = ctx.config;
+	if (skipBump) return "skipBump is enabled";
+	if (releaseType) return `releaseType already set to '${releaseType}'`;
+	if (!bumpStrategy) return "no bumpStrategy configured";
+	return "unknown reason";
+}
+function createDelegateBumpStrategyTask() {
+	return TaskBuilder.create("delegate-bump-strategy").description("Delegates the version bump strategy decision").dependsOn("initialize-release-version").shouldSkip((ctx) => {
+		const shouldSkip = shouldSkipBumpStrategy(ctx);
+		return FireflyOk({
+			shouldSkip,
+			reason: shouldSkip ? getSkipReason(ctx) : void 0
+		});
+	}).execute((ctx) => {
+		logger.info("delegate-bump-strategy");
+		return FireflyOkAsync(ctx);
+	}).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/determine-automatic-bump.task.ts
+function createDetermineAutomaticBump() {
+	return TaskBuilder.create("determine-automatic-bump").description("Automatically determines the version bump from commit messages").dependsOn("delegate-bump-strategy").skipWhenWithReason((ctx) => ctx.config.skipBump || ctx.config.bumpStrategy !== BUMP_STRATEGY_AUTO, "Skipped: skipBump enabled or bumpStrategy is not 'auto'").execute((ctx) => {
+		logger.info("determine-automatic-bump");
+		return FireflyOkAsync(ctx);
+	}).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/prompt-bump-strategy.task.ts
+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) => {
+		logger.info("prompt-bump-strategy");
+		return FireflyOkAsync(ctx);
+	}).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/prompt-manual-bump.task.ts
+function createPromptManualVersionTask() {
+	return TaskBuilder.create("prompt-manual-version").description("Prompts the user for a manual version bump selections").dependsOn("delegate-bump-strategy").skipWhenWithReason((ctx) => ctx.config.skipBump || Boolean(ctx.config.bumpStrategy) || Boolean(ctx.config.releaseType), "Skipped: skipBump enabled, or bumpStrategy/releaseType already specified").execute((ctx) => {
+		logger.info("prompt-manual-version");
+		return FireflyOkAsync(ctx);
+	}).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/straight-version-bump.task.ts
+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();
+}
+
+//#endregion
+//#region src/commands/release/groups/bump-strategy.group.ts
+/**
+* Creates the bump strategy group containing version bump decision tasks.
+*
+* This group handles determining the version bump strategy (auto/manual)
+* and the specific release type. It is skipped when skipBump is enabled.
+*
+*/
+function createBumpStrategyGroup() {
+	const taskResults = [
+		createStraightVersionBump(),
+		createPromptBumpStrategyTask(),
+		createDelegateBumpStrategyTask(),
+		createDetermineAutomaticBump(),
+		createPromptManualVersionTask()
+	];
+	const combined = Result.combine(taskResults);
+	if (combined.isErr()) return combined.map(() => ({}));
+	return buildTaskGroup("bump-strategy").description("Version bump strategy selection").dependsOnGroup("setup").skipWhen(releaseSkipPredicates.skipBump).skipReason("Skipped: skipBump is enabled").tasks(combined.value).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/initialize-release-version.task.ts
+function createInitializeReleaseVersion() {
+	return TaskBuilder.create("initialize-release-version").description("Hydrate and prepare the release configuration").dependsOn("prepare-release-config").execute((ctx) => {
+		logger.info("initialize-release-version");
+		return FireflyOkAsync(ctx);
+	}).build();
+}
+
+//#endregion
+//#region src/commands/release/tasks/prepare-release-config.task.ts
+const HTTPS_REMOTE_REGEX = /https?:\/\/[^/]+\/([^/]+)\/([^/.]+)(?:\.git)?/;
+const SSH_REMOTE_REGEX = /git@[^:]+:([^/]+)\/([^/.]+)(?:\.git)?/;
+const SCOPED_PACKAGE_REGEX = /^@([^/]+)\/(.+)$/;
+const PRERELEASE_REGEX = /^\d+\.\d+\.\d+-([a-zA-Z]+)/;
+/**
+* Parses a git remote URL to extract owner and repository name.
+* Supports both HTTPS and SSH formats.
+*
+* @example
+* parseGitRemoteUrl("https://github.com/owner/repo.git") // { owner: "owner", repo: "repo" }
+* parseGitRemoteUrl("git@github.com:owner/repo.git") // { owner: "owner", repo: "repo" }
+*/
+function parseGitRemoteUrl(url) {
+	const httpsMatch = url.match(HTTPS_REMOTE_REGEX);
+	if (httpsMatch?.[1] && httpsMatch[2]) return {
+		owner: httpsMatch[1],
+		repo: httpsMatch[2]
+	};
+	const sshMatch = url.match(SSH_REMOTE_REGEX);
+	if (sshMatch?.[1] && sshMatch[2]) return {
+		owner: sshMatch[1],
+		repo: sshMatch[2]
+	};
+	return null;
+}
+/**
+* Parses a scoped package name to extract scope and name.
+*
+* @example
+* parsePackageName("@company/tool") // { scope: "company", name: "tool" }
+* parsePackageName("tool") // { scope: undefined, name: "tool" }
+*/
+function parsePackageName(packageName) {
+	const scopeMatch = packageName.match(SCOPED_PACKAGE_REGEX);
+	if (scopeMatch?.[1] && scopeMatch[2]) return {
+		scope: scopeMatch[1],
+		name: scopeMatch[2]
+	};
+	return { name: packageName };
+}
+/**
+* Extracts pre-release identifier from a semver version string.
+*
+* @example
+* extractPreReleaseId("1.0.0-beta.1") // "beta"
+* extractPreReleaseId("1.0.0") // undefined
+*/
+function extractPreReleaseId(version) {
+	return version.match(PRERELEASE_REGEX)?.[1];
+}
+/**
+* Hydrates the repository field from git remote URL.
+*
+* Behavior:
+* - If not inside a git repository, resolves to undefined.
+* - If inside a repository, detect the repository URL
+*   using a fall-through strategy (upstream remote → origin → first remote).
+* - Parses the URL and returns "owner/repo" when possible.
+*/
+function hydrateRepository(ctx) {
+	return ctx.services.git.inferRepositoryUrl().map((url) => {
+		if (!url) return null;
+		const parsed = parseGitRemoteUrl(url);
+		if (parsed) return `${parsed.owner}/${parsed.repo}`;
+		return null;
+	}).map((val) => val ?? void 0).andTee((repository) => logger.verbose(`PrepareReleaseConfigTask: Prepared repository: ${repository}`));
+}
+/**
+* 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.
+*/
+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
+		});
+		return ctx.services.packageJson.read("package.json").andThen((pkg) => zip3Async(hydrateNameFromPackageJson(ctx, pkg), hydrateScopeFromPackageJson(ctx, pkg), hydratePreReleaseIdFromPackageJson(ctx, pkg)).map(([name, scope, preReleaseId]) => {
+			const result = {};
+			if (name) result.name = name;
+			if (scope) result.scope = scope;
+			if (preReleaseId) result.preReleaseId = preReleaseId;
+			return result;
+		}));
+	});
+}
+/**
+* Hydrates the `name` field from package.json when not provided in config.
+*
+* Cases:
+* 1. If name is undefined and package.json has no name, returns a validation error.
+* 2. If name is undefined and package.json has a name, extracts the name (stripping scope) and returns it.
+* 3. Otherwise uses provided name.
+*/
+function hydrateNameFromPackageJson(ctx, packageJson) {
+	if (ctx.config.name === void 0 && !packageJson.name) return validationErrAsync({ message: "Could not find a valid name in package.json" });
+	if (ctx.config.name === void 0 && packageJson.name) {
+		const extractedName = parsePackageName(packageJson.name).name;
+		logger.verbose(`PrepareReleaseConfigTask: Prepared name from package.json: ${extractedName}`);
+		return FireflyOkAsync(extractedName);
+	}
+	logger.verbose(`PrepareReleaseConfigTask: Using provided name: "${ctx.config.name}" as it is explicitly set`);
+	return FireflyOkAsync(ctx.config.name);
+}
+/**
+* Hydrates the `scope` field from package.json when not provided in config.
+*
+* Cases:
+* 1. If scope is explicitly provided (key exists and value is not undefined), it is used.
+* 2. If not provided, but package.json has a scoped `name` (e.g., "@scope/name"), the scope will be extracted and returned.
+* 3. Otherwise returns undefined.
+*/
+function hydrateScopeFromPackageJson(ctx, packageJson) {
+	if (Object.hasOwn(ctx.config, "scope") && ctx.config.scope !== void 0) {
+		logger.verbose(`PrepareReleaseConfigTask: Using provided scope: "${ctx.config.scope}" as it is explicitly set`);
+		return FireflyOkAsync(ctx.config.scope);
+	}
+	if (packageJson.name?.startsWith("@")) {
+		const parsed = parsePackageName(packageJson.name);
+		if (parsed.scope) {
+			logger.verbose(`PrepareReleaseConfigTask: Prepared scope from package.json: ${parsed.scope}`);
+			return FireflyOkAsync(parsed.scope);
+		}
+	}
+	logger.verbose("PrepareReleaseConfigTask: No scope to prepare from package.json");
+	return FireflyOkAsync(void 0);
+}
+/**
+* Hydrates the `preReleaseId` field from `package.json.version` when not provided.
+*
+* Cases:
+* 1. If preReleaseId is explicitly provided and not an empty string, it is used.
+* 2. If not provided, and `package.json.version` contains a prerelease segment, the prerelease identifier will be extracted and returned.
+* 3. Otherwise the function defaults to "alpha".
+*/
+function hydratePreReleaseIdFromPackageJson(ctx, packageJson) {
+	if (ctx.config.preReleaseId !== void 0 && ctx.config.preReleaseId.trim() !== "") {
+		logger.verbose(`PrepareReleaseConfigTask: Using provided preReleaseId: "${ctx.config.preReleaseId}" as it is explicitly set`);
+		return FireflyOkAsync(ctx.config.preReleaseId);
+	}
+	if (packageJson.version) {
+		const parsed = parse(packageJson.version);
+		if (!parsed) return validationErrAsync({ message: `Invalid version format in package.json: ${packageJson.version}` });
+		if (parsed.prerelease.length > 0 && typeof parsed.prerelease[0] === "string") {
+			const preReleaseId = extractPreReleaseId(packageJson.version);
+			logger.verbose(`PrepareReleaseConfigTask: Prepared preReleaseId from package.json: ${preReleaseId}`);
+			return FireflyOkAsync(preReleaseId);
+		}
+	}
+	logger.verbose("PrepareReleaseConfigTask: No preReleaseId to prepare from package.json, defaulting to 'alpha'");
+	return FireflyOkAsync("alpha");
+}
+/**
+* Hydrates branch setting from git.
+*
+* Behavior:
+* - If not inside a git repository, resolves to undefined.
+* - If a branch is explicitly provided in the config, validates it against the
+*   current git branch and returns it (otherwise returns a validation error).
+* - If no branch is provided in the config, uses current git branch.
+*/
+function hydrateBranch(ctx) {
+	return ctx.services.git.isInsideRepository().andThen((isRepo) => {
+		if (!isRepo) return FireflyOkAsync(void 0);
+		return ctx.services.git.getCurrentBranch().andThen((currentBranch) => {
+			if (Object.hasOwn(ctx.config, "branch") && ctx.config.branch !== void 0 && ctx.config.branch.trim() !== "") {
+				if (ctx.config.branch !== currentBranch) return validationErrAsync({ message: `Configured branch "${ctx.config.branch}" does not match current git branch "${currentBranch}"` });
+				logger.verbose(`PrepareReleaseConfigTask: Using provided branch: "${ctx.config.branch}" as it is explicitly set`);
+				return FireflyOkAsync(ctx.config.branch);
+			}
+			logger.verbose(`PrepareReleaseConfigTask: Prepared branch from git: ${currentBranch}`);
+			return FireflyOkAsync(currentBranch);
+		});
+	});
+}
+/**
+* Creates the Prepare Release Config Task.
+*
+* This task determines and hydrates configuration settings, by inferring values from the environment.
+*
+* This task:
+* 1. Detects repository owner/repo from git remote URL
+* 2. Extracts name and scope from package.json
+* 3. Extracts preReleaseId from package.json version
+* 4. Detects current git branch if not provided
+*/
+function createPrepareReleaseConfigTask() {
+	return TaskBuilder.create("prepare-release-config").description("Hydrate and prepare the release configuration").execute((ctx) => {
+		const hydrated = {};
+		return zip3Async(hydrateRepository(ctx), hydrateFromPackageJson(ctx), hydrateBranch(ctx)).map(([repository, pkgData, branch]) => {
+			if (repository) hydrated.repository = repository;
+			if (pkgData.name) hydrated.name = pkgData.name;
+			if (pkgData.scope) hydrated.scope = pkgData.scope;
+			if (pkgData.preReleaseId) hydrated.preReleaseId = pkgData.preReleaseId;
+			if (branch) hydrated.branch = branch;
+			logger.verbose(`PrepareReleaseConfigTask: Hydrated config: ${JSON.stringify(hydrated)}`);
+			return ctx.fork("hydratedConfig", hydrated);
+		});
+	}).build();
+}
+
+//#endregion
+//#region src/core/task/task.helpers.ts
+/**
+* Runs a sequence of void async operations on the context.
+*
+* Like `pipeline` but for operations that don't modify the context.
+* Context is returned unchanged after all operations complete.
+*
+* @param ctx - Context to pass to operations
+* @param operations - Array of void async operations
+* @returns The original context after all operations complete
+*
+* @example
+* ```typescript
+* execute: (ctx) => runChecks(ctx,
+*   (c) => checkGitStatus(c),
+*   (c) => checkPermissions(c),
+*   (c) => checkDiskSpace(c),
+* )
+* ```
+*/
+function runChecks(ctx, ...checks) {
+	const initial = FireflyOkAsync(void 0);
+	return checks.reduce((chain, check) => chain.andThen(() => check(ctx)), initial).map(() => ctx);
+}
+
+//#endregion
+//#region src/commands/release/tasks/release-preflight.task.ts
+/**
+* Checks if the current directory is a git repository.
+*/
+function checkGitRepository(ctx) {
+	return ctx.services.git.isInsideRepository().andThen((isRepo) => ensureNotAsync(!isRepo, { message: "We are not inside a git repository!" })).andTee(() => logger.verbose("ReleasePreflightTask: Confirmed inside a git repository."));
+}
+/**
+* Checks if the working directory is clean (no uncommitted changes).
+*/
+function checkCleanWorkingDirectory(ctx) {
+	return ctx.services.git.getStatus().andThen((status) => {
+		if (!status.isClean) {
+			const issues = [];
+			if (status.hasStaged) issues.push("staged changes");
+			if (status.hasUnstaged) issues.push("unstaged changes");
+			if (status.hasUntracked) issues.push("untracked files");
+			return conflictErrAsync({
+				message: `Working directory is not clean. Found: ${issues.join(", ")}. Commit or stash changes first.`,
+				details: status
+			});
+		}
+		return FireflyOk(void 0);
+	}).andTee(() => logger.verbose("ReleasePreflightTask: Confirmed working directory is clean."));
+}
+/**
+* Checks if there are unpushed commits in the current branch.
+*/
+function checkUnpushedCommits(ctx) {
+	return ctx.services.git.getUnpushedCommits().andThen((result) => ensureNotAsync(result.hasUnpushed, {
+		message: `Found ${result.count} unpushed commit(s). Push changes before releasing.`,
+		source: "commands/release/preflight"
+	})).andTee(() => logger.verbose("ReleasePreflightTask: Confirmed no unpushed commits found."));
+}
+/**
+* Checks if the `cliff.toml` configuration file exists in the project root.
+*/
+function checkCliffConfig(ctx) {
+	const CLIFF_CONFIG_FILE = "cliff.toml";
+	return ctx.services.fs.exists(CLIFF_CONFIG_FILE).andThen((exists) => ensureNotAsync(!exists, {
+		message: `Configuration file "${CLIFF_CONFIG_FILE}" not found. See: https://git-cliff.org/docs/usage/initializing`,
+		source: "commands/release/preflight"
+	})).andTee(() => logger.verbose(`ReleasePreflightTask: Confirmed presence of "${CLIFF_CONFIG_FILE}" in project root.`));
+}
+/**
+* Creates the Release Preflight Task.
+*
+* This task checks the environment and prerequisites for a release.
+* It can be conditionally skipped based on the provided skip condition, though not recommended.
+*
+* Skipping this may led to malformed releases or errors during the release process,
+* and generally done for development purposes only or if you know what you are doing.
+*
+* This task:
+* 1. Check if its on a git repository
+* 2. Check if on a clean working tree, no uncommitted changes
+* 3. Check if no unpushed commits
+* 4. Check if there is `cliff.toml` file in the project root
+*/
+function createReleasePreflightTask(skipCondition) {
+	return TaskBuilder.create("release-preflight").description("Validate environment and prerequisites for a release").skipWhen(skipCondition).execute((ctx) => runChecks(ctx, checkGitRepository, checkCleanWorkingDirectory, checkUnpushedCommits, checkCliffConfig)).build();
+}
+
+//#endregion
+//#region src/commands/release/groups/setup.group.ts
+/**
+* Creates the setup group containing preflight, config preparation, and version initialization.
+*
+* This group runs first and has no skip condition at the group level.
+* Individual tasks have their own skip conditions (preflight can be skipped via config).
+*/
+function createReleaseSetupGroup(skipPreflight) {
+	const taskResults = [
+		createReleasePreflightTask(() => skipPreflight),
+		createPrepareReleaseConfigTask(),
+		createInitializeReleaseVersion()
+	];
+	const combined = Result.combine(taskResults);
+	if (combined.isErr()) return combined.map(() => ({}));
+	return buildTaskGroup("setup").description("Setup and initialization tasks").tasks(combined.value).build();
+}
+/**
+* Creates all release task groups in the correct order.
+*
+* @param skipPreflight - Whether to skip the preflight check
+* @returns Array of task groups or an error
+*/
+function createReleaseGroups(skipPreflight) {
+	const groupResults = [
+		createReleaseSetupGroup(skipPreflight),
+		createBumpStrategyGroup(),
+		createBumpExecutionGroup()
+	];
+	return Result.combine(groupResults);
+}
+
+//#endregion
+//#region src/domain/semver/semver.definitions.ts
+/**
+* Represents the type of version bump decision to be made.
+* If not specified, the user will be prompted to select a release decision.
+*/
+const ReleaseTypeValues = [
+	"major",
+	"minor",
+	"patch",
+	"prerelease",
+	"premajor",
+	"preminor",
+	"prepatch",
+	"graduate"
+];
+const ReleaseTypeSchema = z$1.enum(ReleaseTypeValues);
+/**
+* Defines the base version for a pre-release.
+* Accepts either a number or the string "0" or "1", representing the starting point of the pre-release cycle.
+* This field is optional to allow flexibility in pre-release versioning.
+*/
+const PreReleaseBaseSchema = z$1.union([
+	z$1.number(),
+	z$1.literal("0"),
+	z$1.literal("1")
+]).optional();
+
+//#endregion
+//#region src/commands/release/release.config.ts
+const COMMIT_MSG_TEMPLATE = "chore(release): release {{name}}@{{version}}";
+const TAG_NAME_TEMPLATE = "{{name}}@{{version}}";
+const RELEASE_TITLE_TEMPLATE = "{{name}}@{{version}}";
+function validateReleaseFlagExclusivity(ctx) {
+	const flagNames = [
+		"releaseLatest",
+		"releasePreRelease",
+		"releaseDraft"
+	];
+	if (flagNames.filter((k) => ctx.value[k]).length > 1) ctx.issues.push({
+		code: "custom",
+		message: `Only one of ${flagNames.join(", ")} can be set to true.`,
+		input: ctx.value,
+		path: ["releaseLatest"]
+	});
+}
+function validateSkipGitRedundancy(ctx) {
+	if (ctx.value.skipGit && ctx.value.skipPush) ctx.issues.push({
+		code: "custom",
+		message: "skipPush should not be set when skipGit is true.",
+		input: ctx.value
+	});
+}
+function validateBumpStrategyCompatibility(ctx) {
+	const { bumpStrategy, releaseType } = ctx.value;
+	if (bumpStrategy === "auto" && releaseType !== void 0 && releaseType !== "prerelease") ctx.issues.push({
+		code: "custom",
+		message: "When bumpStrategy is 'auto', releaseType can only be 'prerelease' if specified.",
+		input: ctx.value
+	});
+}
+function validateSkipFlagCombinations(ctx) {
+	const { skipBump, skipChangelog, skipGit, skipGitHubRelease } = ctx.value;
+	if (skipBump && skipChangelog && skipGit && skipGitHubRelease) {
+		ctx.issues.push({
+			code: "custom",
+			message: "Invalid configuration: skipBump, skipChangelog, skipGit, and skipGitHubRelease are all enabled. Nothing to do.",
+			input: ctx.value
+		});
+		return;
+	}
+	if (skipBump && skipChangelog && !skipGit) ctx.issues.push({
+		code: "custom",
+		message: "Invalid configuration: skipBump and skipChangelog are enabled without skipGit. There are no changes to commit or tag.",
+		input: ctx.value
+	});
+	if (skipGit && !skipGitHubRelease) ctx.issues.push({
+		code: "custom",
+		message: "Invalid configuration: skipGit is enabled without skipGitHubRelease. GitHub releases require a git tag.",
+		input: ctx.value
+	});
+}
+const ReleaseConfigSchema = 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."),
+	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."),
+	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."),
+	skipChangelog: z$1.coerce.boolean().default(false).describe("Skip changelog generation step."),
+	skipPush: z$1.coerce.boolean().default(false).describe("Skip push step."),
+	skipGitHubRelease: z$1.coerce.boolean().default(false).describe("Skip GitHub release step."),
+	skipGit: z$1.coerce.boolean().default(false).describe("Skip all git-related steps."),
+	skipPreflightCheck: z$1.coerce.boolean().default(false).describe("Skip preflight checks."),
+	releaseTitle: z$1.string().default(RELEASE_TITLE_TEMPLATE).describe("GitHub release title with placeholders."),
+	releaseLatest: z$1.coerce.boolean().default(true).describe("Mark as latest release."),
+	releasePreRelease: z$1.coerce.boolean().default(false).describe("Mark as pre-release."),
+	releaseDraft: z$1.coerce.boolean().default(false).describe("Release as draft version.")
+}).check((ctx) => {
+	validateReleaseFlagExclusivity(ctx);
+	validateSkipGitRedundancy(ctx);
+	validateBumpStrategyCompatibility(ctx);
+	validateSkipFlagCombinations(ctx);
+});
+
+//#endregion
+//#region src/core/command/command.factory.ts
+/**
+* Factory function for creating commands with full type inference.
+*
+* Provides better IDE support and type checking when defining commands.
+* Uses `satisfies` pattern for optimal type inference.
+*
+* @template TConfig - Command configuration type
+* @template TData - Workflow data type
+* @template TServices - Tuple of required service keys
+* @param command - Command definition
+* @returns The same command (identity function for type inference)
+*
+* @example
+* ```typescript
+* const myCommand = createCommand({
+*   meta: {
+*     name: "my-command",
+*     description: "Does something useful",
+*     configSchema: z.object({ option: z.boolean() }),
+*     requiredServices: ["fs"] as const,
+*   },
+*   buildTasks: (ctx) => okAsync([]),
+* });
+* ```
+*/
+function createCommand(command) {
+	return command;
+}
+
+//#endregion
+//#region src/core/service/service.registry.ts
+/**
+* Helper function to define a service with proper type inference.
+* @internal
+*/
+function defineService(definition) {
+	return definition;
+}
+/**
+* Registry of all available services and their factories.
+* Each service is lazily loaded via dynamic `import()`.
+*/
+const SERVICE_DEFINITIONS = {
+	fs: defineService({ factory: async ({ basePath }) => {
+		const { createFileSystemService } = await import("./filesystem.service-DdVwnqoa.js");
+		return createFileSystemService(basePath);
+	} }),
+	packageJson: defineService({
+		dependencies: ["fs"],
+		factory: async ({ getService }) => {
+			const fs = await getService("fs");
+			const { createPackageJsonService } = await import("./package-json.service-QN7SzRTt.js");
+			return createPackageJsonService(fs);
+		}
+	}),
+	git: defineService({ factory: async ({ basePath }) => {
+		const { createGitService } = await import("./git.service-DarjfyXF.js");
+		return createGitService(basePath);
+	} })
+};
+/**
+* Array of all service keys for iteration
+*/
+const ALL_SERVICE_KEYS = Object.keys(SERVICE_DEFINITIONS);
+/**
+* Helper to define a tuple of service keys with proper type inference.
+* Use this to get editor autocomplete for valid service keys.
+*
+* Example:
+* const RELEASE_SERVICES = defineServiceKeys("fs");
+*/
+function defineServiceKeys(...keys) {
+	return keys;
+}
+
+//#endregion
+//#region src/core/task/task.graph.ts
+/**
+* Validates a task dependency graph.
+*
+* Checks for:
+* - Duplicate task IDs
+* - Missing dependencies (references to non-existent tasks)
+* - Circular dependencies
+*
+* Returns the execution order (topological sort) if valid.
+*
+* @param tasks - Array of tasks to validate
+* @returns Validation result with errors, warnings, and execution order
+*
+* @example
+* ```typescript
+* const result = validateTaskGraph(tasks);
+* if (!result.isValid) {
+*   console.error("Graph validation failed:", result.errors);
+* } else {
+*   console.log("Execution order:", result.executionOrder);
+* }
+* ```
+*/
+function validateTaskGraph(tasks) {
+	const errors = [];
+	const warnings = [];
+	const taskMap = buildTaskMap(tasks, errors);
+	checkMissingDependencies(tasks, taskMap, errors, warnings);
+	checkCyclicDependencies(tasks, taskMap, errors);
+	const { executionOrder, depthMap } = computeExecutionOrder(tasks, taskMap, errors);
+	return {
+		isValid: errors.length === 0,
+		errors,
+		warnings,
+		executionOrder,
+		depthMap
+	};
+}
+/**
+* Builds a map of task IDs to Task objects for efficient lookup.
+*
+* Also detects and reports duplicate task IDs.
+*
+* @param tasks - Array of tasks to index
+* @param errors - Array to collect duplicate ID errors
+* @returns Map from task ID to Task object
+*/
+function buildTaskMap(tasks, errors) {
+	const taskMap = /* @__PURE__ */ new Map();
+	for (const task of tasks) if (taskMap.has(task.meta.id)) errors.push(`Duplicate task ID: "${task.meta.id}"`);
+	else taskMap.set(task.meta.id, task);
+	return taskMap;
+}
+/**
+* Validates that all task dependencies reference existing tasks.
+*
+* Also warns about tasks missing descriptions.
+*
+* @param tasks - Array of tasks to validate
+* @param taskMap - Map of task IDs to Task objects
+* @param errors - Array to collect missing dependency errors
+* @param warnings - Array to collect non-critical warnings
+*/
+function checkMissingDependencies(tasks, taskMap, errors, warnings) {
+	for (const task of tasks) {
+		const deps = task.meta.dependencies ?? [];
+		for (const depId of deps) if (!taskMap.has(depId)) errors.push(`Task "${task.meta.id}" depends on unknown task "${depId}"`);
+		if (!task.meta.description || task.meta.description.trim() === "") warnings.push(`Task "${task.meta.id}" has no description`);
+	}
+}
+/**
+* Detects circular dependencies in the task graph using DFS.
+*
+* When a cycle is detected, adds an error message showing the cycle path
+* (e.g., "A → B → C → A").
+*
+* @param tasks - Array of tasks to check
+* @param taskMap - Map of task IDs to Task objects
+* @param errors - Array to collect cycle detection errors
+*/
+function checkCyclicDependencies(tasks, taskMap, errors) {
+	const visited = /* @__PURE__ */ new Set();
+	const recursionStack = /* @__PURE__ */ new Set();
+	const hasCycle = (taskId, path$1) => {
+		if (recursionStack.has(taskId)) {
+			const cycleStart = path$1.indexOf(taskId);
+			const cycle = [...path$1.slice(cycleStart), taskId].join(" → ");
+			errors.push(`Circular dependency detected: ${cycle}`);
+			return true;
+		}
+		if (visited.has(taskId)) return false;
+		visited.add(taskId);
+		recursionStack.add(taskId);
+		const task = taskMap.get(taskId);
+		if (task) {
+			const deps = task.meta.dependencies ?? [];
+			for (const depId of deps) if (taskMap.has(depId) && hasCycle(depId, [...path$1, taskId])) return true;
+		}
+		recursionStack.delete(taskId);
+		return false;
+	};
+	for (const task of tasks) if (!visited.has(task.meta.id)) hasCycle(task.meta.id, []);
+}
+/**
+* Computes the execution order and depth map for a validated task graph.
+*
+* Uses topological sort to determine execution order and calculates
+* the depth of each task in the dependency tree.
+*
+* @param tasks - Array of tasks to order
+* @param taskMap - Map of task IDs to Task objects
+* @param errors - Array of existing validation errors (skips computation if non-empty)
+* @returns Object containing execution order (task IDs) and depth map
+*/
+function computeExecutionOrder(tasks, taskMap, errors) {
+	const executionOrder = [];
+	const depthMap = /* @__PURE__ */ new Map();
+	if (errors.length === 0) {
+		const sorted = topologicalSort(tasks);
+		if (sorted.isOk()) {
+			executionOrder.push(...sorted.value);
+			for (const taskId of executionOrder) {
+				const task = taskMap.get(taskId);
+				if (task) {
+					const maxDepDepth = (task.meta.dependencies ?? []).reduce((max, depId) => {
+						const depDepth = depthMap.get(depId) ?? 0;
+						return Math.max(max, depDepth);
+					}, -1);
+					depthMap.set(taskId, maxDepDepth + 1);
+				}
+			}
+		}
+	}
+	return {
+		executionOrder,
+		depthMap
+	};
+}
+/**
+* Performs topological sort on tasks.
+*
+* @param tasks - Tasks to sort
+* @returns Sorted task IDs or error if cycle detected
+*/
+function topologicalSort(tasks) {
+	const taskMap = /* @__PURE__ */ new Map();
+	const inDegree = /* @__PURE__ */ new Map();
+	const adjacency = /* @__PURE__ */ new Map();
+	for (const task of tasks) {
+		taskMap.set(task.meta.id, task);
+		inDegree.set(task.meta.id, 0);
+		adjacency.set(task.meta.id, []);
+	}
+	for (const task of tasks) {
+		const deps = task.meta.dependencies ?? [];
+		for (const depId of deps) {
+			const adjList = adjacency.get(depId);
+			if (adjList) {
+				adjList.push(task.meta.id);
+				inDegree.set(task.meta.id, (inDegree.get(task.meta.id) ?? 0) + 1);
+			}
+		}
+	}
+	const queue = [];
+	for (const [taskId, degree] of inDegree) if (degree === 0) queue.push(taskId);
+	const result = [];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (!current) break;
+		result.push(current);
+		const dependents = adjacency.get(current) ?? [];
+		for (const dependent of dependents) {
+			const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+			inDegree.set(dependent, newDegree);
+			if (newDegree === 0) queue.push(dependent);
+		}
+	}
+	if (result.length !== tasks.length) return invalidErr({ message: "Circular dependency detected in task graph" });
+	return FireflyOk(result);
+}
+/**
+* Computes statistics about a task graph.
+*
+* @param tasks - Tasks to analyze
+* @returns Graph statistics
+*
+* @example
+* ```typescript
+* const stats = getGraphStatistics(tasks);
+* console.log(`Total tasks: ${stats.totalTasks}`);
+* console.log(`Max depth: ${stats.maxDepth}`);
+* ```
+*/
+function getGraphStatistics(tasks) {
+	const validation = validateTaskGraph(tasks);
+	const dependentCount = /* @__PURE__ */ new Map();
+	for (const task of tasks) dependentCount.set(task.meta.id, 0);
+	let totalEdges = 0;
+	for (const task of tasks) {
+		const deps = task.meta.dependencies ?? [];
+		totalEdges += deps.length;
+		for (const depId of deps) dependentCount.set(depId, (dependentCount.get(depId) ?? 0) + 1);
+	}
+	const rootTasks = tasks.filter((t) => (t.meta.dependencies ?? []).length === 0);
+	const leafTasks = tasks.filter((t) => (dependentCount.get(t.meta.id) ?? 0) === 0);
+	const sortedByDeps = [...tasks].sort((a, b) => (b.meta.dependencies ?? []).length - (a.meta.dependencies ?? []).length);
+	const maxDeps = (sortedByDeps[0]?.meta.dependencies ?? []).length;
+	const mostDependentTasks = sortedByDeps.filter((t) => (t.meta.dependencies ?? []).length === maxDeps && maxDeps > 0).map((t) => t.meta.id);
+	const sortedByDependents = [...dependentCount.entries()].sort((a, b) => b[1] - a[1]);
+	const maxDependents = sortedByDependents[0]?.[1] ?? 0;
+	const mostDependendUponTasks = sortedByDependents.filter(([, count]) => count === maxDependents && maxDependents > 0).map(([id]) => id);
+	return {
+		totalTasks: tasks.length,
+		rootTasks: rootTasks.length,
+		leafTasks: leafTasks.length,
+		maxDepth: Math.max(...validation.depthMap.values(), 0),
+		totalEdges,
+		avgDependencies: tasks.length > 0 ? totalEdges / tasks.length : 0,
+		mostDependentTasks,
+		mostDependendUponTasks
+	};
+}
+/**
+* Logs graph statistics to the logger.
+*
+* @param stats - Graph statistics to log
+*/
+function logGraphStatistics(stats) {
+	logger.verbose("");
+	logger.verbose("Task Graph Statistics:");
+	logger.verbose(`Total tasks: ${stats.totalTasks}`);
+	logger.verbose(`Root tasks (can run first): ${stats.rootTasks}`);
+	logger.verbose(`Leaf tasks (final): ${stats.leafTasks}`);
+	logger.verbose(`Max depth: ${stats.maxDepth}`);
+	logger.verbose(`Avg dependencies: ${stats.avgDependencies.toFixed(2)}`);
+	if (stats.mostDependentTasks.length > 0) logger.verbose(`Most dependent tasks: ${stats.mostDependentTasks.join(", ")}`);
+	if (stats.mostDependendUponTasks.length > 0) logger.verbose(`Critical path tasks: ${stats.mostDependendUponTasks.join(", ")}`);
+	logger.verbose("");
+}
+
+//#endregion
+//#region src/commands/release/release.command.ts
+const RELEASE_SERVICES = defineServiceKeys("fs", "packageJson", "git");
+const releaseCommand = createCommand({
+	meta: {
+		name: "release",
+		description: "Automated semantic versioning, changelog generation, and GitHub release creation",
+		configSchema: ReleaseConfigSchema,
+		requiredServices: RELEASE_SERVICES
+	},
+	buildTasks(context) {
+		const groupsResult = createReleaseGroups(context.config.skipPreflightCheck === true);
+		if (groupsResult.isErr()) return FireflyErrAsync(groupsResult.error);
+		const tasks = groupsResult.value.flatMap((group) => group.tasks);
+		if (DebugFlags.showTaskGraphStats) logGraphStatistics(getGraphStatistics(tasks));
+		return FireflyOkAsync(tasks);
+	}
+});
+
+//#endregion
+//#region src/core/environment/workspace.ts
+/**
+* Represents the workspace context for CLI operations.
+*
+* The workspace provides:
+* - Centralized base path management
+* - Path resolution relative to the workspace root
+* - Consistent working directory across all services
+*
+* @example
+* ```typescript
+* // Create a workspace from current directory
+* const workspace = Workspace.current();
+*
+* // Create a workspace from explicit path
+* const workspace = Workspace.from("/path/to/project");
+*
+* // Resolve paths relative to workspace
+* const configPath = workspace.resolve("firefly.config.ts");
+* const srcPath = workspace.resolve("src", "index.ts");
+* ```
+*/
+var Workspace = class Workspace {
+	#basePath;
+	constructor(basePath) {
+		this.#basePath = path.resolve(basePath);
+	}
+	/**
+	* The absolute path to the workspace root directory.
+	*/
+	get basePath() {
+		return this.#basePath;
+	}
+	/**
+	* Alias for `basePath` - the current working directory for operations.
+	*/
+	get cwd() {
+		return this.#basePath;
+	}
+	/**
+	* Creates a workspace from the current working directory.
+	*
+	* @returns A new Workspace instance rooted at `process.cwd()`
+	*
+	* @example
+	* ```typescript
+	* const workspace = Workspace.current();
+	* console.log(workspace.basePath); // /current/working/directory
+	* ```
+	*/
+	static current() {
+		return new Workspace(process.cwd());
+	}
+	/**
+	* Creates a workspace from an explicit path.
+	*
+	* @param basePath - The root directory for the workspace
+	* @returns A new Workspace instance rooted at the specified path
+	*
+	* @example
+	* ```typescript
+	* const workspace = Workspace.from("/path/to/project");
+	* console.log(workspace.basePath); // /path/to/project
+	* ```
+	*/
+	static from(basePath) {
+		return new Workspace(basePath);
+	}
+	/**
+	* Creates a workspace from options, falling back to current directory.
+	*
+	* @param options - Optional workspace configuration
+	* @returns A new Workspace instance
+	*
+	* @example
+	* ```typescript
+	* // From CLI options
+	* const workspace = Workspace.fromOptions({ basePath: cliOptions.cwd });
+	*
+	* // Falls back to process.cwd() if basePath is undefined
+	* const workspace = Workspace.fromOptions({});
+	* ```
+	*/
+	static fromOptions(options) {
+		return options?.basePath ? Workspace.from(options.basePath) : Workspace.current();
+	}
+	/**
+	* Resolves a path relative to the workspace root.
+	*
+	* @param segments - Path segments to join and resolve
+	* @returns The absolute resolved path
+	*
+	* @example
+	* ```typescript
+	* const workspace = Workspace.from("/project");
+	*
+	* workspace.resolve("src", "index.ts");
+	* // => "/project/src/index.ts"
+	*
+	* workspace.resolve("package.json");
+	* // => "/project/package.json"
+	*
+	* // Absolute paths are returned as-is
+	* workspace.resolve("/absolute/path");
+	* // => "/absolute/path"
+	* ```
+	*/
+	resolve(...segments) {
+		const joined = path.join(...segments);
+		if (path.isAbsolute(joined)) return joined;
+		return path.join(this.#basePath, joined);
+	}
+	/**
+	* Checks if a path is within the workspace boundaries.
+	*
+	* @param targetPath - The path to check
+	* @returns `true` if the path is within the workspace
+	*
+	* @example
+	* ```typescript
+	* const workspace = Workspace.from("/project");
+	*
+	* workspace.contains("/project/src/file.ts"); // true
+	* workspace.contains("/other/path"); // false
+	* ```
+	*/
+	contains(targetPath) {
+		return path.resolve(targetPath).startsWith(this.#basePath);
+	}
+	/**
+	* Returns a string representation of the workspace.
+	*/
+	toString() {
+		return `Workspace(${this.#basePath})`;
+	}
+	/**
+	* Returns the workspace as a JSON-serializable object.
+	*/
+	toJSON() {
+		return { basePath: this.#basePath };
+	}
+};
+
+//#endregion
+//#region src/core/context/workflow.context.ts
+/**
+* Immutable implementation of WorkflowContext.
+*
+* @template TConfig - Type of the workflow configuration
+* @template TData - Type of the accumulated workflow data
+* @template TServices - Type of the resolved services
+*
+* @example Creating a workflow context
+* ```typescript
+* type Config = { projectName: string; verbose: boolean };
+* type Data = { files: string[]; processedCount: number };
+*
+* const ctx = ImmutableWorkflowContext.create<Config, Data>(
+*   { projectName: "my-app", verbose: true },
+*   resolvedServices,
+*   { files: [], processedCount: 0 }
+* );
+* ```
+*/
+var ImmutableWorkflowContext = class ImmutableWorkflowContext {
+	startTime;
+	workspace;
+	config;
+	services;
+	/**
+	* Internal data - frozen on access via snapshot()
+	*/
+	#data;
+	/**
+	* Cached frozen snapshot
+	*/
+	#frozenData = null;
+	get [Symbol.toStringTag]() {
+		return "WorkflowContext";
+	}
+	constructor(options) {
+		this.startTime = options.startTime;
+		this.workspace = options.workspace;
+		this.config = options.config;
+		this.#data = options.data;
+		this.services = options.services;
+	}
+	/**
+	* Provides read-only access to data with lazy freezing
+	*/
+	get data() {
+		this.#frozenData ??= Object.freeze({ ...this.#data });
+		return this.#frozenData;
+	}
+	/**
+	* Creates a new workflow context.
+	*
+	* @template TC - Configuration type
+	* @template TD - Data type
+	* @template TS - Services type
+	* @param config - Workflow configuration
+	* @param services - Resolved services
+	* @param initialData - Optional initial data values
+	*
+	* @example Without initial data
+	* ```typescript
+	* const ctx = ImmutableWorkflowContext.create(
+	*   { version: "1.0.0" },
+	*   services
+	* );
+	* ```
+	*
+	* @example With initial data
+	* ```typescript
+	* const ctx = ImmutableWorkflowContext.create(
+	*   { version: "1.0.0" },
+	*   services,
+	*   { buildNumber: 42, artifacts: [] }
+	* );
+	* ```
+	*/
+	static create(config, services, initialData, workspace) {
+		return new ImmutableWorkflowContext({
+			startTime: /* @__PURE__ */ new Date(),
+			workspace: workspace ?? Workspace.current(),
+			config: Object.freeze({ ...config }),
+			data: initialData ?? {},
+			services
+		});
+	}
+	/**
+	* @example Safely retrieving a value
+	* ```typescript
+	* const versionResult = ctx.get("version");
+	* if (versionResult.isOk()) {
+	*   console.log(`Processing version: ${versionResult.value}`);
+	* }
+	* ```
+	*
+	* @example Handling missing keys
+	* ```typescript
+	* const result = ctx.get("optionalField");
+	* if (result.isErr()) {
+	*   // Key doesn't exist - use default or handle error
+	*   return FireflyOkAsync(ctx.fork("optionalField", defaultValue));
+	* }
+	* ```
+	*/
+	get(key) {
+		if (!(key in this.#data)) return validationErr({ message: `Key "${String(key)}" not found in context` });
+		return FireflyOk(this.#data[key]);
+	}
+	/**
+	* @example Updating a single value
+	* ```typescript
+	* const updatedCtx = ctx.fork("status", "completed");
+	* ```
+	*
+	* @example Chaining forks
+	* ```typescript
+	* const finalCtx = ctx
+	*   .fork("startedAt", new Date())
+	*   .fork("status", "in-progress");
+	* ```
+	*
+	* @example No-op when value is identical (returns same instance)
+	* ```typescript
+	* const ctx1 = ctx.fork("count", 5);
+	* const ctx2 = ctx1.fork("count", 5);
+	* console.log(ctx1 === ctx2); // true - same reference
+	* ```
+	*/
+	fork(key, value) {
+		if (this.#data[key] === value) return this;
+		const updatedData = {
+			...this.#data,
+			[key]: value
+		};
+		return new ImmutableWorkflowContext({
+			startTime: this.startTime,
+			workspace: this.workspace,
+			config: this.config,
+			data: updatedData,
+			services: this.services
+		});
+	}
+	forkMultiple(updates) {
+		const updateKeys = Object.keys(updates);
+		if (updateKeys.length === 0) return this;
+		if (!updateKeys.some((key) => this.#data[key] !== updates[key])) return this;
+		const updatedData = {
+			...this.#data,
+			...updates
+		};
+		return new ImmutableWorkflowContext({
+			startTime: this.startTime,
+			workspace: this.workspace,
+			config: this.config,
+			data: updatedData,
+			services: this.services
+		});
+	}
+	has(key) {
+		return key in this.#data;
+	}
+	snapshot() {
+		return this.data;
+	}
+};
+
+//#endregion
+//#region src/core/execution/workflow.executor.ts
+/**
+* Executes workflow tasks in sequence with error handling and rollback.
+*
+* The executor:
+* 1. Runs tasks sequentially, passing updated context between them
+* 2. Evaluates skip conditions before each task
+* 3. Tracks executed tasks for potential rollback
+* 4. On failure, optionally rolls back completed tasks in reverse order
+*
+* @example
+* ```typescript
+* const executor = new WorkflowExecutor({
+*   dryRun: false,
+*   enableRollback: true,
+* });
+*
+* const result = await executor.execute(orderedTasks, context);
+*
+* if (result.isOk() && result.value.success) {
+*   console.log(`Executed ${result.value.executedTasks.length} tasks`);
+* } else {
+*   console.error(`Failed at task: ${result.value.failedTask}`);
+* }
+* ```
+*/
+var WorkflowExecutor = class {
+	options;
+	executedTasks = [];
+	/** Resolved AbortSignal for cancellation */
+	#signal;
+	get [Symbol.toStringTag]() {
+		return "WorkflowExecutor";
+	}
+	constructor(options = {}) {
+		this.options = options;
+		this.#signal = options.signal ?? (options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : void 0);
+	}
+	/**
+	* Executes a sequence of tasks with the given initial context.
+	*
+	* @param tasks - Ordered array of tasks to execute
+	* @param initialContext - Starting workflow context
+	* @returns Execution result with success/failure status and metadata
+	*/
+	execute(tasks, initialContext) {
+		const startTime = /* @__PURE__ */ new Date();
+		const executedTaskIds = [];
+		const skippedTaskIds = [];
+		if (this.options.dryRun) logger.warn("Workflow executing in DRY RUN mode - no actual changes will be made");
+		logger.verbose(`WorkflowExecutor: Starting execution of ${tasks.length} tasks`);
+		return this.executeTasksSequentially(tasks, initialContext, executedTaskIds, skippedTaskIds).andThen(() => this.buildExecutionSuccessResult(startTime, executedTaskIds, skippedTaskIds)).orElse((error) => this.handleExecutionFailure({
+			error,
+			startTime,
+			executedTaskIds,
+			skippedTaskIds,
+			initialContext
+		}));
+	}
+	buildExecutionSuccessResult(startTime, executedTaskIds, skippedTaskIds) {
+		const endTime = /* @__PURE__ */ new Date();
+		const result = {
+			success: true,
+			executedTasks: executedTaskIds,
+			skippedTasks: skippedTaskIds,
+			rollbackExecuted: false,
+			startTime,
+			endTime,
+			executionTimeMs: endTime.getTime() - startTime.getTime()
+		};
+		logger.verbose("WorkflowExecutor: Execution completed successfully");
+		logger.verbose(`WorkflowExecutor: Executed: ${executedTaskIds.length}, Skipped: ${skippedTaskIds.length}, Time: ${result.executionTimeMs}ms`);
+		return FireflyOkAsync(result);
+	}
+	handleExecutionFailure(args) {
+		const { error, startTime, executedTaskIds, skippedTaskIds, initialContext } = args;
+		const endTime = /* @__PURE__ */ new Date();
+		if (this.options.enableRollback && this.executedTasks.length > 0) {
+			logger.verbose(`WorkflowExecutor: Attempting rollback of ${this.executedTasks.length} tasks`);
+			return this.rollback(initialContext).andThen((rollbackSuccess) => {
+				return FireflyOkAsync({
+					success: false,
+					executedTasks: executedTaskIds,
+					skippedTasks: skippedTaskIds,
+					failedTask: executedTaskIds.at(-1) || "unknown",
+					error,
+					rollbackExecuted: rollbackSuccess,
+					startTime,
+					endTime,
+					executionTimeMs: endTime.getTime() - startTime.getTime()
+				});
+			});
+		}
+		return FireflyOkAsync({
+			success: false,
+			executedTasks: executedTaskIds,
+			skippedTasks: skippedTaskIds,
+			failedTask: executedTaskIds.at(-1) || "unknown",
+			error,
+			rollbackExecuted: false,
+			startTime,
+			endTime,
+			executionTimeMs: endTime.getTime() - startTime.getTime()
+		});
+	}
+	executeTasksSequentially(tasks, context, executedTaskIds, skippedTaskIds) {
+		if (tasks.length === 0) return FireflyOkAsync(void 0);
+		if (this.#signal?.aborted) return timeoutErrAsync({ message: "Workflow execution was aborted" });
+		const [currentTask, ...remainingTasks] = tasks;
+		if (!currentTask) return FireflyOkAsync(void 0);
+		const skipCheck = this.handleTaskSkip(currentTask, remainingTasks, context, skippedTaskIds);
+		if (skipCheck.isErr()) return FireflyErrAsync(skipCheck.error);
+		if (skipCheck.value.shouldSkip) return this.executeTasksSequentially(skipCheck.value.newRemainingTasks, context, executedTaskIds, skippedTaskIds);
+		return this.executeTaskAndContinue(currentTask, remainingTasks, context, {
+			executedTaskIds,
+			skippedTaskIds
+		});
+	}
+	handleTaskSkip(currentTask, remainingTasks, context, skippedTaskIds) {
+		if (!currentTask.shouldSkip) return FireflyOk({
+			shouldSkip: false,
+			newRemainingTasks: remainingTasks
+		});
+		const skipResult = currentTask.shouldSkip(context);
+		if (skipResult.isErr()) return FireflyErr(skipResult.error);
+		if (!skipResult.value.shouldSkip) return FireflyOk({
+			shouldSkip: false,
+			newRemainingTasks: remainingTasks
+		});
+		const reason = skipResult.value.reason || "condition not met";
+		logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Skipped - ${reason}`);
+		skippedTaskIds.push(currentTask.meta.id);
+		if (skipResult.value.skipToTasks && skipResult.value.skipToTasks.length > 0) {
+			logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Skipping through to ${skipResult.value.skipToTasks.join(", ")}`);
+			const skipToIndex = remainingTasks.findIndex((t) => skipResult.value.skipToTasks?.includes(t.meta.id));
+			if (skipToIndex >= 0) return FireflyOk({
+				shouldSkip: true,
+				newRemainingTasks: remainingTasks.slice(skipToIndex)
+			});
+		}
+		return FireflyOk({
+			shouldSkip: true,
+			newRemainingTasks: remainingTasks
+		});
+	}
+	executeTaskAndContinue(currentTask, remainingTasks, context, executionLists) {
+		logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Executing...`);
+		return currentTask.execute(context).andThen((updatedContext) => {
+			logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Completed`);
+			executionLists.executedTaskIds.push(currentTask.meta.id);
+			this.executedTasks.push(currentTask);
+			return this.executeTasksSequentially(remainingTasks, updatedContext, executionLists.executedTaskIds, executionLists.skippedTaskIds);
+		}).mapErr((error) => {
+			logger.error(error.message);
+			return error;
+		});
+	}
+	rollback(context) {
+		const tasksToRollback = this.executedTasks.toReversed();
+		logger.verbose(`WorkflowExecutor: Rolling back ${tasksToRollback.length} tasks in reverse order`);
+		return this.rollbackTasks(tasksToRollback, context).andThen((errors) => {
+			if (errors.length > 0) {
+				logger.error(`Rollback completed with ${errors.length} errors`);
+				for (const { taskId, error } of errors) logger.error(`  Task '${taskId}': ${error.message}`);
+				return FireflyOkAsync(false);
+			}
+			logger.verbose("WorkflowExecutor: Rollback completed successfully");
+			return FireflyOkAsync(true);
+		});
+	}
+	rollbackTasks(tasks, context) {
+		if (tasks.length === 0) return FireflyOkAsync([]);
+		const [currentTask, ...remainingTasks] = tasks;
+		const errors = [];
+		if (!currentTask) return FireflyOkAsync([]);
+		if (!currentTask.undo) {
+			logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': No undo available, skipping rollback`);
+			return this.rollbackTasks(remainingTasks, context);
+		}
+		logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Rolling back...`);
+		return currentTask.undo(context).andThen(() => {
+			logger.verbose(`WorkflowExecutor: Task '${currentTask.meta.id}': Rollback completed`);
+			return this.rollbackTasks(remainingTasks, context);
+		}).orElse((error) => {
+			logger.error(`Task '${currentTask.meta.id}': Rollback failed - ${error.message}`);
+			errors.push({
+				taskId: currentTask.meta.id,
+				error
+			});
+			return this.rollbackTasks(remainingTasks, context).map((remainingErrors) => [...errors, ...remainingErrors]);
+		});
+	}
+};
+
+//#endregion
+//#region src/core/registry/base.registry.ts
+/**
+* Abstract base class providing common registry functionality.
+*
+* Implements the registry pattern with:
+* - Type-safe item storage and retrieval
+* - Duplicate detection with configurable error codes
+* - Batch registration with fail-fast semantics
+* - Standard CRUD-like operations (register, get, has, clear)
+*
+* @template T - The type of items stored in the registry
+* @template K - The key type used to identify items (defaults to string)
+*
+* @example
+* ```typescript
+* interface User { id: string; name: string; }
+*
+* class UserRegistry extends BaseRegistry<User> {
+*   constructor() {
+*     super({
+*       name: "User",
+*       source: "UserRegistry",
+*       getKey: (user) => user.id,
+*     });
+*   }
+* }
+* ```
+*/
+var BaseRegistry = class {
+	/** Internal storage for registry items */
+	items = /* @__PURE__ */ new Map();
+	/** Configuration for this registry instance */
+	config;
+	/**
+	* Custom string tag for better debugging output.
+	* Displays as [object {name}Registry] instead of [object Object].
+	*/
+	get [Symbol.toStringTag]() {
+		return `${this.config.name}Registry`;
+	}
+	/**
+	* Creates a new registry instance.
+	* @param config - Configuration options for the registry
+	*/
+	constructor(config) {
+		this.config = {
+			duplicateErrorCode: "CONFLICT",
+			notFoundErrorCode: "NOT_FOUND",
+			...config
+		};
+	}
+	/**
+	* Registers a single item in the registry.
+	*
+	* @param item - The item to register
+	* @returns `Ok(void)` on success, `Err(FireflyError)` if duplicate detected
+	*
+	* @example
+	* ```typescript
+	* const result = registry.register({ id: "task-1", name: "My Task" });
+	* if (result.isErr()) {
+	*   console.error(result.error.message);
+	* }
+	* ```
+	*/
+	register(item) {
+		const key = this.config.getKey(item);
+		if (this.items.has(key)) return FireflyErr(this.config.duplicateErrorCode === "CONFLICT" ? conflictError({
+			message: `${this.config.name} "${key}" is already registered`,
+			source: this.config.source
+		}) : notFoundError({
+			message: `${this.config.name} "${key}" is already registered`,
+			source: this.config.source
+		}));
+		this.items.set(key, item);
+		return ok();
+	}
+	/**
+	* Registers multiple items in sequence.
+	* Stops on first error (fail-fast semantics).
+	*
+	* @param items - Array of items to register
+	* @returns `Ok(void)` if all items registered, `Err(FireflyError)` on first failure
+	*/
+	registerAll(items) {
+		for (const item of items) {
+			const result = this.register(item);
+			if (result.isErr()) return result;
+		}
+		return ok();
+	}
+	/**
+	* Retrieves an item by its key.
+	*
+	* @param key - The unique identifier of the item
+	* @returns `Ok(T)` if found, `Err(FireflyError)` if not found
+	*/
+	get(key) {
+		const item = this.items.get(key);
+		if (!item) return FireflyErr(notFoundError({
+			message: `${this.config.name} "${key}" not found in registry`,
+			source: this.config.source
+		}));
+		return ok(item);
+	}
+	/**
+	* Returns all registered items as an array.
+	* @returns Array of all items in registration order
+	*/
+	getAll() {
+		return Array.from(this.items.values());
+	}
+	/**
+	* Returns all registered keys.
+	* @returns Array of all keys in registration order
+	*/
+	getKeys() {
+		return Array.from(this.items.keys());
+	}
+	/**
+	* Checks if an item with the given key exists.
+	* @param key - The key to check
+	* @returns `true` if the item exists, `false` otherwise
+	*/
+	has(key) {
+		return this.items.has(key);
+	}
+	/**
+	* Returns the number of registered items.
+	* @returns The count of items in the registry
+	*/
+	size() {
+		return this.items.size;
+	}
+	/**
+	* Removes all items from the registry.
+	*/
+	clear() {
+		this.items.clear();
+	}
+};
+
+//#endregion
+//#region src/core/task/task-group.types.ts
+/**
+* Separator used between group ID and task ID.
+*/
+const GROUP_TASK_SEPARATOR = ":";
+/**
+* Creates a namespaced task ID from a group ID and task ID.
+*
+* @param groupId - The group's unique identifier
+* @param taskId - The task's unique identifier within the group
+* @returns Namespaced ID in format `groupId:taskId`
+*
+* @example
+* ```typescript
+* const id = createNamespacedTaskId("git", "commit");
+* // Returns "git:commit"
+* ```
+*/
+function createNamespacedTaskId(groupId, taskId) {
+	return `${groupId}${GROUP_TASK_SEPARATOR}${taskId}`;
+}
+
+//#endregion
+//#region src/core/task/task-group.expansion.ts
+/**
+* Expands a task group into individual tasks with namespaced IDs.
+*
+* This function:
+* 1. Prefixes each task ID with the group ID (e.g., "group:task")
+* 2. Updates task dependencies to use namespaced IDs
+* 3. Merges group skip condition with each task's skip condition
+* 4. Adds inter-group dependencies to the first task in the group
+*
+* @param group - The task group to expand
+* @param registeredGroups - Map of already registered group IDs to their last task IDs
+* @returns Expanded tasks with namespaced IDs and merged skip conditions
+*
+* @example
+* ```typescript
+* const result = expandTaskGroup(gitGroup, new Map([["changelog", "changelog:generate"]]));
+* if (result.isOk()) {
+*   for (const task of result.value.tasks) {
+*     registry.register(task);
+*   }
+* }
+* ```
+*/
+function expandTaskGroup(group, registeredGroups) {
+	const groupId = group.meta.id;
+	const expansionContext = {
+		groupId,
+		groupSkipCondition: buildGroupSkipCondition(group),
+		taskIdMapping: /* @__PURE__ */ new Map(),
+		registeredGroups,
+		dependsOnGroups: group.meta.dependsOnGroups
+	};
+	const expandedTasksResult = expandTasks(group.tasks, expansionContext);
+	if (expandedTasksResult.isErr()) return FireflyErr(expandedTasksResult.error);
+	return FireflyOk({
+		groupId,
+		tasks: expandedTasksResult.value,
+		taskIdMapping: expansionContext.taskIdMapping
+	});
+}
+/**
+* Expands an array of tasks within a group context.
+*
+* @param tasks - The tasks to expand
+* @param ctx - The expansion context containing group metadata
+* @returns Array of expanded tasks with namespaced IDs
+*/
+function expandTasks(tasks, ctx) {
+	const expandedTasks = [];
+	for (let i = 0; i < tasks.length; i++) {
+		const task = tasks[i];
+		if (!task) continue;
+		const result = expandSingleTask(task, i, ctx);
+		if (result.isErr()) return FireflyErr(result.error);
+		expandedTasks.push(result.value);
+	}
+	return FireflyOk(expandedTasks);
+}
+/**
+* Expands a single task with namespace prefixing and dependency resolution.
+*
+* @param task - The task to expand
+* @param index - Position of the task within the group (0-based)
+* @param ctx - The expansion context
+* @returns The expanded task with namespaced ID and resolved dependencies
+*/
+function expandSingleTask(task, index, ctx) {
+	const { groupId, groupSkipCondition, taskIdMapping, registeredGroups, dependsOnGroups } = ctx;
+	const originalTaskId = task.meta.id;
+	const namespacedId = createNamespacedTaskId(groupId, originalTaskId);
+	taskIdMapping.set(originalTaskId, namespacedId);
+	const remappedDependencies = remapDependencies(task.meta.dependencies ?? [], taskIdMapping, groupId);
+	if (index === 0 && dependsOnGroups) {
+		const interGroupResult = addInterGroupDependencies(dependsOnGroups, registeredGroups, groupId);
+		if (interGroupResult.isErr()) return FireflyErr(interGroupResult.error);
+		remappedDependencies.push(...interGroupResult.value);
+	}
+	return FireflyOk(createExpandedTask({
+		originalTask: task,
+		namespacedId,
+		originalTaskId,
+		groupId,
+		dependencies: remappedDependencies,
+		groupSkipCondition
+	}));
+}
+/**
+* Resolves inter-group dependencies to their last task IDs.
+*
+* When a group depends on other groups, the first task in the group
+* needs to depend on the last task of each dependency group.
+*
+* @param dependsOnGroups - Array of group IDs this group depends on
+* @param registeredGroups - Map of registered groups to their last task IDs
+* @param groupId - Current group ID (for error messages)
+* @returns Array of namespaced task IDs to depend on, or error if dependency not found
+*/
+function addInterGroupDependencies(dependsOnGroups, registeredGroups, groupId) {
+	const deps = [];
+	for (const depGroupId of dependsOnGroups) {
+		const lastTaskOfDepGroup = registeredGroups.get(depGroupId);
+		if (!lastTaskOfDepGroup) return FireflyErr(validationError({
+			message: `Group "${groupId}" depends on group "${depGroupId}" which is not registered`,
+			source: "expandTaskGroup"
+		}));
+		deps.push(lastTaskOfDepGroup);
+	}
+	return FireflyOk(deps);
+}
+/**
+* Builds a unified skip condition from group options.
+*
+* If a full `skipCondition` is provided, it's used directly.
+* If only `skipWhen` predicate is provided, it's converted to a full skip condition.
+*
+* @param group - The task group to extract skip condition from
+* @returns The group's skip condition function, or undefined if none configured
+*/
+function buildGroupSkipCondition(group) {
+	const { options } = group;
+	if (!options) return;
+	const { skipCondition, skipWhen, skipReason } = options;
+	if (skipCondition) return skipCondition;
+	if (skipWhen) return (ctx) => FireflyOk({
+		shouldSkip: skipWhen(ctx),
+		reason: skipReason ?? `Group "${group.meta.id}" skip condition met`
+	});
+}
+/**
+* Remaps task dependencies to use namespaced IDs.
+*
+* Handles three cases:
+* 1. Dependency already processed in this group → use mapped namespaced ID
+* 2. Dependency already namespaced (cross-group) → use as-is
+* 3. Dependency not yet processed → assume same group, create namespaced ID
+*
+* @param originalDeps - Original dependency IDs from the task
+* @param taskIdMapping - Map of processed task IDs to their namespaced versions
+* @param groupId - Current group ID for namespacing
+* @returns Array of remapped dependency IDs
+*/
+function remapDependencies(originalDeps, taskIdMapping, groupId) {
+	return originalDeps.map((dep) => {
+		const namespacedDep = taskIdMapping.get(dep);
+		if (namespacedDep) return namespacedDep;
+		if (dep.includes(":")) return dep;
+		return createNamespacedTaskId(groupId, dep);
+	});
+}
+/**
+* Creates an expanded task with merged skip condition.
+*
+* The expanded task preserves the original task's execute and undo functions
+* while updating metadata and merging skip conditions.
+*
+* @param opts - Options containing original task and expansion metadata
+* @returns The expanded task with namespaced ID and merged properties
+*/
+function createExpandedTask(opts) {
+	const { originalTask, namespacedId, originalTaskId, groupId, dependencies, groupSkipCondition } = opts;
+	const mergedSkipCondition = mergeSkipConditions(originalTask.shouldSkip, groupSkipCondition);
+	return {
+		meta: {
+			...originalTask.meta,
+			id: namespacedId,
+			dependencies: dependencies.length > 0 ? dependencies : void 0
+		},
+		shouldSkip: mergedSkipCondition,
+		execute: originalTask.execute,
+		undo: originalTask.undo,
+		originalTaskId,
+		groupId,
+		groupSkipCondition
+	};
+}
+/**
+* Merges a group skip condition with a task's own skip condition.
+*
+* The group condition is evaluated first. If it returns `shouldSkip: true`,
+* the task is skipped without evaluating its own condition.
+* This allows groups to skip all their tasks with a single condition.
+*
+* @param taskSkipCondition - The task's original skip condition (if any)
+* @param groupSkipCondition - The group's skip condition (if any)
+* @returns Merged skip condition function, or undefined if neither exists
+*/
+function mergeSkipConditions(taskSkipCondition, groupSkipCondition) {
+	if (!groupSkipCondition) return taskSkipCondition;
+	if (!taskSkipCondition) return groupSkipCondition;
+	return (ctx) => {
+		const groupResult = groupSkipCondition(ctx);
+		if (groupResult.isErr()) return groupResult;
+		if (groupResult.value.shouldSkip) return groupResult;
+		return taskSkipCondition(ctx);
+	};
+}
+/**
+* Creates an empty group registry for tracking registered groups.
+*
+* The registry tracks:
+* - Which groups have been registered
+* - The last task ID of each group (for inter-group dependencies)
+* - All task IDs belonging to each group
+*
+* @returns Empty group registry
+*
+* @example
+* ```typescript
+* const registry = createGroupRegistry();
+* // Register groups and update registry...
+* ```
+*/
+function createGroupRegistry() {
+	return {
+		lastTaskByGroup: /* @__PURE__ */ new Map(),
+		tasksByGroup: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* Updates the group registry with a newly expanded group.
+*
+* Records all task IDs for the group and stores the last task ID
+* to enable inter-group dependency resolution.
+*
+* @param registry - The group registry to update
+* @param expandedResult - The result of expanding a task group
+*
+* @example
+* ```typescript
+* const expandResult = expandTaskGroup(group, registry.lastTaskByGroup);
+* if (expandResult.isOk()) {
+*   updateGroupRegistry(registry, expandResult.value);
+* }
+* ```
+*/
+function updateGroupRegistry(registry, expandedResult) {
+	const { groupId, tasks } = expandedResult;
+	if (tasks.length === 0) return;
+	const taskIds = tasks.map((t) => t.meta.id);
+	registry.tasksByGroup.set(groupId, taskIds);
+	const lastTask = tasks.at(-1);
+	if (lastTask) registry.lastTaskByGroup.set(groupId, lastTask.meta.id);
+}
+
+//#endregion
+//#region src/core/registry/task.registry.ts
+/**
+* Registry for managing workflow tasks with dependency validation.
+*
+* @example
+* ```typescript
+* const registry = new TaskRegistry();
+*
+* // Register tasks (dependencies must be registered first)
+* registry.register(taskA);
+* registry.register(taskB); // If taskB depends on taskA, taskA must exist
+*
+* // Or register a group of related tasks
+* registry.registerGroup(gitGroup);
+*
+* // Iterate directly in execution order using for-of
+* const orderResult = registry.buildExecutionOrder();
+* if (orderResult.isFireflyOk()) {
+*   for (const task of orderResult.value) {
+*     await task.execute(context);
+*   }
+* }
+*
+* // Or use spread operator
+* const tasks = [...registry];
+* ```
+*/
+var TaskRegistry = class extends BaseRegistry {
+	groupRegistry;
+	constructor() {
+		super({
+			name: "Task",
+			source: "TaskRegistry",
+			getKey: (task) => task.meta.id,
+			duplicateErrorCode: "VALIDATION",
+			notFoundErrorCode: "VALIDATION"
+		});
+		this.groupRegistry = createGroupRegistry();
+	}
+	get [Symbol.toStringTag]() {
+		return "TaskRegistry";
+	}
+	/**
+	* Implements Symbol.iterator for direct iteration over tasks in execution order.
+	* Uses a generator for lazy topological traversal.
+	*
+	* @yields Tasks in dependency-respecting execution order
+	* @throws If circular dependency is detected
+	*
+	* @example
+	* ```typescript
+	* for (const task of registry) {
+	*   console.log(task.meta.id);
+	* }
+	*
+	* // Or spread into array
+	* const tasks = [...registry];
+	* ```
+	*/
+	*[Symbol.iterator]() {
+		const visited = /* @__PURE__ */ new Set();
+		const recursionStack = /* @__PURE__ */ new Set();
+		const visit = function* (taskId) {
+			if (recursionStack.has(taskId)) throw new Error(`Circular dependency detected involving task "${taskId}"`);
+			if (visited.has(taskId)) return;
+			const task = this.items.get(taskId);
+			if (!task) return;
+			recursionStack.add(taskId);
+			for (const depId of task.meta.dependencies ?? []) yield* visit.call(this, depId);
+			recursionStack.delete(taskId);
+			visited.add(taskId);
+			yield task;
+		};
+		for (const taskId of this.items.keys()) yield* visit.call(this, taskId);
+	}
+	/**
+	* Registers a task after validating its dependencies exist.
+	*
+	* @param task - The task to register
+	* @returns `FireflyOk(void)` on success, `Err(FireflyError)` if duplicate or missing dependency
+	* @override
+	*/
+	register(task) {
+		if (this.items.has(task.meta.id)) return validationErr({ message: `Task "${task.meta.id}" is already registered` });
+		for (const depId of task.meta.dependencies ?? []) if (!this.items.has(depId)) return validationErr({ message: `Task "${task.meta.id}" depends on "${depId}" which is not registered` });
+		this.items.set(task.meta.id, task);
+		return FireflyOk(void 0);
+	}
+	/**
+	* Registers a task group, expanding it into individual tasks with namespaced IDs.
+	*
+	* This method:
+	* 1. Expands the group into individual tasks with `groupId:taskId` format
+	* 2. Merges group skip conditions with task-level skip conditions
+	* 3. Resolves inter-group dependencies
+	* 4. Registers all expanded tasks
+	*
+	* @param group - The task group to register
+	* @returns `FireflyOk(void)` on success, `Err(FireflyError)` if validation fails
+	*
+	* @example
+	* ```typescript
+	* const gitGroup = buildTaskGroup("git")
+	*   .description("Git operations")
+	*   .skipWhen((ctx) => ctx.config.skipGit)
+	*   .tasks([stageTask, commitTask, tagTask])
+	*   .build();
+	*
+	* if (gitGroup.isFireflyOk()) {
+	*   registry.registerGroup(gitGroup.value);
+	* }
+	* ```
+	*/
+	registerGroup(group) {
+		if (this.groupRegistry.lastTaskByGroup.has(group.meta.id)) return validationErr({ message: `Task group "${group.meta.id}" is already registered` });
+		const expandResult = expandTaskGroup(group, this.groupRegistry.lastTaskByGroup);
+		if (expandResult.isErr()) return err(expandResult.error);
+		for (const task of expandResult.value.tasks) {
+			const registerResult = this.register(task);
+			if (registerResult.isErr()) return registerResult;
+		}
+		updateGroupRegistry(this.groupRegistry, expandResult.value);
+		return FireflyOk(void 0);
+	}
+	/**
+	* Registers multiple task groups in order.
+	*
+	* Groups are registered sequentially, allowing later groups to depend on earlier ones.
+	*
+	* @param groups - Array of task groups to register
+	* @returns `FireflyOk(void)` on success, `Err(FireflyError)` if any registration fails
+	*/
+	registerGroups(groups) {
+		for (const group of groups) {
+			const result = this.registerGroup(group);
+			if (result.isErr()) return result;
+		}
+		return FireflyOk(void 0);
+	}
+	/**
+	* Gets all task IDs belonging to a specific group.
+	*
+	* @param groupId - The group ID to query
+	* @returns Array of namespaced task IDs, or empty array if group not found
+	*/
+	getGroupTaskIds(groupId) {
+		return this.groupRegistry.tasksByGroup.get(groupId) ?? [];
+	}
+	/**
+	* Gets all registered group IDs.
+	*
+	* @returns Array of group IDs in registration order
+	*/
+	getGroupIds() {
+		return [...this.groupRegistry.lastTaskByGroup.keys()];
+	}
+	/**
+	* Checks if a group has been registered.
+	*
+	* @param groupId - The group ID to check
+	* @returns True if the group is registered
+	*/
+	hasGroup(groupId) {
+		return this.groupRegistry.lastTaskByGroup.has(groupId);
+	}
+	/**
+	* Builds an execution order that respects task dependencies.
+	* @returns `FireflyOk(Task[])` with tasks in execution order, `Err(FireflyError)` if circular dependency detected
+	*/
+	buildExecutionOrder() {
+		const sortResult = topologicalSort([...this.items.values()]);
+		if (sortResult.isErr()) return err(sortResult.error);
+		const orderedTasks = [];
+		for (const taskId of sortResult.value) {
+			const task = this.items.get(taskId);
+			if (task) orderedTasks.push(task);
+		}
+		return FireflyOk(orderedTasks);
+	}
+};
+
+//#endregion
+//#region src/core/service/service.proxy.ts
+/**
+* Creates a new resolution context for tracking service instantiation.
+* @internal
+*/
+function createResolutionContext(basePath) {
+	return {
+		basePath,
+		resolving: /* @__PURE__ */ new Set(),
+		resolved: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* Resolves a service within a resolution context, with circular dependency detection.
+* @internal
+*/
+async function resolveServiceWithContext(key, context) {
+	const cached = context.resolved.get(key);
+	if (cached) return cached;
+	if (context.resolving.has(key)) {
+		const chain = [...context.resolving, key].join(" -> ");
+		return Promise.reject(/* @__PURE__ */ new Error(`Circular service dependency detected:  ${chain}`));
+	}
+	context.resolving.add(key);
+	const definition = SERVICE_DEFINITIONS[key];
+	const factoryContext = {
+		basePath: context.basePath,
+		getService: (depKey) => resolveServiceWithContext(depKey, context)
+	};
+	const instance = await definition.factory(factoryContext);
+	context.resolving.delete(key);
+	context.resolved.set(key, instance);
+	return instance;
+}
+/**
+* Creates a lazy proxy that defers async service instantiation until first access.
+*
+* @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
+* @internal
+*/
+function createLazyServiceProxy(factory) {
+	let instancePromise;
+	let instance;
+	const ensureInstance = async () => {
+		if (instance) return instance;
+		instancePromise ??= factory();
+		instance = await instancePromise;
+		return instance;
+	};
+	return new Proxy({}, {
+		get(_target, prop, receiver) {
+			return (...args) => ResultAsync.fromSafePromise(ensureInstance()).andThen((resolved) => {
+				const value = Reflect.get(resolved, prop, receiver);
+				return typeof value === "function" ? value.apply(resolved, args) : value;
+			});
+		},
+		has(_target, prop) {
+			if (instance) return Reflect.has(instance, prop);
+			return true;
+		},
+		ownKeys(_target) {
+			if (instance) return Reflect.ownKeys(instance);
+			return [];
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			return instance ? Reflect.getOwnPropertyDescriptor(instance, prop) : void 0;
+		}
+	});
+}
+/**
+* Resolves a specific set of services for use in a workflow context.
+*
+* @template TKeys - Tuple type of service keys to resolve
+* @param requiredServices - Array of service keys to resolve
+* @param basePath - Base path passed to service factories (usually the project root)
+* @returns Object containing the resolved services
+*
+* @example
+* ```typescript
+* const services = resolveServices(["fs", "git"] as const, "/path/to/project");
+* await services.fs.read("package.json");
+* ```
+*/
+function resolveServices(requiredServices, basePath) {
+	const resolved = {};
+	const context = createResolutionContext(basePath);
+	for (const key of requiredServices) resolved[key] = createLazyServiceProxy(() => resolveServiceWithContext(key, context));
+	return resolved;
+}
+
+//#endregion
+//#region src/core/execution/workflow.orchestrator.ts
+/**
+* Orchestrates the execution of workflow commands.
+* The orchestrator is the main entry point for executing commands.
+*
+* It coordinates:
+* - Service resolution based on command requirements
+* - Context creation with configuration and initial data
+* - Task building, registration, and dependency ordering
+* - Command lifecycle hook execution
+* - Delegation to WorkflowExecutor for task execution
+*
+* @example
+* ```typescript
+* const orchestrator = new WorkflowOrchestrator({
+*   basePath: "/path/to/project",
+*   dryRun: false,
+*   enableRollback: true,
+* });
+*
+* const result = await orchestrator.executeCommand(
+*   releaseCommand,
+*   { version: "1.0.0", changelog: true },
+*   { previousVersion: "0.9.0" }
+* );
+*
+* if (result.isOk() && result.value.success) {
+*   console.log("Release completed successfully!");
+* }
+* ```
+*/
+var WorkflowOrchestrator = class {
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	/**
+	* Executes a command with the given configuration.
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command to execute
+	* @param config - Configuration for the command
+	* @param initialData - Optional initial data values
+	* @returns Execution result with success/failure status
+	*/
+	executeCommand(command, config, initialData) {
+		logger.verbose(`WorkflowOrchestrator: Executing command "${command.meta.name}"`);
+		const context = this.createContext(command, config, initialData);
+		return this.runCommandLifecycle(command, context);
+	}
+	/**
+	* Creates a workflow context with resolved services for the command.
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command for which to create the context
+	* @param config - Configuration for the command
+	* @param initialData - Optional initial data values
+	* @returns The constructed workflow context
+	*/
+	createContext(command, config, initialData) {
+		const workspace = this.options.workspace ?? Workspace.current();
+		const requiredServices = command.meta.requiredServices;
+		const services = resolveServices(requiredServices, workspace.basePath);
+		logger.verbose(`WorkflowOrchestrator: Resolved services: [${requiredServices.join(", ")}]`);
+		logger.verbose(`WorkflowOrchestrator: Using workspace: ${workspace.basePath}`);
+		return ImmutableWorkflowContext.create(config, services, initialData, workspace);
+	}
+	/**
+	* Runs the complete command lifecycle: before → tasks → after / error
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command to execute
+	* @param context - The workflow context for execution
+	* @returns Execution result with success/failure status
+	*/
+	runCommandLifecycle(command, context) {
+		return (command.beforeExecute ? command.beforeExecute(context) : FireflyOkAsync(void 0)).andThen(() => this.buildAndOrderTasks(command, context)).andThen((tasks) => new WorkflowExecutor(this.options).execute(tasks, context)).andThen((result) => this.runAfterExecute(command, context, result)).orElse((error) => this.handleCommandError(command, context, error));
+	}
+	/**
+	* Runs the afterExecute hook if defined
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command to execute
+	* @param context - The workflow context for execution
+	* @param result - The workflow execution result
+	* @returns The original execution result wrapped in FireflyAsyncResult
+	*/
+	runAfterExecute(command, context, result) {
+		if (!command.afterExecute) return FireflyOkAsync(result);
+		return command.afterExecute(result, context).map(() => result);
+	}
+	/**
+	* Handles errors by calling onError hook and wrapping the error
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command to execute
+	* @param context - The workflow context for execution
+	* @param error - The error that occurred
+	* @returns A FireflyAsyncResult with the wrapped error
+	*/
+	handleCommandError(command, context, error) {
+		const wrappedError = wrapErrorMessage(failedError({
+			message: error.message,
+			source: "WorkflowOrchestrator.executeCommand"
+		}), "Command execution failed");
+		if (!command.onError) return FireflyErrAsync(error);
+		return command.onError(new Error(error.message), context).andThen(() => FireflyErrAsync(wrappedError)).orElse(() => FireflyErrAsync(wrappedError));
+	}
+	/**
+	* Builds tasks from command and orders them by dependencies
+	*
+	* @template TConfig - Command configuration type
+	* @template TData - Workflow data type
+	* @template TServices - Required services tuple
+	* @param command - The command to build tasks from
+	* @param context - The workflow context for execution
+	* @returns Ordered array of tasks wrapped in FireflyAsyncResult
+	*/
+	buildAndOrderTasks(command, context) {
+		logger.verbose(`WorkflowOrchestrator: Building tasks for "${command.meta.name}"`);
+		return command.buildTasks(context).andThen((tasks) => {
+			if (tasks.length === 0) return validationErrAsync({
+				message: `Command "${command.meta.name}" returned no tasks`,
+				source: "WorkflowOrchestrator.buildAndOrderTasks"
+			});
+			logger.verbose(`WorkflowOrchestrator: Built ${tasks.length} tasks`);
+			const taskRegistry = new TaskRegistry();
+			const registerResult = taskRegistry.registerAll(tasks);
+			if (registerResult.isErr()) return FireflyErrAsync(registerResult.error);
+			const orderedTasksResult = taskRegistry.buildExecutionOrder();
+			if (orderedTasksResult.isErr()) return FireflyErrAsync(orderedTasksResult.error);
+			const orderedTasks = orderedTasksResult.value;
+			return FireflyOkAsync(orderedTasks);
+		});
+	}
+};
+
+//#endregion
+//#region src/core/command/command.types.ts
+/**
+* Erases a typed Command to a BrandedCommand for registry storage.
+*
+* @param command - The typed command to erase
+* @returns A branded command safe for heterogeneous storage
+* @internal
+*/
+function eraseCommandType(command) {
+	return command;
+}
+
+//#endregion
+//#region src/core/registry/command.registry.ts
+/**
+* Registry for managing workflow commands.
+*
+* Extends `BaseRegistry` with command-specific functionality:
+* - Type-safe command registration with generic support
+* - Command name uniqueness enforcement
+* - Retrieval of all registered command names
+* - Uses branded types instead of `any` for type erasure
+*
+* @example
+* ```typescript
+* const registry = new CommandRegistry();
+*
+* // Register a command
+* registry.register(releaseCommand);
+*
+* // Retrieve and execute
+* const cmdResult = registry.get("release");
+* if (cmdResult.isOk()) {
+*   await orchestrator.executeCommand(cmdResult.value, config);
+* }
+* ```
+*/
+var CommandRegistry = class extends BaseRegistry {
+	constructor() {
+		super({
+			name: "Command",
+			source: "CommandRegistry",
+			getKey: (command) => command.meta.name,
+			duplicateErrorCode: "CONFLICT",
+			notFoundErrorCode: "NOT_FOUND"
+		});
+	}
+	/**
+	* Registers a typed command in the registry.
+	*
+	* @template TConfig - The command's configuration type
+	* @template TData - The command's data type
+	* @template TServices - The command's required services
+	* @param command - The command to register
+	* @returns `Ok(void)` on success, `Err(FireflyError)` if command name already exists
+	*/
+	registerCommand(command) {
+		return this.register(eraseCommandType(command));
+	}
+	/**
+	* Registers multiple typed commands.
+	*
+	* @template TConfig - The commands' configuration type
+	* @template TData - The commands' data type
+	* @template TServices - The commands' required services
+	* @param commands - Array of commands to register
+	* @returns `Ok(void)` if all registered, `Err(FireflyError)` on first failure
+	*/
+	registerAllCommands(commands) {
+		return this.registerAll(commands.map(eraseCommandType));
+	}
+	/**
+	* Returns all registered command names.
+	* @returns Array of command names in registration order
+	*/
+	getNames() {
+		return this.getKeys();
+	}
+};
+
+//#endregion
+//#region src/cli/program.ts
+/**
+* Creates and configures the Firefly CLI program.
+*
+* Sets up the Commander.js program with:
+* - Global options (--dry-run, --verbose, --no-enable-rollback)
+* - All registered commands with their specific options
+* - Help and version information
+*
+* @returns Configured Commander program ready for parsing
+*/
+function createFireflyCLI() {
+	const program = new Command();
+	program.name("firefly").description(RuntimeEnv.description).version(RuntimeEnv.version).helpOption("-h, --help", "Display help information").helpCommand("help", "Display help for command");
+	const builder = new OptionsBuilder();
+	builder.registerGlobalOptions(program);
+	const normalizer = new OptionsNormalizer();
+	const registry = createCommandRegistry();
+	const ctx = {
+		program,
+		builder,
+		normalizer,
+		registry
+	};
+	for (const command of registry.getAll()) {
+		const configSchema = command.meta.configSchema;
+		registerCommand(ctx, command.meta.name, configSchema);
+	}
+	return program;
+}
+/**
+* Creates a command registry for the CLI.
+*
+* @returns Configured command registry with all commands registered
+*/
+function createCommandRegistry() {
+	const registry = new CommandRegistry();
+	registry.registerCommand(releaseCommand);
+	return registry;
+}
+/**
+* Registers a single command with the CLI program.
+*
+* @param ctx - The registration context containing program, builder, and registry
+* @param commandName - The name of the command to register
+* @param configSchema - The Zod schema defining the command's configuration
+*/
+function registerCommand(ctx, commandName, configSchema) {
+	const cmd = ctx.program.command(commandName).description(getCommandDescription(commandName));
+	ctx.builder.registerCommandOptions(cmd, configSchema);
+	cmd.action(async (_cliOptions, command) => {
+		const allOptions = command.optsWithGlobals();
+		const result = await executeCommand(commandName, ctx.normalizer.normalize(allOptions, configSchema), ctx.registry);
+		if (result.isErr()) {
+			logger.error(result.error.message);
+			process.exit(1);
+		}
+		if (!result.value.success) process.exit(1);
+		process.exit(0);
+	});
+}
+/**
+* Executes a command with the given options.
+*
+* Handles the full execution flow:
+* 1. Log version information
+* 2. Load and merge config file values
+* 3. Execute through the workflow orchestrator
+*
+* @param commandName - The command to execute
+* @param cliOptions - Parsed and normalized CLI options (already merged with globals via optsWithGlobals)
+* @param registry - The command registry to look up the command
+* @returns Async result of the workflow execution
+*/
+function executeCommand(commandName, cliOptions, registry) {
+	logVersionInfo(commandName);
+	if (cliOptions.verbose) logger.level = LogLevels.verbose;
+	const workspace = Workspace.fromOptions({ basePath: cliOptions.cwd });
+	return new ConfigLoader({
+		cwd: workspace.basePath,
+		configFile: cliOptions.config,
+		commandName
+	}).load().andThen((fileConfig) => {
+		return executeWithOrchestrator(commandName, {
+			...fileConfig,
+			...cliOptions
+		}, workspace, registry);
+	});
+}
+/**
+* Executes a command through the workflow orchestrator.
+*
+* @param commandName - The command to execute
+* @param config - The merged runtime configuration
+* @param workspace - The workspace for file operations
+* @param registry - The command registry
+* @returns Async result of the workflow execution
+*/
+function executeWithOrchestrator(commandName, config, workspace, registry) {
+	const commandResult = registry.get(commandName);
+	if (commandResult.isErr()) return notFoundErrAsync({ message: `Command "${commandName}" not found` });
+	const command = commandResult.value;
+	const parseResult = command.meta.configSchema.safeParse(config);
+	if (!parseResult.success) {
+		const errors = formatZodErrors(parseResult.error);
+		if (DebugFlags.showRawError) logger.error(parseResult.error);
+		return validationErrAsync({ message: errors });
+	}
+	const parsedConfig = {
+		...config,
+		...parseResult.data
+	};
+	return createOrchestrator(parsedConfig, workspace).executeCommand(command, parsedConfig);
+}
+/**
+* Creates a workflow orchestrator with the given configuration.
+*
+* @param config - The runtime configuration
+* @param workspace - The workspace for file operations
+* @returns Configured workflow orchestrator
+*/
+function createOrchestrator(config, workspace) {
+	return new WorkflowOrchestrator({
+		workspace,
+		dryRun: config.dryRun ?? false,
+		enableRollback: config.enableRollback ?? true,
+		verbose: config.verbose ?? false
+	});
+}
+/**
+* Logs version information for the Firefly CLI.
+*
+* @param commandName - The name of the executed command
+*/
+function logVersionInfo(commandName) {
+	const fireflyVersion = colors.dim(`v${RuntimeEnv.version}`);
+	const fireflyLabel = `${colors.magenta("firefly")} ${fireflyVersion}`;
+	if (commandName === "release") {
+		const gitCliffVersion = colors.dim(`v${RuntimeEnv.gitCliffVersion}`);
+		logger.info(`${fireflyLabel} powered by git-cliff ${gitCliffVersion}`);
+	} else logger.info(fireflyLabel);
+}
+/**
+* Get a description for a specific command.
+*
+* @param commandName - The name of the command
+* @returns A description of the command
+*/
+function getCommandDescription(commandName) {
+	return { release: "Automated semantic versioning, changelog generation, and GitHub release creation" }[commandName] ?? `Run the ${commandName} command`;
+}
+
+//#endregion
+export { createFireflyCLI };