@guanghechen/commander 3.3.0 → 4.1.0

package/lib/types/index.d.ts

@@ -1,144 +1,198 @@
+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';
 /**
- * Reporter interface for logging.
- * Users should provide their own implementation.
+ * 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 IReporter {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
+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;
 }
-/** Supported option value types */
-type IOptionType = 'boolean' | 'string' | 'number' | 'string[]' | 'number[]';
+/** Option value type */
+type ICommandOptionType = 'boolean' | 'number' | 'string';
+/** Option argument mode */
+type ICommandOptionArgs = 'none' | 'required' | 'variadic';
 /**
- * Option definition.
+ * 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 IOption<T = unknown> {
-    /** Long option (e.g., 'verbose' for --verbose), also used as merge key */
+interface ICommandOptionConfig<T = unknown> {
+    /** Long option name (camelCase, required) */
     long: string;
-    /** Short option (single character, e.g., 'v' for -v) */
+    /** Short option (single character) */
     short?: string;
-    /** Value type, defaults to 'string' */
-    type?: IOptionType;
+    /** Value type (required) */
+    type: ICommandOptionType;
+    /** Argument mode (required) */
+    args: ICommandOptionArgs;
     /** Description for help text */
-    description: string;
-    /** Whether this option is required (cannot be used with default or boolean type) */
+    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 (ignored when resolver is present) */
+    /** Single value transformation (called for each value, before choices validation) */
     coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
-    /** Custom resolver that fully replaces builtin parsing (ignores type/coerce) */
-    resolver?: (argv: string[]) => {
-        value: T;
-        remaining: string[];
-    };
     /** Callback after parsing, applies value to context */
     apply?: (value: T, ctx: ICommandContext) => void;
 }
 /** Argument kind */
-type IArgumentKind = 'required' | 'optional' | 'variadic';
+type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
 /** Argument value type */
-type IArgumentType = 'string' | 'number';
+type ICommandArgumentType = 'string' | 'number';
 /**
- * Positional argument definition.
+ * 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 IArgument<T = unknown> {
+interface ICommandArgumentConfig<T = unknown> {
     /** Argument name */
     name: string;
     /** Argument description */
-    description: string;
+    desc: string;
     /** Argument kind: required / optional / variadic */
-    kind: IArgumentKind;
+    kind: ICommandArgumentKind;
     /** Value type, defaults to 'string' */
-    type?: IArgumentType;
-    /** Default value when not provided (only effective for optional arguments) */
+    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 effective for root command) */
+    /** Command name (only for root command) */
     name?: string;
     /** Command description */
-    description: string;
-    /** Version (only effective for built-in root --version) */
+    desc: string;
+    /** Version (for root --version) */
     version?: string;
-    /** Enable built-in "help" subcommand (only effective when command has subcommands) */
+    /** Enable built-in "help" subcommand */
     help?: boolean;
-    /** Default reporter for this command (can be overridden by run params) */
+    /** Default reporter for this command */
     reporter?: IReporter;
 }
-/** Forward declaration for Command class */
+/** Command interface */
 interface ICommand {
-    readonly name: string;
+    readonly name: string | undefined;
     readonly description: string;
     readonly version: string | undefined;
-    readonly parent?: ICommand;
-    readonly options: IOption[];
-    readonly arguments: IArgument[];
+    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 passed in */
+    /** Environment variables */
     envs: Record<string, string | undefined>;
     /** Reporter instance */
     reporter: IReporter;
     /** Original argv */
     argv: string[];
 }
