@guanghechen/commander 4.7.0 → 4.7.2

package/lib/esm/node.mjs

@@ -195,6 +195,116 @@ function kebabToCamelCase(str) {
 function camelToKebabCase$1(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
+const ANSI_ESCAPE_REGEX = new RegExp(String.raw `\\x1B\\[[0-?]*[ -/]*[@-~]`, 'g');
+const DECIMAL_INTEGER_REGEX = /^\d(?:_?\d)*$/;
+const DECIMAL_FRACTION_REGEX = /^\d(?:_?\d)*$/;
+const DECIMAL_EXPONENT_REGEX = /^[eE][+-]?\d(?:_?\d)*$/;
+const BINARY_LITERAL_REGEX = /^0[bB][01](?:_?[01])*$/;
+const OCTAL_LITERAL_REGEX = /^0[oO][0-7](?:_?[0-7])*$/;
+const HEX_LITERAL_REGEX = /^0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*$/;
+function stripAnsi(value) {
+    return value.replace(ANSI_ESCAPE_REGEX, '');
+}
+function isCombiningMark(codePoint) {
+    return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
+        (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+        (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+        (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+        (codePoint >= 0xfe20 && codePoint <= 0xfe2f));
+}
+function isWideCodePoint(codePoint) {
+    if (codePoint < 0x1100) {
+        return false;
+    }
+    return (codePoint <= 0x115f ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0x3247 && codePoint !== 0x303f) ||
+        (codePoint >= 0x3250 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0xa4c6) ||
+        (codePoint >= 0xa960 && codePoint <= 0xa97c) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6b) ||
+        (codePoint >= 0xff01 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1b000 && codePoint <= 0x1b001) ||
+        (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+}
+function getDisplayWidth(value) {
+    const normalized = stripAnsi(value).normalize('NFC');
+    let width = 0;
+    for (const char of normalized) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint === undefined || isCombiningMark(codePoint)) {
+            continue;
+        }
+        width += isWideCodePoint(codePoint) ? 2 : 1;
+    }
+    return width;
+}
+function padDisplayEnd(value, targetWidth) {
+    const width = getDisplayWidth(value);
+    if (width >= targetWidth) {
+        return value;
+    }
+    return value + ' '.repeat(targetWidth - width);
+}
+function isValidPrimitiveNumberLiteral(rawValue) {
+    if (rawValue.trim() !== rawValue || rawValue.length === 0) {
+        return false;
+    }
+    if (rawValue === 'NaN' || rawValue === 'Infinity' || rawValue === '-Infinity') {
+        return false;
+    }
+    if (BINARY_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    if (OCTAL_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    if (HEX_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    const sign = rawValue[0] === '+' || rawValue[0] === '-' ? rawValue[0] : '';
+    const body = sign ? rawValue.slice(1) : rawValue;
+    if (body.length === 0) {
+        return false;
+    }
+    const expIndex = body.search(/[eE]/);
+    const basePart = expIndex === -1 ? body : body.slice(0, expIndex);
+    const expPart = expIndex === -1 ? '' : body.slice(expIndex);
+    if (expPart && !DECIMAL_EXPONENT_REGEX.test(expPart)) {
+        return false;
+    }
+    if (basePart.includes('.')) {
+        const decimalParts = basePart.split('.');
+        if (decimalParts.length !== 2) {
+            return false;
+        }
+        const [intPart, fracPart] = decimalParts;
+        const intOk = intPart.length === 0 || DECIMAL_INTEGER_REGEX.test(intPart);
+        const fracOk = fracPart.length === 0 || DECIMAL_FRACTION_REGEX.test(fracPart);
+        if (!intOk || !fracOk) {
+            return false;
+        }
+        return intPart.length > 0 || fracPart.length > 0;
+    }
+    return DECIMAL_INTEGER_REGEX.test(basePart);
+}
+function parsePrimitiveNumber(rawValue) {
+    if (!isValidPrimitiveNumberLiteral(rawValue)) {
+        return undefined;
+    }
+    const normalized = rawValue.replaceAll('_', '');
+    const value = Number(normalized);
+    if (!Number.isFinite(value)) {
+        return undefined;
+    }
+    return value;
+}
 function tokenizeLongOption(arg, commandPath) {
     const eqIdx = arg.indexOf('=');
     const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
@@ -431,9 +541,13 @@ class Command {
         if (cmd.#parent && cmd.#parent !== this) {
             throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
         }
+        const occupied = this.#subcommandsMap.get(name);
+        if (occupied && occupied !== cmd) {
+            throw new CommanderError('ConfigurationError', `subcommand name/alias "${name}" conflicts with an existing command`, this.#getCommandPath());
+        }
         const existing = this.#subcommandsList.find(e => e.command === cmd);
         if (existing) {
-            if (existing.aliases.includes(name)) {
+            if (existing.name === name || existing.aliases.includes(name)) {
                 return this;
             }
             existing.aliases.push(name);
@@ -562,10 +676,32 @@ class Command {
             else if (arg.kind === 'optional') {
                 usage += ` [${arg.name}]`;
             }
+            else if (arg.kind === 'some') {
+                usage += ` <${arg.name}...>`;
+            }
             else {
                 usage += ` [${arg.name}...]`;
             }
         }
+        const argumentsLines = [];
+        for (const arg of this.#arguments) {
+            const sig = arg.kind === 'required'
+                ? `<${arg.name}>`
+                : arg.kind === 'optional'
+                    ? `[${arg.name}]`
+                    : arg.kind === 'some'
+                        ? `<${arg.name}...>`
+                        : `[${arg.name}...]`;
+            const metadata = [`[type: ${arg.type}]`];
+            if (arg.kind === 'optional' && arg.default !== undefined) {
+                metadata.push(`[default: ${JSON.stringify(arg.default)}]`);
+            }
+            if (arg.choices && arg.choices.length > 0) {
+                metadata.push(`[choices: ${arg.choices.map(choice => JSON.stringify(choice)).join(', ')}]`);
+            }
+            const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
+            argumentsLines.push({ sig, desc });
+        }
         const options = [];
         for (const opt of allOptions) {
             const kebabLong = camelToKebabCase$1(opt.long);
@@ -579,7 +715,7 @@ class Command {
                 desc += ` (default: ${JSON.stringify(opt.default)})`;
             }
             if (opt.choices) {
-                desc += ` [choices: ${opt.choices.join(', ')}]`;
+                desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
             if (opt.type === 'boolean' &&
@@ -611,6 +747,7 @@ class Command {
         return {
             desc: this.#desc,
             usage,
+            arguments: argumentsLines,
             options,
             commands,
             examples,
@@ -618,25 +755,29 @@ class Command {
     }
     #renderHelpPlain(helpData) {
         const lines = [];
+        const labelWidth = this.#getHelpLabelWidth(helpData);
         lines.push(helpData.desc);
         lines.push('');
         lines.push(helpData.usage);
         lines.push('');
+        if (helpData.arguments.length > 0) {
+            lines.push('Arguments:');
+            for (const { sig, desc } of helpData.arguments) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.options.length > 0) {
             lines.push('Options:');
-            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
             for (const { sig, desc } of helpData.options) {
-                const padding = ' '.repeat(maxSigLen - sig.length + 2);
-                lines.push(`  ${sig}${padding}${desc}`);
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
             }
             lines.push('');
         }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
-            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
             for (const { name, desc } of helpData.commands) {
-                const padding = ' '.repeat(maxNameLen - name.length + 2);
-                lines.push(`  ${name}${padding}${desc}`);
+                lines.push(this.#renderAlignedHelpLine(name, desc, labelWidth));
             }
             lines.push('');
         }
@@ -653,25 +794,29 @@ class Command {
     }
     #renderHelpTerminal(helpData) {
         const lines = [];
+        const labelWidth = this.#getHelpLabelWidth(helpData);
         lines.push(helpData.desc);
         lines.push('');
         lines.push(styleText(helpData.usage, TERMINAL_STYLE.bold));
         lines.push('');
+        if (helpData.arguments.length > 0) {
+            lines.push(styleText('Arguments:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of helpData.arguments) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.options.length > 0) {
             lines.push(styleText('Options:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
-            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
             for (const { sig, desc } of helpData.options) {
-                const padding = ' '.repeat(maxSigLen - sig.length + 2);
-                lines.push(`  ${styleText(sig, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
             }
             lines.push('');
         }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
-            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
             for (const { name, desc } of helpData.commands) {
-                const padding = ' '.repeat(maxNameLen - name.length + 2);
-                lines.push(`  ${styleText(name, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+                lines.push(this.#renderAlignedHelpLine(name, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
             }
             lines.push('');
         }
@@ -686,16 +831,41 @@ class Command {
         }
         return lines.join('\n');
     }
+    #getHelpLabelWidth(helpData) {
+        const labels = [
+            ...helpData.arguments.map(line => line.sig),
+            ...helpData.options.map(line => line.sig),
+            ...helpData.commands.map(line => line.name),
+        ];
+        if (labels.length === 0) {
+            return 0;
+        }
+        return Math.max(...labels.map(getDisplayWidth));
+    }
+    #renderAlignedHelpLine(label, desc, labelWidth, styleLabel) {
+        const paddedLabel = padDisplayEnd(label, labelWidth);
+        const outputLabel = styleLabel ? styleLabel(paddedLabel) : paddedLabel;
+        return `  ${outputLabel}  ${desc}`;
+    }
     getCompletionMeta() {
         const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
+        const argumentsMeta = [];
         for (const opt of allOptions) {
             options.push({
                 long: opt.long,
                 short: opt.short,
                 desc: opt.desc,
                 takesValue: opt.args !== 'none',
-                choices: opt.choices,
+                choices: opt.choices?.map(choice => String(choice)),
+            });
+        }
+        for (const arg of this.#arguments) {
+            argumentsMeta.push({
+                name: arg.name,
+                kind: arg.kind,
+                type: arg.type,
+                choices: arg.type === 'choice' ? arg.choices?.map(choice => String(choice)) : undefined,
             });
         }
         return {
@@ -703,6 +873,7 @@ class Command {
             desc: this.#desc,
             aliases: [],
             options,
+            arguments: argumentsMeta,
             subcommands: this.#subcommandsList.map(entry => {
                 const subMeta = entry.command.getCompletionMeta();
                 return {
@@ -1348,8 +1519,8 @@ class Command {
             return opt.coerce(rawValue);
         }
         if (opt.type === 'number') {
-            const num = Number(rawValue);
-            if (Number.isNaN(num)) {
+            const num = parsePrimitiveNumber(rawValue);
+            if (num === undefined) {
                 throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${camelToKebabCase$1(opt.long)}"`, this.#getCommandPath());
             }
             return num;
@@ -1359,12 +1530,34 @@ class Command {
     #parseArguments(rawArgs) {
         const argumentDefs = this.#arguments;
         const args = {};
-        const requiredCount = argumentDefs.filter(a => a.kind === 'required').length;
-        if (rawArgs.length < requiredCount) {
-            const missing = argumentDefs
-                .filter(a => a.kind === 'required')
-                .slice(rawArgs.length)
-                .map(a => a.name);
+        const missing = [];
+        let remaining = rawArgs.length;
+        for (const def of argumentDefs) {
+            if (def.kind === 'required') {
+                if (remaining === 0) {
+                    missing.push(def.name);
+                }
+                else {
+                    remaining -= 1;
+                }
+                continue;
+            }
+            if (def.kind === 'optional') {
+                if (remaining > 0) {
+                    remaining -= 1;
+                }
+                continue;
+            }
+            if (def.kind === 'some') {
+                if (remaining === 0) {
+                    missing.push(def.name);
+                }
+                remaining = 0;
+                continue;
+            }
+            remaining = 0;
+        }
+        if (missing.length > 0) {
             throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
         }
         let index = 0;
@@ -1375,47 +1568,65 @@ class Command {
                 index = rawArgs.length;
                 break;
             }
+            if (def.kind === 'some') {
+                const rest = rawArgs.slice(index);
+                if (rest.length === 0) {
+                    throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${def.name}`, this.#getCommandPath());
+                }
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
             const raw = rawArgs[index];
             if (raw === undefined) {
                 if (def.kind === 'optional') {
                     args[def.name] = def.default ?? undefined;
                     continue;
                 }
+                throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${def.name}`, this.#getCommandPath());
             }
             else {
                 args[def.name] = this.#convertArgument(def, raw);
                 index += 1;
             }
         }
-        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
-        if (!hasVariadic && index < rawArgs.length) {
+        const hasRestArgument = argumentDefs.some(a => a.kind === 'variadic' || a.kind === 'some');
+        if (!hasRestArgument && index < rawArgs.length) {
             throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
         }
         return { args, rawArgs };
     }
     #convertArgument(def, raw) {
+        let value;
         if (def.coerce) {
             try {
-                return def.coerce(raw);
+                value = def.coerce(raw);
             }
             catch {
                 throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
             }
         }
-        if (def.type === 'number') {
-            const n = Number(raw);
-            if (Number.isNaN(n)) {
-                throw new CommanderError('InvalidType', `invalid number "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+        else {
+            value = raw;
+        }
+        if (typeof value !== 'string') {
+            throw new CommanderError('InvalidType', `invalid value for argument "${def.name}": expected ${def.type}`, this.#getCommandPath());
+        }
+        if (def.type === 'choice') {
+            const choices = def.choices ?? [];
+            if (!choices.includes(value)) {
+                throw new CommanderError('InvalidChoice', `invalid value "${value}" for argument "${def.name}". Allowed: ${choices
+                    .map(choice => JSON.stringify(choice))
+                    .join(', ')}`, this.#getCommandPath());
             }
-            return n;
         }
-        return raw;
+        return value;
     }
     #hasUserOption(long) {
         return this.#options.some(option => option.long === long);
     }
     #supportsBuiltinVersion() {
-        return this.#parent === undefined && this.#version !== undefined && this.#builtin.option.version;
+        return this.#version !== undefined && this.#builtin.option.version;
     }
     #resolveOptionPolicy() {
         const optionMap = new Map();
@@ -1495,6 +1706,9 @@ class Command {
         if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
             throw new CommanderError('ConfigurationError', `option long name must be camelCase: "${opt.long}"`, this.#getCommandPath());
         }
+        if (opt.short !== undefined && opt.short.length !== 1) {
+            throw new CommanderError('ConfigurationError', `option short name must be a single character: "${opt.short}"`, this.#getCommandPath());
+        }
         if (opt.required && opt.default !== undefined) {
             throw new CommanderError('ConfigurationError', `option "--${opt.long}" cannot be both required and have a default value`, this.#getCommandPath());
         }
@@ -1511,24 +1725,58 @@ class Command {
         }
     }
     #validateArgumentConfig(arg) {
-        if (arg.kind === 'required' && arg.default !== undefined) {
-            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot have a default value`, this.#getCommandPath());
+        if (arg.kind !== 'required' &&
+            arg.kind !== 'optional' &&
+            arg.kind !== 'variadic' &&
+            arg.kind !== 'some') {
+            throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid kind`, this.#getCommandPath());
+        }
+        if (arg.type !== 'string' && arg.type !== 'choice') {
+            throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid type`, this.#getCommandPath());
+        }
+        if (arg.default !== undefined && arg.kind !== 'optional') {
+            throw new CommanderError('ConfigurationError', `only optional argument "${arg.name}" can have a default value`, this.#getCommandPath());
+        }
+        if (arg.type === 'string' && arg.choices !== undefined) {
+            throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "string" cannot declare choices`, this.#getCommandPath());
+        }
+        if (arg.type === 'choice') {
+            if (!Array.isArray(arg.choices) || arg.choices.length === 0) {
+                throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "choice" must declare a non-empty choices array`, this.#getCommandPath());
+            }
+            if (arg.choices.some(choice => typeof choice !== 'string')) {
+                throw new CommanderError('ConfigurationError', `argument "${arg.name}" choices must be string[]`, this.#getCommandPath());
+            }
+        }
+        if (arg.default !== undefined) {
+            this.#validateArgumentDefaultValue(arg);
         }
-        if (arg.kind === 'variadic') {
-            if (this.#arguments.some(a => a.kind === 'variadic')) {
-                throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
+        if (arg.kind === 'variadic' || arg.kind === 'some') {
+            if (this.#arguments.some(a => a.kind === 'variadic' || a.kind === 'some')) {
+                throw new CommanderError('ConfigurationError', 'only one variadic/some argument is allowed', this.#getCommandPath());
             }
         }
         if (this.#arguments.length > 0) {
             const last = this.#arguments[this.#arguments.length - 1];
-            if (last.kind === 'variadic') {
-                throw new CommanderError('ConfigurationError', 'variadic argument must be the last argument', this.#getCommandPath());
+            if (last.kind === 'variadic' || last.kind === 'some') {
+                throw new CommanderError('ConfigurationError', 'variadic/some argument must be the last argument', this.#getCommandPath());
             }
         }
         if (arg.kind === 'required') {
-            const hasOptional = this.#arguments.some(a => a.kind === 'optional' || a.kind === 'variadic');
+            const hasOptional = this.#arguments.some(a => a.kind === 'optional' || a.kind === 'variadic' || a.kind === 'some');
             if (hasOptional) {
-                throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot come after optional/variadic arguments`, this.#getCommandPath());
+                throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot come after optional/variadic/some arguments`, this.#getCommandPath());
+            }
+        }
+    }
+    #validateArgumentDefaultValue(arg) {
+        if (typeof arg.default !== 'string') {
+            throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must match type "${arg.type}"`, this.#getCommandPath());
+        }
+        if (arg.type === 'choice') {
+            const choices = arg.choices ?? [];
+            if (!choices.includes(arg.default)) {
+                throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must be one of declared choices`, this.#getCommandPath());
             }
         }
     }
@@ -1885,6 +2133,7 @@ class BashCompletion {
             '',
             `${funcName}() {`,
             '  local cur prev words cword',
+            '  local opts arg_choices prefer_value_choices',
             '  _init_completion || return',
             '',
             ...this.#generateCommandCase(this.#meta, 1),
@@ -1904,13 +2153,15 @@ class BashCompletion {
         for (const opt of cmd.options) {
             const kebabLong = camelToKebabCase(opt.long);
             if (opt.short)
-                optParts.push(`-${opt.short}`);
-            optParts.push(`--${kebabLong}`);
+                optParts.push(this.#escapeWord(`-${opt.short}`));
+            optParts.push(this.#escapeWord(`--${kebabLong}`));
             if (!opt.takesValue) {
-                optParts.push(`--no-${kebabLong}`);
+                optParts.push(this.#escapeWord(`--no-${kebabLong}`));
             }
         }
-        const subParts = cmd.subcommands.flatMap(sub => [sub.name, ...sub.aliases]);
+        const subParts = cmd.subcommands
+            .flatMap(sub => [sub.name, ...sub.aliases])
+            .map(value => this.#escapeWord(value));
         const allOpts = [...optParts, ...subParts].join(' ');
         if (cmd.subcommands.length > 0) {
             lines.push(`${indent}case "\${words[${depth}]}" in`);
@@ -1922,14 +2173,105 @@ class BashCompletion {
             }
             lines.push(`${indent}  *)`);
             lines.push(`${indent}    opts="${allOpts}"`);
+            this.#appendChoiceLogicForCommand(lines, `${indent}    `, cmd, depth);
             lines.push(`${indent}    ;;`);
             lines.push(`${indent}esac`);
         }
         else {
             lines.push(`${indent}opts="${allOpts}"`);
+            this.#appendChoiceLogicForCommand(lines, indent, cmd, depth);
         }
         return lines;
     }
+    #serializeWordList(words) {
+        return words.map(choice => this.#escapeWord(choice)).join(' ');
+    }
+    #appendChoiceLogicForCommand(lines, indent, cmd, depth) {
+        const valueOptions = cmd.options.filter(opt => opt.takesValue);
+        const valueOptionsWithChoices = valueOptions.filter(opt => opt.choices && opt.choices.length > 0);
+        const valueLongPatterns = valueOptions.map(opt => `--${camelToKebabCase(opt.long)}`);
+        const valueShortPatterns = valueOptions
+            .map(opt => opt.short)
+            .filter((short) => typeof short === 'string');
+        lines.push(`${indent}prefer_value_choices=0`);
+        if (valueOptionsWithChoices.length > 0) {
+            lines.push(`${indent}if [[ "$cur" != -* ]]; then`);
+            lines.push(`${indent}  case "$prev" in`);
+            for (const opt of valueOptionsWithChoices) {
+                const patterns = [`--${camelToKebabCase(opt.long)}`];
+                if (opt.short) {
+                    patterns.push(`-${opt.short}`);
+                }
+                lines.push(`${indent}    ${patterns.join('|')})`);
+                lines.push(`${indent}      opts="${this.#serializeWordList(opt.choices ?? [])}"`);
+                lines.push(`${indent}      prefer_value_choices=1`);
+                lines.push(`${indent}      ;;`);
+            }
+            lines.push(`${indent}  esac`);
+            lines.push(`${indent}fi`);
+        }
+        lines.push(`${indent}if [[ $prefer_value_choices -eq 0 ]]; then`);
+        lines.push(`${indent}  positional_count=0`);
+        lines.push(`${indent}  expect_value=0`);
+        lines.push(`${indent}  for ((idx=${depth}; idx<cword; idx++)); do`);
+        lines.push(`${indent}    token="\${words[idx]}"`);
+        lines.push(`${indent}    if [[ $expect_value -eq 1 ]]; then`);
+        lines.push(`${indent}      expect_value=0`);
+        lines.push(`${indent}      continue`);
+        lines.push(`${indent}    fi`);
+        lines.push(`${indent}    if [[ "$token" == --* ]]; then`);
+        lines.push(`${indent}      if [[ "$token" == *=* ]]; then`);
+        lines.push(`${indent}        continue`);
+        lines.push(`${indent}      fi`);
+        if (valueLongPatterns.length > 0) {
+            lines.push(`${indent}      case "$token" in`);
+            lines.push(`${indent}        ${valueLongPatterns.join('|')}) expect_value=1 ;;`);
+            lines.push(`${indent}      esac`);
+        }
+        lines.push(`${indent}      continue`);
+        lines.push(`${indent}    fi`);
+        lines.push(`${indent}    if [[ "$token" == -* && "$token" != "-" ]]; then`);
+        lines.push(`${indent}      if [[ \${#token} -eq 2 ]]; then`);
+        if (valueShortPatterns.length > 0) {
+            lines.push(`${indent}        case "\${token:1:1}" in`);
+            lines.push(`${indent}          ${valueShortPatterns.join('|')}) expect_value=1 ;;`);
+            lines.push(`${indent}        esac`);
+        }
+        lines.push(`${indent}      fi`);
+        lines.push(`${indent}      continue`);
+        lines.push(`${indent}    fi`);
+        lines.push(`${indent}    positional_count=$((positional_count + 1))`);
+        lines.push(`${indent}  done`);
+        lines.push(`${indent}  if [[ $expect_value -eq 1 ]]; then`);
+        lines.push(`${indent}    opts=""`);
+        lines.push(`${indent}    prefer_value_choices=1`);
+        lines.push(`${indent}  elif [[ "$cur" != -* ]]; then`);
+        lines.push(`${indent}    arg_slot=-1`);
+        lines.push(`${indent}    arg_count=${cmd.arguments.length}`);
+        const hasRestArgument = cmd.arguments.length > 0 &&
+            (cmd.arguments[cmd.arguments.length - 1].kind === 'variadic' ||
+                cmd.arguments[cmd.arguments.length - 1].kind === 'some');
+        lines.push(`${indent}    has_rest=${hasRestArgument ? 1 : 0}`);
+        lines.push(`${indent}    if [[ $has_rest -eq 1 && $positional_count -ge $((arg_count - 1)) ]]; then`);
+        lines.push(`${indent}      arg_slot=$((arg_count - 1))`);
+        lines.push(`${indent}    elif [[ $positional_count -lt $arg_count ]]; then`);
+        lines.push(`${indent}      arg_slot=$positional_count`);
+        lines.push(`${indent}    fi`);
+        lines.push(`${indent}    case "$arg_slot" in`);
+        for (let index = 0; index < cmd.arguments.length; index += 1) {
+            const arg = cmd.arguments[index];
+            if (arg.type !== 'choice' || !arg.choices || arg.choices.length === 0) {
+                continue;
+            }
+            lines.push(`${indent}      ${index}) opts="${this.#serializeWordList(arg.choices)}" ;;`);
+        }
+        lines.push(`${indent}    esac`);
+        lines.push(`${indent}  fi`);
+        lines.push(`${indent}fi`);
+    }
+    #escapeWord(word) {
+        return word.replace(/([\\\s'"`$!])/g, '\\$1');
+    }
     #sanitizeName(name) {
         return name.replace(/[^a-zA-Z0-9]/g, '_');
     }
@@ -1937,15 +2279,19 @@ class BashCompletion {
 class FishCompletion {
     #meta;
     #programName;
+    #slotMatcherName;
     constructor(meta, programName) {
         this.#meta = meta;
         this.#programName = programName;
+        this.#slotMatcherName = `__${this.#sanitizeName(programName)}_match_arg_slot`;
     }
     generate() {
         const lines = [
             `# Fish completion for ${this.#programName}`,
             '# Generated by @guanghechen/commander',
             '',
+            ...this.#generateSlotMatcherFunction(),
+            '',
             ...this.#generateCommandCompletions(this.#meta, []),
             '',
         ];
@@ -1965,7 +2311,7 @@ class FishCompletion {
             line += ` -l ${kebabLong}`;
             line += ` -d '${this.#escape(opt.desc)}'`;
             if (opt.choices && opt.choices.length > 0) {
-                line += ` -xa '${opt.choices.join(' ')}'`;
+                line += ` -xa '${opt.choices.map(choice => this.#escapeChoice(choice)).join(' ')}'`;
             }
             lines.push(line);
             if (!opt.takesValue) {
@@ -1977,6 +2323,36 @@ class FishCompletion {
                 lines.push(noLine);
             }
         }
+        const valueOptionLongs = cmd.options
+            .filter(opt => opt.takesValue)
+            .map(opt => camelToKebabCase(opt.long))
+            .join(',');
+        const valueOptionShorts = cmd.options
+            .filter(opt => opt.takesValue && opt.short)
+            .map(opt => opt.short)
+            .join(',');
+        const argCount = cmd.arguments.length;
+        const hasRestArgument = argCount > 0 &&
+            (cmd.arguments[argCount - 1].kind === 'variadic' ||
+                cmd.arguments[argCount - 1].kind === 'some');
+        for (let index = 0; index < cmd.arguments.length; index += 1) {
+            const arg = cmd.arguments[index];
+            if (arg.type !== 'choice' || !arg.choices || arg.choices.length === 0) {
+                continue;
+            }
+            let line = `complete -c ${this.#programName}`;
+            const slotCondition = `${this.#slotMatcherName} ${parentPath.length} ${argCount} ${hasRestArgument ? 1 : 0} ${index} '${valueOptionLongs}' '${valueOptionShorts}'`;
+            if (condition) {
+                line += ` -n '${condition}; and ${slotCondition}'`;
+            }
+            else {
+                line += ` -n '${slotCondition}'`;
+            }
+            line += ` -f`;
+            line += ` -a '${arg.choices.map(choice => this.#escapeChoice(choice)).join(' ')}'`;
+            line += ` -d '${this.#escape(`Argument: ${arg.name}`)}'`;
+            lines.push(line);
+        }
         for (const sub of cmd.subcommands) {
             let line = `complete -c ${this.#programName}`;
             if (isRoot) {
@@ -2000,7 +2376,7 @@ class FishCompletion {
                 aliasLine += ` -d 'Alias for ${sub.name}'`;
                 lines.push(aliasLine);
             }
-            const newPath = [...parentPath, sub.name];
+            const newPath = [...parentPath, [sub.name, ...sub.aliases]];
             lines.push(...this.#generateCommandCompletions(sub, newPath));
         }
         return lines;
@@ -2008,7 +2384,7 @@ class FishCompletion {
     #buildCondition(path) {
         if (path.length === 0)
             return '';
-        return `__fish_seen_subcommand_from ${path[path.length - 1]}`;
+        return path.map(level => `__fish_seen_subcommand_from ${level.join(' ')}`).join('; and ');
     }
     #getSubcommandNames(cmd) {
         return cmd.subcommands.flatMap(sub => [sub.name, ...sub.aliases]);
@@ -2016,6 +2392,68 @@ class FishCompletion {
     #escape(s) {
         return s.replace(/'/g, "\\'");
     }
+    #escapeChoice(s) {
+        return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\s/g, '\\ ');
+    }
+    #sanitizeName(name) {
+        return name.replace(/[^a-zA-Z0-9]/g, '_');
+    }
+    #generateSlotMatcherFunction() {
+        return [
+            `function ${this.#slotMatcherName} --argument-names depth arg_count has_rest target_index long_opts short_opts`,
+            '  set -l tokens (commandline -opc)',
+            '  set -l start (math $depth + 2)',
+            '  set -l positional 0',
+            '  set -l expect_value 0',
+            '  set -l i $start',
+            '  set -l token_count (count $tokens)',
+            '  set -l long_list (string split "," -- $long_opts)',
+            '  set -l short_list (string split "," -- $short_opts)',
+            '  while test $i -le $token_count',
+            '    set -l token $tokens[$i]',
+            '    if test $expect_value -eq 1',
+            '      set expect_value 0',
+            '      set i (math $i + 1)',
+            '      continue',
+            '    end',
+            '    if string match -q -- "--*" $token',
+            '      if string match -q -- "*=*" $token',
+            '        set i (math $i + 1)',
+            '        continue',
+            '      end',
+            '      set -l opt_name (string replace -r "^--" "" -- $token)',
+            '      if contains -- $opt_name $long_list',
+            '        set expect_value 1',
+            '      end',
+            '      set i (math $i + 1)',
+            '      continue',
+            '    end',
+            '    if test "$token" != "-"; and string match -q -- "-*" $token',
+            '      set -l raw_short (string replace -r "^-" "" -- $token)',
+            '      if test (string length -- $raw_short) -eq 1',
+            '        if contains -- $raw_short $short_list',
+            '          set expect_value 1',
+            '        end',
+            '      end',
+            '      set i (math $i + 1)',
+            '      continue',
+            '    end',
+            '    set positional (math $positional + 1)',
+            '    set i (math $i + 1)',
+            '  end',
+            '  if test $expect_value -eq 1',
+            '    return 1',
+            '  end',
+            '  set -l slot -1',
+            '  if test $has_rest -eq 1; and test $positional -ge (math $arg_count - 1)',
+            '    set slot (math $arg_count - 1)',
+            '  else if test $positional -lt $arg_count',
+            '    set slot $positional',
+            '  end',
+            '  test $slot -eq $target_index',
+            'end',
+        ];
+    }
 }
 class PwshCompletion {
     #meta;
@@ -2041,16 +2479,105 @@ class PwshCompletion {
             '',
             '  # Find current command context',
             '  $cmd = $commands',
+            '  $commandDepth = 1',
             '  foreach ($word in $words[1..($words.Count - 1)]) {',
             '    if ($word.StartsWith("-")) { continue }',
             '    if ($cmd.subcommands -and $cmd.subcommands.ContainsKey($word)) {',
             '      $cmd = $cmd.subcommands[$word]',
+            '      $commandDepth += 1',
             '    }',
             '  }',
             '',
             '  # Generate completions',
             '  $completions = @()',
             '',
+            '  # Option value slot (always higher priority than arguments)',
+            '  $previous = if ($words.Count -ge 2) { $words[$words.Count - 2] } else { $null }',
+            '  if ($previous) {',
+            '    foreach ($opt in $cmd.options) {',
+            '      $isLong = $previous -eq "--$($opt.long)"',
+            '      $isShort = $opt.short -and $previous -eq "-$($opt.short)"',
+            '      if ($isLong -or $isShort) {',
+            '        if ($opt.choices) {',
+            '          foreach ($choice in $opt.choices) {',
+            '            if ($choice -like "$current*") {',
+            '              $completions += [System.Management.Automation.CompletionResult]::new(',
+            '                $choice,',
+            '                $choice,',
+            '                "ParameterValue",',
+            '                $choice',
+            '              )',
+            '            }',
+            '          }',
+            '        }',
+            '        return $completions',
+            '      }',
+            '    }',
+            '  }',
+            '',
+            '  # Determine argument slot',
+            '  $positionalCount = 0',
+            '  $expectValue = $false',
+            '  for ($i = $commandDepth; $i -lt ($words.Count - 1); $i += 1) {',
+            '    $token = $words[$i]',
+            '    if ($expectValue) {',
+            '      $expectValue = $false',
+            '      continue',
+            '    }',
+            '    if ($token.StartsWith("--")) {',
+            '      if ($token.Contains("=")) { continue }',
+            '      foreach ($opt in $cmd.options) {',
+            '        if ($token -eq "--$($opt.long)" -and $opt.takesValue) {',
+            '          $expectValue = $true',
+            '          break',
+            '        }',
+            '      }',
+            '      continue',
+            '    }',
+            '    if ($token.StartsWith("-") -and $token -ne "-") {',
+            '      if ($token.Length -eq 2) {',
+            '        foreach ($opt in $cmd.options) {',
+            '          if ($opt.short -and $token -eq "-$($opt.short)" -and $opt.takesValue) {',
+            '            $expectValue = $true',
+            '            break',
+            '          }',
+            '        }',
+            '      }',
+            '      continue',
+            '    }',
+            '    $positionalCount += 1',
+            '  }',
+            '  if ($expectValue) {',
+            '    return $completions',
+            '  }',
+            '  if (-not $current.StartsWith("-") -and $cmd.arguments -and $cmd.arguments.Count -gt 0) {',
+            '    $argSlot = -1',
+            '    $argCount = $cmd.arguments.Count',
+            '    $lastArg = $cmd.arguments[$argCount - 1]',
+            '    $hasRest = $lastArg.kind -eq "variadic" -or $lastArg.kind -eq "some"',
+            '    if ($hasRest -and $positionalCount -ge ($argCount - 1)) {',
+            '      $argSlot = $argCount - 1',
+            '    } elseif ($positionalCount -lt $argCount) {',
+            '      $argSlot = $positionalCount',
+            '    }',
+            '    if ($argSlot -ge 0) {',
+            '      $argMeta = $cmd.arguments[$argSlot]',
+            '      if ($argMeta.choices) {',
+            '        foreach ($choice in $argMeta.choices) {',
+            '          if ($choice -like "$current*") {',
+            '            $completions += [System.Management.Automation.CompletionResult]::new(',
+            '              $choice,',
+            '              $choice,',
+            '              "ParameterValue",',
+            '              $choice',
+            '            )',
+            '          }',
+            '        }',
+            '        return $completions',
+            '      }',
+            '    }',
+            '  }',
+            '',
             '  # Options',
             '  if ($current.StartsWith("-")) {',
             '    foreach ($opt in $cmd.options) {',
@@ -2059,7 +2586,7 @@ class PwshCompletion {
             '          "--$($opt.long)",',
             '          $opt.long,',
             '          "ParameterName",',
-            '          $opt.desc',
+            '          $opt.description',
             '        )',
             '      }',
             '      if ($opt.isBoolean -and "--no-$($opt.long)" -like "$current*") {',
@@ -2067,7 +2594,7 @@ class PwshCompletion {
             '          "--no-$($opt.long)",',
             '          "no-$($opt.long)",',
             '          "ParameterName",',
-            '          $opt.desc',
+            '          $opt.description',
             '        )',
             '      }',
             '      if ($opt.short -and "-$($opt.short)" -like "$current*") {',
@@ -2075,7 +2602,7 @@ class PwshCompletion {
             '          "-$($opt.short)",',
             '          $opt.short,',
             '          "ParameterName",',
-            '          $opt.desc',
+            '          $opt.description',
             '        )',
             '      }',
             '    }',
@@ -2089,7 +2616,7 @@ class PwshCompletion {
             '          $sub,',
             '          $sub,',
             '          "Command",',
-            '          $cmd.subcommands[$sub].desc',
+            '          $cmd.subcommands[$sub].description',
             '        )',
             '      }',
             '    }',
@@ -2113,8 +2640,25 @@ class PwshCompletion {
             lines.push(`${indent}    long = '${kebabLong}'`);
             lines.push(`${indent}    description = '${this.#escape(opt.desc)}'`);
             lines.push(`${indent}    isBoolean = $${!opt.takesValue}`);
+            lines.push(`${indent}    takesValue = $${opt.takesValue}`);
             if (opt.choices) {
-                lines.push(`${indent}    choices = @('${opt.choices.join("', '")}')`);
+                lines.push(`${indent}    choices = @('${opt.choices
+                    .map(choice => this.#escape(choice))
+                    .join("', '")}')`);
+            }
+            lines.push(`${indent}  }`);
+        }
+        lines.push(`${indent})`);
+        lines.push(`${indent}arguments = @(`);
+        for (const arg of cmd.arguments) {
+            lines.push(`${indent}  @{`);
+            lines.push(`${indent}    name = '${this.#escape(arg.name)}'`);
+            lines.push(`${indent}    kind = '${arg.kind}'`);
+            lines.push(`${indent}    type = '${arg.type}'`);
+            if (arg.choices && arg.choices.length > 0) {
+                lines.push(`${indent}    choices = @('${arg.choices
+                    .map(choice => this.#escape(choice))
+                    .join("', '")}')`);
             }
             lines.push(`${indent}  }`);
         }