@guanghechen/commander 4.7.2 → 4.7.4

package/lib/types/index.d.ts

@@ -92,54 +92,16 @@ interface ICommandArgumentConfig<T = unknown> {
     /** Custom value transformation (takes precedence over type conversion) */
     coerce?: (rawValue: string) => T;
 }
-interface ICommandBuiltinOptionConfig {
-    /** Enable built-in --version option (root only, requires configured version) */
-    version?: boolean;
-    /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
-    color?: boolean;
-    /** Enable built-in --log-level option */
-    logLevel?: boolean;
-    /** Enable built-in --silent option */
-    silent?: boolean;
-    /** Enable built-in --log-date/--no-log-date option */
-    logDate?: boolean;
-    /** Enable built-in --log-colorful/--no-log-colorful option */
-    logColorful?: boolean;
-}
-interface ICommandBuiltinConfig {
-    /** Built-in options configuration */
-    option?: boolean | ICommandBuiltinOptionConfig;
-}
-/** Command example configuration */
-interface ICommandExample {
-    /** Example title */
-    title: string;
-    /** Usage fragment relative to command path */
-    usage: string;
-    /** Example description */
-    desc: string;
-}
-/** Command preset defaults */
-interface ICommandPresetConfig {
-    /** Preset root directory (absolute path) */
-    root?: string;
-    /** Default preset options file */
-    opt?: string;
-    /** Default preset envs file */
-    env?: string;
-}
 /** Command configuration */
 interface ICommandConfig {
     /** Command name (only for root command) */
     name?: string;
     /** Command description */
     desc: string;
-    /** Version (for built-in --version on this command) */
+    /** Version (for root --version) */
     version?: string;
-    /** Built-in features configuration */
-    builtin?: boolean | ICommandBuiltinConfig;
-    /** Command-level preset defaults */
-    preset?: ICommandPresetConfig;
+    /** Enable built-in "help" subcommand */
+    help?: boolean;
     /** Default reporter for this command */
     reporter?: IReporter;
 }
