@guanghechen/commander 4.7.1 → 4.7.3

package/lib/esm/browser.mjs

@@ -182,6 +182,140 @@ function kebabToCamelCase(str) {
 function camelToKebabCase(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 normalizeSubcommandNameForDistance(name) {
+    return camelToKebabCase(name).toLowerCase();
+}
+function levenshteinDistance(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left.length === 0) {
+        return right.length;
+    }
+    if (right.length === 0) {
+        return left.length;
+    }
+    let prev = Array.from({ length: right.length + 1 }, (_, i) => i);
+    for (let i = 0; i < left.length; i += 1) {
+        const current = [i + 1];
+        for (let j = 0; j < right.length; j += 1) {
+            const substitutionCost = left[i] === right[j] ? 0 : 1;
+            current[j + 1] = Math.min(current[j] + 1, prev[j + 1] + 1, prev[j] + substitutionCost);
+        }
+        prev = current;
+    }
+    return prev[right.length];
+}
 function tokenizeLongOption(arg, commandPath) {
     const eqIdx = arg.indexOf('=');
     const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
@@ -418,9 +552,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);
@@ -549,16 +687,41 @@ 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(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
-            if (opt.args !== 'none') {
+            if (opt.args === 'optional') {
+                sig += ' [value]';
+            }
+            else if (opt.args !== 'none') {
                 sig += ' <value>';
             }
             let desc = opt.desc;
@@ -566,7 +729,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' &&
@@ -598,6 +761,7 @@ class Command {
         return {
             desc: this.#desc,
             usage,
+            arguments: argumentsLines,
             options,
             commands,
             examples,
@@ -605,25 +769,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('');
         }
@@ -640,25 +808,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('');
         }
@@ -673,16 +845,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 {
@@ -690,6 +887,7 @@ class Command {
             desc: this.#desc,
             aliases: [],
             options,
+            arguments: argumentsMeta,
             subcommands: this.#subcommandsList.map(entry => {
                 const subMeta = entry.command.getCompletionMeta();
                 return {
@@ -1142,6 +1340,14 @@ class Command {
                             consumed.push(tokens[i]);
                         }
                     }
+                    else if (opt.args === 'optional') {
+                        if (!token.resolved.includes('=') &&
+                            i + 1 < tokens.length &&
+                            tokens[i + 1].type === 'none') {
+                            i += 1;
+                            consumed.push(tokens[i]);
+                        }
+                    }
                     else if (opt.args === 'variadic') {
                         if (!token.resolved.includes('=')) {
                             while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
@@ -1167,6 +1373,12 @@ class Command {
                             consumed.push(tokens[i]);
                         }
                     }
+                    else if (opt.args === 'optional') {
+                        if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                            i += 1;
+                            consumed.push(tokens[i]);
+                        }
+                    }
                     else if (opt.args === 'variadic') {
                         while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
                             i += 1;
@@ -1208,6 +1420,7 @@ class Command {
                 leafLocalOpts[opt.long] = leafParsedOpts[opt.long];
             }
         }
+        leafCommand.#assertUnknownSubcommand(ctx.sources.user.argv);
         const rawArgStrings = [...argTokens.map(t => t.original), ...restArgs];
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         const parseCtx = {
@@ -1290,6 +1503,23 @@ class Command {
                 i += 1;
                 continue;
             }
+            if (opt.args === 'optional') {
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    opts[opt.long] = this.#convertValue(opt, token.resolved.slice(eqIdx + 1));
+                    i += 1;
+                    continue;
+                }
+                if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                    opts[opt.long] = this.#convertValue(opt, tokens[i + 1].original);
+                    i += 1;
+                }
+                else {
+                    opts[opt.long] = undefined;
+                }
+                i += 1;
+                continue;
+            }
             if (opt.args === 'variadic') {
                 const values = Array.isArray(opts[opt.long]) ? opts[opt.long] : [];
                 const eqIdx = token.resolved.indexOf('=');
@@ -1309,7 +1539,7 @@ class Command {
             i += 1;
         }
         for (const opt of allOptions) {
-            if (opt.required && opts[opt.long] === undefined) {
+            if (opt.required && !Object.prototype.hasOwnProperty.call(opts, opt.long)) {
                 throw new CommanderError('MissingRequired', `missing required option "--${camelToKebabCase(opt.long)}"`, this.#getCommandPath());
             }
         }
@@ -1335,8 +1565,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(opt.long)}"`, this.#getCommandPath());
             }
             return num;
@@ -1346,12 +1576,37 @@ 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);
+        if (argumentDefs.length === 0 && rawArgs.length > 0) {
+            throw new CommanderError('UnexpectedArgument', `unexpected argument "${rawArgs[0]}"`, this.#getCommandPath());
+        }
+        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;
@@ -1362,41 +1617,101 @@ class Command {
                 index = rawArgs.length;
                 break;
             }
-            const raw = rawArgs[index];
-            if (raw === undefined) {
-                if (def.kind === 'optional') {
+            if (def.kind === 'some') {
+                const rest = rawArgs.slice(index);
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
+            if (def.kind === 'optional') {
+                const raw = rawArgs[index];
+                if (raw === undefined) {
                     args[def.name] = def.default ?? undefined;
                     continue;
                 }
-            }
-            else {
                 args[def.name] = this.#convertArgument(def, raw);
                 index += 1;
+                continue;
             }
+            const raw = rawArgs[index];
+            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 value;
+    }
+    #assertUnknownSubcommand(userTailArgv) {
+        if (this.#subcommandsList.length === 0) {
+            return;
+        }
+        const token = userTailArgv[0];
+        if (token === undefined || token.startsWith('-') || token === 'help') {
+            return;
+        }
+        if (this.#findSubcommandEntry(token) !== undefined) {
+            return;
+        }
+        const hints = [];
+        if (this.#arguments.length === 0) {
+            hints.push(`Hint: command "${this.#getCommandPath()}" does not accept positional arguments.`);
+        }
+        const candidate = this.#resolveDidYouMeanSubcommandName(token);
+        if (candidate !== undefined) {
+            hints.push(`Hint: did you mean "${candidate}"?`);
+        }
+        const details = hints.length > 0 ? `\n${hints.join('\n')}` : '';
+        throw new CommanderError('UnknownSubcommand', `unknown subcommand "${token}" for command "${this.#getCommandPath()}"${details}`, this.#getCommandPath());
+    }
+    #resolveDidYouMeanSubcommandName(token) {
+        const source = normalizeSubcommandNameForDistance(token);
+        let minDistance = Number.POSITIVE_INFINITY;
+        let bestName;
+        let isUniqueBest = false;
+        for (const entry of this.#subcommandsList) {
+            const target = normalizeSubcommandNameForDistance(entry.name);
+            const distance = levenshteinDistance(source, target);
+            if (distance < minDistance) {
+                minDistance = distance;
+                bestName = entry.name;
+                isUniqueBest = true;
+            }
+            else if (distance === minDistance) {
+                isUniqueBest = false;
             }
-            return n;
         }
-        return raw;
+        if (minDistance <= 2 && isUniqueBest) {
+            return bestName;
+        }
+        return undefined;
     }
     #hasUserOption(long) {
         return this.#options.some(option => option.long === long);
@@ -1441,11 +1756,9 @@ class Command {
         return optionPolicyMap;
     }
     #mustGetOptionPolicy(optionPolicyMap, cmd) {
-        const policy = optionPolicyMap.get(cmd);
-        if (policy !== undefined) {
-            return policy;
-        }
-        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
+        const policy = optionPolicyMap.get(cmd) ?? cmd.#resolveOptionPolicy();
+        optionPolicyMap.set(cmd, policy);
+        return policy;
     }
     #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
@@ -1474,7 +1787,10 @@ class Command {
             throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" must have args: 'none'`, this.#getCommandPath());
         }
         if ((opt.type === 'string' || opt.type === 'number') && opt.args === 'none') {
-            throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required' or 'variadic'`, this.#getCommandPath());
+            throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required', 'optional', or 'variadic'`, this.#getCommandPath());
+        }
+        if (opt.type === 'number' && opt.args === 'optional') {
+            throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, this.#getCommandPath());
         }
         if (opt.long.startsWith('no')) {
             throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, this.#getCommandPath());
@@ -1482,12 +1798,18 @@ 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());
         }
         if (opt.type === 'boolean' && opt.required) {
             throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" cannot be required`, this.#getCommandPath());
         }
+        if (opt.required && opt.args !== 'required') {
+            throw new CommanderError('ConfigurationError', `required option "--${opt.long}" must use args: 'required'`, this.#getCommandPath());
+        }
     }
     #checkOptionUniqueness(opt) {
         if (this.#options.some(o => o.long === opt.long)) {
@@ -1498,24 +1820,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.kind === 'variadic') {
-            if (this.#arguments.some(a => a.kind === 'variadic')) {
-                throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', 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' || 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());
             }
         }
     }