politty 0.4.14 → 0.4.16

package/dist/{runner-DSZw1AsW.js → runner-BHeCMEa5.js}

@@ -1,5 +1,5 @@
-import { a as getAllAliases, c as toCamelCase, i as extractFields, l as toKebabCase, o as getExtractedFields, r as resolveSubCommandMeta } from "./lazy-DiMJSDMB.js";
-import { a as emptyLogs, i as createLogCollector, n as resolveLazyCommand, o as mergeLogs, r as resolveSubcommand, t as listSubCommands } from "./subcommand-router--EUt6ftA.js";
+import { a as resolveSubcommandWithAlias, c as resolveSubCommandMeta, d as getExtractedFields, l as extractFields, m as toKebabCase, n as listSubCommands, o as isLazyCommand, p as toCamelCase, r as resolveLazyCommand, t as listSubCommandNamesWithAliases, u as getAllAliases } from "./subcommand-router-XZBWe8HN.js";
+import { n as emptyLogs, r as mergeLogs, t as createLogCollector } from "./log-collector-Cu6MCtAx.js";
 import { styleText } from "node:util";
 import stringWidth from "string-width";
 
@@ -236,24 +236,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));
 	}
@@ -650,10 +671,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) {
@@ -682,6 +714,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) {
@@ -697,7 +731,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);
 			}
 		}
 	}
@@ -721,6 +757,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++) {
@@ -738,7 +776,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("");
@@ -753,16 +793,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}`);
@@ -770,10 +810,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
@@ -825,7 +867,14 @@ 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)
@@ -842,6 +891,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;
@@ -855,7 +906,9 @@ function renderSubcommandsWithOptions(subCommands, parentPath, baseIndent) {
 		const cmd = 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);
@@ -886,7 +939,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}`);
@@ -900,9 +955,12 @@ function generateHelp(command, options) {
 		} else {
 			const subLines = [];
 			for (const [name, subCmd] of Object.entries(visibleSubCommands)) {
-				const desc = resolveSubCommandMeta(subCmd)?.description ?? "";
+				const cmd = 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")}`);
 		}
@@ -982,6 +1040,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
@@ -1062,6 +1131,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 = 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 !== false && typeof field.negation !== "string") {
+			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) {
@@ -1176,6 +1318,19 @@ function validateReservedAliases(extracted, _hasSubCommands) {
 	}
 }
 /**
+* 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
@@ -1213,11 +1368,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 = 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,
@@ -1243,6 +1450,7 @@ async function validateCommand(command, options = {}) {
 		const extracted = 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 resolveLazyCommand(subCmd), { commandPath: [...commandPath, name] });
 		if (!subResult.valid) errors.push(...subResult.errors);
@@ -1293,7 +1501,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: [],
@@ -1324,11 +1532,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);
@@ -1341,7 +1557,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);
@@ -1414,6 +1630,8 @@ 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);
@@ -1428,12 +1646,24 @@ function buildParserOptions(extracted) {
 		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 = toCamelCase(field.negation);
+					if (camelNegation !== field.negation) negationMap.set(camelNegation, field.name);
+				}
+			}
+		}
 	}
 	return {
 		aliasMap,
 		booleanFlags,
 		arrayFlags,
-		definedNames
+		definedNames,
+		negationMap,
+		customNegatedFields
 	};
 }
 /**
@@ -1464,7 +1694,7 @@ 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 getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
 	return {
@@ -1472,23 +1702,53 @@ function buildGlobalFlagLookup(globalExtracted) {
 		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
 	};
 }
 /**
@@ -1536,6 +1796,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];
@@ -1543,14 +1804,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) {
@@ -1569,7 +1836,8 @@ function scanForSubcommand(argv, subCommandNames, globalExtracted) {
 	return {
 		subCommandIndex: -1,
 		globalTokensBefore,
-		tokensAfterSubcommand: []
+		tokensAfterSubcommand: [],
+		suppressedTokens
 	};
 }
 const BUILTIN_FLAGS = new Set([
@@ -1615,7 +1883,8 @@ function findFirstPositional(argv, globalExtracted) {
 * @returns Parse result
 */
 function parseArgs(argv, command, options = {}) {
-	const subCommandNames = command.subCommands ? Object.keys(command.subCommands) : [];
+	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);
@@ -1629,13 +1898,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,
@@ -1653,6 +1922,7 @@ function parseArgs(argv, command, options = {}) {
 			validateDuplicateFields(extracted);
 			validateCaseVariantCollisions(extracted);
 			validateDuplicateAliases(extracted);
+			validateDuplicateNegations(extracted);
 			validatePositionalConfig(extracted);
 			validateReservedAliases(extracted, hasSubCommands);
 			if (options.globalExtracted) validateCrossSchemaCollisions(options.globalExtracted, extracted);
@@ -1762,7 +2032,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;
@@ -1998,12 +2268,36 @@ async function runCommand(command, argv, options = {}) {
 	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)
@@ -2021,38 +2315,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 = 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));
@@ -2086,9 +2393,10 @@ async function runCommandInternal(command, argv, options = {}) {
 		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 && !subCmdNames.includes(potentialSubCmd)) hasUnknownSubcommand = true;
+				if (potentialSubCmd && !allSubCmdNameSet.has(potentialSubCmd)) hasUnknownSubcommand = true;
 			}
 			const help = generateHelp(command, {
 				showSubcommands: options.showSubcommands ?? true,
@@ -2099,7 +2407,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,
@@ -2127,16 +2435,33 @@ async function runCommandInternal(command, argv, options = {}) {
 			};
 		}
 		if (parseResult.subCommand) {
-			const subCmd = await 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 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(),
@@ -2266,6 +2591,7 @@ function extractAndValidateGlobal(options) {
 		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(", ")}`);
@@ -2274,5 +2600,5 @@ function extractAndValidateGlobal(options) {
 }
 
 //#endregion
-export { logger as C, createDualCaseProxy as D, symbols as E, isColorEnabled as S, styles as T, PositionalConfigError as _, parseArgv as a, renderInline as b, validateCommand as c, validateDuplicateFields as d, validatePositionalConfig as f, DuplicateFieldError as g, DuplicateAliasError as h, formatValidationErrors as i, validateCrossSchemaCollisions as l, CaseVariantCollisionError as m, runMain as n, formatCommandValidationErrors as o, validateReservedAliases as p, runner_exports as r, validateCaseVariantCollisions as s, runCommand as t, validateDuplicateAliases as u, ReservedAliasError as v, setColorEnabled as w, renderMarkdown as x, generateHelp as y };
-//# sourceMappingURL=runner-DSZw1AsW.js.map
+export { renderMarkdown as C, styles as D, setColorEnabled as E, symbols as O, renderInline as S, logger as T, DuplicateFieldError as _, parseArgv as a, ReservedAliasError as b, validateCommand as c, validateDuplicateFields as d, validateDuplicateNegations as f, DuplicateAliasError as g, CaseVariantCollisionError as h, formatValidationErrors as i, createDualCaseProxy as k, validateCrossSchemaCollisions as l, validateReservedAliases as m, runMain as n, formatCommandValidationErrors as o, validatePositionalConfig as p, runner_exports as r, validateCaseVariantCollisions as s, runCommand as t, validateDuplicateAliases as u, DuplicateNegationError as v, isColorEnabled as w, generateHelp as x, PositionalConfigError as y };
+//# sourceMappingURL=runner-BHeCMEa5.js.map