@gunshi/bone 1.0.0-rc.1 → 1.0.0-rc.11
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 +452 -63
- package/lib/index.js +941 -429
- 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/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,14 +1393,28 @@ 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
|
/**
|
|
1254
1402
|
* Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`.
|
|
1255
1403
|
*/
|
|
1256
1404
|
rest: string[];
|
|
1405
|
+
/**
|
|
1406
|
+
* The arguments that the command does not take, as they are given and in order, for a command with
|
|
1407
|
+
* {@linkcode Command.passthrough | passthrough} to pass on to another program: the options that it does not
|
|
1408
|
+
* declare, with the arguments that they take as their values, the positional arguments that it does not take,
|
|
1409
|
+
* and the arguments after `--`, at the end and without `--` itself.
|
|
1410
|
+
*
|
|
1411
|
+
* `app exec run.js --watch src -- --env x`, for `exec` with the positional argument `script`, gives
|
|
1412
|
+
* `['--watch', 'src', '--env', 'x']`. The arguments after `--` are in {@linkcode CommandContext.rest | rest}
|
|
1413
|
+
* too: pass this on in place of `rest`, not with it.
|
|
1414
|
+
*
|
|
1415
|
+
* It is an empty array for a command without `passthrough`.
|
|
1416
|
+
*/
|
|
1417
|
+
passthrough: string[];
|
|
1257
1418
|
/**
|
|
1258
1419
|
* Original command line arguments.
|
|
1259
1420
|
* This argument is passed from `cli` function.
|
|
@@ -1265,6 +1426,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1265
1426
|
tokens: ArgToken[];
|
|
1266
1427
|
/**
|
|
1267
1428
|
* Whether the currently executing command has been executed with the sub-command name omitted.
|
|
1429
|
+
*
|
|
1430
|
+
* A command that has sub-commands and no {@linkcode Command.run | run} prints its usage then, with
|
|
1431
|
+
* the global options plugin, as `--help` does.
|
|
1268
1432
|
*/
|
|
1269
1433
|
omitted: boolean;
|
|
1270
1434
|
/**
|
|
@@ -1287,9 +1451,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1287
1451
|
*/
|
|
1288
1452
|
toKebab?: boolean;
|
|
1289
1453
|
/**
|
|
1290
|
-
* Output a message.
|
|
1454
|
+
* Output a message for people.
|
|
1291
1455
|
*
|
|
1292
|
-
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
|
|
1456
|
+
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output. Nor is it when a
|
|
1457
|
+
* command that spreads `jsonArgs` is asked for JSON with `--json`, so that stdout has the JSON only:
|
|
1458
|
+
* the hooks and the plugins get the same function.
|
|
1293
1459
|
*
|
|
1294
1460
|
* @param message - an output message, see {@linkcode console.log}
|
|
1295
1461
|
* @param optionalParams - an optional parameters, see {@linkcode console.log}
|
|
@@ -1360,9 +1526,11 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
|
|
|
1360
1526
|
usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
|
|
1361
1527
|
/**
|
|
1362
1528
|
* Validation errors rendering configuration
|
|
1363
|
-
* - `null`: Disable rendering
|
|
1529
|
+
* - `null`: Disable rendering. `cli()` rejects with the validation errors, for the caller to report them
|
|
1364
1530
|
* - `function`: Use custom renderer
|
|
1365
1531
|
* - `undefined` (when omitted): Use default renderer
|
|
1532
|
+
*
|
|
1533
|
+
* See {@linkcode CliOptions.renderValidationErrors} for where the rendered message goes.
|
|
1366
1534
|
*/
|
|
1367
1535
|
validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
|
|
1368
1536
|
}
|
|
@@ -1394,6 +1562,14 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1394
1562
|
examples?: string | CommandExamplesFetcher<G>;
|
|
1395
1563
|
/**
|
|
1396
1564
|
* Command runner. it's the command to be executed
|
|
1565
|
+
*
|
|
1566
|
+
* A command that has sub-commands needs no runner: run without a sub-command, it prints its usage,
|
|
1567
|
+
* with the global options plugin, as `--help` does. A command with a runner runs it then, with
|
|
1568
|
+
* {@linkcode CommandContext.omitted | omitted} set to `true`.
|
|
1569
|
+
*
|
|
1570
|
+
* A command without sub-commands needs a runner. Without one, it throws a `TypeError` when it runs
|
|
1571
|
+
* (`'run' is required in command: <name>`), and `--help` still prints its usage. So does a lazy command
|
|
1572
|
+
* whose loader returns a command without a runner.
|
|
1397
1573
|
*/
|
|
1398
1574
|
run?: CommandRunner<G>;
|
|
1399
1575
|
/**
|
|
@@ -1409,6 +1585,62 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1409
1585
|
* @since v0.27.0
|
|
1410
1586
|
*/
|
|
1411
1587
|
internal?: boolean;
|
|
1588
|
+
/**
|
|
1589
|
+
* Other names of the command, such as `['ls']` for `list`.
|
|
1590
|
+
*
|
|
1591
|
+
* The command runs with any of them, as with its name, and `ctx.name` and `ctx.commandPath` have its name:
|
|
1592
|
+
* the help, the hints and the help as JSON tell the name of the command. An alias is accepted but not taught:
|
|
1593
|
+
* the help does not list it, and the `Did you mean` hint for an unknown command and shell completion do not
|
|
1594
|
+
* offer it.
|
|
1595
|
+
*
|
|
1596
|
+
* A sub-command whose name is the alias wins over the alias, so an alias never hides a command. Two commands
|
|
1597
|
+
* at the same level with the same alias are a mistake: using the alias throws a `TypeError`. A lazy command
|
|
1598
|
+
* takes its aliases from the definition given to `lazy`, as it is found before it is loaded.
|
|
1599
|
+
*/
|
|
1600
|
+
aliases?: readonly string[];
|
|
1601
|
+
/**
|
|
1602
|
+
* Whether the command is deprecated: `true`, or the text that tells what to use instead, such as `'Use deploy.'`.
|
|
1603
|
+
*
|
|
1604
|
+
* A deprecated command still runs. With the global options plugin, it prints a warning to stderr when it runs,
|
|
1605
|
+
* once: `push is deprecated. Use deploy.`, and not when the command is asked for JSON with `--json`. A command
|
|
1606
|
+
* under a deprecated group, such as the old name of a renamed group, warns of the group too. Its help says that
|
|
1607
|
+
* it is deprecated, after its description. As an internal command, it is left out of the help, the
|
|
1608
|
+
* `Did you mean` hint for an unknown command, shell completion and the help as JSON, so that they teach what to
|
|
1609
|
+
* use instead.
|
|
1610
|
+
*
|
|
1611
|
+
* To rename a command, keep the old name as a deprecated command that runs as the new one, such as
|
|
1612
|
+
* `push: define({ ...deploy, name: 'push', aliases: [], deprecated: 'Use deploy.' })`, where `aliases: []` takes
|
|
1613
|
+
* the aliases that the spread copies off the old name. It has no effect on the entry command.
|
|
1614
|
+
*/
|
|
1615
|
+
deprecated?: boolean | string;
|
|
1616
|
+
/**
|
|
1617
|
+
* Whether the command passes the arguments that it does not take on to another program: `true`, or the text that
|
|
1618
|
+
* tells what they are, such as `'The arguments for the script'`, which the help shows.
|
|
1619
|
+
*
|
|
1620
|
+
* Such a command reports neither an option that it does not declare, whatever {@linkcode CliOptions.strict} says,
|
|
1621
|
+
* nor a positional argument that it does not take, whatever {@linkcode CliOptions.strictPositionals} says.
|
|
1622
|
+
* {@linkcode CommandContext.passthrough | ctx.passthrough} has them, as they are given and in order, with the
|
|
1623
|
+
* arguments after `--` at the end. The options that it declares, the global options such as `--help` included,
|
|
1624
|
+
* are read as before and are not passed on: to give `--help` to the other program, give it after `--`. A short
|
|
1625
|
+
* option group with an option that the command does not declare is passed on whole, such as `-qk` for a command
|
|
1626
|
+
* that declares `-q` and not `-k`: `-q` is read too, and the other program gets it in the group. The other errors
|
|
1627
|
+
* of the arguments are reported as before.
|
|
1628
|
+
*
|
|
1629
|
+
* An option that the command does not declare takes the next argument as its value, unless it has a value of its
|
|
1630
|
+
* own, such as `--bail=3`, or the next argument is an option or `--`. Both are passed on, and a positional argument
|
|
1631
|
+
* that the command declares does not get it: give the positional arguments of the command before the options of
|
|
1632
|
+
* the other program that take no value, such as `exec run.js --watch`, not `exec --watch run.js`.
|
|
1633
|
+
*
|
|
1634
|
+
* The help shows it at the end of the usage, as `[ARGUMENTS ...]`, and the text in the ARGUMENTS section, which the
|
|
1635
|
+
* i18n plugin translates with the key `passthrough` of the command. With the global options plugin, `--json` is
|
|
1636
|
+
* passed on too when the command declares no `json` argument: `jsonArgs`, or a `json` argument of its own, takes
|
|
1637
|
+
* `--json`. Without one, `--help --json` and `--version --json` are still answered by gunshi, as JSON, and the help
|
|
1638
|
+
* as JSON has `passthrough`.
|
|
1639
|
+
*
|
|
1640
|
+
* A lazy command takes it from the loaded command, and from the definition given to `lazy` when the loaded
|
|
1641
|
+
* command does not set it, or when the loader returns a runner.
|
|
1642
|
+
*/
|
|
1643
|
+
passthrough?: boolean | string;
|
|
1412
1644
|
/**
|
|
1413
1645
|
* Whether this command is an entry command.
|
|
1414
1646
|
*
|
|
@@ -1426,11 +1658,15 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1426
1658
|
* Nested sub-commands for this command.
|
|
1427
1659
|
*
|
|
1428
1660
|
* Allows building command trees like `git remote add`.
|
|
1429
|
-
* Each key is the sub-command name, and the value is a command
|
|
1661
|
+
* Each key is the sub-command name, and the value is a command, a lazy command, or a loader, a function that
|
|
1662
|
+
* returns the command or its runner, which runs as a lazy command named after its key.
|
|
1663
|
+
* An array of commands is keyed by the names of the commands.
|
|
1664
|
+
*
|
|
1665
|
+
* On the entry command, these are the top-level sub-commands when {@linkcode CliOptions.subCommands} is not given.
|
|
1430
1666
|
*
|
|
1431
1667
|
* @since v0.28.0
|
|
1432
1668
|
*/
|
|
1433
|
-
subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable
|
|
1669
|
+
subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
|
|
1434
1670
|
}
|
|
1435
1671
|
/**
|
|
1436
1672
|
* Lazy command interface.
|
|
@@ -1458,6 +1694,13 @@ type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D exten
|
|
|
1458
1694
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
|
|
1459
1695
|
*/
|
|
1460
1696
|
type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
|
|
1697
|
+
/**
|
|
1698
|
+
* A function given as a sub-command, which the CLI loads as a lazy command named after its key:
|
|
1699
|
+
* it returns the command, or its runner
|
|
1700
|
+
*
|
|
1701
|
+
* @internal
|
|
1702
|
+
*/
|
|
1703
|
+
type SubCommandLoader = () => Awaitable<SubCommandable | ((...args: any[]) => any)>;
|
|
1461
1704
|
/**
|
|
1462
1705
|
* Sub-command entry type for use in subCommands.
|
|
1463
1706
|
*
|
|
@@ -1495,6 +1738,18 @@ interface SubCommandable {
|
|
|
1495
1738
|
* see {@link Command.internal}
|
|
1496
1739
|
*/
|
|
1497
1740
|
internal?: boolean;
|
|
1741
|
+
/**
|
|
1742
|
+
* see {@link Command.aliases}
|
|
1743
|
+
*/
|
|
1744
|
+
aliases?: readonly string[];
|
|
1745
|
+
/**
|
|
1746
|
+
* see {@link Command.deprecated}
|
|
1747
|
+
*/
|
|
1748
|
+
deprecated?: boolean | string;
|
|
1749
|
+
/**
|
|
1750
|
+
* see {@link Command.passthrough}
|
|
1751
|
+
*/
|
|
1752
|
+
passthrough?: boolean | string;
|
|
1498
1753
|
/**
|
|
1499
1754
|
* see {@link Command.entry}
|
|
1500
1755
|
*/
|
|
@@ -1513,11 +1768,7 @@ interface SubCommandable {
|
|
|
1513
1768
|
* @see {@link Command.subCommands}
|
|
1514
1769
|
* @since v0.28.0
|
|
1515
1770
|
*/
|
|
1516
|
-
subCommands?: Record<string, any> | Map<string, any
|
|
1517
|
-
/**
|
|
1518
|
-
* Index signature to allow additional properties
|
|
1519
|
-
*/
|
|
1520
|
-
[key: string]: any;
|
|
1771
|
+
subCommands?: Record<string, any> | Map<string, any> | readonly any[];
|
|
1521
1772
|
}
|
|
1522
1773
|
/**
|
|
1523
1774
|
* Command examples fetcher.
|
|
@@ -1534,15 +1785,53 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
|
|
|
1534
1785
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1535
1786
|
*
|
|
1536
1787
|
* @param ctx - A {@link CommandContext | command context}
|
|
1537
|
-
* @returns
|
|
1788
|
+
* @returns The result of a command that spreads `jsonArgs`, an object keyed by a noun, which is printed
|
|
1789
|
+
* as JSON with `--json`. For any other command, a string, which `cli()` returns, or nothing. See
|
|
1790
|
+
* {@linkcode CommandRunnerResult}.
|
|
1791
|
+
*/
|
|
1792
|
+
type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => CommandRunnerResult<G>;
|
|
1793
|
+
/**
|
|
1794
|
+
* The result of a command that supports `--json`: an object keyed by a noun, such as
|
|
1795
|
+
* `{ project }` or `{ projects }`, so that fields can be added later. The global options plugin prints
|
|
1796
|
+
* it with `JSON.stringify`, so convert what JSON cannot hold, such as a `Map` or a `BigInt`, yourself.
|
|
1797
|
+
*/
|
|
1798
|
+
type JsonResult = Record<string, unknown>;
|
|
1799
|
+
/**
|
|
1800
|
+
* Whether the arguments have the `json` of `jsonArgs`.
|
|
1801
|
+
*
|
|
1802
|
+
* @typeParam A - The arguments of a command
|
|
1803
|
+
*/
|
|
1804
|
+
type HasJsonArgs<A> = [A] extends [{
|
|
1805
|
+
readonly json: {
|
|
1806
|
+
readonly [JSON_ARG]: true;
|
|
1807
|
+
};
|
|
1808
|
+
}] ? true : false;
|
|
1809
|
+
/**
|
|
1810
|
+
* What the runner of a command returns: its result for a command that spreads `jsonArgs`, otherwise a string or
|
|
1811
|
+
* nothing.
|
|
1812
|
+
*
|
|
1813
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}
|
|
1538
1814
|
*/
|
|
1539
|
-
type
|
|
1815
|
+
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>;
|
|
1816
|
+
/**
|
|
1817
|
+
* Whether the arguments are `any`, as in `CommandRunner<any>`. Then a runner may return anything it could before.
|
|
1818
|
+
*
|
|
1819
|
+
* @internal
|
|
1820
|
+
*/
|
|
1821
|
+
type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
|
|
1540
1822
|
/**
|
|
1541
1823
|
* Command loader.
|
|
1542
1824
|
*
|
|
1543
1825
|
* A function that returns a command or command runner.
|
|
1544
1826
|
* This is used to lazily load commands.
|
|
1545
1827
|
*
|
|
1828
|
+
* Any other value, such as `null` or `undefined`, fails with `Cannot resolve command: <name>`. To tell
|
|
1829
|
+
* what went wrong, such as a module that is not found, throw an error instead, such as a
|
|
1830
|
+
* `CommandError`. An error of the loading is thrown where the command would run, as an error of
|
|
1831
|
+
* `run` is: a `CommandError` prints its message with its exit code, `--json` prints the failure as JSON,
|
|
1832
|
+
* and `onErrorCommand` sees it. Until then, the definition given to `lazy` stands for the command, so that
|
|
1833
|
+
* `--help` prints its usage.
|
|
1834
|
+
*
|
|
1546
1835
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context and command runner.
|
|
1547
1836
|
*
|
|
1548
1837
|
* @returns A command or command runner
|
|
@@ -1553,6 +1842,10 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1553
1842
|
*
|
|
1554
1843
|
* A function that wraps a command runner to add or modify its behavior.
|
|
1555
1844
|
*
|
|
1845
|
+
* The decorated runner returns what the base runner returns, as it is: the result of a command that
|
|
1846
|
+
* spreads `jsonArgs` must reach the global options plugin, which prints it as JSON with `--json`. A
|
|
1847
|
+
* decorator prints with `ctx.log`, which is silenced then.
|
|
1848
|
+
*
|
|
1556
1849
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1557
1850
|
*
|
|
1558
1851
|
* @param baseRunner - The base command runner to decorate
|
|
@@ -1560,7 +1853,7 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1560
1853
|
*
|
|
1561
1854
|
* @since v0.27.0
|
|
1562
1855
|
*/
|
|
1563
|
-
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
|
|
1856
|
+
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>;
|
|
1564
1857
|
/**
|
|
1565
1858
|
* Renderer decorator type.
|
|
1566
1859
|
*
|
|
@@ -1590,24 +1883,105 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
|
|
|
1590
1883
|
* @since v0.27.0
|
|
1591
1884
|
*/
|
|
1592
1885
|
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
1886
|
/**
|
|
1596
|
-
*
|
|
1887
|
+
* The keys that people write in an argument, from another library or by a typo, with the key of Gunshi to use
|
|
1888
|
+
* instead
|
|
1889
|
+
*
|
|
1890
|
+
* NOTE(kazupon): keep it short. A key is here when people write it, as the apps that use Gunshi did with `alias`
|
|
1891
|
+
* and `array` (#930). The i18n plugin keeps a copy of it (`packages/plugin-i18n/src/helpers.ts`): change both.
|
|
1892
|
+
*
|
|
1893
|
+
* @internal
|
|
1894
|
+
*/
|
|
1895
|
+
type ArgKeyHints = {
|
|
1896
|
+
alias: 'short';
|
|
1897
|
+
array: 'multiple';
|
|
1898
|
+
desc: 'description';
|
|
1899
|
+
require: 'required';
|
|
1900
|
+
};
|
|
1901
|
+
/**
|
|
1902
|
+
* The message for a key that an argument does not have, with the key to use instead when {@link ArgKeyHints} has
|
|
1903
|
+
* one
|
|
1904
|
+
*
|
|
1905
|
+
* @internal
|
|
1906
|
+
*/
|
|
1907
|
+
type UnknownArgKeyMessage<P> = `'${P & string}' is not a key of an argument${P extends keyof ArgKeyHints ? `: use '${ArgKeyHints[P]}'` : ''}`;
|
|
1908
|
+
/**
|
|
1909
|
+
* The keys of all the members of a union of schemas, such as a schema typed as
|
|
1910
|
+
* `{ type: 'string'; require: true } | { type: 'number' }`: `keyof` of a union has only the keys that every member
|
|
1911
|
+
* has
|
|
1912
|
+
*
|
|
1913
|
+
* @internal
|
|
1914
|
+
*/
|
|
1915
|
+
type KeysOfEach<S> = S extends unknown ? keyof S : never;
|
|
1916
|
+
/**
|
|
1917
|
+
* The keys of each argument that {@link ArgSchema} does not have, mapped to a type that names the key
|
|
1918
|
+
*
|
|
1919
|
+
* NOTE(kazupon): the definition helpers infer the arguments, so a key that an argument does not have, such as
|
|
1920
|
+
* `positional: true` or a misspelled `require`, would type-check and be ignored at run time (#930). A value does not
|
|
1921
|
+
* fit the type, so the error is reported at the key, and says which key an argument does not have, and the key to
|
|
1922
|
+
* use instead for the keys of {@link ArgKeyHints}:
|
|
1923
|
+
* `Type 'true' is not assignable to type 'boolean & { "'require' is not a key of an argument: use 'required'": never; }'`.
|
|
1924
|
+
* The marks of Gunshi, such as the one of `jsonArgs`, are keys that start with `~gunshi.`.
|
|
1925
|
+
*
|
|
1926
|
+
* @internal
|
|
1927
|
+
*/
|
|
1928
|
+
type UnknownArgKeys<A> = { [K in keyof A]: { [P in Exclude<KeysOfEach<A[K]>, keyof ArgSchema | `~gunshi.${string}`>]: { [M in UnknownArgKeyMessage<P>]: never; }; }; };
|
|
1929
|
+
/**
|
|
1930
|
+
* `G`, which a call does not infer from: an indexed access that waits for `G`, as `NoInfer` of TypeScript 5.4 does
|
|
1931
|
+
*
|
|
1932
|
+
* NOTE(kazupon): the first overload of `cli()` infers the arguments of the entry command from its `args`, and takes
|
|
1933
|
+
* `G` as `{ args: A; extensions: {} }` (#931). If `G` were inferred, a command of `define()` would give it from the
|
|
1934
|
+
* keys that the definition does not write, which `define()` types with the default parameters, such as `examples`, and
|
|
1935
|
+
* a command that spreads `jsonArgs` would not fit. Nor is the entry typed as `Command<{ args: A; extensions: {} }>`:
|
|
1936
|
+
* as the first overload, that breaks the inference of `define()` written in the call (#452).
|
|
1937
|
+
*
|
|
1938
|
+
* @typeParam G - The type of the parameters of a command
|
|
1939
|
+
*
|
|
1940
|
+
* @internal
|
|
1941
|
+
*/
|
|
1942
|
+
type NoInferParams<G> = [G][G extends unknown ? 0 : never];
|
|
1943
|
+
/**
|
|
1944
|
+
* A command that the other overloads of `cli()` do not take, such as a command of another copy of the types of gunshi:
|
|
1945
|
+
* its arguments are `Args`, and its runner returns what a runner returns
|
|
1946
|
+
*
|
|
1947
|
+
* NOTE(kazupon): `gunshi` and `@gunshi/definition` bundle their own copies of the types. A command of `define()` types
|
|
1948
|
+
* its `run` with the context of its arguments, and the keys that the definition does not write with the default
|
|
1949
|
+
* parameters. Within one copy, TypeScript compares them by the variance of `CommandContext`, and the command fits;
|
|
1950
|
+
* across the copies, TypeScript compares the structures, and the command fits no other overload. So the runner takes
|
|
1951
|
+
* any arguments here. The arguments are `Args`, and the runner returns what a runner returns, so that an object written
|
|
1952
|
+
* in the call with an argument that is not valid, such as `type: 'numbr'`, is a type error, rather than taken with a
|
|
1953
|
+
* `ctx` of `any` (#931).
|
|
1954
|
+
*
|
|
1955
|
+
* @internal
|
|
1956
|
+
*/
|
|
1957
|
+
type EntryCommandable = Omit<SubCommandable, 'args' | 'run'> & {
|
|
1958
|
+
args?: Args;
|
|
1959
|
+
run?: (...args: any[]) => Awaitable<string | void | JsonResult>;
|
|
1960
|
+
};
|
|
1961
|
+
/**
|
|
1962
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1963
|
+
* To have them, use `cli` from `gunshi`.
|
|
1597
1964
|
*
|
|
1598
|
-
*
|
|
1965
|
+
* An object written as the entry command is typed by its `args`, as with `define`: `ctx.values` of its `run` are
|
|
1966
|
+
* inferred from them, and a key that an argument does not have is an error.
|
|
1967
|
+
*
|
|
1968
|
+
* @typeParam A - The type of {@linkcode Args | arguments} of the entry command, inferred from its `args`.
|
|
1969
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}, which is not inferred: `{ args: A; extensions: {} }`.
|
|
1599
1970
|
*
|
|
1600
1971
|
* @param args - Command line arguments
|
|
1601
1972
|
* @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
|
|
1602
1973
|
* @param options - A {@link CliOptions | CLI options}
|
|
1603
1974
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1604
1975
|
*/
|
|
1605
|
-
declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1976
|
+
export declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1606
1977
|
args: A;
|
|
1607
1978
|
extensions: {};
|
|
1608
|
-
}>(args: string[], entry: Command<
|
|
1979
|
+
}>(args: string[], entry: (Command<NoInferParams<G>> & {
|
|
1980
|
+
args?: A & UnknownArgKeys<A>;
|
|
1981
|
+
}) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>;
|
|
1609
1982
|
/**
|
|
1610
|
-
* Run the command.
|
|
1983
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1984
|
+
* To have them, use `cli` from `gunshi`.
|
|
1611
1985
|
*
|
|
1612
1986
|
* @typeParam E - An {@linkcode ExtendContext} type to specify the shape of command and cli options.
|
|
1613
1987
|
*
|
|
@@ -1616,12 +1990,13 @@ declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
|
1616
1990
|
* @param options - A {@link CliOptions | CLI options}
|
|
1617
1991
|
* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1618
1992
|
*/
|
|
1619
|
-
declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1993
|
+
export declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1620
1994
|
args: Args;
|
|
1621
1995
|
extensions: E;
|
|
1622
1996
|
}>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1623
1997
|
/**
|
|
1624
|
-
* Run the command.
|
|
1998
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1999
|
+
* To have them, use `cli` from `gunshi`.
|
|
1625
2000
|
*
|
|
1626
2001
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command and cli options.
|
|
1627
2002
|
*
|
|
@@ -1630,6 +2005,20 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
|
|
|
1630
2005
|
* @param options - A {@link CliOptions | CLI options}
|
|
1631
2006
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1632
2007
|
*/
|
|
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
|
-
|
|
2008
|
+
export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
2009
|
+
/**
|
|
2010
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
2011
|
+
* To have them, use `cli` from `gunshi`.
|
|
2012
|
+
*
|
|
2013
|
+
* This overload takes a command of another copy of the types of gunshi, such as a command of `@gunshi/definition`,
|
|
2014
|
+
* whose types the overloads above cannot compare. `@gunshi/bone` exports no `define`, so a CLI on it defines its
|
|
2015
|
+
* commands with another package. Its arguments are checked as `Args`, and its runner returns what a runner returns. It
|
|
2016
|
+
* must be the last of the overloads.
|
|
2017
|
+
*
|
|
2018
|
+
* @param args - Command line arguments
|
|
2019
|
+
* @param entry - A command-like object (command, command runner, or lazy command)
|
|
2020
|
+
* @param options - A {@link CliOptions | CLI options}
|
|
2021
|
+
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
2022
|
+
*/
|
|
2023
|
+
export declare function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>;
|
|
2024
|
+
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 };
|