clap-ts 0.2.0 → 0.3.0

package/dist/parser.js

@@ -1,265 +1,297 @@
 /**
- * Argument parser - delegates core tokenizing to node:util parseArgs,
- * then layers on: env fallback, type coercion, count/append actions,
- * numArgs with defaultMissingValue, global args, kebab-to-camel mapping,
- * subcommand detection, and default values.
+ * Argument parser.
  *
- * node:util parseArgs handles:
- *   --flag, --flag=value, --flag value, -f, -fvalue, -abc (combined booleans),
- *   -- separator, positionals
+ * Tokenizes argv directly against the command's own arg definitions. This
+ * replaced node:util parseArgs, which re-validates its entire `options` object
+ * on every call (~170ns per option, regardless of argv length) and cannot
+ * express multi-value options, value terminators, or subcommand boundaries.
  *
- * We handle on top:
- *   conflictsWith / requires (in validation.ts),
- *   env variable fallback, action: 'append' (via multiple:true), action: 'count',
- *   numArgs with defaultMissingValue, global args merge, valueParser enum validation
- *   (in validation.ts), number type coercion, kebab-to-camel mapping,
- *   required arg validation (in validation.ts), typo suggestions (in validation.ts),
- *   valueDelimiter splitting, function valueParser, trailingVarArg, last,
- *   allowHyphenValues, allowNegativeNumbers, inferLongArgs, defaultValueIf.
+ * Handled here: long/short/clustered flags, attached and `=` values, boolean
+ * negation, count and append actions, multi-token numArgs, optional values via
+ * defaultMissingValue, value delimiters, hyphen and negative-number values,
+ * positional assignment, trailing var args, `--` escape, subcommand
+ * boundaries, env fallback, conditional and static defaults, and
+ * kebab-to-camel key mapping.
+ *
+ * Constraint checks that need the whole picture (conflicts, requires, groups,
+ * possible values) live in validation.ts.
  */
-import { parseArgs as nodeParseArgs } from 'node:util';
+// ---- Error ----
+export class CliParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliParseError';
+    }
+}
 // ---- Helpers ----
+const HYPHEN = 45;
+const NEGATIVE_NUMBER = /^-\d/;
 /** Convert kebab-case to camelCase: --config-path -> configPath */
