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

package/README.md

@@ -6,7 +6,7 @@
 
 > usage renderer plugin for gunshi.
 
-This plugin provides customizable rendering for CLI help messages, usage information, and validation errors. It automatically formats command descriptions, arguments, options, examples, and error messages in a consistent and readable format.
+This plugin provides customizable rendering for CLI help messages, usage information, and validation errors. It automatically formats command descriptions, arguments, options, examples, and error messages in a consistent and readable format. Description columns are aligned by the width a terminal draws, including full-width names; emoji sequences joined with ZWJ may still differ by terminal.
 
 ## 💿 Installation
 
@@ -136,7 +136,9 @@ Available extensions:
 
 - **`text<K>(key: K, values?: Record<string, unknown>): Promise<string>`**: Render text with optional i18n support. Handles built-in keys, argument descriptions, and custom keys intelligently.
 
-- **`loadCommands<G>(): Promise<Command<G>[]>`**: Load and cache subcommands for rendering command lists. Results are cached after the first call for performance.
+- **`loadCommands<G>(): Promise<Command<G>[]>`**: Load and cache commands for rendering command lists. At the top level, the list also includes the CLI's entry command when plugins registered the subcommands without adding the entry to the registry. Results are cached after the first call for performance.
+
+- **`localizeCommandDescription(cmd): Promise<string>`**: Resolve the description of a command in the command list. Localized when `@gunshi/plugin-i18n` is installed and the command has a resource of its own; otherwise `Command.description`.
 
 ### Usage Example
 

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
@@ -35,36 +584,21 @@ 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"];
-declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found"];
+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,19 +678,29 @@ 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
    *
    * @typeParam G - A type extending {@link GunshiParams} to specify the shape of command parameters.
    *
-   * @returns A list of commands loaded from the usage renderer plugin.
+   * @returns A list of commands loaded from the usage renderer plugin. At the top-level entry,
+   * the list includes the CLI entry command even when a plugin registered the other commands
+   * without adding the entry to `env.subCommands`.
    */
   loadCommands: <G extends GunshiParams = DefaultGunshiParams>() => Promise<Command<G>[]>;
+  /**
+   * Resolve the description of a command in the command list.
+   *
+   * The description is localized when `@gunshi/plugin-i18n` is installed and the command has a
+   * resource of its own, and falls back to {@link Command.description} otherwise.
+   *
+   * @param cmd - A command from {@link UsageRendererExtension.loadCommands}.
+   * @returns The description to show for the command.
+   */
+  localizeCommandDescription: (cmd: Command) => Promise<string>;
 }
 //#endregion
 //#region src/header.d.ts

package/lib/index.js

