@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 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 ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
2
- //#region src/parser.d.ts
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.0/node_modules/args-tokens/lib/resolver.d.ts
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 options that conflict with this option.
429
+ * Names of other arguments that conflict with this argument.
423
430
  *
424
- * When this option is used together with any of the conflicting options, the error is an
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 starts with the kind of the argument given as `name`:
435
- * `Positional argument 'file' conflicts with '--stdin'` or
436
- * `Optional argument '--stdin' conflicts with 'file'`.
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: "Optional argument '--summer' conflicts with '--autumn'"
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: "Optional argument '--summer-season' conflicts with '--autumn-season'"
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: Command<G> | LazyCommand<G>): void;
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 are not printed either, so `cli()` rejects with them, for the caller to
1142
- * report them (see {@linkcode CliOptions.renderValidationErrors}).
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 execution result
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 exit code is already `1`
1207
- * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
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 void or string (for CLI output)
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 CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
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.0/node_modules/args-tokens/lib/parser.js
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.0/node_modules/args-tokens/lib/utils.js
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.0/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
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` : `Optional argument ${createOptionDisplayName(option, schema)} is required`, option, "required", schema, {
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(`Optional argument ${createOptionDisplayName(option, schema)} should be '${expected}'`, option, "type", schema, {
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(`Optional argument ${displayName} requires a value${hint}`, option, "type", schema, {
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(`Optional argument ${displayName} does not take a value`, option, "type", schema, {
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(`Optional argument ${createOptionDisplayName(option, schema)} should be chosen from '${schema.type}' [${formatChoices(choices)}] values`, option, "type", schema, {
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(`Optional argument ${displayName} has the default ${typeof schema.default === "string" ? JSON.stringify(schema.default) : String(schema.default)}, which is not one of '${schema.type}' [${formatChoices(choices)}] values`, option, "type", schema, {
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
- return new ArgsValidationError(reason, {
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: createArgumentDisplayName(option, schema),
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 starts with "Positional argument"
1096
- * when `schema` is a positional argument, and with "Optional argument" otherwise.
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(`${schema.type === "positional" ? "Positional" : "Optional"} argument ${displayName} conflicts with ${conflictDisplayName}`, option, "conflict", schema, {
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.0/node_modules/args-tokens/lib/index.js
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: cliOptions.usageSilent ? NOOP : 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",
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.4",
55
- "@gunshi/plugin-global": "1.0.0-rc.4",
56
- "@gunshi/plugin-renderer": "1.0.0-rc.4",
57
- "deno": "^2.7.14",
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
  }