-function kebabToCamel(s) {
+export function kebabToCamel(s) {
     return s.replaceAll(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
-/** Get the raw argv slice (after the binary/script path). */
-export function getRawArgs(argv) {
+/**
+ * Get the raw argv slice (after the binary/script path). With `noBinaryName`
+ * the source is taken as-is, matching clap's Command::no_binary_name.
+ */
+export function getRawArgs(argv, noBinaryName = false) {
     if (argv) {
         return [...argv];
     }
     // Bun.argv includes [bun, script, ...args], same as process.argv
     const source = globalThis.Bun === undefined ? process.argv : globalThis.Bun.argv;
-    return source.slice(2);
+    return noBinaryName ? [...source] : source.slice(2);
 }
-// ---- Error ----
-export class CliParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'CliParseError';
-    }
+function readEnv(name) {
+    return globalThis.Bun === undefined
+        ? process.env[name]
+        : globalThis.Bun.env[name];
 }
-// ---- Flag Lookup Maps ----
+// ---- Subcommands ----
+const resolvedSubCommands = new WeakMap();
 /**
- * Build lookup maps from all possible flag forms to the canonical arg name.
- * Used for post-processing parseArgs output back to our ArgDef keys.
- * Registers both hidden aliases and visible aliases.
+ * The command's subcommands, building any lazy ones on first use and caching
+ * the result so the thunk runs at most once per command.
  */
-function buildFlagMaps(argsDef) {
-    const longMap = new Map();
-    const shortMap = new Map();
-    let hasHyphenOrNegative = false;
-    for (const [key, def] of Object.entries(argsDef)) {
-        const longName = def.long ?? key;
-        longMap.set(longName, { key, def, negated: false });
-        if (def.type === 'boolean') {
-            longMap.set(`no-${longName}`, { key, def, negated: true });
-        }
-        if (def.allowHyphenValues || def.allowNegativeNumbers) {
-            hasHyphenOrNegative = true;
-        }
-        // Register hidden aliases
-        if (def.alias) {
-            for (const alias of def.alias) {
-                if (alias.length === 1) {
-                    shortMap.set(alias, { key, def });
-                }
-                else {
-                    longMap.set(alias, { key, def, negated: false });
-                }
-            }
-        }
-        // Register visible aliases (also work as real aliases at parse time)
-        if (def.visibleAlias) {
-            for (const alias of def.visibleAlias) {
-                if (alias.length === 1) {
-                    shortMap.set(alias, { key, def });
-                }
-                else {
-                    longMap.set(alias, { key, def, negated: false });
-                }
-            }
-        }
-        if (def.short && def.short.length === 1) {
-            shortMap.set(def.short, { key, def });
-        }
+export function subCommandsOf(command) {
+    if (command.lazySubCommands === undefined) {
+        return command.subCommands ?? {};
+    }
+    let resolved = resolvedSubCommands.get(command);
+    if (resolved === undefined) {
+        resolved = { ...command.lazySubCommands(), ...command.subCommands };
+        resolvedSubCommands.set(command, resolved);
+    }
+    return resolved;
+}
+/** Whether the command has any subcommand, without building the lazy ones. */
+export function hasSubCommands(command) {
+    if (command.lazySubCommands !== undefined) {
+        return true;
+    }
+    const subs = command.subCommands;
+    if (subs === undefined) {
+        return false;
     }
-    return { longMap, shortMap, hasHyphenOrNegative };
+    for (const _key in subs) {
+        return true;
+    }
+    return false;
 }
-// ---- Build parseArgs options config ----
+// ---- Possible Values ----
+const possibleValueCache = new WeakMap();
 /**
- * Build the `options` config that node:util parseArgs expects from our ArgDef definitions.
+ * Normalize an arg's allowed values to PossibleValue records. Plain strings and
+ * PossibleValue objects can be mixed in the same list.
  */
-function buildParseArgsOptions(argsDef) {
-    const options = {};
-    const optionalValueFlags = new Set();
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (def.type === 'positional') {
-            continue;
-        }
-        const longName = def.long ?? key;
-        if (def.action === 'count') {
-            options[longName] = { type: 'boolean', multiple: true };
-        }
-        else if (def.type === 'boolean') {
-            options[longName] = { type: 'boolean' };
-            options[`no-${longName}`] = { type: 'boolean' };
-        }
-        else if (def.action === 'append') {
-            options[longName] = { type: 'string', multiple: true };
-        }
-        else {
-            options[longName] = { type: 'string' };
-        }
-        if (def.numArgs && def.numArgs.min === 0 && def.type !== 'boolean') {
-            optionalValueFlags.add(longName);
-        }
-        if (def.short && def.short.length === 1) {
-            options[longName].short = def.short;
-        }
-        // Register hidden and visible aliases
-        const registerAliases = (aliases) => {
-            const opt = options[longName];
-            for (const alias of aliases) {
-                if (alias.length > 1 || opt.short) {
-                    options[alias] = { type: opt.type, multiple: opt.multiple };
-                }
-                else {
-                    opt.short = alias;
-                }
-            }
-        };
-        if (def.alias) {
-            registerAliases(def.alias);
-        }
-        if (def.visibleAlias) {
-            registerAliases(def.visibleAlias);
+export function possibleValues(def) {
+    const parser = def.valueParser;
+    if (parser === undefined || typeof parser === 'function') {
+        return [];
+    }
+    const cached = possibleValueCache.get(parser);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const normalized = parser.map((v) => (typeof v === 'string' ? { name: v } : v));
+    possibleValueCache.set(parser, normalized);
+    return normalized;
+}
+/** Whether a raw value matches this possible value, by name or alias. */
+export function matchesPossibleValue(candidate, value, ignoreCase) {
+    if (ignoreCase) {
+        const lowered = value.toLowerCase();
+        if (candidate.name.toLowerCase() === lowered) {
+            return true;
         }
+        return candidate.aliases?.some((a) => a.toLowerCase() === lowered) ?? false;
     }
-    // Built-in flags
-    options['help'] = { type: 'boolean', short: 'h' };
-    options['version'] = { type: 'boolean', short: 'V' };
-    return { options, optionalValueFlags };
-}
-// ---- Pre-scan / Preprocessing ----
-/** Check if the next token looks like a flag (not a value). */
-function isNextTokenAFlag(nextToken) {
-    return (nextToken === undefined ||
-        (nextToken.startsWith('-') && nextToken !== '-' && nextToken !== '--'));
+    return candidate.name === value || (candidate.aliases?.includes(value) ?? false);
 }
-/** Check if a token looks like a negative number (e.g., -1, -3.14, -0). */
-function looksLikeNegativeNumber(token) {
-    return /^-\d/.test(token);
+const specCache = new WeakMap();
+/** Actions that stand alone: the flag carries no value of its own. */
+const VALUELESS_ACTIONS = new Set([
+    'count',
+    'setTrue',
+    'setFalse',
+    'help',
+    'helpShort',
+    'helpLong',
+    'version',
+]);
+function valueCounts(def) {
+    if (def.numArgs) {
+        return { min: def.numArgs.min, max: def.numArgs.max };
+    }
+    if (def.type === 'boolean' || (def.action !== undefined && VALUELESS_ACTIONS.has(def.action))) {
+        return { min: 0, max: 0 };
+    }
+    return { min: 1, max: 1 };
 }
-/** Try to match a long flag token as an optional-value flag without a value. */
-function tryStripOptionalLong(token, nextToken, optionalValueFlags, longMap) {
-    if (!token.startsWith('--') || token.length <= 2 || token.includes('=')) {
-        return undefined;
-    }
-    const flagName = token.slice(2);
-    if (!optionalValueFlags.has(flagName) || !isNextTokenAFlag(nextToken)) {
+/** The stderr notice for a deprecated arg, or undefined when it is current. */
+function deprecationNotice(key, def) {
+    if (def.deprecated === undefined || def.deprecated === false) {
         return undefined;
     }
-    const entry = longMap.get(flagName);
-    if (!entry) {
-        return undefined;
-    }
-    return { key: entry.key, defaultVal: entry.def.defaultMissingValue ?? true };
+    const label = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
+    const reason = typeof def.deprecated === 'string' ? `: ${def.deprecated}` : '';
+    const instead = def.replacedBy === undefined ? '' : `; use '--${def.replacedBy}' instead`;
+    return `'${label}' is deprecated${reason}${instead}`;
 }
-/** Try to match a short flag token as an optional-value flag without a value. */
-function tryStripOptionalShort(token, nextToken, optionalValueFlags, shortMap) {
-    if (!token.startsWith('-') || token.length !== 2 || token[1] === '-') {
-        return undefined;
-    }
-    const c = token[1];
-    const entry = shortMap.get(c);
-    if (!entry) {
-        return undefined;
-    }
-    const entryLong = entry.def.long ?? entry.key;
-    if (!optionalValueFlags.has(entryLong) || !isNextTokenAFlag(nextToken)) {
-        return undefined;
-    }
-    return { key: entry.key, defaultVal: entry.def.defaultMissingValue ?? true };
+function makeSpec(key, def, argsOverrideSelf) {
+    const { min, max } = valueCounts(def);
+    const isAppend = def.action === 'append';
+    const forced = def.action === 'setTrue' ? true : def.action === 'setFalse' ? false : undefined;
+    const triggers = def.action === 'help' || def.action === 'helpShort' || def.action === 'helpLong'
+        ? def.action
+        : def.action === 'version'
+            ? 'version'
+            : undefined;
+    return {
+        forced,
+        triggers,
+        deprecation: deprecationNotice(key, def),
+        key,
+        def,
+        long: def.long ?? key,
+        camel: kebabToCamel(key),
+        repeatIsError: !isAppend && !argsOverrideSelf && def.overridesWith === undefined,
+        isBool: def.type === 'boolean' && !VALUELESS_ACTIONS.has(def.action ?? ''),
+        isCount: def.action === 'count',
+        isAppend,
+        min,
+        max,
+    };
 }
-/**
- * Resolve a flag token to its key and ArgDef, checking both long and short maps.
- * Returns the canonical key (used as fallback long name) and the def.
- */
-function resolveFlag(token, longMap, shortMap) {
-    if (token.startsWith('--') && token.length > 2) {
-        const flagName = token.includes('=') ? token.slice(2, token.indexOf('=')) : token.slice(2);
-        const entry = longMap.get(flagName);
-        return entry ? { key: entry.key, def: entry.def } : undefined;
+function registerAliases(aliases, spec, longs, shorts) {
+    if (!aliases) {
+        return;
     }
-    if (token.startsWith('-') && token.length === 2 && token[1] !== '-') {
-        return shortMap.get(token[1]) ?? undefined;
+    for (const alias of aliases) {
+        if (alias.length === 1) {
+            shorts.set(alias, spec);
+        }
+        else {
+            longs.set(alias, { spec, negated: false });
+        }
     }
-    return undefined;
 }
-/**
- * Pre-process raw args before passing to node:util parseArgs.
- * Handles:
- * 1. Optional-value flags (strip bare flags, record defaults)
- * 2. allowHyphenValues / allowNegativeNumbers (rewrite --flag -value to --flag=-value)
- */
-function preprocessArgs(rawArgs, optionalValueFlags, longMap, shortMap, hasHyphenOrNegative) {
-    if (optionalValueFlags.size === 0 && !hasHyphenOrNegative) {
-        return { processedArgs: [...rawArgs], optionalDefaults: new Map() };
-    }
-    const optionalDefaults = new Map();
-    const processedArgs = [];
-    let stopParsing = false;
-    for (let i = 0; i < rawArgs.length; i++) {
-        const token = rawArgs[i];
-        if (stopParsing || token === '--') {
-            if (token === '--') {
-                stopParsing = true;
-            }
-            processedArgs.push(token);
+function buildSpec(command) {
+    const argsDef = command.args ?? {};
+    const longs = new Map();
+    const shorts = new Map();
+    const positionals = [];
+    const all = [];
+    const byKey = {};
+    let allowsNegative = false;
+    const cmdAllowHyphen = command.meta.allowHyphenValues === true;
+    const argsOverrideSelf = command.meta.argsOverrideSelf === true;
+    let hasOverrides = false;
+    if (command.meta.allowNegativeNumbers) {
+        allowsNegative = true;
+    }
+    for (const key of Object.keys(argsDef)) {
+        const def = argsDef[key];
+        if (def.allowNegativeNumbers) {
+            allowsNegative = true;
+        }
+        if (def.overridesWith !== undefined) {
+            hasOverrides = true;
+        }
+        const spec = makeSpec(key, def, argsOverrideSelf);
+        all.push(spec);
+        byKey[key] = spec;
+        if (def.type === 'positional') {
+            positionals.push(spec);
             continue;
         }
-        const nextToken = rawArgs[i + 1];
-        // Optional-value flag handling (long)
-        const stripped = tryStripOptionalLong(token, nextToken, optionalValueFlags, longMap);
-        if (stripped) {
-            optionalDefaults.set(stripped.key, stripped.defaultVal);
-            continue;
+        longs.set(spec.long, { spec, negated: false });
+        if (spec.isBool) {
+            longs.set(`no-${spec.long}`, { spec, negated: true });
         }
-        // Optional-value flag handling (short)
-        const strippedShort = tryStripOptionalShort(token, nextToken, optionalValueFlags, shortMap);
-        if (strippedShort) {
-            optionalDefaults.set(strippedShort.key, strippedShort.defaultVal);
-            continue;
+        if (def.short && def.short.length === 1) {
+            shorts.set(def.short, spec);
         }
-        // allowHyphenValues / allowNegativeNumbers:
-        // If this token is a known flag and the next token starts with - but the flag's
-        // def allows hyphen values or negative numbers, rewrite to --flag=-value
-        if (nextToken && nextToken.startsWith('-') && nextToken !== '-' && nextToken !== '--') {
-            const resolved = resolveFlag(token, longMap, shortMap);
-            if (resolved && resolved.def.type !== 'boolean' && resolved.def.type !== 'positional') {
-                const shouldRewrite = resolved.def.allowHyphenValues ||
-                    (resolved.def.allowNegativeNumbers && looksLikeNegativeNumber(nextToken));
-                if (shouldRewrite && !token.includes('=')) {
-                    // Rewrite to --longName=value form so node:util parseArgs treats it as a value
-                    const longName = resolved.def.long ?? resolved.key;
-                    processedArgs.push(`--${longName}=${nextToken}`);
-                    i++; // skip the next token (consumed as value)
-                    continue;
-                }
-            }
+        registerAliases(def.alias, spec, longs, shorts);
+        registerAliases(def.visibleAlias, spec, longs, shorts);
+    }
+    // Built-in flags never displace a user-defined arg of the same name.
+    const helpSpec = {
+        key: 'help', def: { type: 'boolean' }, long: 'help', camel: 'help',
+        repeatIsError: false,
+        isBool: true, isCount: false, isAppend: false, min: 0, max: 0, builtin: 'help',
+    };
+    const versionSpec = {
+        key: 'version', def: { type: 'boolean' }, long: 'version', camel: 'version',
+        repeatIsError: false,
+        isBool: true, isCount: false, isAppend: false, min: 0, max: 0, builtin: 'version',
+    };
+    if (command.meta.disableHelpFlag !== true) {
+        if (!longs.has('help')) {
+            longs.set('help', { spec: helpSpec, negated: false });
+        }
+        if (!shorts.has('h')) {
+            shorts.set('h', helpSpec);
         }
-        processedArgs.push(token);
     }
-    return { processedArgs, optionalDefaults };
+    // clap only offers --version where a version exists, either on this command
+    // or propagated down from an ancestor.
+    if (command.meta.disableVersionFlag !== true && command.meta.version !== undefined) {
+        if (!longs.has('version')) {
+            longs.set('version', { spec: versionSpec, negated: false });
+        }
+        if (!shorts.has('V')) {
+            shorts.set('V', versionSpec);
+        }
+    }
+    if (command.meta.helpExpected) {
+        const undocumented = all
+            .filter((spec) => !spec.def.hidden && !spec.def.description && !spec.def.longDescription)
+            .map((spec) => spec.key);
+        if (undocumented.length > 0) {
+            throw new CliParseError(`helpExpected is set but these arguments have no description: ${undocumented.join(', ')}`);
+        }
+    }
+    // An explicit index overrides declaration order; unindexed positionals keep
+    // their relative order after the indexed ones are placed.
+    if (positionals.some((spec) => spec.def.index !== undefined)) {
+        positionals.sort((a, b) => (a.def.index ?? Number.MAX_SAFE_INTEGER) - (b.def.index ?? Number.MAX_SAFE_INTEGER));
+    }
+    return {
+        longs,
+        shorts,
+        positionals,
+        indexedPositionals: positionals.reduce((n, spec) => (spec.def.last ? n : n + 1), 0),
+        all,
+        byKey,
+        command,
+        anySubcommands: hasSubCommands(command),
+        inferSubcommands: command.meta.inferSubcommands === true,
+        allowExternal: command.meta.allowExternalSubcommands === true,
+        subcommandPrecedence: command.meta.subcommandPrecedenceOverArg === true,
+        allowMissingPositional: command.meta.allowMissingPositional === true,
+        argsOverrideSelf,
+        ignoreErrors: command.meta.ignoreErrors === true,
+        dontDelimitTrailingValues: command.meta.dontDelimitTrailingValues === true,
+        hasOverrides,
+        cmdAllowHyphen,
+        allowsNegative,
+        inferLong: command.meta.inferLongArgs === true,
+    };
 }
-// ---- Coerce Value ----
-function coerceValue(value, def, argName) {
-    // If a function valueParser is defined, use it for coercion
+function getSpec(command) {
+    let spec = specCache.get(command);
+    if (spec === undefined) {
+        spec = buildSpec(command);
+        specCache.set(command, spec);
+    }
+    return spec;
+}
+// ---- Value Coercion ----
+export function coerceValue(value, def, argName) {
     if (typeof def.valueParser === 'function') {
         try {
             const parsed = def.valueParser(value);
-            // Ensure the result is a valid ParseResult value type
             if (typeof parsed === 'string' ||
                 typeof parsed === 'number' ||
                 typeof parsed === 'boolean') {
@@ -291,225 +323,488 @@ function coerceValue(value, def, argName) {
         }
     }
 }
-// ---- Subcommand Detection ----
-/**
- * Build a lookup map from subcommand names and aliases to canonical names.
- * Used for O(1) subcommand detection.
- */
-function buildSubcommandMap(subCommands) {
-    const map = new Map();
-    for (const [name, def] of Object.entries(subCommands)) {
-        map.set(name, name);
-        if (def.meta.aliases) {
-            for (const alias of def.meta.aliases) {
-                map.set(alias, name);
-            }
-        }
+/** Human-readable name for this arg in error messages. */
+function displayName(spec) {
+    return spec.def.type === 'positional' ? `<${spec.def.valueName ?? spec.key}>` : `--${spec.long}`;
+}
+/** Record that an arg was explicitly given, keeping the occurrence order. */
+function markSet(state, key, spec) {
+    state.explicitlySet.add(key);
+    state.valueSources.set(key, 'cli');
+    state.order?.set(key, state.seq++);
+    if (spec?.deprecation !== undefined && !state.warned.has(key)) {
+        state.warned.add(key);
+        state.warnings.push(spec.deprecation);
     }
-    return map;
 }
-/**
- * Scan positionals for a subcommand name or alias using O(1) map lookup.
- * Returns the canonical name and the index in the positionals array.
- */
-function detectSubcommand(positionals, command) {
-    if (!command.subCommands) {
-        return undefined;
+/** Whether a token can serve as a value for this arg rather than starting a new flag. */
+function isValueToken(token, spec, cmdSpec) {
+    if (token.length === 0 || token.charCodeAt(0) !== HYPHEN) {
+        return true;
     }
-    const subMap = buildSubcommandMap(command.subCommands);
-    for (let i = 0; i < positionals.length; i++) {
-        const canonical = subMap.get(positionals[i]);
-        if (canonical) {
-            return { name: canonical, index: i };
-        }
+    if (token === '-') {
+        return true;
+    }
+    if (token === '--') {
+        return false;
     }
-    return undefined;
+    if (spec.def.allowHyphenValues || cmdSpec.cmdAllowHyphen) {
+        return true;
+    }
+    return ((spec.def.allowNegativeNumbers || cmdSpec.allowsNegative) && NEGATIVE_NUMBER.test(token));
+}
+/** Record a flag occurrence that carries no value: booleans and counts. */
+function applyFlagOnly(spec, negated, state) {
+    if (spec.builtin === 'help' || spec.triggers === 'help' || spec.triggers === 'helpLong') {
+        state.helpRequested = true;
+        return;
+    }
+    if (spec.triggers === 'helpShort') {
+        state.helpRequested = true;
+        state.helpIsShort = true;
+        return;
+    }
+    if (spec.builtin === 'version' || spec.triggers === 'version') {
+        state.versionRequested = true;
+        return;
+    }
+    if (spec.forced !== undefined) {
+        state.result[spec.key] = negated ? !spec.forced : spec.forced;
+        markSet(state, spec.key, spec);
+        return;
+    }
+    if (spec.isCount) {
+        const previous = state.result[spec.key];
+        state.result[spec.key] = (typeof previous === 'number' ? previous : 0) + 1;
+    }
+    else {
+        state.result[spec.key] = !negated;
+    }
+    markSet(state, spec.key, spec);
+}
+/** Store one or more parsed values for an arg, honouring the append action. */
+function applyValues(spec, values, state) {
+    const name = displayName(spec);
+    // A second occurrence of a single-value arg is an error in clap unless the
+    // command opted into argsOverrideSelf. Reading result is cheaper than the
+    // Set, and defaults have not been applied yet, so a value here means a
+    // previous occurrence.
+    if (spec.repeatIsError && state.result[spec.key] !== undefined) {
+        throw new CliParseError(`the argument '${name}' cannot be used multiple times`);
+    }
+    if (spec.isAppend) {
+        const previous = state.result[spec.key];
+        const list = Array.isArray(previous) ? previous : [];
+        for (const value of values) {
+            list.push(String(coerceValue(value, spec.def, name)));
+        }
+        state.result[spec.key] = list;
+    }
+    else if (values.length > 1) {
+        state.result[spec.key] = values.map((v) => String(coerceValue(v, spec.def, name)));
+    }
+    else {
+        state.result[spec.key] = coerceValue(values[0], spec.def, name);
+    }
+    markSet(state, spec.key, spec);
+}
+/** Apply defaultMissingValue for a flag whose value was omitted (numArgs.min === 0). */
+function applyMissingValue(spec, state) {
+    if (spec.def.defaultMissingValues !== undefined) {
+        state.result[spec.key] = [...spec.def.defaultMissingValues];
+        markSet(state, spec.key, spec);
+        return;
+    }
+    const fallback = spec.def.defaultMissingValue ?? true;
+    if (spec.isAppend) {
+        const previous = state.result[spec.key];
+        const list = Array.isArray(previous) ? previous : [];
+        list.push(String(fallback));
+        state.result[spec.key] = list;
+    }
+    else {
+        state.result[spec.key] = fallback;
+    }
+    markSet(state, spec.key, spec);
 }
-// ---- Separate Rest Args ----
 /**
- * parseArgs lumps everything (before and after --) into its `positionals` array.
- * We need to split them into positionals (before --) and rest (after --).
+ * Consume up to `spec.max` values for a flag starting at argv[from].
+ * Returns the index of the last token consumed.
  */
-function splitPositionalsAndRest(rawArgs, parseArgsPositionals) {
-    let dashDashIdx = -1;
-    for (let i = 0; i < rawArgs.length; i++) {
-        if (rawArgs[i] === '--') {
-            dashDashIdx = i;
+function consumeValues(spec, argv, from, cmdSpec, state) {
+    const values = [];
+    let i = from;
+    while (values.length < spec.max && i < argv.length) {
+        const token = argv[i];
+        if (spec.def.valueTerminator !== undefined && token === spec.def.valueTerminator) {
+            i++;
+            break;
+        }
+        if (!isValueToken(token, spec, cmdSpec)) {
+            break;
+        }
+        if (cmdSpec.subcommandPrecedence &&
+            values.length >= spec.min &&
+            resolveSubcommand(cmdSpec, token) !== undefined) {
             break;
         }
+        values.push(token);
+        i++;
     }
-    if (dashDashIdx === -1) {
-        return { positionals: [...parseArgsPositionals], rest: [] };
+    if (values.length < spec.min) {
+        if (values.length === 0 && spec.min === 0) {
+            applyMissingValue(spec, state);
+            return i - 1;
+        }
+        throw new CliParseError(spec.min === 1
+            ? `a value is required for '${displayName(spec)}' but none was supplied`
+            : `the argument '${displayName(spec)}' requires at least ${String(spec.min)} values but ${String(values.length)} were provided`);
     }
-    const restCount = rawArgs.length - dashDashIdx - 1;
-    const totalPositionals = parseArgsPositionals.length;
-    const beforeCount = totalPositionals - restCount;
-    return {
-        positionals: parseArgsPositionals.slice(0, Math.max(0, beforeCount)),
-        rest: parseArgsPositionals.slice(Math.max(0, beforeCount)),
-    };
+    if (values.length === 0) {
+        applyMissingValue(spec, state);
+    }
+    else {
+        applyValues(spec, values, state);
+    }
+    return i - 1;
 }
-// ---- Infer Long Args ----
 /**
- * Try to resolve an unknown long flag by prefix matching.
- * Returns the matched entry if exactly one match, undefined otherwise.
+ * Resolve an unknown long flag by unique prefix match (inferLongArgs).
+ * Negated (`--no-x`) entries are excluded so `--n` cannot silently negate.
  */
-function tryInferLongArg(flagName, longMap) {
-    const matches = [];
-    for (const [name, entry] of longMap) {
-        if (name.startsWith(flagName) && !entry.negated) {
-            matches.push(entry);
+function inferLongEntry(cmdSpec, name) {
+    let match;
+    for (const [candidate, entry] of cmdSpec.longs) {
+        if (entry.negated || !candidate.startsWith(name)) {
+            continue;
+        }
+        if (match !== undefined) {
+            return undefined;
         }
+        match = entry;
     }
-    return matches.length === 1 ? matches[0] : undefined;
+    return match;
 }
-// ---- Value Delimiter Splitting ----
-/**
- * Split a string value by the delimiter and return as array.
- * Applied after initial parsing for args with valueDelimiter.
- */
-function splitByDelimiter(value, delimiter) {
-    if (Array.isArray(value)) {
-        const result = [];
-        for (const v of value) {
-            result.push(...v.split(delimiter));
-        }
-        return result;
+/** Build the name and flag lookup maps, once, on the first token that needs them. */
+function buildSubcommandMaps(cmdSpec) {
+    const names = new Map();
+    const flags = new Map();
+    const subs = subCommandsOf(cmdSpec.command);
+    for (const name of Object.keys(subs)) {
+        names.set(name, name);
+        const subMeta = subs[name].meta;
+        for (const alias of [...(subMeta.aliases ?? []), ...(subMeta.hiddenAliases ?? [])]) {
+            names.set(alias, name);
+        }
+        for (const form of [
+            ...(subMeta.shortFlag === undefined ? [] : [subMeta.shortFlag]),
+            ...(subMeta.shortFlagAliases ?? []),
+            ...(subMeta.visibleShortFlagAliases ?? []),
+        ]) {
+            flags.set(`-${form}`, name);
+        }
+        for (const form of [
+            ...(subMeta.longFlag === undefined ? [] : [subMeta.longFlag]),
+            ...(subMeta.longFlagAliases ?? []),
+            ...(subMeta.visibleLongFlagAliases ?? []),
+        ]) {
+            flags.set(`--${form}`, name);
+        }
+    }
+    cmdSpec.subcommands = names;
+    cmdSpec.subcommandFlags = flags;
+}
+/** The subcommand named by a flag form like `-S`, or undefined. */
+function subcommandForFlag(cmdSpec, token) {
+    if (!cmdSpec.anySubcommands) {
+        return undefined;
     }
-    return value.split(delimiter);
+    if (cmdSpec.subcommandFlags === undefined) {
+        buildSubcommandMaps(cmdSpec);
+    }
+    return cmdSpec.subcommandFlags.get(token);
 }
-// ---- Main Parser ----
 /**
- * Parse raw argument tokens against a command definition.
- *
- * Uses node:util parseArgs for core tokenizing, then layers on all clap-ts features.
+ * Resolve a bare token to a canonical subcommand name, by exact match on the
+ * name or an alias, then by unique prefix when inferSubcommands is on.
  */
-export function parseArgs(rawArgs, command) {
-    const argsDef = command.args ?? {};
-    const inferLong = command.meta.inferLongArgs === true;
-    // Build parseArgs config from our ArgDef definitions
-    const { options, optionalValueFlags } = buildParseArgsOptions(argsDef);
-    // Build flag maps once and reuse throughout parsing
-    const { longMap, shortMap, hasHyphenOrNegative } = buildFlagMaps(argsDef);
-    // Pre-process: handle optional-value flags, allowHyphenValues, allowNegativeNumbers
-    const { processedArgs, optionalDefaults } = preprocessArgs(rawArgs, optionalValueFlags, longMap, shortMap, hasHyphenOrNegative);
-    // Run node:util parseArgs (strict: false so unknown flags don't throw)
-    let parsed;
-    try {
-        parsed = nodeParseArgs({
-            args: processedArgs,
-            options,
-            allowPositionals: true,
-            strict: false,
-        });
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        throw new CliParseError(msg);
-    }
-    const { values, positionals: rawPositionals } = parsed;
-    const result = {};
-    const unknown = [];
-    const explicitlySet = new Set();
-    // Extract help/version and detect short vs long help
-    const helpRequested = values['help'] === true;
-    const helpIsShort = helpRequested && rawArgs.some((a) => a === '-h');
-    const versionRequested = values['version'] === true;
-    // Process each parsed value back through our ArgDef system
-    for (const [parsedKey, rawValue] of Object.entries(values)) {
-        if (parsedKey === 'help' || parsedKey === 'version') {
+function resolveSubcommand(cmdSpec, token) {
+    if (!cmdSpec.anySubcommands) {
+        return undefined;
+    }
+    if (cmdSpec.subcommands === undefined) {
+        buildSubcommandMaps(cmdSpec);
+    }
+    const map = cmdSpec.subcommands;
+    const exact = map.get(token);
+    if (exact !== undefined) {
+        return exact;
+    }
+    if (!cmdSpec.inferSubcommands) {
+        return undefined;
+    }
+    let match;
+    for (const [candidate, canonical] of map) {
+        if (!candidate.startsWith(token)) {
             continue;
         }
-        // Handle --no-<flag> negation
-        if (parsedKey.startsWith('no-') && rawValue === true) {
-            const positiveName = parsedKey.slice(3);
-            const entry = longMap.get(positiveName);
-            if (entry && entry.def.type === 'boolean') {
-                result[entry.key] = false;
-                explicitlySet.add(entry.key);
-                continue;
+        if (match !== undefined && match !== canonical) {
+            return undefined;
+        }
+        match = canonical;
+    }
+    return match;
+}
+/** Handle a `--long`, `--long=value` or `--no-long` token. Returns the last index consumed. */
+function handleLong(token, argv, i, cmdSpec, state) {
+    const eq = token.indexOf('=');
+    const name = eq === -1 ? token.slice(2) : token.slice(2, eq);
+    let entry = cmdSpec.longs.get(name);
+    if (entry === undefined && cmdSpec.inferLong) {
+        entry = inferLongEntry(cmdSpec, name);
+    }
+    if (entry === undefined) {
+        // Only now is it worth building the subcommand maps: an unrecognised flag
+        // may still be a flag-invoked subcommand like `pacman --sync`.
+        const flagSub = subcommandForFlag(cmdSpec, token);
+        if (flagSub !== undefined) {
+            state.subCommand = flagSub;
+            state.subCommandArgs = argv.slice(i + 1);
+            return i;
+        }
+        state.unknown.push(`--${name}`);
+        return i;
+    }
+    const { spec, negated } = entry;
+    if (eq !== -1) {
+        const inline = token.slice(eq + 1);
+        if (spec.builtin !== undefined || spec.isCount) {
+            applyFlagOnly(spec, negated, state);
+            return i;
+        }
+        if (spec.isBool && negated) {
+            // `--no-verbose=true` means "negate", so invert whatever was supplied.
+            state.result[spec.key] = coerceValue(inline, spec.def, `--${name}`) === false;
+            markSet(state, spec.key, spec);
+            return i;
+        }
+        applyValues(spec, [inline], state);
+        return i;
+    }
+    if (spec.max === 0) {
+        applyFlagOnly(spec, negated, state);
+        return i;
+    }
+    if (spec.def.requireEquals) {
+        if (spec.min === 0) {
+            applyMissingValue(spec, state);
+            return i;
+        }
+        throw new CliParseError(`equal sign is needed when assigning values to '${displayName(spec)}'`);
+    }
+    return consumeValues(spec, argv, i + 1, cmdSpec, state);
+}
+/** Handle a `-abc`, `-p80`, `-p=80` or `-p 80` token. Returns the last index consumed. */
+function handleShort(token, argv, i, cmdSpec, state) {
+    for (let c = 1; c < token.length; c++) {
+        const flag = token[c];
+        const spec = cmdSpec.shorts.get(flag);
+        if (spec === undefined) {
+            const flagSub = subcommandForFlag(cmdSpec, token);
+            if (flagSub !== undefined) {
+                state.subCommand = flagSub;
+                state.subCommandArgs = argv.slice(i + 1);
+                return i;
             }
+            state.unknown.push(`-${flag}`);
+            return i;
         }
-        // Look up canonical key via long map
-        const entry = longMap.get(parsedKey);
-        if (entry) {
-            applyValue(entry.key, entry.def, rawValue, result, explicitlySet);
+        if (spec.builtin === 'help') {
+            state.helpRequested = true;
+            state.helpIsShort = true;
             continue;
         }
-        // Check short map
-        const shortEntry = shortMap.get(parsedKey);
-        if (shortEntry) {
-            applyValue(shortEntry.key, shortEntry.def, rawValue, result, explicitlySet);
+        if (spec.builtin === 'version') {
+            state.versionRequested = true;
+            state.versionIsShort = true;
             continue;
         }
-        // inferLongArgs: try prefix matching on unknown long flags
-        if (inferLong) {
-            const inferred = tryInferLongArg(parsedKey, longMap);
-            if (inferred) {
-                applyValue(inferred.key, inferred.def, rawValue, result, explicitlySet);
-                continue;
+        if (spec.max === 0) {
+            applyFlagOnly(spec, false, state);
+            continue;
+        }
+        // A value-taking short flag takes the rest of the cluster, or the next token.
+        if (c + 1 < token.length) {
+            // clap strips a single leading '=' so `-o=v` and `-ov` agree.
+            const attached = token.charCodeAt(c + 1) === 61 ? token.slice(c + 2) : token.slice(c + 1);
+            applyValues(spec, [attached], state);
+            return i;
+        }
+        if (spec.def.requireEquals) {
+            if (spec.min === 0) {
+                applyMissingValue(spec, state);
+                return i;
             }
+            throw new CliParseError(`equal sign is needed when assigning values to '${displayName(spec)}'`);
         }
-        unknown.push(`--${parsedKey}`);
+        return consumeValues(spec, argv, i + 1, cmdSpec, state);
     }
-    // Apply optional-value defaults from pre-scan
-    for (const [key, defaultVal] of optionalDefaults) {
-        if (!explicitlySet.has(key)) {
-            result[key] = defaultVal;
-            explicitlySet.add(key);
+    return i;
+}
+/**
+ * Consume one token: a flag-invoked subcommand, a long or short flag, a
+ * subcommand boundary, or a positional. Returns the last index consumed.
+ */
+function handleToken(token, rawArgs, i, cmdSpec, state) {
+    if (token.length > 1 && token.charCodeAt(0) === HYPHEN) {
+        if (token.charCodeAt(1) === HYPHEN) {
+            return handleLong(token, rawArgs, i, cmdSpec, state);
+        }
+        // A negative number is a value, not a flag cluster, when nothing claims the
+        // leading digit as a short flag.
+        const isNegativeValue = cmdSpec.allowsNegative && NEGATIVE_NUMBER.test(token) && !cmdSpec.shorts.has(token[1]);
+        if (!isNegativeValue) {
+            return handleShort(token, rawArgs, i, cmdSpec, state);
+        }
+    }
+    if (state.positionals.length === 0) {
+        const canonical = resolveSubcommand(cmdSpec, token);
+        if (canonical !== undefined) {
+            state.subCommand = canonical;
+            state.subCommandArgs = rawArgs.slice(i + 1);
+            return i;
+        }
+        if (cmdSpec.allowExternal) {
+            state.subCommand = token;
+            state.subCommandIsExternal = true;
+            state.subCommandArgs = rawArgs.slice(i + 1);
+            return i;
+        }
+    }
+    state.positionals.push(token);
+    return i;
+}
+// ---- Positional Assignment ----
+function assignPositionals(cmdSpec, state) {
+    let index = 0;
+    // Definitions still waiting for a value, so a leading optional one can be
+    // skipped when there are not enough values to go round.
+    let remainingDefs = cmdSpec.indexedPositionals;
+    for (const spec of cmdSpec.positionals) {
+        if (!spec.def.last) {
+            remainingDefs--;
+            if (cmdSpec.allowMissingPositional &&
+                !spec.def.required &&
+                state.positionals.length - index <= remainingDefs) {
+                continue;
+            }
         }
-    }
-    // Split positionals from rest (tokens after --)
-    const { positionals: allPositionals, rest } = splitPositionalsAndRest(rawArgs, rawPositionals);
-    // Detect subcommand in positionals
-    const subCmdResult = detectSubcommand(allPositionals, command);
-    const subCommand = subCmdResult?.name;
-    // Remove subcommand token from positionals
-    const positionals = [];
-    for (let i = 0; i < allPositionals.length; i++) {
-        if (subCmdResult && i === subCmdResult.index) {
+        if (spec.def.last) {
+            // `last` positionals are only fed from tokens after `--`.
+            if (state.rest.length > 0) {
+                state.result[spec.key] = state.rest[0];
+                state.fromRest.add(spec.key);
+                markSet(state, spec.key, spec);
+            }
             continue;
         }
-        positionals.push(allPositionals[i]);
-    }
-    // Assign positionals to positional arg defs
-    const positionalDefs = [];
-    for (const [key, def] of Object.entries(argsDef)) {
-        if (def.type === 'positional') {
-            positionalDefs.push({ key, def });
+        if (spec.def.trailingVarArg) {
+            if (index < state.positionals.length) {
+                state.result[spec.key] = state.positionals.slice(index);
+                markSet(state, spec.key, spec);
+                index = state.positionals.length;
+            }
+            return;
+        }
+        if (index >= state.positionals.length) {
+            continue;
         }
+        if (spec.max > 1) {
+            const take = Math.min(spec.max, state.positionals.length - index);
+            const values = state.positionals.slice(index, index + take);
+            state.result[spec.key] = values.map((v) => String(coerceValue(v, spec.def, spec.key)));
+            markSet(state, spec.key, spec);
+            index += take;
+            continue;
+        }
+        state.result[spec.key] = coerceValue(state.positionals[index], spec.def, spec.key);
+        markSet(state, spec.key, spec);
+        index++;
     }
-    for (let p = 0; p < positionalDefs.length; p++) {
-        const { key, def } = positionalDefs[p];
-        // last: this positional only gets values from rest (after --)
-        if (def.last) {
-            if (rest.length > 0) {
-                result[key] = rest[0];
-                explicitlySet.add(key);
-            }
+}
+// ---- Overrides ----
+/**
+ * Drop args displaced by a later `overridesWith`. Only command-line
+ * occurrences take part, so an env or default value is never overridden.
+ */
+function applyOverrides(cmdSpec, state) {
+    const order = state.order;
+    if (order === undefined) {
+        return;
+    }
+    for (const spec of cmdSpec.all) {
+        const targets = spec.def.overridesWith;
+        if (targets === undefined || !state.explicitlySet.has(spec.key)) {
             continue;
         }
-        // trailingVarArg: consume all remaining positionals as an array
-        if (def.trailingVarArg) {
-            if (p < positionals.length) {
-                result[key] = positionals.slice(p);
-                explicitlySet.add(key);
+        const mine = order.get(spec.key);
+        if (mine === undefined) {
+            continue;
+        }
+        for (const target of targets) {
+            if (target === spec.key) {
+                continue;
+            }
+            const theirs = order.get(target);
+            if (theirs === undefined || theirs > mine) {
+                continue;
             }
-            break; // no more positional defs to process
+            delete state.result[target];
+            state.explicitlySet.delete(target);
+            order.delete(target);
+        }
+    }
+}
+/**
+ * Copy each deprecated arg's value to the arg that replaced it, unless that one
+ * was given directly. Lets a rename keep working without the handler caring.
+ */
+function applyReplacements(cmdSpec, state) {
+    for (const spec of cmdSpec.all) {
+        const target = spec.def.replacedBy;
+        if (target === undefined || !state.explicitlySet.has(spec.key)) {
+            continue;
+        }
+        if (state.explicitlySet.has(target) || !(target in cmdSpec.byKey)) {
+            continue;
         }
-        // Normal positional assignment
-        if (p < positionals.length) {
-            result[key] = coerceValue(positionals[p], def, key);
-            explicitlySet.add(key);
+        const value = state.result[spec.key];
+        if (value === undefined) {
+            continue;
         }
+        state.result[target] = value;
+        state.explicitlySet.add(target);
+        state.valueSources.set(target, state.valueSources.get(spec.key) ?? 'cli');
     }
-    // Single pass: valueDelimiter splitting, env fallback, conditional defaults, static defaults
-    const argsDefEntries = Object.entries(argsDef);
-    for (let a = 0; a < argsDefEntries.length; a++) {
-        const [key, def] = argsDefEntries[a];
+}
+// ---- Defaults, Env, Delimiters ----
+function splitByDelimiter(value, delimiter) {
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const v of value) {
+            out.push(...v.split(delimiter));
+        }
+        return out;
+    }
+    return value.split(delimiter);
+}
+function applyFallbacks(cmdSpec, state) {
+    const { result, explicitlySet } = state;
+    for (const spec of cmdSpec.all) {
+        const { key, def } = spec;
         if (explicitlySet.has(key)) {
-            // Apply valueDelimiter splitting for explicitly set args
-            if (def.valueDelimiter) {
+            if (def.valueDelimiter &&
+                !(cmdSpec.dontDelimitTrailingValues && state.fromRest.has(key))) {
                 const value = result[key];
                 if (value !== undefined && (typeof value === 'string' || Array.isArray(value))) {
                     result[key] = splitByDelimiter(value, def.valueDelimiter);
@@ -517,103 +812,136 @@ export function parseArgs(rawArgs, command) {
             }
             continue;
         }
-        // Env var fallback
         if (def.env) {
-            const envValue = globalThis.Bun === undefined
-                ? process.env[def.env]
-                : globalThis.Bun.env[def.env];
+            const envValue = readEnv(def.env);
             if (envValue !== undefined && envValue !== '') {
                 result[key] = def.valueDelimiter
                     ? envValue.split(def.valueDelimiter)
                     : coerceValue(envValue, def, `env:${def.env}`);
                 explicitlySet.add(key);
+                state.valueSources.set(key, 'env');
                 continue;
             }
         }
-        // Conditional default (defaultValueIf)
         if (def.defaultValueIf) {
             const [otherKey, otherValue, conditionalDefault] = def.defaultValueIf;
             if (String(result[otherKey]) === String(otherValue)) {
                 result[key] = conditionalDefault;
+                state.valueSources.set(key, 'default');
                 continue;
             }
         }
-        // Static default
-        if (def.default !== undefined) {
-            if (Array.isArray(def.default)) {
-                result[key] = [...def.default];
+        if (def.defaultValueIfs) {
+            let matched = false;
+            for (const [otherKey, otherValue, conditionalDefault] of def.defaultValueIfs) {
+                if (String(result[otherKey]) === String(otherValue)) {
+                    result[key] = conditionalDefault;
+                    state.valueSources.set(key, 'default');
+                    matched = true;
+                    break;
+                }
             }
-            else if (typeof def.default === 'string' ||
-                typeof def.default === 'number' ||
-                typeof def.default === 'boolean') {
-                result[key] = def.default;
+            if (matched) {
+                continue;
             }
         }
-    }
-    // Convert keys to camelCase for the result
-    const camelResult = {};
-    for (const [key, value] of Object.entries(result)) {
-        const camelKey = kebabToCamel(key);
-        camelResult[camelKey] = value;
-        if (key !== camelKey) {
-            camelResult[key] = value;
+        if (def.default !== undefined) {
+            result[key] = Array.isArray(def.default)
+                ? [...def.default]
+                : def.default;
+            state.valueSources.set(key, 'default');
         }
     }
-    return {
-        args: camelResult,
-        positionals,
-        rest,
-        subCommand,
-        helpRequested,
-        helpIsShort,
-        versionRequested,
-        unknown,
-        explicitlySet,
-    };
 }
-// ---- Value Application Helper ----
+// ---- Main Parser ----
 /**
- * Apply a raw value from parseArgs into the result, handling count, append,
- * number coercion, boolean conversion, and function valueParser.
+ * Parse raw argument tokens against a command definition.
+ *
+ * Stops at the first bare token matching a subcommand name or alias; the
+ * remaining tokens are returned as `subCommandArgs` for the caller to parse
+ * against that subcommand.
  */
-function applyValue(key, def, rawValue, result, explicitlySet) {
-    if (def.action === 'count') {
-        if (Array.isArray(rawValue)) {
-            result[key] = rawValue.length;
+export function parseArgs(rawArgs, command) {
+    const cmdSpec = getSpec(command);
+    const state = {
+        result: {},
+        explicitlySet: new Set(),
+        valueSources: new Map(),
+        errors: [],
+        warnings: [],
+        warned: new Set(),
+        fromRest: new Set(),
+        order: cmdSpec.hasOverrides ? new Map() : undefined,
+        seq: 0,
+        unknown: [],
+        positionals: [],
+        rest: [],
+        helpRequested: false,
+        helpIsShort: false,
+        versionRequested: false,
+        versionIsShort: false,
+        subCommandIsExternal: false,
+        subCommandArgs: [],
+    };
+    let i = 0;
+    for (; i < rawArgs.length; i++) {
+        const token = rawArgs[i];
+        if (token === '--') {
+            for (let r = i + 1; r < rawArgs.length; r++) {
+                state.rest.push(rawArgs[r]);
+            }
+            break;
+        }
+        // ignoreErrors keeps going after a bad token, collecting the message, the
+        // way clap's Command::ignore_errors does.
+        if (cmdSpec.ignoreErrors) {
+            try {
+                i = handleToken(token, rawArgs, i, cmdSpec, state);
+            }
+            catch (error) {
+                state.errors.push(error instanceof Error ? error.message : String(error));
+            }
         }
         else {
-            result[key] = rawValue === true ? 1 : 0;
+            i = handleToken(token, rawArgs, i, cmdSpec, state);
+        }
+        if (state.subCommand !== undefined) {
+            break;
         }
-        explicitlySet.add(key);
-        return;
-    }
-    if (def.type === 'boolean') {
-        result[key] = rawValue === true;
-        explicitlySet.add(key);
-        return;
     }
-    if (def.action === 'append') {
-        // node:util parseArgs returns string[] for multiple:true string options
-        if (Array.isArray(rawValue)) {
-            result[key] = rawValue;
+    assignPositionals(cmdSpec, state);
+    applyOverrides(cmdSpec, state);
+    applyReplacements(cmdSpec, state);
+    applyFallbacks(cmdSpec, state);
+    // Expose both the declared key and its camelCase form.
+    const args = {};
+    for (const spec of cmdSpec.all) {
+        const value = state.result[spec.key];
+        if (value === undefined) {
+            continue;
         }
-        else if (typeof rawValue === 'string') {
-            result[key] = [rawValue];
+        args[spec.camel] = value;
+        if (spec.key !== spec.camel) {
+            args[spec.key] = value;
         }
-        explicitlySet.add(key);
-        return;
-    }
-    // Single string/number/enum value
-    if (typeof rawValue === 'string') {
-        result[key] = coerceValue(rawValue, def, `--${def.long ?? key}`);
-        explicitlySet.add(key);
-        return;
-    }
-    // Boolean value for a string-typed arg (edge case from parseArgs)
-    if (typeof rawValue === 'boolean' && rawValue) {
-        result[key] = def.defaultMissingValue ?? true;
-        explicitlySet.add(key);
     }
+    return {
+        args,
+        positionals: state.positionals,
+        rest: state.rest,
+        subCommand: state.subCommand,
+        subCommandIsExternal: state.subCommandIsExternal,
+        subCommandArgs: state.subCommandArgs,
+        helpRequested: state.helpRequested,
+        helpIsShort: state.helpIsShort,
+        versionRequested: state.versionRequested,
+        versionIsShort: state.versionIsShort,
+        unknown: state.unknown,
+        errors: state.errors,
+        warnings: state.warnings,
+        explicitlySet: state.explicitlySet,
+        valueSources: state.valueSources,
+    };
 }
 // ---- Global Args ----
 /**