@gunshi/shared 0.27.0-alpha.9 → 0.27.0-beta.0

package/lib/index.d.ts

@@ -1,12 +1,11 @@
 import en_US_default from "@gunshi/resources/en-US";
 
-//#region rolldown:runtime
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/parser-C6MbpZjd.d.ts
 
-//#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/parser-Cbxholql.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
+ *
  * @module
  */
 /**
@@ -19,6 +18,7 @@ import en_US_default from "@gunshi/resources/en-US";
  */
 /**
  * Argument token Kind.
+ *
  * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
  * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
  * - `positional`: positional token
@@ -58,91 +58,462 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-BoS-UnqX.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/resolver-D64nGlCD.d.ts
 //#region src/resolver.d.ts
 
 /**
- * An argument schema
- * This schema is similar to the schema of the `node:utils`.
- * difference is that:
- * - `required` property and `description` property are added
- * - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
- * - `default` property type, not support multiple types
+ * 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` and `description` 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 argument.
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   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';
   /**
-   * A single character alias for the argument.
+   * 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;
   /**
-   * A description of the argument.
+   * 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;
   /**
-   * Whether the argument is required or not.
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user.
+   * If missing, an `ArgResolveError` with type 'required' will be thrown.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @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?: true;
   /**
-   * Whether the argument allow multiple values or not.
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array.
+   * For options: can be specified multiple times (--tag foo --tag bar)
+   * For positional: collects remaining 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;
   /**
-   * Whether the negatable option for `boolean` type
+   * 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.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
    */
   negatable?: boolean;
   /**
-   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * 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[];
   /**
-   * The default value of the argument.
-   * if the type is 'enum', the default value must be one of the allowed values.
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @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;
   /**
-   * Whether to convert the argument name to kebab-case.
+   * 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.
+   *
+   * Can be overridden globally with `resolveArgs({ 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;
   /**
-   * A function to parse the value of the argument. if the type is 'custom', this function is required.
-   * If argument value will be invalid, this function have to throw an error.
-   * @param value
-   * @returns Parsed value
-   * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * 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 will throw 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[];
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws 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 {
   [option: string]: ArgSchema;
 }
 /**
  * An object that contains the values of the arguments.
+ *
+ * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
  */
 type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
   [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
 };
 type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
 /**
+ * Extracts the value type from the argument schema.
+ *
+ * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
+ *
  * @internal
  */
 type ExtractOptionValue<A extends ArgSchema> = A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? IsFunction<A['parse']> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A['parse']>>> : never : ResolveOptionValue<A, string | boolean | number>;
 type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
 /**
+ * Resolved argument values.
+ *
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
  * @internal
  */
 type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
 /**
+ * Filters the arguments based on their default values.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
+ *
  * @internal
  */
 type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
 /**
+ * Filters positional arguments from the argument schema.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
  * @internal
  */
 type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
@@ -155,10 +526,15 @@ type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> =
  *
  * Each property indicates whether the corresponding argument was explicitly
  * provided (true) or is using a default value or not provided (false).
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
  */
 type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
 /**
  * Resolve command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ *
  * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
  * @param tokens - An array of {@link ArgToken | tokens}.
  * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
@@ -188,15 +564,25 @@ type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
  */
 //#endregion
 //#region ../gunshi/src/types.d.ts