-/** Action parameters */
-interface IActionParams {
+/** Action callback parameters */
+interface ICommandActionParams {
     /** Execution context */
     ctx: ICommandContext;
-    /** Parsed options */
-    opts: Record<string, unknown>;
+    /** Parsed options (keyed by long name) */
+    opts: ICommandParsedOpts;
     /** Parsed positional arguments (keyed by argument name) */
-    args: Record<string, unknown>;
+    args: ICommandParsedArgs;
     /** Raw positional argument strings (before type conversion) */
     rawArgs: string[];
 }
 /** Action handler function */
-type IAction = (params: IActionParams) => void | Promise<void>;
-/** run() method parameters */
-interface IRunParams {
+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 (defaults to command's reporter or console reporter) */
+    /** Optional reporter override */
     reporter?: IReporter;
 }
-/** parse() method result */
-interface IParseResult {
+/** 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: Record<string, unknown>;
-    /** Parsed positional arguments (keyed by argument name) */
-    args: Record<string, unknown>;
-    /** Raw positional argument strings (before type conversion) */
+    opts: ICommandParsedOpts;
+    /** Parsed arguments */
+    args: ICommandParsedArgs;
+    /** Raw argument strings */
     rawArgs: string[];
 }
-/** shift() method result */
-interface IShiftResult {
-    /** Options consumed by this command */
-    opts: Record<string, unknown>;
-    /** Tokens not consumed, to be passed to parent */
-    remaining: string[];
-}
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
+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;
@@ -148,66 +202,74 @@ declare class CommanderError extends Error {
     format(): string;
 }
 /** Shell type for completion */
-type IShellType = 'bash' | 'fish' | 'pwsh';
+type ICompletionShellType = 'bash' | 'fish' | 'pwsh';
 /** Option metadata for completion */
 interface ICompletionOptionMeta {
+    /** Long option name (camelCase) */
     long: string;
+    /** Short option */
     short?: string;
-    description: 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: string;
+    /** Description */
+    desc: string;
+    /** Command aliases */
     aliases: string[];
+    /** Options */
     options: ICompletionOptionMeta[];
+    /** Subcommands */
     subcommands: ICompletionMeta[];
 }
 /** Shell completion paths configuration */
 interface ICompletionPaths {
-    /** Bash completion file path (e.g., ~/.local/share/bash-completion/completions/{name}) */
+    /** Bash completion file path */
     bash: string;
-    /** Fish completion file path (e.g., ~/.config/fish/completions/{name}.fish) */
+    /** Fish completion file path */
     fish: string;
-    /** PowerShell completion file path (only ~ expansion supported, not $PROFILE) */
+    /** 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 (required for --write support) */
+    /** 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;
+    get name(): string | undefined;
     get description(): string;
     get version(): string | undefined;
     get parent(): Command | undefined;
-    get options(): IOption[];
-    get arguments(): IArgument[];
-    option(opt: IOption): this;
-    argument(arg: IArgument): this;
-    action(fn: IAction): this;
+    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: IRunParams): Promise<void>;
-    parse(argv: string[]): IParseResult;
-    /**
-     * Shift options from tokens that this command recognizes.
-     * Unrecognized tokens are returned in `remaining` for parent commands.
-     */
-    shift(tokens: string[]): IShiftResult;
+    run(params: ICommandRunParams): Promise<void>;
+    parse(params: ICommandRunParams): ICommandParseResult;
     formatHelp(): string;
     getCompletionMeta(): ICompletionMeta;
 }
@@ -223,7 +285,7 @@ declare class Command implements ICommand {
  *
  * @example
  * ```typescript
- * const root = new Command({ name: 'mycli', description: 'My CLI' })
+ * const root = new Command({ name: 'mycli', desc: 'My CLI' })
  * root.subcommand('completion', new CompletionCommand(root, {
  *   paths: {
  *     bash: `~/.local/share/bash-completion/completions/mycli`,
@@ -257,5 +319,66 @@ declare class PwshCompletion {
     generate(): string;
 }
 
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion };
-export type { IAction, IActionParams, IArgument, IArgumentKind, ICommand, ICommandConfig, ICommandContext, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, IOption, IOptionType, IParseResult, IReporter, IRunParams, IShellType, IShiftResult };
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "3.3.0",
+  "version": "4.1.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -40,6 +40,9 @@
     "LICENSE",
     "README.md"
   ],
+  "dependencies": {
+    "@guanghechen/reporter": "^3.2.0"
+  },
   "scripts": {
     "build": "rollup -c ../../rollup.config.mjs",
     "clean": "rimraf lib",