@@ -148,28 +110,21 @@ interface ICommand {
     readonly name: string | undefined;
     readonly description: string;
     readonly version: string | undefined;
-    readonly builtin: ICommandConfig['builtin'] | undefined;
-    readonly preset: ICommandPresetConfig | undefined;
     readonly parent: ICommand | undefined;
     readonly options: ICommandOptionConfig[];
     readonly arguments: ICommandArgumentConfig[];
-    readonly examples: ICommandExample[];
     readonly subcommands: Map<string, ICommand>;
 }
 /** Execution context */
 interface ICommandContext {
     /** Current command node */
     cmd: ICommand;
-    /** Command chain from root to leaf */
-    chain: ICommand[];
-    /** Effective environment variables */
+    /** Environment variables */
     envs: Record<string, string | undefined>;
-    /** Built-in control hit status */
-    controls: ICommandControls;
-    /** Input source snapshots */
-    sources: ICommandInputSources;
     /** Reporter instance */
     reporter: IReporter;
+    /** Original argv */
+    argv: string[];
 }
 /** Action callback parameters */
 interface ICommandActionParams {
@@ -198,29 +153,11 @@ type ICommandParsedOpts = Record<string, unknown>;
 /** Parsed arguments record */
 type ICommandParsedArgs = Record<string, unknown>;
 /** Route stage result */
-interface ICommandRouteResult<TCommand = ICommand> {
+interface ICommandRouteResult {
     /** Command chain from root to leaf */
-    chain: TCommand[];
+    chain: ICommand[];
     /** Remaining argv after routing */
     remaining: string[];
-    /** Routed command tokens from user argv (name/alias) */
-    cmds: string[];
-}
-/** Control-scan stage result */
-interface ICommandControlScanResult {
-    /** Built-in control hit status */
-    controls: ICommandControls;
-    /** Remaining argv after stripping control tokens */
-    remaining: string[];
-    /** Optional target token from `help <child>` syntax */
-    helpTarget?: string;
-}
-/** Preset stage result */
-interface ICommandPresetResult {
-    /** Effective tail argv after preset merge */
-    tailArgv: string[];
-    /** Effective envs after preset merge */
-    envs: Record<string, string | undefined>;
 }
 /** Tokenize stage result */
 interface ICommandTokenizeResult {
@@ -254,71 +191,8 @@ interface ICommandParseResult {
     /** Raw argument strings */
     rawArgs: string[];
 }
-/** Input source snapshots for debugging/tracing */
-interface ICommandInputSources {
-    preset: {
-        argv: string[];
-        envs: Record<string, string>;
-    };
-    user: {
-        /** Routed command tokens (name/alias as entered by user) */
-        cmds: string[];
-        /** Clean user tail argv after removing command chain/control/preset directives */
-        argv: string[];
-        /** Raw env snapshot from run/parse params */
-        envs: Record<string, string | undefined>;
-    };
-}
-/** Built-in run controls */
-interface ICommandControls {
-    help: boolean;
-    version: boolean;
-}
-/** Built-in option resolution result (internal) */
-interface ICommandBuiltinOptionResolved {
-    version: boolean;
-    color: boolean;
-    logLevel: boolean;
-    silent: boolean;
-    logDate: boolean;
-    logColorful: boolean;
-}
-/** Built-in config resolution result (internal) */
-interface ICommandBuiltinResolved {
-    option: ICommandBuiltinOptionResolved;
-}
-/** Subcommand registry entry (internal) */
-interface ISubcommandEntry<TCommand = ICommand> {
-    name: string;
-    aliases: string[];
-    command: TCommand;
-}
-/** Help option line (internal) */
-interface IHelpOptionLine {
-    sig: string;
-    desc: string;
-}
-/** Help command line (internal) */
-interface IHelpCommandLine {
-    name: string;
-    desc: string;
-}
-/** Help example line (internal) */
-interface IHelpExampleLine {
-    title: string;
-    usage: string;
-    desc: string;
-}
-/** Structured help data for rendering (internal) */
-interface IHelpData {
-    desc: string;
-    usage: string;
-    options: IHelpOptionLine[];
-    commands: IHelpCommandLine[];
-    examples: IHelpExampleLine[];
-}
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | '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;
@@ -369,13 +243,13 @@ interface ICompletionCommandConfig {
     /** Program name for completion scripts (defaults to root.name) */
     programName?: string;
     /** Default completion file paths for each shell */
-    paths?: Partial<ICompletionPaths>;
+    paths: ICompletionPaths;
 }
 
 /**
  * Command class - CLI command builder with fluent API
  *
- * Execution flow: route → control-scan → run-control(run) → preset → tokenize → resolve → parse → run
+ * Execution flow: route → tokenize → resolve → parse → run
  *
  * @module @guanghechen/commander
  */
@@ -386,48 +260,20 @@ declare class Command implements ICommand {
     get name(): string | undefined;
     get description(): string;
     get version(): string | undefined;
-    get builtin(): ICommandConfig['builtin'] | undefined;
-    get preset(): ICommandPresetConfig | undefined;
     get parent(): Command | undefined;
     get options(): ICommandOptionConfig[];
     get arguments(): ICommandArgumentConfig[];
-    get examples(): ICommandExample[];
     get subcommands(): Map<string, ICommand>;
     option<T>(opt: ICommandOptionConfig<T>): this;
     argument<T>(arg: ICommandArgumentConfig<T>): this;
     action(fn: ICommandAction): this;
-    example(title: string, usage: string, desc: string): this;
     subcommand(name: string, cmd: Command): this;
     run(params: ICommandRunParams): Promise<void>;
-    parse(params: ICommandRunParams): Promise<ICommandParseResult>;
+    parse(params: ICommandRunParams): ICommandParseResult;
     formatHelp(): string;
     getCompletionMeta(): ICompletionMeta;
 }
 
-/**
- * Pre-defined coerce factory methods for @guanghechen/commander.
- *
- * @module @guanghechen/commander/coerce
- */
-declare class Coerce {
-    private constructor();
-    private static create;
-    static choice<TValue extends string>(name: string, values: ReadonlyArray<TValue>, errorMessage?: string): (rawValue: string) => TValue;
-    static domain(name: string, errorMessage?: string): (rawValue: string) => string;
-    static host(name: string, errorMessage?: string): (rawValue: string) => string;
-    static integer(name: string, errorMessage?: string): (rawValue: string) => number;
-    static ip(name: string, errorMessage?: string): (rawValue: string) => string;
-    static number(name: string, errorMessage?: string): (rawValue: string) => number;
-    static port(name: string, errorMessage?: string): (rawValue: string) => number;
-    static positiveInteger(name: string, errorMessage?: string): (rawValue: string) => number;
-    static positiveNumber(name: string, errorMessage?: string): (rawValue: string) => number;
-}
-
-declare function isIpv4(rawValue: string): boolean;
-declare function isIpv6(rawValue: string): boolean;
-declare function isIp(rawValue: string): boolean;
-declare function isDomain(rawValue: string): boolean;
-
 /**
  * Shell completion generators
  *
@@ -455,7 +301,7 @@ declare function isDomain(rawValue: string): boolean;
  * ```
  */
 declare class CompletionCommand extends Command {
-    constructor(root: Command, config?: ICompletionCommandConfig);
+    constructor(root: Command, config: ICompletionCommandConfig);
 }
 declare class BashCompletion {
     #private;
@@ -509,28 +355,6 @@ declare class PwshCompletion {
  * ```
  */
 declare const logLevelOption: ICommandOptionConfig<string>;
-/**
- * Pre-defined --log-date option for controlling timestamp output.
- *
- * | Property  | Value     |
- * | --------- | --------- |
- * | long      | 'logDate' |
- * | type      | 'boolean' |
- * | args      | 'none'    |
- * | default   | true      |
- */
-declare const logDateOption: ICommandOptionConfig<boolean>;
-/**
- * Pre-defined --log-colorful option for controlling colorful output.
- *
- * | Property  | Value         |
- * | --------- | ------------- |
- * | long      | 'logColorful' |
- * | type      | 'boolean'     |
- * | args      | 'none'        |
- * | default   | true          |
- */
-declare const logColorfulOption: ICommandOptionConfig<boolean>;
 /**
  * Pre-defined --silent option for suppressing non-error output.
  *
@@ -556,5 +380,5 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
  */
 declare const silentOption: ICommandOptionConfig<boolean>;
 
-export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandExample, ICommandInputSources, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetResult, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+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

@@ -29,13 +29,14 @@ interface ICommandToken {
 /** Option value type */
 type ICommandOptionType = 'boolean' | 'number' | 'string';
 /** Option argument mode */
-type ICommandOptionArgs = 'none' | 'required' | 'variadic';
+type ICommandOptionArgs = 'none' | 'required' | 'optional' | 'variadic';
 /**
  * Option configuration.
  *
  * `type` and `args` must be specified together. Valid combinations:
  * - boolean + none → boolean
  * - string + required → string
+ * - string + optional → string | undefined
  * - number + required → number
  * - string + variadic → string[]
  * - number + variadic → number[]
@@ -364,8 +365,10 @@ interface ICompletionOptionMeta {
     short?: string;
     /** Description */
     desc: string;
-    /** Whether option takes value (args !== 'none') */
-    takesValue: boolean;
+    /** Option type */
+    type: ICommandOptionType;
+    /** Option args mode */
+    args: ICommandOptionArgs;
     /** Allowed values */
     choices?: string[];
 }

package/package.json

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