+/**
+ * Awaitable type.
+ *
+ * @typeParam T - The type of the value that can be awaited.
+ */
 type Awaitable<T> = T | Promise<T>;
 /**
- * Extend command context type. This type is used to extend the command context with additional properties at {@link CommandContext.extensions}.
+ * Extend command context type. This type is used to extend the command context with additional properties at {@linkcode CommandContext.extensions}.
+ *
  * @since v0.27.0
  */
 type ExtendContext = Record<string, unknown>;
 /**
  * Gunshi unified parameter type.
+ *
  * This type combines both argument definitions and command context extensions.
+ *
+ * @typeParam P - The type of parameters, which can include `args` and `extensions`.
+ *
  * @since v0.27.0
  */
 interface GunshiParams<P extends {
@@ -207,111 +593,131 @@ interface GunshiParams<P extends {
   extensions: {};
 }> {
   /**
-   * Command argument definitions
+   * Command argument definitions.
    */
   args: P extends {
     args: infer A extends Args;
   } ? A : Args;
   /**
-   * Command context extensions
+   * Command context extensions.
    */
   extensions: P extends {
     extensions: infer E extends ExtendContext;
   } ? E : {};
 }
 /**
- * Default Gunshi parameters
+ * Default Gunshi parameters.
+ *
  * @since v0.27.0
  */
 type DefaultGunshiParams = GunshiParams;
 /**
  * Generic constraint for command-related types.
- * This type constraint allows both GunshiParams and objects with extensions.
+ *
+ * This type constraint allows both {@linkcode GunshiParams} and objects with extensions.
+ *
  * @since v0.27.0
  */
 type GunshiParamsConstraint = GunshiParams<any> | {
+  args: Args;
+} | {
   extensions: ExtendContext;
 };
 /**
- * Type helper to extract args from G
+ * Type helper to extract args
+ *
+ * @typeParam G - The type of {@linkcode GunshiParams} or an object with {@linkcode Args}.
+ *
  * @internal
  */
-type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
+type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : G extends {
+  args: infer A extends Args;
+} ? A : Args;
 /**
- * Type helper to extract explicitly provided argument flags from G
+ * Type helper to extract explicitly provided argument flags.
+ *
+ * @typeParam G - The type of {@linkcode GunshiParams}.
+ *
  * @internal
  */
 type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs<G>>;
 /**
  * Type helper to extract extensions from G
+ *
  * @internal
  */
 type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
   extensions: infer E;
 } ? E : {};
-/**
- * Type helper to normalize G to GunshiParams
- * @internal
- */
-
 /**
  * Command environment.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command environments.
  */
 interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Current working directory.
-   * @see {@link CliOptions.cwd}
+   *
+   * @see {@linkcode CliOptions.cwd}
    */
   cwd: string | undefined;
   /**
    * Command name.
-   * @see {@link CliOptions.name}
+   *
+   * @see {@linkcode CliOptions.name}
    */
   name: string | undefined;
   /**
    * Command description.
-   * @see {@link CliOptions.description}
    *
+   * @see {@linkcode CliOptions.description}
    */
   description: string | undefined;
   /**
    * Command version.
-   * @see {@link CliOptions.version}
+   *
+   * @see {@linkcode CliOptions.version}
    */
   version: string | undefined;
   /**
    * Left margin of the command output.
+   *
    * @default 2
-   * @see {@link CliOptions.leftMargin}
+   * @see {@linkcode CliOptions.leftMargin}
    */
   leftMargin: number;
   /**
    * Middle margin of the command output.
+   *
    * @default 10
-   * @see {@link CliOptions.middleMargin}
+   * @see {@linkcode CliOptions.middleMargin}
    */
   middleMargin: number;
   /**
    * Whether to display the usage option type.
+   *
    * @default false
-   * @see {@link CliOptions.usageOptionType}
+   * @see {@linkcode CliOptions.usageOptionType}
    */
   usageOptionType: boolean;
   /**
    * Whether to display the option value.
+   *
    * @default true
-   * @see {@link CliOptions.usageOptionValue}
+   * @see {@linkcode CliOptions.usageOptionValue}
    */
   usageOptionValue: boolean;
   /**
    * Whether to display the command usage.
+   *
    * @default false
-   * @see {@link CliOptions.usageSilent}
+   * @see {@linkcode CliOptions.usageSilent}
    */
   usageSilent: boolean;
   /**
    * Sub commands.
-   * @see {@link CliOptions.subCommands}
+   *
+   * @see {@linkcode CliOptions.subCommands}
    */
   subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
   /**
@@ -328,54 +734,59 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
   renderValidationErrors: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null | undefined;
   /**
    * Hook that runs before any command execution
-   * @see {@link CliOptions.onBeforeCommand}
+   *
+   * @see {@linkcode CliOptions.onBeforeCommand}
    * @since v0.27.0
    */
   onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
   /**
    * Hook that runs after successful command execution
-   * @see {@link CliOptions.onAfterCommand}
+   *
+   * @see {@linkcode CliOptions.onAfterCommand}
    * @since v0.27.0
    */
   onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>) | undefined;
   /**
    * Hook that runs when a command throws an error
-   * @see {@link CliOptions.onErrorCommand}
+   *
+   * @see {@linkcode CliOptions.onErrorCommand}
    * @since v0.27.0
    */
   onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
 }
