@guanghechen/commander 4.6.0 → 4.7.1

package/lib/types/node.d.ts

@@ -0,0 +1,604 @@
+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;
+}
+interface ICommandBuiltinOptionConfig {
+    /** 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;
+    /** 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;
+}
+/** Runtime file stats abstraction */
+interface ICommandRuntimeStats {
+    isDirectory(): boolean;
+}
+/** Runtime abstraction for environment-dependent operations */
+interface ICommandRuntime {
+    /** Current working directory */
+    cwd(): string;
+    /** Path absolute check */
+    isAbsolute(filepath: string): boolean;
+    /** Resolve paths into an absolute path */
+    resolve(...paths: string[]): string;
+    /** Read UTF-8 text file */
+    readFile(filepath: string): Promise<string>;
+    /** Stat file system entry */
+    stat(filepath: string): Promise<ICommandRuntimeStats>;
+}
+/** 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?: string;
+    /** Built-in features configuration */
+    builtin?: boolean | ICommandBuiltinConfig;
+    /** Command-level preset defaults */
+    preset?: ICommandPresetConfig;
+    /** Default reporter for this command */
+    reporter?: IReporter;
+    /** Runtime adapter for environment-dependent operations */
+    runtime?: ICommandRuntime;
+}
+/** Command interface */
+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 */
+    envs: Record<string, string | undefined>;
+    /** Built-in control hit status */
+    controls: ICommandControls;
+    /** Input source snapshots */
+    sources: ICommandInputSources;
+    /** Reporter instance */
+    reporter: IReporter;
+}
+/** 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<TCommand = ICommand> {
+    /** Command chain from root to leaf */
+    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 {
+    /** 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[];
+}
+/** 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 */
+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?: Partial<ICompletionPaths>;
+}
+
+/**
+ * Node runtime adapter
+ *
+ * @module @guanghechen/commander
+ */
+
+declare function createNodeCommandRuntime(): ICommandRuntime;
+
+/**
+ * Command class - CLI command builder with fluent API
+ *
+ * Execution flow: route → control-scan → run-control(run) → preset → 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 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>;
+    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;
+
+/**
+ * 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 --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.
+ *
+ * | 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>;
+
+/**
+ * Browser runtime adapter
+ *
+ * @module @guanghechen/commander
+ */
+
+declare function createBrowserCommandRuntime(): ICommandRuntime;
+
+/**
+ * Runtime adapters
+ *
+ * @module @guanghechen/commander
+ */
+
+declare function getDefaultCommandRuntime(): ICommandRuntime;
+declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
+
+/**
+ * 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;
+}
+
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "4.6.0",
+  "version": "4.7.1",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
@@ -20,17 +20,20 @@
   ],
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "source": "./src/index.ts",
-      "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs"
+    ".": null,
+    "./browser": {
+      "types": "./lib/types/browser.d.ts",
+      "source": "./src/runtime/browser/entry.ts",
+      "import": "./lib/esm/browser.mjs",
+      "require": "./lib/cjs/browser.cjs"
+    },
+    "./node": {
+      "types": "./lib/types/node.d.ts",
+      "source": "./src/runtime/node/index.ts",
+      "import": "./lib/esm/node.mjs",
+      "require": "./lib/cjs/node.cjs"
     }
   },
-  "source": "./src/index.ts",
-  "main": "./lib/cjs/index.cjs",
-  "module": "./lib/esm/index.mjs",
-  "types": "./lib/types/index.d.ts",
   "license": "MIT",
   "files": [
     "lib/",