politty 0.4.3 → 0.4.6

package/dist/{runner-D6k4BgB4.js → runner-DjG0uBxQ.js}

@@ -1,5 +1,5 @@
-import { a as getExtractedFields, i as extractFields, r as resolveSubCommandMeta } from "./lazy-BrEg8SgI.js";
-import { a as emptyLogs, i as createLogCollector, n as resolveLazyCommand, o as mergeLogs, r as resolveSubcommand, t as listSubCommands } from "./subcommand-router-CAzBsLSI.js";
+import { a as getExtractedFields, i as extractFields, r as resolveSubCommandMeta, s as toCamelCase } from "./lazy-DSyfzR-F.js";
+import { a as emptyLogs, i as createLogCollector, n as resolveLazyCommand, o as mergeLogs, r as resolveSubcommand, t as listSubCommands } from "./subcommand-router-CKuy6D2b.js";
 import { z } from "zod";
 import { styleText } from "node:util";
 import stringWidth from "string-width";
@@ -555,6 +555,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 = getExtractedFields(command);
 	if (extracted) {
 		const positionals = extracted.fields.filter((a) => a.positional);
@@ -740,6 +741,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) {
@@ -802,6 +821,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));
@@ -1114,13 +1134,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: [],
@@ -1153,11 +1180,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("=");
@@ -1223,16 +1267,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 = 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
 	};
 }
 /**
@@ -1256,6 +1305,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
 /**
@@ -1269,7 +1463,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,
@@ -1307,6 +1517,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,
@@ -1315,9 +1532,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];
@@ -1332,6 +1551,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 {
@@ -1343,7 +1567,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)
 	};
 }
 
@@ -1526,11 +1807,11 @@ const defaultLogger = {
 * ```
 */
 async function runCommand(command, argv, options = {}) {
+	const globalExtracted = extractAndValidateGlobal(options);
 	return runCommandInternal(command, argv, {
 		...options,
 		handleSignals: false,
-		skipValidation: options.skipValidation,
-		logger: options.logger
+		_globalExtracted: globalExtracted
 	});
 }
 /**
@@ -1557,16 +1838,20 @@ async function runCommand(command, argv, options = {}) {
 * ```
 */
 async function runMain(command, options = {}) {
+	const globalExtracted = extractAndValidateGlobal(options);
 	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,
 		_context: {
 			commandPath: [],
 			rootName: command.name,
-			rootVersion: options.version
+			rootVersion: options.version,
+			globalExtracted
 		}
 	});
 	if (process.stdout.writableLength > 0) await new Promise((resolve) => process.stdout.once("drain", resolve));
@@ -1579,7 +1864,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 ? createLogCollector() : null;
 	collector?.start();
@@ -1587,12 +1873,19 @@ async function runCommandInternal(command, argv, options = {}) {
 		return mergeLogs(options._existingLogs ?? emptyLogs(), collector?.getLogs() ?? 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 = 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("");
@@ -1636,13 +1929,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
 				});
 			}
 		}
@@ -1674,9 +1969,35 @@ 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()
@@ -1693,8 +2014,12 @@ 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()
@@ -1711,7 +2036,24 @@ 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 = 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
 export { symbols as C, styles as S, renderInline as _, parseArgv as a, logger as b, validateDuplicateAliases as c, validateReservedAliases as d, DuplicateAliasError as f, generateHelp as g, ReservedAliasError as h, formatValidationErrors as i, validateDuplicateFields as l, PositionalConfigError as m, runMain as n, formatCommandValidationErrors as o, DuplicateFieldError as p, runner_exports as r, validateCommand as s, runCommand as t, validatePositionalConfig as u, renderMarkdown as v, setColorEnabled as x, isColorEnabled as y };
-//# sourceMappingURL=runner-D6k4BgB4.js.map
+//# sourceMappingURL=runner-DjG0uBxQ.js.map