-/**
- * CLI options of `cli` function.
- */
-
 /**
  * Command call mode.
+ *
+ * - `entry`: The command is executed as an entry command.
+ * - `subCommand`: The command is executed as a sub-command.
  */
 type CommandCallMode = 'entry' | 'subCommand' | 'unexpected';
 /**
  * Command context.
+ *
  * Command context is the context of the command execution.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  */
 interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Command name, that is the command that is executed.
-   * The command name is same {@link CommandEnvironment.name}.
+   * The command name is same {@linkcode CommandEnvironment.name}.
    */
   name: string | undefined;
   /**
    * Command description, that is the description of the command that is executed.
-   * The command description is same {@link CommandEnvironment.description}.
+   * The command description is same {@linkcode CommandEnvironment.description}.
    */
   description: string | undefined;
   /**
    * Command environment, that is the environment of the command that is executed.
-   * The command environment is same {@link CommandEnvironment}.
+   * The command environment is same {@linkcode CommandEnvironment}.
    */
   env: Readonly<CommandEnvironment<G>>;
   /**
    * Command arguments, that is the arguments of the command that is executed.
-   * The command arguments is same {@link Command.args}.
+   * The command arguments is same {@linkcode Command.args}.
    */
   args: ExtractArgs<G>;
   /**
@@ -389,7 +800,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   explicit: ExtractArgExplicitlyProvided<G>;
   /**
    * Command values, that is the values of the command that is executed.
-   * Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
+   * Resolve values with `resolveArgs` from command arguments and {@linkcode Command.args}.
    */
   values: ArgValues<ExtractArgs<G>>;
   /**
@@ -421,35 +832,35 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   callMode: CommandCallMode;
   /**
    * Whether to convert the camel-case style argument name to kebab-case.
-   * This context value is set from {@link Command.toKebab} option.
+   * This context value is set from {@linkcode Command.toKebab} option.
    */
   toKebab?: boolean;
   /**
    * Output a message.
-   * If {@link CommandEnvironment.usageSilent} is true, the message is not output.
-   * @param message an output message, @see {@link console.log}
-   * @param optionalParams an optional parameters, @see {@link console.log}
-   * @internal
+   *
+   * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
+   *
+   * @param message - an output message, see {@linkcode console.log}
+   * @param optionalParams - an optional parameters, see {@linkcode console.log}
    */
   log: (message?: any, ...optionalParams: any[]) => void;
   /**
    * Command context extensions.
+   *
    * @since v0.27.0
    */
-  extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
+  extensions: keyof ExtractExtensions<G> extends never ? any : ExtractExtensions<G>;
   /**
    * Validation error from argument parsing.
    * This will be set if argument validation fails during CLI execution.
    */
   validationError?: AggregateError;
 }
-/**
- * CommandContextCore type (base type without extensions)
- * @since v0.27.0
- */
-
 /**
  * Rendering control options
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of render options.
+ *
  * @since v0.27.0
  */
 interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
@@ -477,6 +888,8 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
 }
 /**
  * Command interface.
+ *
+ * @typeParam G - The Gunshi parameters constraint
  */
 interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
