@gunshi/plugin 1.0.0-rc.5 → 1.0.0-rc.6

package/lib/index.d.ts

@@ -793,7 +793,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    * @param name - Command name
    * @param command - Command definition
    */
-  addCommand(name: string, command: Command<G> | LazyCommand<G>): void;
+  addCommand(name: string, command: SubCommandable): void;
   /**
    * Check if a command exists.
    *
@@ -834,7 +834,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the command runner
    */
-  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;
+  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;
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
@@ -1271,7 +1271,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
    *
    * Output that must still appear — machine-readable results for an agent, warnings for the
-   * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
+   * CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
+   * `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
+   *
+   * The validation errors, and a `CommandError` that the command throws, are not printed either, so
+   * `cli()` rejects with them, for the caller to report them.
    *
    * @default false
    * @see {@linkcode CliOptions.usageSilent}
@@ -1331,7 +1335,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    */
   onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
   /**
-   * Hook that runs after successful command execution
+   * Hook that runs after successful command execution. It receives the result of the command only
+   * when it is a string.
    *
    * @see {@linkcode CliOptions.onAfterCommand}
    * @since v0.27.0
@@ -1396,10 +1401,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
    *
    * Output that must still appear — machine-readable results for an agent, warnings for the
-   * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
+   * CLI author — should use `console.log` / `console.warn`, not `ctx.log`. A command that spreads
+   * `jsonArgs` and is given `--json` prints its result, and its errors, as JSON even with it.
    *
-   * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
-   * report them (see {@linkcode CliOptions.renderValidationErrors}).
+   * The validation errors, and a `CommandError` that the command throws, are not printed either, so
+   * `cli()` rejects with them, for the caller to report them (see
+   * {@linkcode CliOptions.renderValidationErrors}). The exit code is left alone.
    *
    * @default false
    */
@@ -1411,6 +1418,10 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * arguments or installed global options are reported as validation errors
    * before the command runner is executed.
    *
+   * `--json` is not reported, since gunshi knows what it means: given to a command that does not
+   * spread `jsonArgs`, the global options plugin reports `json_not_supported` for it instead, with or
+   * without `strict`. `--json=false` asks for no JSON, and is reported.
+   *
    * @default false
    */
   strict?: boolean;
@@ -1430,6 +1441,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
    * with the `AggregateError`. A renderer that returns an empty message, and
    * {@linkcode CliOptions.usageSilent}, also leave them to the caller.
+   *
+   * With `--json`, the plugin prints the validation errors as one line of JSON, and does not call
+   * the renderer. `null` and {@linkcode CliOptions.usageSilent} still leave them to the caller.
    */
   renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
   /**
@@ -1456,15 +1470,17 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Hook that runs after successful command execution
    *
    * @param ctx - The command context
-   * @param result - The command execution result
+   * @param result - The result of the command, when it is a string. The result of a command that
+   * prints JSON with `--json` is printed, not passed, so it is `undefined`
    * @since v0.27.0
    */
   onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
   /**
    * Hook that runs when a command throws an error, or when the arguments fail validation
    *
-   * For the validation errors that the global options plugin has printed, the exit code is already `1`
-   * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
+   * For the validation errors and a `CommandError` that the global options plugin has printed, the
+   * exit code is already set when the hook runs (`1` for the validation errors, and the `exitCode` of
+   * a `CommandError`), so the hook can set another one, and `cli()` resolves after it. Any other
    * error rejects `cli()` after the hook.
    *
    * @param ctx - The command context
@@ -1564,9 +1580,11 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    */
   toKebab?: boolean;
   /**
-   * Output a message.
+   * Output a message for people.
    *
-   * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
+   * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output. Nor is it when a
+   * command that spreads `jsonArgs` is asked for JSON with `--json`, so that stdout has the JSON only:
+   * the hooks and the plugins get the same function.
    *
    * @param message - an output message, see {@linkcode console.log}
    * @param optionalParams - an optional parameters, see {@linkcode console.log}
@@ -1810,14 +1828,49 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  *
  * @param ctx - A {@link CommandContext | command context}
- * @returns void or string (for CLI output)
+ * @returns The result of a command that spreads `jsonArgs`, an object keyed by a noun, which is printed
+ * as JSON with `--json`. For any other command, a string, which `cli()` returns, or nothing. See
+ * {@linkcode CommandRunnerResult}.
+ */
+type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => CommandRunnerResult<G>;
+/**
+ * The result of a command that supports `--json`: an object keyed by a noun, such as
+ * `{ project }` or `{ projects }`, so that fields can be added later. The global options plugin prints
+ * it with `JSON.stringify`, so convert what JSON cannot hold, such as a `Map` or a `BigInt`, yourself.
+ */
+type JsonResult = Record<string, unknown>;
+/**
+ * Whether the arguments have the `json` of `jsonArgs`.
+ *
+ * @typeParam A - The arguments of a command
+ */
+type HasJsonArgs<A> = [A] extends [{
+  readonly json: {
+    readonly [JSON_ARG]: true;
+  };
+}] ? true : false;
+/**
+ * What the runner of a command returns: its result for a command that spreads `jsonArgs`, otherwise a string or
+ * nothing.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams}
  */
-type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
+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>;
+/**
+ * Whether the arguments are `any`, as in `CommandRunner<any>`. Then a runner may return anything it could before.
+ *
+ * @internal
+ */
+type IsAnyArgs<A> = 0 extends 1 & A ? true : false;
 /**
  * Command decorator.
  *
  * A function that wraps a command runner to add or modify its behavior.
  *
+ * The decorated runner returns what the base runner returns, as it is: the result of a command that
+ * spreads `jsonArgs` must reach the global options plugin, which prints it as JSON with `--json`. A
+ * decorator prints with `ctx.log`, which is silenced then.
+ *
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  *
  * @param baseRunner - The base command runner to decorate
@@ -1825,7 +1878,7 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
  *
  * @since v0.27.0
  */
-type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
+type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void | JsonResult>;
 /**
  * Renderer decorator type.
  *
@@ -1859,6 +1912,13 @@ type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiP
 //#region ../gunshi/src/constants.d.ts
 declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
 declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
+/**
+ * The key of the mark on the `json` argument of `jsonArgs`. A string key, not a symbol: `gunshi` and the other
+ * packages bundle their own copies of the types, and each copy of a `unique symbol` is a different type.
+ *
+ * @internal
+ */
+declare const JSON_ARG = "~gunshi.json-arg";
 //#endregion
 //#region ../gunshi/src/context.d.ts
 /**
@@ -1883,7 +1943,7 @@ interface CommandContextParams<G extends GunshiParams | {
   args: Args;
 } | {
   extensions: ExtendContext;
-}, V extends ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>> {
+}, V extends ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> | SubCommandable = Command<G>, E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>> {
   /**
    * An arguments of target command
    */
@@ -1947,7 +2007,7 @@ interface CommandContextParams<G extends GunshiParams | {
  * @param param - A {@link CommandContextParams | parameters} to create a command context.
  * @returns A {@link CommandContext | command context}, which is readonly.
  */
-declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = {}>({ args, explicit, values, positionals, rest, argv, tokens, command, extensions, cliOptions, callMode, commandPath, omitted, validationError }: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
+declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> | SubCommandable = Command<G>, E extends Record<string, CommandContextExtension> = {}>({ args, explicit, values, positionals, rest, argv, tokens, command, extensions, cliOptions, callMode, commandPath, omitted, validationError }: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
 //#region ../gunshi/src/error.d.ts
 /**
@@ -1974,6 +2034,18 @@ declare const CommandResolutionErrorKeys: {
 };
 /** Command resolution error code. */
 type CommandResolutionErrorCode = (typeof CommandResolutionErrorKeys)[keyof typeof CommandResolutionErrorKeys];
+/**
+ * The resource keys of the errors of the JSON output, which are the codes of {@link JsonOutputError}.
+ */
+declare const JsonOutputErrorKeys: {
+  readonly notSupported: "err:json:not-supported";
+  readonly invalidResult: "err:json:invalid-result";
+  readonly unserializableResult: "err:json:unserializable-result";
+};
+/**
+ * The code of a {@link JsonOutputError}.
+ */
+type JsonOutputErrorCode = (typeof JsonOutputErrorKeys)[keyof typeof JsonOutputErrorKeys];
 /**
  * Options for {@link CommandNotFoundError}.
  */
@@ -2016,6 +2088,31 @@ type CommandResolutionErrorOptions = {
   /** Underlying cause. */
   cause?: unknown;
 };
+/**
+ * Options for {@link CommandError}. All of them are optional.
+ */
+type CommandErrorOptions = {
+  /**
+   * The name of the failure, for programs to read, such as `not_found`. snake_case is recommended.
+   *
+   * It is not printed to the user. With `--json`, it is the `reason` of the JSON error, as it is.
+   */
+  code?: string;
+  /**
+   * The exit code of the process, an integer from 1 to 255. Defaults to 1, and any other value is
+   * replaced with 1, since the command has failed.
+   */
+  exitCode?: number;
+  /**
+   * The error that caused the failure.
+   *
+   * Its message is printed as is, on a `Caused by:` line after the message of the
+   * {@link CommandError}, and so is the message of its own cause. With `--json`, the messages are in
+   * `data.causes` of the JSON error. Do not pass an error whose message may contain a secret, such as
+   * a token in a URL: write the message of the {@link CommandError} yourself instead.
+   */
+  cause?: unknown;
+};
 /**
  * Error raised when a command cannot be resolved.
  *
@@ -2057,6 +2154,62 @@ declare class CommandResolutionError extends Error {
    */
   constructor(message: string, options?: CommandResolutionErrorOptions);
 }
+/**
+ * Error for a failure that a command expects, such as a project that does not exist.
+ *
+ * When a command throws it from `run`, or a plugin throws it from a command decorator, the global
+ * options plugin prints its message to stderr, followed by a `Caused by:` line for each cause,
+ * without a stack trace. It sets the exit code of the process to {@link CommandError.exitCode},
+ * and `cli()` resolves with `undefined`. `onErrorCommand` is still called with the error, after the
+ * exit code is set, so the hook can change it.
+ *
+ * It is not printed, and `cli()` rejects with it, in these cases:
+ *
+ * - `usageSilent` is set, for the caller to report it
+ * - it is thrown from a hook, while a plugin extends the command context, or while a lazy command
+ *   loads, outside the command decorators
+ * - the CLI runs without the global options plugin, as `gunshi/bone` does
+ *
+ * Any other error thrown from a command is not printed either, and `cli()` rejects with it.
+ *
+ * Each package of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/definition`) bundles its own copy of
+ * this class, so `instanceof` does not match an error from another copy. Use
+ * {@link isCommandError} to tell it.
+ *
+ * @example
+ * ```js
+ * import { CommandError, define } from 'gunshi'
+ *
+ * export default define({
+ *   name: 'show',
+ *   args: { project: { type: 'positional', description: 'Project name' } },
+ *   run: async ctx => {
+ *     const project = await findProject(ctx.values.project)
+ *     if (!project) {
+ *       throw new CommandError(`Project ${ctx.values.project} not found`, { code: 'not_found' })
+ *     }
+ *     ctx.log(project.description)
+ *   }
+ * })
+ * ```
+ */
+declare class CommandError extends Error {
+  /**
+   * The name of the failure, for programs to read. See {@link CommandErrorOptions.code}.
+   */
+  readonly code?: string;
+  /**
+   * The exit code of the process, an integer from 1 to 255.
+   */
+  readonly exitCode: number;
+  /**
+   * Create an error for a failure that a command expects.
+   *
+   * @param message - The message printed to the user. It may have more than one line.
+   * @param options - The code, the exit code and the cause of the failure
+   */
+  constructor(message: string, options?: CommandErrorOptions);
+}
 /**
  * Check whether an error is a {@link CommandNotFoundError}.
  *
@@ -2076,6 +2229,76 @@ declare function isCommandNotFoundError(error: unknown): error is CommandNotFoun
  * @returns `true` when the error has the command-resolution brand and shape
  */
 declare function isCommandResolutionError(error: unknown): error is CommandResolutionError;