@@ -1,5 +1,5 @@
-import { ANONYMOUS_COMMAND_NAME, ArgsValidationErrorKeys, isArgsValidationError, isCommandNotFoundError, plugin } from "@gunshi/plugin";
-//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/utils.js
+import { ANONYMOUS_COMMAND_NAME, ArgsValidationErrorKeys, createCommandContext, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin } from "@gunshi/plugin";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -30,14 +30,20 @@ function kebabnize(str) {
 * Check if the given command is a {@link LazyCommand}.
 *
 * @param cmd - A command to check
-* @returns `true` if the command is a {@link LazyCommand}, otherwise `false
+* @returns `true` if the command is a {@link LazyCommand}, otherwise `false`
+*
+* A lazy command is identified by its `commandName` property. The property may be
+* `undefined` when the lazy command has no definition name.
 */
 function isLazyCommand(cmd) {
-	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+	return typeof cmd === "function" && "commandName" in cmd;
 }
 /**
 * Resolve a lazy command to a {@link Command}.
 *
+* If the loader returns a command, the properties of the loaded command take precedence,
+* and the properties that it does not define fall back to the definition that is given to `lazy`.
+*
 * @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
 * @param name - Optional name of the command, if not provided, it will use the name from the command itself.
 * @param needRunResolving - Whether to run the resolving function of the lazy command.
@@ -53,6 +59,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			examples: cmd.examples,
 			internal: cmd.internal,
 			entry: cmd.entry,
+			toKebab: cmd.toKebab,
+			rendering: cmd.rendering,
 			subCommands: cmd.subCommands
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
@@ -62,13 +70,20 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			if (typeof loaded === "function") command.run = loaded;
 			else if (typeof loaded === "object") {
 				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
+				/**
+				* NOTE(kazupon): the loaded command wins, and the definition that is given to `lazy` is the fallback
+				* for what the loaded command does not define. A loader that returns `{ run }` keeps the whole definition,
+				* like a loader that returns the runner itself.
+				*/
 				command.run = loaded.run;
-				command.name = loaded.name;
-				command.description = loaded.description;
-				command.args = loaded.args;
-				command.examples = loaded.examples;
-				command.internal = loaded.internal;
-				command.entry = loaded.entry;
+				command.name = loaded.name ?? cmd.commandName;
+				command.description = loaded.description ?? cmd.description;
+				command.args = loaded.args ?? cmd.args;
+				command.examples = loaded.examples ?? cmd.examples;
+				command.internal = loaded.internal ?? cmd.internal;
+				command.entry = loaded.entry ?? cmd.entry;
+				command.toKebab = loaded.toKebab ?? cmd.toKebab;
+				command.rendering = loaded.rendering ?? cmd.rendering;
 				command.subCommands = loaded.subCommands || cmd.subCommands;
 				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
 			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
@@ -138,12 +153,20 @@ 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}",
+	"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:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
@@ -226,10 +249,36 @@ function namespacedId(id) {
 * @returns A string representing the short and long option pair.
 */
 function makeShortLongOptionPair(schema, name, toKebab) {
-	let key = `--${toKebab || schema.toKebab ? kebabnize(name) : name}`;
+	let key = `--${resolveDisplayName(name, schema, toKebab)}`;
 	if (schema.short) key = `-${schema.short}, ${key}`;
 	return key;
 }
+/**
+* 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;
+}
+/**
+* Collect the names that the arguments are parsed and rendered under.
+*
+* A positional argument is left out: it is never spelled as an option, so it cannot take the name of
+* one. A `hidden` argument is counted, because it still owns the name that it parses.
+*
+* @param args - The {@linkcode Args | arguments} of a command, global options included.
+* @param toKebab - Whether the command converts its names to kebab-case.
+* @returns The set of names.
+*/
+function resolveOptionNames(args, toKebab) {
+	const names = /* @__PURE__ */ new Set();
+	for (const [name, schema] of Object.entries(args)) if (schema.type !== "positional") names.add(resolveDisplayName(name, schema, toKebab));
+	return names;
+}
 //#endregion
 //#region ../shared/src/localization.ts
 /**
@@ -257,15 +306,21 @@ function localizable(ctx, cmd, translate) {
 		if (key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key, key, values);
 		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
-			let argKey = key.slice(namaspacedArgKey.length);
-			let negatable = false;
+			const argKey = key.slice(namaspacedArgKey.length);
+			/**
+			* NOTE(kazupon): an argument describes itself, whatever it is called. `no-` is stripped only
+			* to reach the option that a negated form negates, and only when there is no argument under
+			* the name as written: `no-emoji` may be an argument of its own, and it then has nothing to do
+			* with `emoji`.
+			*/
+			const ownSchema = ctx.args[argKey];
+			if (ownSchema) return ownSchema.description || "";
 			if (argKey.startsWith("no-")) {
-				argKey = argKey.slice(3);
-				negatable = true;
+				const negatedKey = argKey.slice(3);
+				const schema = ctx.args[negatedKey];
+				if (schema && schema.type === "boolean" && schema.negatable) return `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, negatedKey, ctx.toKebab)}`;
 			}
-			const schema = ctx.args[argKey];
-			if (!schema) return argKey;
-			return negatable && schema.type === "boolean" && schema.negatable ? `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, argKey, ctx.toKebab)}` : schema.description || "";
+			return argKey;
 		}
 		if (key === resolveKey("description", ctx.name)) return "";
 		else if (key === resolveKey("examples", ctx.name)) return await resolveExamples$1(ctx, cmd.examples);
@@ -321,6 +376,63 @@ function renderHeader(ctx) {
 */
 const pluginId = namespacedId("renderer");
 //#endregion
+//#region src/width.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* NOTE(kazupon): the columns of the usage are aligned by padding, and padding by `String#length`
+* counts UTF-16 code units, which is not what a terminal draws: a full-width character takes two
+* columns, a combining mark takes none, and a joined emoji takes two however many code points it is
+* written with. The text is walked by grapheme, so that a mark or a joiner is part of the character
+* it belongs to, and each grapheme is measured by the code point it starts with.
+*
+* JavaScript has no `\p{East_Asian_Width=Wide}` escape. Wide columns are those the engine already
+* classifies as Han / Hiragana / Katakana / Hangul or emoji-presentation, plus the fullwidth slice
+* of Halfwidth and Fullwidth Forms. That covers CLI names; the rest of the East Asian Width table
+* is symbols that do not appear there. Unicode updates then come with the runtime.
+*/
+const WIDE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Emoji_Presentation}]/u;
+const ZERO_WIDTH = /[\p{Default_Ignorable_Code_Point}\p{Mn}]/u;
+function graphemeWidth(codePoint) {
+	const ch = String.fromCodePoint(codePoint);
+	if (ZERO_WIDTH.test(ch)) return 0;
+	/**
+	* Halfwidth and Fullwidth Forms: only the fullwidth slices are two columns. The rest of the
+	* block is halfwidth katakana / hangul, which `\p{Script=Katakana}` and `\p{Script=Hangul}`
+	* would otherwise count as wide.
+	*/
+	if (codePoint >= 65280 && codePoint <= 65519) {
+		if (codePoint >= 65281 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510) return 2;
+		return 1;
+	}
+	return WIDE.test(ch) ? 2 : 1;
+}
+const segmenter = new Intl.Segmenter();
+/**
+* Measure the columns a terminal draws a string in.
+*
+* @param value - A string to measure
+* @returns The number of columns
+*/
+function displayWidth(value) {
+	let width = 0;
+	for (const { segment } of segmenter.segment(value)) width += graphemeWidth(segment.codePointAt(0));
+	return width;
+}
+/**
+* Pad a string with spaces until it is drawn in the given number of columns.
+*
+* @param value - A string to pad
+* @param width - The number of columns to pad it to
+* @returns The padded string
+*/
+function padEndToWidth(value, width) {
+	const padding = width - displayWidth(value);
+	return padding > 0 ? value + " ".repeat(padding) : value;
+}
+//#endregion
 //#region src/usage.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -331,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.