@@ -505,66 +918,77 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   run?: CommandRunner<G>;
   /**
    * Whether to convert the camel-case style argument name to kebab-case.
-   * If you will set to `true`, All {@link Command.args} names will be converted to kebab-case.
+   * If you will set to `true`, All {@linkcode Command.args} names will be converted to kebab-case.
    */
   toKebab?: boolean;
   /**
    * Whether this is an internal command.
    * Internal commands are not shown in help usage.
+   *
    * @default false
    * @since v0.27.0
    */
   internal?: boolean;
   /**
    * Whether this command is an entry command.
+   *
    * @default undefined
    * @since v0.27.0
    */
   entry?: boolean;
   /**
    * Rendering control options
+   *
    * @since v0.27.0
    */
   rendering?: RenderingOptions<G>;
 }
 /**
  * Lazy command interface.
+ *
  * Lazy command that's not loaded until it is executed.
+ *
+ * @typeParam G - The Gunshi parameters constraint
+ * @typeParam D - The partial command definition provided to lazy function
  */
-type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
+type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = {}> = {
   /**
    * Command load function
    */
   (): Awaitable<Command<G> | CommandRunner<G>>;
-  /**
-   * Command name
-   */
+} & (D extends {
+  name: infer N;
+} ? {
+  commandName: N;
+} : {
   commandName?: string;
-} & Omit<Command<G>, 'run' | 'name'>;
+}) & Omit<D, 'name' | 'run'> & Partial<Omit<Command<G>, keyof D | 'run' | 'name'>>;
 /**
  * Define a command type.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
  */
-type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G>;
+type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
 /**
  * Command examples fetcher.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param ctx - A {@link CommandContext | command context}
  * @returns A fetched command examples.
  */
 type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
 /**
  * Command runner.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @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)
  */
 type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
-/**
- * Command loader.
- * A function that returns a command or command runner.
- * This is used to lazily load commands.
- * @returns A command or command runner
- */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/utils.d.ts
 //#region src/utils.d.ts
 /**
  * Entry point of utils.
@@ -577,18 +1001,57 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
  */
+/**
+ * Convert a string to kebab-case.
+ *
+ * @param str - A string to convert
+ * @returns Converted string into kebab-case.
+ */
 declare function kebabnize(str: string): string;
 //#endregion
 //#endregion
 //#region ../gunshi/src/utils.d.ts
+/**
+ * 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
+ */
 declare function isLazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: unknown): cmd is LazyCommand<G>;
+/**
+ * Resolve a lazy command to a {@link Command}.
+ *
+ * @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.
+ * @returns A resolved {@link Command}
+ */
 declare function resolveLazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: Commandable<G>, name?: string | undefined, needRunResolving?: boolean): Promise<Command<G>>;
+/**
+ * Create an object with the specified prototype. A shorthand for `Object.create`.
+ *
+ * @param obj - An object to use as the prototype for the new object. If `null`, it will create an object with no prototype.
+ * @returns A new object with the specified prototype
+ */
 declare function create<T>(obj?: object | null): T;
+/**
+ * Log a message to the console.
+ *
+ * @param args - Arguments to log
+ */
 declare function log(...args: unknown[]): void;
-declare function deepFreeze<T extends Record<string, any>>(obj: T, ignores?: string[]): Readonly<T>;
-declare namespace constants_d_exports {
-  export { 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, COMMON_ARGS, PLUGIN_PREFIX };
-}
+/**
+ * Deep freeze an object, making it immutable.
+ *
+ * @param obj - The object to freeze
+ * @param ignores - Properties to ignore during freezing
+ * @returns A frozen object
+ */
+declare function deepFreeze<T extends Record<string, any>>(
+// eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type for deepFreeze
+obj: T, ignores?: string[]): Readonly<T>;
+//#endregion
+//#region src/constants.d.ts
 /**
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
@@ -617,10 +1080,17 @@ declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBC
 //#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] };
+/**
+ * Make all properties in T deeply writeable (not readonly)
+ */
+type DeepWriteable<T> = T extends ((...args: any) => any) ? T : T extends readonly (infer U)[] ? DeepWriteable<U>[] : T extends object ? { -readonly [P in keyof T]: DeepWriteable<T[P]> } : T;
 /**
  * Remove index signature from object or record type.
  */
 type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+/**
+ * Resolve a key on {@link Args}.
+ */
 type KeyOfArgs<A extends Args> = 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.
