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

package/README.md

@@ -5,7 +5,7 @@
 
 > global options plugin for gunshi.
 
-This plugin provides standard global options (`--help` and `--version`) for all commands in your CLI application. It's installed by default in gunshi, ensuring consistent behavior across all CLI applications.
+This plugin provides standard global options (`--help` and `--version`) for all commands in your CLI application, and the JSON output of `--json` for the commands that spread `jsonArgs`. It's installed by default in gunshi, ensuring consistent behavior across all CLI applications.
 
 ## 💿 Installation
 
@@ -74,6 +74,16 @@ When these options are used:
 - **With `--help`**: The command execution is bypassed, and the usage information is displayed instead
 - **With `--version`**: The command execution is bypassed, and only the version number is printed
 
+### JSON Output
+
+A command that spreads `jsonArgs` from `gunshi` into its arguments accepts `--json`. With it, this plugin:
+
+- prints the result that the command returns from `run`, an object keyed by a noun, as one JSON document to stdout
+- prints an error as one line of JSON to stderr, with `status`, `reason`, `message`, `next` and `data`, and leaves stdout empty
+- stops a command that does not spread `jsonArgs` before it runs, with `json_not_supported`, when `--json` is given to it
+
+`--json` is not a global option: the commands that support it declare it. For the details, see [JSON Output](https://gunshi.dev/guide/essentials/json-output).
+
 ### Commands That Take the Name
 
 `help` and `version` are not reserved. A command may declare an argument of its own under either name, and gunshi merges the arguments of a command over the global options, so the command's argument wins:
@@ -119,6 +129,8 @@ Available extensions:
 
 <!-- eslint-enable markdown/no-missing-label-refs -->
 
+`showVersion()`, `showHeader()` and `showUsage()` print with `ctx.log`. When a command that spreads `jsonArgs` is asked for JSON with `--json`, they print nothing and return the text only.
+
 - **`showVersion(): string`**: Display the application version. Returns `'unknown'` if no version is specified in the CLI configuration.
 
 - **`showHeader(): Awaitable<string | undefined>`**: Display the application header. Returns `undefined` if no `renderHeader` function is provided in the CLI configuration.

package/lib/index.d.ts

@@ -3,6 +3,10 @@ import { Awaitable, PluginWithExtension } from "@gunshi/plugin";
 /**
  * Extended command context which provides utilities via global options plugin.
  * These utilities are available via `CommandContext.extensions['g:global']`.
+ *
+ * The functions that show the version, the header and the usage print with `ctx.log`. So they print
+ * nothing when `ctx.log` is silenced, with `usageSilent` or when a command that spreads `jsonArgs` is
+ * asked for JSON with `--json`, and return the text only.
  */
 interface GlobalExtension {
   /**

package/lib/index.js

@@ -1,8 +1,94 @@
-import { hasPriorityValidationError, plugin } from "@gunshi/plugin";
+import { ArgsValidationErrorKeys, CommandNotFoundErrorKeys, CommandResolutionErrorKeys, JsonOutputError, JsonOutputErrorKeys, hasPriorityValidationError, isArgsValidationError, isCommandError, isCommandNotFoundError, isCommandResolutionError, plugin } from "@gunshi/plugin";
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/utils.js
+/**
+* Entry point of utils.
+*
+* Note that this entry point is used by gunshi to import utility functions.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Convert a string to kebab-case.
+*
+* @param str - A string to convert
+* @returns Converted string into kebab-case.
+*/
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
+//#endregion
+//#region ../gunshi/src/utils.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @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;
+}
+/**
+* Log a message to the console.
+*
+* @param args - Arguments to log
+*/
+function log(...args) {
+	console.log(...args);
+}
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `_:`;
 const COMMON_ARGS = {
 	help: {
 		type: "boolean",
@@ -16,12 +102,80 @@ const COMMON_ARGS = {
 	}
 };
 //#endregion
+//#region ../resources/locales/en-US.json
+var en_US_default = {
+	COMMAND: "COMMAND",
+	COMMANDS: "COMMANDS",
+	SUBCOMMAND: "SUBCOMMAND",
+	USAGE: "USAGE",
+	ARGUMENTS: "ARGUMENTS",
+	OPTIONS: "OPTIONS",
+	EXAMPLES: "EXAMPLES",
+	FORMORE: "For more info, run any command with the `--help` flag",
+	NEGATABLE: "Negatable of",
+	DEFAULT: "default",
+	CHOICES: "choices",
+	CAUSEDBY: "Caused by",
+	help: "Display this help message",
+	version: "Display this version",
+	json: "Output the result as JSON",
+	"json:invalid-arguments": "{$count} arguments are invalid",
+	"json:next:help": "See the arguments of the command",
+	"json:next:help-placeholder": "Replace <COMMAND> with how you ran this CLI, to see the arguments of the command",
+	"err:arg:required-option": "Option {$displayName} is required",
+	"err:arg:required-positional": "Positional argument {$displayName} is required",
+	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
+	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
+	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
+	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:arg:unexpected-value": "Option {$displayName} does not take a value",
+	"err:arg:missing-value": "Option {$displayName} requires a value",
+	"err:arg:missing-value:hint": "(to pass '{$next}' as its value, write '{$suggestion}')",
+	"err:arg:conflict": "{$displayName} conflicts with {$conflictDisplayName}",
+	"err:arg:invalid-default": "Invalid default for {$displayName}: {$actual} is not one of {$choices}",
+	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:cmd:ambiguous": "The command is ambiguous. Move options after the command name: {$candidatePaths}",
+	"err:cmd:inconsistent-options": "The options do not identify a consistent command. Move options after the command name.",
+	"err:cmd:lazy-schema-mismatch": "The lazy command definition does not match its loaded options. Declare leading options in the lazy definition or move options after the command name: {$commandPath}",
+	"err:json:not-supported": "This command does not support --json",
+	"err:json:invalid-result": "The command finished, but did not return an object to output as JSON. A plugin that decorates the command may have dropped its result",
+	"err:json:unserializable-result": "The command finished, but its result cannot be converted to JSON: {$message}",
+	"err:suggestion:did-you-mean": "Did you mean {$name}?"
+};
+//#endregion
 //#region ../shared/src/utils.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
 /**
+* Resolve a namespaced key for built-in resources.
+*
+* Built-in keys are prefixed with "_:".
+*
+* @typeParam K - The type of the built-in key to resolve. Defaults to command built-in argument and resource keys.
+*
+* @param key - The built-in key to resolve.
+* @returns Prefixed built-in key.
+*/
+function resolveBuiltInKey(key) {
+	return `_:${key}`;
+}
+/**
+* Resolve a namespaced key for non-built-in resources.
+*
+* Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+*
+* @typeParam T - The type of the non-built-in key to resolve. Defaults to string.
+*
+* @param key - The non-built-in key to resolve.
+* @param name - The command name.
+* @returns Prefixed non-built-in key.
+*/
+function resolveKey(key, name) {
+	return `${name ? `${name}:` : ""}${key}`;
+}
+/**
 * Generate a namespaced key for a plugin.
 *
 * @typeParam K - The type of the plugin id to generate a namespaced key for.
@@ -32,12 +186,128 @@ const COMMON_ARGS = {
 function namespacedId(id) {
 	return `g:${id}`;
 }
+/**
+* Resolve the name that an argument is parsed and rendered under.
+*
+* @param name - The key of the argument.
+* @param schema - The {@linkcode ArgSchema | argument schema}.
+* @param toKebab - Whether to convert the name to kebab-case.
+* @returns The name of the argument, kebab-cased when `toKebab` asks for it.
+*/
+function resolveDisplayName(name, schema, toKebab) {
+	return toKebab || schema.toKebab ? kebabnize(name) : name;
+}
 //#endregion
 //#region ../shared/src/localization.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+/**
+* Format a resource message by replacing placeholder values.
+*
+* @param resource - Resource message template
+* @param values - Placeholder values
+* @returns Formatted resource message
+*/
+function formatResource(resource, values = Object.create(null)) {
+	return resource?.replaceAll(/\{\$(\w+)\}/g, (_, name) => {
+		return values[name] == null ? "" : String(values[name]);
+	});
+}
+//#endregion
+//#region ../shared/src/validation.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const i18nPluginId = namespacedId("i18n");
+const missingValueHintKey = "err:arg:missing-value:hint";
+/**
+* Localize the message of a validation error, as gunshi shows it to the user: with the i18n plugin when
+* it is installed, and otherwise the message of the error.
+*
+* NOTE(kazupon): the renderer plugin renders the validation errors for people, and the global options
+* plugin prints them as JSON with `--json`. Both take the messages from here, so that a message is the
+* same in both.
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param error - A validation error: an {@link ArgsValidationError}, a command-not-found error, or a
+* command-resolution error
+* @returns The localized message
+*/
+async function localizeValidationError(ctx, error) {
+	if (isCommandNotFoundError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
+	if (isCommandResolutionError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
+	if (isArgsValidationError(error) && error.code) {
+		const values = await resolveValidationValues(ctx, error);
+		const message = await localize(ctx, error.code, values);
+		if (message && message !== error.code) {
+			const hint = await localizeHint(ctx, error, values);
+			return hint ? `${message} ${hint}` : message;
+		}
+	}
+	return error.message;
+}
+/**
+* Localize a text of the built-in resources: with the i18n plugin when it is installed and knows the key,
+* and otherwise the English one.
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param key - The key of the text: `_:<key>` for a text that is not an error, and the key itself for an
+* error, such as `err:json:not-supported`
+* @param values - The values of the placeholders of the text
+* @returns The localized text, or the key when no resource has it
+*/
+async function localizeBuiltinResource(ctx, key, values) {
+	const message = await localize(ctx, key, values);
+	if (message && message !== key) return message;
+	return formatResource(en_US_default[key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR) ? key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length) : key], values) || key;
+}
+/**
+* Localize the hint that args-tokens adds to the message of an error.
+*
+* A translation replaces the whole message, hint included, so the hint is translated by a key of
+* its own and follows the translated error. args-tokens gives one today: for an option given without
+* a value, when the argument after it may be the value, the long form with `=` (`--port=-5` for
+* `--port -5`), in `values.next` and `values.suggestion`.
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param error - An args validation error
+* @param values - The values of the error, as given to its translation
+* @returns The localized hint, or `undefined` when the error has none.
+*/
+async function localizeHint(ctx, error, values) {
+	if (error.code !== ArgsValidationErrorKeys.missingValue || typeof values.next !== "string" || typeof values.suggestion !== "string") return;
+	const hint = await localize(ctx, missingValueHintKey, values);
+	return hint && hint !== missingValueHintKey ? hint : void 0;
+}
+async function resolveValidationValues(ctx, error) {
+	if (error.code !== ArgsValidationErrorKeys.customParse) return error.values;
+	const { reasonKey, reasonValues } = error.values;
+	if (typeof reasonKey !== "string") return error.values;
+	const key = resolveKey(reasonKey, ctx.name);
+	const localizedReason = await localize(ctx, key, toRecord(reasonValues));
+	if (!localizedReason || localizedReason === key) return error.values;
+	return {
+		...error.values,
+		reason: localizedReason
+	};
+}
+async function localize(ctx, key, values) {
+	const i18n = ctx.extensions?.[i18nPluginId];
+	if (i18n?.translate) return i18n.translate(key, values);
+	return key;
+}
+function toRecord(value) {
+	return value != null && typeof value === "object" ? value : Object.create(null);
+}
 //#endregion
 //#region ../shared/src/index.ts
 /**
@@ -55,18 +325,321 @@ function namespacedId(id) {
 */
 const pluginId = namespacedId("global");
 //#endregion
+//#region src/extension.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Print the version of the application.
+*
+* @param ctx - The command context
+* @param write - The function to print with
+* @returns The version of the application, or `unknown` if the version is not specified
+*/
+function writeVersion(ctx, write) {
+	const version = ctx.env.version || "unknown";
+	write(version);
+	return version;
+}
+/**
+* Print the usage of the application, with the header as its title.
+*
+* NOTE(kazupon): the header is the title of the usage, so it comes with the usage, wherever the usage is
+* shown: for `--help`, and when a command that takes `--help` itself shows it. It is not shown before a
+* command runs, where it would come before what the command prints, such as JSON.
+*
+* @param ctx - The command context
+* @param write - The function to print with
+* @returns The header and the usage of the application, or `undefined` if the `renderUsage` is not specified
+*/
+async function writeUsage(ctx, write) {
+	if (ctx.env.renderUsage == null) return;
+	const usage = await ctx.env.renderUsage(ctx);
+	if (!usage) return;
+	const header = ctx.env.renderHeader == null ? void 0 : await ctx.env.renderHeader(ctx);
+	if (header) {
+		write(header);
+		write();
+	}
+	write(usage);
+	return header ? [header, usage].join("\n") : usage;
+}
+/**
+* Extends the command context for global options plugin.
+*
+* @param ctx - The {@linkcode CommandContextCore | command context} core
+* @returns An {@linkcode GlobalExtension} of global options plugin
+*/
+function extension(ctx) {
+	return {
+		showVersion: () => writeVersion(ctx, ctx.log),
+		showHeader: async () => {
+			let header;
+			if (ctx.env.renderHeader != null) {
+				header = await ctx.env.renderHeader(ctx);
+				if (header) {
+					ctx.log(header);
+					ctx.log();
+				}
+			}
+			return header;
+		},
+		showUsage: async () => await writeUsage(ctx, ctx.log),
+		showValidationErrors: async (error) => {
+			if (ctx.env.renderValidationErrors === null) return;
+			if (ctx.env.renderValidationErrors !== void 0) {
+				const message = await ctx.env.renderValidationErrors(ctx, error);
+				/**
+				* NOTE(kazupon): the validation errors are diagnostics, not the output of the command, so they
+				* go to stderr, as the other CLI libraries do. stdout stays for what a command prints, such as JSON.
+				*/
+				if (message && !ctx.env.usageSilent) console.error(message);
+				return message;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/json.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* The reasons that are not derived from the codes by the rule: they would read as something else.
+*/
+const RENAMED_REASONS = /* @__PURE__ */ new Map([
+	[ArgsValidationErrorKeys.conflict, "conflicting_options"],
+	[CommandNotFoundErrorKeys.notFound, "unknown_command"],
+	[CommandResolutionErrorKeys.ambiguous, "ambiguous_command"],
+	[JsonOutputErrorKeys.notSupported, "json_not_supported"]
+]);
+/**
+* Convert the code of an error of gunshi to the `reason` of a JSON error: without the prefix, in
+* snake_case, such as `required_option` for `err:arg:required-option`. So the reasons are a contract
+* apart from the keys of the resources.
+*
+* @param code - The code of the error
+* @returns The reason
+*/
+function toReason(code) {
+	return RENAMED_REASONS.get(code) ?? code.replace(/^err:[^:]+:/, "").replaceAll("-", "_");
+}
+/**
+* Create the JSON error of the validation errors: the argument errors, an unknown command, and a command
+* that cannot be resolved. They stop the command before it runs.
+*
+* @param ctx - The command context
+* @param error - The aggregate error of the validation errors
+* @returns The JSON error
+*/
+async function createValidationFailure(ctx, error) {
+	const errors = error.errors;
+	const issues = [];
+	for (const err of errors) issues.push(await createIssue(ctx, err));
+	const [single] = issues.length === 1 ? issues : [];
+	return {
+		status: "action_required",
+		reason: single ? single.reason : "invalid_arguments",
+		message: single ? single.message : await localizeBuiltinResource(ctx, resolveBuiltInKey("json:invalid-arguments"), { count: issues.length }),
+		next: await createNext(ctx, resolveCommandPath(ctx, errors)),
+		data: { issues }
+	};
+}
+/**
+* Create the JSON error of `--json` given to a command that does not spread `jsonArgs`.
+*
+* @param ctx - The command context
+* @returns The JSON error
+*/
+async function createNotSupportedFailure(ctx) {
+	return {
+		status: "action_required",
+		reason: toReason(JsonOutputErrorKeys.notSupported),
+		message: await localizeBuiltinResource(ctx, JsonOutputErrorKeys.notSupported),
+		next: await createNext(ctx, ctx.commandPath)
+	};
+}
+/**
+* Create the JSON error of a result that cannot be printed as JSON.
+*
+* @param ctx - The command context
+* @param code - The code of the error
+* @param values - The values of the message
+* @returns The JSON error
+*/
+async function createResultFailure(ctx, code, values) {
+	return {
+		status: "error",
+		reason: toReason(code),
+		message: await localizeBuiltinResource(ctx, code, values)
+	};
+}
+/**
+* Create the JSON error of an error that the command threw. The `code` of a `CommandError` is its
+* reason, as it is: it is a contract of the app. Any other error is `command_failed`, even with a
+* `code`, such as `ENOENT`, that the app does not promise.
+*
+* @param error - The thrown error
+* @returns The JSON error
+*/
+function createRunFailure(error) {
+	const causes = collectCauses(error);
+	let message;
+	try {
+		message = messageOf(error);
+	} catch {
+		message = Object.prototype.toString.call(error);
+	}
+	return {
+		status: "error",
+		reason: (isCommandError(error) ? error.code : void 0) ?? "command_failed",
+		message,
+		...causes.length > 0 ? { data: { causes } } : {}
+	};
+}
+/**
+* Collect the messages of the causes of an error, from the outermost.
+*
+* A cause may be any value: a value without a message, such as a string, is converted to a string. A
+* cause may point back to an error in the chain, and may have a getter that throws: the chain ends
+* there.
+*
+* @param error - The error
+* @returns The messages of the causes
+*/
+function collectCauses(error) {
+	const causes = [];
+	const seen = /* @__PURE__ */ new Set([error]);
+	let cause;
+	try {
+		cause = typeof error === "object" && error !== null ? error.cause : void 0;
+	} catch {
+		return causes;
+	}
+	while (cause != null && !seen.has(cause)) {
+		seen.add(cause);
+		try {
+			causes.push(messageOf(cause));
+			cause = typeof cause === "object" ? cause.cause : void 0;
+		} catch {
+			break;
+		}
+	}
+	return causes;
+}
+/**
+* Get the message of an error, or of a cause, which may be any value. A value without a message, such as
+* a string, is converted to a string.
+*
+* @param value - The error or the cause
+* @returns The message
+* @throws {unknown} The error of a getter of `message` that throws
+*/
+function messageOf(value) {
+	const message = value?.message;
+	if (typeof message === "string" && message !== "") return message;
+	try {
+		return String(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}
+async function createIssue(ctx, error) {
+	const field = resolveField(ctx, error);
+	const reason = resolveReason(error);
+	const message = await localizeValidationError(ctx, error);
+	return field === void 0 ? {
+		reason,
+		message
+	} : {
+		field,
+		reason,
+		message
+	};
+}
+function resolveReason(error) {
+	if (isCommandNotFoundError(error)) return toReason(error.code ?? CommandNotFoundErrorKeys.notFound);
+	const code = error.code;
+	return typeof code === "string" ? toReason(code) : "invalid_arguments";
+}
+/**
+* Resolve how the user wrote the argument of an error on the command line: the long form of an option,
+* the name of a positional argument, an unknown option as it is typed, and an unknown command as it is
+* typed. So an agent can use it as it is.
+*
+* @param ctx - The command context
+* @param error - A validation error
+* @returns The field, or `undefined` for an error that no argument caused
+*/
+function resolveField(ctx, error) {
+	if (isCommandNotFoundError(error)) return error.commandName;
+	if (!isArgsValidationError(error)) return;
+	const { name, rawName } = error.values;
+	if (error.code === ArgsValidationErrorKeys.unknownOption) return typeof rawName === "string" ? rawName : void 0;
+	if (typeof name !== "string" || !Object.hasOwn(ctx.args, name)) return;
+	const schema = ctx.args[name];
+	return schema.type === "positional" ? name : `--${resolveDisplayName(name, schema, ctx.toKebab)}`;
+}
+/**
+* Resolve the path of the command whose help `next` points to: the command that is nearest to what the
+* user wrote. For an unknown command, and for a command that cannot be resolved, it is the command
+* under which the resolution failed.
+*
+* @param ctx - The command context
+* @param errors - The validation errors
+* @returns The command path
+*/
+function resolveCommandPath(ctx, errors) {
+	for (const error of errors) if (isCommandNotFoundError(error) || isCommandResolutionError(error)) return error.commandPath;
+	return ctx.commandPath;
+}
+/**
+* Create the `next` of a JSON error: the help of a command. Without the name of the CLI, the command
+* line has `<COMMAND>` for its name, and `when` tells to replace it, since the agent knows how it ran
+* the CLI.
+*
+* @param ctx - The command context
+* @param commandPath - The path of the command
+* @returns The `next`
+*/
+async function createNext(ctx, commandPath) {
+	const name = ctx.env.name;
+	const argv = [
+		name || "<COMMAND>",
+		...commandPath,
+		"--help"
+	];
+	const when = await localizeBuiltinResource(ctx, resolveBuiltInKey(name ? "json:next:help" : "json:next:help-placeholder"));
+	return [{
+		command: argv.join(" "),
+		argv,
+		when
+	}];
+}
+//#endregion
 //#region src/decorator.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
 /**
+* The id of the i18n plugin, which translates the heading of the causes of a {@linkcode CommandError}.
+*/
+const I18n = namespacedId("i18n");
+/**
+* The key of the built-in resource for the heading of the causes of a {@linkcode CommandError}.
+*/
+const CAUSED_BY = resolveBuiltInKey("CAUSEDBY");
+/**
 * The key of the registry in which the core keeps, for the command context of each run, the set of the
 * errors that have been reported to the user. An error in the set tells `cli()` to end without
 * rejecting. The errors are frozen with the command context, so they are not marked themselves. The key
 * is a registered symbol, since `gunshi` and the plugins bundle their own copies.
 */
 const REPORTED = Symbol.for("gunshi.reported");
+const NOOP = () => {};
 /**
 * Mark an error as reported to the user, in the set that the core keeps for the run of the context.
 *
@@ -90,6 +663,98 @@ function setExitCode(code) {
 	const proc = globalThis.process;
 	if (proc != null && typeof proc === "object") proc.exitCode = code;
 }
+function getStdout() {
+	const stdout = globalThis.process?.stdout;
+	return stdout != null && typeof stdout === "object" ? stdout : void 0;
+}
+/**
+* Wait until stdout has written what it holds, when it holds something: it drains, fails, or closes.
+*
+* NOTE(kazupon): Node.js writes to a pipe later, and `process.exit()` does not wait for it, so a large
+* JSON document is cut at 64KB or so when the app calls `process.exit()` after `cli()`. The wait has no
+* limit: a limit would cut the document only when the reader is slow. It does not keep the process
+* alive any longer than the write does.
+*/
+async function flushStdout() {
+	const stdout = getStdout();
+	if (stdout === void 0 || typeof stdout.writableLength !== "number" || stdout.writableLength === 0 || typeof stdout.once !== "function") return;
+	const once = stdout.once.bind(stdout);
+	await new Promise((resolve) => {
+		const done = () => {
+			for (const event of [
+				"drain",
+				"error",
+				"close"
+			]) stdout.removeListener?.(event, done);
+			resolve();
+		};
+		for (const event of [
+			"drain",
+			"error",
+			"close"
+		]) once(event, done);
+	});
+}
+/**
+* Translate the heading of the causes of a {@linkcode CommandError}, with the i18n plugin when it is
+* installed.
+*
+* NOTE(kazupon): the i18n plugin depends on this plugin, so this plugin cannot depend on it, and reads
+* its extension as the renderer plugin does. The i18n plugin translates a built-in key that the
+* resources of the app lack in English, and an older one returns the key itself: then the heading is
+* the English one of this plugin.
+*
+* @param extensions - The extensions of the command context
+* @returns The heading
+*/
+function translateCausedBy(extensions) {
+	const heading = extensions[I18n]?.translate?.(CAUSED_BY);
+	return heading && heading !== CAUSED_BY ? heading : en_US_default.CAUSEDBY;
+}
+/**
+* Render a {@linkcode CommandError} for the user: its message, followed by a `Caused by:` line for each
+* cause in the chain. The stack traces and the code are not rendered.
+*
+* @param error - The error
+* @param extensions - The extensions of the command context, to translate the heading of the causes
+* @returns The rendered error
+*/
+function renderCommandError(error, extensions) {
+	const causes = collectCauses(error);
+	if (causes.length === 0) return error.message;
+	const heading = translateCausedBy(extensions);
+	return [error.message, ...causes.map((cause) => `${heading}: ${cause}`)].join("\n");
+}
+/**
+* Create a {@linkcode JsonOutputError}, with the English message.
+*
+* @param code - The code of the error
+* @param values - The values of the message
+* @param cause - The cause of the error
+* @returns The error
+*/
+function createJsonOutputError(code, values, cause) {
+	const message = formatResource(en_US_default[code], values) || code;
+	return new JsonOutputError(message, {
+		code,
+		values,
+		cause
+	});
+}
+/**
+* Leave out the unknown-option errors of a `--json` that asks for JSON, which `strict` reports for a
+* command without a `json` argument. `--json` is the option of gunshi, so it is not unknown to it: the
+* plugin reports `json_not_supported` for it instead, with or without `strict`.
+*
+* @param error - The aggregate error of the validation errors
+* @returns The aggregate error without them, or `undefined` when no error is left
+*/
+function withoutJsonOption(error) {
+	if (error === void 0) return;
+	const errors = error.errors.filter((err) => !(isArgsValidationError(err) && err.code === ArgsValidationErrorKeys.unknownOption && err.values.rawName === "--json"));
+	if (errors.length === error.errors.length) return error;
+	return errors.length === 0 ? void 0 : new AggregateError(errors, error.message);
+}
 /**
 * Decorator function to extend the command with global options.
 *
@@ -102,7 +767,26 @@ const decorator = (baseRunner) => async (ctx) => {
 	* declares the same name — even with an identical schema — is not in that map, so `--version` /
 	* `--help` belong to the command.
 	*/
-	const { values, validationError, env: { globalOptions }, extensions: { [pluginId]: { showVersion, showUsage, showValidationErrors } } } = ctx;
+	const { values, env: { globalOptions }, extensions: { [pluginId]: { showValidationErrors } } } = ctx;
+	/**
+	* NOTE(kazupon): whether `--json` asks for JSON. `'declared'` for a command that spreads `jsonArgs`,
+	* by the resolved value of its `json`, and `'undeclared'` for a command without a `json` argument, by
+	* the raw tokens. Either way, the errors are printed as JSON. A command with a `json` of its own
+	* handles `--json` itself.
+	*/
+	const request = resolveJsonRequest(ctx.args, values, ctx.tokens);
+	const validationError = request === void 0 ? ctx.validationError : withoutJsonOption(ctx.validationError);
+	/**
+	* Print a JSON error to stderr, and mark the error as reported, with the exit code.
+	*
+	* @param error - The error
+	* @param failure - The JSON error
+	* @param exitCode - The exit code
+	*/
+	const printFailure = (error, failure, exitCode) => {
+		console.error(JSON.stringify(failure));
+		if (typeof error === "object" && error !== null && markReported(ctx, error)) setExitCode(exitCode);
+	};
 	/**
 	* NOTE(kazupon): when the plugin has shown the validation errors to the user, they have been
 	* reported: the exit code is 1, and `cli()` ends without rejecting, as the other CLI libraries end
@@ -111,79 +795,92 @@ const decorator = (baseRunner) => async (ctx) => {
 	* rejects with them, for the app to report them. So it does when the core keeps no set of reported
 	* errors for the run, and then the exit code is left alone.
 	*
+	* With `--json`, they are printed as JSON, and the renderer of the validation errors is not called.
+	* `renderValidationErrors: null` and `usageSilent` still leave them to the app.
+	*
 	* @param error - The aggregate error of the validation errors
+	* @param createFailure - The function that creates the JSON error, for an error that is not one of
+	* the validation errors
 	*/
-	const report = async (error) => {
+	const report = async (error, createFailure = () => createValidationFailure(ctx, error)) => {
+		if (request !== void 0) {
+			if (ctx.env.renderValidationErrors !== null && !ctx.env.usageSilent) printFailure(error, await createFailure(), 1);
+			throw error;
+		}
 		if (await showValidationErrors(error) && !ctx.env.usageSilent && markReported(ctx, error)) setExitCode(1);
 		throw error;
 	};
 	if (hasPriorityValidationError(validationError)) return await report(validationError);
-	if (values.version && globalOptions?.has("version")) return showVersion();
-	if (values.help && globalOptions?.has("help")) return await showUsage();
+	/**
+	* NOTE(kazupon): `--help` and `--version` print with `log`, not with `ctx.log`, which is silenced when
+	* the command is asked for JSON: the text of the help is what was asked for. `usageSilent` still
+	* silences them.
+	*/
+	const write = ctx.env.usageSilent ? NOOP : log;
+	if (values.version && globalOptions?.has("version")) return writeVersion(ctx, write);
+	if (values.help && globalOptions?.has("help")) return await writeUsage(ctx, write);
+	/**
+	* NOTE(kazupon): `--json` given to a command that does not spread `jsonArgs` stops it before it runs,
+	* as an argument error does, so that the caller does not take its text for JSON.
+	*/
+	if (request === "undeclared") return await report(new AggregateError([createJsonOutputError(JsonOutputErrorKeys.notSupported)]), () => createNotSupportedFailure(ctx));
 	if (validationError) return await report(validationError);
-	return baseRunner(ctx);
-};
-//#endregion
-//#region src/extension.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-/**
-* Extends the command context for global options plugin.
-*
-* @param ctx - The {@linkcode CommandContextCore | command context} core
-* @returns An {@linkcode GlobalExtension} of global options plugin
-*/
-function extension(ctx) {
-	return {
-		showVersion: () => {
-			const version = ctx.env.version || "unknown";
-			if (!ctx.env.usageSilent) ctx.log(version);
-			return version;
-		},
-		showHeader: async () => {
-			let header;
-			if (ctx.env.renderHeader != null) {
-				header = await ctx.env.renderHeader(ctx);
-				if (header) {
-					ctx.log(header);
-					ctx.log();
-				}
-			}
-			return header;
-		},
-		showUsage: async () => {
-			if (ctx.env.renderUsage == null) return;
-			const usage = await ctx.env.renderUsage(ctx);
-			if (!usage) return;
+	let result;
+	try {
+		result = await baseRunner(ctx);
+	} catch (error) {
+		if (request === "declared")
+ /**
+		* NOTE(kazupon): with `--json`, any error of the command is printed as JSON, so that the caller
+		* always gets JSON: the `code` of a `CommandError` is the reason, with the exit code of the error,
+		* and any other error is `command_failed`, with exit code 1. It is printed with `usageSilent` too,
+		* since it is not a text for people.
+		*/
+		printFailure(error, createRunFailure(error), isCommandError(error) ? error.exitCode : 1);
+		else if (isCommandError(error) && !ctx.env.usageSilent) {
 			/**
-			* NOTE(kazupon): the header is the title of the usage, so it comes with the usage, wherever the
-			* usage is shown: for `--help`, and when a command that takes `--help` itself shows it. It is not
-			* shown before a command runs, where it would come before what the command prints, such as JSON.
+			* NOTE(kazupon): a `CommandError` thrown from the command, or from a decorator of another plugin,
+			* is a failure that the command expects. It is reported as the validation errors are: the message
+			* is printed to stderr without a stack trace, the exit code is the one of the error, and `cli()`
+			* ends without rejecting. It is still thrown, so that the `onErrorCommand` hook sees it after the
+			* exit code is set. With `usageSilent`, nothing is printed, and `cli()` rejects with it, for the
+			* app to report it. Any other error is thrown as before, and `cli()` rejects with it.
 			*/
-			const header = ctx.env.renderHeader == null ? void 0 : await ctx.env.renderHeader(ctx);
-			if (header) {
-				ctx.log(header);
-				ctx.log();
-			}
-			ctx.log(usage);
-			return header ? [header, usage].join("\n") : usage;
-		},
-		showValidationErrors: async (error) => {
-			if (ctx.env.renderValidationErrors === null) return;
-			if (ctx.env.renderValidationErrors !== void 0) {
-				const message = await ctx.env.renderValidationErrors(ctx, error);
-				/**
-				* NOTE(kazupon): the validation errors are diagnostics, not the output of the command, so they
-				* go to stderr, as the other CLI libraries do. stdout stays for what a command prints, such as JSON.
-				*/
-				if (message && !ctx.env.usageSilent) console.error(message);
-				return message;
-			}
+			console.error(renderCommandError(error, ctx.extensions));
+			if (markReported(ctx, error)) setExitCode(error.exitCode);
 		}
+		throw error;
+	}
+	if (request !== "declared") return result;
+	/**
+	* Report a result that cannot be printed as JSON, and throw the error. The command has finished, so the
+	* message says so.
+	*
+	* @param code - The code of the error
+	* @param messageValues - The values of the message
+	* @param cause - The cause of the error
+	*/
+	const fail = async (code, messageValues, cause) => {
+		const error = createJsonOutputError(code, messageValues, cause);
+		printFailure(error, await createResultFailure(ctx, code, messageValues), 1);
+		throw error;
 	};
-}
+	/**
+	* NOTE(kazupon): the result is printed as one JSON document to stdout: indented on a terminal, on one
+	* line otherwise. It is checked first, for the code written in JavaScript and the types cast away: it
+	* must be an object, which `JSON.stringify` turns into an object.
+	*/
+	if (result === null || typeof result !== "object" || Array.isArray(result)) return await fail(JsonOutputErrorKeys.invalidResult);
+	let text;
+	try {
+		text = JSON.stringify(result, null, getStdout()?.isTTY === true ? 2 : void 0);
+	} catch (error) {
+		return await fail(JsonOutputErrorKeys.unserializableResult, { message: messageOf(error) }, error);
+	}
+	if (typeof text !== "string" || !text.startsWith("{")) return await fail(JsonOutputErrorKeys.invalidResult);
+	log(text);
+	await flushStdout();
+};
 //#endregion
 //#region src/index.ts
 /**

package/package.json

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