+/**
+ * Check whether an error is a {@link CommandError}.
+ *
+ * An error from another copy of gunshi is recognized through the `Symbol.for('gunshi.CommandError')`
+ * brand. It is not recognized by `error.name`, so an error of the app that is also named
+ * `CommandError` is not taken for one.
+ *
+ * @param error - An unknown error
+ * @returns `true` if the error is a {@link CommandError}
+ */
+declare function isCommandError(error: unknown): error is CommandError;
+/**
+ * Options for {@link JsonOutputError}.
+ */
+type JsonOutputErrorOptions = {
+  /**
+   * The code of the error, which is also the resource key of its message.
+   */
+  code: JsonOutputErrorCode;
+  /**
+   * Values used when localizing the message.
+   */
+  values?: Record<string, unknown>;
+  /**
+   * Underlying cause, such as the error of `JSON.stringify`.
+   */
+  cause?: unknown;
+};
+/**
+ * Error raised by the global options plugin for the JSON output, when a command is given `--json`.
+ *
+ * - `err:json:not-supported`: the command does not spread `jsonArgs`. It is raised before the command
+ *   runs, and thrown in an `AggregateError`, as the argument errors are.
+ * - `err:json:invalid-result`: the command finished, but did not return an object to output as JSON
+ * - `err:json:unserializable-result`: the command finished, but its result cannot be converted to
+ *   JSON, such as an object with a `BigInt`
+ *
+ * The plugin prints it as one line of JSON to stderr, and `cli()` resolves with `undefined`. For
+ * `err:json:not-supported`, with `renderValidationErrors: null` or `usageSilent`, nothing is printed
+ * and `cli()` rejects with the `AggregateError`, as it does for the argument errors.
+ *
+ * Use {@link isJsonOutputError} to tell it, since each package bundles its own copy of this class.
+ */
+declare class JsonOutputError extends Error {
+  /**
+   * The code of the error, which is also the resource key of its message.
+   */
+  readonly code: JsonOutputErrorCode;
+  /**
+   * Values used when localizing the message.
+   */
+  readonly values: Record<string, unknown>;
+  /**
+   * Create an error of the JSON output.
+   *
+   * @param message - Fallback error message
+   * @param options - The code of the error, and the values of its message
+   */
+  constructor(message: string, options: JsonOutputErrorOptions);
+}
+/**
+ * Check whether an error is a {@link JsonOutputError}.
+ *
+ * An error from another copy of gunshi is recognized through the
+ * `Symbol.for('gunshi.JsonOutputError')` brand, not by `error.name`.
+ *
+ * @param error - An unknown error
+ * @returns `true` if the error is a {@link JsonOutputError}
+ */
+declare function isJsonOutputError(error: unknown): error is JsonOutputError;
 /**
  * Check whether an error is an {@link ArgsValidationError}.
  *
@@ -2103,4 +2326,4 @@ declare function isArgsValidationError(error: unknown): error is ArgsValidationE
  */
 declare function hasPriorityValidationError(error: AggregateError | undefined): boolean;
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, type ArgsValidationErrorCode, ArgsValidationErrorKeys, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, CommandNotFoundError, type CommandNotFoundErrorCode, CommandNotFoundErrorKeys, type CommandNotFoundErrorOptions, CommandResolutionError, type CommandResolutionErrorCode, CommandResolutionErrorKeys, type CommandResolutionErrorOptions, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, type ArgsValidationErrorCode, ArgsValidationErrorKeys, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, CommandError, type CommandErrorOptions, type CommandExamplesFetcher, CommandNotFoundError, type CommandNotFoundErrorCode, CommandNotFoundErrorKeys, type CommandNotFoundErrorOptions, CommandResolutionError, type CommandResolutionErrorCode, CommandResolutionErrorKeys, type CommandResolutionErrorOptions, type CommandRunner, type CommandRunnerResult, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, JsonOutputError, type JsonOutputErrorCode, JsonOutputErrorKeys, type JsonOutputErrorOptions, type JsonResult, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type SubCommandable, type ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandError, isCommandNotFoundError, isCommandResolutionError, isJsonOutputError, plugin };

