politty 0.4.4 → 0.4.7

package/dist/{runner-C4fSHJMe.cjs → runner-Cn6Oq4ZZ.cjs}

@@ -1,5 +1,5 @@
-const require_subcommand_router = require('./subcommand-router-ZjNjFaUL.cjs');
-const require_lazy = require('./lazy-BEDnSR0m.cjs');
+const require_subcommand_router = require('./subcommand-router-sZHhUP7b.cjs');
+const require_lazy = require('./lazy-DHlvJiQQ.cjs');
 let zod = require("zod");
 let node_util = require("node:util");
 let string_width = require("string-width");
@@ -35,12 +35,30 @@ async function executeLifecycle(command, args, _options = {}) {
 				process.off("SIGINT", signalHandler);
 				process.off("SIGTERM", signalHandler);
 			}
+			const signalError = /* @__PURE__ */ new Error("Process interrupted");
+			cleanupContext.error = signalError;
 			if (command.cleanup) try {
 				await command.cleanup(cleanupContext);
 			} catch (e) {
 				console.error("Error during signal cleanup:", e);
 			}
+			if (_options.globalCleanup) try {
+				await _options.globalCleanup({ error: signalError });
+			} catch (e) {
+				console.error("Error during global signal cleanup:", e);
+			}
 			collector?.stop();
+			if (process.stdout.writableNeedDrain) await new Promise((resolve) => {
+				const timeout = setTimeout(() => {
+					process.stdout.off("drain", onDrain);
+					resolve();
+				}, 200);
+				const onDrain = () => {
+					clearTimeout(timeout);
+					resolve();
+				};
+				process.stdout.once("drain", onDrain);
+			});
 			process.exit(1);
 		};
 		process.on("SIGINT", signalHandler);