@@ -629,11 +1099,11 @@ type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof
 /**
  * Command i18n built-in arguments keys.
  */
-type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
+type CommandBuiltinArgsKeys = keyof typeof COMMON_ARGS;
 /**
  * Command i18n built-in resource keys.
  */
-type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
+type CommandBuiltinResourceKeys = (typeof COMMAND_BUILTIN_RESOURCE_KEYS)[number];
 /**
  * Built-in resource keys.
  */
@@ -671,6 +1141,13 @@ K = ResolveTranslationKeys<A, C, E>> {
 }
 //#endregion
 //#region src/localization.d.ts
+/**
+ * Localization function type.
+ *
+ * @typeParam A - The {@linkcode Args} type extracted from Gunshi command.
+ * @typeParam C - Additional context type for command localization.
+ * @typeParam E - Extended resource keys type.
+ */
 interface Localization<A extends Args, C = {},
 // for CommandContext
 E extends Record<string, string> = {}> {
@@ -678,10 +1155,16 @@ E extends Record<string, string> = {}> {
 }
 /**
  * Create a localizable function for a command.
+ *
  * This function will resolve the translation key based on the command context and the provided translation function.
- * @param ctx Command context
- * @param cmd Command
- * @param translate Translation function
+ *
+ * @typeParam A - The {@linkcode Args} type extracted from Gunshi command.
+ * @typeParam C - Additional context type for command localization.
+ * @typeParam E - Extended resource keys type.
+ *
+ * @param ctx - Command context
+ * @param cmd - Command
+ * @param translate - Translation function
  * @returns Localizable function
  */
 declare function localizable<A extends Args, C = {},
@@ -693,30 +1176,67 @@ K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translat
 //#region src/utils.d.ts
 /**
  * Resolve a namespaced key for built-in resources.
+ *
  * Built-in keys are prefixed with "_:".
- * @param key The built-in key to resolve.
+ *
+ * @typeParam K - The type of the built-in key to resolve. Defaults to command built-in argument and resource keys.
+ *
+ * @param key - The built-in key to resolve.
  * @returns Prefixed built-in key.
  */
-declare function resolveBuiltInKey<K extends string = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
+declare function resolveBuiltInKey<K extends string = CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
 /**
  * Resolve a namespaced key for argument resources.
+ *
  * Argument keys are prefixed with "arg:".
  * If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
- * @param key The argument key to resolve.
- * @param ctx The command context.
+ *
+ * @typeParam A - The {@linkcode Args} type extracted from G
+ *
+ * @param key - The argument key to resolve.
+ * @param name - The command name.
  * @returns Prefixed argument key.
  */
-declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, ctx?: Readonly<CommandContext>): string;
+declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, name?: string): string;
 /**
  * Resolve a namespaced key for non-built-in resources.
+ *
  * Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
- * @param key The non-built-in key to resolve.
- * @param ctx The command context.
+ *
+ * @typeParam T - The type of the non-built-in key to resolve. Defaults to string.
+ *
+ * @param key - The non-built-in key to resolve.
+ * @param name - The command name.
  * @returns Prefixed non-built-in key.
  */
-declare function resolveKey<T extends Record<string, string> = {}, K = (keyof T extends string ? keyof T : string)>(key: K, ctx?: Readonly<CommandContext>): string;
+declare function resolveKey<T extends Record<string, string> = {}, K = (keyof T extends string ? keyof T : string)>(key: K, name?: string): string;
+/**
+ * Resolve command examples.
+ *
+ * @typeParam G - Type parameter extending {@linkcode GunshiParams}
+ *
+ * @param ctx - A {@linkcode CommandContext | command context}.
+ * @param examples - The examples to resolve, which can be a string or a {@linkcode CommandExamplesFetcher | function} that returns a string.
+ * @returns A resolved string of examples.
+ */
 declare function resolveExamples<G extends GunshiParamsConstraint = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>, examples?: string | CommandExamplesFetcher<G>): Promise<string>;
