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

package/lib/index.d.ts

@@ -1,3 +1,12 @@
+//#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.
@@ -845,7 +854,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}
@@ -905,7 +918,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
@@ -1010,9 +1024,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}
@@ -1233,9 +1249,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 CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
+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 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;
 //#endregion
 //#region ../../node_modules/.pnpm/args-tokens@1.0.2/node_modules/args-tokens/lib/utils.d.ts
 /**
@@ -1258,6 +1305,36 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
 declare function kebabnize(str: string): string;
 //#endregion
 //#region ../gunshi/src/utils.d.ts
+/**
+ * How `--json` asks a command for JSON.
+ *
+ * - `'declared'`: the command spreads `jsonArgs` into its arguments, and `--json` asks it for JSON
+ * - `'undeclared'`: the command has no `json` argument, and `--json` is given to it
+ */
+type JsonRequest = 'declared' | 'undeclared';
+/**
+ * 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`
+ */
+declare function isJsonArg(schema: unknown): boolean;
+/**
+ * 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
+ */
+declare function resolveJsonRequest(args: Readonly<Args>, values: Readonly<Record<string, unknown>>, tokens?: readonly ArgToken[]): JsonRequest | undefined;
 /**
  * Check if the given command is a {@link LazyCommand}.
  *
@@ -1339,11 +1416,13 @@ type CommonArgType = {
   };
 };
 declare const COMMON_ARGS: CommonArgType;
-declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
+declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES", "CAUSEDBY"];
 declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
 declare const ARG_ERROR_HINT_RESOURCE_KEYS: readonly ["err:arg:missing-value:hint"];
 declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
+declare const JSON_RESOURCE_KEYS: readonly ["json", "json:invalid-arguments", "json:next:help", "json:next:help-placeholder"];
+declare const JSON_ERROR_RESOURCE_KEYS: readonly ["err:json:not-supported", "err:json:invalid-result", "err:json:unserializable-result"];
 //#endregion
 //#region src/types.d.ts
 type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
@@ -1387,14 +1466,23 @@ type CommandErrorResourceKeys = (typeof COMMAND_ERROR_RESOURCE_KEYS)[number];
  * Suggestion error resource keys.
  */
 type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the errors of the JSON output.
+ */
+type JsonErrorResourceKeys = (typeof JSON_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the description of the `json` argument of `jsonArgs`, and of the texts that only
+ * the JSON errors print.
+ */
+type JsonResourceKeys = (typeof JSON_RESOURCE_KEYS)[number];
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys | JsonErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
-type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
+type BuiltinResourceKeys = ErrorResourceKeys | CommandBuiltinArgsKeys | CommandBuiltinResourceKeys | JsonResourceKeys;
 /**
  * Built-in resource.
  */
@@ -1478,8 +1566,13 @@ declare const _exports: {
   NEGATABLE: string;
   DEFAULT: string;
   CHOICES: string;
+  CAUSEDBY: string;
   help: string;
   version: string;
+  json: string;
+  "json:invalid-arguments": string;
+  "json:next:help": string;
+  "json:next:help-placeholder": string;
   "err:arg:required-option": string;
   "err:arg:required-positional": string;
   "err:arg:invalid-type": string;
@@ -1495,6 +1588,9 @@ declare const _exports: {
   "err:cmd:ambiguous": string;
   "err:cmd:inconsistent-options": string;
   "err:cmd:lazy-schema-mismatch": string;
+  "err:json:not-supported": string;
+  "err:json:invalid-result": string;
+  "err:json:unserializable-result": string;
   "err:suggestion:did-you-mean": string;
 };
 //#endregion
@@ -1601,4 +1697,31 @@ declare function resolveOptionNames(args: Args, toKebab?: boolean): Set<string>;
  */
 declare function resolveCommandArgs<A extends Args = Args>(globalOptions?: ReadonlyMap<string, ArgSchema>, args?: A): A;
 //#endregion
-export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, type ArgErrorHintResourceKeys, type ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, type BuiltinResource, type BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, type CommandArgKeys, type CommandBuiltinArgsKeys, type CommandBuiltinKeys, type CommandBuiltinResourceKeys, type CommandErrorResourceKeys, type DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, type ErrorResourceKeys, type GenerateNamespacedKey, type KeyOfArgs, Localization, PLUGIN_PREFIX, type RemovedIndex, type ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, type SuggestionErrorResourceKeys, type Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };
+//#region src/validation.d.ts
+/**
+ * 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
+ */
+declare function localizeValidationError<G extends GunshiParams = DefaultGunshiParams>(ctx: CommandContext<G>, error: Error): Promise<string>;
+/**
+ * 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
+ */
+declare function localizeBuiltinResource<G extends GunshiParams = DefaultGunshiParams>(ctx: CommandContext<G>, key: string, values?: Record<string, unknown>): Promise<string>;
+//#endregion
+export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, type ArgErrorHintResourceKeys, type ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, type BuiltinResource, type BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, type CommandArgKeys, type CommandBuiltinArgsKeys, type CommandBuiltinKeys, type CommandBuiltinResourceKeys, type CommandErrorResourceKeys, type DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, type ErrorResourceKeys, type GenerateNamespacedKey, JSON_ERROR_RESOURCE_KEYS, JSON_RESOURCE_KEYS, type JsonErrorResourceKeys, JsonRequest, type JsonResourceKeys, type KeyOfArgs, Localization, PLUGIN_PREFIX, type RemovedIndex, type ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, type SuggestionErrorResourceKeys, type Translation, create, deepFreeze, formatResource, getCommandSubCommands, isJsonArg, isLazyCommand, kebabnize, localizable, localizeBuiltinResource, localizeValidationError, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveJsonRequest, resolveKey, resolveLazyCommand, resolveOptionNames };