@@ -539,6 +557,7 @@ function renderUsageLine(command, context) {
 	const parts = [];
 	const name = buildUsageCommandName(command, context);
 	parts.push(styles.commandName(name));
+	if (context?.globalExtracted?.fields.length) parts.push(styles.placeholder("[global options]"));
 	const extracted = require_lazy.getExtractedFields(command);
 	if (extracted) {
 		const positionals = extracted.fields.filter((a) => a.positional);
@@ -724,6 +743,24 @@ function formatOption(flags, description, indent = 0, extraDescPadding = 0) {
 	return `${indentStr}  ${padEndVisual(flags, effectiveFlagWidth)}${description}`;
 }
 /**
+* Format a single option field as a help line
+*/
+function formatFieldLine(opt, indent = 0, extraDescPadding = 0) {
+	const flags = formatFlags(opt);
+	let desc = opt.description ?? "";
+	if (opt.defaultValue !== void 0) desc += ` ${styles.defaultValue(`(default: ${JSON.stringify(opt.defaultValue)})`)}`;
+	if (opt.required) desc += ` ${styles.required("(required)")}`;
+	const envInfo = formatEnvInfo(opt.env);
+	if (envInfo) desc += ` ${envInfo}`;
+	return formatOption(flags, desc, indent, extraDescPadding);
+}
+/**
+* Render global options section
+*/
+function renderGlobalOptions(globalExtracted) {
+	return globalExtracted.fields.filter((a) => !a.positional).map((opt) => formatFieldLine(opt)).join("\n");
+}
+/**
 * Render options for a subcommand (used by showSubcommandOptions)
 */
 function renderSubcommandOptionsCompact(command, indent) {
@@ -786,6 +823,7 @@ function generateHelp(command, options) {
 	sections.push(`${styles.sectionHeader("Usage:")} ${renderUsageLine(command, context)}`);
 	const optionsText = renderOptions(command, options.descriptions, context);
 	if (optionsText) sections.push(`${styles.sectionHeader("Options:")}\n${optionsText}`);
+	if (context?.globalExtracted?.fields.length) sections.push(`${styles.sectionHeader("Global Options:")}\n${renderGlobalOptions(context.globalExtracted)}`);
 	if (options.showSubcommands !== false && command.subCommands && getVisibleSubcommandEntries(command.subCommands).length > 0) {
 		const currentPath = context?.commandPath?.join(" ") ?? "";
 		const visibleSubCommands = Object.fromEntries(getVisibleSubcommandEntries(command.subCommands));
@@ -1098,13 +1136,20 @@ function formatCommandValidationErrors(errors) {
 * - Combined short options: -abc (treated as -a -b -c if all are boolean)
 * - Positional arguments
 * - -- to stop parsing options
+* - Boolean negation: --no-flag, --noFlag (requires `booleanFlags`)
+*
+* **Note:** When using negation detection (`--noFlag` / `--no-flag`),
+* supply `definedNames` so that options whose names happen to start with
+* "no" (e.g. `noDryRun`) are not mistaken for negation of another flag.
+* Without `definedNames`, all `--noX` forms matching a boolean flag will
+* be treated as negation.
 *
 * @param argv - Command line arguments
 * @param options - Parser options
 * @returns Parsed arguments
 */
 function parseArgv(argv, options = {}) {
-	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set() } = options;
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set(), arrayFlags = /* @__PURE__ */ new Set(), definedNames = /* @__PURE__ */ new Set() } = options;
 	const result = {
 		options: {},
 		positionals: [],
@@ -1137,11 +1182,28 @@ function parseArgv(argv, options = {}) {
 			const withoutDashes = arg.slice(2);
 			if (withoutDashes.startsWith("no-")) {
 				const flagName = withoutDashes.slice(3);
-				const resolvedName = aliasMap.get(flagName) ?? flagName;
+				if (flagName === flagName.toLowerCase()) {
+					const resolvedName = aliasMap.get(flagName) ?? flagName;
+					if (booleanFlags.has(resolvedName)) {
+						const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
+						if (!definedNames.has(asIsResolved)) {
+							setOption(flagName, false);
+							i++;
+							continue;
+						}
+					}
+				}
+			}
+			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)) {
-					setOption(flagName, false);
-					i++;
-					continue;
+					const asIsResolved = aliasMap.get(withoutDashes) ?? withoutDashes;
+					if (!definedNames.has(asIsResolved)) {
+						setOption(camelFlagName, false);
+						i++;
+						continue;
+					}
 				}
 			}
 			const eqIndex = withoutDashes.indexOf("=");
@@ -1207,16 +1269,21 @@ function buildParserOptions(extracted) {
 	const aliasMap = /* @__PURE__ */ new Map();
 	const booleanFlags = /* @__PURE__ */ new Set();
 	const arrayFlags = /* @__PURE__ */ new Set();
+	const definedNames = /* @__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);
 		if (field.alias) aliasMap.set(field.alias, field.name);
+		const camelVariant = require_lazy.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);
 	}
 	return {
 		aliasMap,
 		booleanFlags,
-		arrayFlags
+		arrayFlags,
+		definedNames
 	};
 }
 /**
@@ -1240,6 +1307,151 @@ function mergeWithPositionals(parsed, extracted) {
 	return result;
 }
 
+//#endregion
+//#region src/parser/subcommand-scanner.ts
+/**
+* Build lookup tables from extracted global schema fields.
+* Shared by scanForSubcommand, separateGlobalArgs, and findFirstPositional.
+*/
+function buildGlobalFlagLookup(globalExtracted) {
+	const { aliasMap = /* @__PURE__ */ new Map(), booleanFlags = /* @__PURE__ */ new Set() } = buildParserOptions(globalExtracted);
+	return {
+		aliasMap,
+		booleanFlags,
+		flagNames: new Set(globalExtracted.fields.map((f) => f.name)),
+		cliNames: new Set(globalExtracted.fields.map((f) => f.cliName)),
+		aliases: new Set(globalExtracted.fields.filter((f) => f.alias).map((f) => f.alias))
+	};
+}
+/**
+* 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.
+*/
+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 resolvedName = lookup.aliasMap.get(flagName) ?? flagName;
+	return {
+		resolvedName,
+		withoutDashes,
+		isNegated,
+		isGlobal: lookup.flagNames.has(resolvedName) || lookup.cliNames.has(withoutDashes) || lookup.cliNames.has(flagName)
+	};
+}
+/**
+* Check whether a non-boolean flag should consume the next argv token as its value.
+* Returns true when the next token exists, is not a flag, and the current flag
+* is not boolean / negated / using = syntax.
+*/
+function shouldConsumeValue(arg, resolvedName, isNegated, nextArg, booleanFlags) {
+	return !arg.includes("=") && !booleanFlags.has(resolvedName) && !isNegated && nextArg !== void 0 && !nextArg.startsWith("-");
+}
+/**
+* Collect a recognized global flag (and its value if applicable) into `dest`,
+* returning how many argv positions were consumed (1 or 2).
+*/
+function collectGlobalFlag(argv, i, resolvedName, isNegated, booleanFlags, dest) {
+	const arg = argv[i];
+	dest.push(arg);
+	if (shouldConsumeValue(arg, resolvedName, isNegated, argv[i + 1], booleanFlags)) {
+		dest.push(argv[i + 1]);
+		return 2;
+	}
+	return 1;
+}
+/**
+* Scan argv to find the subcommand position, skipping over global flags.
+*
+* Walks argv and recognizes global flags (long, short, --no-*) so that
+* `my-cli --verbose build --output dist` correctly identifies `build` as
+* the subcommand (index 1) rather than treating `--verbose` as the subcommand.
+*
+* Limitation: flags appearing before the subcommand name are matched only
+* against the global schema. If a flag is defined in both global and a
+* subcommand's local schema, the pre-subcommand occurrence is always treated
+* as global because the local schema is not available until the subcommand is
+* identified (lazy-loaded commands make eager checking infeasible). Place
+* colliding flags after the subcommand name so that `separateGlobalArgs` can
+* apply local-precedence logic.
+*
+* @param argv - Command line arguments
+* @param subCommandNames - Valid subcommand names
+* @param globalExtracted - Extracted fields from global args schema
+* @returns Scan result with subcommand position and token separation
+*/
+function scanForSubcommand(argv, subCommandNames, globalExtracted) {
+	const lookup = buildGlobalFlagLookup(globalExtracted);
+	const subCommandNameSet = new Set(subCommandNames);
+	const globalTokensBefore = [];
+	let i = 0;
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (arg === "--" || BUILTIN_FLAGS.has(arg)) break;
+		if (!arg.startsWith("-") && subCommandNameSet.has(arg)) return {
+			subCommandIndex: i,
+			globalTokensBefore,
+			tokensAfterSubcommand: argv.slice(i + 1)
+		};
+		if (arg.startsWith("--")) {
+			const { resolvedName, isNegated, isGlobal } = resolveGlobalLongOption(arg, lookup);
+			if (isGlobal) {
+				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokensBefore);
+				continue;
+			}
+			break;
+		}
+		if (arg.startsWith("-") && arg.length > 1) {
+			const withoutDash = arg.includes("=") ? arg.slice(1, arg.indexOf("=")) : arg.slice(1);
+			if (withoutDash.length === 1) {
+				const resolvedName = lookup.aliasMap.get(withoutDash) ?? withoutDash;
+				if (lookup.aliases.has(withoutDash) || lookup.flagNames.has(resolvedName)) {
+					i += collectGlobalFlag(argv, i, resolvedName, false, lookup.booleanFlags, globalTokensBefore);
+					continue;
+				}
+			}
+			break;
+		}
+		break;
+	}
+	return {
+		subCommandIndex: -1,
+		globalTokensBefore,
+		tokensAfterSubcommand: []
+	};
+}
+const BUILTIN_FLAGS = new Set([
+	"--help",
+	"-h",
+	"--help-all",
+	"-H",
+	"--version"
+]);
+/**
+* Find the first positional argument in argv, properly skipping global flag values.
+* Without globalExtracted, falls back to the first non-flag token.
+*/
+function findFirstPositional(argv, globalExtracted) {
+	if (!globalExtracted) return argv.find((arg) => !arg.startsWith("-"));
+	const lookup = buildGlobalFlagLookup(globalExtracted);
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (!arg.startsWith("-")) return arg;
+		if (arg === "--") return void 0;
+		if (arg.startsWith("--")) {
+			const { resolvedName, isNegated, isGlobal } = resolveGlobalLongOption(arg, lookup);
+			if (isGlobal && shouldConsumeValue(arg, resolvedName, isNegated, argv[i + 1], lookup.booleanFlags)) i++;
+			continue;
+		}
+		if (arg.length === 2) {
+			const ch = arg[1];
+			if (lookup.aliases.has(ch)) {
+				if (shouldConsumeValue(arg, lookup.aliasMap.get(ch) ?? ch, false, argv[i + 1], lookup.booleanFlags)) i++;
+			}
+		}
+	}
+}
+
 //#endregion
 //#region src/parser/arg-parser.ts
 /**
@@ -1253,7 +1465,23 @@ function mergeWithPositionals(parsed, extracted) {
 function parseArgs(argv, command, options = {}) {
 	const subCommandNames = command.subCommands ? Object.keys(command.subCommands) : [];
 	const hasSubCommands = subCommandNames.length > 0;
-	if (hasSubCommands && argv.length > 0) {
+	if (hasSubCommands && argv.length > 0) if (options.globalExtracted) {
+		const scanResult = scanForSubcommand(argv, subCommandNames, options.globalExtracted);
+		if (scanResult.subCommandIndex >= 0) {
+			const rawGlobalArgs = parseGlobalArgs(scanResult.globalTokensBefore, options.globalExtracted);
+			return {
+				helpRequested: false,
+				helpAllRequested: false,
+				versionRequested: false,
+				subCommand: argv[scanResult.subCommandIndex],
+				remainingArgs: scanResult.tokensAfterSubcommand,
+				rawArgs: {},
+				positionals: [],
+				unknownFlags: [],
+				rawGlobalArgs
+			};
+		}
+	} else {
 		const firstArg = argv[0];
 		if (firstArg && !firstArg.startsWith("-") && subCommandNames.includes(firstArg)) return {
 			helpRequested: false,
@@ -1291,6 +1519,13 @@ function parseArgs(argv, command, options = {}) {
 		positionals: [],
 		unknownFlags: []
 	};
+	let commandArgv = argv;
+	let rawGlobalArgs;
+	if (options.globalExtracted) {
+		const { separated, globalParsed } = separateGlobalArgs(argv, options.globalExtracted, extracted);
+		commandArgv = separated;
+		rawGlobalArgs = globalParsed;
+	}
 	if (!extracted) return {
 		helpRequested: false,
 		helpAllRequested: false,
@@ -1299,9 +1534,11 @@ function parseArgs(argv, command, options = {}) {
 		remainingArgs: [],
 		rawArgs: {},
 		positionals: [],
-		unknownFlags: []
+		unknownFlags: [],
+		rawGlobalArgs
 	};
-	const parsed = parseArgv(argv, buildParserOptions(extracted));
+	const parserOptions = buildParserOptions(extracted);
+	const parsed = parseArgv(commandArgv, parserOptions);
 	const rawArgs = mergeWithPositionals(parsed, extracted);
 	for (const field of extracted.fields) if (field.env && rawArgs[field.name] === void 0) {
 		const envNames = Array.isArray(field.env) ? field.env : [field.env];
@@ -1316,6 +1553,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 = new Set(extracted.fields.filter((f) => f.alias).map((f) => f.alias));
+	if (options.globalExtracted) for (const f of options.globalExtracted.fields) {
+		knownFlags.add(f.name);
+		knownCliNames.add(f.cliName);
+		if (f.alias) knownAliases.add(f.alias);
+	}
 	const unknownFlags = [];
 	for (const key of Object.keys(parsed.options)) if (!knownFlags.has(key) && !knownCliNames.has(key) && !knownAliases.has(key)) unknownFlags.push(key);
 	return {
@@ -1327,7 +1569,64 @@ function parseArgs(argv, command, options = {}) {
 		rawArgs,
 		positionals: parsed.positionals,
 		unknownFlags,
-		extractedFields: extracted
+		extractedFields: extracted,
+		rawGlobalArgs
+	};
+}
+/**
+* Parse global args from a list of tokens (e.g., tokens before the subcommand).
+* Env fallbacks are applied later in the runner on the accumulated global args.
+*/
+function parseGlobalArgs(tokens, globalExtracted) {
+	if (tokens.length === 0) return {};
+	return mergeWithPositionals(parseArgv(tokens, buildParserOptions(globalExtracted)), globalExtracted);
+}
+/**
+* Separate global flags from command-local args in argv.
+* Global flags mixed with command args (e.g., `build --verbose --output dist`)
+* are extracted and returned separately.
+* When a flag is defined in both global and local schemas, the local definition
+* takes precedence (the flag stays in the command tokens).
+*
+* Note: Combined short flags (e.g., `-vq`) are not decomposed here; only
+* single-character short options are recognized as global. The underlying
+* `parseArgv` handles combined shorts for command-local parsing.
+*/
+function separateGlobalArgs(argv, globalExtracted, localExtracted) {
+	const lookup = buildGlobalFlagLookup(globalExtracted);
+	const localCliNames = new Set(localExtracted?.fields.map((f) => f.cliName) ?? []);
+	const localAliases = new Set(localExtracted?.fields.filter((f) => f.alias).map((f) => f.alias) ?? []);
+	const globalTokens = [];
+	const commandTokens = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--") {
+			commandTokens.push(...argv.slice(i));
+			break;
+		}
+		if (arg.startsWith("--")) {
+			const { resolvedName, withoutDashes, isNegated, isGlobal } = resolveGlobalLongOption(arg, lookup);
+			const flagName = isNegated ? withoutDashes.slice(3) : withoutDashes;
+			const isLocalCollision = localCliNames.has(withoutDashes) || localCliNames.has(flagName);
+			if (isGlobal && !isLocalCollision) {
+				i += collectGlobalFlag(argv, i, resolvedName, isNegated, lookup.booleanFlags, globalTokens) - 1;
+				continue;
+			}
+		} else if (arg.startsWith("-") && arg.length > 1) {
+			const withoutDash = arg.includes("=") ? arg.slice(1, arg.indexOf("=")) : arg.slice(1);
+			if (withoutDash.length === 1) {
+				const resolvedName = lookup.aliasMap.get(withoutDash) ?? withoutDash;
+				if ((lookup.aliases.has(withoutDash) || lookup.flagNames.has(resolvedName)) && !localAliases.has(withoutDash)) {
+					i += collectGlobalFlag(argv, i, resolvedName, false, lookup.booleanFlags, globalTokens) - 1;
+					continue;
+				}
+			}
+		}
+		commandTokens.push(arg);
+	}
+	return {
+		separated: commandTokens,
+		globalParsed: parseGlobalArgs(globalTokens, globalExtracted)
 	};
 }
 
