@gunshi/definition 1.0.0-rc.4 → 1.0.0-rc.6

package/README.md

@@ -2,7 +2,6 @@
 
 [![Version][npm-version-src]][npm-version-href]
 [![InstallSize][install-size-src]][install-size-src]
-[![JSR][jsr-src]][jsr-href]
 
 > utilities for gunshi command definition
 
@@ -10,6 +9,9 @@ This package exports the bellow APIs and types.
 
 - `define`: A function to define a command.
 - `lazy`: A function to lazily load a command.
+- `CommandError` and `isCommandError`: An error for the failures that a command expects, printed without a stack trace, and its guard.
+- `jsonArgs`: The argument that a command spreads into its `args` to support `--json`.
+- `SubCommandable`: The type of a command to collect into the sub-commands, with or without `jsonArgs`.
 - Some basic type definitions, such as `Command`, `LazyCommand`, etc.
 
 <!-- eslint-disable markdown/no-missing-label-refs -->
@@ -32,9 +34,6 @@ pnpm add @gunshi/definition
 ## yarn
 yarn add @gunshi/definition
 
-## deno
-deno add jsr:@gunshi/definition
-
 ## bun
 bun add @gunshi/definition
 ```
@@ -84,6 +83,4 @@ About details, See the below official docs sections:
 
 [npm-version-src]: https://img.shields.io/npm/v/@gunshi/definition?style=flat
 [npm-version-href]: https://npmjs.com/package/@gunshi/definition@alpha
-[jsr-src]: https://jsr.io/badges/@gunshi/definition
-[jsr-href]: https://jsr.io/@gunshi/definition
 [install-size-src]: https://pkg-size.dev/badge/install/23122

package/lib/index.d.ts

@@ -1,5 +1,13 @@
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
-//#region src/parser.d.ts
+//#region ../gunshi/src/constants.d.ts
+/**
+ * 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 ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/parser-DvPxBZG9.d.ts
 /**
  * Entry point of argument parser.
  *
@@ -56,8 +64,7 @@ interface ArgToken {
   inlineValue?: boolean | undefined;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver.d.ts
-//#region src/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
  *
@@ -419,9 +426,9 @@ interface ArgSchema {
    */
   toKebab?: true;
   /**
-   * Names of other options that conflict with this option.
+   * Names of other arguments that conflict with this argument.
    *
-   * When this option is used together with any of the conflicting options, the error is an
+   * When this argument is used together with any of the conflicting arguments, the error is an
    * `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
    * ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
    * the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
@@ -431,9 +438,8 @@ interface ArgSchema {
    *
    * A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
    * it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as
-   * in its other errors. The message starts with the kind of the argument given as `name`:
-   * `Positional argument 'file' conflicts with '--stdin'` or
-   * `Optional argument '--stdin' conflicts with 'file'`.
+   * in its other errors. The message names the argument given as `name` first:
+   * `'file' conflicts with '--stdin'` or `'--stdin' conflicts with 'file'`.
    *
    * Conflicts only need to be defined on one side - if option A defines a conflict
    * with option B, the conflict is automatically detected when both are used,
@@ -472,7 +478,7 @@ interface ArgSchema {
    *   }
    * }
    * // Usage: --summer --autumn reports an error
-   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * // Error: "'--summer' conflicts with '--autumn'"
    * ```
    *
    * @example
@@ -512,7 +518,7 @@ interface ArgSchema {
    *     toKebab: true  // Accessible as --autumn-season
    *   }
    * }
-   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * // Error: "'--summer-season' conflicts with '--autumn-season'"
    * ```
    */
   conflicts?: string | string[];
@@ -733,7 +739,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.
    *
@@ -774,7 +780,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
@@ -1011,7 +1017,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}
@@ -1071,7 +1081,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
@@ -1136,10 +1147,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
    */