@@ -428,18 +540,21 @@ async function makeUsageSymbols(ctx) {
 async function renderCommandsSection(ctx) {
 	const messages = [`${await ctx.extensions[pluginId].text(resolveBuiltInKey("COMMANDS"))}:`];
 	const loadedCommands = await ctx.extensions?.[pluginId].loadCommands() || [];
-	const commandMaxLength = Math.max(...loadedCommands.map((cmd) => (cmd.name || "").length));
-	const commandsStr = await Promise.all(loadedCommands.map(async (cmd) => {
-		const desc = cmd.description || "";
-		const optionSymbol = await generateOptionsSymbols(ctx, ctx.args);
-		const positionalSymbol = generatePositionalSymbols(ctx.args);
-		const commandStr = await makeCommandSymbol(ctx, cmd);
-		const symbolLength = desc.length > 0 ? commandMaxLength + optionSymbol.length + positionalSymbol.length : 0;
-		const command = `${commandStr.padEnd(symbolLength + ctx.env.middleMargin)}${desc}`;
+	const commandSymbols = await Promise.all(loadedCommands.map(async (cmd) => await makeCommandSymbol(ctx, cmd)));
+	const symbolMaxLength = Math.max(...commandSymbols.map((symbol) => displayWidth(symbol)));
+	const commandsStr = (await Promise.all(loadedCommands.map(async (cmd) => await ctx.extensions[pluginId].localizeCommandDescription(cmd)))).map((desc, index) => {
+		const commandStr = commandSymbols[index];
+		const command = desc ? `${padEndToWidth(commandStr, symbolMaxLength + ctx.env.middleMargin)}${desc}` : commandStr;
 		return `${command.padStart(ctx.env.leftMargin + command.length)}`;
-	}));
+	});
 	messages.push(...commandsStr, "", `${await ctx.extensions[pluginId].text(resolveBuiltInKey("FORMORE"))}:`);
-	const basePath = ctx.commandPath && ctx.commandPath.length > 0 ? `${ctx.env.name} ${ctx.commandPath.join(" ")}` : ctx.env.name;
+	/**
+	* NOTE(kazupon): the CLI is named the same way the usage line and the entry row of the section
+	* above name it, because `CliOptions.name` is optional and the block would otherwise invite the
+	* reader to run `undefined --help`.
+	*/
+	const entry = await resolveEntry(ctx);
+	const basePath = ctx.commandPath && ctx.commandPath.length > 0 ? `${entry} ${ctx.commandPath.join(" ")}` : entry;
 	messages.push(...loadedCommands.map((cmd) => {
 		let commandStr = cmd.entry ? "" : cmd.name || "";
 		if (commandStr) commandStr += " ";
@@ -449,9 +564,15 @@ async function renderCommandsSection(ctx) {
 	return messages;
 }
 async function makeCommandSymbol(ctx, cmd) {
-	const optionSymbol = await generateOptionsSymbols(ctx, ctx.args);
-	const positionalSymbol = generatePositionalSymbols(ctx.args);
-	let commandStr = cmd.entry ? cmd.name === void 0 || cmd.name === ANONYMOUS_COMMAND_NAME ? "" : `[${cmd.name}]` : cmd.name || "";
+	/**
+	* NOTE(kazupon): the row describes `cmd`, so its symbols come from what `cmd` declares.
+	* A lazy command is described by the definition that is given to `lazy`, since the command
+	* list does not run the loader.
+	*/
+	const args = cmd.args || {};
+	const optionSymbol = await generateOptionsSymbols(ctx, args);
+	const positionalSymbol = generatePositionalSymbols(args);
+	let commandStr = cmd.entry ? cmd.name === void 0 || cmd.name === ANONYMOUS_COMMAND_NAME ? `[${await resolveEntry(ctx)}]` : `[${cmd.name}]` : cmd.name || "";
 	if (optionSymbol) {
 		if (commandStr) commandStr += " ";
 		commandStr += `${optionSymbol}`;
@@ -537,7 +658,11 @@ function hasPositionalArgs(args) {
 */
 function hasAllDefaultOptions(args) {
 	const visibleOptionalArgs = getVisibleOptionalArgs(args);
-	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default);
+	/**
+	* 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);
 }
 /**
 * Generate options symbols for usage
@@ -556,23 +681,32 @@ async function generateOptionsSymbols(ctx, args) {
 * @returns Options pairs for usage
 */
 function getOptionalArgsPairs(ctx) {
+	/**
+	* NOTE(kazupon): an argument owns the name that it renders under, so the negated form of another
+	* option must not be listed under it (#732). The names are compared as they are rendered, because
+	* `toKebab` can bring two different keys under one name (#743). A `hidden` argument counts: it is
+	* not listed, and neither is a negated form that would take its name.
+	*/
+	const optionNames = resolveOptionNames(ctx.args, ctx.toKebab);
 	return getVisibleOptionalArgs(ctx.args).reduce((acc, [name, schema]) => {
+		const displayName = resolveDisplayName(name, schema, ctx.toKebab);
 		let key = makeShortLongOptionPair(schema, name, ctx.toKebab);
-		if (schema.type !== "boolean") {
-			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
-			key = schema.default ? `${key} [${displayName}]` : `${key} <${displayName}>`;
-		}
+		if (schema.type !== "boolean") key = schema.default === void 0 ? `${key} <${displayName}>` : `${key} [${displayName}]`;
 		acc[name] = key;
 		if (schema.type === "boolean" && schema.negatable && !COMMON_ARGS_KEYS.includes(name)) {
-			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
-			acc[`no-${name}`] = `--no-${displayName}`;
+			const negatedName = `no-${displayName}`;
+			if (!optionNames.has(negatedName)) acc[`no-${name}`] = `--${negatedName}`;
 		}
 		return acc;
 	}, Object.create(null));
 }
-const resolveNegatableKey = (key) => key.split("no-")[1];
+const resolveNegatableKey = (key) => key.slice(3);
 function resolveNegatableType(key, ctx) {
-	return ctx.args[key.startsWith("no-") ? resolveNegatableKey(key) : key].type;
+	/**
+	* NOTE(kazupon): the key of an argument wins over the option that a negated form negates, and a
+	* negated form is a boolean flag whether or not the option it negates can be reached from here.
+	*/
+	return (ctx.args[key] ?? ctx.args[resolveNegatableKey(key)])?.type ?? "boolean";
 }
 async function generateDefaultDisplayValue(ctx, schema) {
 	return `${await ctx.extensions[pluginId].text(resolveBuiltInKey("DEFAULT"))}: ${schema.default}`;
@@ -598,21 +732,26 @@ 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]) => value.length));
-	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
+	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));
-		if (!rawDesc && key.startsWith("no-")) {
+		if (!rawDesc && !ctx.args[key] && key.startsWith("no-")) {
+			/**
+			* NOTE(kazupon): only a key that no argument answers to may be read as the negated form of
+			* another option, and only when that option is there to be negated.
+			*/
 			const name = resolveNegatableKey(key);
 			const schema = ctx.args[name];
-			const optionKey = makeShortLongOptionPair(schema, name, ctx.toKebab);
-			rawDesc = `${await ctx.extensions[pluginId].text(resolveBuiltInKey("NEGATABLE"))} ${optionKey}`;
+			if (schema) {
+				const optionKey = makeShortLongOptionPair(schema, name, ctx.toKebab);
+				rawDesc = `${await ctx.extensions[pluginId].text(resolveBuiltInKey("NEGATABLE"))} ${optionKey}`;
+			}
 		}
 		const optionsSchema = ctx.env.usageOptionType ? `[${resolveNegatableType(key, ctx)}] ` : "";
 		const valueDesc = key.startsWith("no-") ? "" : await resolveDisplayValue(ctx, key);
-		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
-		const descLength = desc.length + valueDesc.length;
-		const option = `${value.padEnd((descLength > 0 ? optionsMaxLength : 0) + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
+		const desc = `${optionsSchema ? padEndToWidth(optionsSchema, optionSchemaMaxLength + 3) : ""}${rawDesc}`;
+		const option = `${padEndToWidth(value, (desc.length + valueDesc.length > 0 ? optionsMaxLength : 0) + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
 		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
 	}))).join("\n");
 }
@@ -622,10 +761,10 @@ function getPositionalArgs(args) {
 async function generatePositionalArgsUsage(ctx) {
 	const positionals = getPositionalArgs(ctx.args);
 	if (positionals.length === 0) return "";
-	const argsMaxLength = Math.max(...positionals.map(([name]) => name.length));
+	const argsMaxLength = Math.max(...positionals.map(([name]) => displayWidth(name)));
 	return (await Promise.all(positionals.map(async ([name]) => {
 		const desc = await ctx.extensions[pluginId].text(resolveArgKey(name, ctx.name)) || ctx.args[name].description || "";
-		const arg = `${name.padEnd(argsMaxLength + ctx.env.middleMargin)} ${desc}`;
+		const arg = `${padEndToWidth(name, argsMaxLength + ctx.env.middleMargin)} ${desc}`;
 		return `${arg.padStart(ctx.env.leftMargin + arg.length)}`;
 	}))).join("\n");
 }
@@ -652,6 +791,7 @@ function isRequiredSinglePositionalArg(arg) {
 * @license MIT
 */
 const i18nPluginId$1 = namespacedId("i18n");
+const missingValueHintKey = "err:arg:missing-value:hint";
 /**
 * Render the validation errors.
 *
@@ -669,13 +809,38 @@ async function renderValidationError(ctx, error) {
 		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) 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;
@@ -748,7 +913,10 @@ function renderer() {
 			async function loadCommands() {
 				if (cachedCommands) return cachedCommands;
 				const subCommands = [...ctx.env.subCommands || []];
-				cachedCommands = (await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)))).filter((cmd) => !cmd.internal).filter(Boolean);
+				const allCommands = await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)));
+				const entryCommand = ctx.env.entryCommand;
+				if (ctx.callMode === "entry" && subCommands.length > 0 && entryCommand && !subCommands.some(([, command]) => command === entryCommand)) allCommands.push(await resolveLazyCommand(entryCommand, ANONYMOUS_COMMAND_NAME));
+				cachedCommands = allCommands.filter((cmd) => !cmd.internal).filter(Boolean);
 				cachedCommands.sort((a, b) => {
 					if (a.entry && !b.entry) return -1;
 					if (!a.entry && b.entry) return 1;
@@ -759,9 +927,33 @@ function renderer() {
 				});
 				return cachedCommands;
 			}
+			/**
+			* Resolve the description of a command in the command list.
+			*
+			* NOTE(kazupon): the description is localized the way the command's own help localizes it,
+			* which needs that command's resource. `text()` is bound to the command that is running, so it
+			* cannot answer for another one. The i18n plugin loads a resource into the adapter under the
+			* name of the command it is given, and `translate()` reads it back from there (#748).
+			*
+			* @param target - A command from `loadCommands`
+			* @returns The description to show for the command
+			*/
+			async function localizeCommandDescription(target) {
+				const fallback = target.description || "";
+				if (!i18n || !target.name) return fallback;
+				const commandCtx = await createCommandContext({
+					args: target.args,
+					command: target,
+					callMode: target.entry ? "entry" : "subCommand",
+					extensions: {}
+				});
+				await i18n.loadResource(i18n.locale, commandCtx, target);
+				return await i18n.translate(resolveKey("description", target.name)) || fallback;
+			}
 			return {
 				text: localizable(ctx, cmd, i18n?.translate),
-				loadCommands
+				loadCommands,
+				localizeCommandDescription
 			};
 		},
 		setup: (ctx) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "0.37.3",
+  "version": "1.0.0-beta.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,18 +53,18 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.37.3"
+    "@gunshi/plugin": "1.0.0-beta.1"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "0.37.3"
+    "@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": "0.37.3"
+    "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",