@gunshi/bone 1.0.0-rc.1 → 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.
Files changed (4) hide show
  1. package/README.md +0 -6
  2. package/lib/index.d.ts +407 -63
  3. package/lib/index.js +627 -265
  4. package/package.json +32 -38
package/lib/index.d.ts CHANGED
@@ -1,5 +1,10 @@
1
- //#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
2
- //#region src/parser.d.ts
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 `hidden` properties
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 options that conflict with this option.
450
+ * Names of other arguments that conflict with this argument.
423
451
  *
424
- * When this option is used together with any of the conflicting options, the error is an
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 starts with the kind of the argument given as `name`:
435
- * `Positional argument 'file' conflicts with '--stdin'` or
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: "Optional argument '--summer' conflicts with '--autumn'"
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: "Optional argument '--summer-season' conflicts with '--autumn-season'"
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: Command<G> | LazyCommand<G>): void;
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
- * Command name.
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 false
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 are given with {@linkcode CliOptions.subCommands}.
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
- * Command program name.
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
- * When enabled, option tokens that are not declared by the resolved command
1144
- * arguments or installed global options are reported as validation errors
1145
- * before the command runner is executed.
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
- * @default false
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 execution result
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
- * Command positionals arguments, that is the positionals of the command that is executed.
1250
- * Resolve positionals with `resolveArgs` from command arguments.
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 or lazy 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 void or string (for CLI output)
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 CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
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
- * Run the command.
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
- * @typeParam A - The type of {@linkcode Args | arguments} defined in the command and cli options.
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<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
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
- //#endregion
1635
- export { type ArgSchema, type ArgToken, type ArgValues, type Args, type Awaitable, type CliOptions, type Command, type CommandCallMode, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandDecorator, type CommandEnvironment, type CommandExamplesFetcher, type CommandLoader, type CommandRunner, type Commandable, type DefaultGunshiParams, type ExtendContext, type ExtractArgExplicitlyProvided, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type Prettify, type RendererDecorator, type RenderingOptions, type SubCommandable, type ValidationErrorsDecorator, cli };
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 };