@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.
Files changed (4) hide show
  1. package/README.md +0 -6
  2. package/lib/index.d.ts +452 -63
  3. package/lib/index.js +941 -429
  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,14 +1393,28 @@ 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
  /**
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 or lazy 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 void or string (for CLI output)
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 CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
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
- * Run the command.
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
- * @typeParam A - The type of {@linkcode Args | arguments} defined in the command and cli options.
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<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
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
- //#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 };
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 };