+/**
+ * Generate a namespaced key for a plugin.
+ *
+ * @typeParam K - The type of the plugin id to generate a namespaced key for.
+ *
+ * @param id - A plugin id to generate a namespaced key.
+ * @returns A namespaced key for the plugin.
+ */
 declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K, typeof PLUGIN_PREFIX>;
+/**
+ * Generate a short and long option pair for command arguments.
+ *
+ * @param schema - The {@linkcode ArgSchema | argument schema} to generate the option pair.
+ * @param name - The name of the argument.
+ * @param toKebab - Whether to convert the name to kebab-case for display in help text.
+ * @returns A string representing the short and long option pair.
+ */
 declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKebab?: boolean): string;
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, en_US_default as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, DeepWriteable, en_US_default as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/utils-N7UlhLbz.js
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/utils-1LQrGCWG.js
 /**
 * Entry point of utils.
 *
@@ -10,15 +10,35 @@
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+/**
+* Convert a string to kebab-case.
+*
+* @param str - A string to convert
+* @returns Converted string into kebab-case.
+*/
 function kebabnize(str) {
 	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
 }
 
 //#endregion
 //#region ../gunshi/src/utils.ts
+/**
+* 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
+*/
 function isLazyCommand(cmd) {
 	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
 }
+/**
+* Resolve a lazy command to a {@link Command}.
+*
+* @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.
+* @returns A resolved {@link Command}
+*/
 async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 	let command;
 	if (isLazyCommand(cmd)) {
@@ -51,12 +71,30 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 	if (command.name == null && name) command.name = name;
 	return deepFreeze(command);
 }
+/**
+* Create an object with the specified prototype. A shorthand for `Object.create`.
+*
+* @param obj - An object to use as the prototype for the new object. If `null`, it will create an object with no prototype.
+* @returns A new object with the specified prototype
+*/
 function create(obj = null) {
 	return Object.create(obj);
 }
+/**
+* Log a message to the console.
+*
+* @param args - Arguments to log
+*/
 function log(...args) {
 	console.log(...args);
 }
