@guanghechen/commander 3.3.0 → 4.0.0

package/lib/esm/index.mjs

@@ -29,41 +29,131 @@ class DefaultReporter {
         console.error(message, ...args);
     }
 }
+const LONG_OPTION_REGEX = /^--[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const NEGATIVE_OPTION_REGEX = /^--no-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function kebabToCamelCase(str) {
+    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelToKebabCase$1(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+function tokenizeLongOption(arg, commandPath) {
+    const eqIdx = arg.indexOf('=');
+    const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
+    const valuePart = eqIdx !== -1 ? arg.slice(eqIdx) : '';
+    if (namePart.includes('_')) {
+        throw new CommanderError('InvalidOptionFormat', `invalid option "${arg}": use '-' instead of '_'`, commandPath);
+    }
+    const lowerName = namePart.toLowerCase();
+    if (lowerName === '--no' || lowerName === '--no-') {
+        throw new CommanderError('InvalidNegativeOption', `invalid negative option syntax "${arg}"`, commandPath);
+    }
+    if (lowerName.startsWith('--no-')) {
+        if (valuePart !== '') {
+            throw new CommanderError('NegativeOptionWithValue', `"${namePart}" does not accept a value`, commandPath);
+        }
+        if (!NEGATIVE_OPTION_REGEX.test(lowerName)) {
+            throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
+        }
+        const camelName = kebabToCamelCase(lowerName.slice(5));
+        return {
+            original: arg,
+            resolved: `--${camelName}=false`,
+            name: camelName,
+            type: 'long',
+        };
+    }
+    if (!LONG_OPTION_REGEX.test(lowerName)) {
+        throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
+    }
+    const camelName = kebabToCamelCase(lowerName.slice(2));
+    return {
+        original: arg,
+        resolved: `--${camelName}${valuePart}`,
+        name: camelName,
+        type: 'long',
+    };
+}
+function tokenizeShortOptions(arg, commandPath) {
+    if (arg.includes('=')) {
+        throw new CommanderError('UnsupportedShortSyntax', `"${arg}" is not supported. Use "-${arg[1]} ${arg.slice(3)}" instead`, commandPath);
+    }
+    const flags = arg.slice(1);
+    return flags.split('').map(flag => ({
+        original: `-${flag}`,
+        resolved: `-${flag}`,
+        name: flag,
+        type: 'short',
+    }));
+}
+function tokenize(argv, commandPath) {
+    const optionTokens = [];
+    const restArgs = [];
+    let passThrough = false;
+    for (const arg of argv) {
+        if (arg === '--') {
+            passThrough = true;
+            continue;
+        }
+        if (passThrough) {
+            restArgs.push(arg);
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            optionTokens.push(tokenizeLongOption(arg, commandPath));
+            continue;
+        }
+        if (arg.startsWith('-') && arg.length > 1) {
+            optionTokens.push(...tokenizeShortOptions(arg, commandPath));
+            continue;
+        }
+        optionTokens.push({
+            original: arg,
+            resolved: arg,
+            name: '',
+            type: 'none',
+        });
+    }
+    return { optionTokens, restArgs };
+}
 const BUILTIN_HELP_OPTION = {
     long: 'help',
     short: 'h',
     type: 'boolean',
-    description: 'Show help information',
+    args: 'none',
+    desc: 'Show help information',
 };
 const BUILTIN_VERSION_OPTION = {
     long: 'version',
     short: 'V',
     type: 'boolean',
-    description: 'Show version number',
+    args: 'none',
+    desc: 'Show version number',
 };
 class Command {
     #name;
-    #description;
+    #desc;
     #version;
     #helpSubcommandEnabled;
     #reporter;
     #parent;
     #options = [];
     #arguments = [];
-    #subcommands = [];
-    #action;
+    #subcommandsList = [];
+    #subcommandsMap = new Map();
+    #action = undefined;
     constructor(config) {
         this.#name = config.name ?? '';
-        this.#description = config.description;
+        this.#desc = config.desc;
         this.#version = config.version;
         this.#helpSubcommandEnabled = config.help ?? false;
         this.#reporter = config.reporter;
     }
     get name() {
-        return this.#name;
+        return this.#name || undefined;
     }
     get description() {
-        return this.#description;
+        return this.#desc;
     }
     get version() {
         return this.#version;
@@ -77,6 +167,9 @@ class Command {
     get arguments() {
         return [...this.#arguments];
     }
+    get subcommands() {
+        return new Map(this.#subcommandsMap);
+    }
     option(opt) {
         this.#validateOptionConfig(opt);
         this.#checkOptionUniqueness(opt);
@@ -99,14 +192,16 @@ class Command {
         if (cmd.#parent && cmd.#parent !== this) {
             throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
         }
-        const existing = this.#subcommands.find(e => e.command === cmd);
+        const existing = this.#subcommandsList.find(e => e.command === cmd);
         if (existing) {
             existing.aliases.push(name);
+            this.#subcommandsMap.set(name, cmd);
         }
         else {
             cmd.#name = name;
             cmd.#parent = this;
-            this.#subcommands.push({ name, aliases: [], command: cmd });
+            this.#subcommandsList.push({ name, aliases: [], command: cmd });
+            this.#subcommandsMap.set(name, cmd);
         }
         return this;
     }
@@ -114,52 +209,42 @@ class Command {
         const { argv, envs, reporter } = params;
         try {
             const processedArgv = this.#processHelpSubcommand(argv);
-            const { chain, remaining } = this.#routeChain(processedArgv);
+            const routeResult = this.#route(processedArgv);
+            const { chain, remaining } = routeResult;
             const leafCommand = chain[chain.length - 1];
             const rootCommand = chain[0];
-            const includeRootVersion = chain.length === 1;
-            this.#validateMergedShortOptions(chain, includeRootVersion);
-            const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
-            const leafOptions = leafCommand.#getMergedOptions(leafCommand === rootCommand);
+            const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
+            const { optionTokens, restArgs } = tokenizeResult;
             const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
             const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
-            if (!hasUserHelp && leafCommand.#hasHelpFlag(optionTokens, leafOptions)) {
+            if (!hasUserHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
                 console.log(leafCommand.formatHelp());
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand) {
-                if (leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
-                    console.log(leafCommand.version ?? 'unknown');
+            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
+                if (this.#hasFlag(optionTokens, 'version', 'V')) {
+                    console.log(leafCommand.#version);
                     return;
                 }
             }
-            const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
+            const resolveResult = this.#resolve(chain, optionTokens);
             const ctx = {
                 cmd: leafCommand,
                 envs,
                 reporter: reporter ?? this.#reporter ?? new DefaultReporter(),
                 argv,
             };
-            this.#applyChain(chain, optsMap, ctx);
-            const mergedOpts = this.#mergeOpts(chain, optsMap);
-            const allArgs = [...positionalArgs, ...restArgs];
-            const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
-            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
+            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const actionParams = {
+                ctx: parseResult.ctx,
+                opts: parseResult.opts,
+                args: parseResult.args,
+                rawArgs: parseResult.rawArgs,
+            };
             if (leafCommand.#action) {
-                try {
-                    await leafCommand.#action(actionParams);
-                }
-                catch (err) {
-                    if (err instanceof Error) {
-                        console.error(`Error: ${err.message}`);
-                    }
-                    else {
-                        console.error('Error: action failed');
-                    }
-                    process.exit(1);
-                }
+                await leafCommand.#runAction(actionParams);
             }
-            else if (leafCommand.#subcommands.length > 0) {
+            else if (leafCommand.#subcommandsList.length > 0) {
                 console.log(leafCommand.formatHelp());
             }
             else {
@@ -175,105 +260,33 @@ class Command {
             throw err;
         }
     }
-    parse(argv) {
+    parse(params) {
+        const { argv, envs, reporter } = params;
         const processedArgv = this.#processHelpSubcommand(argv);
-        const { chain, remaining } = this.#routeChain(processedArgv);
+        const routeResult = this.#route(processedArgv);
+        const { chain, remaining } = routeResult;
         const leafCommand = chain[chain.length - 1];
-        const includeRootVersion = chain.length === 1;
-        this.#validateMergedShortOptions(chain, includeRootVersion);
-        const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
-        const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
-        const mergedOpts = this.#mergeOpts(chain, optsMap);
-        const allArgs = [...positionalArgs, ...restArgs];
-        const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
-        return { opts: mergedOpts, args, rawArgs };
-    }
-    shift(tokens) {
-        return this.#shiftWithShadowed(tokens, new Set());
-    }
-    #shiftWithShadowed(tokens, shadowed, includeVersion = !this.#parent) {
-        const allDirectOptions = this.#getMergedOptions(includeVersion);
-        const directOptions = allDirectOptions.filter(o => !shadowed.has(o.long));
-        const opts = {};
-        for (const opt of directOptions) {
-            if (opt.default !== undefined) {
-                opts[opt.long] = opt.default;
-            }
-            else if (opt.type === 'boolean') {
-                opts[opt.long] = false;
-            }
-            else if (opt.type === 'string[]' || opt.type === 'number[]') {
-                opts[opt.long] = [];
-            }
-        }
-        let remaining = [...tokens];
-        const resolverOptions = directOptions.filter(o => o.resolver);
-        for (const opt of resolverOptions) {
-            const result = opt.resolver(remaining);
-            opts[opt.long] = result.value;
-            remaining = result.remaining;
-        }
-        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(directOptions, true);
-        const normalizedTokens = this.#normalizeArgv(remaining, booleanOptions);
-        const finalRemaining = [];
-        let i = 0;
-        while (i < normalizedTokens.length) {
-            const token = normalizedTokens[i];
-            if (token.startsWith('--')) {
-                const consumed = this.#tryConsumeLongOption(normalizedTokens, i, optionByLong, opts);
-                if (consumed > 0) {
-                    i += consumed;
-                    continue;
-                }
-                finalRemaining.push(token);
-                i += 1;
-                continue;
-            }
-            if (token.startsWith('-') && token.length > 1) {
-                const result = this.#tryConsumeShortOption(normalizedTokens, i, optionByShort, opts);
-                if (result.consumed) {
-                    i = result.nextIdx;
-                    if (result.remainingToken) {
-                        finalRemaining.push(result.remainingToken);
-                    }
-                    continue;
-                }
-                finalRemaining.push(token);
-                i += 1;
-                continue;
-            }
-            finalRemaining.push(token);
-            i += 1;
-        }
-        for (const opt of directOptions) {
-            if (opt.required && opts[opt.long] === undefined) {
-                throw new CommanderError('MissingRequired', `missing required option "--${opt.long}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
-            }
-        }
-        for (const opt of directOptions) {
-            if (opt.choices && opts[opt.long] !== undefined) {
-                const value = opts[opt.long];
-                const values = Array.isArray(value) ? value : [value];
-                const choices = opt.choices;
-                for (const v of values) {
-                    if (!choices.includes(v)) {
-                        throw new CommanderError('InvalidChoice', `invalid value "${v}" for option "--${opt.long}". Allowed: ${opt.choices.join(', ')}`, this.#getCommandPath());
-                    }
-                }
-            }
-        }
-        return { opts, remaining: finalRemaining };
+        const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
+        const { optionTokens, restArgs } = tokenizeResult;
+        const resolveResult = this.#resolve(chain, optionTokens);
+        const ctx = {
+            cmd: leafCommand,
+            envs,
+            reporter: reporter ?? this.#reporter ?? new DefaultReporter(),
+            argv,
+        };
+        return this.#parse(chain, resolveResult, ctx, restArgs);
     }
     formatHelp() {
         const lines = [];
         const allOptions = this.#getMergedOptions();
-        lines.push(this.#description);
+        lines.push(this.#desc);
         lines.push('');
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
             usage += ' [options]';
-        if (this.#subcommands.length > 0)
+        if (this.#subcommandsList.length > 0)
             usage += ' [command]';
         for (const arg of this.#arguments) {
             if (arg.kind === 'required') {
@@ -292,24 +305,24 @@ class Command {
             lines.push('Options:');
             const optLines = [];
             for (const opt of allOptions) {
+                const kebabLong = camelToKebabCase$1(opt.long);
                 let sig = opt.short ? `-${opt.short}, ` : '    ';
-                sig += `--${opt.long}`;
-                const effectiveType = opt.type ?? 'string';
-                if (effectiveType !== 'boolean') {
+                sig += `--${kebabLong}`;
+                if (opt.args !== 'none') {
                     sig += ' <value>';
                 }
-                let desc = opt.description;
-                if (opt.default !== undefined && effectiveType !== 'boolean') {
+                let desc = opt.desc;
+                if (opt.default !== undefined && opt.type !== 'boolean') {
                     desc += ` (default: ${JSON.stringify(opt.default)})`;
                 }
                 if (opt.choices) {
                     desc += ` [choices: ${opt.choices.join(', ')}]`;
                 }
                 optLines.push({ sig, desc });
-                if (effectiveType === 'boolean') {
+                if (opt.type === 'boolean' && opt.args === 'none') {
                     optLines.push({
-                        sig: `    --no-${opt.long}`,
-                        desc: `Negate --${opt.long}`,
+                        sig: `    --no-${kebabLong}`,
+                        desc: `Negate --${kebabLong}`,
                     });
                 }
             }
@@ -320,19 +333,19 @@ class Command {
             }
             lines.push('');
         }
-        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommands.length > 0;
-        if (this.#subcommands.length > 0) {
+        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommandsList.length > 0;
+        if (this.#subcommandsList.length > 0) {
             lines.push('Commands:');
             const cmdLines = [];
             if (showHelpSubcommand) {
                 cmdLines.push({ name: 'help', desc: 'Show help for a command' });
             }
-            for (const entry of this.#subcommands) {
+            for (const entry of this.#subcommandsList) {
                 let name = entry.name;
                 if (entry.aliases.length > 0) {
                     name += `, ${entry.aliases.join(', ')}`;
                 }
-                cmdLines.push({ name, desc: entry.command.#description });
+                cmdLines.push({ name, desc: entry.command.#desc });
             }
             const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
             for (const { name, desc } of cmdLines) {
@@ -347,21 +360,20 @@ class Command {
         const allOptions = this.#getMergedOptions();
         const options = [];
         for (const opt of allOptions) {
-            const effectiveType = opt.type ?? 'string';
             options.push({
                 long: opt.long,
                 short: opt.short,
-                description: opt.description,
-                takesValue: effectiveType !== 'boolean',
+                desc: opt.desc,
+                takesValue: opt.args !== 'none',
                 choices: opt.choices,
             });
         }
         return {
             name: this.#name,
-            description: this.#description,
+            desc: this.#desc,
             aliases: [],
             options,
-            subcommands: this.#subcommands.map(entry => {
+            subcommands: this.#subcommandsList.map(entry => {
                 const subMeta = entry.command.getCompletionMeta();
                 return {
                     ...subMeta,
@@ -376,17 +388,17 @@ class Command {
             return argv;
         if (argv.length < 1 || argv[0] !== 'help')
             return argv;
-        if (argv.length === 1 || this.#subcommands.length === 0) {
+        if (argv.length === 1 || this.#subcommandsList.length === 0) {
             return ['--help'];
         }
         const subName = argv[1];
-        const entry = this.#subcommands.find(e => e.name === subName || e.aliases.includes(subName));
+        const entry = this.#subcommandsList.find(e => e.name === subName || e.aliases.includes(subName));
         if (entry) {
             return [subName, '--help', ...argv.slice(2)];
         }
         return argv;
     }
-    #routeChain(argv) {
+    #route(argv) {
         const chain = [this];
         let current = this;
         let idx = 0;
@@ -394,7 +406,7 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            const entry = current.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
             if (!entry)
                 break;
             current = entry.command;
@@ -403,93 +415,299 @@ class Command {
         }
         return { chain, remaining: argv.slice(idx) };
     }
-    #splitAtDoubleDash(tokens) {
-        const ddIdx = tokens.indexOf('--');
-        if (ddIdx === -1) {
-            return { optionTokens: tokens, restArgs: [] };
-        }
-        return {
-            optionTokens: tokens.slice(0, ddIdx),
-            restArgs: tokens.slice(ddIdx + 1),
-        };
-    }
-    #shiftChain(chain, tokens, includeRootVersion) {
-        const optsMap = new Map();
+    #resolve(chain, tokens) {
+        const consumedTokens = new Map();
         let remaining = [...tokens];
-        const rootCommand = chain[0];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const includeVersion = cmd === rootCommand && includeRootVersion;
-            const result = cmd.#shiftWithShadowed(remaining, shadowed, includeVersion);
-            optsMap.set(cmd, result.opts);
+            const includeVersion = i === 0;
+            const result = cmd.#shift(remaining, shadowed, includeVersion);
+            consumedTokens.set(cmd, result.consumed);
             remaining = result.remaining;
             for (const opt of cmd.#options) {
                 shadowed.add(opt.long);
             }
         }
-        const positionalArgs = [];
+        const argTokens = [];
         for (const token of remaining) {
-            if (token.startsWith('-')) {
+            if (token.type !== 'none') {
                 const leafCommand = chain[chain.length - 1];
-                if (!token.startsWith('--') && token.length > 2) {
-                    const flag = token[1];
-                    throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+                throw new CommanderError('UnknownOption', `unknown option "${token.original}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+            }
+            argTokens.push(token);
+        }
+        return { consumedTokens, argTokens };
+    }
+    #shift(tokens, shadowed, includeVersion) {
+        const allOptions = this.#getMergedOptions(includeVersion);
+        const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
+        const optionByLong = new Map();
+        const optionByShort = new Map();
+        for (const opt of effectiveOptions) {
+            optionByLong.set(opt.long, opt);
+            if (opt.short) {
+                optionByShort.set(opt.short, opt);
+            }
+        }
+        const consumed = [];
+        const remaining = [];
+        let i = 0;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            if (token.type === 'long') {
+                const opt = optionByLong.get(token.name);
+                if (opt) {
+                    consumed.push(token);
+                    if (opt.args === 'required') {
+                        if (!token.resolved.includes('=') && i + 1 < tokens.length) {
+                            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') {
+                                i += 1;
+                                consumed.push(tokens[i]);
+                            }
+                        }
+                    }
+                    i += 1;
+                    continue;
+                }
+                remaining.push(token);
+                i += 1;
+                continue;
+            }
+            if (token.type === 'short') {
+                const opt = optionByShort.get(token.name);
+                if (opt) {
+                    consumed.push(token);
+                    if (opt.args === 'required') {
+                        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;
+                            consumed.push(tokens[i]);
+                        }
+                    }
+                    i += 1;
+                    continue;
                 }
-                throw new CommanderError('UnknownOption', `unknown option "${token}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+                remaining.push(token);
+                i += 1;
+                continue;
             }
-            positionalArgs.push(token);
+            remaining.push(token);
+            i += 1;
         }
-        return { optsMap, positionalArgs };
+        return { consumed, remaining };
     }
-    #applyChain(chain, optsMap, ctx) {
-        for (const cmd of chain) {
-            const opts = optsMap.get(cmd) ?? {};
-            for (const opt of cmd.#getMergedOptions()) {
+    #parse(chain, resolveResult, ctx, restArgs) {
+        const { consumedTokens, argTokens } = resolveResult;
+        const leafCommand = chain[chain.length - 1];
+        this.#validateMergedShortOptions(chain);
+        const optsMap = new Map();
+        for (let i = 0; i < chain.length; i++) {
+            const cmd = chain[i];
+            const includeVersion = i === 0;
+            const tokens = consumedTokens.get(cmd) ?? [];
+            const opts = cmd.#parseOptions(tokens, includeVersion);
+            optsMap.set(cmd, opts);
+            for (const opt of cmd.#getMergedOptions(includeVersion)) {
                 if (opt.apply && opts[opt.long] !== undefined) {
                     opt.apply(opts[opt.long], ctx);
                 }
             }
         }
-    }
-    #mergeOpts(chain, optsMap) {
-        const merged = {};
+        const mergedOpts = {};
         for (const cmd of chain) {
-            Object.assign(merged, optsMap.get(cmd) ?? {});
+            Object.assign(mergedOpts, optsMap.get(cmd) ?? {});
         }
-        return merged;
+        const rawArgStrings = [...argTokens.map(t => t.original), ...restArgs];
+        const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
+        return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #applyValue(opt, rawValue, opts) {
-        const type = opt.type ?? 'string';
-        let parsedValue = rawValue;
-        if (opt.coerce) {
-            parsedValue = opt.coerce(rawValue);
+    #parseOptions(tokens, includeVersion) {
+        const allOptions = this.#getMergedOptions(includeVersion);
+        const opts = {};
+        for (const opt of allOptions) {
+            if (opt.default !== undefined) {
+                opts[opt.long] = opt.default;
+            }
+            else if (opt.type === 'boolean' && opt.args === 'none') {
+                opts[opt.long] = false;
+            }
+            else if (opt.args === 'variadic') {
+                opts[opt.long] = [];
+            }
         }
-        else {
-            switch (type) {
-                case 'string':
-                case 'string[]':
-                    parsedValue = rawValue;
-                    break;
-                case 'number':
-                case 'number[]': {
-                    const num = Number(rawValue);
-                    if (Number.isNaN(num)) {
-                        throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${opt.long}"`, this.#getCommandPath());
+        const optionByLong = new Map();
+        const optionByShort = new Map();
+        for (const opt of allOptions) {
+            optionByLong.set(opt.long, opt);
+            if (opt.short) {
+                optionByShort.set(opt.short, opt);
+            }
+        }
+        let i = 0;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            const opt = token.type === 'long' ? optionByLong.get(token.name) : optionByShort.get(token.name);
+            if (!opt) {
+                i += 1;
+                continue;
+            }
+            const isNegativeToken = token.original.toLowerCase().startsWith('--no-');
+            if (isNegativeToken && !(opt.type === 'boolean' && opt.args === 'none')) {
+                throw new CommanderError('NegativeOptionType', `"--no-${camelToKebabCase$1(opt.long)}" can only be used with boolean options`, this.#getCommandPath());
+            }
+            if (opt.type === 'boolean' && opt.args === 'none') {
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    const value = token.resolved.slice(eqIdx + 1);
+                    if (value === 'true') {
+                        opts[opt.long] = true;
                     }
-                    parsedValue = num;
-                    break;
+                    else if (value === 'false') {
+                        opts[opt.long] = false;
+                    }
+                    else {
+                        throw new CommanderError('InvalidBooleanValue', `invalid value "${value}" for boolean option "--${camelToKebabCase$1(opt.long)}". Use "true" or "false"`, this.#getCommandPath());
+                    }
+                }
+                else {
+                    opts[opt.long] = true;
                 }
+                i += 1;
+                continue;
+            }
+            if (opt.args === 'required') {
+                const eqIdx = token.resolved.indexOf('=');
+                let rawValue;
+                if (eqIdx !== -1) {
+                    rawValue = token.resolved.slice(eqIdx + 1);
+                }
+                else if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                    rawValue = tokens[i + 1].original;
+                    i += 1;
+                }
+                else {
+                    throw new CommanderError('MissingValue', `option "--${camelToKebabCase$1(opt.long)}" requires a value`, this.#getCommandPath());
+                }
+                opts[opt.long] = this.#convertValue(opt, rawValue);
+                i += 1;
+                continue;
+            }
+            if (opt.args === 'variadic') {
+                const values = Array.isArray(opts[opt.long]) ? opts[opt.long] : [];
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    values.push(this.#convertValue(opt, token.resolved.slice(eqIdx + 1)));
+                }
+                else {
+                    while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                        i += 1;
+                        values.push(this.#convertValue(opt, tokens[i].original));
+                    }
+                }
+                opts[opt.long] = values;
+                i += 1;
+                continue;
             }
+            i += 1;
         }
-        if (type === 'string[]' || type === 'number[]') {
-            const currentValue = opts[opt.long];
-            const current = Array.isArray(currentValue) ? currentValue : [];
-            opts[opt.long] = [...current, parsedValue];
+        for (const opt of allOptions) {
+            if (opt.required && opts[opt.long] === undefined) {
+                throw new CommanderError('MissingRequired', `missing required option "--${camelToKebabCase$1(opt.long)}"`, this.#getCommandPath());
+            }
         }
-        else {
-            opts[opt.long] = parsedValue;
+        for (const opt of allOptions) {
+            if (opt.choices && opts[opt.long] !== undefined) {
+                const value = opts[opt.long];
+                const values = Array.isArray(value) ? value : [value];
+                const choices = opt.choices;
+                for (const v of values) {
+                    if (!choices.includes(v)) {
+                        throw new CommanderError('InvalidChoice', `invalid value "${v}" for option "--${camelToKebabCase$1(opt.long)}". Allowed: ${opt.choices.join(', ')}`, this.#getCommandPath());
+                    }
+                }
+            }
+        }
+        return opts;
+    }
+    #convertValue(opt, rawValue) {
+        if (opt.coerce) {
+            return opt.coerce(rawValue);
+        }
+        if (opt.type === 'number') {
+            const num = Number(rawValue);
+            if (Number.isNaN(num)) {
+                throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${camelToKebabCase$1(opt.long)}"`, this.#getCommandPath());
+            }
+            return num;
+        }
+        return rawValue;
+    }
+    #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);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        let index = 0;
+        for (const def of argumentDefs) {
+            if (def.kind === 'variadic') {
+                const rest = rawArgs.slice(index);
+                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;
+                }
+            }
+            else {
+                args[def.name] = this.#convertArgument(def, raw);
+                index += 1;
+            }
+        }
+        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
+        if (!hasVariadic && index < rawArgs.length) {
+            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
+        }
+        return { args, rawArgs };
+    }
+    #convertArgument(def, raw) {
+        if (def.coerce) {
+            try {
+                return 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());
+            }
+            return n;
         }
+        return raw;
     }
     #getMergedOptions(includeVersion = !this.#parent) {
         const optionMap = new Map();
@@ -506,11 +724,11 @@ class Command {
         }
         return Array.from(optionMap.values());
     }
-    #validateMergedShortOptions(chain, includeRootVersion) {
+    #validateMergedShortOptions(chain) {
         const mergedByLong = new Map();
-        const rootCommand = chain[0];
-        for (const cmd of chain) {
-            const includeVersion = cmd === rootCommand && includeRootVersion;
+        for (let i = 0; i < chain.length; i++) {
+            const cmd = chain[i];
+            const includeVersion = i === 0;
             for (const opt of cmd.#getMergedOptions(includeVersion)) {
                 mergedByLong.set(opt.long, opt);
             }
@@ -527,8 +745,17 @@ class Command {
         }
     }
     #validateOptionConfig(opt) {
-        if (opt.long.startsWith('no-')) {
-            throw new CommanderError('ConfigurationError', `option long name cannot start with "no-": "${opt.long}"`, this.#getCommandPath());
+        if (opt.type === 'boolean' && opt.args !== 'none') {
+            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());
+        }
+        if (opt.long.startsWith('no')) {
+            throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, this.#getCommandPath());
+        }
+        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.required && opt.default !== undefined) {
             throw new CommanderError('ConfigurationError', `option "--${opt.long}" cannot be both required and have a default value`, this.#getCommandPath());
@@ -567,154 +794,33 @@ 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);
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+    async #runAction(params) {
+        if (!this.#action)
+            return;
+        try {
+            await this.#action(params);
         }
-        let index = 0;
-        for (const def of argumentDefs) {
-            if (def.kind === 'variadic') {
-                const rest = rawArgs.slice(index);
-                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;
-                }
+        catch (err) {
+            if (err instanceof Error) {
+                console.error(`Error: ${err.message}`);
             }
             else {
-                args[def.name] = this.#convertArgument(def, raw);
-                index += 1;
-            }
-        }
-        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
-        if (!hasVariadic && index < rawArgs.length) {
-            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
-        }
-        return { args, rawArgs };
-    }
-    #convertArgument(def, raw) {
-        if (def.coerce) {
-            try {
-                return 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());
-            }
-            return n;
-        }
-        return raw;
-    }
-    #buildOptionMaps(allOptions, excludeResolver = false) {
-        const optionByLong = new Map();
-        const optionByShort = new Map();
-        const booleanOptions = new Set();
-        for (const opt of allOptions) {
-            if (excludeResolver && opt.resolver)
-                continue;
-            optionByLong.set(opt.long, opt);
-            if (opt.short) {
-                optionByShort.set(opt.short, opt);
-            }
-            if (opt.type === 'boolean') {
-                booleanOptions.add(opt.long);
+                console.error('Error: action failed');
             }
+            process.exit(1);
         }
-        return { optionByLong, optionByShort, booleanOptions };
     }
-    #hasHelpFlag(argv, allOptions) {
-        return this.#hasBuiltinFlag(argv, 'help', 'h', allOptions);
-    }
-    #hasVersionFlag(argv, allOptions) {
-        return this.#hasBuiltinFlag(argv, 'version', 'V', allOptions);
-    }
-    #hasBuiltinFlag(argv, flagLong, flagShort, allOptions) {
-        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(allOptions);
-        const normalizedArgv = this.#normalizeArgv(argv, booleanOptions);
-        for (let i = 0; i < normalizedArgv.length; i++) {
-            const arg = normalizedArgv[i];
-            if (arg === '--') {
-                break;
-            }
-            if (arg === `--${flagLong}` || (flagShort && arg === `-${flagShort}`)) {
+    #hasFlag(tokens, longName, shortName) {
+        for (const token of tokens) {
+            if (token.type === 'long' && token.name === longName) {
                 return true;
             }
-            if (this.#optionConsumesNextValue(arg, optionByLong, optionByShort)) {
-                i += 1;
-            }
-        }
-        return false;
-    }
-    #optionConsumesNextValue(arg, optionByLong, optionByShort) {
-        if (arg.startsWith('--')) {
-            const eqIdx = arg.indexOf('=');
-            if (eqIdx !== -1) {
-                return false;
-            }
-            const optName = arg.slice(2);
-            const opt = optionByLong.get(optName);
-            if (!opt) {
-                return false;
-            }
-            const type = opt.type ?? 'string';
-            return type !== 'boolean';
-        }
-        if (arg.startsWith('-') && arg.length === 2) {
-            const opt = optionByShort.get(arg[1]);
-            if (!opt) {
-                return false;
+            if (token.type === 'short' && token.name === shortName) {
+                return true;
             }
-            const type = opt.type ?? 'string';
-            return type !== 'boolean';
         }
         return false;
     }
-    #normalizeArgv(argv, booleanOptions) {
-        const result = [];
-        let seenDoubleDash = false;
-        for (const arg of argv) {
-            if (arg === '--') {
-                seenDoubleDash = true;
-                result.push(arg);
-                continue;
-            }
-            if (!seenDoubleDash && arg.startsWith('--no-')) {
-                const eqIdx = arg.indexOf('=');
-                if (eqIdx !== -1) {
-                    const optName = arg.slice(5, eqIdx);
-                    if (booleanOptions.has(optName)) {
-                        throw new CommanderError('InvalidBooleanValue', `"--no-${optName}" does not accept a value`, this.#getCommandPath());
-                    }
-                }
-                else {
-                    const optName = arg.slice(5);
-                    if (booleanOptions.has(optName)) {
-                        result.push(`--${optName}=false`);
-                        continue;
-                    }
-                }
-            }
-            result.push(arg);
-        }
-        return result;
-    }
     #getCommandPath() {
         const parts = [];
         let current = this;
@@ -726,130 +832,41 @@ class Command {
         }
         return parts.join(' ') || this.#name;
     }
-    #tryConsumeLongOption(tokens, idx, optionByLong, opts) {
-        const token = tokens[idx];
-        const eqIdx = token.indexOf('=');
-        let optName;
-        let inlineValue;
-        if (eqIdx !== -1) {
-            optName = token.slice(2, eqIdx);
-            inlineValue = token.slice(eqIdx + 1);
-        }
-        else {
-            optName = token.slice(2);
-        }
-        const opt = optionByLong.get(optName);
-        if (!opt) {
-            return 0;
-        }
-        if (opt.type === 'boolean') {
-            if (inlineValue !== undefined) {
-                if (inlineValue === 'true') {
-                    opts[optName] = true;
-                }
-                else if (inlineValue === 'false') {
-                    opts[optName] = false;
-                }
-                else {
-                    throw new CommanderError('InvalidBooleanValue', `invalid value "${inlineValue}" for boolean option "--${optName}". Use "true" or "false"`, this.#getCommandPath());
-                }
-            }
-            else {
-                opts[optName] = true;
-            }
-            return 1;
-        }
-        let value;
-        let consumed = 1;
-        if (inlineValue !== undefined) {
-            value = inlineValue;
-        }
-        else if (idx + 1 < tokens.length) {
-            value = tokens[idx + 1];
-            consumed = 2;
-        }
-        else {
-            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
-        }
-        this.#applyValue(opt, value, opts);
-        return consumed;
-    }
-    #tryConsumeShortOption(tokens, idx, optionByShort, opts) {
-        const token = tokens[idx];
-        if (token.includes('=')) {
-            const firstFlag = token[1];
-            if (!optionByShort.has(firstFlag)) {
-                return { consumed: false, nextIdx: idx + 1 };
-            }
-            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
-        }
-        const flags = token.slice(1);
-        let j = 0;
-        const consumedFlags = [];
-        const unconsumedFlags = [];
-        let nextIdx = idx + 1;
-        while (j < flags.length) {
-            const flag = flags[j];
-            const opt = optionByShort.get(flag);
-            if (!opt) {
-                unconsumedFlags.push(...flags.slice(j).split(''));
-                break;
-            }
-            consumedFlags.push(flag);
-            if (opt.type === 'boolean') {
-                opts[opt.long] = true;
-                j += 1;
-                continue;
-            }
-            if (j < flags.length - 1) {
-                throw new CommanderError('UnsupportedShortSyntax', `"-${flags}" is not supported. Use "-${flags.slice(0, j + 1)} ${flags.slice(j + 1)}" or separate options`, this.#getCommandPath());
-            }
-            if (idx + 1 < tokens.length && !tokens[idx + 1].startsWith('-')) {
-                const value = tokens[idx + 1];
-                this.#applyValue(opt, value, opts);
-                nextIdx = idx + 2;
-            }
-            else {
-                throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
-            }
-            j += 1;
-        }
-        if (consumedFlags.length > 0) {
-            const remainingToken = unconsumedFlags.length > 0 ? `-${unconsumedFlags.join('')}` : undefined;
-            return { consumed: true, nextIdx, remainingToken };
-        }
-        return { consumed: false, nextIdx: idx + 1 };
-    }
 }
 
+function camelToKebabCase(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
 class CompletionCommand extends Command {
     constructor(root, config) {
         const paths = config.paths;
-        const programName = config.programName ?? root.name;
-        super({
-            description: 'Generate shell completion script',
-        });
+        const programName = config.programName ?? root.name ?? 'program';
+        super({ desc: 'Generate shell completion script' });
         this.option({
             long: 'bash',
             type: 'boolean',
-            description: 'Generate Bash completion script',
+            args: 'none',
+            desc: 'Generate Bash completion script',
         })
             .option({
             long: 'fish',
             type: 'boolean',
-            description: 'Generate Fish completion script',
+            args: 'none',
+            desc: 'Generate Fish completion script',
         })
             .option({
             long: 'pwsh',
             type: 'boolean',
-            description: 'Generate PowerShell completion script',
+            args: 'none',
+            desc: 'Generate PowerShell completion script',
         })
             .option({
             long: 'write',
             short: 'w',
             type: 'string',
-            description: 'Write to file (default path if no value given)',
-            resolver: argv => resolveOptionalStringOption(argv, 'write', 'w'),
+            args: 'required',
+            desc: 'Write to file (use shell default path if empty)',
+            default: undefined,
         })
             .action(({ opts }) => {
             const meta = root.getCompletionMeta();
@@ -905,45 +922,6 @@ function expandHome(filepath) {
     }
     return filepath;
 }
-function resolveOptionalStringOption(argv, longName, shortName) {
-    const remaining = [];
-    let value;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg.startsWith(`--${longName}=`)) {
-            value = arg.slice(`--${longName}=`.length);
-            continue;
-        }
-        if (arg === `--${longName}`) {
-            const next = argv[i + 1];
-            if (next !== undefined && !next.startsWith('-')) {
-                value = next;
-                i += 1;
-            }
-            else {
-                value = '';
-            }
-            continue;
-        }
-        if (arg.startsWith(`-${shortName}=`)) {
-            value = arg.slice(`-${shortName}=`.length);
-            continue;
-        }
-        if (arg === `-${shortName}`) {
-            const next = argv[i + 1];
-            if (next !== undefined && !next.startsWith('-')) {
-                value = next;
-                i += 1;
-            }
-            else {
-                value = '';
-            }
-            continue;
-        }
-        remaining.push(arg);
-    }
-    return { value, remaining };
-}
 class BashCompletion {
     #meta;
     #programName;
@@ -976,11 +954,12 @@ class BashCompletion {
         const lines = [];
         const optParts = [];
         for (const opt of cmd.options) {
+            const kebabLong = camelToKebabCase(opt.long);
             if (opt.short)
                 optParts.push(`-${opt.short}`);
-            optParts.push(`--${opt.long}`);
+            optParts.push(`--${kebabLong}`);
             if (!opt.takesValue) {
-                optParts.push(`--no-${opt.long}`);
+                optParts.push(`--no-${kebabLong}`);
             }
         }
         const subParts = cmd.subcommands.flatMap(sub => [sub.name, ...sub.aliases]);
@@ -1029,13 +1008,14 @@ class FishCompletion {
         const isRoot = parentPath.length === 0;
         const condition = this.#buildCondition(parentPath);
         for (const opt of cmd.options) {
+            const kebabLong = camelToKebabCase(opt.long);
             let line = `complete -c ${this.#programName}`;
             if (condition)
                 line += ` -n '${condition}'`;
             if (opt.short)
                 line += ` -s ${opt.short}`;
-            line += ` -l ${opt.long}`;
-            line += ` -d '${this.#escape(opt.description)}'`;
+            line += ` -l ${kebabLong}`;
+            line += ` -d '${this.#escape(opt.desc)}'`;
             if (opt.choices && opt.choices.length > 0) {
                 line += ` -xa '${opt.choices.join(' ')}'`;
             }
@@ -1044,8 +1024,8 @@ class FishCompletion {
                 let noLine = `complete -c ${this.#programName}`;
                 if (condition)
                     noLine += ` -n '${condition}'`;
-                noLine += ` -l no-${opt.long}`;
-                noLine += ` -d '${this.#escape(opt.description)}'`;
+                noLine += ` -l no-${kebabLong}`;
+                noLine += ` -d '${this.#escape(opt.desc)}'`;
                 lines.push(noLine);
             }
         }
@@ -1058,7 +1038,7 @@ class FishCompletion {
                 line += ` -n '${condition}; and not __fish_seen_subcommand_from ${this.#getSubcommandNames(cmd).join(' ')}'`;
             }
             line += ` -a ${sub.name}`;
-            line += ` -d '${this.#escape(sub.description)}'`;
+            line += ` -d '${this.#escape(sub.desc)}'`;
             lines.push(line);
             for (const alias of sub.aliases) {
                 let aliasLine = `complete -c ${this.#programName}`;
@@ -1131,7 +1111,7 @@ class PwshCompletion {
             '          "--$($opt.long)",',
             '          $opt.long,',
             '          "ParameterName",',
-            '          $opt.description',
+            '          $opt.desc',
             '        )',
             '      }',
             '      if ($opt.isBoolean -and "--no-$($opt.long)" -like "$current*") {',
@@ -1139,7 +1119,7 @@ class PwshCompletion {
             '          "--no-$($opt.long)",',
             '          "no-$($opt.long)",',
             '          "ParameterName",',
-            '          $opt.description',
+            '          $opt.desc',
             '        )',
             '      }',
             '      if ($opt.short -and "-$($opt.short)" -like "$current*") {',
@@ -1147,7 +1127,7 @@ class PwshCompletion {
             '          "-$($opt.short)",',
             '          $opt.short,',
             '          "ParameterName",',
-            '          $opt.description',
+            '          $opt.desc',
             '        )',
             '      }',
             '    }',
@@ -1161,7 +1141,7 @@ class PwshCompletion {
             '          $sub,',
             '          $sub,',
             '          "Command",',
-            '          $cmd.subcommands[$sub].description',
+            '          $cmd.subcommands[$sub].desc',
             '        )',
             '      }',
             '    }',
@@ -1175,14 +1155,15 @@ class PwshCompletion {
     }
     #generateCommandHash(cmd, indent) {
         const lines = [];
-        lines.push(`${indent}description = '${this.#escape(cmd.description)}'`);
+        lines.push(`${indent}description = '${this.#escape(cmd.desc)}'`);
         lines.push(`${indent}options = @(`);
         for (const opt of cmd.options) {
+            const kebabLong = camelToKebabCase(opt.long);
             lines.push(`${indent}  @{`);
             if (opt.short)
                 lines.push(`${indent}    short = '${opt.short}'`);
-            lines.push(`${indent}    long = '${opt.long}'`);
-            lines.push(`${indent}    description = '${this.#escape(opt.description)}'`);
+            lines.push(`${indent}    long = '${kebabLong}'`);
+            lines.push(`${indent}    description = '${this.#escape(opt.desc)}'`);
             lines.push(`${indent}    isBoolean = $${!opt.takesValue}`);
             if (opt.choices) {
                 lines.push(`${indent}    choices = @('${opt.choices.join("', '")}')`);