politty 0.4.14 → 0.4.16

package/dist/{runner-CY5fOsSh.cjs → runner-BcyR6Z8r.cjs}

@@ -1,8 +1,8 @@
-const require_subcommand_router = require('./subcommand-router-C9ONv6Nq.cjs');
-const require_lazy = require('./lazy-AGV9Pkt5.cjs');
+const require_log_collector = require('./log-collector-Cd2_mv87.cjs');
+const require_subcommand_router = require('./subcommand-router-DQy0KZU-.cjs');
 let node_util = require("node:util");
 let string_width = require("string-width");
-string_width = require_subcommand_router.__toESM(string_width);
+string_width = require_log_collector.__toESM(string_width, 1);
 
 //#region src/core/case-proxy.ts
 /**
@@ -19,9 +19,9 @@ function createDualCaseProxy(obj) {
 		get(target, prop, receiver) {
 			if (typeof prop === "string") {
 				if (prop in target) return Reflect.get(target, prop, receiver);
-				const camel = require_lazy.toCamelCase(prop);
+				const camel = require_subcommand_router.toCamelCase(prop);
 				if (camel !== prop && camel in target) return Reflect.get(target, camel, receiver);
-				const kebab = require_lazy.toKebabCase(prop);
+				const kebab = require_subcommand_router.toKebabCase(prop);
 				if (kebab !== prop && kebab in target) return Reflect.get(target, kebab, receiver);
 			}
 			return Reflect.get(target, prop, receiver);
@@ -29,9 +29,9 @@ function createDualCaseProxy(obj) {
 		has(target, prop) {
 			if (typeof prop === "string") {
 				if (prop in target) return true;
-				const camel = require_lazy.toCamelCase(prop);
+				const camel = require_subcommand_router.toCamelCase(prop);
 				if (camel !== prop && camel in target) return true;
-				const kebab = require_lazy.toKebabCase(prop);
+				const kebab = require_subcommand_router.toKebabCase(prop);
 				if (kebab !== prop && kebab in target) return true;
 			}
 			return Reflect.has(target, prop);
@@ -56,7 +56,7 @@ function createDualCaseProxy(obj) {
 async function executeLifecycle(command, args, _options = {}) {
 	let error;
 	let result;
-	const collector = _options.captureLogs ?? false ? require_subcommand_router.createLogCollector() : null;
+	const collector = _options.captureLogs ?? false ? require_log_collector.createLogCollector() : null;
 	collector?.start();
 	const setupContext = { args };
 	const cleanupContext = {
@@ -119,7 +119,7 @@ async function executeLifecycle(command, args, _options = {}) {
 		}
 	}
 	collector?.stop();
-	const logs = require_subcommand_router.mergeLogs(_options.existingLogs ?? require_subcommand_router.emptyLogs(), collector?.getLogs() ?? require_subcommand_router.emptyLogs());
+	const logs = require_log_collector.mergeLogs(_options.existingLogs ?? require_log_collector.emptyLogs(), collector?.getLogs() ?? require_log_collector.emptyLogs());
 	if (error) return {
 		success: false,
 		error,
@@ -220,24 +220,45 @@ const symbols = {
 * Logger for CLI output
 */
 const logger = {
+	/**
+	* Log informational message
+	*/
 	info(message) {
 		console.log(message);
 	},
+	/**
+	* Log success message
+	*/
 	success(message) {
 		console.log(`${symbols.success} ${styles.success(message)}`);
 	},
+	/**
+	* Log warning message
+	*/
 	warn(message) {
 		console.warn(`${symbols.warning} ${styles.warning(message)}`);
 	},
+	/**
+	* Log error message
+	*/
 	error(message) {
 		console.error(`${symbols.error} ${styles.error(message)}`);
 	},
+	/**
+	* Log raw message without prefix
+	*/
 	log(message) {
 		console.log(message);
 	},
+	/**
+	* Log empty line
+	*/
 	newline() {
 		console.log("");
 	},
+	/**
+	* Log debug message with dim color
+	*/
 	debug(message) {
 		console.log(styles.dim(message));
 	}
@@ -593,7 +614,7 @@ function renderUsageLine(command, context) {
 	const name = buildUsageCommandName(command, context);
 	parts.push(styles.commandName(name));
 	if (context?.globalExtracted?.fields.length) parts.push(styles.placeholder("[global options]"));
-	const extracted = require_lazy.getExtractedFields(command);
+	const extracted = require_subcommand_router.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]"));
@@ -613,9 +634,9 @@ function renderOptions(command, descriptions = {}, context) {
 		helpAll: descriptions.helpAll ?? defaultBuiltinDescriptions.helpAll,
 		version: descriptions.version ?? defaultBuiltinDescriptions.version
 	};
-	const extracted = require_lazy.getExtractedFields(command);
-	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_lazy.getAllAliases(f).includes("h")) ?? false;
-	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_lazy.getAllAliases(f).includes("H")) ?? false;
+	const extracted = require_subcommand_router.getExtractedFields(command);
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_subcommand_router.getAllAliases(f).includes("h")) ?? false;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_subcommand_router.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));
@@ -634,10 +655,21 @@ function renderOptions(command, descriptions = {}, context) {
 		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) {
@@ -666,6 +698,8 @@ function renderDiscriminatedUnionOptions(extracted, _command, lines) {
 			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) {
@@ -681,7 +715,9 @@ function renderDiscriminatedUnionOptions(extracted, _command, lines) {
 				if (field.required) desc += ` ${styles.required("(required)")}`;
 				const envInfo = formatEnvInfo(field.env);
 				if (envInfo) desc += ` ${envInfo}`;
-				lines.push(formatOption(`  ${flags}`, desc));
+				lines.push(formatOption(flags, desc, 1));
+				const negationLine = formatNegationLine(field, 1);
+				if (negationLine) lines.push(negationLine);
 			}
 		}
 	}
