@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.
- package/CHANGELOG.md +14 -0
- package/lib/cjs/browser.cjs +290 -42
- package/lib/cjs/index.cjs +2089 -0
- package/lib/cjs/node.cjs +598 -54
- package/lib/esm/browser.mjs +290 -42
- package/lib/esm/index.mjs +2054 -0
- package/lib/esm/node.mjs +598 -54
- package/lib/types/browser.d.ts +27 -6
- package/lib/types/index.d.ts +560 -0
- package/lib/types/node.d.ts +27 -6
- package/package.json +3 -3
package/lib/types/browser.d.ts
CHANGED
|
@@ -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' | '
|
|
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
|
|
89
|
-
type
|
|
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 (
|
|
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 };
|