@guanghechen/commander 4.7.0 → 4.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -65,9 +65,9 @@ interface ICommandOptionConfig<T = unknown> {
65
65
  apply?: (value: T, ctx: ICommandContext) => void;
66
66
  }
67
67
  /** Argument kind */
68
- type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
68
+ type ICommandArgumentKind = 'required' | 'optional' | 'variadic' | 'some';
69
69
  /** Argument value type */
70
- type ICommandArgumentType = 'string' | 'number';
70
+ type ICommandArgumentType = 'string' | 'choice';
71
71
  /**
72
72
  * Positional argument configuration.
73
73
  *
@@ -85,15 +85,17 @@ interface ICommandArgumentConfig<T = unknown> {
85
85
  desc: string;
86
86
  /** Argument kind: required / optional / variadic */
87
87
  kind: ICommandArgumentKind;
88
- /** Value type, defaults to 'string' */
89
- type?: ICommandArgumentType;
88
+ /** Value type */
89
+ type: ICommandArgumentType;
90
+ /** Allowed values for choice type */
91
+ choices?: ReadonlyArray<string>;
90
92
  /** Default value when not provided (only for optional arguments) */
91
93
  default?: T;
92
94
  /** Custom value transformation (takes precedence over type conversion) */
93
95
  coerce?: (rawValue: string) => T;
94
96
  }
