@gunshi/bone 1.0.0-beta.2 → 1.0.0-rc.10
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/README.md +0 -6
- package/lib/index.d.ts +407 -63
- package/lib/index.js +627 -265
- package/package.json +32 -38
package/lib/index.d.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The key of the mark on the `json` argument of `jsonArgs`. A string key, not a symbol: `gunshi` and the other
|
|
3
|
+
* packages bundle their own copies of the types, and each copy of a `unique symbol` is a different type.
|
|
4
|
+
*
|
|
5
|
+
* @internal
|
|
6
|
+
*/
|
|
7
|
+
declare const JSON_ARG = "~gunshi.json-arg";
|
|
3
8
|
/**
|
|
4
9
|
* Entry point of argument parser.
|
|
5
10
|
*
|
|
@@ -55,14 +60,11 @@ interface ArgToken {
|
|
|
55
60
|
*/
|
|
56
61
|
inlineValue?: boolean | undefined;
|
|
57
62
|
}
|
|
58
|
-
//#endregion
|
|
59
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
|
|
60
|
-
//#region src/resolver.d.ts
|
|
61
63
|
/**
|
|
62
64
|
* An argument schema definition for command-line argument parsing.
|
|
63
65
|
*
|
|
64
66
|
* This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
|
|
65
|
-
* - Additional `required`, `description`, and `
|
|
67
|
+
* - Additional `required`, `description`, `hidden`, and `deprecated` properties
|
|
66
68
|
* - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
|
|
67
69
|
* - Simplified `default` property (single type, not union types)
|
|
68
70
|
*
|
|
@@ -192,6 +194,32 @@ interface ArgSchema {
|
|
|
192
194
|
* ```
|
|
193
195
|
*/
|
|
194
196
|
hidden?: boolean;
|
|
197
|
+
/**
|
|
198
|
+
* Mark the argument as deprecated: `true`, or a text that tells what to use instead, such as
|
|
199
|
+
* `'Use --output.'`.
|
|
200
|
+
*
|
|
201
|
+
* Like {@link ArgSchema.hidden}, this is metadata for the tools that read the schema, such as a CLI
|
|
202
|
+
* framework that warns when a deprecated argument is given and leaves it out of the help. It does
|
|
203
|
+
* not affect parsing, validation, required checks, defaults, conflicts, or resolved values: a
|
|
204
|
+
* deprecated argument still works. `false`, like leaving it out, means that the argument is not
|
|
205
|
+
* deprecated.
|
|
206
|
+
*
|
|
207
|
+
* @example
|
|
208
|
+
* The old name of an option, kept while the scripts that use it move to the new one:
|
|
209
|
+
* ```ts
|
|
210
|
+
* {
|
|
211
|
+
* output: {
|
|
212
|
+
* type: 'string',
|
|
213
|
+
* description: 'Output format'
|
|
214
|
+
* },
|
|
215
|
+
* format: {
|
|
216
|
+
* type: 'string',
|
|
217
|
+
* deprecated: 'Use --output.'
|
|
218
|
+
* }
|
|
219
|
+
* }
|
|
220
|
+
* ```
|
|
221
|
+
*/
|
|
222
|
+
deprecated?: boolean | string;
|
|
195
223
|
/**
|
|
196
224
|
* Marks the argument as required.
|
|
197
225
|
*
|
|
@@ -419,9 +447,9 @@ interface ArgSchema {
|
|
|
419
447
|
*/
|
|
420
448
|
toKebab?: true;
|
|
421
449
|
/**
|
|
422
|
-
* Names of other
|
|
450
|
+
* Names of other arguments that conflict with this argument.
|
|
423
451
|
*
|
|
424
|
-
* When this
|
|
452
|
+
* When this argument is used together with any of the conflicting arguments, the error is an
|
|
425
453
|
* `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
|
|
426
454
|
* ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
|
|
427
455
|
* the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
|
|
@@ -431,9 +459,8 @@ interface ArgSchema {
|
|
|
431
459
|
*
|
|
432
460
|
* A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
|
|
433
461
|
* it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as
|
|
434
|
-
* in its other errors. The message
|
|
435
|
-
* `
|
|
436
|
-
* `Optional argument '--stdin' conflicts with 'file'`.
|
|
462
|
+
* in its other errors. The message names the argument given as `name` first:
|
|
463
|
+
* `'file' conflicts with '--stdin'` or `'--stdin' conflicts with 'file'`.
|
|
437
464
|
*
|
|
438
465
|
* Conflicts only need to be defined on one side - if option A defines a conflict
|
|
439
466
|
* with option B, the conflict is automatically detected when both are used,
|
|
@@ -472,7 +499,7 @@ interface ArgSchema {
|
|
|
472
499
|
* }
|
|
473
500
|
* }
|
|
474
501
|
* // Usage: --summer --autumn reports an error
|
|
475
|
-
* // Error: "
|
|
502
|
+
* // Error: "'--summer' conflicts with '--autumn'"
|
|
476
503
|
* ```
|
|
477
504
|
*
|
|
478
505
|
* @example
|
|
@@ -512,7 +539,7 @@ interface ArgSchema {
|
|
|
512
539
|
* toKebab: true // Accessible as --autumn-season
|
|
513
540
|
* }
|
|
514
541
|
* }
|
|
515
|
-
* // Error: "
|
|
542
|
+
* // Error: "'--summer-season' conflicts with '--autumn-season'"
|
|
516
543
|
* ```
|
|
517
544
|
*/
|
|
518
545
|
conflicts?: string | string[];
|
|
@@ -698,8 +725,6 @@ type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] ex
|
|
|
698
725
|
* @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
|
|
699
726
|
*/
|
|
700
727
|
type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean; };
|
|
701
|
-
//#endregion
|
|
702
|
-
//#region ../gunshi/src/plugin/context.d.ts
|
|
703
728
|
/**
|
|
704
729
|
* Gunshi plugin context interface.
|
|
705
730
|
*
|
|
@@ -733,7 +758,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
733
758
|
* @param name - Command name
|
|
734
759
|
* @param command - Command definition
|
|
735
760
|
*/
|
|
736
|
-
addCommand(name: string, command:
|
|
761
|
+
addCommand(name: string, command: SubCommandable): void;
|
|
737
762
|
/**
|
|
738
763
|
* Check if a command exists.
|
|
739
764
|
*
|
|
@@ -774,10 +799,8 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
774
799
|
*
|
|
775
800
|
* @param decorator - A decorator function that wraps the command runner
|
|
776
801
|
*/
|
|
777
|
-
decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
|
|
802
|
+
decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string | JsonResult>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string | JsonResult>): void;
|
|
778
803
|
}
|
|
779
|
-
//#endregion
|
|
780
|
-
//#region ../gunshi/src/plugin/core.d.ts
|
|
781
804
|
/**
|
|
782
805
|
* Plugin dependency definition
|
|
783
806
|
*
|
|
@@ -818,8 +841,6 @@ type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensio
|
|
|
818
841
|
dependencies?: (PluginDependency | string)[];
|
|
819
842
|
extension?: CommandContextExtension<E>;
|
|
820
843
|
};
|
|
821
|
-
//#endregion
|
|
822
|
-
//#region ../gunshi/src/types.d.ts
|
|
823
844
|
/**
|
|
824
845
|
* Awaitable type.
|
|
825
846
|
*
|
|
@@ -961,7 +982,7 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
961
982
|
*/
|
|
962
983
|
cwd: string | undefined;
|
|
963
984
|
/**
|
|
964
|
-
*
|
|
985
|
+
* The name of the CLI, given to `cli()` as `name`.
|
|
965
986
|
*
|
|
966
987
|
* @see {@linkcode CliOptions.name}
|
|
967
988
|
*/
|
|
@@ -1011,7 +1032,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1011
1032
|
* (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
|
|
1012
1033
|
*
|
|
1013
1034
|
* Output that must still appear — machine-readable results for an agent, warnings for the
|
|
1014
|
-
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
|
|
1035
|
+
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
|
|
1036
|
+
* `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
|
|
1037
|
+
*
|
|
1038
|
+
* The validation errors, and a `CommandError` that the command throws, are not printed either, so
|
|
1039
|
+
* `cli()` rejects with them, for the caller to report them.
|
|
1015
1040
|
*
|
|
1016
1041
|
* @default false
|
|
1017
1042
|
* @see {@linkcode CliOptions.usageSilent}
|
|
@@ -1020,10 +1045,32 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1020
1045
|
/**
|
|
1021
1046
|
* Whether to treat undefined options as argument validation errors.
|
|
1022
1047
|
*
|
|
1023
|
-
* @default
|
|
1048
|
+
* @default true
|
|
1024
1049
|
* @see {@linkcode CliOptions.strict}
|
|
1025
1050
|
*/
|
|
1026
1051
|
strict: boolean;
|
|
1052
|
+
/**
|
|
1053
|
+
* Whether to treat the positional arguments that the command does not take as argument validation errors.
|
|
1054
|
+
*
|
|
1055
|
+
* @default false
|
|
1056
|
+
* @see {@linkcode CliOptions.strictPositionals}
|
|
1057
|
+
*/
|
|
1058
|
+
strictPositionals: boolean;
|
|
1059
|
+
/**
|
|
1060
|
+
* Whether to follow the validation errors with the command that shows the help.
|
|
1061
|
+
*
|
|
1062
|
+
* @default true
|
|
1063
|
+
* @see {@linkcode CliOptions.helpHint}
|
|
1064
|
+
*/
|
|
1065
|
+
helpHint: boolean;
|
|
1066
|
+
/**
|
|
1067
|
+
* The exit code of the validation errors. A command can give it to a `CommandError`, to end an
|
|
1068
|
+
* argument error that it finds itself with the same exit code.
|
|
1069
|
+
*
|
|
1070
|
+
* @default 1
|
|
1071
|
+
* @see {@linkcode CliOptions.validationErrorExitCode}
|
|
1072
|
+
*/
|
|
1073
|
+
validationErrorExitCode: number;
|
|
1027
1074
|
/**
|
|
1028
1075
|
* Sub commands.
|
|
1029
1076
|
*
|
|
@@ -1034,7 +1081,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1034
1081
|
* The entry command of the CLI, marked with `entry: true`.
|
|
1035
1082
|
*
|
|
1036
1083
|
* It is available whether or not the CLI has sub-commands, while {@linkcode CommandEnvironment.subCommands}
|
|
1037
|
-
* includes the entry command only when the sub-commands
|
|
1084
|
+
* includes the entry command only when the CLI has sub-commands, given with {@linkcode CliOptions.subCommands}
|
|
1085
|
+
* or with {@linkcode Command.subCommands} of the entry command.
|
|
1038
1086
|
* It is not frozen, like the commands in {@linkcode CommandEnvironment.subCommands}.
|
|
1039
1087
|
*/
|
|
1040
1088
|
entryCommand?: Command<any> | LazyCommand<any>;
|
|
@@ -1070,7 +1118,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1070
1118
|
*/
|
|
1071
1119
|
onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
|
|
1072
1120
|
/**
|
|
1073
|
-
* Hook that runs after successful command execution
|
|
1121
|
+
* Hook that runs after successful command execution. It receives the result of the command only
|
|
1122
|
+
* when it is a string.
|
|
1074
1123
|
*
|
|
1075
1124
|
* @see {@linkcode CliOptions.onAfterCommand}
|
|
1076
1125
|
* @since v0.27.0
|
|
@@ -1095,7 +1144,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1095
1144
|
*/
|
|
1096
1145
|
cwd?: string;
|
|
1097
1146
|
/**
|
|
1098
|
-
*
|
|
1147
|
+
* The name of the CLI, as it is run, such as `todo`.
|
|
1148
|
+
*
|
|
1149
|
+
* The usage line and the help as JSON start with it, and so do the command that the errors point to
|
|
1150
|
+
* for the help and `next` of the errors of `--json`. Without it, the usage line starts with `COMMAND`,
|
|
1151
|
+
* and the others with `<COMMAND>`, a placeholder for how the CLI was run.
|
|
1099
1152
|
*/
|
|
1100
1153
|
name?: string;
|
|
1101
1154
|
/**
|
|
@@ -1109,8 +1162,13 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1109
1162
|
version?: string;
|
|
1110
1163
|
/**
|
|
1111
1164
|
* Sub commands.
|
|
1165
|
+
*
|
|
1166
|
+
* An object or a Map keyed by the sub-command names, or an array of commands, which are keyed by their names.
|
|
1167
|
+
* A value of the object or the Map may also be a loader, a function that returns the command or its runner,
|
|
1168
|
+
* which runs as a lazy command named after its key.
|
|
1169
|
+
* When this is not given, the {@linkcode Command.subCommands} of the entry command are the sub-commands.
|
|
1112
1170
|
*/
|
|
1113
|
-
subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable
|
|
1171
|
+
subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
|
|
1114
1172
|
/**
|
|
1115
1173
|
* Left margin of the command output.
|
|
1116
1174
|
*/
|
|
@@ -1132,7 +1190,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1132
1190
|
* (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
|
|
1133
1191
|
*
|
|
1134
1192
|
* Output that must still appear — machine-readable results for an agent, warnings for the
|
|
1135
|
-
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
|
|
1193
|
+
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
|
|
1194
|
+
* `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
|
|
1195
|
+
*
|
|
1196
|
+
* The validation errors, and a `CommandError` that the command throws, are not printed either, so
|
|
1197
|
+
* `cli()` rejects with them, for the caller to report them (see
|
|
1198
|
+
* {@linkcode CliOptions.renderValidationErrors}). The exit code is left alone.
|
|
1136
1199
|
*
|
|
1137
1200
|
* @default false
|
|
1138
1201
|
*/
|
|
@@ -1140,13 +1203,40 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1140
1203
|
/**
|
|
1141
1204
|
* Whether to treat undefined options as argument validation errors.
|
|
1142
1205
|
*
|
|
1143
|
-
*
|
|
1144
|
-
*
|
|
1145
|
-
*
|
|
1206
|
+
* By default, option tokens that are not declared by the resolved command arguments or installed global
|
|
1207
|
+
* options are reported as validation errors before the command runner is executed, such as
|
|
1208
|
+
* `Unknown option: --alow-reload`. Set it to `false` to ignore them, and run the command, such as for a
|
|
1209
|
+
* command that passes its arguments as they are to another program. The arguments after `--` are not
|
|
1210
|
+
* option tokens: they stay in `rest` either way.
|
|
1146
1211
|
*
|
|
1147
|
-
*
|
|
1212
|
+
* With the global options plugin, `--help` and `--version` are still answered: given with them, an
|
|
1213
|
+
* unknown option is not reported, as the other argument validation errors are not. An unknown command
|
|
1214
|
+
* is still reported.
|
|
1215
|
+
*
|
|
1216
|
+
* `--json` is not reported, since gunshi knows what it means: given to a command that does not
|
|
1217
|
+
* spread `jsonArgs`, the global options plugin reports `json_not_supported` for it instead, with or
|
|
1218
|
+
* without `strict`. `--json=false` asks for no JSON, and is reported.
|
|
1219
|
+
*
|
|
1220
|
+
* @default true
|
|
1148
1221
|
*/
|
|
1149
1222
|
strict?: boolean;
|
|
1223
|
+
/**
|
|
1224
|
+
* Whether to treat the positional arguments that the command does not take as argument validation
|
|
1225
|
+
* errors, as `strict` does for the options.
|
|
1226
|
+
*
|
|
1227
|
+
* When enabled, the positional arguments after the command path that the positional arguments of the
|
|
1228
|
+
* resolved command do not take are reported as validation errors before the command runner is
|
|
1229
|
+
* executed. A command takes as many as it declares, an optional one included, and any number with a
|
|
1230
|
+
* positional argument with `multiple: true`. The arguments after `--` are not positional arguments:
|
|
1231
|
+
* they stay in `rest`.
|
|
1232
|
+
*
|
|
1233
|
+
* With the global options plugin, `--help` and `--version` are still answered, as they are with the
|
|
1234
|
+
* other argument validation errors. After a command with sub-commands, a word that is not one of them
|
|
1235
|
+
* is reported as an unknown command instead.
|
|
1236
|
+
*
|
|
1237
|
+
* @default false
|
|
1238
|
+
*/
|
|
1239
|
+
strictPositionals?: boolean;
|
|
1150
1240
|
/**
|
|
1151
1241
|
* Render function the command usage.
|
|
1152
1242
|
*/
|
|
@@ -1157,11 +1247,62 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1157
1247
|
renderHeader?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
|
|
1158
1248
|
/**
|
|
1159
1249
|
* Render function the validation errors.
|
|
1250
|
+
*
|
|
1251
|
+
* With the global options plugin, the rendered message is printed to stderr, the exit code is set
|
|
1252
|
+
* to {@linkcode CliOptions.validationErrorExitCode}, `1` by default,
|
|
1253
|
+
* {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
|
|
1254
|
+
* The message is followed by the command that shows the help, unless {@linkcode CliOptions.helpHint}
|
|
1255
|
+
* is `false`.
|
|
1256
|
+
* Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
|
|
1257
|
+
* with the `AggregateError`. A renderer that returns an empty message, and
|
|
1258
|
+
* {@linkcode CliOptions.usageSilent}, also leave them to the caller.
|
|
1259
|
+
*
|
|
1260
|
+
* With `--json`, the plugin prints the validation errors as one line of JSON, and does not call
|
|
1261
|
+
* the renderer. `null` and {@linkcode CliOptions.usageSilent} still leave them to the caller.
|
|
1160
1262
|
*/
|
|
1161
1263
|
renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
|
|
1264
|
+
/**
|
|
1265
|
+
* Whether to follow the validation errors with the command that shows the help of the nearest
|
|
1266
|
+
* command: the command itself for an argument error, and the parent of an unknown command, such as
|
|
1267
|
+
* `my-app deploy --help`. With the global options plugin, it is printed to stderr after the errors,
|
|
1268
|
+
* after an empty line and a heading. It is the command that `next` of the JSON error has with
|
|
1269
|
+
* `--json`.
|
|
1270
|
+
*
|
|
1271
|
+
* Set it to `false` to leave the command out, such as when your renderer of the validation errors
|
|
1272
|
+
* points to the help in its own way. It changes the output for people only: `next` of the JSON error
|
|
1273
|
+
* stays. The command is left out for a command whose `--help` does not show the help, too: one that
|
|
1274
|
+
* declares a `help` argument of its own, or with `renderUsage: null`.
|
|
1275
|
+
*
|
|
1276
|
+
* @default true
|
|
1277
|
+
*/
|
|
1278
|
+
helpHint?: boolean;
|
|
1279
|
+
/**
|
|
1280
|
+
* The exit code of the validation errors, such as `2`, the exit code of a usage error in many
|
|
1281
|
+
* command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown
|
|
1282
|
+
* command or a command line that cannot be resolved, an unknown option, unless `strict` is `false`, a
|
|
1283
|
+
* positional argument that the command does not take, only with `strictPositionals`, and `--json`
|
|
1284
|
+
* given to a command that does not spread `jsonArgs`. With the global options plugin, the exit code is set
|
|
1285
|
+
* to it when the errors are printed, as text or as JSON, before {@linkcode CliOptions.onErrorCommand} is
|
|
1286
|
+
* called, which can still change it.
|
|
1287
|
+
*
|
|
1288
|
+
* It is an integer from `1` to `255`, as the `exitCode` of a `CommandError` is, and any other value is
|
|
1289
|
+
* replaced with `1`. It does not change the exit code of a `CommandError`, nor of any other error that a
|
|
1290
|
+
* command throws. With `renderValidationErrors: null`, a renderer that returns an empty message, or
|
|
1291
|
+
* {@linkcode CliOptions.usageSilent}, nothing is printed, and the exit code is left alone.
|
|
1292
|
+
*
|
|
1293
|
+
* @default 1
|
|
1294
|
+
*/
|
|
1295
|
+
validationErrorExitCode?: number;
|
|
1162
1296
|
/**
|
|
1163
1297
|
* Whether to fallback to entry command when the sub-command is not found.
|
|
1164
1298
|
*
|
|
1299
|
+
* When it is not set, it is `true` for a CLI that declares no sub-commands and to which a plugin adds
|
|
1300
|
+
* commands, such as the `complete` command of `@gunshi/plugin-completion`, so that the positional
|
|
1301
|
+
* arguments of the entry command are not taken for command names. This is so when the entry command
|
|
1302
|
+
* has something to run: a command object with `run`, a lazy command, whose loader gives the runner,
|
|
1303
|
+
* or a runner given to `cli()`. For a command object without `run`, it stays `false`: the commands of
|
|
1304
|
+
* the plugins are then the commands of the CLI, and an argument that is not one of them is reported.
|
|
1305
|
+
*
|
|
1165
1306
|
* @default false
|
|
1166
1307
|
* @since v0.27.0
|
|
1167
1308
|
*/
|
|
@@ -1183,15 +1324,21 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1183
1324
|
* Hook that runs after successful command execution
|
|
1184
1325
|
*
|
|
1185
1326
|
* @param ctx - The command context
|
|
1186
|
-
* @param result - The command
|
|
1327
|
+
* @param result - The result of the command, when it is a string. The result of a command that
|
|
1328
|
+
* prints JSON with `--json` is printed, not passed, so it is `undefined`
|
|
1187
1329
|
* @since v0.27.0
|
|
1188
1330
|
*/
|
|
1189
1331
|
onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
|
|
1190
1332
|
/**
|
|
1191
|
-
* Hook that runs when a command throws an error
|
|
1333
|
+
* Hook that runs when a command throws an error, or when the arguments fail validation
|
|
1334
|
+
*
|
|
1335
|
+
* For the validation errors and a `CommandError` that the global options plugin has printed, the
|
|
1336
|
+
* exit code is already set when the hook runs ({@linkcode CliOptions.validationErrorExitCode} for the
|
|
1337
|
+
* validation errors, and the `exitCode` of a `CommandError`), so the hook can set another one, and
|
|
1338
|
+
* `cli()` resolves after it. Any other error rejects `cli()` after the hook.
|
|
1192
1339
|
*
|
|
1193
1340
|
* @param ctx - The command context
|
|
1194
|
-
* @param error - The error thrown during execution
|
|
1341
|
+
* @param error - The error thrown during execution, or the `AggregateError` of the validation errors
|
|
1195
1342
|
* @since v0.27.0
|
|
1196
1343
|
*/
|
|
1197
1344
|
onErrorCommand?: (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>;
|
|
@@ -1246,8 +1393,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1246
1393
|
*/
|
|
1247
1394
|
values: ArgValues<ExtractArgs<G>>;
|
|
1248
1395
|
/**
|
|
1249
|
-
*
|
|
1250
|
-
*
|
|
1396
|
+
* The positional arguments of the command line, the names of the command path first: `app deploy web`
|
|
1397
|
+
* gives `['deploy', 'web']`. The positional arguments of the command itself are
|
|
1398
|
+
* `positionals.slice(commandPath.length)`, and the ones that it declares are in `values` too.
|
|
1251
1399
|
*/
|
|
1252
1400
|
positionals: string[];
|
|
1253
1401
|
/**
|
|
@@ -1265,6 +1413,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1265
1413
|
tokens: ArgToken[];
|
|
1266
1414
|
/**
|
|
1267
1415
|
* Whether the currently executing command has been executed with the sub-command name omitted.
|
|
1416
|
+
*
|
|
1417
|
+
* A command that has sub-commands and no {@linkcode Command.run | run} prints its usage then, with
|
|
1418
|
+
* the global options plugin, as `--help` does.
|
|
1268
1419
|
*/
|
|
1269
1420
|
omitted: boolean;
|
|
1270
1421
|
/**
|
|
@@ -1287,9 +1438,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1287
1438
|
*/
|
|
1288
1439
|
toKebab?: boolean;
|
|
1289
1440
|
/**
|
|
1290
|
-
* Output a message.
|
|
1441
|
+
* Output a message for people.
|
|
1291
1442
|
*
|
|
1292
|
-
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
|
|
1443
|
+
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output. Nor is it when a
|
|
1444
|
+
* command that spreads `jsonArgs` is asked for JSON with `--json`, so that stdout has the JSON only:
|
|
1445
|
+
* the hooks and the plugins get the same function.
|
|
1293
1446
|
*
|
|
1294
1447
|
* @param message - an output message, see {@linkcode console.log}
|
|
1295
1448
|
* @param optionalParams - an optional parameters, see {@linkcode console.log}
|
|
@@ -1360,9 +1513,11 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
|
|
|
1360
1513
|
usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
|
|
1361
1514
|
/**
|
|
1362
1515
|
* Validation errors rendering configuration
|
|
1363
|
-
* - `null`: Disable rendering
|
|
1516
|
+
* - `null`: Disable rendering. `cli()` rejects with the validation errors, for the caller to report them
|
|
1364
1517
|
* - `function`: Use custom renderer
|
|
1365
1518
|
* - `undefined` (when omitted): Use default renderer
|
|
1519
|
+
*
|
|
1520
|
+
* See {@linkcode CliOptions.renderValidationErrors} for where the rendered message goes.
|
|
1366
1521
|
*/
|
|
1367
1522
|
validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
|
|
1368
1523
|
}
|
|
@@ -1394,6 +1549,14 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1394
1549
|
examples?: string | CommandExamplesFetcher<G>;
|
|
1395
1550
|
/**
|
|
1396
1551
|
* Command runner. it's the command to be executed
|
|
1552
|
+
*
|
|
1553
|
+
* A command that has sub-commands needs no runner: run without a sub-command, it prints its usage,
|
|
1554
|
+
* with the global options plugin, as `--help` does. A command with a runner runs it then, with
|
|
1555
|
+
* {@linkcode CommandContext.omitted | omitted} set to `true`.
|
|
1556
|
+
*
|
|
1557
|
+
* A command without sub-commands needs a runner. Without one, it throws a `TypeError` when it runs
|
|
1558
|
+
* (`'run' is required in command: <name>`), and `--help` still prints its usage. So does a lazy command
|
|
1559
|
+
* whose loader returns a command without a runner.
|
|
1397
1560
|
*/
|
|
1398
1561
|
run?: CommandRunner<G>;
|
|
1399
1562
|
/**
|
|
@@ -1409,6 +1572,34 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1409
1572
|
* @since v0.27.0
|
|
1410
1573
|
*/
|
|
1411
1574
|
internal?: boolean;
|
|
1575
|
+
/**
|
|
1576
|
+
* Other names of the command, such as `['ls']` for `list`.
|
|
1577
|
+
*
|
|
1578
|
+
* The command runs with any of them, as with its name, and `ctx.name` and `ctx.commandPath` have its name:
|
|
1579
|
+
* the help, the hints and the help as JSON tell the name of the command. An alias is accepted but not taught:
|
|
1580
|
+
* the help does not list it, and the `Did you mean` hint for an unknown command and shell completion do not
|
|
1581
|
+
* offer it.
|
|
1582
|
+
*
|
|
1583
|
+
* A sub-command whose name is the alias wins over the alias, so an alias never hides a command. Two commands
|
|
1584
|
+
* at the same level with the same alias are a mistake: using the alias throws a `TypeError`. A lazy command
|
|
1585
|
+
* takes its aliases from the definition given to `lazy`, as it is found before it is loaded.
|
|
1586
|
+
*/
|
|
1587
|
+
aliases?: readonly string[];
|
|
1588
|
+
/**
|
|
1589
|
+
* Whether the command is deprecated: `true`, or the text that tells what to use instead, such as `'Use deploy.'`.
|
|
1590
|
+
*
|
|
1591
|
+
* A deprecated command still runs. With the global options plugin, it prints a warning to stderr when it runs,
|
|
1592
|
+
* once: `push is deprecated. Use deploy.`, and not when the command is asked for JSON with `--json`. A command
|
|
1593
|
+
* under a deprecated group, such as the old name of a renamed group, warns of the group too. Its help says that
|
|
1594
|
+
* it is deprecated, after its description. As an internal command, it is left out of the help, the
|
|
1595
|
+
* `Did you mean` hint for an unknown command, shell completion and the help as JSON, so that they teach what to
|
|
1596
|
+
* use instead.
|
|
1597
|
+
*
|
|
1598
|
+
* To rename a command, keep the old name as a deprecated command that runs as the new one, such as
|
|
1599
|
+
* `push: define({ ...deploy, name: 'push', aliases: [], deprecated: 'Use deploy.' })`, where `aliases: []` takes
|
|
1600
|
+
* the aliases that the spread copies off the old name. It has no effect on the entry command.
|
|
1601
|
+
*/
|
|
1602
|
+
deprecated?: boolean | string;
|
|
1412
1603
|
/**
|
|
1413
1604
|
* Whether this command is an entry command.
|
|
1414
1605
|
*
|
|
@@ -1426,11 +1617,15 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1426
1617
|
* Nested sub-commands for this command.
|
|
1427
1618
|
*
|
|
1428
1619
|
* Allows building command trees like `git remote add`.
|
|
1429
|
-
* Each key is the sub-command name, and the value is a command
|
|
1620
|
+
* Each key is the sub-command name, and the value is a command, a lazy command, or a loader, a function that
|
|
1621
|
+
* returns the command or its runner, which runs as a lazy command named after its key.
|
|
1622
|
+
* An array of commands is keyed by the names of the commands.
|
|
1623
|
+
*
|
|
1624
|
+
* On the entry command, these are the top-level sub-commands when {@linkcode CliOptions.subCommands} is not given.
|
|
1430
1625
|
*
|
|
1431
1626
|
* @since v0.28.0
|
|
1432
1627
|
*/
|
|
1433
|
-
subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable
|
|
1628
|
+
subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
|
|
1434
1629
|
}
|
|
1435
1630
|
/**
|
|
1436
1631
|
* Lazy command interface.
|
|
@@ -1458,6 +1653,13 @@ type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D exten
|
|
|
1458
1653
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
|
|
1459
1654
|
*/
|
|
1460
1655
|
type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
|
|
1656
|
+
/**
|
|
1657
|
+
* A function given as a sub-command, which the CLI loads as a lazy command named after its key:
|
|
1658
|
+
* it returns the command, or its runner
|
|
1659
|
+
*
|
|
1660
|
+
* @internal
|
|
1661
|
+
*/
|
|
1662
|
+
type SubCommandLoader = () => Awaitable<SubCommandable | ((...args: any[]) => any)>;
|
|
1461
1663
|
/**
|
|
1462
1664
|
* Sub-command entry type for use in subCommands.
|
|
1463
1665
|
*
|
|
@@ -1495,6 +1697,14 @@ interface SubCommandable {
|
|
|
1495
1697
|
* see {@link Command.internal}
|
|
1496
1698
|
*/
|
|
1497
1699
|
internal?: boolean;
|
|
1700
|
+
/**
|
|
1701
|
+
* see {@link Command.aliases}
|
|
1702
|
+
*/
|
|
1703
|
+
aliases?: readonly string[];
|
|
1704
|
+
/**
|
|
1705
|
+
* see {@link Command.deprecated}
|
|
1706
|
+
*/
|
|
1707
|
+
deprecated?: boolean | string;
|
|
1498
1708
|
/**
|
|
1499
1709
|
* see {@link Command.entry}
|
|
1500
1710
|
*/
|
|
@@ -1513,11 +1723,7 @@ interface SubCommandable {
|
|
|
1513
1723
|
* @see {@link Command.subCommands}
|
|
1514
1724
|
* @since v0.28.0
|
|
1515
1725
|
*/
|
|
1516
|
-
subCommands?: Record<string, any> | Map<string, any
|
|
1517
|
-
/**
|
|
1518
|
-
* Index signature to allow additional properties
|
|
1519
|
-
*/
|
|
1520
|
-
[key: string]: any;
|
|
1726
|
+
subCommands?: Record<string, any> | Map<string, any> | readonly any[];
|
|
1521
1727
|
}
|
|
1522
1728
|
/**
|
|
1523
1729
|
* Command examples fetcher.
|
|
@@ -1534,15 +1740,53 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
|
|
|
1534
1740
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1535
1741
|
*
|
|
1536
1742
|
* @param ctx - A {@link CommandContext | command context}
|
|
1537
|
-
* @returns
|
|
1743
|
+
* @returns The result of a command that spreads `jsonArgs`, an object keyed by a noun, which is printed
|
|
1744
|
+
* as JSON with `--json`. For any other command, a string, which `cli()` returns, or nothing. See
|
|
1745
|
+
* {@linkcode CommandRunnerResult}.
|
|
1746
|
+
*/
|
|
1747
|
+
type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => CommandRunnerResult<G>;
|
|
1748
|
+
/**
|
|
1749
|
+
* The result of a command that supports `--json`: an object keyed by a noun, such as
|
|
1750
|
+
* `{ project }` or `{ projects }`, so that fields can be added later. The global options plugin prints
|
|
1751
|
+
* it with `JSON.stringify`, so convert what JSON cannot hold, such as a `Map` or a `BigInt`, yourself.
|
|
1538
1752
|
*/
|
|
1539
|
-
type
|
|
1753
|
+
type JsonResult = Record<string, unknown>;
|
|
1754
|
+
/**
|
|
1755
|
+
* Whether the arguments have the `json` of `jsonArgs`.
|
|
1756
|
+
*
|
|
1757
|
+
* @typeParam A - The arguments of a command
|
|
1758
|
+
*/
|
|
1759
|
+
type HasJsonArgs<A> = [A] extends [{
|
|
1760
|
+
readonly json: {
|
|
1761
|
+
readonly [JSON_ARG]: true;
|
|
1762
|
+
};
|
|
1763
|
+
}] ? true : false;
|
|
1764
|
+
/**
|
|
1765
|
+
* What the runner of a command returns: its result for a command that spreads `jsonArgs`, otherwise a string or
|
|
1766
|
+
* nothing.
|
|
1767
|
+
*
|
|
1768
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}
|
|
1769
|
+
*/
|
|
1770
|
+
type CommandRunnerResult<G extends GunshiParamsConstraint = DefaultGunshiParams> = IsAnyArgs<ExtractArgs<G>> extends true ? Awaitable<string | void | JsonResult> : HasJsonArgs<ExtractArgs<G>> extends true ? Awaitable<JsonResult> : Awaitable<string | void>;
|
|
1771
|
+
/**
|
|
1772
|
+
* Whether the arguments are `any`, as in `CommandRunner<any>`. Then a runner may return anything it could before.
|
|
1773
|
+
*
|
|
1774
|
+
* @internal
|
|
1775
|
+
*/
|
|
1776
|
+
type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
|
|
1540
1777
|
/**
|
|
1541
1778
|
* Command loader.
|
|
1542
1779
|
*
|
|
1543
1780
|
* A function that returns a command or command runner.
|
|
1544
1781
|
* This is used to lazily load commands.
|
|
1545
1782
|
*
|
|
1783
|
+
* Any other value, such as `null` or `undefined`, fails with `Cannot resolve command: <name>`. To tell
|
|
1784
|
+
* what went wrong, such as a module that is not found, throw an error instead, such as a
|
|
1785
|
+
* `CommandError`. An error of the loading is thrown where the command would run, as an error of
|
|
1786
|
+
* `run` is: a `CommandError` prints its message with its exit code, `--json` prints the failure as JSON,
|
|
1787
|
+
* and `onErrorCommand` sees it. Until then, the definition given to `lazy` stands for the command, so that
|
|
1788
|
+
* `--help` prints its usage.
|
|
1789
|
+
*
|
|
1546
1790
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context and command runner.
|
|
1547
1791
|
*
|
|
1548
1792
|
* @returns A command or command runner
|
|
@@ -1553,6 +1797,10 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1553
1797
|
*
|
|
1554
1798
|
* A function that wraps a command runner to add or modify its behavior.
|
|
1555
1799
|
*
|
|
1800
|
+
* The decorated runner returns what the base runner returns, as it is: the result of a command that
|
|
1801
|
+
* spreads `jsonArgs` must reach the global options plugin, which prints it as JSON with `--json`. A
|
|
1802
|
+
* decorator prints with `ctx.log`, which is silenced then.
|
|
1803
|
+
*
|
|
1556
1804
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1557
1805
|
*
|
|
1558
1806
|
* @param baseRunner - The base command runner to decorate
|
|
@@ -1560,7 +1808,7 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1560
1808
|
*
|
|
1561
1809
|
* @since v0.27.0
|
|
1562
1810
|
*/
|
|
1563
|
-
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
|
|
1811
|
+
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>;
|
|
1564
1812
|
/**
|
|
1565
1813
|
* Renderer decorator type.
|
|
1566
1814
|
*
|
|
@@ -1590,24 +1838,105 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
|
|
|
1590
1838
|
* @since v0.27.0
|
|
1591
1839
|
*/
|
|
1592
1840
|
type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
|
|
1593
|
-
//#endregion
|
|
1594
|
-
//#region ../gunshi/src/cli/bone.d.ts
|
|
1595
1841
|
/**
|
|
1596
|
-
*
|
|
1842
|
+
* The keys that people write in an argument, from another library or by a typo, with the key of Gunshi to use
|
|
1843
|
+
* instead
|
|
1844
|
+
*
|
|
1845
|
+
* NOTE(kazupon): keep it short. A key is here when people write it, as the apps that use Gunshi did with `alias`
|
|
1846
|
+
* and `array` (#930). The i18n plugin keeps a copy of it (`packages/plugin-i18n/src/helpers.ts`): change both.
|
|
1847
|
+
*
|
|
1848
|
+
* @internal
|
|
1849
|
+
*/
|
|
1850
|
+
type ArgKeyHints = {
|
|
1851
|
+
alias: 'short';
|
|
1852
|
+
array: 'multiple';
|
|
1853
|
+
desc: 'description';
|
|
1854
|
+
require: 'required';
|
|
1855
|
+
};
|
|
1856
|
+
/**
|
|
1857
|
+
* The message for a key that an argument does not have, with the key to use instead when {@link ArgKeyHints} has
|
|
1858
|
+
* one
|
|
1597
1859
|
*
|
|
1598
|
-
* @
|
|
1860
|
+
* @internal
|
|
1861
|
+
*/
|
|
1862
|
+
type UnknownArgKeyMessage<P> = `'${P & string}' is not a key of an argument${P extends keyof ArgKeyHints ? `: use '${ArgKeyHints[P]}'` : ''}`;
|
|
1863
|
+
/**
|
|
1864
|
+
* The keys of all the members of a union of schemas, such as a schema typed as
|
|
1865
|
+
* `{ type: 'string'; require: true } | { type: 'number' }`: `keyof` of a union has only the keys that every member
|
|
1866
|
+
* has
|
|
1867
|
+
*
|
|
1868
|
+
* @internal
|
|
1869
|
+
*/
|
|
1870
|
+
type KeysOfEach<S> = S extends unknown ? keyof S : never;
|
|
1871
|
+
/**
|
|
1872
|
+
* The keys of each argument that {@link ArgSchema} does not have, mapped to a type that names the key
|
|
1873
|
+
*
|
|
1874
|
+
* NOTE(kazupon): the definition helpers infer the arguments, so a key that an argument does not have, such as
|
|
1875
|
+
* `positional: true` or a misspelled `require`, would type-check and be ignored at run time (#930). A value does not
|
|
1876
|
+
* fit the type, so the error is reported at the key, and says which key an argument does not have, and the key to
|
|
1877
|
+
* use instead for the keys of {@link ArgKeyHints}:
|
|
1878
|
+
* `Type 'true' is not assignable to type 'boolean & { "'require' is not a key of an argument: use 'required'": never; }'`.
|
|
1879
|
+
* The marks of Gunshi, such as the one of `jsonArgs`, are keys that start with `~gunshi.`.
|
|
1880
|
+
*
|
|
1881
|
+
* @internal
|
|
1882
|
+
*/
|
|
1883
|
+
type UnknownArgKeys<A> = { [K in keyof A]: { [P in Exclude<KeysOfEach<A[K]>, keyof ArgSchema | `~gunshi.${string}`>]: { [M in UnknownArgKeyMessage<P>]: never; }; }; };
|
|
1884
|
+
/**
|
|
1885
|
+
* `G`, which a call does not infer from: an indexed access that waits for `G`, as `NoInfer` of TypeScript 5.4 does
|
|
1886
|
+
*
|
|
1887
|
+
* NOTE(kazupon): the first overload of `cli()` infers the arguments of the entry command from its `args`, and takes
|
|
1888
|
+
* `G` as `{ args: A; extensions: {} }` (#931). If `G` were inferred, a command of `define()` would give it from the
|
|
1889
|
+
* keys that the definition does not write, which `define()` types with the default parameters, such as `examples`, and
|
|
1890
|
+
* a command that spreads `jsonArgs` would not fit. Nor is the entry typed as `Command<{ args: A; extensions: {} }>`:
|
|
1891
|
+
* as the first overload, that breaks the inference of `define()` written in the call (#452).
|
|
1892
|
+
*
|
|
1893
|
+
* @typeParam G - The type of the parameters of a command
|
|
1894
|
+
*
|
|
1895
|
+
* @internal
|
|
1896
|
+
*/
|
|
1897
|
+
type NoInferParams<G> = [G][G extends unknown ? 0 : never];
|
|
1898
|
+
/**
|
|
1899
|
+
* A command that the other overloads of `cli()` do not take, such as a command of another copy of the types of gunshi:
|
|
1900
|
+
* its arguments are `Args`, and its runner returns what a runner returns
|
|
1901
|
+
*
|
|
1902
|
+
* NOTE(kazupon): `gunshi` and `@gunshi/definition` bundle their own copies of the types. A command of `define()` types
|
|
1903
|
+
* its `run` with the context of its arguments, and the keys that the definition does not write with the default
|
|
1904
|
+
* parameters. Within one copy, TypeScript compares them by the variance of `CommandContext`, and the command fits;
|
|
1905
|
+
* across the copies, TypeScript compares the structures, and the command fits no other overload. So the runner takes
|
|
1906
|
+
* any arguments here. The arguments are `Args`, and the runner returns what a runner returns, so that an object written
|
|
1907
|
+
* in the call with an argument that is not valid, such as `type: 'numbr'`, is a type error, rather than taken with a
|
|
1908
|
+
* `ctx` of `any` (#931).
|
|
1909
|
+
*
|
|
1910
|
+
* @internal
|
|
1911
|
+
*/
|
|
1912
|
+
type EntryCommandable = Omit<SubCommandable, 'args' | 'run'> & {
|
|
1913
|
+
args?: Args;
|
|
1914
|
+
run?: (...args: any[]) => Awaitable<string | void | JsonResult>;
|
|
1915
|
+
};
|
|
1916
|
+
/**
|
|
1917
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1918
|
+
* To have them, use `cli` from `gunshi`.
|
|
1919
|
+
*
|
|
1920
|
+
* An object written as the entry command is typed by its `args`, as with `define`: `ctx.values` of its `run` are
|
|
1921
|
+
* inferred from them, and a key that an argument does not have is an error.
|
|
1922
|
+
*
|
|
1923
|
+
* @typeParam A - The type of {@linkcode Args | arguments} of the entry command, inferred from its `args`.
|
|
1924
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}, which is not inferred: `{ args: A; extensions: {} }`.
|
|
1599
1925
|
*
|
|
1600
1926
|
* @param args - Command line arguments
|
|
1601
1927
|
* @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
|
|
1602
1928
|
* @param options - A {@link CliOptions | CLI options}
|
|
1603
1929
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1604
1930
|
*/
|
|
1605
|
-
declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1931
|
+
export declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1606
1932
|
args: A;
|
|
1607
1933
|
extensions: {};
|
|
1608
|
-
}>(args: string[], entry: Command<
|
|
1934
|
+
}>(args: string[], entry: (Command<NoInferParams<G>> & {
|
|
1935
|
+
args?: A & UnknownArgKeys<A>;
|
|
1936
|
+
}) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>;
|
|
1609
1937
|
/**
|
|
1610
|
-
* Run the command.
|
|
1938
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1939
|
+
* To have them, use `cli` from `gunshi`.
|
|
1611
1940
|
*
|
|
1612
1941
|
* @typeParam E - An {@linkcode ExtendContext} type to specify the shape of command and cli options.
|
|
1613
1942
|
*
|
|
@@ -1616,12 +1945,13 @@ declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
|
1616
1945
|
* @param options - A {@link CliOptions | CLI options}
|
|
1617
1946
|
* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1618
1947
|
*/
|
|
1619
|
-
declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1948
|
+
export declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1620
1949
|
args: Args;
|
|
1621
1950
|
extensions: E;
|
|
1622
1951
|
}>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1623
1952
|
/**
|
|
1624
|
-
* Run the command.
|
|
1953
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1954
|
+
* To have them, use `cli` from `gunshi`.
|
|
1625
1955
|
*
|
|
1626
1956
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command and cli options.
|
|
1627
1957
|
*
|
|
@@ -1630,6 +1960,20 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
|
|
|
1630
1960
|
* @param options - A {@link CliOptions | CLI options}
|
|
1631
1961
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1632
1962
|
*/
|
|
1633
|
-
declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1634
|
-
|
|
1635
|
-
|
|
1963
|
+
export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1964
|
+
/**
|
|
1965
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1966
|
+
* To have them, use `cli` from `gunshi`.
|
|
1967
|
+
*
|
|
1968
|
+
* This overload takes a command of another copy of the types of gunshi, such as a command of `@gunshi/definition`,
|
|
1969
|
+
* whose types the overloads above cannot compare. `@gunshi/bone` exports no `define`, so a CLI on it defines its
|
|
1970
|
+
* commands with another package. Its arguments are checked as `Args`, and its runner returns what a runner returns. It
|
|
1971
|
+
* must be the last of the overloads.
|
|
1972
|
+
*
|
|
1973
|
+
* @param args - Command line arguments
|
|
1974
|
+
* @param entry - A command-like object (command, command runner, or lazy command)
|
|
1975
|
+
* @param options - A {@link CliOptions | CLI options}
|
|
1976
|
+
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1977
|
+
*/
|
|
1978
|
+
export declare function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>;
|
|
1979
|
+
export type { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, CommandRunnerResult, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, HasJsonArgs, JsonResult, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator };
|