@gunshi/bone 1.0.0-rc.5 → 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/lib/index.d.ts CHANGED
@@ -1,3 +1,12 @@
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
1
10
  //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser-DvPxBZG9.d.ts
2
11
  /**
3
12
  * Entry point of argument parser.
@@ -730,7 +739,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
730
739
  * @param name - Command name
731
740
  * @param command - Command definition
732
741
  */
733
- addCommand(name: string, command: Command<G> | LazyCommand<G>): void;
742
+ addCommand(name: string, command: SubCommandable): void;
734
743
  /**
735
744
  * Check if a command exists.
736
745
  *
@@ -771,7 +780,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
771
780
  *
772
781
  * @param decorator - A decorator function that wraps the command runner
773
782
  */
774
- decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
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;
775
784
  }
776
785
  //#endregion
777
786
  //#region ../gunshi/src/plugin/core.d.ts
@@ -1008,7 +1017,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
1008
1017
  * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
1009
1018
  *
1010
1019
  * Output that must still appear — machine-readable results for an agent, warnings for the
1011
- * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
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.
1012
1025
  *
1013
1026
  * @default false
1014
1027
  * @see {@linkcode CliOptions.usageSilent}
@@ -1068,7 +1081,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
1068
1081
  */
1069
1082
  onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
1070
1083
  /**
1071
- * 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.
1072
1086
  *
1073
1087
  * @see {@linkcode CliOptions.onAfterCommand}
1074
1088
  * @since v0.27.0
@@ -1133,10 +1147,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1133
1147
  * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
1134
1148
  *
1135
1149
  * Output that must still appear — machine-readable results for an agent, warnings for the
1136
- * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
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.
1137
1152
  *
1138
- * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
1139
- * 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.
1140
1156
  *
1141
1157
  * @default false
1142
1158
  */
@@ -1148,6 +1164,10 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1148
1164
  * arguments or installed global options are reported as validation errors
1149
1165
  * before the command runner is executed.
1150
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
+ *
1151
1171
  * @default false
1152
1172
  */
1153
1173
  strict?: boolean;
@@ -1167,6 +1187,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1167
1187
  * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
1168
1188
  * with the `AggregateError`. A renderer that returns an empty message, and
1169
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.
1170
1193
  */
1171
1194
  renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
1172
1195
  /**
@@ -1193,15 +1216,17 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
1193
1216
  * Hook that runs after successful command execution
1194
1217
  *
1195
1218
  * @param ctx - The command context
1196
- * @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`
1197
1221
  * @since v0.27.0
1198
1222
  */
1199
1223
  onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
1200
1224
  /**
1201
1225
  * Hook that runs when a command throws an error, or when the arguments fail validation
1202
1226
  *
1203
- * For the validation errors that the global options plugin has printed, the exit code is already `1`
1204
- * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
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
1205
1230
  * error rejects `cli()` after the hook.
1206
1231
  *
1207
1232
  * @param ctx - The command context
@@ -1301,9 +1326,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
1301
1326
  */
1302
1327
  toKebab?: boolean;
1303
1328
  /**
1304
- * Output a message.
1329
+ * Output a message for people.
1305
1330
  *
1306
- * 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.
1307
1334
  *
1308
1335
  * @param message - an output message, see {@linkcode console.log}
1309
1336
  * @param optionalParams - an optional parameters, see {@linkcode console.log}
@@ -1553,9 +1580,40 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
1553
1580
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
1554
1581
  *
1555
1582
  * @param ctx - A {@link CommandContext | command context}
1556
- * @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.
1557
1592
  */
1558
- 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;
1559
1617
  /**
1560
1618
  * Command loader.
1561
1619
  *
@@ -1572,6 +1630,10 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
1572
1630
  *
1573
1631
  * A function that wraps a command runner to add or modify its behavior.
1574
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
+ *
1575
1637
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
1576
1638
  *
1577
1639
  * @param baseRunner - The base command runner to decorate
@@ -1579,7 +1641,7 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
1579
1641
  *
1580
1642
  * @since v0.27.0
1581
1643
  */
1582
- 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>;
1583
1645
  /**
1584
1646
  * Renderer decorator type.
1585
1647
  *
@@ -1654,4 +1716,4 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
1654
1716
  */
1655
1717
  declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
1656
1718
  //#endregion
1657
- export { type ArgSchema, type ArgToken, type ArgValues, type Args, type Awaitable, type CliOptions, type Command, type CommandCallMode, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandDecorator, type CommandEnvironment, type CommandExamplesFetcher, type CommandLoader, type CommandRunner, type Commandable, type DefaultGunshiParams, type ExtendContext, type ExtractArgExplicitlyProvided, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type Prettify, type RendererDecorator, type RenderingOptions, type SubCommandable, type ValidationErrorsDecorator, cli };
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
@@ -1189,6 +1189,51 @@ const CLI_OPTIONS_DEFAULT = {
1189
1189
  * @license MIT
1190
1190
  */
1191
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
+ /**
1192
1237
  * Check if the given command is a {@link LazyCommand}.
1193
1238
  *
1194
1239
  * @param cmd - A command to check
@@ -1366,6 +1411,14 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
1366
1411
  /**
1367
1412
  * create the command context
1368
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";
1369
1422
  const core = Object.assign(create(), {
1370
1423
  name: getCommandName(command),
1371
1424
  description: command.description,
@@ -1381,7 +1434,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
1381
1434
  _: argv,
1382
1435
  tokens,
1383
1436
  toKebab: command.toKebab,
1384
- log: cliOptions.usageSilent ? NOOP : log,
1437
+ log: silent ? NOOP : log,
1385
1438
  validationError
1386
1439
  });
1387
1440
  /**
@@ -2540,7 +2593,7 @@ async function executeCommand(cmd, ctx, decorators) {
2540
2593
  try {
2541
2594
  if (ctx.env.onBeforeCommand) await ctx.env.onBeforeCommand(ctx);
2542
2595
  const result = await decoratedRunner(ctx);
2543
- 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);
2544
2597
  return typeof result === "string" ? result : void 0;
2545
2598
  } catch (error) {
2546
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.5",
4
+ "version": "1.0.0-rc.6",
5
5
  "author": {
6
6
  "name": "kazuya kawaguchi",
7
7
  "email": "kawakazu80@gmail.com"
@@ -51,10 +51,10 @@
51
51
  }
52
52
  },
53
53
  "devDependencies": {
54
- "@gunshi/definition": "1.0.0-rc.5",
55
- "@gunshi/plugin-global": "1.0.0-rc.5",
56
- "@gunshi/plugin-renderer": "1.0.0-rc.5",
57
- "gunshi": "1.0.0-rc.5",
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",
58
58
  "publint": "^0.3.20",
59
59
  "tsdown": "0.22.14"
60
60
  },