95
97
  interface ICommandBuiltinOptionConfig {
96
- /** Enable built-in --version option (root only, requires configured version) */
98
+ /** Enable built-in --version option (requires configured version on target command) */
97
99
  version?: boolean;
98
100
  /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
99
101
  color?: boolean;
@@ -317,6 +319,11 @@ interface IHelpOptionLine {
317
319
  sig: string;
318
320
  desc: string;
319
321
  }
322
+ /** Help argument line (internal) */
323
+ interface IHelpArgumentLine {
324
+ sig: string;
325
+ desc: string;
326
+ }
320
327
  /** Help command line (internal) */
321
328
  interface IHelpCommandLine {
322
329
  name: string;
@@ -332,6 +339,7 @@ interface IHelpExampleLine {
332
339
  interface IHelpData {
333
340
  desc: string;
334
341
  usage: string;
342
+ arguments: IHelpArgumentLine[];
335
343
  options: IHelpOptionLine[];
336
344
  commands: IHelpCommandLine[];
337
345
  examples: IHelpExampleLine[];
@@ -361,6 +369,17 @@ interface ICompletionOptionMeta {
361
369
  /** Allowed values */
362
370
  choices?: string[];
363
371
  }
372
+ /** Argument metadata for completion */
373
+ interface ICompletionArgumentMeta {
374
+ /** Argument name */
375
+ name: string;
376
+ /** Argument kind */
377
+ kind: ICommandArgumentKind;
378
+ /** Argument type */
379
+ type: ICommandArgumentType;
380
+ /** Allowed values (only for type='choice') */
381
+ choices?: string[];
382
+ }
364
383
  /** Command metadata for completion */
365
384
  interface ICompletionMeta {
366
385
  /** Command name */
@@ -371,6 +390,8 @@ interface ICompletionMeta {
371
390
  aliases: string[];
372
391
  /** Options */
373
392
  options: ICompletionOptionMeta[];
393
+ /** Positional arguments */
394
+ arguments: ICompletionArgumentMeta[];
374
395
  /** Subcommands */
375
396
  subcommands: ICompletionMeta[];
376
397
  }
@@ -548,4 +569,4 @@ declare function getDefaultCommandRuntime(): ICommandRuntime;
548
569
  declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
549
570
 
550
571
  export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, setDefaultCommandRuntime, silentOption };
551
- 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 };
572
+ 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 };
@@ -0,0 +1,560 @@
1
+ import { IReporter } from '@guanghechen/reporter';
2
+
3
+ /**
4
+ * Type definitions for @guanghechen/commander
5
+ *
6
+ * @module @guanghechen/commander
7
+ */
8
+
9
+ /** Token type: long option, short option, or positional */
10
+ type ICommandTokenType = 'long' | 'short' | 'none';
11
+ /**
12
+ * Command token after preprocessing.
13
+ *
14
+ * - original: raw input for error messages (e.g., --LOG-LEVEL=info, -v)
15
+ * - resolved: normalized form (e.g., --logLevel=info, -v)
16
+ * - name: option name for matching (e.g., logLevel, v, '')
17
+ * - type: token type (long/short/none)
18
+ */
19
+ interface ICommandToken {
20
+ /** Raw input, used for error display */
21
+ original: string;
22
+ /** Normalized form, used for parsing */
23
+ resolved: string;
24
+ /** Option name for matching: camelCase for long, single char for short, '' for positional */
25
+ name: string;
26
+ /** Token type */
27
+ type: ICommandTokenType;
28
+ }
29
+ /** Option value type */
30
+ type ICommandOptionType = 'boolean' | 'number' | 'string';
31
+ /** Option argument mode */
32
+ type ICommandOptionArgs = 'none' | 'required' | 'variadic';
33
+ /**
34
+ * Option configuration.
35
+ *
36
+ * `type` and `args` must be specified together. Valid combinations:
37
+ * - boolean + none → boolean
38
+ * - string + required → string
39
+ * - number + required → number
40
+ * - string + variadic → string[]
41
+ * - number + variadic → number[]
42
+ *
43
+ * @template T - The type of the option value
44
+ */
45
+ interface ICommandOptionConfig<T = unknown> {
46
+ /** Long option name (camelCase, required) */
47
+ long: string;
48
+ /** Short option (single character) */
49
+ short?: string;
50
+ /** Value type (required) */
51
+ type: ICommandOptionType;
52
+ /** Argument mode (required) */
53
+ args: ICommandOptionArgs;
54
+ /** Description for help text */
55
+ desc: string;
56
+ /** Whether this option is required (mutually exclusive with default) */
57
+ required?: boolean;
58
+ /** Default value when not provided */
59
+ default?: T;
60
+ /** Allowed values for validation and completion */
61
+ choices?: T extends Array<infer U> ? U[] : T[];
62
+ /** Single value transformation (called for each value, before choices validation) */
63
+ coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
64
+ /** Callback after parsing, applies value to context */
65
+ apply?: (value: T, ctx: ICommandContext) => void;
66
+ }
67
+ /** Argument kind */
68
+ type ICommandArgumentKind = 'required' | 'optional' | 'variadic';
69
+ /** Argument value type */
70
+ type ICommandArgumentType = 'string' | 'number';
71
+ /**
72
+ * Positional argument configuration.
73
+ *
74
+ * Constraints:
75
+ * - required arguments must come before optional
76
+ * - variadic can only appear once, and must be last
77
+ * - required cannot have default
78
+ *
79
+ * @template T - The type of the argument value
80
+ */
81
+ interface ICommandArgumentConfig<T = unknown> {
82
+ /** Argument name */
83
+ name: string;
84
+ /** Argument description */
85
+ desc: string;
86
+ /** Argument kind: required / optional / variadic */
87
+ kind: ICommandArgumentKind;
88
+ /** Value type, defaults to 'string' */
89
+ type?: ICommandArgumentType;
90
+ /** Default value when not provided (only for optional arguments) */
91
+ default?: T;
92
+ /** Custom value transformation (takes precedence over type conversion) */
93
+ coerce?: (rawValue: string) => T;
94
+ }
95
+ interface ICommandBuiltinOptionConfig {
96
+ /** Enable built-in --version option (root only, requires configured version) */
97
+ version?: boolean;
98
+ /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
99
+ color?: boolean;
100
+ /** Enable built-in --log-level option */
101
+ logLevel?: boolean;
102
+ /** Enable built-in --silent option */
103
+ silent?: boolean;
104
+ /** Enable built-in --log-date/--no-log-date option */
105
+ logDate?: boolean;
106
+ /** Enable built-in --log-colorful/--no-log-colorful option */
107
+ logColorful?: boolean;
108
+ }
109
+ interface ICommandBuiltinConfig {
110
+ /** Built-in options configuration */
111
+ option?: boolean | ICommandBuiltinOptionConfig;
112
+ }
113
+ /** Command example configuration */
114
+ interface ICommandExample {
115
+ /** Example title */
116
+ title: string;
117
+ /** Usage fragment relative to command path */
118
+ usage: string;
119
+ /** Example description */
120
+ desc: string;
121
+ }
122
+ /** Command preset defaults */
123
+ interface ICommandPresetConfig {
124
+ /** Preset root directory (absolute path) */
125
+ root?: string;
126
+ /** Default preset options file */
127
+ opt?: string;
128
+ /** Default preset envs file */
129
+ env?: string;
130
+ }
131
+ /** Command configuration */
132
+ interface ICommandConfig {
133
+ /** Command name (only for root command) */
134
+ name?: string;
135
+ /** Command description */
136
+ desc: string;
137
+ /** Version (for built-in --version on this command) */
138
+ version?: string;
139
+ /** Built-in features configuration */
140
+ builtin?: boolean | ICommandBuiltinConfig;
141
+ /** Command-level preset defaults */
142
+ preset?: ICommandPresetConfig;
143
+ /** Default reporter for this command */
144
+ reporter?: IReporter;
145
+ }
146
+ /** Command interface */
147
+ interface ICommand {
148
+ readonly name: string | undefined;
149
+ readonly description: string;
150
+ readonly version: string | undefined;
151
+ readonly builtin: ICommandConfig['builtin'] | undefined;
152
+ readonly preset: ICommandPresetConfig | undefined;
153
+ readonly parent: ICommand | undefined;
154
+ readonly options: ICommandOptionConfig[];
155
+ readonly arguments: ICommandArgumentConfig[];
156
+ readonly examples: ICommandExample[];
157
+ readonly subcommands: Map<string, ICommand>;
158
+ }
159
+ /** Execution context */
160
+ interface ICommandContext {
161
+ /** Current command node */
162
+ cmd: ICommand;
163
+ /** Command chain from root to leaf */
164
+ chain: ICommand[];
165
+ /** Effective environment variables */
166
+ envs: Record<string, string | undefined>;
167
+ /** Built-in control hit status */
168
+ controls: ICommandControls;
169
+ /** Input source snapshots */
170
+ sources: ICommandInputSources;
171
+ /** Reporter instance */
172
+ reporter: IReporter;
173
+ }
174
+ /** Action callback parameters */
175
+ interface ICommandActionParams {
176
+ /** Execution context */
177
+ ctx: ICommandContext;
178
+ /** Parsed options (keyed by long name) */
179
+ opts: ICommandParsedOpts;
180
+ /** Parsed positional arguments (keyed by argument name) */
181
+ args: ICommandParsedArgs;
182
+ /** Raw positional argument strings (before type conversion) */
183
+ rawArgs: string[];
184
+ }
185
+ /** Action handler function */
186
+ type ICommandAction = (params: ICommandActionParams) => void | Promise<void>;
187
+ /** run() / parse() method parameters */
188
+ interface ICommandRunParams {
189
+ /** Command line arguments (usually process.argv.slice(2)) */
190
+ argv: string[];
191
+ /** Environment variables (usually process.env) */
192
+ envs: Record<string, string | undefined>;
193
+ /** Optional reporter override */
194
+ reporter?: IReporter;
195
+ }
196
+ /** Parsed options record */
197
+ type ICommandParsedOpts = Record<string, unknown>;
198
+ /** Parsed arguments record */
199
+ type ICommandParsedArgs = Record<string, unknown>;
200
+ /** Route stage result */
201
+ interface ICommandRouteResult<TCommand = ICommand> {
202
+ /** Command chain from root to leaf */
203
+ chain: TCommand[];
204
+ /** Remaining argv after routing */
205
+ remaining: string[];
206
+ /** Routed command tokens from user argv (name/alias) */
207
+ cmds: string[];
208
+ }
209
+ /** Control-scan stage result */
210
+ interface ICommandControlScanResult {
211
+ /** Built-in control hit status */
212
+ controls: ICommandControls;
213
+ /** Remaining argv after stripping control tokens */
214
+ remaining: string[];
215
+ /** Optional target token from `help <child>` syntax */
216
+ helpTarget?: string;
217
+ }
218
+ /** Preset stage result */
219
+ interface ICommandPresetResult {
220
+ /** Effective tail argv after preset merge */
221
+ tailArgv: string[];
222
+ /** Effective envs after preset merge */
223
+ envs: Record<string, string | undefined>;
224
+ }
225
+ /** Tokenize stage result */
226
+ interface ICommandTokenizeResult {
227
+ /** Option tokens (before --) */
228
+ optionTokens: ICommandToken[];
229
+ /** Arguments after -- */
230
+ restArgs: string[];
231
+ }
232
+ /** Resolve stage result */
233
+ interface ICommandResolveResult {
234
+ /** Tokens consumed by each command */
235
+ consumedTokens: Map<ICommand, ICommandToken[]>;
236
+ /** Argument tokens (non-option tokens) */
237
+ argTokens: ICommandToken[];
238
+ }
239
+ /** shift() method result (internal) */
240
+ interface ICommandShiftResult {
241
+ /** Tokens consumed by this command */
242
+ consumed: ICommandToken[];
243
+ /** Remaining tokens to pass to parent */
244
+ remaining: ICommandToken[];
245
+ }
246
+ /** Parse stage result */
247
+ interface ICommandParseResult {
248
+ /** Execution context */
249
+ ctx: ICommandContext;
250
+ /** Parsed options */
251
+ opts: ICommandParsedOpts;
252
+ /** Parsed arguments */
253
+ args: ICommandParsedArgs;
254
+ /** Raw argument strings */
255
+ rawArgs: string[];
256
+ }
257
+ /** Input source snapshots for debugging/tracing */
258
+ interface ICommandInputSources {
259
+ preset: {
260
+ argv: string[];
261
+ envs: Record<string, string>;
262
+ };
263
+ user: {
264
+ /** Routed command tokens (name/alias as entered by user) */
265
+ cmds: string[];
266
+ /** Clean user tail argv after removing command chain/control/preset directives */
267
+ argv: string[];
268
+ /** Raw env snapshot from run/parse params */
269
+ envs: Record<string, string | undefined>;
270
+ };
271
+ }
272
+ /** Built-in run controls */
273
+ interface ICommandControls {
274
+ help: boolean;
275
+ version: boolean;
276
+ }
277
+ /** Built-in option resolution result (internal) */
278
+ interface ICommandBuiltinOptionResolved {
279
+ version: boolean;
280
+ color: boolean;
281
+ logLevel: boolean;
282
+ silent: boolean;
283
+ logDate: boolean;
284
+ logColorful: boolean;
285
+ }
286
+ /** Built-in config resolution result (internal) */
287
+ interface ICommandBuiltinResolved {
288
+ option: ICommandBuiltinOptionResolved;
289
+ }
290
+ /** Subcommand registry entry (internal) */
291
+ interface ISubcommandEntry<TCommand = ICommand> {
292
+ name: string;
293
+ aliases: string[];
294
+ command: TCommand;
295
+ }
296
+ /** Help option line (internal) */
297
+ interface IHelpOptionLine {
298
+ sig: string;
299
+ desc: string;
300
+ }
301
+ /** Help command line (internal) */
302
+ interface IHelpCommandLine {
303
+ name: string;
304
+ desc: string;
305
+ }
306
+ /** Help example line (internal) */
307
+ interface IHelpExampleLine {
308
+ title: string;
309
+ usage: string;
310
+ desc: string;
311
+ }
312
+ /** Structured help data for rendering (internal) */
313
+ interface IHelpData {
314
+ desc: string;
315
+ usage: string;
316
+ options: IHelpOptionLine[];
317
+ commands: IHelpCommandLine[];
318
+ examples: IHelpExampleLine[];
319
+ }
320
+ /** Error kinds for command parsing */
321
+ type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
322
+ /** Commander error with structured information */
323
+ declare class CommanderError extends Error {
324
+ readonly kind: ICommanderErrorKind;
325
+ readonly commandPath: string;
326
+ constructor(kind: ICommanderErrorKind, message: string, commandPath: string);
327
+ /** Format error with help hint */
328
+ format(): string;
329
+ }
330
+ /** Shell type for completion */
331
+ type ICompletionShellType = 'bash' | 'fish' | 'pwsh';
332
+ /** Option metadata for completion */
333
+ interface ICompletionOptionMeta {
334
+ /** Long option name (camelCase) */
335
+ long: string;
336
+ /** Short option */
337
+ short?: string;
338
+ /** Description */
339
+ desc: string;
340
+ /** Whether option takes value (args !== 'none') */
341
+ takesValue: boolean;
342
+ /** Allowed values */
343
+ choices?: string[];
344
+ }
345
+ /** Command metadata for completion */
346
+ interface ICompletionMeta {
347
+ /** Command name */
348
+ name: string;
349
+ /** Description */
350
+ desc: string;
351
+ /** Command aliases */
352
+ aliases: string[];
353
+ /** Options */
354
+ options: ICompletionOptionMeta[];
355
+ /** Subcommands */
356
+ subcommands: ICompletionMeta[];
357
+ }
358
+ /** Shell completion paths configuration */
359
+ interface ICompletionPaths {
360
+ /** Bash completion file path */
361
+ bash: string;
362
+ /** Fish completion file path */
363
+ fish: string;
364
+ /** PowerShell completion file path */
365
+ pwsh: string;
366
+ }
367
+ /** CompletionCommand configuration */
368
+ interface ICompletionCommandConfig {
369
+ /** Program name for completion scripts (defaults to root.name) */
370
+ programName?: string;
371
+ /** Default completion file paths for each shell */
372
+ paths?: Partial<ICompletionPaths>;
373
+ }
374
+
375
+ /**
376
+ * Command class - CLI command builder with fluent API
377
+ *
378
+ * Execution flow: route → control-scan → run-control(run) → preset → tokenize → resolve → parse → run
379
+ *
380
+ * @module @guanghechen/commander
381
+ */
382
+
383
+ declare class Command implements ICommand {
384
+ #private;
385
+ constructor(config: ICommandConfig);
386
+ get name(): string | undefined;
387
+ get description(): string;
388
+ get version(): string | undefined;
389
+ get builtin(): ICommandConfig['builtin'] | undefined;
390
+ get preset(): ICommandPresetConfig | undefined;
391
+ get parent(): Command | undefined;
392
+ get options(): ICommandOptionConfig[];
393
+ get arguments(): ICommandArgumentConfig[];
394
+ get examples(): ICommandExample[];
395
+ get subcommands(): Map<string, ICommand>;
396
+ option<T>(opt: ICommandOptionConfig<T>): this;
397
+ argument<T>(arg: ICommandArgumentConfig<T>): this;
398
+ action(fn: ICommandAction): this;
399
+ example(title: string, usage: string, desc: string): this;
400
+ subcommand(name: string, cmd: Command): this;
401
+ run(params: ICommandRunParams): Promise<void>;
402
+ parse(params: ICommandRunParams): Promise<ICommandParseResult>;
403
+ formatHelp(): string;
404
+ getCompletionMeta(): ICompletionMeta;
405
+ }
406
+
407
+ /**
408
+ * Pre-defined coerce factory methods for @guanghechen/commander.
409
+ *
410
+ * @module @guanghechen/commander/coerce
411
+ */
412
+ declare class Coerce {
413
+ private constructor();
414
+ private static create;
415
+ static choice<TValue extends string>(name: string, values: ReadonlyArray<TValue>, errorMessage?: string): (rawValue: string) => TValue;
416
+ static domain(name: string, errorMessage?: string): (rawValue: string) => string;
417
+ static host(name: string, errorMessage?: string): (rawValue: string) => string;
418
+ static integer(name: string, errorMessage?: string): (rawValue: string) => number;
419
+ static ip(name: string, errorMessage?: string): (rawValue: string) => string;
420
+ static number(name: string, errorMessage?: string): (rawValue: string) => number;
421
+ static port(name: string, errorMessage?: string): (rawValue: string) => number;
422
+ static positiveInteger(name: string, errorMessage?: string): (rawValue: string) => number;
423
+ static positiveNumber(name: string, errorMessage?: string): (rawValue: string) => number;
424
+ }
425
+
426
+ declare function isIpv4(rawValue: string): boolean;
427
+ declare function isIpv6(rawValue: string): boolean;
428
+ declare function isIp(rawValue: string): boolean;
429
+ declare function isDomain(rawValue: string): boolean;
430
+
431
+ /**
432
+ * Shell completion generators
433
+ *
434
+ * @module @guanghechen/commander
435
+ */
436
+
437
+ /**
438
+ * Built-in completion command that generates shell completion scripts.
439
+ *
440
+ * @example
441
+ * ```typescript
442
+ * const root = new Command({ name: 'mycli', desc: 'My CLI' })
443
+ * root.subcommand('completion', new CompletionCommand(root, {
444
+ * paths: {
445
+ * bash: `~/.local/share/bash-completion/completions/mycli`,
446
+ * fish: `~/.config/fish/completions/mycli.fish`,
447
+ * pwsh: `~/.config/powershell/Microsoft.PowerShell_profile.ps1`,
448
+ * }
449
+ * }))
450
+ *
451
+ * // Usage:
452
+ * // mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
453
+ * // mycli completion --fish --write (writes to default path)
454
+ * // mycli completion --fish --write /custom/path.fish
455
+ * ```
456
+ */
457
+ declare class CompletionCommand extends Command {
458
+ constructor(root: Command, config?: ICompletionCommandConfig);
459
+ }
460
+ declare class BashCompletion {
461
+ #private;
462
+ constructor(meta: ICompletionMeta, programName: string);
463
+ generate(): string;
464
+ }
465
+ declare class FishCompletion {
466
+ #private;
467
+ constructor(meta: ICompletionMeta, programName: string);
468
+ generate(): string;
469
+ }
470
+ declare class PwshCompletion {
471
+ #private;
472
+ constructor(meta: ICompletionMeta, programName: string);
473
+ generate(): string;
474
+ }
475
+
476
+ /**
477
+ * Pre-defined common options for @guanghechen/commander
478
+ *
479
+ * @module @guanghechen/commander/options
480
+ */
481
+
482
+ /**
483
+ * Pre-defined --log-level option for setting log verbosity.
484
+ *
485
+ * Supports: debug | info | hint | warn | error (case-insensitive)
486
+ *
487
+ * | Property | Value |
488
+ * | --------- | ---------------------------------- |
489
+ * | long | 'logLevel' |
490
+ * | type | 'string' |
491
+ * | args | 'required' |
492
+ * | default | 'info' |
493
+ * | choices | LOG_LEVELS |
494
+ * | coerce | resolveLogLevel (case-insensitive) |
495
+ * | apply | ctx.reporter.setLevel(value) |
496
+ *
497
+ * @example
498
+ * ```typescript
499
+ * import { logLevelOption } from '@guanghechen/commander'
500
+ *
501
+ * const cmd = new Command('app')
502
+ * .option(logLevelOption)
503
+ * .action(({ opts }) => {
504
+ * console.log(opts.logLevel) // 'debug' | 'info' | 'hint' | 'warn' | 'error'
505
+ * })
506
+ *
507
+ * // Override with spread syntax
508
+ * .option({ ...logLevelOption, default: 'warn' })
509
+ * ```
510
+ */
511
+ declare const logLevelOption: ICommandOptionConfig<string>;
512
+ /**
513
+ * Pre-defined --log-date option for controlling timestamp output.
514
+ *
515
+ * | Property | Value |
516
+ * | --------- | --------- |
517
+ * | long | 'logDate' |
518
+ * | type | 'boolean' |
519
+ * | args | 'none' |
520
+ * | default | true |
521
+ */
522
+ declare const logDateOption: ICommandOptionConfig<boolean>;
523
+ /**
524
+ * Pre-defined --log-colorful option for controlling colorful output.
525
+ *
526
+ * | Property | Value |
527
+ * | --------- | ------------- |
528
+ * | long | 'logColorful' |
529
+ * | type | 'boolean' |
530
+ * | args | 'none' |
531
+ * | default | true |
532
+ */
533
+ declare const logColorfulOption: ICommandOptionConfig<boolean>;
534
+ /**
535
+ * Pre-defined --silent option for suppressing non-error output.
536
+ *
537
+ * | Property | Value |
538
+ * | --------- | --------- |
539
+ * | long | 'silent' |
540
+ * | type | 'boolean' |
541
+ * | args | 'none' |
542
+ * | default | false |
543
+ *
544
+ * @example
545
+ * ```typescript
546
+ * import { silentOption } from '@guanghechen/commander'
547
+ *
548
+ * const cmd = new Command('app')
549
+ * .option(silentOption)
550
+ * .action(({ opts }) => {
551
+ * if (!opts.silent) {
552
+ * console.log('Processing...')
553
+ * }
554
+ * })
555
+ * ```
556
+ */
557
+ declare const silentOption: ICommandOptionConfig<boolean>;
558
+
559
+ export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };
560
+ 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 };