@politty/zod 0.0.0

package/dist/runner-D72I7wvK.js

@@ -0,0 +1,2956 @@
+import { a as getValidatorAdapter, i as toKebabCase, r as toCamelCase, t as getAllAliases } from "./field-meta-DMy5BcRr.js";
+import { n as getExtractedFields, o as isInternalArgsSchema, s as validateInternalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { a as resolveSubcommandWithAlias, c as resolveSubCommandMeta, n as listSubCommands, o as isLazyCommand, r as resolveLazyCommand, t as listSubCommandNamesWithAliases } from "./subcommand-router-Cskpofdk.js";
+import { n as enableCompileCache } from "./compile-cache-Ct41pWGL.js";
+import { n as emptyLogs, r as mergeLogs, t as createLogCollector } from "./log-collector-CoUkLVJB.js";
+import { a as symbols, i as styles } from "./logger-i_bb-Jhc.js";
+import { stripVTControlCharacters } from "node:util";
+
+//#region ../core/src/core/case-proxy.ts
+/**
+* Wrap an args object with a Proxy that allows dual-case access.
+*
+* Given `{ "my-option": "value" }`, both `obj["my-option"]` and `obj.myOption`
+* will return `"value"`.
+*
+* - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
+* - The `in` operator detects both case variants.
+*/
+function createDualCaseProxy(obj) {
+	return new Proxy(obj, {
+		get(target, prop, receiver) {
+			if (typeof prop === "string") {
+				if (prop in target) return Reflect.get(target, prop, receiver);
+				const camel = toCamelCase(prop);
+				if (camel !== prop && camel in target) return Reflect.get(target, camel, receiver);
+				const kebab = toKebabCase(prop);
+				if (kebab !== prop && kebab in target) return Reflect.get(target, kebab, receiver);
+			}
+			return Reflect.get(target, prop, receiver);
+		},
+		has(target, prop) {
+			if (typeof prop === "string") {
+				if (prop in target) return true;
+				const camel = toCamelCase(prop);
+				if (camel !== prop && camel in target) return true;
+				const kebab = toKebabCase(prop);
+				if (kebab !== prop && kebab in target) return true;
+			}
+			return Reflect.has(target, prop);
+		}
+	});
+}
+
+//#endregion
+//#region ../core/src/executor/command-runner.ts
+/**
+* Execute a command lifecycle: setup → run → cleanup
+*
+* This is an internal function that executes the command's lifecycle hooks.
+* For running commands with argument parsing, use `runCommand` instead.
+*
+* @param command - The command to execute
+* @param args - Already validated arguments
+* @param options - Lifecycle options
+* @returns The result of command execution
+* @internal
+*/
+async function executeLifecycle(command, args, _options = {}) {
+	let error;
+	let result;
+	const collector = _options.captureLogs ?? false ? createLogCollector() : null;
+	collector?.start();
+	const setupContext = { args };
+	const cleanupContext = {
+		args,
+		error
+	};
+	let signalHandler;
+	if (_options.handleSignals) {
+		signalHandler = async (_signal) => {
+			if (signalHandler) {
+				process.off("SIGINT", signalHandler);
+				process.off("SIGTERM", signalHandler);
+			}
+			const signalError = /* @__PURE__ */ new Error("Process interrupted");
+			cleanupContext.error = signalError;
+			if (command.cleanup) try {
+				await command.cleanup(cleanupContext);
+			} catch (e) {
+				console.error("Error during signal cleanup:", e);
+			}
+			if (_options.globalCleanup) try {
+				await _options.globalCleanup({ error: signalError });
+			} catch (e) {
+				console.error("Error during global signal cleanup:", e);
+			}
+			collector?.stop();
+			if (process.stdout.writableNeedDrain) await new Promise((resolve) => {
+				const timeout = setTimeout(() => {
+					process.stdout.off("drain", onDrain);
+					resolve();
+				}, 200);
+				const onDrain = () => {
+					clearTimeout(timeout);
+					resolve();
+				};
+				process.stdout.once("drain", onDrain);
+			});
+			process.exit(1);
+		};
+		process.on("SIGINT", signalHandler);
+		process.on("SIGTERM", signalHandler);
+	}
+	try {
+		if (command.setup) await command.setup(setupContext);
+		if (command.run) result = await command.run(args);
+	} catch (e) {
+		error = e instanceof Error ? e : new Error(String(e));
+	} finally {
+		if (signalHandler) {
+			process.off("SIGINT", signalHandler);
+			process.off("SIGTERM", signalHandler);
+		}
+	}
+	if (command.cleanup) {
+		cleanupContext.error = error;
+		try {
+			await command.cleanup(cleanupContext);
+		} catch (cleanupError) {
+			if (!error) error = cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError));
+		}
+	}
+	collector?.stop();
+	const logs = mergeLogs(_options.existingLogs ?? emptyLogs(), collector?.getLogs() ?? emptyLogs());
+	if (error) return {
+		success: false,
+		error,
+		exitCode: 1,
+		logs
+	};
+	return {
+		success: true,
+		result,
+		exitCode: 0,
+		logs
+	};
+}
+
+//#endregion
+//#region ../core/src/output/string-width.ts
+/**
+* Lightweight replacement for the `string-width` package.
+*
+* Computes the visual (terminal) width of a string by:
+*   1. Stripping ANSI escape codes (via Node's `stripVTControlCharacters`)
+*   2. Skipping zero-width characters (combining marks, control chars, etc.)
+*   3. Counting East Asian wide / fullwidth characters and most emoji as 2
+*   4. Counting everything else as 1
+*
+* This covers the cases the markdown renderer cares about (CJK text, emoji,
+* and already-styled ANSI strings) without pulling in an external dependency.
+*/
+/**
+* Whether a code point has no visual width (combining marks, zero-width
+* spaces/joiners, variation selectors, control characters).
+*/
+function isZeroWidth(cp) {
+	return cp <= 31 || cp >= 127 && cp <= 159 || cp >= 768 && cp <= 879 || cp >= 6832 && cp <= 6911 || cp >= 7616 && cp <= 7679 || cp >= 8400 && cp <= 8447 || cp >= 65056 && cp <= 65071 || cp === 8203 || cp >= 8204 && cp <= 8207 || cp === 65279 || cp >= 65024 && cp <= 65039 || cp >= 917760 && cp <= 917999;
+}
+/**
+* Whether a code point is rendered at double (full) width in a terminal.
+* Based on Unicode East Asian Width (Wide/Fullwidth) plus common emoji ranges.
+*/
+function isFullWidth(cp) {
+	return cp >= 4352 && cp <= 4447 || cp >= 11904 && cp <= 12350 || cp >= 12353 && cp <= 13311 || cp >= 13312 && cp <= 19903 || cp >= 19968 && cp <= 40959 || cp >= 40960 && cp <= 42191 || cp >= 43360 && cp <= 43391 || cp >= 44032 && cp <= 55203 || cp >= 63744 && cp <= 64255 || cp >= 65040 && cp <= 65049 || cp >= 65072 && cp <= 65135 || cp >= 65280 && cp <= 65376 || cp >= 65504 && cp <= 65510 || cp >= 110592 && cp <= 110959 || cp >= 127488 && cp <= 127569 || cp >= 131072 && cp <= 262141 || cp >= 9728 && cp <= 10175 || cp >= 126976 && cp <= 129791;
+}
+/**
+* Visual width of a single grapheme cluster (a user-perceived character).
+*
+* Iterating by code point would over-count multi-code-point clusters such as
+* ZWJ emoji sequences (👨‍👩‍👧), regional-indicator flags (🇯🇵), and emoji with
+* skin-tone modifiers (👍🏽). These render as a single glyph, so the whole
+* cluster contributes width 0/1/2 once.
+*/
+function graphemeWidth(grapheme) {
+	let hasVisible = false;
+	let hasWide = false;
+	let hasEmojiVariation = false;
+	for (const char of grapheme) {
+		const cp = char.codePointAt(0);
+		if (cp === 65039) {
+			hasEmojiVariation = true;
+			continue;
+		}
+		if (isZeroWidth(cp)) continue;
+		hasVisible = true;
+		if (isFullWidth(cp)) hasWide = true;
+	}
+	if (!hasVisible) return 0;
+	return hasWide || hasEmojiVariation ? 2 : 1;
+}
+const segmenter = (() => {
+	try {
+		return new Intl.Segmenter("en", { granularity: "grapheme" });
+	} catch {
+		return;
+	}
+})();
+/**
+* Compute the visual width of a string as rendered in a terminal.
+*/
+function stringWidth(input) {
+	if (input.length === 0) return 0;
+	const str = input.includes("\x1B") || input.includes("›") ? stripVTControlCharacters(input) : input;
+	let width = 0;
+	if (segmenter) for (const { segment } of segmenter.segment(str)) width += graphemeWidth(segment);
+	else for (const char of str) width += graphemeWidth(char);
+	return width;
+}
+
+//#endregion
+//#region ../core/src/output/markdown-renderer.ts
+/**
+* Lightweight Markdown-to-terminal renderer.
+*
+* Supports a subset of Markdown tailored for CLI help notes:
+* - Inline: bold, italic, inline code, links
+* - Block: paragraphs, unordered/ordered lists, blockquotes, headings,
+*          horizontal rules, fenced code blocks
+*/
+/**
+* Apply inline Markdown formatting to a string.
+*
+* Processing order matters to avoid conflicts:
+*   1. Inline code (backticks) — content inside is literal, no further processing
+*   2. Bold (**text**)
+*   3. Italic (*text* or _text_)
+*   4. Links [text](url)
+*/
+function renderInline(text) {
+	const codeSpans = [];
+	let result = text.replace(/`([^`]+)`/g, (_match, code) => {
+		const index = codeSpans.length;
+		codeSpans.push(styles.cyan(code));
+		return `\x00CODE${index}\x00`;
+	});
+	result = result.replace(/\*\*(.+?)\*\*/g, (_match, content) => styles.bold(content));
+	result = result.replace(/__(.+?)__/g, (_match, content) => styles.bold(content));
+	result = result.replace(/\*(.+?)\*/g, (_match, content) => styles.italic(content));
+	result = result.replace(/(?<!\w)_(.+?)_(?!\w)/g, (_match, content) => styles.italic(content));
+	result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, linkText, url) => `${styles.underline(linkText)} ${styles.dim(`(${url})`)}`);
+	result = result.replace(/\x00CODE(\d+)\x00/g, (_match, index) => codeSpans[Number(index)]);
+	return result;
+}
+/**
+* Render a Markdown string to styled terminal output.
+*
+* Block-level processing:
+*   - Splits input into blocks separated by blank lines
+*   - Detects headings, horizontal rules, blockquotes, lists, code blocks, and paragraphs
+*   - Applies inline formatting within each block
+*/
+function renderMarkdown(markdown) {
+	return splitIntoBlocks(markdown.split("\n")).map(renderBlock).join("\n\n");
+}
+const HEADING_RE = /^(#{1,6})\s+(.+)$/;
+const HR_RE = /^(?:---+|\*\*\*+|___+)\s*$/;
+const BLOCKQUOTE_RE = /^>\s?(.*)$/;
+const UL_RE = /^-\s+(.+)$/;
+const OL_RE = /^(\d+)[.)]\s+(.+)$/;
+const FENCE_OPEN_RE = /^(`{3,}|~{3,})(\S*)\s*$/;
+const ALERT_RE = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$/;
+const TABLE_ROW_RE = /^\|(.+)\|$/;
+const TABLE_SEP_RE = /^\|(\s*:?-+:?\s*\|)+$/;
+/**
+* Split lines into logical blocks separated by blank lines.
+* Consecutive lines of the same block type are grouped together.
+*/
+function splitIntoBlocks(lines) {
+	const blocks = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (line.trim() === "") {
+			i++;
+			continue;
+		}
+		const fenceMatch = line.match(FENCE_OPEN_RE);
+		if (fenceMatch) {
+			const fence = fenceMatch[1];
+			const lang = fenceMatch[2] ?? "";
+			const codeLines = [];
+			i++;
+			while (i < lines.length) {
+				if (lines[i].startsWith(fence.charAt(0).repeat(fence.length)) && lines[i].trim() === fence.charAt(0).repeat(Math.max(fence.length, lines[i].trim().length))) {
+					i++;
+					break;
+				}
+				codeLines.push(lines[i]);
+				i++;
+			}
+			blocks.push({
+				type: "code",
+				lang,
+				lines: codeLines
+			});
+			continue;
+		}
+		const headingMatch = line.match(HEADING_RE);
+		if (headingMatch) {
+			blocks.push({
+				type: "heading",
+				level: headingMatch[1].length,
+				content: headingMatch[2]
+			});
+			i++;
+			continue;
+		}
+		if (HR_RE.test(line)) {
+			blocks.push({ type: "hr" });
+			i++;
+			continue;
+		}
+		if (BLOCKQUOTE_RE.test(line)) {
+			const bqLines = [];
+			while (i < lines.length) {
+				const bqMatch = lines[i].match(BLOCKQUOTE_RE);
+				if (bqMatch) {
+					bqLines.push(bqMatch[1]);
+					i++;
+				} else break;
+			}
+			if (bqLines.length > 0) {
+				const alertMatch = bqLines[0].match(ALERT_RE);
+				if (alertMatch) {
+					const contentLines = bqLines.slice(1).filter((l) => l !== "");
+					blocks.push({
+						type: "alert",
+						alertType: alertMatch[1],
+						lines: contentLines
+					});
+					continue;
+				}
+			}
+			blocks.push({
+				type: "blockquote",
+				lines: bqLines
+			});
+			continue;
+		}
+		if (UL_RE.test(line)) {
+			const items = [];
+			while (i < lines.length) {
+				const ulMatch = lines[i].match(UL_RE);
+				if (ulMatch) {
+					items.push(ulMatch[1]);
+					i++;
+				} else break;
+			}
+			blocks.push({
+				type: "ul",
+				items
+			});
+			continue;
+		}
+		const olMatch = line.match(OL_RE);
+		if (olMatch) {
+			const start = Number(olMatch[1]);
+			const items = [];
+			while (i < lines.length) {
+				const match = lines[i].match(OL_RE);
+				if (match) {
+					items.push(match[2]);
+					i++;
+				} else break;
+			}
+			blocks.push({
+				type: "ol",
+				items,
+				start
+			});
+			continue;
+		}
+		if (TABLE_ROW_RE.test(line) && i + 1 < lines.length && TABLE_SEP_RE.test(lines[i + 1])) {
+			const headers = parseCells(line);
+			const alignments = parseAlignments(lines[i + 1]);
+			i += 2;
+			const rows = [];
+			while (i < lines.length && TABLE_ROW_RE.test(lines[i])) {
+				rows.push(parseCells(lines[i]));
+				i++;
+			}
+			blocks.push({
+				type: "table",
+				headers,
+				alignments,
+				rows
+			});
+			continue;
+		}
+		const paraLines = [];
+		while (i < lines.length) {
+			const l = lines[i];
+			if (l.trim() === "" || HEADING_RE.test(l) || HR_RE.test(l) || BLOCKQUOTE_RE.test(l) || UL_RE.test(l) || OL_RE.test(l) || FENCE_OPEN_RE.test(l) || TABLE_ROW_RE.test(l) && i + 1 < lines.length && TABLE_SEP_RE.test(lines[i + 1])) break;
+			paraLines.push(l);
+			i++;
+		}
+		if (paraLines.length > 0) blocks.push({
+			type: "paragraph",
+			lines: paraLines
+		});
+	}
+	return blocks;
+}
+/**
+* Parse cells from a table row: `| a | b | c |` → `["a", "b", "c"]`
+*/
+function parseCells(row) {
+	return row.slice(1, -1).split("|").map((cell) => cell.trim());
+}
+/**
+* Parse alignment from separator row: `|:---|:---:|---:|` → `["left", "center", "right"]`
+*/
+function parseAlignments(sepRow) {
+	return sepRow.slice(1, -1).split("|").map((cell) => {
+		const trimmed = cell.trim();
+		if (trimmed.startsWith(":") && trimmed.endsWith(":")) return "center";
+		if (trimmed.endsWith(":")) return "right";
+		return "left";
+	});
+}
+/**
+* Pad a string to a given width with the specified alignment.
+*/
+function alignText(text, width, alignment) {
+	const visualWidth = stringWidth(text);
+	const total = Math.max(0, width - visualWidth);
+	if (alignment === "right") return " ".repeat(total) + text;
+	if (alignment === "center") {
+		const left = Math.floor(total / 2);
+		return " ".repeat(left) + text + " ".repeat(total - left);
+	}
+	return text + " ".repeat(total);
+}
+/**
+* Style configuration for GitHub-style alert blocks.
+*/
+const alertStyles = {
+	NOTE: {
+		icon: "ℹ",
+		label: "Note",
+		styleFn: styles.cyan
+	},
+	TIP: {
+		icon: "💡",
+		label: "Tip",
+		styleFn: styles.green
+	},
+	IMPORTANT: {
+		icon: "❗",
+		label: "Important",
+		styleFn: styles.magenta
+	},
+	WARNING: {
+		icon: "⚠",
+		label: "Warning",
+		styleFn: styles.yellow
+	},
+	CAUTION: {
+		icon: "🔴",
+		label: "Caution",
+		styleFn: styles.red
+	}
+};
+/**
+* Render a single block to styled terminal output.
+*/
+function renderBlock(block) {
+	switch (block.type) {
+		case "heading": return styles.green(styles.bold(renderInline(block.content)));
+		case "hr": return styles.dim("─".repeat(40));
+		case "blockquote": {
+			const prefix = styles.dim("│ ");
+			return block.lines.map((line) => `${prefix}${renderInline(line)}`).join("\n");
+		}
+		case "alert": {
+			const { icon, label, styleFn } = alertStyles[block.alertType];
+			const prefix = styleFn(styles.bold("│")) + " ";
+			const header = `${prefix}${styleFn(icon)} ${styleFn(label)}`;
+			if (block.lines.length === 0) return header;
+			return `${header}\n${block.lines.map((line) => `${prefix}${renderInline(line)}`).join("\n")}`;
+		}
+		case "ul": return block.items.map((item) => `${styles.dim("•")} ${renderInline(item)}`).join("\n");
+		case "ol": {
+			const maxNum = block.start + block.items.length - 1;
+			const width = String(maxNum).length;
+			return block.items.map((item, i) => {
+				const num = String(block.start + i).padStart(width, " ");
+				return `${styles.dim(`${num}.`)} ${renderInline(item)}`;
+			}).join("\n");
+		}
+		case "table": {
+			const colCount = block.headers.length;
+			const renderedHeaders = block.headers.map((h) => renderInline(h));
+			const renderedRows = block.rows.map((row) => Array.from({ length: colCount }, (_, i) => renderInline(row[i] ?? "")));
+			const colWidths = renderedHeaders.map((h, i) => {
+				const headerWidth = stringWidth(h);
+				const cellWidths = renderedRows.map((row) => stringWidth(row[i]));
+				return Math.max(headerWidth, ...cellWidths);
+			});
+			const pipe = styles.dim("│");
+			const topBorder = styles.dim(`┌─${colWidths.map((w) => "─".repeat(w)).join("─┬─")}─┐`);
+			const midBorder = styles.dim(`├─${colWidths.map((w) => "─".repeat(w)).join("─┼─")}─┤`);
+			const botBorder = styles.dim(`└─${colWidths.map((w) => "─".repeat(w)).join("─┴─")}─┘`);
+			return [
+				topBorder,
+				`${pipe} ${renderedHeaders.map((h, i) => styles.bold(alignText(h, colWidths[i], block.alignments[i] ?? "left"))).join(` ${pipe} `)} ${pipe}`,
+				midBorder,
+				...renderedRows.map((row) => {
+					const cells = row.map((cell, i) => alignText(cell, colWidths[i], block.alignments[i] ?? "left"));
+					return `${pipe} ${cells.join(` ${pipe} `)} ${pipe}`;
+				}),
+				botBorder
+			].join("\n");
+		}
+		case "code": return block.lines.map((line) => `  ${styles.yellow(line)}`).join("\n");
+		case "paragraph": return renderInline(block.lines.join(" "));
+	}
+}
+
+//#endregion
+//#region ../core/src/output/help-generator.ts
+/**
+* Default descriptions for built-in options
+*/
+const defaultBuiltinDescriptions = {
+	help: "Show help",
+	helpAll: "Show help with all subcommand options",
+	version: "Show version"
+};
+/**
+* Internal subcommands are reserved for framework internals and hidden from help output.
+*/
+function isVisibleSubcommand(name) {
+	return !name.startsWith("__");
+}
+function getVisibleSubcommandEntries(subCommands) {
+	return Object.entries(subCommands).filter(([name]) => isVisibleSubcommand(name));
+}
+/**
+* Build full command name from context
+*/
+function buildFullCommandName(command, context) {
+	if (context?.rootName && context.commandPath && context.commandPath.length > 0) return context.commandPath.join(" ");
+	return command.name ?? "command";
+}
+/**
+* Build usage command name (includes root name for subcommands)
+*/
+function buildUsageCommandName(command, context) {
+	if (context?.rootName && context.commandPath && context.commandPath.length > 0) return `${context.rootName} ${context.commandPath.join(" ")}`;
+	return command.name ?? "command";
+}
+/**
+* Render the usage line for a command
+*/
+function renderUsageLine(command, context) {
+	const parts = [];
+	const name = buildUsageCommandName(command, context);
+	parts.push(styles.commandName(name));
+	if (context?.globalExtracted?.fields.length) parts.push(styles.placeholder("[global options]"));
+	const extracted = getExtractedFields(command);
+	if (extracted) {
+		const positionals = extracted.fields.filter((a) => a.positional);
+		if (extracted.fields.filter((a) => !a.positional).length > 0) parts.push(styles.placeholder("[options]"));
+		if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) if (command.run) parts.push(styles.placeholder("[command]"));
+		else parts.push(styles.option("<command>"));
+		for (const arg of positionals) if (arg.required) parts.push(styles.option(`<${arg.name}>`));
+		else parts.push(styles.placeholder(`[${arg.name}]`));
+	} else if (command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) if (command.run) parts.push(styles.placeholder("[command]"));
+	else parts.push(styles.option("<command>"));
+	return parts.join(" ");
+}
+/**
+* Render the options section
+*/
+function renderOptions(command, descriptions = {}, context) {
+	const lines = [];
+	const desc = {
+		help: descriptions.help ?? defaultBuiltinDescriptions.help,
+		helpAll: descriptions.helpAll ?? defaultBuiltinDescriptions.helpAll,
+		version: descriptions.version ?? defaultBuiltinDescriptions.version
+	};
+	const extracted = getExtractedFields(command);
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && getAllAliases(f).includes("h")) ?? false;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && getAllAliases(f).includes("H")) ?? false;
+	if (hasUserDefinedh) lines.push(formatOption(styles.option("--help"), desc.help));
+	else lines.push(formatOption(`${styles.option("-h")}, ${styles.option("--help")}`, desc.help));
+	if (hasUserDefinedH) lines.push(formatOption(styles.option("--help-all"), desc.helpAll));
+	else lines.push(formatOption(`${styles.option("-H")}, ${styles.option("--help-all")}`, desc.helpAll));
+	if (context?.rootVersion) lines.push(formatOption(styles.option("--version"), desc.version));
+	if (!extracted) return lines.join("\n");
+	if (extracted.schemaType === "discriminatedUnion" && extracted.discriminator) return renderDiscriminatedUnionOptions(extracted, command, lines);
+	if (extracted.schemaType === "union" && extracted.unionOptions) return renderUnionOptions(extracted, command, lines);
+	if (extracted.schemaType === "xor" && extracted.unionOptions) return renderUnionOptions(extracted, command, lines);
+	const options = extracted.fields.filter((a) => !a.positional);
+	for (const opt of options) {
+		const flags = formatFlags(opt);
+		let desc = opt.description ?? "";
+		if (opt.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(opt.defaultValue)})`)}`;
+		if (opt.required) desc += ` ${styles.required("(required)")}`;
+		const envInfo = formatEnvInfo(opt.env);
+		if (envInfo) desc += ` ${envInfo}`;
+		lines.push(formatOption(flags, desc));
+		const negationLine = formatNegationLine(opt);
+		if (negationLine) lines.push(negationLine);
+	}
+	return lines.join("\n");
+}
+/**
+* Render a separate line for the custom negation option when a
+* `negationDescription` is provided. When no description is given, the
+* negation is shown inline by `formatFlags`.
+*/
+function formatNegationLine(opt, indent = 0, extraDescPadding = 0) {
+	if (!opt.negationDisplay || !opt.negationDescription) return null;
+	return formatOption(styles.option(`--${opt.negationDisplay}`), `${opt.negationDescription} ${styles.dim(`(↔ --${opt.cliName})`)}`, indent, extraDescPadding);
+}
+/**
+* Render options for discriminated union with variants
+*/
+function renderDiscriminatedUnionOptions(extracted, _command, lines) {
+	const discriminator = extracted.discriminator;
+	const variants = extracted.variants ?? [];
+	const discriminatorField = extracted.fields.find((f) => f.name === discriminator);
+	if (discriminatorField) {
+		const variantValues = variants.map((v) => v.discriminatorValue).join("|");
+		const flags = `${styles.option(`--${discriminator}`)} ${styles.placeholder(`<${variantValues}>`)}`;
+		const description = extracted.description ?? discriminatorField.description ?? "Action to perform";
+		lines.push(formatOption(flags, description));
+	}
+	const commonFields = /* @__PURE__ */ new Set();
+	const allFieldNames = /* @__PURE__ */ new Set();
+	for (const variant of variants) for (const field of variant.fields) allFieldNames.add(field.name);
+	for (const fieldName of allFieldNames) {
+		if (fieldName === discriminator) continue;
+		if (variants.every((v) => v.fields.some((f) => f.name === fieldName))) commonFields.add(fieldName);
+	}
+	for (const fieldName of commonFields) {
+		const field = extracted.fields.find((f) => f.name === fieldName);
+		if (field && !field.positional) {
+			const flags = formatFlags(field);
+			let desc = field.description ?? "";
+			if (field.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(field.defaultValue)})`)}`;
+			const envInfo = formatEnvInfo(field.env);
+			if (envInfo) desc += ` ${envInfo}`;
+			lines.push(formatOption(flags, desc));
+			const negationLine = formatNegationLine(field);
+			if (negationLine) lines.push(negationLine);
+		}
+	}
+	for (const variant of variants) {
+		const variantFields = variant.fields.filter((f) => f.name !== discriminator && !commonFields.has(f.name) && !f.positional);
+		if (variantFields.length > 0) {
+			lines.push("");
+			const variantLabel = variant.description ? `${styles.dim("When")} ${styles.option(discriminator)}=${styles.bold(variant.discriminatorValue)}: ${variant.description}` : `${styles.dim("When")} ${styles.option(discriminator)}=${styles.bold(variant.discriminatorValue)}:`;
+			lines.push(variantLabel);
+			for (const field of variantFields) {
+				const flags = formatFlags(field);
+				let desc = field.description ?? "";
+				if (field.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(field.defaultValue)})`)}`;
+				if (field.required) desc += ` ${styles.required("(required)")}`;
+				const envInfo = formatEnvInfo(field.env);
+				if (envInfo) desc += ` ${envInfo}`;
+				lines.push(formatOption(flags, desc, 1));
+				const negationLine = formatNegationLine(field, 1);
+				if (negationLine) lines.push(negationLine);
+			}
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Render options for union with multiple options
+*/
+function renderUnionOptions(extracted, _command, lines) {
+	const unionOptions = extracted.unionOptions ?? [];
+	const commonFields = /* @__PURE__ */ new Set();
+	const allFieldNames = /* @__PURE__ */ new Set();
+	for (const option of unionOptions) for (const field of option.fields) allFieldNames.add(field.name);
+	for (const fieldName of allFieldNames) if (unionOptions.every((o) => o.fields.some((f) => f.name === fieldName))) commonFields.add(fieldName);
+	for (const fieldName of commonFields) {
+		const field = extracted.fields.find((f) => f.name === fieldName);
+		if (field && !field.positional) {
+			const flags = formatFlags(field);
+			let desc = field.description ?? "";
+			if (field.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(field.defaultValue)})`)}`;
+			const envInfo = formatEnvInfo(field.env);
+			if (envInfo) desc += ` ${envInfo}`;
+			lines.push(formatOption(flags, desc));
+			const negationLine = formatNegationLine(field);
+			if (negationLine) lines.push(negationLine);
+		}
+	}
+	for (let i = 0; i < unionOptions.length; i++) {
+		const option = unionOptions[i];
+		if (!option) continue;
+		const uniqueFields = option.fields.filter((f) => !commonFields.has(f.name) && !f.positional);
+		const label = option.description ?? `Variant ${i + 1}`;
+		if (uniqueFields.length > 0) {
+			lines.push("");
+			lines.push(`  ${styles.bold(`${label}:`)}`);
+			for (const field of uniqueFields) {
+				const flags = formatFlags(field);
+				let desc = field.description ?? "";
+				if (field.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(field.defaultValue)})`)}`;
+				if (field.required) desc += ` ${styles.required("(required)")}`;
+				const envInfo = formatEnvInfo(field.env);
+				if (envInfo) desc += ` ${envInfo}`;
+				lines.push(formatOption(flags, desc, 1));
+				const negationLine = formatNegationLine(field, 1);
+				if (negationLine) lines.push(negationLine);
+			}
+		} else {
+			lines.push("");
+			lines.push(`  ${styles.bold(`${label}:`)}`);
+			lines.push(`    ${styles.dim(styles.italic("no options"))}`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Format option flags (-v, --verbose <VALUE>)
+* Uses cliName (kebab-case) for display
+*/
+function formatFlags(opt) {
+	const aliasParts = [];
+	if (opt.alias) {
+		for (const alias of opt.alias) if (alias.length === 1) aliasParts.push(styles.option(`-${alias}`));
+	}
+	let longFlag = styles.option(`--${opt.cliName}`);
+	if (opt.type !== "boolean") {
+		const placeholder = opt.placeholder ?? opt.cliName.toUpperCase();
+		longFlag += ` ${styles.placeholder(`<${placeholder}>`)}`;
+	}
+	aliasParts.push(longFlag);
+	if (opt.alias) {
+		for (const alias of opt.alias) if (alias.length > 1) {
+			let longAlias = styles.option(`--${alias}`);
+			if (opt.type !== "boolean") {
+				const placeholder = opt.placeholder ?? opt.cliName.toUpperCase();
+				longAlias += ` ${styles.placeholder(`<${placeholder}>`)}`;
+			}
+			aliasParts.push(longAlias);
+		}
+	}
+	const aliasStr = aliasParts.join(", ");
+	if (opt.type === "boolean" && opt.negationDisplay && !opt.negationDescription) return `${aliasStr} / ${styles.option(`--${opt.negationDisplay}`)}`;
+	return aliasStr;
+}
+/**
+* Format environment variable info for help display
+*/
+function formatEnvInfo(env) {
+	if (!env) return "";
+	const envNames = Array.isArray(env) ? env : [env];
+	return styles.dim(`[env: ${envNames.join(", ")}]`);
+}
+/**
+* Strip ANSI escape codes from a string to get visual length
+*/
+function stripAnsi(str) {
+	return str.replace(/\x1B\[[0-9;]*m/g, "");
+}
+/**
+* Pad a string that may contain ANSI codes to a visual width
+*/
+function padEndVisual(str, width) {
+	const visualLength = stripAnsi(str).length;
+	const padding = Math.max(0, width - visualLength);
+	return str + " ".repeat(padding);
+}
+/**
+* Format a single option line
+* If flags exceed the column width, description is moved to the next line
+*/
+function formatOption(flags, description, indent = 0, extraDescPadding = 0) {
+	const flagWidth = 32;
+	const indentStr = "  ".repeat(indent);
+	const visualFlagLength = stripAnsi(flags).length;
+	const effectiveFlagWidth = flagWidth - indent * 2 + extraDescPadding;
+	if (visualFlagLength >= effectiveFlagWidth) return `${indentStr}  ${flags}\n${" ".repeat(effectiveFlagWidth + 2 + indent * 2)}${description}`;
+	return `${indentStr}  ${padEndVisual(flags, effectiveFlagWidth)}${description}`;
+}
+/**
+* Format a single option field as a help line
+*/
+function formatFieldLine(opt, indent = 0, extraDescPadding = 0) {
+	const flags = formatFlags(opt);
+	let desc = opt.description ?? "";
+	if (opt.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(opt.defaultValue)})`)}`;
+	if (opt.required) desc += ` ${styles.required("(required)")}`;
+	const envInfo = formatEnvInfo(opt.env);
+	if (envInfo) desc += ` ${envInfo}`;
+	return formatOption(flags, desc, indent, extraDescPadding);
+}
+/**
+* Render global options section
+*/
+function renderGlobalOptions(globalExtracted) {
+	const lines = [];
+	for (const opt of globalExtracted.fields) {
+		if (opt.positional) continue;
+		lines.push(formatFieldLine(opt));
+		const negationLine = formatNegationLine(opt);
+		if (negationLine) lines.push(negationLine);
+	}
+	return lines.join("\n");
+}
+/**
+* Render options for a subcommand (used by showSubcommandOptions)
+*/
+function renderSubcommandOptionsCompact(command, indent) {
+	const lines = [];
+	const extracted = getExtractedFields(command);
+	if (extracted) {
+		const options = extracted.fields.filter((a) => !a.positional);
+		for (const opt of options) {
+			const flags = formatFlags(opt);
+			let desc = opt.description ?? "";
+			if (opt.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(opt.defaultValue)})`)}`;
+			const envInfo = formatEnvInfo(opt.env);
+			if (envInfo) desc += ` ${envInfo}`;
+			lines.push(formatOption(flags, desc, indent, 2));
+			const negationLine = formatNegationLine(opt, indent, 2);
+			if (negationLine) lines.push(negationLine);
+		}
+	}
+	return lines;
+}
+/**
+* Render subcommands recursively with their options (flat style)
+*/
+function renderSubcommandsWithOptions(subCommands, parentPath, baseIndent) {
+	const lines = [];
+	for (const [name, subCmd] of getVisibleSubcommandEntries(subCommands)) {
+		const cmd = resolveSubCommandMeta(subCmd);
+		const fullPath = parentPath ? `${parentPath} ${name}` : name;
+		const desc = cmd?.description ?? "";
+		const aliases = cmd?.aliases;
+		const displayName = aliases && aliases.length > 0 ? `${fullPath}, ${aliases.join(", ")}` : fullPath;
+		lines.push(formatOption(styles.command(displayName), desc, baseIndent));
+		if (cmd) {
+			const optionLines = renderSubcommandOptionsCompact(cmd, baseIndent + 1);
+			lines.push(...optionLines);
+			const visibleNestedSubCommands = cmd.subCommands ? Object.fromEntries(getVisibleSubcommandEntries(cmd.subCommands)) : void 0;
+			if (visibleNestedSubCommands && Object.keys(visibleNestedSubCommands).length > 0) {
+				const nestedLines = renderSubcommandsWithOptions(visibleNestedSubCommands, fullPath, baseIndent);
+				lines.push(...nestedLines);
+			}
+		}
+	}
+	return lines;
+}
+/**
+* Generate help text for a command
+*
+* @param command - The command to generate help for
+* @param options - Help generation options
+* @returns Formatted help text
+*/
+function generateHelp(command, options) {
+	const sections = [];
+	const context = options.context;
+	const displayName = buildFullCommandName(command, context);
+	if (displayName) {
+		let header = styles.commandName(displayName);
+		if (context?.rootName && context.commandPath && context.commandPath.length > 0) if (context.rootVersion) header += ` ${styles.version(`(${context.rootName} v${context.rootVersion})`)}`;
+		else header += ` ${styles.version(`(${context.rootName})`)}`;
+		else if (context?.rootVersion) header += ` ${styles.version(`v${context.rootVersion}`)}`;
+		sections.push(header);
+	}
+	if (context?.aliasFor) sections.push(styles.dim(`Alias for ${styles.commandName(context.aliasFor)}`));
+	if (command.description) sections.push(command.description);
+	if (!context?.aliasFor && command.aliases && command.aliases.length > 0) sections.push(`${styles.sectionHeader("Aliases:")} ${command.aliases.map((a) => styles.command(a)).join(", ")}`);
+	sections.push(`${styles.sectionHeader("Usage:")} ${renderUsageLine(command, context)}`);
+	const optionsText = renderOptions(command, options.descriptions, context);
+	if (optionsText) sections.push(`${styles.sectionHeader("Options:")}\n${optionsText}`);
+	if (context?.globalExtracted?.fields.length) sections.push(`${styles.sectionHeader("Global Options:")}\n${renderGlobalOptions(context.globalExtracted)}`);
+	if (options.showSubcommands !== false && command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) {
+		const currentPath = context?.commandPath?.join(" ") ?? "";
+		const visibleSubCommands = Object.fromEntries(getVisibleSubcommandEntries(command.subCommands));
+		if (options.showSubcommandOptions) {
+			const subLines = renderSubcommandsWithOptions(visibleSubCommands, currentPath, 0);
+			sections.push(`${styles.sectionHeader("Commands:")}\n${subLines.join("\n")}`);
+		} else {
+			const subLines = [];
+			for (const [name, subCmd] of Object.entries(visibleSubCommands)) {
+				const cmd = resolveSubCommandMeta(subCmd);
+				const desc = cmd?.description ?? "";
+				const fullName = currentPath ? `${currentPath} ${name}` : name;
+				const aliases = cmd?.aliases;
+				const displayName = aliases && aliases.length > 0 ? `${fullName}, ${aliases.join(", ")}` : fullName;
+				subLines.push(formatOption(styles.command(displayName), desc));
+			}
+			sections.push(`${styles.sectionHeader("Commands:")}\n${subLines.join("\n")}`);
+		}
+	}
+	if (command.examples && command.examples.length > 0) {
+		const exampleLines = renderExamplesForHelp(command.examples, context);
+		sections.push(`${styles.sectionHeader("Examples:")}\n${exampleLines}`);
+	}
+	if (command.notes) {
+		const indented = renderMarkdown(command.notes).split("\n").map((line) => line === "" ? "" : `  ${line}`).join("\n");
+		sections.push(`${styles.sectionHeader("Notes:")}\n${indented}`);
+	}
+	return `\n${sections.join("\n\n")}\n`;
+}
+/**
+* Render examples for CLI help output
+*/
+function renderExamplesForHelp(examples, context) {
+	const lines = [];
+	const cmdPrefix = context?.rootName ? `${context.rootName} ` : "";
+	const cmdPath = context?.commandPath?.join(" ") ?? "";
+	const fullPrefix = cmdPath ? `${cmdPrefix}${cmdPath} ` : cmdPrefix;
+	for (const example of examples) {
+		lines.push(`  ${styles.dim(example.desc)}`);
+		lines.push(`    ${styles.dim("$")} ${fullPrefix}${example.cmd}`);
+		if (example.output) for (const line of example.output.split("\n")) lines.push(`    ${line}`);
+		lines.push("");
+	}
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+
+//#endregion
+//#region ../core/src/validator/validation-errors.ts
+/**
+* Error thrown when positional argument configuration is invalid
+*/
+var PositionalConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PositionalConfigError";
+	}
+};
+/**
+* Error thrown when a reserved alias is used
+*/
+var ReservedAliasError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ReservedAliasError";
+	}
+};
+/**
+* Error thrown when duplicate field names are detected
+*/
+var DuplicateFieldError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DuplicateFieldError";
+	}
+};
+/**
+* Error thrown when duplicate aliases are detected
+*/
+var DuplicateAliasError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DuplicateAliasError";
+	}
+};
+/**
+* Error thrown when fields are case variants of each other (e.g. "my-option" and "myOption")
+*/
+var CaseVariantCollisionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CaseVariantCollisionError";
+	}
+};
+/**
+* Error thrown when a custom boolean negation name collides with another
+* field's name, cliName, alias, or another field's negation (including
+* derived camelCase variants).
+*/
+var DuplicateNegationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "DuplicateNegationError";
+	}
+};
+/**
+* Error thrown when a field name collides with a reserved, framework-injected
+* key on the final args object (e.g. `$source`).
+*/
+var ReservedFieldNameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ReservedFieldNameError";
+	}
+};
+/**
+* Error thrown when a global field and a same-named local field have
+* different definitions (per `extractFields()`'s type bucket, whether the
+* field is positional, and enum values). Only exactly-matching definitions
+* are allowed to share a name across global/local schemas — anything else
+* is rejected at validation time rather than risking a value from one
+* schema silently flowing into the other.
+*/
+var FieldTypeConflictError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FieldTypeConflictError";
+	}
+};
+
+//#endregion
+//#region ../core/src/validator/command-validator.ts
+/**
+* Check for duplicate field names
+*/
+function checkDuplicateFields(extracted, commandPath) {
+	const errors = [];
+	const seenNames = /* @__PURE__ */ new Map();
+	for (const field of extracted.fields) {
+		if (seenNames.has(field.name)) errors.push({
+			commandPath,
+			type: "duplicate_field",
+			message: `Duplicate field name "${field.name}" detected.`,
+			field: field.name
+		});
+		seenNames.set(field.name, field.name);
+	}
+	return errors;
+}
+/**
+* Check for case-variant collisions (e.g. "my-option" and "myOption" defined simultaneously)
+*/
+function checkCaseVariantCollisions(extracted, commandPath) {
+	const errors = [];
+	const canonicalMap = /* @__PURE__ */ new Map();
+	for (const field of extracted.fields) {
+		const camel = toCamelCase(field.name);
+		const existing = canonicalMap.get(camel);
+		if (existing && existing !== field.name) errors.push({
+			commandPath,
+			type: "case_variant_collision",
+			message: `Fields "${existing}" and "${field.name}" are case variants of each other and would collide.`,
+			field: field.name
+		});
+		canonicalMap.set(camel, field.name);
+	}
+	return errors;
+}
+/**
+* Check for duplicate aliases and alias-field name conflicts
+*/
+function checkDuplicateAliases(extracted, commandPath) {
+	const errors = [];
+	const seenAliases = /* @__PURE__ */ new Map();
+	const fieldNames = new Set(extracted.fields.map((f) => f.name));
+	const cliNames = new Set(extracted.fields.map((f) => f.cliName));
+	const registerAlias = (alias, fieldName, isDerived) => {
+		if (fieldNames.has(alias) || cliNames.has(alias)) errors.push({
+			commandPath,
+			type: "duplicate_alias",
+			message: `Alias "${alias}" for field "${fieldName}" conflicts with existing field name or CLI name "${alias}".`,
+			field: fieldName
+		});
+		const existingField = seenAliases.get(alias);
+		if (existingField && existingField !== fieldName) {
+			const qualifier = isDerived ? " (derived camelCase variant)" : "";
+			errors.push({
+				commandPath,
+				type: "duplicate_alias",
+				message: `Duplicate alias "${alias}"${qualifier} detected. Both "${existingField}" and "${fieldName}" use the same alias.`,
+				field: fieldName
+			});
+		}
+		seenAliases.set(alias, fieldName);
+	};
+	for (const field of extracted.fields) {
+		const allAliases = getAllAliases(field);
+		if (allAliases.length === 0) continue;
+		for (const alias of allAliases) {
+			registerAlias(alias, field.name, false);
+			if (alias.length > 1 && alias.includes("-")) {
+				const camelVariant = toCamelCase(alias);
+				if (camelVariant !== alias && !fieldNames.has(camelVariant)) registerAlias(camelVariant, field.name, true);
+			}
+		}
+	}
+	return errors;
+}
+/**
+* Check for collisions involving custom boolean `negation` names
+*/
+function checkDuplicateNegations(extracted, commandPath) {
+	const errors = [];
+	const claimed = /* @__PURE__ */ new Map();
+	const claim = (name, fieldName, kind) => {
+		if (!claimed.has(name)) claimed.set(name, {
+			field: fieldName,
+			kind
+		});
+	};
+	for (const field of extracted.fields) {
+		claim(field.name, field.name, "field name");
+		if (field.name.includes("-")) {
+			const camelName = toCamelCase(field.name);
+			if (camelName !== field.name) claim(camelName, field.name, "field name");
+		}
+		if (field.cliName !== field.name) claim(field.cliName, field.name, "CLI name");
+		if (field.cliName.includes("-")) {
+			const camelCli = toCamelCase(field.cliName);
+			if (camelCli !== field.cliName) claim(camelCli, field.name, "CLI name");
+		}
+		for (const alias of getAllAliases(field)) {
+			claim(alias, field.name, "alias");
+			if (alias.length > 1 && alias.includes("-")) {
+				const camelVariant = toCamelCase(alias);
+				if (camelVariant !== alias) claim(camelVariant, field.name, "alias");
+			}
+		}
+		if (field.type === "boolean" && field.negation === true) {
+			const defaultKebab = `no-${field.cliName}`;
+			claim(defaultKebab, field.name, "default negation");
+			const camelBase = toCamelCase(field.cliName);
+			const defaultCamel = `no${camelBase[0]?.toUpperCase() ?? ""}${camelBase.slice(1)}`;
+			if (defaultCamel !== defaultKebab) claim(defaultCamel, field.name, "default negation");
+		}
+	}
+	const seenNegations = /* @__PURE__ */ new Map();
+	const register = (name, fieldName, isDerived) => {
+		const claim = claimed.get(name);
+		if (claim) {
+			const qualifier = isDerived ? " (derived camelCase variant)" : "";
+			const conflict = claim.field === fieldName ? `the same field's own ${claim.kind} "${name}"` : `${claim.kind} "${name}" of field "${claim.field}"`;
+			errors.push({
+				commandPath,
+				type: "duplicate_negation",
+				message: `Negation "${name}"${qualifier} for field "${fieldName}" conflicts with ${conflict}.`,
+				field: fieldName
+			});
+		}
+		const existing = seenNegations.get(name);
+		if (existing && existing !== fieldName) {
+			const qualifier = isDerived ? " (derived camelCase variant)" : "";
+			errors.push({
+				commandPath,
+				type: "duplicate_negation",
+				message: `Duplicate negation "${name}"${qualifier} detected. Both "${existing}" and "${fieldName}" use the same negation name.`,
+				field: fieldName
+			});
+		}
+		seenNegations.set(name, fieldName);
+	};
+	for (const field of extracted.fields) {
+		if (typeof field.negation !== "string") continue;
+		register(field.negation, field.name, false);
+		if (field.negation.includes("-")) {
+			const camelVariant = toCamelCase(field.negation);
+			if (camelVariant !== field.negation) register(camelVariant, field.name, true);
+		}
+	}
+	return errors;
+}
+/**
+* Check positional argument configuration
+*/
+function checkPositionalConfig(extracted, commandPath) {
+	const errors = [];
+	const positionalFields = extracted.fields.filter((f) => f.positional);
+	let foundArrayPositional = null;
+	let foundOptionalPositional = null;
+	for (const field of positionalFields) {
+		if (foundArrayPositional !== null) errors.push({
+			commandPath,
+			type: "positional_config",
+			message: `Positional argument "${field.name}" cannot follow array positional argument "${foundArrayPositional}".`,
+			field: field.name
+		});
+		if (field.type === "array" && foundOptionalPositional !== null) errors.push({
+			commandPath,
+			type: "positional_config",
+			message: `Array positional "${field.name}" cannot be used with optional positional "${foundOptionalPositional}" (ambiguous parsing).`,
+			field: field.name
+		});
+		if (foundOptionalPositional !== null && field.required) errors.push({
+			commandPath,
+			type: "positional_config",
+			message: `Required positional "${field.name}" cannot follow optional positional "${foundOptionalPositional}".`,
+			field: field.name
+		});
+		if (field.type === "array") foundArrayPositional = field.name;
+		if (!field.required) foundOptionalPositional = field.name;
+	}
+	return errors;
+}
+/**
+* Check for reserved aliases used without override flag
+*/
+function checkReservedAliases(extracted, commandPath) {
+	const errors = [];
+	for (const field of extracted.fields) {
+		if (field.overrideBuiltinAlias === true) continue;
+		for (const alias of getAllAliases(field)) if (alias === "h" || alias === "H") errors.push({
+			commandPath,
+			type: "reserved_alias",
+			message: `Alias "${alias}" is reserved for --${alias === "h" ? "help" : "help-all"}.`,
+			field: field.name
+		});
+	}
+	return errors;
+}
+/**
+* Check for field names starting with `$`.
+*
+* The `$` prefix is reserved for framework-injected helpers on the final
+* args object (e.g. `$source`). It is also impractical as a real CLI flag
+* since an unquoted `$name` is expanded by the shell before it ever reaches
+* the program, so this is rejected outright rather than merely discouraged.
+*
+* Aliases can't start with `$` (schema extraction already restricts alias
+* characters to `[A-Za-z0-9-]`), and `cliName` is derived from `name` via
+* `toKebabCase`, which never strips or moves a leading `$` — so checking
+* `field.name` alone covers every way `$` could reach the final args object.
+*/
+function checkReservedFieldNames(extracted, commandPath) {
+	const errors = [];
+	for (const field of extracted.fields) if (field.name.startsWith("$")) errors.push({
+		commandPath,
+		type: "reserved_field_name",
+		message: `Field "${field.name}" starts with "$", which is reserved for framework-injected helpers (e.g. $source).`,
+		field: field.name
+	});
+	return errors;
+}
+/**
+* Validate that no duplicate field names exist
+*
+* @param extracted - Extracted fields from schema
+* @throws {DuplicateFieldError} If duplicate field names are found
+*/
+function validateDuplicateFields(extracted) {
+	const errors = checkDuplicateFields(extracted, []);
+	if (errors.length > 0) throw new DuplicateFieldError(`Duplicate field name "${errors[0]?.field ?? "unknown"}" detected. Each field must have a unique name.`);
+}
+/**
+* Validate that no duplicate aliases exist
+*
+* Also checks for conflicts between aliases and field names
+*
+* @param extracted - Extracted fields from schema
+* @throws {DuplicateAliasError} If duplicate aliases are found or alias conflicts with field name
+*/
+function validateDuplicateAliases(extracted) {
+	const errors = checkDuplicateAliases(extracted, []);
+	if (errors.length > 0) {
+		const err = errors[0];
+		throw new DuplicateAliasError(err.message);
+	}
+}
+/**
+* Validate positional argument configuration
+*
+* Rules:
+* - Array positional arguments must be the last positional
+* - No positional arguments can follow an array positional
+* - Required positional arguments cannot follow optional positional arguments
+* - Array positional and optional positional cannot be used together (ambiguous parsing)
+*
+* @param extracted - Extracted fields from schema
+* @throws {PositionalConfigError} If configuration is invalid
+*/
+function validatePositionalConfig(extracted) {
+	const errors = checkPositionalConfig(extracted, []);
+	if (errors.length > 0) {
+		const err = errors[0];
+		throw new PositionalConfigError(err.message);
+	}
+}
+/**
+* Validate that no reserved aliases are used without explicit override
+*
+* Reserved aliases:
+* - 'h' is reserved for --help
+* - 'H' is reserved for --help-all
+*
+* Users can override these by setting overrideBuiltinAlias: true
+*
+* @param extracted - Extracted fields from schema
+* @param _hasSubCommands - Whether the command has subcommands (reserved for future use)
+* @throws {ReservedAliasError} If a reserved alias is used without override flag
+*/
+function validateReservedAliases(extracted, _hasSubCommands) {
+	const errors = checkReservedAliases(extracted, []);
+	if (errors.length > 0) {
+		const field = errors[0].field ?? "unknown";
+		const found = extracted.fields.find((f) => f.name === field);
+		const alias = (found ? getAllAliases(found) : []).find((a) => a === "h" || a === "H") ?? "h";
+		throw new ReservedAliasError(`Alias "${alias}" is reserved for --${alias === "h" ? "help" : "help-all"}. To override this, set { overrideBuiltinAlias: true } for "${field}" and keep the alias where it is currently defined (in alias or hiddenAlias).`);
+	}
+}
+/**
+* Validate that no field name starts with `$`
+*
+* The `$` prefix is reserved for framework-injected helpers on the final
+* args object (e.g. `$source`), and is unusable as a real CLI flag anyway
+* since an unquoted `$name` gets shell-expanded before the program sees it.
+*
+* Checking `field.name` alone is sufficient: aliases can't start with `$`
+* (schema extraction already restricts alias characters to `[A-Za-z0-9-]`),
+* and `cliName` is derived from `name` via `toKebabCase`, which never strips
+* or moves a leading `$`. See {@link checkReservedFieldNames}.
+*
+* @param extracted - Extracted fields from schema
+* @throws {ReservedFieldNameError} If a field name starts with "$"
+*/
+function validateReservedFieldNames(extracted) {
+	const errors = checkReservedFieldNames(extracted, []);
+	if (errors.length > 0) {
+		const err = errors[0];
+		throw new ReservedFieldNameError(err.message);
+	}
+}
+/**
+* Validate that custom boolean negation names do not collide with anything
+*
+* @param extracted - Extracted fields from schema
+* @throws {DuplicateNegationError} If a colliding negation is found
+*/
+function validateDuplicateNegations(extracted) {
+	const errors = checkDuplicateNegations(extracted, []);
+	if (errors.length > 0) {
+		const err = errors[0];
+		throw new DuplicateNegationError(err.message);
+	}
+}
+/**
+* Validate that no case-variant collisions exist
+*
+* @param extracted - Extracted fields from schema
+* @throws {CaseVariantCollisionError} If case-variant collisions are found
+*/
+function validateCaseVariantCollisions(extracted) {
+	const errors = checkCaseVariantCollisions(extracted, []);
+	if (errors.length > 0) {
+		const err = errors[0];
+		throw new CaseVariantCollisionError(err.message);
+	}
+}
+/**
+* Check whether two same-named fields from different schemas (e.g. global
+* args and command args) have identical definitions. Only the facts
+* `extractFields()` already exposes are compared: the coarse type bucket,
+* whether the field is positional, and, for enum-like fields, the exact
+* set of allowed values. Anything `extractFields()` can't see (e.g. a
+* `.refine()`) is intentionally not compared — this is a coarse, cheap
+* equality check, not a full schema comparison.
+*/
+function fieldsAreIdentical(a, b) {
+	if (a.type !== b.type) return false;
+	if (a.positional !== b.positional) return false;
+	const aEnum = a.enumValues;
+	const bEnum = b.enumValues;
+	if (!aEnum && !bEnum) return true;
+	if (!aEnum || !bEnum) return false;
+	const aSet = new Set(aEnum);
+	const bSet = new Set(bEnum);
+	if (aSet.size !== bSet.size) return false;
+	for (const value of aSet) if (!bSet.has(value)) return false;
+	return true;
+}
+/**
+* Check for cross-schema collisions between two schemas (e.g., global args
+* and command args): neither a case-variant collision (same canonical name,
+* different spelling) nor a same-named field with a different definition
+* (same spelling, but the two schemas don't agree on what values are valid).
+*/
+function checkCrossSchemaCollisions(extractedA, extractedB, commandPath) {
+	const errors = [];
+	const canonicalMap = /* @__PURE__ */ new Map();
+	for (const field of extractedA.fields) canonicalMap.set(toCamelCase(field.name), field);
+	for (const field of extractedB.fields) {
+		const camel = toCamelCase(field.name);
+		const existing = canonicalMap.get(camel);
+		if (!existing) continue;
+		if (existing.name !== field.name) {
+			errors.push({
+				commandPath,
+				type: "case_variant_collision",
+				message: `Global field "${existing.name}" and command field "${field.name}" are case variants of each other and would collide.`,
+				field: field.name
+			});
+			continue;
+		}
+		if (!fieldsAreIdentical(existing, field)) errors.push({
+			commandPath,
+			type: "field_type_conflict",
+			message: `Global field "${existing.name}" and command field "${field.name}" share the same name but have different definitions.`,
+			field: field.name
+		});
+	}
+	return errors;
+}
+/**
+* Validate that no cross-schema collisions exist between two schemas
+* (e.g., global args and command args): neither a case-variant collision
+* (same canonical name, different spelling) nor a same-named field with a
+* different definition (same spelling, but the two schemas don't agree on
+* what values are valid).
+*
+* @param extractedA - Extracted fields from first schema (e.g., global args)
+* @param extractedB - Extracted fields from second schema (e.g., command args)
+* @throws {CaseVariantCollisionError} If cross-schema case-variant collisions are found
+* @throws {FieldTypeConflictError} If a same-named field has a different definition on each schema
+*/
+function validateCrossSchemaCollisions(extractedA, extractedB) {
+	const err = checkCrossSchemaCollisions(extractedA, extractedB, [])[0];
+	if (!err) return;
+	if (err.type === "case_variant_collision") throw new CaseVariantCollisionError(err.message);
+	throw new FieldTypeConflictError(err.message);
+}
+/**
+* Collect validation errors for a single command's schema (non-throwing)
+*/
+function collectSchemaErrors(extracted, _hasSubCommands, commandPath) {
+	return [
+		...checkDuplicateFields(extracted, commandPath),
+		...checkCaseVariantCollisions(extracted, commandPath),
+		...checkDuplicateAliases(extracted, commandPath),
+		...checkDuplicateNegations(extracted, commandPath),
+		...checkPositionalConfig(extracted, commandPath),
+		...checkReservedAliases(extracted, commandPath),
+		...checkReservedFieldNames(extracted, commandPath)
+	];
+}
+/**
+* Check for alias conflicts within subcommands
+* - Aliases must not conflict with subcommand names
+* - Aliases must not conflict with other aliases
+*/
+function checkSubCommandAliasConflicts(command, commandPath) {
+	const errors = [];
+	if (!command.subCommands) return errors;
+	const nameToOwner = /* @__PURE__ */ new Map();
+	for (const [name] of Object.entries(command.subCommands)) nameToOwner.set(name, name);
+	for (const [name, subCmdValue] of Object.entries(command.subCommands)) {
+		const resolved = isLazyCommand(subCmdValue) ? subCmdValue.meta : typeof subCmdValue !== "function" ? subCmdValue : null;
+		if (!resolved?.aliases) continue;
+		const subCommandPath = [...commandPath, name];
+		for (const alias of resolved.aliases) {
+			if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(alias)) {
+				errors.push({
+					commandPath: subCommandPath,
+					type: "invalid_alias",
+					message: `Alias "${alias}" is invalid. Aliases must start with an alphanumeric character and contain only alphanumeric characters, hyphens, or underscores.`,
+					field: name
+				});
+				continue;
+			}
+			if (alias === name) {
+				errors.push({
+					commandPath: subCommandPath,
+					type: "duplicate_alias",
+					message: `Alias "${alias}" conflicts with its own name.`,
+					field: name
+				});
+				continue;
+			}
+			const existing = nameToOwner.get(alias);
+			if (existing) if (existing === name) errors.push({
+				commandPath: subCommandPath,
+				type: "duplicate_alias",
+				message: `Alias "${alias}" is duplicated within the alias list.`,
+				field: name
+			});
+			else errors.push({
+				commandPath: subCommandPath,
+				type: "duplicate_alias",
+				message: `Alias "${alias}" conflicts with existing subcommand or alias "${existing}".`,
+				field: name
+			});
+			else nameToOwner.set(alias, name);
+		}
+	}
+	return errors;
+}
+/**
+* Validate a command and all its subcommands recursively
+*
+* This function collects all validation errors without throwing,
+* making it suitable for test assertions.
+*
+* @param command - The command to validate
+* @param options - Validation options
+* @returns Validation result with all errors collected
+*
+* @example
+* ```ts
+* const result = await validateCommand(myCommand);
+* if (!result.valid) {
+*   console.error(result.errors);
+* }
+* ```
+*/
+async function validateCommand(command, options = {}) {
+	const commandPath = options.commandPath ?? [command.name];
+	const errors = [];
+	const hasSubCommands = command.subCommands ? Object.keys(command.subCommands).length > 0 : false;
+	const globalExtracted = options.globalArgs ? extractFields(options.globalArgs) : void 0;
+	if (command.args) {
+		const extracted = extractFields(command.args);
+		errors.push(...collectSchemaErrors(extracted, hasSubCommands, commandPath));
+		if (globalExtracted) errors.push(...checkCrossSchemaCollisions(globalExtracted, extracted, commandPath));
+	}
+	errors.push(...checkSubCommandAliasConflicts(command, commandPath));
+	if (command.subCommands) for (const [name, subCmd] of Object.entries(command.subCommands)) {
+		const subResult = await validateCommand(await resolveLazyCommand(subCmd), {
+			commandPath: [...commandPath, name],
+			...options.globalArgs ? { globalArgs: options.globalArgs } : {}
+		});
+		if (!subResult.valid) errors.push(...subResult.errors);
+	}
+	if (errors.length === 0) return { valid: true };
+	return {
+		valid: false,
+		errors
+	};
+}
+/**
+* Format command validation errors for display
+*
+* @param errors - Array of validation errors
+* @returns Formatted error message
+*/
+function formatCommandValidationErrors(errors) {
+	if (errors.length === 0) return "";
+	const lines = ["Command definition errors:"];
+	for (const error of errors) {
+		const path = error.commandPath.join(" > ");
+		lines.push(`  - [${path}] ${error.message}`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+//#region ../core/src/parser/long-option-resolver.ts
+/** Return a long option's name without leading dashes or an inline value. */
+function getLongOptionName(arg) {
+	const equalsIndex = arg.indexOf("=");
+	return equalsIndex >= 0 ? arg.slice(2, equalsIndex) : arg.slice(2);
+}
+function resolveLongOption(arg, lookup) {
+	const withoutDashes = getLongOptionName(arg);
+	if (!arg.includes("=")) {
+		const negatedField = lookup.negationMap.get(withoutDashes);
+		if (negatedField && lookup.booleanFlags.has(negatedField)) return {
+			resolvedName: negatedField,
+			withoutDashes,
+			isNegated: true,
+			isCustomNegation: true,
+			isSuppressedNegation: false
+		};
+	}
+	const hasEquals = arg.includes("=");
+	if (!hasEquals && withoutDashes.startsWith("no-")) {
+		const flagName = withoutDashes.slice(3);
+		if (flagName === flagName.toLowerCase()) {
+			const resolvedName = lookup.aliasMap.get(flagName) ?? flagName;
+			if (lookup.booleanFlags.has(resolvedName)) {
+				const asIsResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
+				if (!lookup.definedNames.has(asIsResolved)) {
+					if (lookup.defaultNegationDisabledFields.has(resolvedName)) return {
+						resolvedName,
+						withoutDashes,
+						isNegated: false,
+						isCustomNegation: false,
+						isSuppressedNegation: true
+					};
+					return {
+						resolvedName,
+						withoutDashes,
+						isNegated: true,
+						isCustomNegation: false,
+						isSuppressedNegation: false
+					};
+				}
+			}
+		}
+	}
+	if (!hasEquals && withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2])) {
+		const camelFlagName = withoutDashes[2].toLowerCase() + withoutDashes.slice(3);
+		const resolvedName = lookup.aliasMap.get(camelFlagName) ?? camelFlagName;
+		if (lookup.booleanFlags.has(resolvedName)) {
+			const asIsResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
+			if (!lookup.definedNames.has(asIsResolved)) {
+				if (lookup.defaultNegationDisabledFields.has(resolvedName)) return {
+					resolvedName,
+					withoutDashes,
+					isNegated: false,
+					isCustomNegation: false,
+					isSuppressedNegation: true
+				};
+				return {
+					resolvedName,
+					withoutDashes,
+					isNegated: true,
+					isCustomNegation: false,
+					isSuppressedNegation: false
+				};
+			}
+		}
+	}
+	return {
+		resolvedName: lookup.aliasMap.get(withoutDashes) ?? withoutDashes,
+		withoutDashes,
+		isNegated: false,
+		isCustomNegation: false,
+		isSuppressedNegation: false
+	};
+}
+
+//#endregion
+//#region ../core/src/parser/argv-parser.ts
+/**
+* Coerce a `--flag=value` string to a boolean for boolean-typed flags.
+* Values other than "true"/"false" are passed through unchanged so
+* downstream validation reports the invalid input instead of silently
+* guessing.
+*/
+function coerceBoolean(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	return value;
+}
+/**
+* Matches tokens that look like a negative number (e.g. "-5", "-5.2", "-.5"),
+* as opposed to another flag. Used to decide whether a dash-prefixed token
+* should still be consumed as a value-taking option's value.
+*/
+const NEGATIVE_NUMBER_PATTERN = /^-\.?\d/;
+function looksLikeNegativeNumber(value) {
+	return NEGATIVE_NUMBER_PATTERN.test(value);
+}
+/**
+* Parse argv into a flat record
+*
+* Supports:
+* - Long options: --flag, --flag=value, --flag value
+* - Short options: -f, -f=value, -f value
+* - Combined short options: -abc (treated as -a -b -c if all are boolean)
+* - Positional arguments
+* - -- to stop parsing options
+* - Boolean negation: --no-flag, --noFlag (requires `booleanFlags` and `negation: true`)
+*
+* **Note:** When using negation detection (`--noFlag` / `--no-flag`),
+* supply `definedNames` so that options whose names happen to start with
+* "no" (e.g. `noDryRun`) are not mistaken for negation of another flag.
+* Without `definedNames`, all `--noX` forms matching a boolean flag will
+* be treated as negation.
+*
+* @param argv - Command line arguments
+* @param options - Parser options
+* @returns Parsed arguments
+*/
+function parseArgv(argv, options = {}) {
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), defaultNegationDisabledFields: configuredDefaultNegationDisabledFields } = options;
+	const longOptionLookup = {
+		aliasMap,
+		booleanFlags,
+		definedNames,
+		negationMap,
+		defaultNegationDisabledFields: configuredDefaultNegationDisabledFields ?? new Set(booleanFlags)
+	};
+	const result = {
+		options: {},
+		positionals: [],
+		rest: []
+	};
+	let i = 0;
+	let stopParsing = false;
+	const setOption = (name, value) => {
+		const resolvedName = aliasMap.get(name) ?? name;
+		if (arrayFlags.has(resolvedName)) {
+			const existing = result.options[resolvedName];
+			if (Array.isArray(existing)) existing.push(value);
+			else if (existing !== void 0) result.options[resolvedName] = [existing, value];
+			else result.options[resolvedName] = [value];
+		} else result.options[resolvedName] = value;
+	};
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (stopParsing) {
+			result.rest.push(arg);
+			i++;
+			continue;
+		}
+		if (arg === "--") {
+			stopParsing = true;
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--")) {
+			const withoutDashes = arg.slice(2);
+			const resolution = resolveLongOption(arg, longOptionLookup);
+			if (resolution.isSuppressedNegation) {
+				setOption(resolution.withoutDashes, true);
+				i++;
+				continue;
+			}
+			if (resolution.isNegated) {
+				setOption(resolution.resolvedName, false);
+				i++;
+				continue;
+			}
+			const eqIndex = withoutDashes.indexOf("=");
+			if (eqIndex !== -1) {
+				const name = withoutDashes.slice(0, eqIndex);
+				const value = withoutDashes.slice(eqIndex + 1);
+				const resolvedName = aliasMap.get(name) ?? name;
+				setOption(name, booleanFlags.has(resolvedName) ? coerceBoolean(value) : value);
+				i++;
+			} else {
+				const name = withoutDashes;
+				const resolvedName = aliasMap.get(name) ?? name;
+				if (booleanFlags.has(resolvedName)) {
+					setOption(name, true);
+					i++;
+				} else {
+					const nextArg = argv[i + 1];
+					if (nextArg !== void 0 && (!nextArg.startsWith("-") || looksLikeNegativeNumber(nextArg))) {
+						setOption(name, nextArg);
+						i += 2;
+					} else {
+						setOption(name, true);
+						i++;
+					}
+				}
+			}
+			continue;
+		}
+		if (arg.startsWith("-") && arg.length > 1 && !arg.startsWith("--")) {
+			const withoutDash = arg.slice(1);
+			const eqIndex = withoutDash.indexOf("=");
+			if (eqIndex !== -1) {
+				const name = withoutDash.slice(0, eqIndex);
+				const value = withoutDash.slice(eqIndex + 1);
+				const resolvedName = aliasMap.get(name) ?? name;
+				setOption(name, booleanFlags.has(resolvedName) ? coerceBoolean(value) : value);
+				i++;
+			} else if (withoutDash.length === 1) {
+				const name = withoutDash;
+				const resolvedName = aliasMap.get(name) ?? name;
+				if (booleanFlags.has(resolvedName)) {
+					setOption(name, true);
+					i++;
+				} else {
+					const nextArg = argv[i + 1];
+					if (nextArg !== void 0 && (!nextArg.startsWith("-") || looksLikeNegativeNumber(nextArg))) {
+						setOption(name, nextArg);
+						i += 2;
+					} else {
+						setOption(name, true);
+						i++;
+					}
+				}
+			} else {
+				for (const char of withoutDash) setOption(char, true);
+				i++;
+			}
+			continue;
+		}
+		result.positionals.push(arg);
+		i++;
+	}
+	return result;
+}
+/**
+* Build parser options from extracted fields
+*/
+function buildParserOptions(extracted) {
+	const aliasMap = /* @__PURE__ */ new Map();
+	const booleanFlags = /* @__PURE__ */ new Set();
+	const arrayFlags = /* @__PURE__ */ new Set();
+	const definedNames = /* @__PURE__ */ new Set();
+	const negationMap = /* @__PURE__ */ new Map();
+	const defaultNegationDisabledFields = /* @__PURE__ */ new Set();
+	for (const field of extracted.fields) definedNames.add(field.name);
+	for (const field of extracted.fields) {
+		if (field.cliName !== field.name) aliasMap.set(field.cliName, field.name);
+		for (const alias of getAllAliases(field)) {
+			aliasMap.set(alias, field.name);
+			if (alias.length > 1 && alias.includes("-")) {
+				const camelAlias = toCamelCase(alias);
+				if (camelAlias !== alias && !definedNames.has(camelAlias) && !aliasMap.has(camelAlias)) aliasMap.set(camelAlias, field.name);
+			}
+		}
+		const camelVariant = toCamelCase(field.name);
+		if (camelVariant !== field.name && !definedNames.has(camelVariant) && !aliasMap.has(camelVariant)) aliasMap.set(camelVariant, field.name);
+		if (field.type === "boolean") booleanFlags.add(field.name);
+		if (field.type === "array") arrayFlags.add(field.name);
+		if (field.type === "boolean" && field.negation !== true) {
+			defaultNegationDisabledFields.add(field.name);
+			if (typeof field.negation === "string") {
+				negationMap.set(field.negation, field.name);
+				if (field.negation.includes("-")) {
+					const camelNegation = toCamelCase(field.negation);
+					if (camelNegation !== field.negation) negationMap.set(camelNegation, field.name);
+				}
+			}
+		}
+	}
+	return {
+		aliasMap,
+		booleanFlags,
+		arrayFlags,
+		definedNames,
+		negationMap,
+		defaultNegationDisabledFields
+	};
+}
+/**
+* Merge parsed argv with positional fields to create a flat record
+*/
+function mergeWithPositionals(parsed, extracted) {
+	const result = { ...parsed.options };
+	const positionalFields = extracted.fields.filter((f) => f.positional);
+	const allPositionals = parsed.rest.length > 0 ? [...parsed.positionals, ...parsed.rest] : parsed.positionals;
+	let positionalIndex = 0;
+	for (const field of positionalFields) {
+		if (positionalIndex >= allPositionals.length) break;
+		if (field.type === "array") {
+			result[field.name] = allPositionals.slice(positionalIndex);
+			break;
+		} else {
+			result[field.name] = allPositionals[positionalIndex];
+			positionalIndex++;
+		}
+	}
+	return result;
+}
+
+//#endregion
+//#region ../core/src/parser/subcommand-scanner.ts
+/**
+* Build lookup tables from extracted global schema fields.
+* Shared by scanForSubcommand, separateGlobalArgs, and findFirstPositional.
+*/
+function buildGlobalFlagLookup(globalExtracted) {
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), defaultNegationDisabledFields = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
+	const shortAliases = /* @__PURE__ */ new Set();
+	for (const field of globalExtracted.fields) for (const alias of getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
+	return {
+		aliasMap,
+		booleanFlags,
+		definedNames,
+		flagNames: new Set(globalExtracted.fields.map((f) => f.name)),
+		cliNames: new Set(globalExtracted.fields.map((f) => f.cliName)),
+		aliases: shortAliases,
+		negationMap,
+		defaultNegationDisabledFields
+	};
+}
+/**
+* Resolve a long option (--flag, --flag=value, --no-flag, --custom-negation)
+* against global flag lookup. Returns the resolved camelCase name and whether
+* it is a known global flag.
+*
+* `isSuppressedNegation` is true when the token matches a disabled default
+* `--no-X` form on the target field.
+* The caller may use this to keep argv scanning past such tokens (so a
+* trailing subcommand is still detected) even though they no longer negate.
+*/
+function resolveGlobalLongOption(arg, lookup) {
+	const { resolvedName, withoutDashes, isNegated, isCustomNegation, isSuppressedNegation } = resolveLongOption(arg, lookup);
+	if (isSuppressedNegation) return {
+		resolvedName,
+		withoutDashes,
+		isNegated: false,
+		isGlobal: false,
+		isSuppressedNegation
+	};
+	const flagName = isNegated && !isCustomNegation ? withoutDashes.startsWith("no-") ? withoutDashes.slice(3) : withoutDashes[2].toLowerCase() + withoutDashes.slice(3) : withoutDashes;
+	return {
+		resolvedName,
+		withoutDashes,
+		isNegated,
+		isGlobal: lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName),
+		isSuppressedNegation: false
+	};
+}
+/**
+* Check whether a non-boolean flag should consume the next argv token as its value.
+* Returns true when the next token exists, is not a flag, and the current flag
+* is not boolean / negated / using = syntax.
+*/
+function shouldConsumeValue(arg, resolvedName, isNegated, nextArg, booleanFlags) {
+	return !arg.includes("=") && !booleanFlags.has(resolvedName) && !isNegated && nextArg !== void 0 && !nextArg.startsWith("-");
+}
+/**
+* Collect a recognized global flag (and its value if applicable) into `dest`,
+* returning how many argv positions were consumed (1 or 2).
+*/
+function collectGlobalFlag(argv, i, resolvedName, isNegated, booleanFlags, dest) {
+	const arg = argv[i];
+	dest.push(arg);
+	if (shouldConsumeValue(arg, resolvedName, isNegated, argv[i + 1], booleanFlags)) {
+		dest.push(argv[i + 1]);
+		return 2;
+	}
+	return 1;
+}
+/**
+* Scan argv to find the subcommand position, skipping over global flags.
+*
+* Walks argv and recognizes global flags (long, short, --no-*) so that
+* `my-cli --verbose build --output dist` correctly identifies `build` as
+* the subcommand (index 1) rather than treating `--verbose` as the subcommand.
+*
+* Limitation: flags appearing before the subcommand name are matched only
+* against the global schema. If a flag is defined in both global and a
+* subcommand's local schema, the pre-subcommand occurrence is always treated
+* as global because the local schema is not available until the subcommand is
+* identified (lazy-loaded commands make eager checking infeasible). Place
+* colliding flags after the subcommand name so that `separateGlobalArgs` can
+* apply local-precedence logic.
+*
+* @param argv - Command line arguments
+* @param subCommandNames - Valid subcommand names
+* @param globalExtracted - Extracted fields from global args schema
+* @returns Scan result with subcommand position and token separation
+*/
+function scanForSubcommand(argv, subCommandNames, globalExtracted) {
+	const lookup = buildGlobalFlagLookup(globalExtracted);
+	const subCommandNameSet = new Set(subCommandNames);
+	const globalTokensBefore = [];
+	const suppressedTokens = [];
+	let i = 0;
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (arg === "--" || BUILTIN_FLAGS.has(arg)) break;
+		if (!arg.startsWith("-") && subCommandNameSet.has(arg)) return {
+			subCommandIndex: i,
+			globalTokensBefore,
+			tokensAfterSubcommand: argv.slice(i + 1),
+			suppressedTokens
+		};
+		if (arg.startsWith("--")) {
+			const { resolvedName, withoutDashes, isNegated, isGlobal, isSuppressedNegation } = resolveGlobalLongOption(arg, lookup);
+			if (isGlobal) {
+				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokensBefore);
+				continue;
+			}
+			if (isSuppressedNegation) {
+				suppressedTokens.push(withoutDashes);
+				i++;
+				continue;
+			}
+			break;
+		}
+		if (arg.startsWith("-") && arg.length > 1) {
+			const withoutDash = arg.includes("=") ? arg.slice(1, arg.indexOf("=")) : arg.slice(1);
+			if (withoutDash.length === 1) {
+				const resolvedName = lookup.aliasMap.get(withoutDash) ?? withoutDash;
+				if (lookup.aliases.has(withoutDash) || lookup.flagNames.has(resolvedName)) {
+					i += collectGlobalFlag(argv, i, resolvedName, false, lookup.booleanFlags, globalTokensBefore);
+					continue;
+				}
+			}
+			break;
+		}
+		break;
+	}
+	return {
+		subCommandIndex: -1,
+		globalTokensBefore,
+		tokensAfterSubcommand: [],
+		suppressedTokens
+	};
+}
+const BUILTIN_FLAGS = /* @__PURE__ */ new Set([
+	"--help",
+	"-h",
+	"--help-all",
+	"-H",
+	"--version"
+]);
+/**
+* Find the index of the first positional argument in argv, properly skipping
+* global flag values. Returns -1 when no positional is present.
+*
+* Mirrors `scanForSubcommand`'s conservative stop conditions: the scan stops
+* (returning -1) on a `--` terminator, a builtin flag (`--help`/`--version`),
+* an unknown long flag, or an unknown/combined short flag. Past such tokens we
+* can't tell a flag *value* from a positional, so continuing would misclassify
+* e.g. `--help plugin` or `--unknown value` and wrongly trip plugin dispatch.
+*
+* Without globalExtracted, no flag is global, so any leading flag halts the
+* scan and a positional is only found when it precedes every flag.
+*/
+function findFirstPositionalIndex(argv, globalExtracted, options = {}) {
+	const stopOnSuppressedNegation = options.stopOnSuppressedNegation === true || globalExtracted?.unknownKeysMode === "strict";
+	const lookup = globalExtracted ? buildGlobalFlagLookup(globalExtracted) : {
+		aliasMap: /* @__PURE__ */ new Map(),
+		booleanFlags: /* @__PURE__ */ new Set(),
+		definedNames: /* @__PURE__ */ new Set(),
+		flagNames: /* @__PURE__ */ new Set(),
+		cliNames: /* @__PURE__ */ new Set(),
+		aliases: /* @__PURE__ */ new Set(),
+		negationMap: /* @__PURE__ */ new Map(),
+		defaultNegationDisabledFields: /* @__PURE__ */ new Set()
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (!arg.startsWith("-")) return i;
+		if (arg === "--" || BUILTIN_FLAGS.has(arg)) return -1;
+		if (arg.startsWith("--")) {
+			const { resolvedName, isNegated, isGlobal, isSuppressedNegation } = resolveGlobalLongOption(arg, lookup);
+			if (isGlobal) {
+				if (shouldConsumeValue(arg, resolvedName, isNegated, argv[i + 1], lookup.booleanFlags)) i++;
+				continue;
+			}
+			if (isSuppressedNegation) {
+				if (stopOnSuppressedNegation) return -1;
+				continue;
+			}
+			return -1;
+		}
+		const withoutDash = arg.includes("=") ? arg.slice(1, arg.indexOf("=")) : arg.slice(1);
+		if (withoutDash.length === 1) {
+			const resolvedName = lookup.aliasMap.get(withoutDash) ?? withoutDash;
+			if (lookup.aliases.has(withoutDash) || lookup.flagNames.has(resolvedName)) {
+				if (shouldConsumeValue(arg, resolvedName, false, argv[i + 1], lookup.booleanFlags)) i++;
+				continue;
+			}
+		}
+		return -1;
+	}
+	return -1;
+}
+/**
+* Find the first positional argument in argv, properly skipping global flag
+* values. Thin wrapper over {@link findFirstPositionalIndex} — see that
+* function for the scan and stop conditions. Returns `undefined` when none.
+*/
+function findFirstPositional(argv, globalExtracted) {
+	const index = findFirstPositionalIndex(argv, globalExtracted);
+	return index >= 0 ? argv[index] : void 0;
+}
+
+//#endregion
+//#region ../core/src/parser/arg-parser.ts
+/**
+* Parse CLI arguments for a command
+*
+* @param argv - Command line arguments
+* @param command - The command to parse for
+* @param options - Parse options
+* @returns Parse result
+*/
+function parseArgs(argv, command, options = {}) {
+	const subCommandNameSet = listSubCommandNamesWithAliases(command);
+	const subCommandNames = [...subCommandNameSet];
+	const hasSubCommands = subCommandNames.length > 0;
+	if (hasSubCommands && argv.length > 0) if (options.globalExtracted) {
+		const scanResult = scanForSubcommand(argv, subCommandNames, options.globalExtracted);
+		if (scanResult.subCommandIndex >= 0) {
+			const rawGlobalArgs = parseGlobalArgs(scanResult.globalTokensBefore, options.globalExtracted);
+			return {
+				helpRequested: false,
+				helpAllRequested: false,
+				versionRequested: false,
+				subCommand: argv[scanResult.subCommandIndex],
+				remainingArgs: scanResult.tokensAfterSubcommand,
+				rawArgs: {},
+				positionals: [],
+				rest: [],
+				unknownFlags: scanResult.suppressedTokens,
+				unknownGlobalFlags: scanResult.suppressedTokens,
+				rawGlobalArgs
+			};
+		}
+	} else {
+		const firstArg = argv[0];
+		if (firstArg && !firstArg.startsWith("-") && subCommandNameSet.has(firstArg)) return {
+			helpRequested: false,
+			helpAllRequested: false,
+			versionRequested: false,
+			subCommand: firstArg,
+			remainingArgs: argv.slice(1),
+			rawArgs: {},
+			positionals: [],
+			rest: [],
+			unknownFlags: []
+		};
+	}
+	let extracted;
+	if (command.args) {
+		extracted = extractFields(command.args);
+		if (!options.skipValidation) {
+			validateDuplicateFields(extracted);
+			validateCaseVariantCollisions(extracted);
+			validateDuplicateAliases(extracted);
+			validateDuplicateNegations(extracted);
+			validatePositionalConfig(extracted);
+			validateReservedAliases(extracted, hasSubCommands);
+			validateReservedFieldNames(extracted);
+			if (options.globalExtracted) validateCrossSchemaCollisions(options.globalExtracted, extracted);
+		}
+	}
+	let commandArgv = argv;
+	let rawGlobalArgs;
+	let suppressedGlobalFlags = [];
+	if (options.globalExtracted) {
+		const { separated, globalParsed, suppressedTokens } = separateGlobalArgs(argv, options.globalExtracted, extracted);
+		commandArgv = separated;
+		rawGlobalArgs = globalParsed;
+		suppressedGlobalFlags = suppressedTokens;
+	}
+	const ddIdx = argv.indexOf("--");
+	const flagScanArgv = ddIdx >= 0 ? argv.slice(0, ddIdx) : argv;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && getAllAliases(f).includes("H")) ?? false;
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && getAllAliases(f).includes("h")) ?? false;
+	const helpAllRequested = flagScanArgv.includes("--help-all") || !hasUserDefinedH && flagScanArgv.includes("-H");
+	const helpRequested = !helpAllRequested && (flagScanArgv.includes("--help") || !hasUserDefinedh && flagScanArgv.includes("-h"));
+	const versionRequested = flagScanArgv.includes("--version");
+	if (helpRequested || helpAllRequested || versionRequested) return {
+		helpRequested,
+		helpAllRequested,
+		versionRequested,
+		subCommand: void 0,
+		remainingArgs: [],
+		rawArgs: {},
+		positionals: [],
+		rest: [],
+		unknownFlags: [],
+		unknownGlobalFlags: suppressedGlobalFlags,
+		rawGlobalArgs
+	};
+	if (!extracted) {
+		const ddIdx = commandArgv.indexOf("--");
+		return {
+			helpRequested: false,
+			helpAllRequested: false,
+			versionRequested: false,
+			subCommand: void 0,
+			remainingArgs: [],
+			rawArgs: {},
+			positionals: ddIdx >= 0 ? commandArgv.slice(0, ddIdx) : commandArgv,
+			rest: ddIdx >= 0 ? commandArgv.slice(ddIdx + 1) : [],
+			unknownFlags: [],
+			unknownGlobalFlags: suppressedGlobalFlags,
+			rawGlobalArgs
+		};
+	}
+	const parserOptions = buildParserOptions(extracted);
+	const parsed = parseArgv(commandArgv, parserOptions);
+	const rawArgs = mergeWithPositionals(parsed, extracted);
+	const envFallbackFields = /* @__PURE__ */ new Set();
+	for (const field of extracted.fields) if (field.env && rawArgs[field.name] === void 0) {
+		const envNames = Array.isArray(field.env) ? field.env : [field.env];
+		for (const envName of envNames) {
+			const envValue = process.env[envName];
+			if (envValue !== void 0) {
+				rawArgs[field.name] = envValue;
+				envFallbackFields.add(field.name);
+				break;
+			}
+		}
+	}
+	const knownFlags = new Set(extracted.fields.map((f) => f.name));
+	const knownCliNames = new Set(extracted.fields.map((f) => f.cliName));
+	const knownAliases = /* @__PURE__ */ new Set();
+	for (const f of extracted.fields) for (const alias of getAllAliases(f)) knownAliases.add(alias);
+	if (options.globalExtracted) for (const f of options.globalExtracted.fields) {
+		knownFlags.add(f.name);
+		knownCliNames.add(f.cliName);
+		for (const alias of getAllAliases(f)) knownAliases.add(alias);
+	}
+	const unknownFlags = [];
+	for (const key of Object.keys(parsed.options)) if (!knownFlags.has(key) && !knownCliNames.has(key) && !knownAliases.has(key)) unknownFlags.push(key);
+	return {
+		helpRequested: false,
+		helpAllRequested: false,
+		versionRequested: false,
+		subCommand: void 0,
+		remainingArgs: [],
+		rawArgs,
+		positionals: parsed.positionals,
+		rest: parsed.rest,
+		unknownFlags,
+		unknownGlobalFlags: suppressedGlobalFlags,
+		extractedFields: extracted,
+		rawGlobalArgs,
+		envFallbackFields
+	};
+}
+/**
+* Parse global args from a list of tokens (e.g., tokens before the subcommand).
+* Env fallbacks are applied later in the runner on the accumulated global args.
+*/
+function parseGlobalArgs(tokens, globalExtracted) {
+	if (tokens.length === 0) return {};
+	return mergeWithPositionals(parseArgv(tokens, buildParserOptions(globalExtracted)), globalExtracted);
+}
+/**
+* Separate global flags from command-local args in argv.
+* Global flags mixed with command args (e.g., `build --verbose --output dist`)
+* are extracted and returned separately.
+* When a flag is defined in both global and local schemas, the local definition
+* takes precedence (the flag stays in the command tokens).
+*
+* Note: Combined short flags (e.g., `-vq`) are not decomposed here; only
+* single-character short options are recognized as global. The underlying
+* `parseArgv` handles combined shorts for command-local parsing.
+*/
+function separateGlobalArgs(argv, globalExtracted, localExtracted) {
+	const lookup = buildGlobalFlagLookup(globalExtracted);
+	const localFieldNames = new Set(localExtracted?.fields.map((f) => f.name) ?? []);
+	const localCliNames = new Set(localExtracted?.fields.map((f) => f.cliName) ?? []);
+	const localParserOptions = localExtracted ? buildParserOptions(localExtracted) : void 0;
+	const localAliasMapKeys = new Set(localParserOptions?.aliasMap?.keys() ?? []);
+	const localNegationMapKeys = new Set(localParserOptions?.negationMap?.keys() ?? []);
+	const localDefaultNegationKeys = /* @__PURE__ */ new Set();
+	for (const field of localExtracted?.fields ?? []) {
+		if (field.type !== "boolean" || field.negation !== true) continue;
+		for (const name of [field.cliName, ...getAllAliases(field)]) {
+			const kebab = `no-${name}`;
+			localDefaultNegationKeys.add(kebab);
+			localDefaultNegationKeys.add(toCamelCase(kebab));
+		}
+	}
+	const globalTokens = [];
+	const commandTokens = [];
+	const suppressedTokens = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--") {
+			commandTokens.push(...argv.slice(i));
+			break;
+		}
+		if (arg.startsWith("--")) {
+			const { resolvedName, withoutDashes, isNegated, isGlobal, isSuppressedNegation } = resolveGlobalLongOption(arg, lookup);
+			const flagName = resolvedName;
+			const isLocalCollision = localFieldNames.has(withoutDashes) || localFieldNames.has(flagName) || localCliNames.has(withoutDashes) || localCliNames.has(flagName) || localAliasMapKeys.has(withoutDashes) || localAliasMapKeys.has(flagName) || localNegationMapKeys.has(withoutDashes) || localNegationMapKeys.has(flagName) || localDefaultNegationKeys.has(withoutDashes);
+			if (isGlobal && !isLocalCollision) {
+				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokens) - 1;
+				continue;
+			}
+			if (isSuppressedNegation && !isLocalCollision) {
+				suppressedTokens.push(withoutDashes);
+				continue;
+			}
+		} else if (arg.startsWith("-") && arg.length > 1) {
+			const withoutDash = arg.includes("=") ? arg.slice(1, arg.indexOf("=")) : arg.slice(1);
+			if (withoutDash.length === 1) {
+				const resolvedName = lookup.aliasMap.get(withoutDash) ?? withoutDash;
+				if ((lookup.aliases.has(withoutDash) || lookup.flagNames.has(resolvedName)) && !localAliasMapKeys.has(withoutDash)) {
+					i += collectGlobalFlag(argv, i, resolvedName, false, lookup.booleanFlags, globalTokens) - 1;
+					continue;
+				}
+			}
+		}
+		commandTokens.push(arg);
+	}
+	return {
+		separated: commandTokens,
+		globalParsed: parseGlobalArgs(globalTokens, globalExtracted),
+		suppressedTokens
+	};
+}
+
+//#endregion
+//#region ../core/src/validator/args-validator.ts
+/**
+* Args validation facade.
+*
+* Routes raw parsed args to the implementation that understands the
+* command's schema: politty's internal validator-free descriptors, or the
+* registered validator adapter for user schemas. Neutral error shapes live
+* in `adapter/types.ts`; the schema-library-specific validation lives in
+* the adapter package (e.g. `@politty/zod`).
+*/
+/**
+* Validate raw arguments against a schema
+*
+* @param rawArgs - Parsed but unvalidated arguments
+* @param schema - Args schema (ZodObject, ZodDiscriminatedUnion, internal descriptor, etc.)
+* @returns Validation result with typed data or errors
+*/
+function validateArgs(rawArgs, schema) {
+	if (isInternalArgsSchema(schema)) return validateInternalArgs(rawArgs, schema);
+	return getValidatorAdapter().validate(rawArgs, schema);
+}
+/**
+* Format validation errors for display
+*/
+function formatValidationErrors(errors) {
+	return errors.map((e) => {
+		return `${e.path.length > 0 ? `${e.path.join(".")}: ` : ""}${e.message}`;
+	}).join("\n");
+}
+
+//#endregion
+//#region ../core/src/validator/error-formatter.ts
+/**
+* Calculate Levenshtein distance between two strings
+*/
+function levenshteinDistance(a, b) {
+	const matrix = [];
+	for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+	for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+	for (let i = 1; i <= b.length; i++) for (let j = 1; j <= a.length; j++) if (b.charAt(i - 1) === a.charAt(j - 1)) matrix[i][j] = matrix[i - 1][j - 1];
+	else matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+	return matrix[b.length][a.length];
+}
+/**
+* Find similar strings from a list
+*/
+function findSimilar(target, candidates) {
+	const threshold = Math.max(2, Math.floor(target.length / 2));
+	return candidates.map((candidate) => ({
+		candidate,
+		distance: levenshteinDistance(target.toLowerCase(), candidate.toLowerCase())
+	})).filter(({ distance }) => distance <= threshold).sort((a, b) => a.distance - b.distance).map(({ candidate }) => candidate).slice(0, 3);
+}
+/**
+* Format unknown flag warning with suggestions (for strip mode)
+*
+* @param flag - The unknown flag (e.g., "--verbos")
+* @param knownFlags - List of known flag names
+* @returns Formatted warning message with suggestions
+*/
+function formatUnknownFlagWarning(flag, knownFlags) {
+	const similar = findSimilar(flag.replace(/^-{1,2}/, ""), knownFlags);
+	let message = `${styles.warning("Warning: Unknown option:")} ${styles.bold(flag)}`;
+	if (similar.length > 0) {
+		message += `\n\n${styles.info("Did you mean?")}`;
+		for (const suggestion of similar) message += `\n  ${symbols.arrow} ${styles.option(`--${suggestion}`)}`;
+	}
+	return message;
+}
+/**
+* Format runtime error
+*
+* @param error - The error that occurred
+* @param debug - Whether to include stack trace
+* @returns Formatted error message
+*/
+function formatRuntimeError(error, debug) {
+	if (debug && error.stack) return `${styles.error("Error:")} ${error.message}\n\n${styles.dim(error.stack)}`;
+	return `${styles.error("Error:")} ${error.message}`;
+}
+
+//#endregion
+//#region ../core/src/core/effect-runner.ts
+/**
+* Execute all registered effect callbacks for validated args.
+*
+* Effects run sequentially in field-definition order.
+* Only fires for fields that have an `effect` callback defined.
+*
+* @param validatedArgs - The validated (post-Zod) argument values
+* @param extracted - The extracted fields from the schema
+* @param globalArgs - The validated global args (passed to command arg effects)
+*/
+async function runEffects(validatedArgs, extracted, globalArgs) {
+	for (const field of extracted.fields) {
+		if (!field.effect) continue;
+		await field.effect(validatedArgs[field.name], {
+			name: field.name,
+			args: validatedArgs,
+			...globalArgs != null && { globalArgs }
+		});
+	}
+}
+
+//#endregion
+//#region ../core/src/core/runner.ts
+/**
+* Default logger using console
+*/
+const defaultLogger = {
+	log: (message) => console.log(message),
+	error: (message) => console.error(message),
+	warn: (message) => console.warn(message)
+};
+/**
+* Attach a non-enumerable `$source` helper to the final args object so it
+* stays invisible to `Object.keys`/`JSON.stringify`/spread (those only ever
+* see real field values) while still being reachable via property access
+* (including through `createDualCaseProxy`).
+*/
+function attachArgSource(target, sourceMap) {
+	Object.defineProperty(target, "$source", {
+		value: (name) => sourceMap.get(name) ?? sourceMap.get(toCamelCase(name)) ?? sourceMap.get(toKebabCase(name)) ?? "default",
+		enumerable: false
+	});
+}
+/**
+* Run a command with the given arguments (programmatic/test usage)
+*
+* This function parses arguments, validates them, routes to subcommands,
+* and executes the command. It does NOT call process.exit.
+*
+* @param command - The command to run
+* @param argv - Command line arguments to parse
+* @param options - Run options
+* @returns The result of command execution
+*
+* @example
+* ```ts
+* import { defineCommand, runCommand } from "politty";
+*
+* const command = defineCommand({
+*   name: "my-cli",
+*   args: z.object({ name: z.string() }),
+*   run: ({ name }) => console.log(`Hello, ${name}!`),
+* });
+*
+* // In tests
+* const result = await runCommand(command, ["--name", "World"]);
+* expect(result.exitCode).toBe(0);
+* ```
+*/
+async function runCommand(command, argv, options = {}) {
+	const globalExtracted = extractAndValidateGlobal(options);
+	const shouldCaptureLogs = options.captureLogs ?? false;
+	const globalCollector = shouldCaptureLogs ? createLogCollector() : null;
+	if (options.setup) {
+		globalCollector?.start();
+		try {
+			await options.setup({});
+		} catch (e) {
+			const error = e instanceof Error ? e : new Error(String(e));
+			if (options.cleanup) try {
+				await options.cleanup({ error });
+			} catch {}
+			globalCollector?.stop();
+			return {
+				success: false,
+				error,
+				exitCode: 1,
+				logs: globalCollector?.getLogs() ?? emptyLogs()
+			};
+		}
+		globalCollector?.stop();
+	}
+	const result = await runCommandInternal(command, argv, {
+		...options,
+		handleSignals: false,
+		_globalExtracted: globalExtracted,
+		_globalCleanup: options.cleanup,
+		_existingLogs: globalCollector?.getLogs()
+	});
+	if (options.cleanup) {
+		const cleanupCollector = shouldCaptureLogs ? createLogCollector() : null;
+		cleanupCollector?.start();
+		const cleanupCtx = { error: !result.success ? result.error : void 0 };
+		try {
+			await options.cleanup(cleanupCtx);
+		} catch (e) {
+			if (result.success) {
+				const error = e instanceof Error ? e : new Error(String(e));
+				cleanupCollector?.stop();
+				return {
+					success: false,
+					error,
+					exitCode: 1,
+					logs: mergeLogs(result.logs, cleanupCollector?.getLogs() ?? emptyLogs())
+				};
+			}
+		}
+		cleanupCollector?.stop();
+		const cleanupLogs = cleanupCollector?.getLogs() ?? emptyLogs();
+		if (cleanupLogs.entries.length > 0) return {
+			...result,
+			logs: mergeLogs(result.logs, cleanupLogs)
+		};
+	}
+	return result;
+}
+/**
+* Hidden internal subcommands (e.g. `__refresh-completion`) are spawned
+* by background hooks and must not run user-provided
+* `setup`/`cleanup`/`prompt` or required `globalArgs`. Those exist for
+* the foreground CLI run; replaying them in a detached child causes
+* duplicate side effects, stuck prompts, and validation failures the
+* user never opted into.
+*
+* We treat any registered subcommand whose name starts with `__` as
+* internal. We use `findFirstPositional` (schema-aware) instead of the
+* naive "first non-flag token" so an option *value* like
+* `--name __refresh-completion` doesn't trip the bypass — that would
+* silently skip lifecycle hooks for ordinary invocations.
+*/
+function isInternalSubcommandInvocation(command, argv, globalExtracted) {
+	const firstPositional = findFirstPositional(argv, globalExtracted);
+	if (!firstPositional || !firstPositional.startsWith("__")) return false;
+	return Object.hasOwn(command.subCommands ?? {}, firstPositional);
+}
+/**
+* Run a CLI command as the main entry point
+*
+* This function:
+* - Uses process.argv for arguments
+* - Handles SIGINT/SIGTERM signals
+* - Calls process.exit with the appropriate exit code
+* - Invokes `command.runMainHook` once before parsing if set, so plug-ins
+*   like `withCompletionCommand` can fire detached background work
+* - Bypasses user `setup`/`cleanup`/`prompt` and required `globalArgs`
+*   for registered hidden subcommands whose name starts with `__`
+*   (e.g. `__refresh-completion`)
+*
+* @param command - The command to run
+* @param options - Main options (version, debug)
+*
+* @example
+* ```ts
+* import { defineCommand, runMain } from "politty";
+*
+* const command = defineCommand({
+*   name: "my-cli",
+*   run: () => console.log("Hello!"),
+* });
+*
+* runMain(command, { version: "1.0.0" });
+* ```
+*/
+async function runMain(command, options = {}) {
+	if (options.compileCache !== false) enableCompileCache(typeof options.compileCache === "string" ? { cacheDir: options.compileCache } : { programName: command.name });
+	if (command.runMainHook) try {
+		command.runMainHook(process.argv.slice(2));
+	} catch {}
+	const argv = process.argv.slice(2);
+	let globalExtractedForBypass;
+	if (options.globalArgs) try {
+		globalExtractedForBypass = extractFields(options.globalArgs);
+	} catch {}
+	let effectiveOptions = options;
+	if (isInternalSubcommandInvocation(command, argv, globalExtractedForBypass)) {
+		const { setup: _s, cleanup: _c, prompt: _p, globalArgs: _g, ...rest } = options;
+		effectiveOptions = rest;
+	}
+	const globalExtracted = extractAndValidateGlobal(effectiveOptions);
+	if (effectiveOptions.onUnknownSubcommand && !command.run && !isInternalSubcommandInvocation(command, argv, globalExtractedForBypass)) {
+		const knownSubCommands = listSubCommandNamesWithAliases(command);
+		if (knownSubCommands.size > 0) {
+			const positionalIndex = findFirstPositionalIndex(argv, globalExtracted, { stopOnSuppressedNegation: globalExtracted?.unknownKeysMode !== "passthrough" });
+			const name = positionalIndex >= 0 ? argv[positionalIndex] : void 0;
+			if (name && !knownSubCommands.has(name)) {
+				const forwardArgs = argv.slice(positionalIndex + 1);
+				const exitCode = await effectiveOptions.onUnknownSubcommand({
+					commandPath: [],
+					name,
+					args: forwardArgs,
+					precedingArgs: argv.slice(0, positionalIndex)
+				});
+				if (typeof exitCode === "number") {
+					await flushStandardStreams();
+					return process.exit(exitCode);
+				}
+			}
+		}
+	}
+	if (effectiveOptions.setup) try {
+		await effectiveOptions.setup({});
+	} catch (e) {
+		const error = e instanceof Error ? e : new Error(String(e));
+		if (effectiveOptions.cleanup) try {
+			await effectiveOptions.cleanup({ error });
+		} catch {}
+		process.exit(1);
+	}
+	const result = await runCommandInternal(command, argv, {
+		debug: effectiveOptions.debug,
+		captureLogs: effectiveOptions.captureLogs,
+		skipValidation: effectiveOptions.skipValidation,
+		handleSignals: true,
+		logger: effectiveOptions.logger,
+		globalArgs: effectiveOptions.globalArgs,
+		prompt: effectiveOptions.prompt,
+		onUnknownSubcommand: effectiveOptions.onUnknownSubcommand,
+		_globalExtracted: globalExtracted,
+		_globalCleanup: effectiveOptions.cleanup,
+		_context: {
+			commandPath: [],
+			rootName: command.name,
+			rootVersion: effectiveOptions.version,
+			globalExtracted
+		}
+	});
+	if ((effectiveOptions.displayErrors ?? true) && !result.success && result.error) (effectiveOptions.logger ?? defaultLogger).error(formatRuntimeError(result.error, effectiveOptions.debug ?? false));
+	if (effectiveOptions.cleanup) {
+		const cleanupCtx = { error: !result.success ? result.error : void 0 };
+		try {
+			await effectiveOptions.cleanup(cleanupCtx);
+		} catch {}
+	}
+	await flushStandardStreams();
+	process.exit(result.exitCode);
+}
+/**
+* Flush stdout/stderr before exit to prevent truncated output when piped
+* (pipe writes are buffered asynchronously, so exiting early loses data).
+*
+* We await a zero-byte write's callback rather than a `drain` event: `drain`
+* only fires after a `write()` returned `false` (backpressure), so buffered
+* writes that never tripped it would hang. The write callback is ordered after
+* all pending writes, so it resolves once the buffer is flushed.
+*/
+async function flushStandardStreams() {
+	await Promise.all([process.stdout, process.stderr].map((stream) => stream.writableLength > 0 ? new Promise((resolve) => stream.write("", () => resolve())) : Promise.resolve()));
+}
+/**
+* Internal implementation of command running
+*/
+async function runCommandInternal(command, argv, options = {}) {
+	const logger = options.logger ?? defaultLogger;
+	const context = options._context ?? {
+		commandPath: [],
+		rootName: command.name,
+		globalExtracted: options._globalExtracted
+	};
+	const collector = options.captureLogs ?? false ? createLogCollector() : null;
+	collector?.start();
+	const getCurrentLogs = () => {
+		return mergeLogs(options._existingLogs ?? emptyLogs(), collector?.getLogs() ?? emptyLogs());
+	};
+	try {
+		const parseResult = parseArgs(argv, command, {
+			skipValidation: options.skipValidation,
+			globalExtracted: options._globalExtracted
+		});
+		const accumulatedGlobalArgs = {
+			...options._parsedGlobalArgs,
+			...parseResult.rawGlobalArgs
+		};
+		const nestedCommandPath = context.commandPath ?? [];
+		if (options.onUnknownSubcommand && !command.run && nestedCommandPath.length > 0) {
+			const knownSubCommands = listSubCommandNamesWithAliases(command);
+			if (knownSubCommands.size > 0) {
+				const positionalIndex = findFirstPositionalIndex(argv, options._globalExtracted, { stopOnSuppressedNegation: options._globalExtracted?.unknownKeysMode !== "passthrough" });
+				const name = positionalIndex >= 0 ? argv[positionalIndex] : void 0;
+				if (name && !knownSubCommands.has(name)) {
+					const forwardArgs = argv.slice(positionalIndex + 1);
+					const exitCode = await options.onUnknownSubcommand({
+						commandPath: nestedCommandPath,
+						name,
+						args: forwardArgs,
+						precedingArgs: [...options._precedingArgs ?? [], ...argv.slice(0, positionalIndex)]
+					});
+					if (typeof exitCode === "number") {
+						collector?.stop();
+						if (options.handleSignals) {
+							if (options._globalCleanup) try {
+								await options._globalCleanup({ error: void 0 });
+							} catch {}
+							await flushStandardStreams();
+							process.exit(exitCode);
+						}
+						return exitCode === 0 ? {
+							success: true,
+							result: void 0,
+							exitCode: 0,
+							logs: getCurrentLogs()
+						} : {
+							success: false,
+							error: /* @__PURE__ */ new Error(`Plugin "${[...nestedCommandPath, name].join(" ")}" exited with code ${exitCode}`),
+							exitCode,
+							logs: getCurrentLogs()
+						};
+					}
+				}
+			}
+		}
+		if (parseResult.helpRequested || parseResult.helpAllRequested) {
+			let hasUnknownSubcommand = false;
+			const subCmdNames = listSubCommands(command);
+			const allSubCmdNameSet = listSubCommandNamesWithAliases(command);
+			if (subCmdNames.length > 0) {
+				const potentialSubCmd = findFirstPositional(argv, context.globalExtracted);
+				if (potentialSubCmd && !allSubCmdNameSet.has(potentialSubCmd)) hasUnknownSubcommand = true;
+			}
+			const help = generateHelp(command, {
+				showSubcommands: options.showSubcommands ?? true,
+				showSubcommandOptions: parseResult.helpAllRequested || options.showSubcommandOptions,
+				context
+			});
+			logger.log(help);
+			collector?.stop();
+			if (hasUnknownSubcommand) {
+				const unknownCmd = findFirstPositional(argv, context.globalExtracted) ?? "";
+				const similar = findSimilar(unknownCmd, [...allSubCmdNameSet]);
+				const suggestion = similar.length > 0 ? ` Did you mean: ${similar.join(", ")}?` : "";
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error(`Unknown subcommand: ${unknownCmd}${suggestion ? `.${suggestion}` : ""}`),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			}
+			return {
+				success: true,
+				result: void 0,
+				exitCode: 0,
+				logs: getCurrentLogs()
+			};
+		}
+		if (parseResult.unknownGlobalFlags && parseResult.unknownGlobalFlags.length > 0) {
+			const globalMode = context.globalExtracted?.unknownKeysMode ?? "strip";
+			if (globalMode === "strict") {
+				collector?.stop();
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error(`Unknown flags: ${parseResult.unknownGlobalFlags.join(", ")}`),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			}
+			if (globalMode === "strip") {
+				const knownGlobalFlags = context.globalExtracted?.fields.map((f) => f.name) ?? [];
+				for (const flag of parseResult.unknownGlobalFlags) logger.error(formatUnknownFlagWarning(flag, knownGlobalFlags));
+			}
+		}
+		if (parseResult.versionRequested) {
+			const version = context.rootVersion;
+			if (version) logger.log(version);
+			collector?.stop();
+			return {
+				success: true,
+				result: void 0,
+				exitCode: 0,
+				logs: getCurrentLogs()
+			};
+		}
+		if (parseResult.subCommand) {
+			const resolved = await resolveSubcommandWithAlias(command, parseResult.subCommand);
+			if (resolved) {
+				const subContext = {
+					commandPath: [...context.commandPath ?? [], parseResult.subCommand],
+					rootName: context.rootName,
+					rootVersion: context.rootVersion,
+					globalExtracted: context.globalExtracted,
+					aliasFor: resolved.aliasFor
+				};
+				collector?.stop();
+				const suppressedNames = new Set(options._globalExtracted?.unknownKeysMode === "passthrough" ? [] : parseResult.unknownGlobalFlags ?? []);
+				const isSuppressedFlag = (token) => {
+					return token.startsWith("--") && suppressedNames.has(getLongOptionName(token));
+				};
+				const levelPrecedingArgs = argv.slice(0, argv.length - parseResult.remainingArgs.length - 1).filter((token) => !isSuppressedFlag(token));
+				return runCommandInternal(resolved.command, parseResult.remainingArgs, {
+					...options,
+					_context: subContext,
+					_existingLogs: getCurrentLogs(),
+					_parsedGlobalArgs: accumulatedGlobalArgs,
+					_precedingArgs: [...options._precedingArgs ?? [], ...levelPrecedingArgs]
+				});
+			}
+		}
+		const positionalFields = parseResult.extractedFields?.fields.filter((f) => f.positional) ?? [];
+		const hasArrayPositional = positionalFields.some((f) => f.type === "array");
+		const allPositionals = [...parseResult.positionals, ...parseResult.rest];
+		const extraPositionals = hasArrayPositional ? [] : allPositionals.slice(positionalFields.length);
+		const unconsumedRegulars = hasArrayPositional ? [] : parseResult.positionals.slice(positionalFields.length);
+		if (listSubCommands(command).length > 0 && !parseResult.subCommand && !command.run && extraPositionals.length === 0) {
+			const help = generateHelp(command, {
+				showSubcommands: options.showSubcommands ?? true,
+				context
+			});
+			logger.log(help);
+			collector?.stop();
+			return {
+				success: true,
+				result: void 0,
+				exitCode: 0,
+				logs: getCurrentLogs()
+			};
+		}
+		if (parseResult.unknownFlags.length > 0) {
+			const unknownKeysMode = parseResult.extractedFields?.unknownKeysMode ?? "strip";
+			const knownFlags = parseResult.extractedFields?.fields.map((f) => f.name) ?? [];
+			if (unknownKeysMode === "strict") {
+				collector?.stop();
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error(`Unknown flags: ${parseResult.unknownFlags.join(", ")}`),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			} else if (unknownKeysMode === "strip") for (const flag of parseResult.unknownFlags) logger.error(formatUnknownFlagWarning(flag, knownFlags));
+		}
+		if (extraPositionals.length > 0) {
+			const subCmdNames = listSubCommandNamesWithAliases(command);
+			if (subCmdNames.size > 0) {
+				const unknownCmd = unconsumedRegulars.find((t) => !t.startsWith("-") && !subCmdNames.has(t));
+				if (unknownCmd) {
+					const similar = findSimilar(unknownCmd, [...subCmdNames]);
+					const suggestion = similar.length > 0 ? ` Did you mean: ${similar.join(", ")}?` : "";
+					collector?.stop();
+					return {
+						success: false,
+						error: /* @__PURE__ */ new Error(`Unknown subcommand: ${unknownCmd}${suggestion ? `.${suggestion}` : ""}`),
+						exitCode: 1,
+						logs: getCurrentLogs()
+					};
+				}
+			}
+			const unknownKeysMode = parseResult.extractedFields?.unknownKeysMode ?? "strip";
+			if (unknownKeysMode === "strict") {
+				collector?.stop();
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error(`Unexpected positional argument${extraPositionals.length > 1 ? "s" : ""}: ${extraPositionals.join(", ")}`),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			} else if (unknownKeysMode === "strip") for (const positional of extraPositionals) (logger.warn ?? logger.error)(`Warning: Unexpected positional argument: ${positional}`);
+		}
+		let validatedGlobalArgs = {};
+		const isCompletionInvocation = command.name === "__complete";
+		const cliProvidedGlobalFields = new Set(Object.keys(accumulatedGlobalArgs));
+		const envFallbackGlobalFields = /* @__PURE__ */ new Set();
+		if (options.globalArgs && options._globalExtracted && !isCompletionInvocation) {
+			for (const field of options._globalExtracted.fields) if (field.env && accumulatedGlobalArgs[field.name] === void 0) {
+				const envNames = Array.isArray(field.env) ? field.env : [field.env];
+				for (const envName of envNames) {
+					const envValue = process.env[envName];
+					if (envValue !== void 0) {
+						accumulatedGlobalArgs[field.name] = envValue;
+						envFallbackGlobalFields.add(field.name);
+						break;
+					}
+				}
+			}
+			if (options.prompt) {
+				const resolved = await options.prompt(accumulatedGlobalArgs, options._globalExtracted);
+				for (const [key, value] of Object.entries(resolved)) if (value !== void 0) accumulatedGlobalArgs[key] = value;
+			}
+			const globalValidation = validateArgs(accumulatedGlobalArgs, options.globalArgs);
+			if (!globalValidation.success) {
+				collector?.stop();
+				return {
+					success: false,
+					error: new Error(formatValidationErrors(globalValidation.errors)),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			}
+			validatedGlobalArgs = globalValidation.data;
+		}
+		if (!command.args) {
+			const globalSourceMap = /* @__PURE__ */ new Map();
+			for (const name of cliProvidedGlobalFields) globalSourceMap.set(name, "cli");
+			for (const name of envFallbackGlobalFields) globalSourceMap.set(name, "env");
+			attachArgSource(validatedGlobalArgs, globalSourceMap);
+			const proxiedGlobalArgs = createDualCaseProxy(validatedGlobalArgs);
+			if (options._globalExtracted && !isCompletionInvocation) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
+			collector?.stop();
+			return await executeLifecycle(command, proxiedGlobalArgs, {
+				handleSignals: options.handleSignals,
+				captureLogs: options.captureLogs,
+				existingLogs: getCurrentLogs(),
+				globalCleanup: options._globalCleanup
+			});
+		}
+		let argsToValidate = parseResult.rawArgs;
+		const promptResolvedFields = /* @__PURE__ */ new Set();
+		if (options.prompt && parseResult.extractedFields) {
+			const resolved = await options.prompt(argsToValidate, parseResult.extractedFields);
+			const nextArgsToValidate = { ...argsToValidate };
+			for (const [key, value] of Object.entries(resolved)) if (value !== void 0) {
+				nextArgsToValidate[key] = value;
+				promptResolvedFields.add(key);
+			}
+			argsToValidate = nextArgsToValidate;
+		}
+		const globalPrefilledFields = /* @__PURE__ */ new Set();
+		if (parseResult.extractedFields) {
+			for (const field of parseResult.extractedFields.fields) if (!(Object.hasOwn(parseResult.rawArgs, field.name) || promptResolvedFields.has(field.name)) && cliProvidedGlobalFields.has(field.name) && Object.hasOwn(validatedGlobalArgs, field.name)) {
+				argsToValidate = {
+					...argsToValidate,
+					[field.name]: validatedGlobalArgs[field.name]
+				};
+				globalPrefilledFields.add(field.name);
+			}
+		}
+		const validationResult = validateArgs(argsToValidate, command.args);
+		if (!validationResult.success) {
+			collector?.stop();
+			return {
+				success: false,
+				error: new Error(formatValidationErrors(validationResult.errors)),
+				exitCode: 1,
+				logs: getCurrentLogs()
+			};
+		}
+		const proxiedCommandArgs = createDualCaseProxy(validationResult.data);
+		const proxiedGlobalArgs = createDualCaseProxy(validatedGlobalArgs);
+		if (options._globalExtracted && !isCompletionInvocation) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
+		if (parseResult.extractedFields && !isCompletionInvocation) await runEffects(proxiedCommandArgs, parseResult.extractedFields, proxiedGlobalArgs);
+		const mergedPlainArgs = {
+			...proxiedGlobalArgs,
+			...proxiedCommandArgs
+		};
+		const argSourceMap = /* @__PURE__ */ new Map();
+		for (const name of cliProvidedGlobalFields) argSourceMap.set(name, "cli");
+		for (const name of envFallbackGlobalFields) argSourceMap.set(name, "env");
+		const localEnvFallbackFields = parseResult.envFallbackFields ?? /* @__PURE__ */ new Set();
+		for (const field of parseResult.extractedFields?.fields ?? []) {
+			if (globalPrefilledFields.has(field.name)) {
+				argSourceMap.set(field.name, "cli");
+				continue;
+			}
+			const localHasCliOrEnvValue = Object.hasOwn(parseResult.rawArgs, field.name) || localEnvFallbackFields.has(field.name);
+			argSourceMap.set(field.name, localHasCliOrEnvValue ? localEnvFallbackFields.has(field.name) ? "env" : "cli" : "default");
+		}
+		attachArgSource(mergedPlainArgs, argSourceMap);
+		const mergedArgs = createDualCaseProxy(mergedPlainArgs);
+		collector?.stop();
+		return await executeLifecycle(command, mergedArgs, {
+			handleSignals: options.handleSignals,
+			captureLogs: options.captureLogs,
+			existingLogs: getCurrentLogs(),
+			globalCleanup: options._globalCleanup
+		});
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		collector?.stop();
+		return {
+			success: false,
+			error: err,
+			exitCode: 1,
+			logs: getCurrentLogs()
+		};
+	}
+}
+/**
+* Extract global fields from options.globalArgs and validate the schema upfront.
+* Rejects positional fields since global options must be flags.
+* Returns undefined when no globalArgs is provided.
+*/
+function extractAndValidateGlobal(options) {
+	if (!options.globalArgs) return void 0;
+	const extracted = extractFields(options.globalArgs);
+	if (!options.skipValidation) {
+		validateDuplicateFields(extracted);
+		validateCaseVariantCollisions(extracted);
+		validateDuplicateAliases(extracted);
+		validateDuplicateNegations(extracted);
+		validateReservedAliases(extracted, true);
+		validateReservedFieldNames(extracted);
+		const positionalNames = extracted.fields.filter((f) => f.positional).map((f) => f.name);
+		if (positionalNames.length > 0) throw new Error(`Global options schema must not contain positional arguments. Found: ${positionalNames.join(", ")}`);
+	}
+	return extracted;
+}
+
+//#endregion
+export { generateHelp as C, createDualCaseProxy as E, ReservedFieldNameError as S, renderMarkdown as T, DuplicateFieldError as _, formatCommandValidationErrors as a, PositionalConfigError as b, validateCrossSchemaCollisions as c, validateDuplicateNegations as d, validatePositionalConfig as f, DuplicateAliasError as g, CaseVariantCollisionError as h, parseArgv as i, validateDuplicateAliases as l, validateReservedFieldNames as m, runMain as n, validateCaseVariantCollisions as o, validateReservedAliases as p, formatValidationErrors as r, validateCommand as s, runCommand as t, validateDuplicateFields as u, DuplicateNegationError as v, renderInline as w, ReservedAliasError as x, FieldTypeConflictError as y };