politty 0.4.15 → 0.5.0

package/dist/{runner-CriXJlm4.cjs → runner-CRZ_7Y9i.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_schema_extractor = require('./schema-extractor-SLPgBNgZ.cjs');
 let node_util = require("node:util");
 let string_width = require("string-width");
 string_width = require_log_collector.__toESM(string_width, 1);
@@ -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_subcommand_router.toCamelCase(prop);
+				const camel = require_schema_extractor.toCamelCase(prop);
 				if (camel !== prop && camel in target) return Reflect.get(target, camel, receiver);
-				const kebab = require_subcommand_router.toKebabCase(prop);
+				const kebab = require_schema_extractor.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_subcommand_router.toCamelCase(prop);
+				const camel = require_schema_extractor.toCamelCase(prop);
 				if (camel !== prop && camel in target) return true;
-				const kebab = require_subcommand_router.toKebabCase(prop);
+				const kebab = require_schema_extractor.toKebabCase(prop);
 				if (kebab !== prop && kebab in target) return true;
 			}
 			return Reflect.has(target, prop);
@@ -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_subcommand_router.getExtractedFields(command);
+	const extracted = require_schema_extractor.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_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;
+	const extracted = require_schema_extractor.getExtractedFields(command);
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_schema_extractor.getAllAliases(f).includes("h")) ?? false;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_schema_extractor.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_subcommand_router.getExtractedFields(command);
+	const extracted = require_schema_extractor.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,7 +887,7 @@ function renderSubcommandOptionsCompact(command, indent) {
 function renderSubcommandsWithOptions(subCommands, parentPath, baseIndent) {
 	const lines = [];
 	for (const [name, subCmd] of getVisibleSubcommandEntries(subCommands)) {
-		const cmd = require_subcommand_router.resolveSubCommandMeta(subCmd);
+		const cmd = require_schema_extractor.resolveSubCommandMeta(subCmd);
 		const fullPath = parentPath ? `${parentPath} ${name}` : name;
 		const desc = cmd?.description ?? "";
 		const aliases = cmd?.aliases;
@@ -888,7 +939,7 @@ function generateHelp(command, options) {
 		} else {
 			const subLines = [];
 			for (const [name, subCmd] of Object.entries(visibleSubCommands)) {
-				const cmd = require_subcommand_router.resolveSubCommandMeta(subCmd);
+				const cmd = require_schema_extractor.resolveSubCommandMeta(subCmd);
 				const desc = cmd?.description ?? "";
 				const fullName = currentPath ? `${currentPath} ${name}` : name;
 				const aliases = cmd?.aliases;
@@ -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
@@ -1000,7 +1062,7 @@ function checkCaseVariantCollisions(extracted, commandPath) {
 	const errors = [];
 	const canonicalMap = /* @__PURE__ */ new Map();
 	for (const field of extracted.fields) {
-		const camel = require_subcommand_router.toCamelCase(field.name);
+		const camel = require_schema_extractor.toCamelCase(field.name);
 		const existing = canonicalMap.get(camel);
 		if (existing && existing !== field.name) errors.push({
 			commandPath,
@@ -1040,12 +1102,12 @@ function checkDuplicateAliases(extracted, commandPath) {
 		seenAliases.set(alias, fieldName);
 	};
 	for (const field of extracted.fields) {
-		const allAliases = require_subcommand_router.getAllAliases(field);
+		const allAliases = require_schema_extractor.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_subcommand_router.toCamelCase(alias);
+				const camelVariant = require_schema_extractor.toCamelCase(alias);
 				if (camelVariant !== alias && !fieldNames.has(camelVariant)) registerAlias(camelVariant, field.name, true);
 			}
 		}
@@ -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_schema_extractor.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_schema_extractor.toCamelCase(field.cliName);
+			if (camelCli !== field.cliName) claim(camelCli, field.name, "CLI name");
+		}
+		for (const alias of require_schema_extractor.getAllAliases(field)) {
+			claim(alias, field.name, "alias");
+			if (alias.length > 1 && alias.includes("-")) {
+				const camelVariant = require_schema_extractor.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_schema_extractor.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_schema_extractor.toCamelCase(field.negation);
+			if (camelVariant !== field.negation) register(camelVariant, field.name, true);
+		}
+	}
+	return errors;
+}
+/**
 * Check positional argument configuration
 */
 function checkPositionalConfig(extracted, commandPath) {
@@ -1091,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_subcommand_router.getAllAliases(field)) if (alias === "h" || alias === "H") errors.push({
+		for (const alias of require_schema_extractor.getAllAliases(field)) if (alias === "h" || alias === "H") errors.push({
 			commandPath,
 			type: "reserved_alias",
 			message: `Alias "${alias}" is reserved for --${alias === "h" ? "help" : "help-all"}.`,
@@ -1162,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_subcommand_router.getAllAliases(found) : []).find((a) => a === "h" || a === "H") ?? "h";
+		const alias = (found ? require_schema_extractor.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
@@ -1189,9 +1337,9 @@ function validateCaseVariantCollisions(extracted) {
 */
 function validateCrossSchemaCollisions(extractedA, extractedB) {
 	const canonicalMap = /* @__PURE__ */ new Map();
-	for (const field of extractedA.fields) canonicalMap.set(require_subcommand_router.toCamelCase(field.name), field.name);
+	for (const field of extractedA.fields) canonicalMap.set(require_schema_extractor.toCamelCase(field.name), field.name);
 	for (const field of extractedB.fields) {
-		const camel = require_subcommand_router.toCamelCase(field.name);
+		const camel = require_schema_extractor.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.`);
 	}
@@ -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)
 	];
@@ -1219,7 +1368,7 @@ function checkSubCommandAliasConflicts(command, commandPath) {
 	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;
+		const resolved = require_schema_extractor.isLazyCommand(subCmdValue) ? subCmdValue.meta : typeof subCmdValue !== "function" ? subCmdValue : null;
 		if (!resolved?.aliases) continue;
 		const subCommandPath = [...commandPath, name];
 		for (const alias of resolved.aliases) {
@@ -1282,12 +1431,12 @@ async function validateCommand(command, options = {}) {
 	const errors = [];
 	const hasSubCommands = command.subCommands ? Object.keys(command.subCommands).length > 0 : false;
 	if (command.args) {
-		const extracted = require_subcommand_router.extractFields(command.args);
+		const extracted = require_schema_extractor.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] });
+		const subResult = await validateCommand(await require_schema_extractor.resolveLazyCommand(subCmd), { commandPath: [...commandPath, name] });
 		if (!subResult.valid) errors.push(...subResult.errors);
 	}
 	if (errors.length === 0) return { valid: true };
@@ -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,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_subcommand_router.getAllAliases(field)) {
+		for (const alias of require_schema_extractor.getAllAliases(field)) {
 			aliasMap.set(alias, field.name);
 			if (alias.length > 1 && alias.includes("-")) {
-				const camelAlias = require_subcommand_router.toCamelCase(alias);
+				const camelAlias = require_schema_extractor.toCamelCase(alias);
 				if (camelAlias !== alias && !definedNames.has(camelAlias) && !aliasMap.has(camelAlias)) aliasMap.set(camelAlias, field.name);
 			}
 		}
-		const camelVariant = require_subcommand_router.toCamelCase(field.name);
+		const camelVariant = require_schema_extractor.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_schema_extractor.toCamelCase(field.negation);
+					if (camelNegation !== field.negation) negationMap.set(camelNegation, field.name);
+				}
+			}
+		}
 	}
 	return {
 		aliasMap,
 		booleanFlags,
 		arrayFlags,
-		definedNames
+		definedNames,
+		negationMap,
+		customNegatedFields
 	};
 }
 /**
@@ -1507,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_subcommand_router.getAllAliases(field)) if (alias.length === 1) shortAliases.add(alias);
+	for (const field of globalExtracted.fields) for (const alias of require_schema_extractor.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
 	};
 }
 /**
@@ -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([
@@ -1658,7 +1867,7 @@ function findFirstPositional(argv, globalExtracted) {
 * @returns Parse result
 */
 function parseArgs(argv, command, options = {}) {
-	const subCommandNameSet = require_subcommand_router.listSubCommandNamesWithAliases(command);
+	const subCommandNameSet = require_schema_extractor.listSubCommandNamesWithAliases(command);
 	const subCommandNames = [...subCommandNameSet];
 	const hasSubCommands = subCommandNames.length > 0;
 	if (hasSubCommands && argv.length > 0) if (options.globalExtracted) {
@@ -1673,7 +1882,7 @@ function parseArgs(argv, command, options = {}) {
 				remainingArgs: scanResult.tokensAfterSubcommand,
 				rawArgs: {},
 				positionals: [],
-				unknownFlags: [],
+				unknownFlags: scanResult.suppressedTokens,
 				rawGlobalArgs
 			};
 		}
@@ -1692,21 +1901,24 @@ function parseArgs(argv, command, options = {}) {
 	}
 	let extracted;
 	if (command.args) {
-		extracted = require_subcommand_router.extractFields(command.args);
+		extracted = require_schema_extractor.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_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");
+	const ddIdx = argv.indexOf("--");
+	const flagScanArgv = ddIdx >= 0 ? argv.slice(0, ddIdx) : argv;
+	const hasUserDefinedH = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_schema_extractor.getAllAliases(f).includes("H")) ?? false;
+	const hasUserDefinedh = extracted?.fields.some((f) => f.overrideBuiltinAlias === true && require_schema_extractor.getAllAliases(f).includes("h")) ?? false;
+	const helpAllRequested = flagScanArgv.includes("--help-all") || !hasUserDefinedH && flagScanArgv.includes("-H");
+	const helpRequested = !helpAllRequested && (flagScanArgv.includes("--help") || !hasUserDefinedh && flagScanArgv.includes("-h"));
+	const versionRequested = flagScanArgv.includes("--version");
 	if (helpRequested || helpAllRequested || versionRequested) return {
 		helpRequested,
 		helpAllRequested,
@@ -1751,11 +1963,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_subcommand_router.getAllAliases(f)) knownAliases.add(alias);
+	for (const f of extracted.fields) for (const alias of require_schema_extractor.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_subcommand_router.getAllAliases(f)) knownAliases.add(alias);
+		for (const alias of require_schema_extractor.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);
@@ -1806,7 +2018,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 +2254,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 +2301,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_schema_extractor.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));
@@ -2129,8 +2378,8 @@ 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);
+			const subCmdNames = require_schema_extractor.listSubCommands(command);
+			const allSubCmdNameSet = require_schema_extractor.listSubCommandNamesWithAliases(command);
 			if (subCmdNames.length > 0) {
 				const potentialSubCmd = findFirstPositional(argv, context.globalExtracted);
 				if (potentialSubCmd && !allSubCmdNameSet.has(potentialSubCmd)) hasUnknownSubcommand = true;
@@ -2172,7 +2421,23 @@ async function runCommandInternal(command, argv, options = {}) {
 			};
 		}
 		if (parseResult.subCommand) {
-			const resolved = await require_subcommand_router.resolveSubcommandWithAlias(command, 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_schema_extractor.resolveSubcommandWithAlias(command, parseResult.subCommand);
 			if (resolved) {
 				const subContext = {
 					commandPath: [...context.commandPath ?? [], parseResult.subCommand],
@@ -2190,7 +2455,7 @@ async function runCommandInternal(command, argv, options = {}) {
 				});
 			}
 		}
-		if (require_subcommand_router.listSubCommands(command).length > 0 && !parseResult.subCommand && !command.run) {
+		if (require_schema_extractor.listSubCommands(command).length > 0 && !parseResult.subCommand && !command.run) {
 			const help = generateHelp(command, {
 				showSubcommands: options.showSubcommands ?? true,
 				context
@@ -2218,7 +2483,8 @@ async function runCommandInternal(command, argv, options = {}) {
 			} else if (unknownKeysMode === "strip") for (const flag of parseResult.unknownFlags) logger.error(formatUnknownFlagWarning(flag, knownFlags));
 		}
 		let validatedGlobalArgs = {};
-		if (options.globalArgs && options._globalExtracted) {
+		const isCompletionInvocation = command.name === "__complete";
+		if (options.globalArgs && options._globalExtracted && !isCompletionInvocation) {
 			for (const field of options._globalExtracted.fields) if (field.env && accumulatedGlobalArgs[field.name] === void 0) {
 				const envNames = Array.isArray(field.env) ? field.env : [field.env];
 				for (const envName of envNames) {
@@ -2247,7 +2513,7 @@ async function runCommandInternal(command, argv, options = {}) {
 		}
 		if (!command.args) {
 			const proxiedGlobalArgs = createDualCaseProxy(validatedGlobalArgs);
-			if (options._globalExtracted) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
+			if (options._globalExtracted && !isCompletionInvocation) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
 			collector?.stop();
 			return await executeLifecycle(command, proxiedGlobalArgs, {
 				handleSignals: options.handleSignals,
@@ -2276,8 +2542,8 @@ async function runCommandInternal(command, argv, options = {}) {
 		}
 		const proxiedCommandArgs = createDualCaseProxy(validationResult.data);
 		const proxiedGlobalArgs = createDualCaseProxy(validatedGlobalArgs);
-		if (options._globalExtracted) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
-		if (parseResult.extractedFields) await runEffects(proxiedCommandArgs, parseResult.extractedFields, proxiedGlobalArgs);
+		if (options._globalExtracted && !isCompletionInvocation) await runEffects(proxiedGlobalArgs, options._globalExtracted, proxiedGlobalArgs);
+		if (parseResult.extractedFields && !isCompletionInvocation) await runEffects(proxiedCommandArgs, parseResult.extractedFields, proxiedGlobalArgs);
 		const mergedArgs = createDualCaseProxy({
 			...proxiedGlobalArgs,
 			...proxiedCommandArgs
@@ -2307,11 +2573,12 @@ async function runCommandInternal(command, argv, options = {}) {
 */
 function extractAndValidateGlobal(options) {
 	if (!options.globalArgs) return void 0;
-	const extracted = require_subcommand_router.extractFields(options.globalArgs);
+	const extracted = require_schema_extractor.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(", ")}`);
@@ -2338,6 +2605,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 +2743,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 +2761,4 @@ Object.defineProperty(exports, 'validateReservedAliases', {
     return validateReservedAliases;
   }
 });
-//# sourceMappingURL=runner-CriXJlm4.cjs.map
+//# sourceMappingURL=runner-CRZ_7Y9i.cjs.map