@gunshi/plugin-renderer 1.0.0-beta.0 → 1.0.0-beta.1

package/lib/index.d.ts

@@ -1,18 +1,567 @@
 import { Args, Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
-import { Args as Args$1 } from "args-tokens";
-
-//#region ../gunshi/src/types.d.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
+import "@gunshi/plugin-i18n";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
+//#region src/resolver.d.ts
+/**
+ * An argument schema definition for command-line argument parsing.
+ *
+ * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
+ * - Additional `required`, `description`, and `hidden` properties
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
+ */
+interface ArgSchema {
+  /**
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix). `--flag=true` and
+   *   `--flag=false` set the value explicitly; any other value after `=` is a type error
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property, unless the argument
+   *   has a `parse` function)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * Any other `type`, or no `type`, is a mistake that only untyped code can make: if the argument
+   * has no `parse` function, {@link resolveArgs} and `parse()` throw an `Error`, whether or not the
+   * argument is given.
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose (--no-verbose needs negatable: true)
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
+  /**
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
+   */
+  short?: string;
+  /**
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
+   */
+  description?: string;
+  /**
+   * Hide the argument from generated help or usage output.
+   *
+   * This is metadata for renderers. It does not affect parsing, validation,
+   * required checks, defaults, conflicts, or resolved values.
+   *
+   * @example
+   * Hidden compatibility option:
+   * ```ts
+   * {
+   *   legacy: {
+   *     type: 'string',
+   *     hidden: true,
+   *     description: 'Deprecated compatibility option'
+   *   }
+   * }
+   * ```
+   */
+  hidden?: boolean;
+  /**
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user. If it is missing, the error is an
+   * `ArgResolveError` with type 'required' and the code `err:arg:required-option`
+   * ({@link ArgsValidationErrorKeys}.requiredOption), or `err:arg:required-positional`
+   * ({@link ArgsValidationErrorKeys}.requiredPositional) for a positional argument. Its
+   * `values` has the `displayName` as in the message, such as `'--name'` for an option
+   * (`'--name' or '-n'` with the short name `n`) and `'file'` for a positional argument, and
+   * the `name`, which is the schema key.
+   * An option that is given without a value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue) instead, because the option itself was given.
+   * An explicit empty value, such as `--name=` or `-n ''`, is still reported as required, but the
+   * option counts as given: it is `true` in `explicit` and takes part in conflicts, as any other
+   * given option does.
+   *
+   * For single-value positional arguments, omitting `required` keeps the argument required for
+   * compatibility, unless it has a `default`, which makes it optional. A `multiple` positional
+   * argument is optional unless `required: true` is set. Set `required: false` to make a positional
+   * argument explicitly optional. Optional positional arguments leave enough input values for later
+   * required positional arguments before consuming a value.
+   *
+   * In the type of the values, such as {@link ArgValues}, a single-value positional argument whose
+   * `required` may be `false`, such as one of type `boolean`, is optional, as it may be missing,
+   * unless it has a `default`. An optional `required` of type `boolean`, as declared here, says
+   * nothing, and keeps it required. TypeScript widens a `required: true` to `boolean` in a schema
+   * written apart from the call, such as `{ type: 'positional' as const, required: true }`, which
+   * types the argument as optional: write such a schema `as const`.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
+   */
+  required?: boolean;
+  /**
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array. When the argument is not given and has no
+   * `default`, its value is `undefined`, not an empty array.
+   * For options: can be specified multiple times (--tags foo --tags bar)
+   * For positional: collects remaining positional arguments after preserving values for
+   * later required positional arguments.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
+   */
+  multiple?: true;
+  /**
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * The negated name is always `no-` followed by the full option name. An option named
+   * `no-cache` is negated by `--no-no-cache`, and `--no-cache` sets it to `true`.
+   *
+   * The negated form does not take a value. `--no-flag=<value>` is reported as
+   * `err:arg:unexpected-value` ({@link ArgsValidationErrorKeys}.unexpectedValue).
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
+   */
+  negatable?: boolean;
+  /**
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`, unless the argument has a `parse` function: if `choices` is
+   * missing or not an array, {@link resolveArgs} and `parse()` throw a `TypeError`, whether or not
+   * the argument is given. With a `parse` function and no `choices`, the value is passed to the
+   * function as for a `string` argument with a `parse` function.
+   *
+   * The argument value must be one of these choices, otherwise the error is an `ArgResolveError`
+   * with type 'type' and the code `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice).
+   *
+   * The value is checked before `parse` is called, so a `parse` function receives only one of
+   * these choices and can change it, for example to upper case.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
+   */
+  choices?: string[] | readonly string[];
+  /**
+   * Default value used when the argument is not provided. An option that is given without a value,
+   * or with a value that is rejected, also gets its default, along with the error.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: one of the `choices` values, or a value that a `parse` of your own returns
+   * - `positional`/`custom` type: string, boolean, or number default
+   *
+   * The default is used as is and never goes through `parse`, including when an option is given
+   * without a value. An explicit empty value, such as `--name=` or `-n ''`, is a value, not a
+   * missing one: a `string` option without `parse` gets `''` instead of the default, unless it is
+   * `required`. What `parse` returns is a value too, even `undefined` or `null`, and the default
+   * does not replace it.
+   *
+   * The value of a `multiple` argument is an array, so its default becomes the only element of the
+   * array: `default: 'latest'` gives `['latest']`.
+   *
+   * The default of an `enum` option with `choices` is checked when it would be used, that is, when
+   * no value from the command line is used: one that is not one of the choices is reported as an
+   * `ArgResolveError` with type 'type' and the code `err:arg:invalid-default`
+   * ({@link ArgsValidationErrorKeys}.invalidDefault), and is not used. With a `parse` function of
+   * your own, or a `map()` transform, the default is a value that the function returns, which need
+   * not be one of the choices, and it is not checked. `choice()` returns the value as is, so its
+   * default is checked.
+   *
+   * For positional arguments, `multiple` ones included, the default is used when no value is left
+   * for the argument: when the positional values run out, or when the remaining ones are preserved
+   * for later required positional arguments. With `required: true`, the default is not used, and
+   * the argument is reported as required instead.
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
+   */
+  default?: string | boolean | number;
+  /**
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * The `toKebab` option of {@link resolveArgs} and `parse()` applies it to all arguments, as in
+   * `resolveArgs(args, tokens, { toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
+   */
+  toKebab?: true;
+  /**
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options, 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
+   * `conflictName` of the other one. `displayName` and `conflictDisplayName` show an option as
+   * it was written, such as `'-p'`, and `name` and `conflictName` are the schema keys. When both
+   * name each other, `name` is the one that comes first in the schema.
+   *
+   * 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'`.
+   *
+   * 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,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn reports an error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
+  /**
+   * Display name hint for help text generation.
+   *
+   * Provides a meaningful type hint for the argument value in help output.
+   * Particularly useful for `type: 'custom'` arguments where the type
+   * name would otherwise be unhelpful.
+   *
+   * For a `custom` option that is given without a value, it is also the `expected` in the `values`
+   * of the `err:arg:missing-value` error ({@link ArgsValidationErrorKeys}.missingValue), which is
+   * `'custom'` without it.
+   *
+   * @example
+   * Metavar usage:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'custom',
+   *     parse: (v: string) => parseInt(v, 10),
+   *     metavar: 'integer',
+   *     description: 'Port number (1-65535)'
+   *   }
+   * }
+   * // Help output: --port <integer>  Port number (1-65535)
+   * ```
+   */
+  metavar?: string;
+  /**
+   * Custom parsing function, used in place of the parsing of the argument's `type`.
+   *
+   * Required when `type: 'custom'`: if it is missing or not a function, {@link resolveArgs} and
+   * `parse()` throw a `TypeError`, whether or not the argument is given. The function receives the
+   * raw string value and must return the parsed result. It should throw an Error (or subclass) if
+   * parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * `parse` is called synchronously, and what it returns becomes the value, even `undefined` or
+   * `null`, so throw to reject a value. An `async` function returns a promise, and the promise
+   * becomes the value as is: it is not awaited, and its rejection is not reported as an error.
+   * Await the value, or each of its elements with `multiple` (for example with `Promise.all()`),
+   * and handle the rejection yourself: a rejection that nothing handles is an unhandled rejection,
+   * which ends a Node.js process by default.
+   *
+   * A `boolean` option calls `parse` with `'true'`, or `'false'` for the negated form. Other
+   * options call it only with a value from the command line: when the option is given without a
+   * value, `parse` is not called and the missing value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue). When that error may suggest the argument after
+   * the option as its value, such as `--port=-5` for `--port -5`, a `parse` function of your own
+   * is not called to check it either: only the `parse` functions of `string()`, `number()`,
+   * `integer()`, `float()` and `choice()`, which have no side effects, are called for that.
+   * An explicit empty value, such as `--name=` or `-n=`, is passed as `''` unless
+   * `required: true` is set.
+   *
+   * An `enum` option with `choices` calls it only with one of them. Any other value, an explicit
+   * empty one included, is reported as `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice), except that a required option reports an
+   * explicit empty value as required.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws {Error} Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  parse?: (value: string) => any;
+}
+/**
+ * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
+ */
+interface Args$1 {
+  [option: string]: ArgSchema;
+}
 //#endregion
 //#region ../shared/src/constants.d.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
 /**
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
@@ -36,35 +585,20 @@ 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 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"];
-//#endregion
-//#region ../plugin-i18n/src/types.d.ts
-
-//#endregion
-//#region ../plugin-i18n/src/helpers.d.ts
-
-//#endregion
-//#region ../plugin-i18n/src/translation.d.ts
-
-//#endregion
-//#region ../gunshi/src/index.d.ts
-
 //#endregion
 //#region ../shared/src/types.d.ts
-type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
-/**
- * Make all properties in T deeply writeable (not readonly)
- */
-
+type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
 /**
  * Remove index signature from object or record type.
  */
-type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K]; }>;
 /**
  * Resolve a key on {@link Args}.
  */