@@ -1151,6 +1164,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;
@@ -1170,6 +1187,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;
   /**
@@ -1196,15 +1216,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
@@ -1304,9 +1326,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}
@@ -1550,9 +1574,40 @@ 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 loader.
  *
@@ -1588,7 +1643,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
    */
@@ -1652,7 +1707,144 @@ 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
+/**
+ * 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 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 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;
+//#endregion
+//#region ../gunshi/src/json.d.ts
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * The argument that a command spreads into its `args` to support `--json`.
+ *
+ * A command that spreads it returns its result from `run`, as an object keyed by a noun, and prints
+ * the output for people with `ctx.log`. With `--json`, the global options plugin silences `ctx.log`,
+ * prints the result as one JSON document to stdout, and prints a failure as one line of JSON to
+ * stderr. `--json` given to a command that does not spread it stops the command before it runs, with
+ * `json_not_supported`.
+ *
+ * The `json` argument has a mark, by which gunshi tells it from a `json` argument of the command's
+ * own, which gunshi does not touch. To give it a short name, spread it:
+ * `{ ...jsonArgs.json, short: 'j' }`. A lazy command spreads it into its definition too.
+ *
+ * @example
+ * ```js
+ * import { define, jsonArgs } from 'gunshi'
+ *
+ * export default define({
+ *   name: 'list',
+ *   args: { ...jsonArgs },
+ *   run: async ctx => {
+ *     const projects = await fetchProjects()
+ *     for (const project of projects) {
+ *       ctx.log(project.name)
+ *     }
+ *     return { projects }
+ *   }
+ * })
+ * ```
+ */
+declare const jsonArgs: {
+  readonly json: {
+    readonly type: "boolean";
+    readonly description: "Output the result as JSON";
+    readonly "~gunshi.json-arg": true;
+  };
+};
 //#endregion
 //#region ../gunshi/src/definition.d.ts
 /**
@@ -1751,6 +1943,15 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
  * @since v0.27.0
  */
 declare function defineWithTypes<G extends GunshiParamsConstraint>(): DefineWithTypesReturn<ExtractExtensions<G>, ExtractArgs<G>>;
+/**
+ * A definition that does not spread `jsonArgs`. A definition that does is checked by the overload that ties the
+ * runner to its arguments.
+ *
+ * @internal
+ */
+type WithoutJsonArgs<D> = D extends {
+  args: infer A;
+} ? HasJsonArgs<A> extends true ? never : unknown : unknown;
 /**
  * Define a {@link LazyCommand | lazy command}.
  *
@@ -1830,7 +2031,7 @@ declare function lazy<D extends {
  *   including when the lazy command is used as the CLI entry command.
  * @returns A {@link LazyCommand | lazy command} that can be executed later
  */
-declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = Partial<Command<G>>>(loader: CommandLoader<G>, definition?: D): LazyCommand<G, D>;
+declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = Partial<Command<G>>>(loader: CommandLoader<G>, definition?: D & WithoutJsonArgs<D>): LazyCommand<G, D>;
 /**
  * Return type for lazyWithTypes
  *
@@ -1875,4 +2076,4 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
  */
 declare function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<NormalizeToGunshiParams<G>>;
 //#endregion
-export { type ArgSchema, type ArgValues, type Args, type Command, type CommandContextParams, type CommandLoader, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type GunshiParams, type LazyCommand, createCommandContext, define, defineWithTypes, lazy, lazyWithTypes };
+export { type ArgSchema, type ArgValues, type Args, type Command, type CommandContextParams, CommandError, type CommandErrorOptions, type CommandLoader, type CommandRunner, type CommandRunnerResult, type DefaultGunshiParams, type ExtendContext, type GunshiParams, type JsonResult, type LazyCommand, type SubCommandable, createCommandContext, define, defineWithTypes, isCommandError, jsonArgs, lazy, lazyWithTypes };

package/lib/index.js

@@ -26,6 +26,13 @@ const CLI_OPTIONS_DEFAULT = {
 	plugins: void 0,
 	fallbackToEntry: false
 };
