@gunshi/bone 1.0.0-rc.4 → 1.0.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +0 -6
- package/lib/index.d.ts +86 -27
- package/lib/index.js +80 -17
- package/package.json +6 -11
package/README.md
CHANGED
|
@@ -2,7 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
[![Version][npm-version-src]][npm-version-href]
|
|
4
4
|
[![InstallSize][install-size-src]][install-size-src]
|
|
5
|
-
[![JSR][jsr-src]][jsr-href]
|
|
6
5
|
|
|
7
6
|
> gunshi minimum
|
|
8
7
|
|
|
@@ -35,9 +34,6 @@ pnpm add @gunshi/bone
|
|
|
35
34
|
## yarn
|
|
36
35
|
yarn add @gunshi/bone
|
|
37
36
|
|
|
38
|
-
## deno
|
|
39
|
-
deno add jsr:@gunshi/bone
|
|
40
|
-
|
|
41
37
|
## bun
|
|
42
38
|
bun add @gunshi/bone
|
|
43
39
|
```
|
|
@@ -74,6 +70,4 @@ await cli(process.argv.slice(2), entry, {
|
|
|
74
70
|
|
|
75
71
|
[npm-version-src]: https://img.shields.io/npm/v/@gunshi/bone?style=flat
|
|
76
72
|
[npm-version-href]: https://npmjs.com/package/@gunshi/bone@alpha
|
|
77
|
-
[jsr-src]: https://jsr.io/badges/@gunshi/bone
|
|
78
|
-
[jsr-href]: https://jsr.io/@gunshi/bone
|
|
79
73
|
[install-size-src]: https://pkg-size.dev/badge/install/57026
|
package/lib/index.d.ts
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
|
-
//#region
|
|
2
|
-
|
|
1
|
+
//#region ../gunshi/src/constants.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* The key of the mark on the `json` argument of `jsonArgs`. A string key, not a symbol: `gunshi` and the other
|
|
4
|
+
* packages bundle their own copies of the types, and each copy of a `unique symbol` is a different type.
|
|
5
|
+
*
|
|
6
|
+
* @internal
|
|
7
|
+
*/
|
|
8
|
+
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
|
|
3
11
|
/**
|
|
4
12
|
* Entry point of argument parser.
|
|
5
13
|
*
|
|
@@ -56,8 +64,7 @@ interface ArgToken {
|
|
|
56
64
|
inlineValue?: boolean | undefined;
|
|
57
65
|
}
|
|
58
66
|
//#endregion
|
|
59
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.
|
|
60
|
-
//#region src/resolver.d.ts
|
|
67
|
+
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
|
|
61
68
|
/**
|
|
62
69
|
* An argument schema definition for command-line argument parsing.
|
|
63
70
|
*
|
|
@@ -419,9 +426,9 @@ interface ArgSchema {
|
|
|
419
426
|
*/
|
|
420
427
|
toKebab?: true;
|
|
421
428
|
/**
|
|
422
|
-
* Names of other
|
|
429
|
+
* Names of other arguments that conflict with this argument.
|
|
423
430
|
*
|
|
424
|
-
* When this
|
|
431
|
+
* When this argument is used together with any of the conflicting arguments, the error is an
|
|
425
432
|
* `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
|
|
426
433
|
* ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
|
|
427
434
|
* the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
|
|
@@ -431,9 +438,8 @@ interface ArgSchema {
|
|
|
431
438
|
*
|
|
432
439
|
* A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
|
|
433
440
|
* 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
|
|
435
|
-
* `
|
|
436
|
-
* `Optional argument '--stdin' conflicts with 'file'`.
|
|
441
|
+
* in its other errors. The message names the argument given as `name` first:
|
|
442
|
+
* `'file' conflicts with '--stdin'` or `'--stdin' conflicts with 'file'`.
|
|
437
443
|
*
|
|
438
444
|
* Conflicts only need to be defined on one side - if option A defines a conflict
|
|
439
445
|
* with option B, the conflict is automatically detected when both are used,
|
|
@@ -472,7 +478,7 @@ interface ArgSchema {
|
|
|
472
478
|
* }
|
|
473
479
|
* }
|
|
474
480
|
* // Usage: --summer --autumn reports an error
|
|
475
|
-
* // Error: "
|
|
481
|
+
* // Error: "'--summer' conflicts with '--autumn'"
|
|
476
482
|
* ```
|
|
477
483
|
*
|
|
478
484
|
* @example
|
|
@@ -512,7 +518,7 @@ interface ArgSchema {
|
|
|
512
518
|
* toKebab: true // Accessible as --autumn-season
|
|
513
519
|
* }
|
|
514
520
|
* }
|
|
515
|
-
* // Error: "
|
|
521
|
+
* // Error: "'--summer-season' conflicts with '--autumn-season'"
|
|
516
522
|
* ```
|
|
517
523
|
*/
|
|
518
524
|
conflicts?: string | string[];
|
|
@@ -733,7 +739,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
733
739
|
* @param name - Command name
|
|
734
740
|
* @param command - Command definition
|
|
735
741
|
*/
|
|
736
|
-
addCommand(name: string, command:
|
|
742
|
+
addCommand(name: string, command: SubCommandable): void;
|
|
737
743
|
/**
|
|
738
744
|
* Check if a command exists.
|
|
739
745
|
*
|
|
@@ -774,7 +780,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
774
780
|
*
|
|
775
781
|
* @param decorator - A decorator function that wraps the command runner
|
|
776
782
|
*/
|
|
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;
|
|
783
|
+
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
784
|
}
|
|
779
785
|
//#endregion
|
|
780
786
|
//#region ../gunshi/src/plugin/core.d.ts
|
|
@@ -1011,7 +1017,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1011
1017
|
* (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
|
|
1012
1018
|
*
|
|
1013
1019
|
* 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`.
|
|
1020
|
+
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
|
|
1021
|
+
* `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
|
|
1022
|
+
*
|
|
1023
|
+
* The validation errors, and a `CommandError` that the command throws, are not printed either, so
|
|
1024
|
+
* `cli()` rejects with them, for the caller to report them.
|
|
1015
1025
|
*
|
|
1016
1026
|
* @default false
|
|
1017
1027
|
* @see {@linkcode CliOptions.usageSilent}
|
|
@@ -1071,7 +1081,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
|
|
|
1071
1081
|
*/
|
|
1072
1082
|
onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
|
|
1073
1083
|
/**
|
|
1074
|
-
* Hook that runs after successful command execution
|
|
1084
|
+
* Hook that runs after successful command execution. It receives the result of the command only
|
|
1085
|
+
* when it is a string.
|
|
1075
1086
|
*
|
|
1076
1087
|
* @see {@linkcode CliOptions.onAfterCommand}
|
|
1077
1088
|
* @since v0.27.0
|
|
@@ -1136,10 +1147,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1136
1147
|
* (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
|
|
1137
1148
|
*
|
|
1138
1149
|
* Output that must still appear — machine-readable results for an agent, warnings for the
|
|
1139
|
-
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
|
|
1150
|
+
* CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
|
|
1151
|
+
* `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
|
|
1140
1152
|
*
|
|
1141
|
-
* The validation errors
|
|
1142
|
-
* report them (see
|
|
1153
|
+
* The validation errors, and a `CommandError` that the command throws, are not printed either, so
|
|
1154
|
+
* `cli()` rejects with them, for the caller to report them (see
|
|
1155
|
+
* {@linkcode CliOptions.renderValidationErrors}). The exit code is left alone.
|
|
1143
1156
|
*
|
|
1144
1157
|
* @default false
|
|
1145
1158
|
*/
|
|
@@ -1151,6 +1164,10 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1151
1164
|
* arguments or installed global options are reported as validation errors
|
|
1152
1165
|
* before the command runner is executed.
|
|
1153
1166
|
*
|
|
1167
|
+
* `--json` is not reported, since gunshi knows what it means: given to a command that does not
|
|
1168
|
+
* spread `jsonArgs`, the global options plugin reports `json_not_supported` for it instead, with or
|
|
1169
|
+
* without `strict`. `--json=false` asks for no JSON, and is reported.
|
|
1170
|
+
*
|
|
1154
1171
|
* @default false
|
|
1155
1172
|
*/
|
|
1156
1173
|
strict?: boolean;
|
|
@@ -1170,6 +1187,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1170
1187
|
* Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
|
|
1171
1188
|
* with the `AggregateError`. A renderer that returns an empty message, and
|
|
1172
1189
|
* {@linkcode CliOptions.usageSilent}, also leave them to the caller.
|
|
1190
|
+
*
|
|
1191
|
+
* With `--json`, the plugin prints the validation errors as one line of JSON, and does not call
|
|
1192
|
+
* the renderer. `null` and {@linkcode CliOptions.usageSilent} still leave them to the caller.
|
|
1173
1193
|
*/
|
|
1174
1194
|
renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
|
|
1175
1195
|
/**
|
|
@@ -1196,15 +1216,17 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
|
1196
1216
|
* Hook that runs after successful command execution
|
|
1197
1217
|
*
|
|
1198
1218
|
* @param ctx - The command context
|
|
1199
|
-
* @param result - The command
|
|
1219
|
+
* @param result - The result of the command, when it is a string. The result of a command that
|
|
1220
|
+
* prints JSON with `--json` is printed, not passed, so it is `undefined`
|
|
1200
1221
|
* @since v0.27.0
|
|
1201
1222
|
*/
|
|
1202
1223
|
onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
|
|
1203
1224
|
/**
|
|
1204
1225
|
* Hook that runs when a command throws an error, or when the arguments fail validation
|
|
1205
1226
|
*
|
|
1206
|
-
* For the validation errors that the global options plugin has printed, the
|
|
1207
|
-
* when the hook runs
|
|
1227
|
+
* 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
|
|
1208
1230
|
* error rejects `cli()` after the hook.
|
|
1209
1231
|
*
|
|
1210
1232
|
* @param ctx - The command context
|
|
@@ -1304,9 +1326,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
|
|
|
1304
1326
|
*/
|
|
1305
1327
|
toKebab?: boolean;
|
|
1306
1328
|
/**
|
|
1307
|
-
* Output a message.
|
|
1329
|
+
* Output a message for people.
|
|
1308
1330
|
*
|
|
1309
|
-
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
|
|
1331
|
+
* If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output. Nor is it when a
|
|
1332
|
+
* command that spreads `jsonArgs` is asked for JSON with `--json`, so that stdout has the JSON only:
|
|
1333
|
+
* the hooks and the plugins get the same function.
|
|
1310
1334
|
*
|
|
1311
1335
|
* @param message - an output message, see {@linkcode console.log}
|
|
1312
1336
|
* @param optionalParams - an optional parameters, see {@linkcode console.log}
|
|
@@ -1556,9 +1580,40 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
|
|
|
1556
1580
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1557
1581
|
*
|
|
1558
1582
|
* @param ctx - A {@link CommandContext | command context}
|
|
1559
|
-
* @returns
|
|
1583
|
+
* @returns The result of a command that spreads `jsonArgs`, an object keyed by a noun, which is printed
|
|
1584
|
+
* as JSON with `--json`. For any other command, a string, which `cli()` returns, or nothing. See
|
|
1585
|
+
* {@linkcode CommandRunnerResult}.
|
|
1586
|
+
*/
|
|
1587
|
+
type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => CommandRunnerResult<G>;
|
|
1588
|
+
/**
|
|
1589
|
+
* The result of a command that supports `--json`: an object keyed by a noun, such as
|
|
1590
|
+
* `{ project }` or `{ projects }`, so that fields can be added later. The global options plugin prints
|
|
1591
|
+
* it with `JSON.stringify`, so convert what JSON cannot hold, such as a `Map` or a `BigInt`, yourself.
|
|
1560
1592
|
*/
|
|
1561
|
-
type
|
|
1593
|
+
type JsonResult = Record<string, unknown>;
|
|
1594
|
+
/**
|
|
1595
|
+
* Whether the arguments have the `json` of `jsonArgs`.
|
|
1596
|
+
*
|
|
1597
|
+
* @typeParam A - The arguments of a command
|
|
1598
|
+
*/
|
|
1599
|
+
type HasJsonArgs<A> = [A] extends [{
|
|
1600
|
+
readonly json: {
|
|
1601
|
+
readonly [JSON_ARG]: true;
|
|
1602
|
+
};
|
|
1603
|
+
}] ? true : false;
|
|
1604
|
+
/**
|
|
1605
|
+
* What the runner of a command returns: its result for a command that spreads `jsonArgs`, otherwise a string or
|
|
1606
|
+
* nothing.
|
|
1607
|
+
*
|
|
1608
|
+
* @typeParam G - A type extending {@linkcode GunshiParams}
|
|
1609
|
+
*/
|
|
1610
|
+
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>;
|
|
1611
|
+
/**
|
|
1612
|
+
* Whether the arguments are `any`, as in `CommandRunner<any>`. Then a runner may return anything it could before.
|
|
1613
|
+
*
|
|
1614
|
+
* @internal
|
|
1615
|
+
*/
|
|
1616
|
+
type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
|
|
1562
1617
|
/**
|
|
1563
1618
|
* Command loader.
|
|
1564
1619
|
*
|
|
@@ -1575,6 +1630,10 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1575
1630
|
*
|
|
1576
1631
|
* A function that wraps a command runner to add or modify its behavior.
|
|
1577
1632
|
*
|
|
1633
|
+
* The decorated runner returns what the base runner returns, as it is: the result of a command that
|
|
1634
|
+
* spreads `jsonArgs` must reach the global options plugin, which prints it as JSON with `--json`. A
|
|
1635
|
+
* decorator prints with `ctx.log`, which is silenced then.
|
|
1636
|
+
*
|
|
1578
1637
|
* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
|
|
1579
1638
|
*
|
|
1580
1639
|
* @param baseRunner - The base command runner to decorate
|
|
@@ -1582,7 +1641,7 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
|
|
|
1582
1641
|
*
|
|
1583
1642
|
* @since v0.27.0
|
|
1584
1643
|
*/
|
|
1585
|
-
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
|
|
1644
|
+
type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>;
|
|
1586
1645
|
/**
|
|
1587
1646
|
* Renderer decorator type.
|
|
1588
1647
|
*
|
|
@@ -1657,4 +1716,4 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
|
|
|
1657
1716
|
*/
|
|
1658
1717
|
declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
|
|
1659
1718
|
//#endregion
|
|
1660
|
-
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 };
|
|
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 };
|
package/lib/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.
|
|
1
|
+
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser.js
|
|
2
2
|
/**
|
|
3
3
|
* forked from `nodejs/node` (`pkgjs/parseargs`)
|
|
4
4
|
* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
|
|
@@ -201,7 +201,7 @@ function hasLongOptionPrefix(arg) {
|
|
|
201
201
|
return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
|
|
202
202
|
}
|
|
203
203
|
//#endregion
|
|
204
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.
|
|
204
|
+
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/utils.js
|
|
205
205
|
/**
|
|
206
206
|
* Entry point of utils.
|
|
207
207
|
*
|
|
@@ -232,7 +232,7 @@ function formatChoices(choices) {
|
|
|
232
232
|
return choices.map((value) => JSON.stringify(value)).join(", ");
|
|
233
233
|
}
|
|
234
234
|
//#endregion
|
|
235
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.
|
|
235
|
+
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver-Cx5Pw6-S.js
|
|
236
236
|
/**
|
|
237
237
|
* Internal definitions shared by the modules of `args-tokens`.
|
|
238
238
|
*
|
|
@@ -718,7 +718,7 @@ function parseSchemaValue(value, rawArg, option, schema) {
|
|
|
718
718
|
}
|
|
719
719
|
}
|
|
720
720
|
function createRequireError(rawArg, option, schema) {
|
|
721
|
-
return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `
|
|
721
|
+
return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `Option ${createOptionDisplayName(option, schema)} is required`, option, "required", schema, {
|
|
722
722
|
code: schema.type === "positional" ? ArgsValidationErrorKeys.requiredPositional : ArgsValidationErrorKeys.requiredOption,
|
|
723
723
|
values: schema.type === "positional" ? {
|
|
724
724
|
displayName: createArgumentDisplayName(option, schema),
|
|
@@ -840,7 +840,7 @@ function isNumeric(str) {
|
|
|
840
840
|
return str.trim() !== "" && !isNaN(str);
|
|
841
841
|
}
|
|
842
842
|
function createTypeError(rawArg, option, schema, actual, expected = schema.type) {
|
|
843
|
-
return new ArgResolveError(`
|
|
843
|
+
return new ArgResolveError(`Invalid value for ${createOptionDisplayName(option, schema)}: expected ${expected}`, option, "type", schema, {
|
|
844
844
|
code: ArgsValidationErrorKeys.invalidType,
|
|
845
845
|
values: {
|
|
846
846
|
displayName: createOptionDisplayName(option, schema),
|
|
@@ -870,7 +870,7 @@ function createMissingValueError(rawArg, option, schema, next) {
|
|
|
870
870
|
const suggestion = next === void 0 || !acceptsSuggestedValue(schema, next) ? void 0 : `--${option}=${next}`;
|
|
871
871
|
const hint = suggestion === void 0 ? "" : ` (to pass '${next}' as its value, write '${suggestion}')`;
|
|
872
872
|
const choices = schema.choices ?? [];
|
|
873
|
-
return new ArgResolveError(`
|
|
873
|
+
return new ArgResolveError(`Option ${displayName} requires a value${hint}`, option, "type", schema, {
|
|
874
874
|
code: ArgsValidationErrorKeys.missingValue,
|
|
875
875
|
values: {
|
|
876
876
|
displayName,
|
|
@@ -989,7 +989,7 @@ function hasPureParseBrand(parse) {
|
|
|
989
989
|
function createUnexpectedValueError(rawArg, option, schema, token) {
|
|
990
990
|
const rawName = token.rawName;
|
|
991
991
|
const displayName = `'${rawName}'`;
|
|
992
|
-
return new ArgResolveError(`
|
|
992
|
+
return new ArgResolveError(`Option ${displayName} does not take a value`, option, "type", schema, {
|
|
993
993
|
code: ArgsValidationErrorKeys.unexpectedValue,
|
|
994
994
|
values: {
|
|
995
995
|
displayName,
|
|
@@ -1001,7 +1001,7 @@ function createUnexpectedValueError(rawArg, option, schema, token) {
|
|
|
1001
1001
|
}
|
|
1002
1002
|
function createChoiceError(rawArg, option, schema, actual) {
|
|
1003
1003
|
const choices = schema.choices ?? [];
|
|
1004
|
-
return new ArgResolveError(`
|
|
1004
|
+
return new ArgResolveError(`Invalid value for ${createOptionDisplayName(option, schema)}: expected one of ${formatChoices(choices)}`, option, "type", schema, {
|
|
1005
1005
|
code: ArgsValidationErrorKeys.invalidChoice,
|
|
1006
1006
|
values: {
|
|
1007
1007
|
displayName: createOptionDisplayName(option, schema),
|
|
@@ -1027,7 +1027,7 @@ function createChoiceError(rawArg, option, schema, actual) {
|
|
|
1027
1027
|
function createDefaultChoiceError(rawArg, option, schema) {
|
|
1028
1028
|
const choices = schema.choices ?? [];
|
|
1029
1029
|
const displayName = createOptionDisplayName(option, schema);
|
|
1030
|
-
return new ArgResolveError(`
|
|
1030
|
+
return new ArgResolveError(`Invalid default for ${displayName}: ${typeof schema.default === "string" ? JSON.stringify(schema.default) : String(schema.default)} is not one of ${formatChoices(choices)}`, option, "type", schema, {
|
|
1031
1031
|
code: ArgsValidationErrorKeys.invalidDefault,
|
|
1032
1032
|
values: {
|
|
1033
1033
|
displayName,
|
|
@@ -1043,10 +1043,11 @@ function createCustomParseError(error, rawArg, option, schema, value) {
|
|
|
1043
1043
|
const reused = reuseValidationError(error, rawArg, option, schema, value);
|
|
1044
1044
|
if (reused) return reused;
|
|
1045
1045
|
const reason = getErrorReason(error);
|
|
1046
|
-
|
|
1046
|
+
const displayName = createArgumentDisplayName(option, schema);
|
|
1047
|
+
return new ArgsValidationError(`Invalid value for ${displayName}: ${reason}`, {
|
|
1047
1048
|
code: ArgsValidationErrorKeys.customParse,
|
|
1048
1049
|
values: {
|
|
1049
|
-
displayName
|
|
1050
|
+
displayName,
|
|
1050
1051
|
name: rawArg,
|
|
1051
1052
|
reason
|
|
1052
1053
|
},
|
|
@@ -1056,6 +1057,11 @@ function createCustomParseError(error, rawArg, option, schema, value) {
|
|
|
1056
1057
|
/**
|
|
1057
1058
|
* Reuse an {@link ArgsValidationError} thrown from a custom `parse` function, filling in missing values.
|
|
1058
1059
|
*
|
|
1060
|
+
* An error with no `displayName` in its `values`, such as one thrown by the combinators, gets the
|
|
1061
|
+
* argument before its message, as a custom parse error does:
|
|
1062
|
+
* `Invalid value for '--port': Expected an integer, got 'abc'`. An error that names its argument keeps
|
|
1063
|
+
* its message.
|
|
1064
|
+
*
|
|
1059
1065
|
* @param error - The value thrown from `parse`
|
|
1060
1066
|
* @param rawArg - The argument key in the schema
|
|
1061
1067
|
* @param option - The option name used on the command line
|
|
@@ -1075,9 +1081,13 @@ function reuseValidationError(error, rawArg, option, schema, value) {
|
|
|
1075
1081
|
}
|
|
1076
1082
|
function augmentValidationError(error, rawArg, option, schema, value) {
|
|
1077
1083
|
const values = error.values;
|
|
1084
|
+
const named = values.displayName != null;
|
|
1078
1085
|
values.name ??= rawArg;
|
|
1079
1086
|
values.displayName ??= createArgumentDisplayName(option, schema);
|
|
1080
1087
|
if ((error.code === ArgsValidationErrorKeys.invalidType || error.code === ArgsValidationErrorKeys.invalidChoice) && values.actual == null) values.actual = value;
|
|
1088
|
+
if (!named) try {
|
|
1089
|
+
error.message = `Invalid value for ${String(values.displayName)}: ${error.message}`;
|
|
1090
|
+
} catch {}
|
|
1081
1091
|
}
|
|
1082
1092
|
function getErrorReason(error) {
|
|
1083
1093
|
return error instanceof Error ? error.message : String(error);
|
|
@@ -1092,8 +1102,8 @@ function createOptionDisplayName(option, schema) {
|
|
|
1092
1102
|
* Create the error for two arguments that conflict.
|
|
1093
1103
|
*
|
|
1094
1104
|
* An option is shown as it was written, such as `'-p'` or `'--no-color'`, and a positional argument
|
|
1095
|
-
* by its name, such as `'file'`, as in the message. The message
|
|
1096
|
-
*
|
|
1105
|
+
* by its name, such as `'file'`, as in the message. The message names first the argument whose
|
|
1106
|
+
* `conflicts` names the other one.
|
|
1097
1107
|
*
|
|
1098
1108
|
* @param rawArg - The argument key of the argument whose `conflicts` names the other one
|
|
1099
1109
|
* @param option - The name of that argument used on the command line
|
|
@@ -1107,7 +1117,7 @@ function createOptionDisplayName(option, schema) {
|
|
|
1107
1117
|
function createConflictError(rawArg, option, schema, actualName, conflictingArg, conflictingActualName) {
|
|
1108
1118
|
const displayName = `'${actualName}'`;
|
|
1109
1119
|
const conflictDisplayName = `'${conflictingActualName}'`;
|
|
1110
|
-
return new ArgResolveError(`${
|
|
1120
|
+
return new ArgResolveError(`${displayName} conflicts with ${conflictDisplayName}`, option, "conflict", schema, {
|
|
1111
1121
|
code: ArgsValidationErrorKeys.conflict,
|
|
1112
1122
|
values: {
|
|
1113
1123
|
displayName,
|
|
@@ -1134,7 +1144,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
|
|
|
1134
1144
|
return [];
|
|
1135
1145
|
}
|
|
1136
1146
|
//#endregion
|
|
1137
|
-
//#region ../../node_modules/.pnpm/args-tokens@1.0.
|
|
1147
|
+
//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/index.js
|
|
1138
1148
|
/**
|
|
1139
1149
|
* @author kazuya kawaguchi (a.k.a. kazupon)
|
|
1140
1150
|
* @license MIT
|
|
@@ -1179,6 +1189,51 @@ const CLI_OPTIONS_DEFAULT = {
|
|
|
1179
1189
|
* @license MIT
|
|
1180
1190
|
*/
|
|
1181
1191
|
/**
|
|
1192
|
+
* Check whether an argument schema is the `json` argument of `jsonArgs`, by its mark.
|
|
1193
|
+
*
|
|
1194
|
+
* @param schema - An argument schema
|
|
1195
|
+
* @returns `true` if the schema has the mark of `jsonArgs`
|
|
1196
|
+
*/
|
|
1197
|
+
function isJsonArg(schema) {
|
|
1198
|
+
return typeof schema === "object" && schema !== null && schema["~gunshi.json-arg"] === true;
|
|
1199
|
+
}
|
|
1200
|
+
/**
|
|
1201
|
+
* Resolve whether `--json` asks a command for JSON.
|
|
1202
|
+
*
|
|
1203
|
+
* A command that spreads `jsonArgs` is asked for JSON when the resolved value of its `json` is `true`:
|
|
1204
|
+
* with `--json`, or with a short name that the command gives it, but not with `--json=false`, nor with
|
|
1205
|
+
* `--json` after `--`. The raw tokens are read only when they are given, and only when there is no
|
|
1206
|
+
* value to read: when the command has no `json` argument, and when the core could not resolve the
|
|
1207
|
+
* command and left the values empty. A `json` argument without the mark belongs to the command, and
|
|
1208
|
+
* `--json` is never taken for a request then.
|
|
1209
|
+
*
|
|
1210
|
+
* @param args - The arguments of the command, the global options included
|
|
1211
|
+
* @param values - The resolved values of the arguments
|
|
1212
|
+
* @param tokens - The raw tokens of the arguments, to find a `--json` that no argument declares
|
|
1213
|
+
* @returns How the command is asked for JSON, or `undefined` when it is not
|
|
1214
|
+
*/
|
|
1215
|
+
function resolveJsonRequest(args, values, tokens) {
|
|
1216
|
+
const schema = Object.hasOwn(args, "json") ? args.json : void 0;
|
|
1217
|
+
if (schema === void 0) return tokens !== void 0 && hasJsonOption(tokens) ? "undeclared" : void 0;
|
|
1218
|
+
if (!isJsonArg(schema)) return;
|
|
1219
|
+
if (values.json !== void 0) return values.json === true ? "declared" : void 0;
|
|
1220
|
+
return tokens !== void 0 && hasJsonOption(tokens) ? "declared" : void 0;
|
|
1221
|
+
}
|
|
1222
|
+
/**
|
|
1223
|
+
* Check whether the raw tokens have a `--json` that asks for JSON: `--json` or `--json=true`, before
|
|
1224
|
+
* `--`. Without a declaration, a short name of `--json` is not known.
|
|
1225
|
+
*
|
|
1226
|
+
* @param tokens - The raw tokens of the arguments
|
|
1227
|
+
* @returns `true` if a `--json` asks for JSON
|
|
1228
|
+
*/
|
|
1229
|
+
function hasJsonOption(tokens) {
|
|
1230
|
+
for (const token of tokens) {
|
|
1231
|
+
if (token.kind === "option-terminator") return false;
|
|
1232
|
+
if (token.kind === "option" && token.rawName === "--json" && (token.value === void 0 || token.value === "true")) return true;
|
|
1233
|
+
}
|
|
1234
|
+
return false;
|
|
1235
|
+
}
|
|
1236
|
+
/**
|
|
1182
1237
|
* Check if the given command is a {@link LazyCommand}.
|
|
1183
1238
|
*
|
|
1184
1239
|
* @param cmd - A command to check
|
|
@@ -1356,6 +1411,14 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
|
|
|
1356
1411
|
/**
|
|
1357
1412
|
* create the command context
|
|
1358
1413
|
*/
|
|
1414
|
+
/**
|
|
1415
|
+
* NOTE(kazupon): a command that spreads `jsonArgs` and is asked for JSON prints its result as JSON, so
|
|
1416
|
+
* the human output of `ctx.log` is silenced, as it is with `usageSilent`. The hooks and the decorators
|
|
1417
|
+
* get the same context, so their `ctx.log` is silenced too. Only the resolved value of the `json`
|
|
1418
|
+
* argument counts here, not the raw tokens: a command that does not support `--json` keeps its output,
|
|
1419
|
+
* and the global options plugin reports the `--json` given to it.
|
|
1420
|
+
*/
|
|
1421
|
+
const silent = cliOptions.usageSilent || resolveJsonRequest(_args, values) === "declared";
|
|
1359
1422
|
const core = Object.assign(create(), {
|
|
1360
1423
|
name: getCommandName(command),
|
|
1361
1424
|
description: command.description,
|
|
@@ -1371,7 +1434,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
|
|
|
1371
1434
|
_: argv,
|
|
1372
1435
|
tokens,
|
|
1373
1436
|
toKebab: command.toKebab,
|
|
1374
|
-
log:
|
|
1437
|
+
log: silent ? NOOP : log,
|
|
1375
1438
|
validationError
|
|
1376
1439
|
});
|
|
1377
1440
|
/**
|
|
@@ -2530,7 +2593,7 @@ async function executeCommand(cmd, ctx, decorators) {
|
|
|
2530
2593
|
try {
|
|
2531
2594
|
if (ctx.env.onBeforeCommand) await ctx.env.onBeforeCommand(ctx);
|
|
2532
2595
|
const result = await decoratedRunner(ctx);
|
|
2533
|
-
if (ctx.env.onAfterCommand) await ctx.env.onAfterCommand(ctx, result);
|
|
2596
|
+
if (ctx.env.onAfterCommand) await ctx.env.onAfterCommand(ctx, typeof result === "string" ? result : void 0);
|
|
2534
2597
|
return typeof result === "string" ? result : void 0;
|
|
2535
2598
|
} catch (error) {
|
|
2536
2599
|
if (ctx.env.onErrorCommand) try {
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gunshi/bone",
|
|
3
3
|
"description": "gunshi minimum",
|
|
4
|
-
"version": "1.0.0-rc.
|
|
4
|
+
"version": "1.0.0-rc.6",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "kazuya kawaguchi",
|
|
7
7
|
"email": "kawakazu80@gmail.com"
|
|
@@ -51,19 +51,14 @@
|
|
|
51
51
|
}
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
|
-
"@gunshi/definition": "1.0.0-rc.
|
|
55
|
-
"@gunshi/plugin-global": "1.0.0-rc.
|
|
56
|
-
"@gunshi/plugin-renderer": "1.0.0-rc.
|
|
57
|
-
"
|
|
58
|
-
"gunshi": "1.0.0-rc.4",
|
|
59
|
-
"jsr": "^0.14.3",
|
|
60
|
-
"jsr-exports-lint": "^0.4.2",
|
|
54
|
+
"@gunshi/definition": "1.0.0-rc.6",
|
|
55
|
+
"@gunshi/plugin-global": "1.0.0-rc.6",
|
|
56
|
+
"@gunshi/plugin-renderer": "1.0.0-rc.6",
|
|
57
|
+
"gunshi": "1.0.0-rc.6",
|
|
61
58
|
"publint": "^0.3.20",
|
|
62
59
|
"tsdown": "0.22.14"
|
|
63
60
|
},
|
|
64
61
|
"scripts": {
|
|
65
|
-
"build": "tsdown"
|
|
66
|
-
"lint:jsr": "jsr publish --dry-run --allow-dirty",
|
|
67
|
-
"typecheck:deno": "deno check --import-map=../../importmap.json ./src"
|
|
62
|
+
"build": "tsdown"
|
|
68
63
|
}
|
|
69
64
|
}
|