@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 +78 -16
- package/lib/index.js +55 -2
- package/package.json +5 -5
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:
|
|
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
|
|
1139
|
-
* 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.
|
|
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
|
|
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
|
|
1204
|
-
* 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
|
|
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
|
|
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
|
|
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:
|
|
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.
|
|
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.
|
|
55
|
-
"@gunshi/plugin-global": "1.0.0-rc.
|
|
56
|
-
"@gunshi/plugin-renderer": "1.0.0-rc.
|
|
57
|
-
"gunshi": "1.0.0-rc.
|
|
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
|
},
|