@gunshi/bone 1.0.0-rc.6 → 1.0.0-rc.8

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