@gunshi/bone 1.0.0-rc.5 → 1.0.0-rc.7

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 (3) hide show
  1. package/lib/index.d.ts +263 -43
  2. package/lib/index.js +501 -246
  3. package/package.json +32 -33
package/lib/index.d.ts CHANGED
@@ -1,4 +1,10 @@
1
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser-DvPxBZG9.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";
2
8
  /**
3
9
  * Entry point of argument parser.
4
10
  *
@@ -54,13 +60,11 @@ interface ArgToken {
54
60
  */
55
61
  inlineValue?: boolean | undefined;
56
62
  }
57
- //#endregion
58
- //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
59
63
  /**
60
64
  * An argument schema definition for command-line argument parsing.
61
65
  *
62
66
  * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
63
- * - Additional `required`, `description`, and `hidden` properties
67
+ * - Additional `required`, `description`, `hidden`, and `deprecated` properties
64
68
  * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
65
69
  * - Simplified `default` property (single type, not union types)
66
70
  *
@@ -190,6 +194,32 @@ interface ArgSchema {
190
194
  * ```
191
195
  */
192
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;
193
223
  /**
194
224
  * Marks the argument as required.
195
225
  *
@@ -695,8 +725,6 @@ type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] ex
695
725
  * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
696
726
  */
697
727
  type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean; };
698
- //#endregion
699
- //#region ../gunshi/src/plugin/context.d.ts
700
728
  /**
701
729
  * Gunshi plugin context interface.
702
730
  *
@@ -730,7 +758,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
730
758
  * @param name - Command name
731
759
  * @param command - Command definition
732
760
  */
733
- addCommand(name: string, command: Command<G> | LazyCommand<G>): void;
761
+ addCommand(name: string, command: SubCommandable): void;
734
762
  /**
735
763
  * Check if a command exists.
736
764
  *
@@ -771,10 +799,8 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
771
799
  *
772
800
  * @param decorator - A decorator function that wraps the command runner
773
801
  */
774
- 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;
775
803
  }
776
- //#endregion
777
- //#region ../gunshi/src/plugin/core.d.ts
778
804
  /**
779
805
  * Plugin dependency definition
780
806
  *
@@ -815,8 +841,6 @@ type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensio
815
841
  dependencies?: (PluginDependency | string)[];
816
842
  extension?: CommandContextExtension<E>;
817
843
  };
818
- //#endregion
819
- //#region ../gunshi/src/types.d.ts
820
844
  /**
821
845
  * Awaitable type.
822
846
  *
@@ -1008,7 +1032,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
1008
1032
  * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
1009
1033
  *
1010
1034
  * Output that must still appear — machine-readable results for an agent, warnings for the
1011
- * 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.
1012
1040
  *
1013
1041
  * @default false
1014
1042
  * @see {@linkcode CliOptions.usageSilent}
@@ -1021,6 +1049,28 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
1021
1049
  * @see {@linkcode CliOptions.strict}
1022
1050
  */
1023
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;
1024
1074
  /**
1025
1075
  * Sub commands.
1026
1076
  *
@@ -1068,7 +1118,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
1068
1118
  */
1069
1119
  onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
1070
1120
  /**
1071
- * 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.
1072
1123
  *
1073
1124
  * @see {@linkcode CliOptions.onAfterCommand}
1074
1125
  * @since v0.27.0
@@ -1109,9 +1160,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1109
1160
  * Sub commands.
1110
1161
  *
1111
1162
  * An object or a Map keyed by the sub-command names, or an array of commands, which are keyed by their names.
1163
+ * A value of the object or the Map may also be a loader, a function that returns the command or its runner,
1164
+ * which runs as a lazy command named after its key.
1112
1165
  * When this is not given, the {@linkcode Command.subCommands} of the entry command are the sub-commands.
1113
1166
  */
1114
- subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
1167
+ subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
1115
1168
  /**
1116
1169
  * Left margin of the command output.
1117
1170
  */