-type KeyOfArgs<A extends Args$1> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
+type KeyOfArgs<A extends Args$1> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never; }[keyof A];
 /**
  * Generate a namespaced key.
  */
@@ -81,6 +615,10 @@ type CommandBuiltinResourceKeys = (typeof COMMAND_BUILTIN_RESOURCE_KEYS)[number]
  * Args validation error resource keys.
  */
 type ArgErrorResourceKeys = (typeof ARG_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the hints that follow an args validation error.
+ */
+type ArgErrorHintResourceKeys = (typeof ARG_ERROR_HINT_RESOURCE_KEYS)[number];
 /**
  * Command validation error resource keys.
  */
@@ -92,7 +630,7 @@ type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[numbe
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
 /**
  * Command built-in keys.
  */
@@ -107,22 +645,11 @@ type CommandArgKeys<A extends Args$1, C = {}, K extends string = GenerateNamespa
 /**
  * Resolve translation keys for command context.
  */
-type ResolveTranslationKeys<A extends Args$1, C = {},
-// for CommandContext
-E extends Record<string, string> = {},
-// for extended resources
-R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
+type ResolveTranslationKeys<A extends Args$1, C = {} // for CommandContext
+, E extends Record<string, string> = {} // for extended resources
+, R extends string = keyof RemovedIndex<E>, T extends string = C extends {
   name: infer N;
-} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
-//#endregion
-//#region ../shared/src/localization.d.ts
-
-//#endregion
-//#region ../shared/src/utils.d.ts
-
-//#endregion
-//#region ../shared/src/index.d.ts
-
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys, O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -151,11 +678,9 @@ interface UsageRendererExtension<G extends GunshiParams<any> = DefaultGunshiPara
    * @param values - An optional record of values to interpolate into the translation string.
    * @returns The resolved translation string with interpolated values if provided.
    */
-  text: <A extends Args = G['args'], C = {},
-  // for CommandContext
-  E extends Record<string, string> = {},
-  // for extended resources
-  K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>) => Promise<string>;
+  text: <A extends Args = G['args'], C = {} // for CommandContext
+  , E extends Record<string, string> = {} // for extended resources
+  , K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>) => Promise<string>;
   /**
    * Load commands
    *

package/lib/index.js

@@ -153,13 +153,14 @@ var en_US_default = {
 	help: "Display this help message",
 	version: "Display this version",
 	"err:arg:required-option": "Optional argument {$displayName} is required",
-	"err:arg:required-positional": "Positional argument {$name} 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": "Optional argument {$displayName} does not take a value",
 	"err:arg:missing-value": "Optional argument {$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}",
@@ -442,10 +443,10 @@ function isHiddenArg(schema) {
 	return schema.hidden === true;
 }
 function getVisibleOptionalArgs(args) {
-	return Object.entries(args).filter(([_, schema]) => schema.type !== "positional" && !isHiddenArg(schema));
+	return Object.entries(args).filter(([, schema]) => schema.type !== "positional" && !isHiddenArg(schema));
 }
 function getVisiblePositionalArgs(args) {
-	return Object.entries(args).filter(([_, schema]) => schema.type === "positional" && !isHiddenArg(schema));
+	return Object.entries(args).filter(([, schema]) => schema.type === "positional" && !isHiddenArg(schema));
 }
 /**
 * Render the usage.
@@ -661,7 +662,7 @@ function hasAllDefaultOptions(args) {
 	* NOTE(kazupon): an argument has a default when one is declared, whatever its value. `0`, `''` and
 	* `false` are defaults like any other, and an option that has one is not required (#750).
 	*/
