@guanghechen/commander 4.7.1 → 4.7.3

package/lib/types/browser.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[]
@@ -65,9 +66,9 @@ interface ICommandOptionConfig<T = unknown> {
     apply?: (value: T, ctx: ICommandContext) => void;
 }
 /** Argument kind */
-type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
+type ICommandArgumentKind = 'required' | 'optional' | 'variadic' | 'some';
 /** Argument value type */
-type ICommandArgumentType = 'string' | 'number';
+type ICommandArgumentType = 'string' | 'choice';
 /**
  * Positional argument configuration.
  *
@@ -85,8 +86,10 @@ interface ICommandArgumentConfig<T = unknown> {
     desc: string;
     /** Argument kind: required / optional / variadic */
     kind: ICommandArgumentKind;
-    /** Value type, defaults to 'string' */
-    type?: ICommandArgumentType;
+    /** Value type */
+    type: ICommandArgumentType;
+    /** Allowed values for choice type */
+    choices?: ReadonlyArray<string>;
     /** Default value when not provided (only for optional arguments) */
     default?: T;
     /** Custom value transformation (takes precedence over type conversion) */
@@ -317,6 +320,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help argument line (internal) */
+interface IHelpArgumentLine {
+    sig: string;
+    desc: string;
+}
 /** Help command line (internal) */
 interface IHelpCommandLine {
     name: string;
@@ -332,6 +340,7 @@ interface IHelpExampleLine {
 interface IHelpData {
     desc: string;
     usage: string;
+    arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
@@ -361,6 +370,17 @@ interface ICompletionOptionMeta {
     /** Allowed values */
     choices?: string[];
 }
+/** Argument metadata for completion */
+interface ICompletionArgumentMeta {
+    /** Argument name */
+    name: string;
+    /** Argument kind */
+    kind: ICommandArgumentKind;
+    /** Argument type */
+    type: ICommandArgumentType;
+    /** Allowed values (only for type='choice') */
+    choices?: string[];
+}
 /** Command metadata for completion */
 interface ICompletionMeta {
     /** Command name */
@@ -371,6 +391,8 @@ interface ICompletionMeta {
     aliases: string[];
     /** Options */
     options: ICompletionOptionMeta[];
+    /** Positional arguments */
+    arguments: ICompletionArgumentMeta[];
     /** Subcommands */
     subcommands: ICompletionMeta[];
 }
@@ -548,4 +570,4 @@ declare function getDefaultCommandRuntime(): ICommandRuntime;
 declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
 
 export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, setDefaultCommandRuntime, 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, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+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, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };

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[]
@@ -65,9 +66,9 @@ interface ICommandOptionConfig<T = unknown> {
     apply?: (value: T, ctx: ICommandContext) => void;
 }
 /** Argument kind */
-type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
+type ICommandArgumentKind = 'required' | 'optional' | 'variadic' | 'some';
 /** Argument value type */
-type ICommandArgumentType = 'string' | 'number';
+type ICommandArgumentType = 'string' | 'choice';
 /**
  * Positional argument configuration.
  *
@@ -85,8 +86,10 @@ interface ICommandArgumentConfig<T = unknown> {
     desc: string;
     /** Argument kind: required / optional / variadic */
     kind: ICommandArgumentKind;
-    /** Value type, defaults to 'string' */
-    type?: ICommandArgumentType;
+    /** Value type */
+    type: ICommandArgumentType;
+    /** Allowed values for choice type */
+    choices?: ReadonlyArray<string>;
     /** Default value when not provided (only for optional arguments) */
     default?: T;
     /** Custom value transformation (takes precedence over type conversion) */
@@ -317,6 +320,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help argument line (internal) */
+interface IHelpArgumentLine {
+    sig: string;
+    desc: string;
+}
 /** Help command line (internal) */
 interface IHelpCommandLine {
     name: string;
@@ -332,6 +340,7 @@ interface IHelpExampleLine {
 interface IHelpData {
     desc: string;
     usage: string;
+    arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
@@ -361,6 +370,17 @@ interface ICompletionOptionMeta {
     /** Allowed values */
     choices?: string[];
 }
+/** Argument metadata for completion */
+interface ICompletionArgumentMeta {
+    /** Argument name */
+    name: string;
+    /** Argument kind */
+    kind: ICommandArgumentKind;
+    /** Argument type */
+    type: ICommandArgumentType;
+    /** Allowed values (only for type='choice') */
+    choices?: string[];
+}
 /** Command metadata for completion */
 interface ICompletionMeta {
     /** Command name */
@@ -371,6 +391,8 @@ interface ICompletionMeta {
     aliases: string[];
     /** Options */
     options: ICompletionOptionMeta[];
+    /** Positional arguments */
+    arguments: ICompletionArgumentMeta[];
     /** Subcommands */
     subcommands: ICompletionMeta[];
 }
@@ -601,4 +623,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, createBrowserCommandRuntime, createNodeCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, setDefaultCommandRuntime, 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, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+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, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.7.1",
+  "version": "4.7.3",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",