package/lib/index.js

@@ -1,3 +1,8 @@
+/**
+* @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.
@@ -26,6 +31,51 @@ function kebabnize(str) {
 * @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
@@ -194,7 +244,8 @@ const COMMAND_BUILTIN_RESOURCE_KEYS = [
 	"FORMORE",
 	"NEGATABLE",
 	"DEFAULT",
-	"CHOICES"
+	"CHOICES",
+	"CAUSEDBY"
 ];
 const ARG_ERROR_RESOURCE_KEYS = [
 	"err:arg:required-option",
@@ -216,6 +267,17 @@ const COMMAND_ERROR_RESOURCE_KEYS = [
 	"err:cmd:lazy-schema-mismatch"
 ];
 const SUGGESTION_ERROR_RESOURCE_KEYS = ["err:suggestion:did-you-mean"];
+const JSON_RESOURCE_KEYS = [
+	"json",
+	"json:invalid-arguments",
+	"json:next:help",
+	"json:next:help-placeholder"
+];
+const JSON_ERROR_RESOURCE_KEYS = [
+	"err:json:not-supported",
+	"err:json:invalid-result",
+	"err:json:unserializable-result"
+];
 //#endregion
 //#region ../resources/locales/en-US.json
 var en_US_default = {
@@ -230,8 +292,13 @@ var en_US_default = {
 	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}",
@@ -247,6 +314,9 @@ var en_US_default = {
 	"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
@@ -458,6 +528,402 @@ function formatResource(resource, values = Object.create(null)) {
 		return values[name] == null ? "" : String(values[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
+*/
+/**
+* Entry point of argument options resolver.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Machine-readable error codes for {@link ArgsValidationError}.
+*
+* Each code identifies a validation failure category and is also suitable as an
+* i18n resource key for localized rendering.
+*
+* {@link resolveArgs} and `parse()` do not report `unknownOption`. An option that is not in the
+* schema takes the argument after it as its value, unless that argument is an option, and the value
+* is dropped: with no `foo` in the schema, `--foo bar` gives no positional argument.
+*/
+const ArgsValidationErrorKeys = {
+	requiredOption: "err:arg:required-option",
+	requiredPositional: "err:arg:required-positional",
+	invalidType: "err:arg:invalid-type",
+	invalidChoice: "err:arg:invalid-choice",
+	customParse: "err:arg:custom-parse",
+	unknownOption: "err:arg:unknown-option",
+	unexpectedValue: "err:arg:unexpected-value",
+	missingValue: "err:arg:missing-value",
+	conflict: "err:arg:conflict",
+	invalidDefault: "err:arg:invalid-default"
+};
+/**
+* Brand that marks {@link ArgsValidationError} instances.
+*
+* The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
+* identical across bundled copies of this module and across realms. It lets
+* {@link isArgsValidationError} recognize errors created by another copy of `args-tokens`,
+* where `instanceof` cannot match.
+*/
+const ARGS_VALIDATION_ERROR_BRAND = Symbol.for("args-tokens.ArgsValidationError");
+/**
+* An error that contains structured metadata for argument validation failures.
+*
+* The `message` remains the English fallback message. Renderers can use `code`
+* and `values` to localize the error, falling back to `message` when localization
+* is unavailable.
+*
+* Each instance carries a non-enumerable brand keyed by
+* `Symbol.for('args-tokens.ArgsValidationError')`, which {@link isArgsValidationError}
+* uses to recognize instances created by another bundled copy of `args-tokens`.
+*/
+var ArgsValidationError = class extends Error {
+	/**
+	* Machine-readable error code for this validation failure.
+	*
+	* This code can also be used as an i18n resource key.
+	*/
+	code;
+	/**
+	* Interpolation values for `code`.
+	*/
+	values;
+	/**
+	* Create an `ArgsValidationError` instance.
+	*
+	* @param message - fallback error message
+	* @param options - structured validation metadata
+	*/
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "ArgsValidationError";
+		this.code = options.code;
+		this.values = options.values ?? {};
+		Object.defineProperty(this, ARGS_VALIDATION_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+	}
+};
+/**
+* Check whether the given value is an {@link ArgsValidationError}.
+*
+* This guard also recognizes errors created by another bundled copy of `args-tokens`
+* (0.29.0 or later), where `instanceof` does not match. Such an error must have an own brand
+* keyed by `Symbol.for('args-tokens.ArgsValidationError')` set to `true`, and a `values` object.
+* The guard does not rely on `error.name`, so subclasses such as {@link ArgResolveError} that
+* override `name` are still recognized.
+*
+* The guard narrows to `ArgsValidationError` only. Across bundled copies,
+* `instanceof ArgResolveError` still does not match.
+*
+* @param error - value to check
+* @returns `true` when the value is an `ArgsValidationError`
+*/
+function isArgsValidationError$1(error) {
+	if (error instanceof ArgsValidationError) return true;
+	if (typeof error !== "object" || error === null) return false;
+	if (!Object.hasOwn(error, ARGS_VALIDATION_ERROR_BRAND) || error[ARGS_VALIDATION_ERROR_BRAND] !== true) return false;
+	const values = error.values;
+	return typeof values === "object" && values !== null;
+}
+//#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
+*/
+/**
+* Brand that marks {@link CommandNotFoundError} instances.
+*
+* The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
+* identical across bundled copies of gunshi (`gunshi`, `@gunshi/plugin`, `@gunshi/bone`)
+* and across realms. It lets {@link isCommandNotFoundError} recognize errors created by
+* another copy, where `instanceof` cannot match.
+*/
+const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
+const COMMAND_RESOLUTION_ERROR_BRAND = Symbol.for("gunshi.CommandResolutionError");
+/**
+* Error raised when a command cannot be resolved.
+*
+* Each instance carries a non-enumerable brand keyed by
+* `Symbol.for('gunshi.CommandNotFoundError')`, so that {@link isCommandNotFoundError}
+* recognizes it even when it was created by another bundled copy of gunshi.
+*/
+var CommandNotFoundError = class extends Error {
+	code;
+	values;
+	commandName;
+	candidates;
+	commandPath;
+	/**
+	* Create a command-not-found error.
+	*
+	* @param message - Fallback error message
+	* @param options - Command-not-found metadata
+	*/
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "CommandNotFoundError";
+		this.code = options.code;
+		this.values = options.values || {};
+		this.commandName = options.commandName;
+		this.candidates = options.candidates || [];
+		this.commandPath = options.commandPath || [];
+		Object.defineProperty(this, COMMAND_NOT_FOUND_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+	}
+};
+/**
+* Error raised when command routing cannot produce one consistent command.
+*
+* The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
+* guard, the new guard deliberately has no name-based fallback because this error type is new and
+* must not classify arbitrary errors from older versions.
+*/
+var CommandResolutionError = class extends Error {
+	code;
+	values;
+	commandPath;
+	candidatePaths;
+	/**
+	* Create a command resolution error with structured routing metadata.
+	*
+	* @param message - Human-readable fallback message
+	* @param options - Error code and command-routing metadata
+	*/
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "CommandResolutionError";
+		this.code = options.code;
+		this.values = options.values || {};
+		this.commandPath = options.commandPath || [];
+		this.candidatePaths = options.candidatePaths || [];
+		Object.defineProperty(this, COMMAND_RESOLUTION_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
+* class (`noExternal: ['gunshi/plugin']`), so an error thrown by `gunshi` is never an instance
+* of the class a plugin imports. Errors from another copy are recognized through the
+* `Symbol.for('gunshi.CommandNotFoundError')` brand, which does not depend on `error.name`.
+*
+* @param error - An unknown error
+* @returns `true` if the error is a {@link CommandNotFoundError}
+*/
+function isCommandNotFoundError(error) {
+	if (error instanceof CommandNotFoundError) return true;
+	if (!isRecord(error) || !hasCommandNotFoundErrorShape(error)) return false;
+	if (Object.hasOwn(error, COMMAND_NOT_FOUND_ERROR_BRAND) && error[COMMAND_NOT_FOUND_ERROR_BRAND] === true) return true;
+	return error instanceof Error && error.name === "CommandNotFoundError";
+}
+/**
+* Check whether an error is a {@link CommandResolutionError}.
+*
+* @param error - An unknown error
+* @returns `true` when the error has the command-resolution brand and shape
+*/
+function isCommandResolutionError(error) {
+	if (error instanceof CommandResolutionError) return true;
+	if (!isRecord(error) || !hasCommandResolutionErrorShape(error)) return false;
+	return Object.hasOwn(error, COMMAND_RESOLUTION_ERROR_BRAND) && error[COMMAND_RESOLUTION_ERROR_BRAND] === true;
+}
+/**
+* Check whether an error is an {@link ArgsValidationError}.
+*
+* Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
+* bundled copy through the `Symbol.for('args-tokens.ArgsValidationError')` brand that
+* `args-tokens` 0.29.0 or later sets, including subclasses such as `ArgResolveError` that
+* override `name` with the argument name. This guard additionally:
+*
+* - recognizes direct `ArgsValidationError` instances from copies bundling `args-tokens`
+*   older than 0.29.0, which do not set the brand
+* - checks that `code` and `values` of an error from another copy have the expected types
+*
+* The guard narrows only to {@link ArgsValidationError}: across copies,
+* `instanceof ArgResolveError` still fails, so do not rely on `type` or `schema` for such errors.
+*
+* @param error - An unknown error
+* @returns `true` if the error is an {@link ArgsValidationError}
+*/
+function isArgsValidationError(error) {
+	if (error instanceof ArgsValidationError) return true;
+	if (!isRecord(error) || !hasArgsValidationErrorShape(error)) return false;
+	if (isArgsValidationError$1(error)) return true;
+	return error instanceof Error && error.name === "ArgsValidationError";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+* 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 hasCommandNotFoundErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values) && typeof error.commandName === "string" && isStringArray(error.candidates) && isStringArray(error.commandPath);
+}
+function hasCommandResolutionErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values) && isStringArray(error.commandPath) && Array.isArray(error.candidatePaths) && error.candidatePaths.every((path) => isStringArray(path));
+}
+function hasArgsValidationErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values);
+}
+//#endregion
+//#region ../gunshi/src/plugin.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region ../plugin/src/index.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region 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 src/index.ts
 /**
@@ -465,4 +931,4 @@ function formatResource(resource, values = Object.create(null)) {
 * @license MIT
 */
 //#endregion
-export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };
+export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, JSON_ERROR_RESOURCE_KEYS, JSON_RESOURCE_KEYS, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isJsonArg, isLazyCommand, kebabnize, localizable, localizeBuiltinResource, localizeValidationError, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveJsonRequest, resolveKey, resolveLazyCommand, resolveOptionNames };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -50,8 +50,9 @@
     }
   },
   "devDependencies": {
-    "@gunshi/resources": "1.0.0-rc.5",
-    "gunshi": "1.0.0-rc.5",
+    "@gunshi/plugin": "1.0.0-rc.6",
+    "@gunshi/resources": "1.0.0-rc.6",
+    "gunshi": "1.0.0-rc.6",
     "publint": "^0.3.20",
     "tsdown": "0.22.14"
   },