-	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default !== void 0);
+	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([, arg]) => arg.default !== void 0);
 }
 /**
 * Generate options symbols for usage
@@ -731,7 +732,7 @@ async function resolveDisplayValue(ctx, key) {
 async function generateOptionalArgsUsage(ctx, optionsPairs) {
 	const optionsPairsEntries = Object.entries(optionsPairs);
 	if (optionsPairsEntries.length === 0) return "";
-	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([_, value]) => displayWidth(value)));
+	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([, value]) => displayWidth(value)));
 	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => displayWidth(resolveNegatableType(key, ctx)))) : 0;
 	return (await Promise.all(optionsPairsEntries.map(async ([key, value]) => {
 		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx.name));
@@ -790,6 +791,7 @@ function isRequiredSinglePositionalArg(arg) {
 * @license MIT
 */
 const i18nPluginId$1 = namespacedId("i18n");
+const missingValueHintKey = "err:arg:missing-value:hint";
 /**
 * Render the validation errors.
 *
@@ -814,10 +816,31 @@ async function renderValidationError(ctx, error) {
 	if (isArgsValidationError(error) && error.code) {
 		const values = await resolveValidationValues(ctx, error);
 		const message = await localize(ctx, error.code, values);
-		if (message && message !== error.code) return message;
+		if (message && message !== error.code) {
+			const hint = await localizeHint(ctx, error, values);
+			return hint ? `${message} ${hint}` : message;
+		}
 	}
 	return error.message;
 }
+/**
+* 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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,18 +53,18 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-beta.0"
+    "@gunshi/plugin": "1.0.0-beta.1"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "1.0.0-beta.0"
+    "@gunshi/plugin-i18n": "1.0.0-beta.1"
   },
   "devDependencies": {
+    "@gunshi/shared": "1.0.0-beta.1",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
-    "tsdown": "0.21.0",
-    "@gunshi/shared": "1.0.0-beta.0"
+    "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",