+/**
+* 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
+*/
+const JSON_ARG = "~gunshi.json-arg";
 //#endregion
 //#region ../gunshi/src/utils.ts
 /**
@@ -33,6 +40,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 +176,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 +199,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 		_: argv,
 		tokens,
 		toKebab: command.toKebab,
-		log: cliOptions.usageSilent ? NOOP : log,
+		log: silent ? NOOP : log,
 		validationError
 	});
 	/**
@@ -165,6 +225,192 @@ function getCommandName(cmd) {
 	else if (typeof cmd === "object") return cmd.name || "(anonymous)";
 	else return ANONYMOUS_COMMAND_NAME;
 }
+/**
+* forked from `nodejs/node` (`pkgjs/parseargs`)
+* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+* code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+*
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+"-".codePointAt(0);
+"=".codePointAt(0);
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/resolver-Cx5Pw6-S.js
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/index.js
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region ../gunshi/src/error.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const COMMAND_ERROR_BRAND = Symbol.for("gunshi.CommandError");
+/**
+* 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 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);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Check whether `code` is an own or inherited property that is a string or `undefined`.
+*
+* Constructors always assign `code`, even when the option is omitted.
+*
+* @param error - An error from another copy
+* @returns `true` if `code` has the expected type
+*/
+function hasOptionalStringCode(error) {
+	return "code" in error && (error.code === void 0 || typeof error.code === "string");
+}
+function hasCommandErrorShape(error) {
+	return hasOptionalStringCode(error) && typeof error.message === "string" && isFailureExitCode(error.exitCode);
+}
+/**
+* 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;
+}
+//#endregion
+//#region ../gunshi/src/json.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* The argument that a command spreads into its `args` to support `--json`.
+*
+* A command that spreads it returns its result from `run`, as an object keyed by a noun, and prints
+* the output for people with `ctx.log`. With `--json`, the global options plugin silences `ctx.log`,
+* prints the result as one JSON document to stdout, and prints a failure as one line of JSON to
+* stderr. `--json` given to a command that does not spread it stops the command before it runs, with
+* `json_not_supported`.
+*
+* The `json` argument has a mark, by which gunshi tells it from a `json` argument of the command's
+* own, which gunshi does not touch. To give it a short name, spread it:
+* `{ ...jsonArgs.json, short: 'j' }`. A lazy command spreads it into its definition too.
+*
+* @example
+* ```js
+* import { define, jsonArgs } from 'gunshi'
+*
+* export default define({
+*   name: 'list',
+*   args: { ...jsonArgs },
+*   run: async ctx => {
+*     const projects = await fetchProjects()
+*     for (const project of projects) {
+*       ctx.log(project.name)
+*     }
+*     return { projects }
+*   }
+* })
+* ```
+*/
+const jsonArgs = { json: {
+	type: "boolean",
+	description: "Output the result as JSON",
+	[JSON_ARG]: true
+} };
 //#endregion
 //#region ../gunshi/src/definition.ts
 /**
@@ -288,4 +534,4 @@ function lazyWithTypes() {
 * @license MIT
 */
 //#endregion
-export { createCommandContext, define, defineWithTypes, lazy, lazyWithTypes };
+export { CommandError, createCommandContext, define, defineWithTypes, isCommandError, jsonArgs, lazy, lazyWithTypes };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/definition",
   "description": "utilities for gunshi command definition",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -52,16 +52,11 @@
     }
   },
   "devDependencies": {
-    "deno": "^2.7.14",
-    "gunshi": "1.0.0-rc.4",
-    "jsr": "^0.14.3",
-    "jsr-exports-lint": "^0.4.2",
+    "gunshi": "1.0.0-rc.6",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"
   },
   "scripts": {
-    "build": "tsdown",
-    "lint:jsr": "jsr publish --dry-run --allow-dirty",
-    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+    "build": "tsdown"
   }
 }