package/lib/index.js

@@ -33,6 +33,51 @@ const CLI_OPTIONS_DEFAULT = {
 * @license MIT
 */
 /**
+* Check whether an argument schema is the `json` argument of `jsonArgs`, by its mark.
+*
+* @param schema - An argument schema
+* @returns `true` if the schema has the mark of `jsonArgs`
+*/
+function isJsonArg(schema) {
+	return typeof schema === "object" && schema !== null && schema["~gunshi.json-arg"] === true;
+}
+/**
+* Resolve whether `--json` asks a command for JSON.
+*
+* A command that spreads `jsonArgs` is asked for JSON when the resolved value of its `json` is `true`:
+* with `--json`, or with a short name that the command gives it, but not with `--json=false`, nor with
+* `--json` after `--`. The raw tokens are read only when they are given, and only when there is no
+* value to read: when the command has no `json` argument, and when the core could not resolve the
+* command and left the values empty. A `json` argument without the mark belongs to the command, and
+* `--json` is never taken for a request then.
+*
+* @param args - The arguments of the command, the global options included
+* @param values - The resolved values of the arguments
+* @param tokens - The raw tokens of the arguments, to find a `--json` that no argument declares
+* @returns How the command is asked for JSON, or `undefined` when it is not
+*/
+function resolveJsonRequest(args, values, tokens) {
+	const schema = Object.hasOwn(args, "json") ? args.json : void 0;
+	if (schema === void 0) return tokens !== void 0 && hasJsonOption(tokens) ? "undeclared" : void 0;
+	if (!isJsonArg(schema)) return;
+	if (values.json !== void 0) return values.json === true ? "declared" : void 0;
+	return tokens !== void 0 && hasJsonOption(tokens) ? "declared" : void 0;
+}
+/**
+* Check whether the raw tokens have a `--json` that asks for JSON: `--json` or `--json=true`, before
+* `--`. Without a declaration, a short name of `--json` is not known.
+*
+* @param tokens - The raw tokens of the arguments
+* @returns `true` if a `--json` asks for JSON
+*/
+function hasJsonOption(tokens) {
+	for (const token of tokens) {
+		if (token.kind === "option-terminator") return false;
+		if (token.kind === "option" && token.rawName === "--json" && (token.value === void 0 || token.value === "true")) return true;
+	}
+	return false;
+}
+/**
 * Check if the given command is a {@link LazyCommand}.
 *
 * @param cmd - A command to check
@@ -124,6 +169,14 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 	/**
 	* create the command context
 	*/
+	/**
+	* NOTE(kazupon): a command that spreads `jsonArgs` and is asked for JSON prints its result as JSON, so
+	* the human output of `ctx.log` is silenced, as it is with `usageSilent`. The hooks and the decorators
+	* get the same context, so their `ctx.log` is silenced too. Only the resolved value of the `json`
+	* argument counts here, not the raw tokens: a command that does not support `--json` keeps its output,
+	* and the global options plugin reports the `--json` given to it.
+	*/
+	const silent = cliOptions.usageSilent || resolveJsonRequest(_args, values) === "declared";
 	const core = Object.assign(create(), {
 		name: getCommandName(command),
 		description: command.description,
@@ -139,7 +192,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 		_: argv,
 		tokens,
 		toKebab: command.toKebab,
-		log: cliOptions.usageSilent ? NOOP : log,
+		log: silent ? NOOP : log,
 		validationError
 	});
 	/**
@@ -317,6 +370,14 @@ const CommandResolutionErrorKeys = {
 	lazySchemaMismatch: "err:cmd:lazy-schema-mismatch"
 };
 /**
+* The resource keys of the errors of the JSON output, which are the codes of {@link JsonOutputError}.
+*/
+const JsonOutputErrorKeys = {
+	notSupported: "err:json:not-supported",
+	invalidResult: "err:json:invalid-result",
+	unserializableResult: "err:json:unserializable-result"
+};
+/**
 * Brand that marks {@link CommandNotFoundError} instances.
 *
 * The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
@@ -326,6 +387,8 @@ const CommandResolutionErrorKeys = {
 */
 const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
 const COMMAND_RESOLUTION_ERROR_BRAND = Symbol.for("gunshi.CommandResolutionError");
+const COMMAND_ERROR_BRAND = Symbol.for("gunshi.CommandError");
+const JSON_OUTPUT_ERROR_BRAND = Symbol.for("gunshi.JsonOutputError");
 /**
 * Error raised when a command cannot be resolved.
 *
@@ -395,6 +458,73 @@ var CommandResolutionError = class extends Error {
 	}
 };
 /**
+* Error for a failure that a command expects, such as a project that does not exist.
+*
+* When a command throws it from `run`, or a plugin throws it from a command decorator, the global
+* options plugin prints its message to stderr, followed by a `Caused by:` line for each cause,
+* without a stack trace. It sets the exit code of the process to {@link CommandError.exitCode},
+* and `cli()` resolves with `undefined`. `onErrorCommand` is still called with the error, after the
+* exit code is set, so the hook can change it.
+*
+* It is not printed, and `cli()` rejects with it, in these cases:
+*
+* - `usageSilent` is set, for the caller to report it
+* - it is thrown from a hook, while a plugin extends the command context, or while a lazy command
+*   loads, outside the command decorators
+* - the CLI runs without the global options plugin, as `gunshi/bone` does
+*
+* Any other error thrown from a command is not printed either, and `cli()` rejects with it.
+*
+* Each package of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/definition`) bundles its own copy of
+* this class, so `instanceof` does not match an error from another copy. Use
+* {@link isCommandError} to tell it.
+*
+* @example
+* ```js
+* import { CommandError, define } from 'gunshi'
+*
+* export default define({
+*   name: 'show',
+*   args: { project: { type: 'positional', description: 'Project name' } },
+*   run: async ctx => {
+*     const project = await findProject(ctx.values.project)
+*     if (!project) {
+*       throw new CommandError(`Project ${ctx.values.project} not found`, { code: 'not_found' })
+*     }
+*     ctx.log(project.description)
+*   }
+* })
+* ```
+*/
+var CommandError = class extends Error {
+	/**
+	* The name of the failure, for programs to read. See {@link CommandErrorOptions.code}.
+	*/
+	code;
+	/**
+	* The exit code of the process, an integer from 1 to 255.
+	*/
+	exitCode;
+	/**
+	* Create an error for a failure that a command expects.
+	*
+	* @param message - The message printed to the user. It may have more than one line.
+	* @param options - The code, the exit code and the cause of the failure
+	*/
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "CommandError";
+		this.code = options.code;
+		this.exitCode = isFailureExitCode(options.exitCode) ? options.exitCode : 1;
+		Object.defineProperty(this, COMMAND_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+	}
+};
+/**
 * Check whether an error is a {@link CommandNotFoundError}.
 *
 * `instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
@@ -423,6 +553,78 @@ function isCommandResolutionError(error) {
 	return Object.hasOwn(error, COMMAND_RESOLUTION_ERROR_BRAND) && error[COMMAND_RESOLUTION_ERROR_BRAND] === true;
 }
 /**
+* Check whether an error is a {@link CommandError}.
+*
+* An error from another copy of gunshi is recognized through the `Symbol.for('gunshi.CommandError')`
+* brand. It is not recognized by `error.name`, so an error of the app that is also named
+* `CommandError` is not taken for one.
+*
+* @param error - An unknown error
+* @returns `true` if the error is a {@link CommandError}
+*/
+function isCommandError(error) {
+	if (error instanceof CommandError) return true;
+	if (!isRecord(error) || !Object.hasOwn(error, COMMAND_ERROR_BRAND) || error[COMMAND_ERROR_BRAND] !== true) return false;
+	return hasCommandErrorShape(error);
+}
+/**
+* Error raised by the global options plugin for the JSON output, when a command is given `--json`.
+*
+* - `err:json:not-supported`: the command does not spread `jsonArgs`. It is raised before the command
+*   runs, and thrown in an `AggregateError`, as the argument errors are.
+* - `err:json:invalid-result`: the command finished, but did not return an object to output as JSON
+* - `err:json:unserializable-result`: the command finished, but its result cannot be converted to
+*   JSON, such as an object with a `BigInt`
+*
+* The plugin prints it as one line of JSON to stderr, and `cli()` resolves with `undefined`. For
+* `err:json:not-supported`, with `renderValidationErrors: null` or `usageSilent`, nothing is printed
+* and `cli()` rejects with the `AggregateError`, as it does for the argument errors.
+*
+* Use {@link isJsonOutputError} to tell it, since each package bundles its own copy of this class.
+*/
+var JsonOutputError = class extends Error {
+	/**
+	* The code of the error, which is also the resource key of its message.
+	*/
+	code;
+	/**
+	* Values used when localizing the message.
+	*/
+	values;
+	/**
+	* Create an error of the JSON output.
+	*
+	* @param message - Fallback error message
+	* @param options - The code of the error, and the values of its message
+	*/
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "JsonOutputError";
+		this.code = options.code;
+		this.values = options.values || {};
+		Object.defineProperty(this, JSON_OUTPUT_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+	}
+};
+/**
+* Check whether an error is a {@link JsonOutputError}.
+*
+* An error from another copy of gunshi is recognized through the
+* `Symbol.for('gunshi.JsonOutputError')` brand, not by `error.name`.
+*
+* @param error - An unknown error
+* @returns `true` if the error is a {@link JsonOutputError}
+*/
+function isJsonOutputError(error) {
+	if (error instanceof JsonOutputError) return true;
+	if (!isRecord(error) || !Object.hasOwn(error, JSON_OUTPUT_ERROR_BRAND) || error[JSON_OUTPUT_ERROR_BRAND] !== true) return false;
+	return hasJsonOutputErrorShape(error);
+}
+/**
 * Check whether an error is an {@link ArgsValidationError}.
 *
 * Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
@@ -472,6 +674,21 @@ function hasCommandResolutionErrorShape(error) {
 function hasArgsValidationErrorShape(error) {
 	return hasOptionalStringCode(error) && isRecord(error.values);
 }
+function hasCommandErrorShape(error) {
+	return hasOptionalStringCode(error) && typeof error.message === "string" && isFailureExitCode(error.exitCode);
+}
+function hasJsonOutputErrorShape(error) {
+	return Object.values(JsonOutputErrorKeys).includes(error.code) && isRecord(error.values);
+}
+/**
+* Check whether a value is an exit code of a failure: an integer from 1 to 255.
+*
+* @param value - The value to check
+* @returns `true` if the value is an exit code of a failure
+*/
+function isFailureExitCode(value) {
+	return Number.isInteger(value) && value >= 1 && value <= 255;
+}
 /**
 * Check whether validation errors should be handled before version, help, or command execution.
 *
@@ -546,4 +763,4 @@ function plugin(options = {}) {
 * @license MIT
 */
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandNotFoundError, CommandNotFoundErrorKeys, CommandResolutionError, CommandResolutionErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };
+export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandError, CommandNotFoundError, CommandNotFoundErrorKeys, CommandResolutionError, CommandResolutionErrorKeys, JsonOutputError, JsonOutputErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandError, isCommandNotFoundError, isCommandResolutionError, isJsonOutputError, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,7 +51,7 @@
     }
   },
   "devDependencies": {
-    "gunshi": "1.0.0-rc.5",
+    "gunshi": "1.0.0-rc.6",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"
   },