+/**
+* Deep freeze an object, making it immutable.
+*
+* @param obj - The object to freeze
+* @param ignores - Properties to ignore during freezing
+* @returns A frozen object
+*/
 function deepFreeze(obj, ignores = []) {
 	if (obj === null || typeof obj !== "object") return obj;
 	for (const key of Object.keys(obj)) {
@@ -141,8 +179,12 @@ var en_US_default = {
 //#region src/utils.ts
 /**
 * Resolve a namespaced key for built-in resources.
+*
 * Built-in keys are prefixed with "_:".
-* @param key The built-in key to resolve.
+*
+* @typeParam K - The type of the built-in key to resolve. Defaults to command built-in argument and resource keys.
+*
+* @param key - The built-in key to resolve.
 * @returns Prefixed built-in key.
 */
 function resolveBuiltInKey(key) {
@@ -150,34 +192,66 @@ function resolveBuiltInKey(key) {
 }
 /**
 * Resolve a namespaced key for argument resources.
+*
 * Argument keys are prefixed with "arg:".
 * If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
-* @param key The argument key to resolve.
-* @param ctx The command context.
+*
+* @typeParam A - The {@linkcode Args} type extracted from G
+*
+* @param key - The argument key to resolve.
+* @param name - The command name.
 * @returns Prefixed argument key.
 */
-function resolveArgKey(key, ctx) {
-	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+function resolveArgKey(key, name) {
+	return `${name ? `${name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
 /**
 * Resolve a namespaced key for non-built-in resources.
+*
 * Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
-* @param key The non-built-in key to resolve.
-* @param ctx The command context.
+*
+* @typeParam T - The type of the non-built-in key to resolve. Defaults to string.
+*
+* @param key - The non-built-in key to resolve.
+* @param name - The command name.
 * @returns Prefixed non-built-in key.
 */
-function resolveKey(key, ctx) {
-	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
+function resolveKey(key, name) {
+	return `${name ? `${name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
 }
+/**
+* Resolve command examples.
+*
+* @typeParam G - Type parameter extending {@linkcode GunshiParams}
+*
+* @param ctx - A {@linkcode CommandContext | command context}.
+* @param examples - The examples to resolve, which can be a string or a {@linkcode CommandExamplesFetcher | function} that returns a string.
+* @returns A resolved string of examples.
+*/
 async function resolveExamples(ctx, examples) {
 	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
 }
+/**
+* Generate a namespaced key for a plugin.
+*
+* @typeParam K - The type of the plugin id to generate a namespaced key for.
+*
+* @param id - A plugin id to generate a namespaced key.
+* @returns A namespaced key for the plugin.
+*/
 function namespacedId(id) {
 	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
 }
+/**
+* Generate a short and long option pair for command arguments.
+*
+* @param schema - The {@linkcode ArgSchema | argument schema} to generate the option pair.
+* @param name - The name of the argument.
+* @param toKebab - Whether to convert the name to kebab-case for display in help text.
+* @returns A string representing the short and long option pair.
+*/
 function makeShortLongOptionPair(schema, name, toKebab) {
-	const displayName = toKebab || schema.toKebab ? kebabnize(name) : name;
-	let key = `--${displayName}`;
+	let key = `--${toKebab || schema.toKebab ? kebabnize(name) : name}`;
 	if (schema.short) key = `-${schema.short}, ${key}`;
 	return key;
 }
@@ -186,20 +260,23 @@ function makeShortLongOptionPair(schema, name, toKebab) {
 //#region src/localization.ts
 /**
 * Create a localizable function for a command.
+*
 * This function will resolve the translation key based on the command context and the provided translation function.
-* @param ctx Command context
-* @param cmd Command
-* @param translate Translation function
+*
+* @typeParam A - The {@linkcode Args} type extracted from Gunshi command.
+* @typeParam C - Additional context type for command localization.
+* @typeParam E - Extended resource keys type.
+*
+* @param ctx - Command context
+* @param cmd - Command
+* @param translate - Translation function
 * @returns Localizable function
 */
 function localizable(ctx, cmd, translate) {
 	async function localize(key, values) {
 		if (translate) return translate(key, values);
-		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) {
-			const resKey = key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length);
-			return en_US_default[resKey] || key;
-		}
-		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx);
+		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) return en_US_default[key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length)] || key;
+		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
 			let argKey = key.slice(namaspacedArgKey.length);
 			let negatable = false;
@@ -211,8 +288,8 @@ function localizable(ctx, cmd, translate) {
 			if (!schema) return argKey;
 			return negatable && schema.type === "boolean" && schema.negatable ? `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, argKey, ctx.toKebab)}` : schema.description || "";
 		}
-		if (key === resolveKey("description", ctx)) return "";
-		else if (key === resolveKey("examples", ctx)) return await resolveExamples(ctx, cmd.examples);
+		if (key === resolveKey("description", ctx.name)) return "";
+		else if (key === resolveKey("examples", ctx.name)) return await resolveExamples(ctx, cmd.examples);
 		else return key;
 	}
 	return localize;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "0.27.0-alpha.9",
+  "version": "0.27.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -50,13 +50,13 @@
     }
   },
   "devDependencies": {
-    "deno": "^2.4.2",
+    "deno": "^2.5.4",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
-    "publint": "^0.3.12",
-    "tsdown": "^0.13.0",
-    "@gunshi/resources": "0.27.0-alpha.9",
-    "gunshi": "0.27.0-alpha.9"
+    "publint": "^0.3.14",
+    "tsdown": "^0.15.6",
+    "@gunshi/resources": "0.27.0-beta.0",
+    "gunshi": "0.27.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",