@@ -1133,10 +1186,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1133
1186
  * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
1134
1187
  *
1135
1188
  * Output that must still appear — machine-readable results for an agent, warnings for the
1136
- * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
1189
+ * CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
1190
+ * `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
1137
1191
  *
1138
- * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
1139
- * report them (see {@linkcode CliOptions.renderValidationErrors}).
1192
+ * The validation errors, and a `CommandError` that the command throws, are not printed either, so
1193
+ * `cli()` rejects with them, for the caller to report them (see
1194
+ * {@linkcode CliOptions.renderValidationErrors}). The exit code is left alone.
1140
1195
  *
1141
1196
  * @default false
1142
1197
  */
@@ -1148,9 +1203,34 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1148
1203
  * arguments or installed global options are reported as validation errors
1149
1204
  * before the command runner is executed.
1150
1205
  *
1206
+ * With the global options plugin, `--help` and `--version` are still answered: given with them, an
1207
+ * unknown option is not reported, as the other argument validation errors are not. An unknown command
1208
+ * is still reported.
1209
+ *
1210
+ * `--json` is not reported, since gunshi knows what it means: given to a command that does not
1211
+ * spread `jsonArgs`, the global options plugin reports `json_not_supported` for it instead, with or
1212
+ * without `strict`. `--json=false` asks for no JSON, and is reported.
1213
+ *
1151
1214
  * @default false
1152
1215
  */
1153
1216
  strict?: boolean;
1217
+ /**
1218
+ * Whether to treat the positional arguments that the command does not take as argument validation
1219
+ * errors, as `strict` does for the options.
1220
+ *
1221
+ * When enabled, the positional arguments after the command path that the positional arguments of the
1222
+ * resolved command do not take are reported as validation errors before the command runner is
1223
+ * executed. A command takes as many as it declares, an optional one included, and any number with a
1224
+ * positional argument with `multiple: true`. The arguments after `--` are not positional arguments:
1225
+ * they stay in `rest`.
1226
+ *
1227
+ * With the global options plugin, `--help` and `--version` are still answered, as they are with the
1228
+ * other argument validation errors. After a command with sub-commands, a word that is not one of them
1229
+ * is reported as an unknown command instead.
1230
+ *
1231
+ * @default false
1232
+ */
1233
+ strictPositionals?: boolean;
1154
1234
  /**
1155
1235
  * Render function the command usage.
1156
1236
  */
@@ -1163,15 +1243,60 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1163
1243
  * Render function the validation errors.
1164
1244
  *
1165
1245
  * With the global options plugin, the rendered message is printed to stderr, the exit code is set
1166
- * to `1`, {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
1246
+ * to {@linkcode CliOptions.validationErrorExitCode}, `1` by default,
1247
+ * {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
1248
+ * The message is followed by the command that shows the help, unless {@linkcode CliOptions.helpHint}
1249
+ * is `false`.
1167
1250
  * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
1168
1251
  * with the `AggregateError`. A renderer that returns an empty message, and
1169
1252
  * {@linkcode CliOptions.usageSilent}, also leave them to the caller.
1253
+ *
1254
+ * With `--json`, the plugin prints the validation errors as one line of JSON, and does not call
1255
+ * the renderer. `null` and {@linkcode CliOptions.usageSilent} still leave them to the caller.
1170
1256
  */
1171
1257
  renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
1258
+ /**
1259
+ * Whether to follow the validation errors with the command that shows the help of the nearest
1260
+ * command: the command itself for an argument error, and the parent of an unknown command, such as
1261
+ * `my-app deploy --help`. With the global options plugin, it is printed to stderr after the errors,
1262
+ * after an empty line and a heading. It is the command that `next` of the JSON error has with
1263
+ * `--json`.
1264
+ *
1265
+ * Set it to `false` to leave the command out, such as when your renderer of the validation errors
1266
+ * points to the help in its own way. It changes the output for people only: `next` of the JSON error
1267
+ * stays. The command is left out for a command whose `--help` does not show the help, too: one that
1268
+ * declares a `help` argument of its own, or with `renderUsage: null`.
1269
+ *
1270
+ * @default true
1271
+ */
1272
+ helpHint?: boolean;
1273
+ /**
1274
+ * The exit code of the validation errors, such as `2`, the exit code of a usage error in many
1275
+ * command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown
1276
+ * command or a command line that cannot be resolved, an unknown option of `strict`, a positional
1277
+ * argument that the command does not take of `strictPositionals`, and `--json` given to a command
1278
+ * that does not spread `jsonArgs`. With the global options plugin, the exit code is set to it when
1279
+ * the errors are printed, as text or as JSON, before {@linkcode CliOptions.onErrorCommand} is called,
1280
+ * which can still change it.
1281
+ *
1282
+ * It is an integer from `1` to `255`, as the `exitCode` of a `CommandError` is, and any other value is
1283
+ * replaced with `1`. It does not change the exit code of a `CommandError`, nor of any other error that a
1284
+ * command throws. With `renderValidationErrors: null`, a renderer that returns an empty message, or
1285
+ * {@linkcode CliOptions.usageSilent}, nothing is printed, and the exit code is left alone.
1286
+ *
1287
+ * @default 1
1288
+ */
1289
+ validationErrorExitCode?: number;
1172
1290
  /**
1173
1291
  * Whether to fallback to entry command when the sub-command is not found.
1174
1292
  *
1293
+ * When it is not set, it is `true` for a CLI that declares no sub-commands and to which a plugin adds
1294
+ * commands, such as the `complete` command of `@gunshi/plugin-completion`, so that the positional
1295
+ * arguments of the entry command are not taken for command names. This is so when the entry command
1296
+ * has something to run: a command object with `run`, a lazy command, whose loader gives the runner,
1297
+ * or a runner given to `cli()`. For a command object without `run`, it stays `false`: the commands of
1298
+ * the plugins are then the commands of the CLI, and an argument that is not one of them is reported.
1299
+ *
1175
1300
  * @default false
1176
1301
  * @since v0.27.0
1177
1302
  */
@@ -1193,16 +1318,18 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1193
1318
  * Hook that runs after successful command execution
1194
1319
  *
1195
1320
  * @param ctx - The command context
1196
- * @param result - The command execution result
1321
+ * @param result - The result of the command, when it is a string. The result of a command that
1322
+ * prints JSON with `--json` is printed, not passed, so it is `undefined`
1197
1323
  * @since v0.27.0
1198
1324
  */
1199
1325
  onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
1200
1326
  /**
1201
1327
  * Hook that runs when a command throws an error, or when the arguments fail validation
1202
1328
  *
1203
- * For the validation errors that the global options plugin has printed, the exit code is already `1`
1204
- * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
1205
- * error rejects `cli()` after the hook.
1329
+ * For the validation errors and a `CommandError` that the global options plugin has printed, the
1330
+ * exit code is already set when the hook runs ({@linkcode CliOptions.validationErrorExitCode} for the
1331
+ * validation errors, and the `exitCode` of a `CommandError`), so the hook can set another one, and
1332
+ * `cli()` resolves after it. Any other error rejects `cli()` after the hook.
1206
1333
  *
1207
1334
  * @param ctx - The command context
1208
1335
  * @param error - The error thrown during execution, or the `AggregateError` of the validation errors
@@ -1260,8 +1387,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
1260
1387
  */
1261
1388
  values: ArgValues<ExtractArgs<G>>;
1262
1389
  /**
1263
- * Command positionals arguments, that is the positionals of the command that is executed.
1264
- * Resolve positionals with `resolveArgs` from command arguments.
1390
+ * The positional arguments of the command line, the names of the command path first: `app deploy web`
1391
+ * gives `['deploy', 'web']`. The positional arguments of the command itself are
1392
+ * `positionals.slice(commandPath.length)`, and the ones that it declares are in `values` too.
1265
1393
  */
1266
1394
  positionals: string[];
1267
1395
  /**
@@ -1279,6 +1407,9 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
1279
1407
  tokens: ArgToken[];
1280
1408
  /**
1281
1409
  * Whether the currently executing command has been executed with the sub-command name omitted.
1410
+ *
1411
+ * A command that has sub-commands and no {@linkcode Command.run | run} prints its usage then, with
1412
+ * the global options plugin, as `--help` does.
1282
1413
  */
1283
1414
  omitted: boolean;
1284
1415
  /**
@@ -1301,9 +1432,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
1301
1432
  */
1302
1433
  toKebab?: boolean;
1303
1434
  /**
1304
- * Output a message.
1435
+ * Output a message for people.
1305
1436
  *
1306
- * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
1437
+ * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output. Nor is it when a
1438
+ * command that spreads `jsonArgs` is asked for JSON with `--json`, so that stdout has the JSON only:
1439
+ * the hooks and the plugins get the same function.
1307
1440
  *
1308
1441
  * @param message - an output message, see {@linkcode console.log}
1309
1442
  * @param optionalParams - an optional parameters, see {@linkcode console.log}
@@ -1410,6 +1543,14 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1410
1543
  examples?: string | CommandExamplesFetcher<G>;
1411
1544
  /**
1412
1545
  * Command runner. it's the command to be executed
1546
+ *
1547
+ * A command that has sub-commands needs no runner: run without a sub-command, it prints its usage,
1548
+ * with the global options plugin, as `--help` does. A command with a runner runs it then, with
1549
+ * {@linkcode CommandContext.omitted | omitted} set to `true`.
1550
+ *
1551
+ * A command without sub-commands needs a runner. Without one, it throws a `TypeError` when it runs
1552
+ * (`'run' is required in command: <name>`), and `--help` still prints its usage. So does a lazy command
1553
+ * whose loader returns a command without a runner.
1413
1554
  */
1414
1555
  run?: CommandRunner<G>;
1415
1556
  /**
@@ -1425,6 +1566,34 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1425
1566
  * @since v0.27.0
1426
1567
  */
1427
1568
  internal?: boolean;
1569
+ /**
1570
+ * Other names of the command, such as `['ls']` for `list`.
1571
+ *
1572
+ * The command runs with any of them, as with its name, and `ctx.name` and `ctx.commandPath` have its name:
1573
+ * the help, the hints and the help as JSON tell the name of the command. An alias is accepted but not taught:
1574
+ * the help does not list it, and the `Did you mean` hint for an unknown command and shell completion do not
1575
+ * offer it.
1576
+ *
1577
+ * A sub-command whose name is the alias wins over the alias, so an alias never hides a command. Two commands
1578
+ * at the same level with the same alias are a mistake: using the alias throws a `TypeError`. A lazy command
1579
+ * takes its aliases from the definition given to `lazy`, as it is found before it is loaded.
1580
+ */
1581
+ aliases?: readonly string[];
1582
+ /**
1583
+ * Whether the command is deprecated: `true`, or the text that tells what to use instead, such as `'Use deploy.'`.
1584
+ *
1585
+ * A deprecated command still runs. With the global options plugin, it prints a warning to stderr when it runs,
1586
+ * once: `push is deprecated. Use deploy.`, and not when the command is asked for JSON with `--json`. A command
1587
+ * under a deprecated group, such as the old name of a renamed group, warns of the group too. Its help says that
1588
+ * it is deprecated, after its description. As an internal command, it is left out of the help, the
1589
+ * `Did you mean` hint for an unknown command, shell completion and the help as JSON, so that they teach what to
1590
+ * use instead.
1591
+ *
1592
+ * To rename a command, keep the old name as a deprecated command that runs as the new one, such as
1593
+ * `push: define({ ...deploy, name: 'push', aliases: [], deprecated: 'Use deploy.' })`, where `aliases: []` takes
1594
+ * the aliases that the spread copies off the old name. It has no effect on the entry command.
1595
+ */
1596
+ deprecated?: boolean | string;
1428
1597
  /**
1429
1598
  * Whether this command is an entry command.
1430
1599
  *
@@ -1442,14 +1611,15 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1442
1611
  * Nested sub-commands for this command.
1443
1612
  *
1444
1613
  * Allows building command trees like `git remote add`.
1445
- * Each key is the sub-command name, and the value is a command or lazy command.
1614
+ * Each key is the sub-command name, and the value is a command, a lazy command, or a loader, a function that
1615
+ * returns the command or its runner, which runs as a lazy command named after its key.
1446
1616
  * An array of commands is keyed by the names of the commands.
1447
1617
  *
1448
1618
  * On the entry command, these are the top-level sub-commands when {@linkcode CliOptions.subCommands} is not given.
1449
1619
  *
1450
1620
  * @since v0.28.0
1451
1621
  */
1452
- subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
1622
+ subCommands?: Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[];
1453
1623
  }
1454
1624
  /**
1455
1625
  * Lazy command interface.
@@ -1477,6 +1647,13 @@ type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D exten
1477
1647
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
1478
1648
  */
1479
1649
  type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
1650
+ /**
1651
+ * A function given as a sub-command, which the CLI loads as a lazy command named after its key:
1652
+ * it returns the command, or its runner
1653
+ *
1654
+ * @internal
1655
+ */
1656
+ type SubCommandLoader = () => Awaitable<SubCommandable | ((...args: any[]) => any)>;
1480
1657
  /**
1481
1658
  * Sub-command entry type for use in subCommands.
1482
1659
  *
@@ -1514,6 +1691,14 @@ interface SubCommandable {
1514
1691
  * see {@link Command.internal}
1515
1692
  */
1516
1693
  internal?: boolean;
1694
+ /**
1695
+ * see {@link Command.aliases}
1696
+ */
1697
+ aliases?: readonly string[];
1698
+ /**
1699
+ * see {@link Command.deprecated}
1700
+ */
1701
+ deprecated?: boolean | string;
1517
1702
  /**
1518
1703
  * see {@link Command.entry}
1519
1704
  */
@@ -1533,10 +1718,6 @@ interface SubCommandable {
1533
1718
  * @since v0.28.0
1534
1719
  */
1535
1720
  subCommands?: Record<string, any> | Map<string, any> | readonly any[];
1536
- /**
1537
- * Index signature to allow additional properties
1538
- */
1539
- [key: string]: any;
1540
1721
  }
1541
1722
  /**
1542
1723
  * Command examples fetcher.
@@ -1553,15 +1734,53 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
1553
1734
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
1554
1735
  *
1555
1736
  * @param ctx - A {@link CommandContext | command context}
1556
- * @returns void or string (for CLI output)
1737
+ * @returns The result of a command that spreads `jsonArgs`, an object keyed by a noun, which is printed
1738
+ * as JSON with `--json`. For any other command, a string, which `cli()` returns, or nothing. See
1739
+ * {@linkcode CommandRunnerResult}.
1740
+ */
1741
+ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => CommandRunnerResult<G>;
1742
+ /**
1743
+ * The result of a command that supports `--json`: an object keyed by a noun, such as
1744
+ * `{ project }` or `{ projects }`, so that fields can be added later. The global options plugin prints
1745
+ * it with `JSON.stringify`, so convert what JSON cannot hold, such as a `Map` or a `BigInt`, yourself.
1557
1746
  */
1558
- type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
1747
+ type JsonResult = Record<string, unknown>;
1748
+ /**
1749
+ * Whether the arguments have the `json` of `jsonArgs`.
1750
+ *
1751
+ * @typeParam A - The arguments of a command
1752
+ */
1753
+ type HasJsonArgs<A> = [A] extends [{
1754
+ readonly json: {
1755
+ readonly [JSON_ARG]: true;
1756
+ };
1757
+ }] ? true : false;
1758
+ /**
1759
+ * What the runner of a command returns: its result for a command that spreads `jsonArgs`, otherwise a string or
1760
+ * nothing.
1761
+ *
1762
+ * @typeParam G - A type extending {@linkcode GunshiParams}
1763
+ */
1764
+ 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>;
1765
+ /**
1766
+ * Whether the arguments are `any`, as in `CommandRunner<any>`. Then a runner may return anything it could before.
1767
+ *
1768
+ * @internal
1769
+ */
1770
+ type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
1559
1771
  /**
1560
1772
  * Command loader.
1561
1773
  *
1562
1774
  * A function that returns a command or command runner.
1563
1775
  * This is used to lazily load commands.
1564
1776
  *
1777
+ * Any other value, such as `null` or `undefined`, fails with `Cannot resolve command: <name>`. To tell
1778
+ * what went wrong, such as a module that is not found, throw an error instead, such as a
1779
+ * `CommandError`. An error of the loading is thrown where the command would run, as an error of
1780
+ * `run` is: a `CommandError` prints its message with its exit code, `--json` prints the failure as JSON,
1781
+ * and `onErrorCommand` sees it. Until then, the definition given to `lazy` stands for the command, so that
1782
+ * `--help` prints its usage.
1783
+ *
1565
1784
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context and command runner.
1566
1785
  *
1567
1786
  * @returns A command or command runner
@@ -1572,6 +1791,10 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
1572
1791
  *
1573
1792
  * A function that wraps a command runner to add or modify its behavior.
1574
1793
  *
1794
+ * The decorated runner returns what the base runner returns, as it is: the result of a command that
1795
+ * spreads `jsonArgs` must reach the global options plugin, which prints it as JSON with `--json`. A
1796
+ * decorator prints with `ctx.log`, which is silenced then.
1797
+ *
1575
1798
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
1576
1799
  *
1577
1800
  * @param baseRunner - The base command runner to decorate
@@ -1579,7 +1802,7 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
1579
1802
  *
1580
1803
  * @since v0.27.0
1581
1804
  */
1582
- type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
1805
+ type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>;
1583
1806
  /**
1584
1807
  * Renderer decorator type.
1585
1808
  *
@@ -1609,8 +1832,6 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
1609
1832
  * @since v0.27.0
1610
1833
  */
1611
1834
  type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
1612
- //#endregion
1613
- //#region ../gunshi/src/cli/bone.d.ts
1614
1835
  /**
1615
1836
  * Run the command, without the built-in plugins: `--help` and `--version` print nothing, unless you add the plugins.
1616
1837
  * To have them, use `cli` from `gunshi`.
@@ -1622,7 +1843,7 @@ type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiP
1622
1843
  * @param options - A {@link CliOptions | CLI options}
1623
1844
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
1624
1845
  */
1625
- declare function cli<A extends Args = Args, G extends GunshiParams = {
1846
+ export declare function cli<A extends Args = Args, G extends GunshiParams = {
1626
1847
  args: A;
1627
1848
  extensions: {};
1628
1849
  }>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
@@ -1637,7 +1858,7 @@ declare function cli<A extends Args = Args, G extends GunshiParams = {
1637
1858
  * @param options - A {@link CliOptions | CLI options}
1638
1859
  * @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
1639
1860
  */
1640
- declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
1861
+ export declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
1641
1862
  args: Args;
1642
1863
  extensions: E;
1643
1864
  }>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
@@ -1652,6 +1873,5 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
1652
1873
  * @param options - A {@link CliOptions | CLI options}
1653
1874
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
1654
1875
  */
1655
- declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
1656
- //#endregion
1657
- 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 };
1876
+ export declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
1877
+ 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 };