@guanghechen/commander 4.7.0 → 4.7.1

package/lib/esm/node.mjs

@@ -1415,7 +1415,7 @@ class Command {
         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();

package/lib/types/browser.d.ts

@@ -93,7 +93,7 @@ interface ICommandArgumentConfig<T = unknown> {
     coerce?: (rawValue: string) => T;
 }
 interface ICommandBuiltinOptionConfig {
-    /** Enable built-in --version option (root only, requires configured version) */
+    /** Enable built-in --version option (requires configured version on target command) */
     version?: boolean;
     /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
     color?: boolean;

package/lib/types/index.d.ts

@@ -0,0 +1,384 @@
+import { IReporter } from '@guanghechen/reporter';
+
+/**
+ * Type definitions for @guanghechen/commander
+ *
+ * @module @guanghechen/commander
+ */
+
+/** Token type: long option, short option, or positional */
+type ICommandTokenType = 'long' | 'short' | 'none';
+/**
+ * Command token after preprocessing.
+ *
+ * - original: raw input for error messages (e.g., --LOG-LEVEL=info, -v)
+ * - resolved: normalized form (e.g., --logLevel=info, -v)
+ * - name: option name for matching (e.g., logLevel, v, '')
+ * - type: token type (long/short/none)
+ */
+interface ICommandToken {
+    /** Raw input, used for error display */
+    original: string;
+    /** Normalized form, used for parsing */
+    resolved: string;
+    /** Option name for matching: camelCase for long, single char for short, '' for positional */
+    name: string;
+    /** Token type */
+    type: ICommandTokenType;
+}
+/** Option value type */
+type ICommandOptionType = 'boolean' | 'number' | 'string';
+/** Option argument mode */
+type ICommandOptionArgs = 'none' | 'required' | 'variadic';
+/**
+ * Option configuration.
+ *
+ * `type` and `args` must be specified together. Valid combinations:
+ * - boolean + none → boolean
+ * - string + required → string
+ * - number + required → number
+ * - string + variadic → string[]
+ * - number + variadic → number[]
+ *
+ * @template T - The type of the option value
+ */
+interface ICommandOptionConfig<T = unknown> {
+    /** Long option name (camelCase, required) */
+    long: string;
+    /** Short option (single character) */
+    short?: string;
+    /** Value type (required) */
+    type: ICommandOptionType;
+    /** Argument mode (required) */
+    args: ICommandOptionArgs;
+    /** Description for help text */
+    desc: string;
+    /** Whether this option is required (mutually exclusive with default) */
+    required?: boolean;
+    /** Default value when not provided */
+    default?: T;
+    /** Allowed values for validation and completion */
+    choices?: T extends Array<infer U> ? U[] : T[];
+    /** Single value transformation (called for each value, before choices validation) */
+    coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
+    /** Callback after parsing, applies value to context */
+    apply?: (value: T, ctx: ICommandContext) => void;
+}
+/** Argument kind */
+type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
+/** Argument value type */
+type ICommandArgumentType = 'string' | 'number';
+/**
+ * Positional argument configuration.
+ *
+ * Constraints:
+ * - required arguments must come before optional
+ * - variadic can only appear once, and must be last
+ * - required cannot have default
+ *
+ * @template T - The type of the argument value
+ */
+interface ICommandArgumentConfig<T = unknown> {
+    /** Argument name */
+    name: string;
+    /** Argument description */
+    desc: string;
+    /** Argument kind: required / optional / variadic */
+    kind: ICommandArgumentKind;
+    /** Value type, defaults to 'string' */
+    type?: ICommandArgumentType;
+    /** Default value when not provided (only for optional arguments) */
+    default?: T;
+    /** Custom value transformation (takes precedence over type conversion) */
+    coerce?: (rawValue: string) => T;
+}
+/** Command configuration */
+interface ICommandConfig {
+    /** Command name (only for root command) */
+    name?: string;
+    /** Command description */
+    desc: string;
+    /** Version (for root --version) */
+    version?: string;
+    /** Enable built-in "help" subcommand */
+    help?: boolean;
+    /** Default reporter for this command */
+    reporter?: IReporter;
+}
+/** Command interface */
+interface ICommand {
+    readonly name: string | undefined;
+    readonly description: string;
+    readonly version: string | undefined;
+    readonly parent: ICommand | undefined;
+    readonly options: ICommandOptionConfig[];
+    readonly arguments: ICommandArgumentConfig[];
+    readonly subcommands: Map<string, ICommand>;
+}
+/** Execution context */
+interface ICommandContext {
+    /** Current command node */
+    cmd: ICommand;
+    /** Environment variables */
+    envs: Record<string, string | undefined>;
+    /** Reporter instance */
+    reporter: IReporter;
+    /** Original argv */
+    argv: string[];
+}
+/** Action callback parameters */
+interface ICommandActionParams {
+    /** Execution context */
+    ctx: ICommandContext;
+    /** Parsed options (keyed by long name) */
+    opts: ICommandParsedOpts;
+    /** Parsed positional arguments (keyed by argument name) */
+    args: ICommandParsedArgs;
+    /** Raw positional argument strings (before type conversion) */
+    rawArgs: string[];
+}
+/** Action handler function */
+type ICommandAction = (params: ICommandActionParams) => void | Promise<void>;
+/** run() / parse() method parameters */
+interface ICommandRunParams {
+    /** Command line arguments (usually process.argv.slice(2)) */
+    argv: string[];
+    /** Environment variables (usually process.env) */
+    envs: Record<string, string | undefined>;
+    /** Optional reporter override */
+    reporter?: IReporter;
+}
+/** Parsed options record */
+type ICommandParsedOpts = Record<string, unknown>;
+/** Parsed arguments record */
+type ICommandParsedArgs = Record<string, unknown>;
+/** Route stage result */
+interface ICommandRouteResult {
+    /** Command chain from root to leaf */
+    chain: ICommand[];
+    /** Remaining argv after routing */
+    remaining: string[];
+}
+/** Tokenize stage result */
+interface ICommandTokenizeResult {
+    /** Option tokens (before --) */
+    optionTokens: ICommandToken[];
+    /** Arguments after -- */
+    restArgs: string[];
+}
+/** Resolve stage result */
+interface ICommandResolveResult {
+    /** Tokens consumed by each command */
+    consumedTokens: Map<ICommand, ICommandToken[]>;
+    /** Argument tokens (non-option tokens) */
+    argTokens: ICommandToken[];
+}
+/** shift() method result (internal) */
+interface ICommandShiftResult {
+    /** Tokens consumed by this command */
+    consumed: ICommandToken[];
+    /** Remaining tokens to pass to parent */
+    remaining: ICommandToken[];
+}
+/** Parse stage result */
+interface ICommandParseResult {
+    /** Execution context */
+    ctx: ICommandContext;
+    /** Parsed options */
+    opts: ICommandParsedOpts;
+    /** Parsed arguments */
+    args: ICommandParsedArgs;
+    /** Raw argument strings */
+    rawArgs: string[];
+}
+/** Error kinds for command parsing */
+type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
+/** Commander error with structured information */
+declare class CommanderError extends Error {
+    readonly kind: ICommanderErrorKind;
+    readonly commandPath: string;
+    constructor(kind: ICommanderErrorKind, message: string, commandPath: string);
+    /** Format error with help hint */
+    format(): string;
+}
+/** Shell type for completion */
+type ICompletionShellType = 'bash' | 'fish' | 'pwsh';
+/** Option metadata for completion */
+interface ICompletionOptionMeta {
+    /** Long option name (camelCase) */
+    long: string;
+    /** Short option */
+    short?: string;
+    /** Description */
+    desc: string;
+    /** Whether option takes value (args !== 'none') */
+    takesValue: boolean;
+    /** Allowed values */
+    choices?: string[];
+}
+/** Command metadata for completion */
+interface ICompletionMeta {
+    /** Command name */
+    name: string;
+    /** Description */
+    desc: string;
+    /** Command aliases */
+    aliases: string[];
+    /** Options */
+    options: ICompletionOptionMeta[];
+    /** Subcommands */
+    subcommands: ICompletionMeta[];
+}
+/** Shell completion paths configuration */
+interface ICompletionPaths {
+    /** Bash completion file path */
+    bash: string;
+    /** Fish completion file path */
+    fish: string;
+    /** PowerShell completion file path */
+    pwsh: string;
+}
+/** CompletionCommand configuration */
+interface ICompletionCommandConfig {
+    /** Program name for completion scripts (defaults to root.name) */
+    programName?: string;
+    /** Default completion file paths for each shell */
+    paths: ICompletionPaths;
+}
+
+/**
+ * Command class - CLI command builder with fluent API
+ *
+ * Execution flow: route → tokenize → resolve → parse → run
+ *
+ * @module @guanghechen/commander
+ */
+
+declare class Command implements ICommand {
+    #private;
+    constructor(config: ICommandConfig);
+    get name(): string | undefined;
+    get description(): string;
+    get version(): string | undefined;
+    get parent(): Command | undefined;
+    get options(): ICommandOptionConfig[];
+    get arguments(): ICommandArgumentConfig[];
+    get subcommands(): Map<string, ICommand>;
+    option<T>(opt: ICommandOptionConfig<T>): this;
+    argument<T>(arg: ICommandArgumentConfig<T>): this;
+    action(fn: ICommandAction): this;
+    subcommand(name: string, cmd: Command): this;
+    run(params: ICommandRunParams): Promise<void>;
+    parse(params: ICommandRunParams): ICommandParseResult;
+    formatHelp(): string;
+    getCompletionMeta(): ICompletionMeta;
+}
+
+/**
+ * Shell completion generators
+ *
+ * @module @guanghechen/commander
+ */
+
+/**
+ * Built-in completion command that generates shell completion scripts.
+ *
+ * @example
+ * ```typescript
+ * const root = new Command({ name: 'mycli', desc: 'My CLI' })
+ * root.subcommand('completion', new CompletionCommand(root, {
+ *   paths: {
+ *     bash: `~/.local/share/bash-completion/completions/mycli`,
+ *     fish: `~/.config/fish/completions/mycli.fish`,
+ *     pwsh: `~/.config/powershell/Microsoft.PowerShell_profile.ps1`,
+ *   }
+ * }))
+ *
+ * // Usage:
+ * // mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
+ * // mycli completion --fish --write  (writes to default path)
+ * // mycli completion --fish --write /custom/path.fish
+ * ```
+ */
+declare class CompletionCommand extends Command {
+    constructor(root: Command, config: ICompletionCommandConfig);
+}
+declare class BashCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
+declare class FishCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
+declare class PwshCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
+
+/**
+ * Pre-defined common options for @guanghechen/commander
+ *
+ * @module @guanghechen/commander/options
+ */
+
+/**
+ * Pre-defined --log-level option for setting log verbosity.
+ *
+ * Supports: debug | info | hint | warn | error (case-insensitive)
+ *
+ * | Property  | Value                              |
+ * | --------- | ---------------------------------- |
+ * | long      | 'logLevel'                         |
+ * | type      | 'string'                           |
+ * | args      | 'required'                         |
+ * | default   | 'info'                             |
+ * | choices   | LOG_LEVELS                         |
+ * | coerce    | resolveLogLevel (case-insensitive) |
+ * | apply     | ctx.reporter.setLevel(value)       |
+ *
+ * @example
+ * ```typescript
+ * import { logLevelOption } from '@guanghechen/commander'
+ *
+ * const cmd = new Command('app')
+ *   .option(logLevelOption)
+ *   .action(({ opts }) => {
+ *     console.log(opts.logLevel) // 'debug' | 'info' | 'hint' | 'warn' | 'error'
+ *   })
+ *
+ * // Override with spread syntax
+ * .option({ ...logLevelOption, default: 'warn' })
+ * ```
+ */
+declare const logLevelOption: ICommandOptionConfig<string>;
+/**
+ * Pre-defined --silent option for suppressing non-error output.
+ *
+ * | Property  | Value     |
+ * | --------- | --------- |
+ * | long      | 'silent'  |
+ * | type      | 'boolean' |
+ * | args      | 'none'    |
+ * | default   | false     |
+ *
+ * @example
+ * ```typescript
+ * import { silentOption } from '@guanghechen/commander'
+ *
+ * const cmd = new Command('app')
+ *   .option(silentOption)
+ *   .action(({ opts }) => {
+ *     if (!opts.silent) {
+ *       console.log('Processing...')
+ *     }
+ *   })
+ * ```
+ */
+declare const silentOption: ICommandOptionConfig<boolean>;
+
+export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logLevelOption, silentOption };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandConfig, ICommandContext, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };

package/lib/types/node.d.ts

@@ -93,7 +93,7 @@ interface ICommandArgumentConfig<T = unknown> {
     coerce?: (rawValue: string) => T;
 }
 interface ICommandBuiltinOptionConfig {
-    /** Enable built-in --version option (root only, requires configured version) */
+    /** Enable built-in --version option (requires configured version on target command) */
     version?: boolean;
     /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
     color?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -44,8 +44,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/reporter": "^3.3.0",
-    "@guanghechen/env": "^2.0.2"
+    "@guanghechen/env": "^2.0.2",
+    "@guanghechen/reporter": "^3.3.0"
   },
   "scripts": {
     "build": "rollup -c ../../rollup.config.mjs",