@@ -1510,12 +1809,61 @@ const defaultLogger = {
 * ```
 */
 async function runCommand(command, argv, options = {}) {
-	return runCommandInternal(command, argv, {
+	const globalExtracted = extractAndValidateGlobal(options);
+	const shouldCaptureLogs = options.captureLogs ?? false;
+	const globalCollector = shouldCaptureLogs ? require_subcommand_router.createLogCollector() : null;
+	if (options.setup) {
+		globalCollector?.start();
+		try {
+			await options.setup({});
+		} catch (e) {
+			const error = e instanceof Error ? e : new Error(String(e));
+			if (options.cleanup) try {
+				await options.cleanup({ error });
+			} catch {}
+			globalCollector?.stop();
+			return {
+				success: false,
+				error,
+				exitCode: 1,
+				logs: globalCollector?.getLogs() ?? require_subcommand_router.emptyLogs()
+			};
+		}
+		globalCollector?.stop();
+	}
+	const result = await runCommandInternal(command, argv, {
 		...options,
 		handleSignals: false,
-		skipValidation: options.skipValidation,
-		logger: options.logger
+		_globalExtracted: globalExtracted,
+		_globalCleanup: options.cleanup,
+		_existingLogs: globalCollector?.getLogs()
 	});
+	if (options.cleanup) {
+		const cleanupCollector = shouldCaptureLogs ? require_subcommand_router.createLogCollector() : null;
+		cleanupCollector?.start();
+		const cleanupCtx = { error: !result.success ? result.error : void 0 };
+		try {
+			await options.cleanup(cleanupCtx);
+		} catch (e) {
+			if (result.success) {
+				const error = e instanceof Error ? e : new Error(String(e));
+				cleanupCollector?.stop();
+				return {
+					success: false,
+					error,
+					exitCode: 1,
+					logs: require_subcommand_router.mergeLogs(result.logs, cleanupCollector?.getLogs() ?? require_subcommand_router.emptyLogs())
+				};
+			}
+		}
+		cleanupCollector?.stop();
+		const cleanupLogs = cleanupCollector?.getLogs() ?? require_subcommand_router.emptyLogs();
+		if (cleanupLogs.entries.length > 0) return {
+			...result,
+			logs: require_subcommand_router.mergeLogs(result.logs, cleanupLogs)
+		};
+	}
+	return result;
 }
 /**
 * Run a CLI command as the main entry point
@@ -1541,18 +1889,38 @@ async function runCommand(command, argv, options = {}) {
 * ```
 */
 async function runMain(command, options = {}) {
+	const globalExtracted = extractAndValidateGlobal(options);
+	if (options.setup) try {
+		await options.setup({});
+	} catch (e) {
+		const error = e instanceof Error ? e : new Error(String(e));
+		if (options.cleanup) try {
+			await options.cleanup({ error });
+		} catch {}
+		process.exit(1);
+	}
 	const result = await runCommandInternal(command, process.argv.slice(2), {
 		debug: options.debug,
 		captureLogs: options.captureLogs,
 		skipValidation: options.skipValidation,
 		handleSignals: true,
 		logger: options.logger,
+		globalArgs: options.globalArgs,
+		_globalExtracted: globalExtracted,
+		_globalCleanup: options.cleanup,
 		_context: {
 			commandPath: [],
 			rootName: command.name,
-			rootVersion: options.version
+			rootVersion: options.version,
+			globalExtracted
 		}
 	});
+	if (options.cleanup) {
+		const cleanupCtx = { error: !result.success ? result.error : void 0 };
+		try {
+			await options.cleanup(cleanupCtx);
+		} catch {}
+	}
 	if (process.stdout.writableLength > 0) await new Promise((resolve) => process.stdout.once("drain", resolve));
 	process.exit(result.exitCode);
 }
@@ -1563,7 +1931,8 @@ async function runCommandInternal(command, argv, options = {}) {
 	const logger = options.logger ?? defaultLogger;
 	const context = options._context ?? {
 		commandPath: [],
-		rootName: command.name
+		rootName: command.name,
+		globalExtracted: options._globalExtracted
 	};
 	const collector = options.captureLogs ?? false ? require_subcommand_router.createLogCollector() : null;
 	collector?.start();
@@ -1571,12 +1940,19 @@ async function runCommandInternal(command, argv, options = {}) {
 		return require_subcommand_router.mergeLogs(options._existingLogs ?? require_subcommand_router.emptyLogs(), collector?.getLogs() ?? require_subcommand_router.emptyLogs());
 	};
 	try {
-		const parseResult = parseArgs(argv, command, { skipValidation: options.skipValidation });
+		const parseResult = parseArgs(argv, command, {
+			skipValidation: options.skipValidation,
+			globalExtracted: options._globalExtracted
+		});
+		const accumulatedGlobalArgs = {
+			...options._parsedGlobalArgs,
+			...parseResult.rawGlobalArgs
+		};
 		if (parseResult.helpRequested || parseResult.helpAllRequested) {
 			let hasUnknownSubcommand = false;
 			const subCmdNames = require_subcommand_router.listSubCommands(command);
 			if (subCmdNames.length > 0) {
-				const potentialSubCmd = argv.find((arg) => !arg.startsWith("-"));
+				const potentialSubCmd = findFirstPositional(argv, context.globalExtracted);
 				if (potentialSubCmd && !subCmdNames.includes(potentialSubCmd)) {
 					logger.error(formatUnknownSubcommand(potentialSubCmd, subCmdNames));
 					logger.error("");
@@ -1620,13 +1996,15 @@ async function runCommandInternal(command, argv, options = {}) {
 				const subContext = {
 					commandPath: [...context.commandPath ?? [], parseResult.subCommand],
 					rootName: context.rootName,
-					rootVersion: context.rootVersion
+					rootVersion: context.rootVersion,
+					globalExtracted: context.globalExtracted
 				};
 				collector?.stop();
 				return runCommandInternal(subCmd, parseResult.remainingArgs, {
 					...options,
 					_context: subContext,
-					_existingLogs: getCurrentLogs()
+					_existingLogs: getCurrentLogs(),
+					_parsedGlobalArgs: accumulatedGlobalArgs
 				});
 			}
 		}
@@ -1658,12 +2036,39 @@ 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) {
+			for (const field of options._globalExtracted.fields) if (field.env && accumulatedGlobalArgs[field.name] === void 0) {
+				const envNames = Array.isArray(field.env) ? field.env : [field.env];
+				for (const envName of envNames) {
+					const envValue = process.env[envName];
+					if (envValue !== void 0) {
+						accumulatedGlobalArgs[field.name] = envValue;
+						break;
+					}
+				}
+			}
+			const globalValidation = validateArgs(accumulatedGlobalArgs, options.globalArgs);
+			if (!globalValidation.success) {
+				const errorMessage = formatValidationErrors$1(globalValidation.errors);
+				logger.error(errorMessage);
+				collector?.stop();
+				return {
+					success: false,
+					error: new Error(errorMessage),
+					exitCode: 1,
+					logs: getCurrentLogs()
+				};
+			}
+			validatedGlobalArgs = globalValidation.data;
+		}
 		if (!command.args) {
 			collector?.stop();
-			return await executeLifecycle(command, {}, {
+			return await executeLifecycle(command, validatedGlobalArgs, {
 				handleSignals: options.handleSignals,
 				captureLogs: options.captureLogs,
-				existingLogs: getCurrentLogs()
+				existingLogs: getCurrentLogs(),
+				globalCleanup: options._globalCleanup
 			});
 		}
 		const validationResult = validateArgs(parseResult.rawArgs, command.args);
@@ -1677,11 +2082,16 @@ async function runCommandInternal(command, argv, options = {}) {
 				logs: getCurrentLogs()
 			};
 		}
+		const mergedArgs = {
+			...validatedGlobalArgs,
+			...validationResult.data
+		};
 		collector?.stop();
-		return await executeLifecycle(command, validationResult.data, {
+		return await executeLifecycle(command, mergedArgs, {
 			handleSignals: options.handleSignals,
 			captureLogs: options.captureLogs,
-			existingLogs: getCurrentLogs()
+			existingLogs: getCurrentLogs(),
+			globalCleanup: options._globalCleanup
 		});
 	} catch (error) {
 		const err = error instanceof Error ? error : new Error(String(error));
@@ -1695,6 +2105,23 @@ async function runCommandInternal(command, argv, options = {}) {
 		};
 	}
 }
+/**
+* Extract global fields from options.globalArgs and validate the schema upfront.
+* Rejects positional fields since global options must be flags.
+* Returns undefined when no globalArgs is provided.
+*/
+function extractAndValidateGlobal(options) {
+	if (!options.globalArgs) return void 0;
+	const extracted = require_lazy.extractFields(options.globalArgs);
+	if (!options.skipValidation) {
+		validateDuplicateFields(extracted);
+		validateDuplicateAliases(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(", ")}`);
+	}
+	return extracted;
+}
 
 //#endregion
 Object.defineProperty(exports, 'DuplicateAliasError', {
@@ -1835,4 +2262,4 @@ Object.defineProperty(exports, 'validateReservedAliases', {
     return validateReservedAliases;
   }
 });
-//# sourceMappingURL=runner-C4fSHJMe.cjs.map
+//# sourceMappingURL=runner-Cn6Oq4ZZ.cjs.map