@guanghechen/commander 4.5.0 → 4.6.0

package/lib/types/index.d.ts

@@ -93,6 +93,8 @@ interface ICommandArgumentConfig<T = unknown> {
     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 */
@@ -104,15 +106,9 @@ interface ICommandBuiltinOptionConfig {
     /** Enable built-in --log-colorful/--no-log-colorful option */
     logColorful?: boolean;
 }
-interface ICommandBuiltinCommandConfig {
-    /** Enable built-in help subcommand */
-    help?: boolean;
-}
 interface ICommandBuiltinConfig {
     /** Built-in options configuration */
     option?: boolean | ICommandBuiltinOptionConfig;
-    /** Built-in command configuration */
-    command?: boolean | ICommandBuiltinCommandConfig;
 }
 /** Command example configuration */
 interface ICommandExample {
@@ -123,6 +119,15 @@ interface ICommandExample {
     /** 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) */
@@ -133,6 +138,8 @@ interface ICommandConfig {
     version?: string;
     /** Built-in features configuration */
     builtin?: boolean | ICommandBuiltinConfig;
+    /** Command-level preset defaults */
+    preset?: ICommandPresetConfig;
     /** Default reporter for this command */
     reporter?: IReporter;
 }
@@ -141,6 +148,8 @@ 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[];
@@ -151,12 +160,16 @@ interface ICommand {
 interface ICommandContext {
     /** Current command node */
     cmd: ICommand;
-    /** Environment variables */
+    /** Command chain from root to leaf */
+    chain: ICommand[];
+    /** Effective 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 {
@@ -185,11 +198,29 @@ type ICommandParsedOpts = Record<string, unknown>;
 /** Parsed arguments record */
 type ICommandParsedArgs = Record<string, unknown>;
 /** Route stage result */
-interface ICommandRouteResult {
+interface ICommandRouteResult<TCommand = ICommand> {
     /** Command chain from root to leaf */
-    chain: ICommand[];
+    chain: TCommand[];
     /** 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 {
@@ -223,6 +254,69 @@ 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';
 /** Commander error with structured information */
@@ -275,13 +369,13 @@ interface ICompletionCommandConfig {
     /** Program name for completion scripts (defaults to root.name) */
     programName?: string;
     /** Default completion file paths for each shell */
-    paths: ICompletionPaths;
+    paths?: Partial<ICompletionPaths>;
 }
 
 /**
  * Command class - CLI command builder with fluent API
  *
- * Execution flow: route → tokenize → resolve → parse → run
+ * Execution flow: route → control-scan → run-control(run) → preset → tokenize → resolve → parse → run
  *
  * @module @guanghechen/commander
  */
@@ -292,6 +386,8 @@ 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[];
@@ -303,7 +399,7 @@ declare class Command implements ICommand {
     example(title: string, usage: string, desc: string): this;
     subcommand(name: string, cmd: Command): this;
     run(params: ICommandRunParams): Promise<void>;
-    parse(params: ICommandRunParams): ICommandParseResult;
+    parse(params: ICommandRunParams): Promise<ICommandParseResult>;
     formatHelp(): string;
     getCompletionMeta(): ICompletionMeta;
 }
@@ -316,12 +412,22 @@ declare class Command implements ICommand {
 declare class Coerce {
     private constructor();
     private static create;
-    static number(name: string, errorMessage?: string): (rawValue: string) => number;
+    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
  *
@@ -349,7 +455,7 @@ declare class Coerce {
  * ```
  */
 declare class CompletionCommand extends Command {
-    constructor(root: Command, config: ICompletionCommandConfig);
+    constructor(root: Command, config?: ICompletionCommandConfig);
 }
 declare class BashCompletion {
     #private;
@@ -450,5 +556,5 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
  */
 declare const silentOption: ICommandOptionConfig<boolean>;
 
-export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandConfig, ICommandContext, ICommandExample, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -41,6 +41,7 @@
     "README.md"
   ],
   "dependencies": {
+    "@guanghechen/env": "^2.0.2",
     "@guanghechen/reporter": "^3.3.0"
   },
   "scripts": {