@@ -705,6 +741,8 @@ function renderUnionOptions(extracted, _command, lines) {
 			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++) {
@@ -722,7 +760,9 @@ function renderUnionOptions(extracted, _command, lines) {
 				if (field.required) desc += ` ${styles.required("(required)")}`;
 				const envInfo = formatEnvInfo(field.env);
 				if (envInfo) desc += ` ${envInfo}`;
-				lines.push(formatOption(`  ${flags}`, desc));
+				lines.push(formatOption(flags, desc, 1));
+				const negationLine = formatNegationLine(field, 1);
+				if (negationLine) lines.push(negationLine);
 			}
 		} else {
 			lines.push("");
@@ -737,16 +777,16 @@ function renderUnionOptions(extracted, _command, lines) {
 * Uses cliName (kebab-case) for display
 */
 function formatFlags(opt) {
-	const parts = [];
+	const aliasParts = [];
 	if (opt.alias) {
-		for (const alias of opt.alias) if (alias.length === 1) parts.push(styles.option(`-${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}>`)}`;
 	}
-	parts.push(longFlag);
+	aliasParts.push(longFlag);
 	if (opt.alias) {
 		for (const alias of opt.alias) if (alias.length > 1) {
 			let longAlias = styles.option(`--${alias}`);
@@ -754,10 +794,12 @@ function formatFlags(opt) {
 				const placeholder = opt.placeholder ?? opt.cliName.toUpperCase();
 				longAlias += ` ${styles.placeholder(`<${placeholder}>`)}`;
 			}
-			parts.push(longAlias);
+			aliasParts.push(longAlias);
 		}
 	}
-	return parts.join(", ");
+	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
@@ -809,14 +851,21 @@ function formatFieldLine(opt, indent = 0, extraDescPadding = 0) {
 * Render global options section
 */
 function renderGlobalOptions(globalExtracted) {
-	return globalExtracted.fields.filter((a) => !a.positional).map((opt) => formatFieldLine(opt)).join("\n");
+	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 = require_lazy.getExtractedFields(command);
+	const extracted = require_subcommand_router.getExtractedFields(command);
 	if (extracted) {
 		const options = extracted.fields.filter((a) => !a.positional);
 		for (const opt of options) {
@@ -826,6 +875,8 @@ function renderSubcommandOptionsCompact(command, indent) {
 			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;
@@ -836,10 +887,12 @@ function renderSubcommandOptionsCompact(command, indent) {
 function renderSubcommandsWithOptions(subCommands, parentPath, baseIndent) {
 	const lines = [];
 	for (const [name, subCmd] of getVisibleSubcommandEntries(subCommands)) {
-		const cmd = require_lazy.resolveSubCommandMeta(subCmd);
+		const cmd = require_subcommand_router.resolveSubCommandMeta(subCmd);
 		const fullPath = parentPath ? `${parentPath} ${name}` : name;
 		const desc = cmd?.description ?? "";
-		lines.push(formatOption(styles.command(fullPath), desc, baseIndent));
+		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);
@@ -870,7 +923,9 @@ function generateHelp(command, options) {
 		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}`);
@@ -884,9 +939,12 @@ function generateHelp(command, options) {
 		} else {
 			const subLines = [];
 			for (const [name, subCmd] of Object.entries(visibleSubCommands)) {
-				const desc = require_lazy.resolveSubCommandMeta(subCmd)?.description ?? "";
+				const cmd = require_subcommand_router.resolveSubCommandMeta(subCmd);
+				const desc = cmd?.description ?? "";
 				const fullName = currentPath ? `${currentPath} ${name}` : name;
-				subLines.push(formatOption(styles.command(fullName), desc));
+				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")}`);
 		}
@@ -966,6 +1024,17 @@ var CaseVariantCollisionError = class extends Error {
 		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";
+	}
+};
 
 //#endregion
 //#region src/validator/command-validator.ts
@@ -993,7 +1062,7 @@ function checkCaseVariantCollisions(extracted, commandPath) {
 	const errors = [];
 	const canonicalMap = /* @__PURE__ */ new Map();
 	for (const field of extracted.fields) {
-		const camel = require_lazy.toCamelCase(field.name);
+		const camel = require_subcommand_router.toCamelCase(field.name);
 		const existing = canonicalMap.get(camel);
 		if (existing && existing !== field.name) errors.push({
 			commandPath,
@@ -1033,12 +1102,12 @@ function checkDuplicateAliases(extracted, commandPath) {
 		seenAliases.set(alias, fieldName);
 	};
 	for (const field of extracted.fields) {
-		const allAliases = require_lazy.getAllAliases(field);
+		const allAliases = require_subcommand_router.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 = require_lazy.toCamelCase(alias);
+				const camelVariant = require_subcommand_router.toCamelCase(alias);
 				if (camelVariant !== alias && !fieldNames.has(camelVariant)) registerAlias(camelVariant, field.name, true);
 			}
 		}
@@ -1046,6 +1115,79 @@ function checkDuplicateAliases(extracted, commandPath) {
 	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 = require_subcommand_router.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 = require_subcommand_router.toCamelCase(field.cliName);
+			if (camelCli !== field.cliName) claim(camelCli, field.name, "CLI name");
+		}
+		for (const alias of require_subcommand_router.getAllAliases(field)) {
+			claim(alias, field.name, "alias");
+			if (alias.length > 1 && alias.includes("-")) {
+				const camelVariant = require_subcommand_router.toCamelCase(alias);
+				if (camelVariant !== alias) claim(camelVariant, field.name, "alias");
+			}
+		}
+		if (field.type === "boolean" && field.negation !== false && typeof field.negation !== "string") {
+			const defaultKebab = `no-${field.cliName}`;
+			claim(defaultKebab, field.name, "default negation");
+			const camelBase = require_subcommand_router.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 = require_subcommand_router.toCamelCase(field.negation);
+			if (camelVariant !== field.negation) register(camelVariant, field.name, true);
+		}
+	}
+	return errors;
+}
+/**
 * Check positional argument configuration
 */
 function checkPositionalConfig(extracted, commandPath) {
@@ -1084,7 +1226,7 @@ function checkReservedAliases(extracted, commandPath) {
 	const errors = [];
 	for (const field of extracted.fields) {
 		if (field.overrideBuiltinAlias === true) continue;
-		for (const alias of require_lazy.getAllAliases(field)) if (alias === "h" || alias === "H") errors.push({
+		for (const alias of require_subcommand_router.getAllAliases(field)) if (alias === "h" || alias === "H") errors.push({
 			commandPath,
 			type: "reserved_alias",
 			message: `Alias "${alias}" is reserved for --${alias === "h" ? "help" : "help-all"}.`,
@@ -1155,11 +1297,24 @@ function validateReservedAliases(extracted, _hasSubCommands) {
 	if (errors.length > 0) {
 		const field = errors[0].field ?? "unknown";
 		const found = extracted.fields.find((f) => f.name === field);
-		const alias = (found ? require_lazy.getAllAliases(found) : []).find((a) => a === "h" || a === "H") ?? "h";
+		const alias = (found ? require_subcommand_router.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 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
@@ -1182,9 +1337,9 @@ function validateCaseVariantCollisions(extracted) {
 */
 function validateCrossSchemaCollisions(extractedA, extractedB) {
 	const canonicalMap = /* @__PURE__ */ new Map();
-	for (const field of extractedA.fields) canonicalMap.set(require_lazy.toCamelCase(field.name), field.name);
+	for (const field of extractedA.fields) canonicalMap.set(require_subcommand_router.toCamelCase(field.name), field.name);
 	for (const field of extractedB.fields) {
-		const camel = require_lazy.toCamelCase(field.name);
+		const camel = require_subcommand_router.toCamelCase(field.name);
 		const existing = canonicalMap.get(camel);
 		if (existing && existing !== field.name) throw new CaseVariantCollisionError(`Global field "${existing}" and command field "${field.name}" are case variants of each other and would collide.`);
 	}
@@ -1197,11 +1352,63 @@ function collectSchemaErrors(extracted, _hasSubCommands, commandPath) {
 		...checkDuplicateFields(extracted, commandPath),
 		...checkCaseVariantCollisions(extracted, commandPath),
 		...checkDuplicateAliases(extracted, commandPath),
+		...checkDuplicateNegations(extracted, commandPath),
 		...checkPositionalConfig(extracted, commandPath),
 		...checkReservedAliases(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 = require_subcommand_router.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,
@@ -1224,9 +1431,10 @@ async function validateCommand(command, options = {}) {
 	const errors = [];
 	const hasSubCommands = command.subCommands ? Object.keys(command.subCommands).length > 0 : false;
 	if (command.args) {
-		const extracted = require_lazy.extractFields(command.args);
+		const extracted = require_subcommand_router.extractFields(command.args);
 		errors.push(...collectSchemaErrors(extracted, hasSubCommands, commandPath));
 	}
+	errors.push(...checkSubCommandAliasConflicts(command, commandPath));
 	if (command.subCommands) for (const [name, subCmd] of Object.entries(command.subCommands)) {
 		const subResult = await validateCommand(await require_subcommand_router.resolveLazyCommand(subCmd), { commandPath: [...commandPath, name] });
 		if (!subResult.valid) errors.push(...subResult.errors);
@@ -1277,7 +1485,7 @@ function formatCommandValidationErrors(errors) {
 * @returns Parsed arguments
 */
 function parseArgv(argv, options = {}) {
-	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set() } = options;
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), customNegatedFields = /* @__PURE__ */ new Set() } = options;
 	const result = {
 		options: {},
 		positionals: [],
@@ -1308,11 +1516,19 @@ function parseArgv(argv, options = {}) {
 		}
 		if (arg.startsWith("--")) {
 			const withoutDashes = arg.slice(2);
+			if (!withoutDashes.includes("=")) {
+				const negatedField = negationMap.get(withoutDashes);
+				if (negatedField && booleanFlags.has(negatedField)) {
+					setOption(negatedField, false);
+					i++;
+					continue;
+				}
+			}
 			if (withoutDashes.startsWith("no-")) {
 				const flagName = withoutDashes.slice(3);
 				if (flagName === flagName.toLowerCase()) {
 					const resolvedName = aliasMap.get(flagName) ?? flagName;
-					if (booleanFlags.has(resolvedName)) {
+					if (booleanFlags.has(resolvedName) && !customNegatedFields.has(resolvedName)) {
 						const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
 						if (!definedNames.has(asIsResolved)) {
 							setOption(flagName, false);
@@ -1325,7 +1541,7 @@ function parseArgv(argv, options = {}) {
 			if (withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2])) {
 				const camelFlagName = withoutDashes[2].toLowerCase() + withoutDashes.slice(3);
 				const resolvedName = aliasMap.get(camelFlagName) ?? camelFlagName;
-				if (booleanFlags.has(resolvedName)) {
+				if (booleanFlags.has(resolvedName) && !customNegatedFields.has(resolvedName)) {
 					const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
 					if (!definedNames.has(asIsResolved)) {
 						setOption(camelFlagName, false);
@@ -1398,26 +1614,40 @@ function buildParserOptions(extracted) {
 	const booleanFlags = /* @__PURE__ */ new Set();
 	const arrayFlags = /* @__PURE__ */ new Set();
 	const definedNames = /* @__PURE__ */ new Set();
+	const negationMap = /* @__PURE__ */ new Map();
+	const customNegatedFields = /* @__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 require_lazy.getAllAliases(field)) {
+		for (const alias of require_subcommand_router.getAllAliases(field)) {
 			aliasMap.set(alias, field.name);
 			if (alias.length > 1 && alias.includes("-")) {
-				const camelAlias = require_lazy.toCamelCase(alias);
+				const camelAlias = require_subcommand_router.toCamelCase(alias);
 				if (camelAlias !== alias && !definedNames.has(camelAlias) && !aliasMap.has(camelAlias)) aliasMap.set(camelAlias, field.name);
 			}
 		}
-		const camelVariant = require_lazy.toCamelCase(field.name);
+		const camelVariant = require_subcommand_router.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" && (typeof field.negation === "string" || field.negation === false)) {
+			customNegatedFields.add(field.name);
+			if (typeof field.negation === "string") {
+				negationMap.set(field.negation, field.name);
+				if (field.negation.includes("-")) {
+					const camelNegation = require_subcommand_router.toCamelCase(field.negation);
+					if (camelNegation !== field.negation) negationMap.set(camelNegation, field.name);
+				}
+			}
+		}
 	}
 	return {
 		aliasMap,
 		booleanFlags,
 		arrayFlags,
-		definedNames
+		definedNames,
+		negationMap,
+		customNegatedFields
 	};
 }
 /**
@@ -1448,31 +1678,61 @@ function mergeWithPositionals(parsed, extracted) {
 * Shared by scanForSubcommand, separateGlobalArgs, and findFirstPositional.
 */
 function buildGlobalFlagLookup(globalExtracted) {
-	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), negationMap = /* @__PURE__ */ new Map(), customNegatedFields = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
 	const shortAliases = /* @__PURE__ */ new Set();
-	for (const field of globalExtracted.fields) for (const alias of require_lazy.getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
+	for (const field of globalExtracted.fields) for (const alias of require_subcommand_router.getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
 	return {
 		aliasMap,
 		booleanFlags,
 		flagNames: new Set(globalExtracted.fields.map((f) => f.name)),
 		cliNames: new Set(globalExtracted.fields.map((f) => f.cliName)),
-		aliases: shortAliases
+		aliases: shortAliases,
+		negationMap,
+		customNegatedFields
 	};
 }
 /**
-* Resolve a long option (--flag, --flag=value, --no-flag) against global flag lookup.
-* Returns the resolved camelCase name and whether it is a known global flag.
+* 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 default `--no-X`
+* form that has been suppressed by a custom `negation` 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 withoutDashes = arg.includes("=") ? arg.slice(2, arg.indexOf("=")) : arg.slice(2);
-	const isNegated = withoutDashes.startsWith("no-");
-	const flagName = isNegated ? withoutDashes.slice(3) : withoutDashes;
+	const customNegated = !arg.includes("=") ? lookup.negationMap.get(withoutDashes) : void 0;
+	if (customNegated) return {
+		resolvedName: customNegated,
+		withoutDashes,
+		isNegated: true,
+		isGlobal: lookup.flagNames.has(customNegated),
+		isSuppressedNegation: false
+	};
+	const kebabNegated = withoutDashes.startsWith("no-");
+	const camelNegated = !kebabNegated && withoutDashes.length > 2 && withoutDashes.startsWith("no") && /[A-Z]/.test(withoutDashes[2]);
+	if (kebabNegated || camelNegated) {
+		const literalResolved = lookup.aliasMap.get(withoutDashes) ?? withoutDashes;
+		if (lookup.flagNames.has(literalResolved) || lookup.cliNames.has(withoutDashes)) return {
+			resolvedName: literalResolved,
+			withoutDashes,
+			isNegated: false,
+			isGlobal: true,
+			isSuppressedNegation: false
+		};
+	}
+	const defaultIsNegated = kebabNegated || camelNegated;
+	const flagName = kebabNegated ? withoutDashes.slice(3) : camelNegated ? withoutDashes[2].toLowerCase() + withoutDashes.slice(3) : withoutDashes;
 	const resolvedName = lookup.aliasMap.get(flagName) ?? flagName;
+	const suppressDefaultNegation = defaultIsNegated && lookup.customNegatedFields.has(resolvedName);
 	return {
 		resolvedName,
 		withoutDashes,
-		isNegated,
-		isGlobal: lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName)
+		isNegated: defaultIsNegated && !suppressDefaultNegation,
+		isGlobal: !suppressDefaultNegation && (lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName)),
+		isSuppressedNegation: suppressDefaultNegation
 	};
 }
 /**
@@ -1520,6 +1780,7 @@ 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];
@@ -1527,14 +1788,20 @@ function scanForSubcommand(argv, subCommandNames, globalExtracted) {
 		if (!arg.startsWith("-") && subCommandNameSet.has(arg)) return {
 			subCommandIndex: i,
 			globalTokensBefore,
-			tokensAfterSubcommand: argv.slice(i + 1)
+			tokensAfterSubcommand: argv.slice(i + 1),
+			suppressedTokens
 		};
 		if (arg.startsWith("--")) {
-			const { resolvedName, isNegated, isGlobal } = resolveGlobalLongOption(arg, lookup);
+			const { resolvedName, isNegated, isGlobal, isSuppressedNegation } = resolveGlobalLongOption(arg, lookup);
 			if (isGlobal) {
 				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokensBefore);
 				continue;
 			}
+			if (isSuppressedNegation) {
+				suppressedTokens.push(arg.includes("=") ? arg.slice(2, arg.indexOf("=")) : arg.slice(2));
+				i++;
+				continue;
+			}
 			break;
 		}
 		if (arg.startsWith("-") && arg.length > 1) {
@@ -1553,7 +1820,8 @@ function scanForSubcommand(argv, subCommandNames, globalExtracted) {
 	return {
 		subCommandIndex: -1,
 		globalTokensBefore,
-		tokensAfterSubcommand: []
+		tokensAfterSubcommand: [],
+		suppressedTokens
 	};
 }
 const BUILTIN_FLAGS = new Set([
@@ -1599,7 +1867,8 @@ function findFirstPositional(argv, globalExtracted) {
 * @returns Parse result
 */
 function parseArgs(argv, command, options = {}) {
-	const subCommandNames = command.subCommands ? Object.keys(command.subCommands) : [];
+	const subCommandNameSet = require_subcommand_router.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);
@@ -1613,13 +1882,13 @@ function parseArgs(argv, command, options = {}) {
 				remainingArgs: scanResult.tokensAfterSubcommand,
 				rawArgs: {},
 				positionals: [],
-				unknownFlags: [],
+				unknownFlags: scanResult.suppressedTokens,
 				rawGlobalArgs
 			};
 		}
 	} else {
 		const firstArg = argv[0];
-		if (firstArg && !firstArg.startsWith("-") && subCommandNames.includes(firstArg)) return {
+		if (firstArg && !firstArg.startsWith("-") && subCommandNameSet.has(firstArg)) return {
 			helpRequested: false,
 			helpAllRequested: false,
 			versionRequested: false,
@@ -1632,18 +1901,19 @@ function parseArgs(argv, command, options = {}) {
 	}
 	let extracted;
 	if (command.args) {
-		extracted = require_lazy.extractFields(command.args);
+		extracted = require_subcommand_router.extractFields(command.args);
 		if (!options.skipValidation) {
 			validateDuplicateFields(extracted);
 			validateCaseVariantCollisions(extracted);
 			validateDuplicateAliases(extracted);
+			validateDuplicateNegations(extracted);
 			validatePositionalConfig(extracted);
 			validateReservedAliases(extracted, hasSubCommands);
 			if (options.globalExtracted) validateCrossSchemaCollisions(options.globalExtracted, extracted);
 		}
 	}
-	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_lazy.getAllAliases(f).includes("H")) ?? false;
-	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_lazy.getAllAliases(f).includes("h")) ?? false;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_subcommand_router.getAllAliases(f).includes("H")) ?? false;
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_subcommand_router.getAllAliases(f).includes("h")) ?? false;
 	const helpAllRequested = argv.includes("--help-all") || !hasUserDefinedH && argv.includes("-H");
 	const helpRequested = !helpAllRequested && (argv.includes("--help") || !hasUserDefinedh && argv.includes("-h"));
 	const versionRequested = argv.includes("--version");
@@ -1691,11 +1961,11 @@ function parseArgs(argv, command, options = {}) {
 	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 require_lazy.getAllAliases(f)) knownAliases.add(alias);
+	for (const f of extracted.fields) for (const alias of require_subcommand_router.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 require_lazy.getAllAliases(f)) knownAliases.add(alias);
+		for (const alias of require_subcommand_router.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);
@@ -1746,7 +2016,7 @@ function separateGlobalArgs(argv, globalExtracted, localExtracted) {
 		}
 		if (arg.startsWith("--")) {
 			const { resolvedName, withoutDashes, isNegated, isGlobal } = resolveGlobalLongOption(arg, lookup);
-			const flagName = isNegated ? withoutDashes.slice(3) : withoutDashes;
+			const flagName = resolvedName;
 			const isLocalCollision = localFieldNames.has(withoutDashes) || localFieldNames.has(flagName) || localCliNames.has(withoutDashes) || localCliNames.has(flagName) || localAliasMapKeys.has(withoutDashes) || localAliasMapKeys.has(flagName);
 			if (isGlobal && !isLocalCollision) {
 				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokens) - 1;
@@ -1887,7 +2157,7 @@ async function runEffects(validatedArgs, extracted, globalArgs) {
 
 //#endregion
 //#region src/core/runner.ts
-var runner_exports = /* @__PURE__ */ require_subcommand_router.__exportAll({
+var runner_exports = /* @__PURE__ */ require_log_collector.__exportAll({
 	runCommand: () => runCommand,
 	runMain: () => runMain
 });
@@ -1927,7 +2197,7 @@ const defaultLogger = {
 async function runCommand(command, argv, options = {}) {
 	const globalExtracted = extractAndValidateGlobal(options);
 	const shouldCaptureLogs = options.captureLogs ?? false;
-	const globalCollector = shouldCaptureLogs ? require_subcommand_router.createLogCollector() : null;
+	const globalCollector = shouldCaptureLogs ? require_log_collector.createLogCollector() : null;
 	if (options.setup) {
 		globalCollector?.start();
 		try {
@@ -1942,7 +2212,7 @@ async function runCommand(command, argv, options = {}) {
 				success: false,
 				error,
 				exitCode: 1,
-				logs: globalCollector?.getLogs() ?? require_subcommand_router.emptyLogs()
+				logs: globalCollector?.getLogs() ?? require_log_collector.emptyLogs()
 			};
 		}
 		globalCollector?.stop();
@@ -1955,7 +2225,7 @@ async function runCommand(command, argv, options = {}) {
 		_existingLogs: globalCollector?.getLogs()
 	});
 	if (options.cleanup) {
-		const cleanupCollector = shouldCaptureLogs ? require_subcommand_router.createLogCollector() : null;
+		const cleanupCollector = shouldCaptureLogs ? require_log_collector.createLogCollector() : null;
 		cleanupCollector?.start();
 		const cleanupCtx = { error: !result.success ? result.error : void 0 };
 		try {
@@ -1968,26 +2238,50 @@ async function runCommand(command, argv, options = {}) {
 					success: false,
 					error,
 					exitCode: 1,
-					logs: require_subcommand_router.mergeLogs(result.logs, cleanupCollector?.getLogs() ?? require_subcommand_router.emptyLogs())
+					logs: require_log_collector.mergeLogs(result.logs, cleanupCollector?.getLogs() ?? require_log_collector.emptyLogs())
 				};
 			}
 		}
 		cleanupCollector?.stop();
-		const cleanupLogs = cleanupCollector?.getLogs() ?? require_subcommand_router.emptyLogs();
+		const cleanupLogs = cleanupCollector?.getLogs() ?? require_log_collector.emptyLogs();
 		if (cleanupLogs.entries.length > 0) return {
 			...result,
-			logs: require_subcommand_router.mergeLogs(result.logs, cleanupLogs)
+			logs: require_log_collector.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 Boolean(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)
@@ -2005,38 +2299,51 @@ async function runCommand(command, argv, options = {}) {
 * ```
 */
 async function runMain(command, options = {}) {
-	const globalExtracted = extractAndValidateGlobal(options);
-	if (options.setup) try {
-		await options.setup({});
+	if (command.runMainHook) try {
+		command.runMainHook(process.argv.slice(2));
+	} catch {}
+	const argv = process.argv.slice(2);
+	let globalExtractedForBypass;
+	if (options.globalArgs) try {
+		globalExtractedForBypass = require_subcommand_router.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.setup) try {
+		await effectiveOptions.setup({});
 	} catch (e) {
 		const error = e instanceof Error ? e : new Error(String(e));
-		if (options.cleanup) try {
-			await options.cleanup({ error });
+		if (effectiveOptions.cleanup) try {
+			await effectiveOptions.cleanup({ error });
 		} catch {}
 		process.exit(1);
 	}
-	const result = await runCommandInternal(command, process.argv.slice(2), {
-		debug: options.debug,
-		captureLogs: options.captureLogs,
-		skipValidation: options.skipValidation,
+	const result = await runCommandInternal(command, argv, {
+		debug: effectiveOptions.debug,
+		captureLogs: effectiveOptions.captureLogs,
+		skipValidation: effectiveOptions.skipValidation,
 		handleSignals: true,
-		logger: options.logger,
-		globalArgs: options.globalArgs,
-		prompt: options.prompt,
+		logger: effectiveOptions.logger,
+		globalArgs: effectiveOptions.globalArgs,
+		prompt: effectiveOptions.prompt,
 		_globalExtracted: globalExtracted,
-		_globalCleanup: options.cleanup,
+		_globalCleanup: effectiveOptions.cleanup,
 		_context: {
 			commandPath: [],
 			rootName: command.name,
-			rootVersion: options.version,
+			rootVersion: effectiveOptions.version,
 			globalExtracted
 		}
 	});
-	if ((options.displayErrors ?? true) && !result.success && result.error) (options.logger ?? defaultLogger).error(formatRuntimeError(result.error, options.debug ?? false));
-	if (options.cleanup) {
+	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 options.cleanup(cleanupCtx);
+			await effectiveOptions.cleanup(cleanupCtx);
 		} catch {}
 	}
 	if (process.stdout.writableLength > 0) await new Promise((resolve) => process.stdout.once("drain", resolve));
@@ -2053,10 +2360,10 @@ async function runCommandInternal(command, argv, options = {}) {
 		rootName: command.name,
 		globalExtracted: options._globalExtracted
 	};
-	const collector = options.captureLogs ?? false ? require_subcommand_router.createLogCollector() : null;
+	const collector = options.captureLogs ?? false ? require_log_collector.createLogCollector() : null;
 	collector?.start();
 	const getCurrentLogs = () => {
-		return require_subcommand_router.mergeLogs(options._existingLogs ?? require_subcommand_router.emptyLogs(), collector?.getLogs() ?? require_subcommand_router.emptyLogs());
+		return require_log_collector.mergeLogs(options._existingLogs ?? require_log_collector.emptyLogs(), collector?.getLogs() ?? require_log_collector.emptyLogs());
 	};
 	try {
 		const parseResult = parseArgs(argv, command, {
@@ -2070,9 +2377,10 @@ async function runCommandInternal(command, argv, options = {}) {
 		if (parseResult.helpRequested || parseResult.helpAllRequested) {
 			let hasUnknownSubcommand = false;
 			const subCmdNames = require_subcommand_router.listSubCommands(command);
+			const allSubCmdNameSet = require_subcommand_router.listSubCommandNamesWithAliases(command);
 			if (subCmdNames.length > 0) {
 				const potentialSubCmd = findFirstPositional(argv, context.globalExtracted);
-				if (potentialSubCmd && !subCmdNames.includes(potentialSubCmd)) hasUnknownSubcommand = true;
+				if (potentialSubCmd && !allSubCmdNameSet.has(potentialSubCmd)) hasUnknownSubcommand = true;
 			}
 			const help = generateHelp(command, {
 				showSubcommands: options.showSubcommands ?? true,
@@ -2083,7 +2391,7 @@ async function runCommandInternal(command, argv, options = {}) {
 			collector?.stop();
 			if (hasUnknownSubcommand) {
 				const unknownCmd = findFirstPositional(argv, context.globalExtracted) ?? "";
-				const similar = findSimilar(unknownCmd, subCmdNames);
+				const similar = findSimilar(unknownCmd, [...allSubCmdNameSet]);
 				const suggestion = similar.length > 0 ? ` Did you mean: ${similar.join(", ")}?` : "";
 				return {
 					success: false,
@@ -2111,16 +2419,33 @@ async function runCommandInternal(command, argv, options = {}) {
 			};
 		}
 		if (parseResult.subCommand) {
-			const subCmd = await require_subcommand_router.resolveSubcommand(command, parseResult.subCommand);
-			if (subCmd) {
+			if (parseResult.unknownFlags.length > 0) {
+				const globalMode = context.globalExtracted?.unknownKeysMode ?? "strip";
+				if (globalMode === "strict") {
+					collector?.stop();
+					return {
+						success: false,
+						error: /* @__PURE__ */ new Error(`Unknown flags: ${parseResult.unknownFlags.join(", ")}`),
+						exitCode: 1,
+						logs: getCurrentLogs()
+					};
+				}
+				if (globalMode === "strip") {
+					const knownGlobalFlags = context.globalExtracted?.fields.map((f) => f.name) ?? [];
+					for (const flag of parseResult.unknownFlags) logger.error(formatUnknownFlagWarning(flag, knownGlobalFlags));
+				}
+			}
+			const resolved = await require_subcommand_router.resolveSubcommandWithAlias(command, parseResult.subCommand);
+			if (resolved) {
 				const subContext = {
 					commandPath: [...context.commandPath ?? [], parseResult.subCommand],
 					rootName: context.rootName,
 					rootVersion: context.rootVersion,
-					globalExtracted: context.globalExtracted
+					globalExtracted: context.globalExtracted,
+					aliasFor: resolved.aliasFor
 				};
 				collector?.stop();
-				return runCommandInternal(subCmd, parseResult.remainingArgs, {
+				return runCommandInternal(resolved.command, parseResult.remainingArgs, {
 					...options,
 					_context: subContext,
 					_existingLogs: getCurrentLogs(),
@@ -2245,11 +2570,12 @@ async function runCommandInternal(command, argv, options = {}) {
 */
 function extractAndValidateGlobal(options) {
 	if (!options.globalArgs) return void 0;
-	const extracted = require_lazy.extractFields(options.globalArgs);
+	const extracted = require_subcommand_router.extractFields(options.globalArgs);
 	if (!options.skipValidation) {
 		validateDuplicateFields(extracted);
 		validateCaseVariantCollisions(extracted);
 		validateDuplicateAliases(extracted);
+		validateDuplicateNegations(extracted);
 		validateReservedAliases(extracted, true);
 		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(", ")}`);
@@ -2276,6 +2602,12 @@ Object.defineProperty(exports, 'DuplicateFieldError', {
     return DuplicateFieldError;
   }
 });
+Object.defineProperty(exports, 'DuplicateNegationError', {
+  enumerable: true,
+  get: function () {
+    return DuplicateNegationError;
+  }
+});
 Object.defineProperty(exports, 'PositionalConfigError', {
   enumerable: true,
   get: function () {
@@ -2408,6 +2740,12 @@ Object.defineProperty(exports, 'validateDuplicateFields', {
     return validateDuplicateFields;
   }
 });
+Object.defineProperty(exports, 'validateDuplicateNegations', {
+  enumerable: true,
+  get: function () {
+    return validateDuplicateNegations;
+  }
+});
 Object.defineProperty(exports, 'validatePositionalConfig', {
   enumerable: true,
   get: function () {
@@ -2420,4 +2758,4 @@ Object.defineProperty(exports, 'validateReservedAliases', {
     return validateReservedAliases;
   }
 });
-//# sourceMappingURL=runner-CY5fOsSh.cjs.map
+//# sourceMappingURL=runner-BcyR6Z8r.cjs.map