politty 0.4.15 → 0.4.16

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

@@ -1,5 +1,5 @@
 const require_log_collector = require('./log-collector-Cd2_mv87.cjs');
-const require_subcommand_router = require('./subcommand-router-CqZX3orq.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_log_collector.__toESM(string_width, 1);
@@ -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));
 	}
@@ -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,7 +851,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)
@@ -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;
@@ -973,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
@@ -1053,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) {
@@ -1167,6 +1302,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
@@ -1204,6 +1352,7 @@ function collectSchemaErrors(extracted, _hasSubCommands, commandPath) {
 		...checkDuplicateFields(extracted, commandPath),
 		...checkCaseVariantCollisions(extracted, commandPath),
 		...checkDuplicateAliases(extracted, commandPath),
+		...checkDuplicateNegations(extracted, commandPath),
 		...checkPositionalConfig(extracted, commandPath),
 		...checkReservedAliases(extracted, commandPath)
 	];
@@ -1336,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: [],
@@ -1367,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);
@@ -1384,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);
@@ -1457,6 +1614,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);
@@ -1471,12 +1630,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 = require_subcommand_router.toCamelCase(field.negation);
+					if (camelNegation !== field.negation) negationMap.set(camelNegation, field.name);
+				}
+			}
+		}
 	}
 	return {
 		aliasMap,
 		booleanFlags,
 		arrayFlags,
-		definedNames
+		definedNames,
+		negationMap,
+		customNegatedFields
 	};
 }
 /**
@@ -1507,7 +1678,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 require_subcommand_router.getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
 	return {
@@ -1515,23 +1686,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
 	};
 }
 /**
@@ -1579,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];
@@ -1586,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) {
@@ -1612,7 +1820,8 @@ function scanForSubcommand(argv, subCommandNames, globalExtracted) {
 	return {
 		subCommandIndex: -1,
 		globalTokensBefore,
-		tokensAfterSubcommand: []
+		tokensAfterSubcommand: [],
+		suppressedTokens
 	};
 }
 const BUILTIN_FLAGS = new Set([
@@ -1673,7 +1882,7 @@ function parseArgs(argv, command, options = {}) {
 				remainingArgs: scanResult.tokensAfterSubcommand,
 				rawArgs: {},
 				positionals: [],
-				unknownFlags: [],
+				unknownFlags: scanResult.suppressedTokens,
 				rawGlobalArgs
 			};
 		}
@@ -1697,6 +1906,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);
@@ -1806,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;
@@ -2042,12 +2252,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)
@@ -2065,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));
@@ -2172,6 +2419,22 @@ async function runCommandInternal(command, argv, options = {}) {
 			};
 		}
 		if (parseResult.subCommand) {
+			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 = {
@@ -2312,6 +2575,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(", ")}`);
@@ -2338,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 () {
@@ -2470,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 () {
@@ -2482,4 +2758,4 @@ Object.defineProperty(exports, 'validateReservedAliases', {
     return validateReservedAliases;
   }
 });
-//# sourceMappingURL=runner-CriXJlm4.cjs.map
+//# sourceMappingURL=runner-BcyR6Z8r.cjs.map