@gunshi/bone 1.0.0-rc.6 → 1.0.0-rc.8
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/lib/index.d.ts +295 -36
- package/lib/index.js +456 -244
- package/package.json +32 -33
package/lib/index.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
//#region ../gunshi/src/constants.d.ts
|
|
2
1
|
/**
|
|
3
2
|
* The key of the mark on the `json` argument of `jsonArgs`. A string key, not a symbol: `gunshi` and the other
|
|
4
3
|
* packages bundle their own copies of the types, and each copy of a `unique symbol` is a different type.
|
|
@@ -6,8 +5,6 @@
|
|
|
6
5
|
* @internal
|
|
7
6
|
*/
|
|
8
7
|
declare const JSON_ARG = "~gunshi.json-arg";
|
|
9
|
-
//#endregion
|
|
10
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser-DvPxBZG9.d.ts
|
|
11
8
|
/**
|
|
12
9
|
* Entry point of argument parser.
|
|
13
10
|
*
|
|
@@ -63,13 +60,11 @@ interface ArgToken {
|
|
|
63
60
|
*/
|
|
64
61
|
inlineValue?: boolean | undefined;
|
|
65
62
|
}
|
|
66
|
-
//#endregion
|
|
67
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
|
|
68
63
|
/**
|
|
69
64
|
* An argument schema definition for command-line argument parsing.
|
|
70
65
|
*
|
|
71
66
|
* This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
|
|
72
|
-
* - Additional `required`, `description`, and `
|
|
67
|
+
* - Additional `required`, `description`, `hidden`, and `deprecated` properties
|
|
73
68
|
* - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
|
|
74
69
|
* - Simplified `default` property (single type, not union types)
|
|
75
70
|
*
|
|
@@ -199,6 +194,32 @@ interface ArgSchema {
|
|
|
199
194
|
* ```
|
|
200
195
|
*/
|
|
201
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;
|
|
202
223
|
/**
|
|
203
224
|
* Marks the argument as required.
|
|
204
225
|
*
|
|
@@ -704,8 +725,6 @@ type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] ex
|
|
|
704
725
|
* @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
|
|
705
726
|
*/
|
|
706
727
|
type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean; };
|
|
707
|
-
//#endregion
|
|
708
|
-
//#region ../gunshi/src/plugin/context.d.ts
|
|
709
728
|
/**
|
|
710
729
|
* Gunshi plugin context interface.
|
|
711
730
|
*
|
|
@@ -782,8 +801,6 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
782
801
|
*/
|
|
783
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;
|
|
784
803
|
}
|
|
785
|
-
//#endregion
|
|
786
|
-
//#region ../gunshi/src/plugin/core.d.ts
|
|
787
804
|
/**
|
|
788
805
|
* Plugin dependency definition
|
|
789
806
|
*
|
|
@@ -824,8 +841,6 @@ type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensio
|
|
|
824
841
|
dependencies?: (PluginDependency | string)[];
|
|
825
842
|
extension?: CommandContextExtension<E>;
|
|
826
843
|
};
|
|
827
|
-
//#endregion
|
|
828
|
-
//#region ../gunshi/src/types.d.ts
|
|
829
844
|
/**
|
|
830
845
|
* Awaitable type.
|
|
831
846
|
*
|
|
@@ -967,7 +982,7 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
967
982
|
*/
|
|
968
983
|
cwd: string | undefined;
|
|
969
984
|
/**
|
|
970
|
-
*
|
|
985
|
+
* The name of the CLI, given to `cli()` as `name`.
|
|
971
986
|
*
|
|
972
987
|
* @see {@linkcode CliOptions.name}
|
|
973
988
|
*/
|
|
@@ -1034,6 +1049,28 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1034
1049
|
* @see {@linkcode CliOptions.strict}
|
|
1035
1050
|
*/
|
|
1036
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;
|
|
1037
1074
|
/**
|
|
1038
1075
|
* Sub commands.
|
|
1039
1076
|
*
|
|
@@ -1107,7 +1144,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1107
1144
|
*/
|
|
1108
1145
|
cwd?: string;
|
|
1109
1146
|
/**
|
|
1110
|
-
*
|
|
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.
|
|
1111
1152
|
*/
|
|
1112
1153
|
name?: string;
|
|
1113
1154
|
/**
|
|
@@ -1123,9 +1164,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1123
1164
|
* Sub commands.
|
|
1124
1165
|
*
|
|
1125
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.
|
|
1126
1169
|
* When this is not given, the {@linkcode Command.subCommands} of the entry command are the sub-commands.
|
|
1127
1170
|
*/
|
|
1128
|
-
subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
|
|
1171
|
+
subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
|
|
1129
1172
|
/**
|
|
1130
1173
|
* Left margin of the command output.
|
|
1131
1174
|
*/
|
|
@@ -1164,6 +1207,10 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1164
1207
|
* arguments or installed global options are reported as validation errors
|
|
1165
1208
|
* before the command runner is executed.
|
|
1166
1209
|
*
|
|
1210
|
+
* With the global options plugin, `--help` and `--version` are still answered: given with them, an
|
|
1211
|
+
* unknown option is not reported, as the other argument validation errors are not. An unknown command
|
|
1212
|
+
* is still reported.
|
|
1213
|
+
*
|
|
1167
1214
|
* `--json` is not reported, since gunshi knows what it means: given to a command that does not
|
|
1168
1215
|
* spread `jsonArgs`, the global options plugin reports `json_not_supported` for it instead, with or
|
|
1169
1216
|
* without `strict`. `--json=false` asks for no JSON, and is reported.
|
|
@@ -1171,6 +1218,23 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1171
1218
|
* @default false
|
|
1172
1219
|
*/
|
|
1173
1220
|
strict?: boolean;
|
|
1221
|
+
/**
|
|
1222
|
+
* Whether to treat the positional arguments that the command does not take as argument validation
|
|
1223
|
+
* errors, as `strict` does for the options.
|
|
1224
|
+
*
|
|
1225
|
+
* When enabled, the positional arguments after the command path that the positional arguments of the
|
|
1226
|
+
* resolved command do not take are reported as validation errors before the command runner is
|
|
1227
|
+
* executed. A command takes as many as it declares, an optional one included, and any number with a
|
|
1228
|
+
* positional argument with `multiple: true`. The arguments after `--` are not positional arguments:
|
|
1229
|
+
* they stay in `rest`.
|
|
1230
|
+
*
|
|
1231
|
+
* With the global options plugin, `--help` and `--version` are still answered, as they are with the
|
|
1232
|
+
* other argument validation errors. After a command with sub-commands, a word that is not one of them
|
|
1233
|
+
* is reported as an unknown command instead.
|
|
1234
|
+
*
|
|
1235
|
+
* @default false
|
|
1236
|
+
*/
|
|
1237
|
+
strictPositionals?: boolean;
|
|
1174
1238
|
/**
|
|
1175
1239
|
* Render function the command usage.
|
|
1176
1240
|
*/
|
|
@@ -1183,7 +1247,10 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1183
1247
|
* Render function the validation errors.
|
|
1184
1248
|
*
|
|
1185
1249
|
* With the global options plugin, the rendered message is printed to stderr, the exit code is set
|
|
1186
|
-
* to
|
|
1250
|
+
* to {@linkcode CliOptions.validationErrorExitCode}, `1` by default,
|
|
1251
|
+
* {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
|
|
1252
|
+
* The message is followed by the command that shows the help, unless {@linkcode CliOptions.helpHint}
|
|
1253
|
+
* is `false`.
|
|
1187
1254
|
* Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
|
|
1188
1255
|
* with the `AggregateError`. A renderer that returns an empty message, and
|
|
1189
1256
|
* {@linkcode CliOptions.usageSilent}, also leave them to the caller.
|
|
@@ -1192,9 +1259,49 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1192
1259
|
* the renderer. `null` and {@linkcode CliOptions.usageSilent} still leave them to the caller.
|
|
1193
1260
|
*/
|
|
1194
1261
|
renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
|
|
1262
|
+
/**
|
|
1263
|
+
* Whether to follow the validation errors with the command that shows the help of the nearest
|
|
1264
|
+
* command: the command itself for an argument error, and the parent of an unknown command, such as
|
|
1265
|
+
* `my-app deploy --help`. With the global options plugin, it is printed to stderr after the errors,
|
|
1266
|
+
* after an empty line and a heading. It is the command that `next` of the JSON error has with
|
|
1267
|
+
* `--json`.
|
|
1268
|
+
*
|
|
1269
|
+
* Set it to `false` to leave the command out, such as when your renderer of the validation errors
|
|
1270
|
+
* points to the help in its own way. It changes the output for people only: `next` of the JSON error
|
|
1271
|
+
* stays. The command is left out for a command whose `--help` does not show the help, too: one that
|
|
1272
|
+
* declares a `help` argument of its own, or with `renderUsage: null`.
|
|
1273
|
+
*
|
|
1274
|
+
* @default true
|
|
1275
|
+
*/
|
|
1276
|
+
helpHint?: boolean;
|
|
1277
|
+
/**
|
|
1278
|
+
* The exit code of the validation errors, such as `2`, the exit code of a usage error in many
|
|
1279
|
+
* command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown
|
|
1280
|
+
* command or a command line that cannot be resolved, an unknown option, only with `strict`, a
|
|
1281
|
+
* positional argument that the command does not take, only with `strictPositionals`, and `--json`
|
|
1282
|
+
* given to a command that does not spread `jsonArgs`. Without `strict`, an unknown option is ignored
|
|
1283
|
+
* and the command runs, so to end it with this exit code too, give `strict: true` as well. With the
|
|
1284
|
+
* global options plugin, the exit code is set to it when the errors are printed, as text or as JSON,
|
|
1285
|
+
* before {@linkcode CliOptions.onErrorCommand} is called, which can still change it.
|
|
1286
|
+
*
|
|
1287
|
+
* It is an integer from `1` to `255`, as the `exitCode` of a `CommandError` is, and any other value is
|
|
1288
|
+
* replaced with `1`. It does not change the exit code of a `CommandError`, nor of any other error that a
|
|
1289
|
+
* command throws. With `renderValidationErrors: null`, a renderer that returns an empty message, or
|
|
1290
|
+
* {@linkcode CliOptions.usageSilent}, nothing is printed, and the exit code is left alone.
|
|
1291
|
+
*
|
|
1292
|
+
* @default 1
|
|
1293
|
+
*/
|
|
1294
|
+
validationErrorExitCode?: number;
|
|
1195
1295
|
/**
|
|
1196
1296
|
* Whether to fallback to entry command when the sub-command is not found.
|
|
1197
1297
|
*
|
|
1298
|
+
* When it is not set, it is `true` for a CLI that declares no sub-commands and to which a plugin adds
|
|
1299
|
+
* commands, such as the `complete` command of `@gunshi/plugin-completion`, so that the positional
|
|
1300
|
+
* arguments of the entry command are not taken for command names. This is so when the entry command
|
|
1301
|
+
* has something to run: a command object with `run`, a lazy command, whose loader gives the runner,
|
|
1302
|
+
* or a runner given to `cli()`. For a command object without `run`, it stays `false`: the commands of
|
|
1303
|
+
* the plugins are then the commands of the CLI, and an argument that is not one of them is reported.
|
|
1304
|
+
*
|
|
1198
1305
|
* @default false
|
|
1199
1306
|
* @since v0.27.0
|
|
1200
1307
|
*/
|
|
@@ -1225,9 +1332,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1225
1332
|
* Hook that runs when a command throws an error, or when the arguments fail validation
|
|
1226
1333
|
*
|
|
1227
1334
|
* For the validation errors and a `CommandError` that the global options plugin has printed, the
|
|
1228
|
-
* exit code is already set when the hook runs (
|
|
1229
|
-
* a `CommandError`), so the hook can set another one, and
|
|
1230
|
-
* error rejects `cli()` after the hook.
|
|
1335
|
+
* exit code is already set when the hook runs ({@linkcode CliOptions.validationErrorExitCode} for the
|
|
1336
|
+
* validation errors, and the `exitCode` of a `CommandError`), so the hook can set another one, and
|
|
1337
|
+
* `cli()` resolves after it. Any other error rejects `cli()` after the hook.
|
|
1231
1338
|
*
|
|
1232
1339
|
* @param ctx - The command context
|
|
1233
1340
|
* @param error - The error thrown during execution, or the `AggregateError` of the validation errors
|
|
@@ -1285,8 +1392,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1285
1392
|
*/
|
|
1286
1393
|
values: ArgValues<ExtractArgs<G>>;
|
|
1287
1394
|
/**
|
|
1288
|
-
*
|
|
1289
|
-
*
|
|
1395
|
+
* The positional arguments of the command line, the names of the command path first: `app deploy web`
|
|
1396
|
+
* gives `['deploy', 'web']`. The positional arguments of the command itself are
|
|
1397
|
+
* `positionals.slice(commandPath.length)`, and the ones that it declares are in `values` too.
|
|
1290
1398
|
*/
|
|
1291
1399
|
positionals: string[];
|
|
1292
1400
|
/**
|
|
@@ -1304,6 +1412,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1304
1412
|
tokens: ArgToken[];
|
|
1305
1413
|
/**
|
|
1306
1414
|
* Whether the currently executing command has been executed with the sub-command name omitted.
|
|
1415
|
+
*
|
|
1416
|
+
* A command that has sub-commands and no {@linkcode Command.run | run} prints its usage then, with
|
|
1417
|
+
* the global options plugin, as `--help` does.
|
|
1307
1418
|
*/
|
|
1308
1419
|
omitted: boolean;
|
|
1309
1420
|
/**
|
|
@@ -1437,6 +1548,14 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1437
1548
|
examples?: string | CommandExamplesFetcher<G>;
|
|
1438
1549
|
/**
|
|
1439
1550
|
* Command runner. it's the command to be executed
|
|
1551
|
+
*
|
|
1552
|
+
* A command that has sub-commands needs no runner: run without a sub-command, it prints its usage,
|
|
1553
|
+
* with the global options plugin, as `--help` does. A command with a runner runs it then, with
|
|
1554
|
+
* {@linkcode CommandContext.omitted | omitted} set to `true`.
|
|
1555
|
+
*
|
|
1556
|
+
* A command without sub-commands needs a runner. Without one, it throws a `TypeError` when it runs
|
|
1557
|
+
* (`'run' is required in command: <name>`), and `--help` still prints its usage. So does a lazy command
|
|
1558
|
+
* whose loader returns a command without a runner.
|
|
1440
1559
|
*/
|
|
1441
1560
|
run?: CommandRunner<G>;
|
|
1442
1561
|
/**
|
|
@@ -1452,6 +1571,34 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1452
1571
|
* @since v0.27.0
|
|
1453
1572
|
*/
|
|
1454
1573
|
internal?: boolean;
|
|
1574
|
+
/**
|
|
1575
|
+
* Other names of the command, such as `['ls']` for `list`.
|
|
1576
|
+
*
|
|
1577
|
+
* The command runs with any of them, as with its name, and `ctx.name` and `ctx.commandPath` have its name:
|
|
1578
|
+
* the help, the hints and the help as JSON tell the name of the command. An alias is accepted but not taught:
|
|
1579
|
+
* the help does not list it, and the `Did you mean` hint for an unknown command and shell completion do not
|
|
1580
|
+
* offer it.
|
|
1581
|
+
*
|
|
1582
|
+
* A sub-command whose name is the alias wins over the alias, so an alias never hides a command. Two commands
|
|
1583
|
+
* at the same level with the same alias are a mistake: using the alias throws a `TypeError`. A lazy command
|
|
1584
|
+
* takes its aliases from the definition given to `lazy`, as it is found before it is loaded.
|
|
1585
|
+
*/
|
|
1586
|
+
aliases?: readonly string[];
|
|
1587
|
+
/**
|
|
1588
|
+
* Whether the command is deprecated: `true`, or the text that tells what to use instead, such as `'Use deploy.'`.
|
|
1589
|
+
*
|
|
1590
|
+
* A deprecated command still runs. With the global options plugin, it prints a warning to stderr when it runs,
|
|
1591
|
+
* once: `push is deprecated. Use deploy.`, and not when the command is asked for JSON with `--json`. A command
|
|
1592
|
+
* under a deprecated group, such as the old name of a renamed group, warns of the group too. Its help says that
|
|
1593
|
+
* it is deprecated, after its description. As an internal command, it is left out of the help, the
|
|
1594
|
+
* `Did you mean` hint for an unknown command, shell completion and the help as JSON, so that they teach what to
|
|
1595
|
+
* use instead.
|
|
1596
|
+
*
|
|
1597
|
+
* To rename a command, keep the old name as a deprecated command that runs as the new one, such as
|
|
1598
|
+
* `push: define({ ...deploy, name: 'push', aliases: [], deprecated: 'Use deploy.' })`, where `aliases: []` takes
|
|
1599
|
+
* the aliases that the spread copies off the old name. It has no effect on the entry command.
|
|
1600
|
+
*/
|
|
1601
|
+
deprecated?: boolean | string;
|
|
1455
1602
|
/**
|
|
1456
1603
|
* Whether this command is an entry command.
|
|
1457
1604
|
*
|
|
@@ -1469,14 +1616,15 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1469
1616
|
* Nested sub-commands for this command.
|
|
1470
1617
|
*
|
|
1471
1618
|
* Allows building command trees like `git remote add`.
|
|
1472
|
-
* Each key is the sub-command name, and the value is a command
|
|
1619
|
+
* Each key is the sub-command name, and the value is a command, a lazy command, or a loader, a function that
|
|
1620
|
+
* returns the command or its runner, which runs as a lazy command named after its key.
|
|
1473
1621
|
* An array of commands is keyed by the names of the commands.
|
|
1474
1622
|
*
|
|
1475
1623
|
* On the entry command, these are the top-level sub-commands when {@linkcode CliOptions.subCommands} is not given.
|
|
1476
1624
|
*
|
|
1477
1625
|
* @since v0.28.0
|
|
1478
1626
|
*/
|
|
1479
|
-
subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
|
|
1627
|
+
subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
|
|
1480
1628
|
}
|
|
1481
1629
|
/**
|
|
1482
1630
|
* Lazy command interface.
|
|
@@ -1504,6 +1652,13 @@ type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D exten
|
|
|
1504
1652
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
|
|
1505
1653
|
*/
|
|
1506
1654
|
type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
|
|
1655
|
+
/**
|
|
1656
|
+
* A function given as a sub-command, which the CLI loads as a lazy command named after its key:
|
|
1657
|
+
* it returns the command, or its runner
|
|
1658
|
+
*
|
|
1659
|
+
* @internal
|
|
1660
|
+
*/
|
|
1661
|
+
type SubCommandLoader = () => Awaitable<SubCommandable | ((...args: any[]) => any)>;
|
|
1507
1662
|
/**
|
|
1508
1663
|
* Sub-command entry type for use in subCommands.
|
|
1509
1664
|
*
|
|
@@ -1541,6 +1696,14 @@ interface SubCommandable {
|
|
|
1541
1696
|
* see {@link Command.internal}
|
|
1542
1697
|
*/
|
|
1543
1698
|
internal?: boolean;
|
|
1699
|
+
/**
|
|
1700
|
+
* see {@link Command.aliases}
|
|
1701
|
+
*/
|
|
1702
|
+
aliases?: readonly string[];
|
|
1703
|
+
/**
|
|
1704
|
+
* see {@link Command.deprecated}
|
|
1705
|
+
*/
|
|
1706
|
+
deprecated?: boolean | string;
|
|
1544
1707
|
/**
|
|
1545
1708
|
* see {@link Command.entry}
|
|
1546
1709
|
*/
|
|
@@ -1560,10 +1723,6 @@ interface SubCommandable {
|
|
|
1560
1723
|
* @since v0.28.0
|
|
1561
1724
|
*/
|
|
1562
1725
|
subCommands?: Record<string, any> | Map<string, any> | readonly any[];
|
|
1563
|
-
/**
|
|
1564
|
-
* Index signature to allow additional properties
|
|
1565
|
-
*/
|
|
1566
|
-
[key: string]: any;
|
|
1567
1726
|
}
|
|
1568
1727
|
/**
|
|
1569
1728
|
* Command examples fetcher.
|
|
@@ -1620,6 +1779,13 @@ type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
|
|
|
1620
1779
|
* A function that returns a command or command runner.
|
|
1621
1780
|
* This is used to lazily load commands.
|
|
1622
1781
|
*
|
|
1782
|
+
* Any other value, such as `null` or `undefined`, fails with `Cannot resolve command: <name>`. To tell
|
|
1783
|
+
* what went wrong, such as a module that is not found, throw an error instead, such as a
|
|
1784
|
+
* `CommandError`. An error of the loading is thrown where the command would run, as an error of
|
|
1785
|
+
* `run` is: a `CommandError` prints its message with its exit code, `--json` prints the failure as JSON,
|
|
1786
|
+
* and `onErrorCommand` sees it. Until then, the definition given to `lazy` stands for the command, so that
|
|
1787
|
+
* `--help` prints its usage.
|
|
1788
|
+
*
|
|
1623
1789
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context and command runner.
|
|
1624
1790
|
*
|
|
1625
1791
|
* @returns A command or command runner
|
|
@@ -1671,23 +1837,102 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
|
|
|
1671
1837
|
* @since v0.27.0
|
|
1672
1838
|
*/
|
|
1673
1839
|
type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
|
|
1674
|
-
|
|
1675
|
-
|
|
1840
|
+
/**
|
|
1841
|
+
* The keys that people write in an argument, from another library or by a typo, with the key of Gunshi to use
|
|
1842
|
+
* instead
|
|
1843
|
+
*
|
|
1844
|
+
* NOTE(kazupon): keep it short. A key is here when people write it, as the apps that use Gunshi did with `alias`
|
|
1845
|
+
* and `array` (#930). The i18n plugin keeps a copy of it (`packages/plugin-i18n/src/helpers.ts`): change both.
|
|
1846
|
+
*
|
|
1847
|
+
* @internal
|
|
1848
|
+
*/
|
|
1849
|
+
type ArgKeyHints = {
|
|
1850
|
+
alias: 'short';
|
|
1851
|
+
array: 'multiple';
|
|
1852
|
+
desc: 'description';
|
|
1853
|
+
require: 'required';
|
|
1854
|
+
};
|
|
1855
|
+
/**
|
|
1856
|
+
* The message for a key that an argument does not have, with the key to use instead when {@link ArgKeyHints} has
|
|
1857
|
+
* one
|
|
1858
|
+
*
|
|
1859
|
+
* @internal
|
|
1860
|
+
*/
|
|
1861
|
+
type UnknownArgKeyMessage<P> = `'${P & string}' is not a key of an argument${P extends keyof ArgKeyHints ? `: use '${ArgKeyHints[P]}'` : ''}`;
|
|
1862
|
+
/**
|
|
1863
|
+
* The keys of all the members of a union of schemas, such as a schema typed as
|
|
1864
|
+
* `{ type: 'string'; require: true } | { type: 'number' }`: `keyof` of a union has only the keys that every member
|
|
1865
|
+
* has
|
|
1866
|
+
*
|
|
1867
|
+
* @internal
|
|
1868
|
+
*/
|
|
1869
|
+
type KeysOfEach<S> = S extends unknown ? keyof S : never;
|
|
1870
|
+
/**
|
|
1871
|
+
* The keys of each argument that {@link ArgSchema} does not have, mapped to a type that names the key
|
|
1872
|
+
*
|
|
1873
|
+
* NOTE(kazupon): the definition helpers infer the arguments, so a key that an argument does not have, such as
|
|
1874
|
+
* `positional: true` or a misspelled `require`, would type-check and be ignored at run time (#930). A value does not
|
|
1875
|
+
* fit the type, so the error is reported at the key, and says which key an argument does not have, and the key to
|
|
1876
|
+
* use instead for the keys of {@link ArgKeyHints}:
|
|
1877
|
+
* `Type 'true' is not assignable to type 'boolean & { "'require' is not a key of an argument: use 'required'": never; }'`.
|
|
1878
|
+
* The marks of Gunshi, such as the one of `jsonArgs`, are keys that start with `~gunshi.`.
|
|
1879
|
+
*
|
|
1880
|
+
* @internal
|
|
1881
|
+
*/
|
|
1882
|
+
type UnknownArgKeys<A> = { [K in keyof A]: { [P in Exclude<KeysOfEach<A[K]>, keyof ArgSchema | `~gunshi.${string}`>]: { [M in UnknownArgKeyMessage<P>]: never; }; }; };
|
|
1883
|
+
/**
|
|
1884
|
+
* `G`, which a call does not infer from: an indexed access that waits for `G`, as `NoInfer` of TypeScript 5.4 does
|
|
1885
|
+
*
|
|
1886
|
+
* NOTE(kazupon): the first overload of `cli()` infers the arguments of the entry command from its `args`, and takes
|
|
1887
|
+
* `G` as `{ args: A; extensions: {} }` (#931). If `G` were inferred, a command of `define()` would give it from the
|
|
1888
|
+
* keys that the definition does not write, which `define()` types with the default parameters, such as `examples`, and
|
|
1889
|
+
* a command that spreads `jsonArgs` would not fit. Nor is the entry typed as `Command<{ args: A; extensions: {} }>`:
|
|
1890
|
+
* as the first overload, that breaks the inference of `define()` written in the call (#452).
|
|
1891
|
+
*
|
|
1892
|
+
* @typeParam G - The type of the parameters of a command
|
|
1893
|
+
*
|
|
1894
|
+
* @internal
|
|
1895
|
+
*/
|
|
1896
|
+
type NoInferParams<G> = [G][G extends unknown ? 0 : never];
|
|
1897
|
+
/**
|
|
1898
|
+
* A command that the other overloads of `cli()` do not take, such as a command of another copy of the types of gunshi:
|
|
1899
|
+
* its arguments are `Args`, and its runner returns what a runner returns
|
|
1900
|
+
*
|
|
1901
|
+
* NOTE(kazupon): `gunshi` and `@gunshi/definition` bundle their own copies of the types. A command of `define()` types
|
|
1902
|
+
* its `run` with the context of its arguments, and the keys that the definition does not write with the default
|
|
1903
|
+
* parameters. Within one copy, TypeScript compares them by the variance of `CommandContext`, and the command fits;
|
|
1904
|
+
* across the copies, TypeScript compares the structures, and the command fits no other overload. So the runner takes
|
|
1905
|
+
* any arguments here. The arguments are `Args`, and the runner returns what a runner returns, so that an object written
|
|
1906
|
+
* in the call with an argument that is not valid, such as `type: 'numbr'`, is a type error, rather than taken with a
|
|
1907
|
+
* `ctx` of `any` (#931).
|
|
1908
|
+
*
|
|
1909
|
+
* @internal
|
|
1910
|
+
*/
|
|
1911
|
+
type EntryCommandable = Omit<SubCommandable, 'args' | 'run'> & {
|
|
1912
|
+
args?: Args;
|
|
1913
|
+
run?: (...args: any[]) => Awaitable<string | void | JsonResult>;
|
|
1914
|
+
};
|
|
1676
1915
|
/**
|
|
1677
1916
|
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1678
1917
|
* To have them, use `cli` from `gunshi`.
|
|
1679
1918
|
*
|
|
1680
|
-
*
|
|
1919
|
+
* An object written as the entry command is typed by its `args`, as with `define`: `ctx.values` of its `run` are
|
|
1920
|
+
* inferred from them, and a key that an argument does not have is an error.
|
|
1921
|
+
*
|
|
1922
|
+
* @typeParam A - The type of {@linkcode Args | arguments} of the entry command, inferred from its `args`.
|
|
1923
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}, which is not inferred: `{ args: A; extensions: {} }`.
|
|
1681
1924
|
*
|
|
1682
1925
|
* @param args - Command line arguments
|
|
1683
1926
|
* @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
|
|
1684
1927
|
* @param options - A {@link CliOptions | CLI options}
|
|
1685
1928
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1686
1929
|
*/
|
|
1687
|
-
declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1930
|
+
export declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
1688
1931
|
args: A;
|
|
1689
1932
|
extensions: {};
|
|
1690
|
-
}>(args: string[], entry: Command<
|
|
1933
|
+
}>(args: string[], entry: (Command<NoInferParams<G>> & {
|
|
1934
|
+
args?: A & UnknownArgKeys<A>;
|
|
1935
|
+
}) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>;
|
|
1691
1936
|
/**
|
|
1692
1937
|
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1693
1938
|
* To have them, use `cli` from `gunshi`.
|
|
@@ -1699,7 +1944,7 @@ declare function cli<A extends Args = Args, G extends GunshiParams = {
|
|
|
1699
1944
|
* @param options - A {@link CliOptions | CLI options}
|
|
1700
1945
|
* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1701
1946
|
*/
|
|
1702
|
-
declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1947
|
+
export declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
|
|
1703
1948
|
args: Args;
|
|
1704
1949
|
extensions: E;
|
|
1705
1950
|
}>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
@@ -1714,6 +1959,20 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
|
|
|
1714
1959
|
* @param options - A {@link CliOptions | CLI options}
|
|
1715
1960
|
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1716
1961
|
*/
|
|
1717
|
-
declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1718
|
-
|
|
1719
|
-
|
|
1962
|
+
export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1963
|
+
/**
|
|
1964
|
+
* Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
|
|
1965
|
+
* To have them, use `cli` from `gunshi`.
|
|
1966
|
+
*
|
|
1967
|
+
* This overload takes a command of another copy of the types of gunshi, such as a command of `@gunshi/definition`,
|
|
1968
|
+
* whose types the overloads above cannot compare. `@gunshi/bone` exports no `define`, so a CLI on it defines its
|
|
1969
|
+
* commands with another package. Its arguments are checked as `Args`, and its runner returns what a runner returns. It
|
|
1970
|
+
* must be the last of the overloads.
|
|
1971
|
+
*
|
|
1972
|
+
* @param args - Command line arguments
|
|
1973
|
+
* @param entry - A command-like object (command, command runner, or lazy command)
|
|
1974
|
+
* @param options - A {@link CliOptions | CLI options}
|
|
1975
|
+
* @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
|
|
1976
|
+
*/
|
|
1977
|
+
export declare function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>;
|
|
1978
|
+
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 };
|