@gunshi/shared 0.26.3 → 0.27.0-alpha.10

package/README.md

@@ -1,8 +1,14 @@
 # `@gunshi/shared`
 
-shared utils for gunshi
+> shared utils for gunshi
 
-TODO(kazupon): more explanation
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!WARNING]
+> Please, don't use this package for your project.
+> This package was made for use with the gunshi plugin.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
 
 ## ©️ License
 

package/lib/index.d.ts

@@ -3,164 +3,201 @@ import en_US_default from "@gunshi/resources/en-US";
 //#region rolldown:runtime
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/parser-FiQIAw-2.d.ts
+//#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
-*/
-/**
-* forked from `nodejs/node` (`pkgjs/parseargs`)
-* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
-* code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
-*
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-/**
-* 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
-*/
-type ArgTokenKind = "option" | "option-terminator" | "positional";
-/**
-* Argument token.
-*/
+ * Entry point of argument parser.
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * 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
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
 interface ArgToken {
   /**
-  * Argument token kind.
-  */
+   * Argument token kind.
+   */
   kind: ArgTokenKind;
   /**
-  * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
-  */
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
   index: number;
   /**
-  * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
-  */
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
   name?: string;
   /**
-  * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
-  */
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
   rawName?: string;
   /**
-  * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
-  * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
-  */
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
   value?: string;
   /**
-  * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
-  */
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
   inlineValue?: boolean;
-} //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
-
+}
 /**
-* Parser Options.
-*/
+ * Parser Options.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-BoS-UnqX.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
+ * 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
+ */
 interface ArgSchema {
   /**
-  * Type of argument.
-  */
-  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
+   * Type of argument.
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
   /**
-  * A single character alias for the argument.
-  */
+   * A single character alias for the argument.
+   */
   short?: string;
   /**
-  * A description of the argument.
-  */
+   * A description of the argument.
+   */
   description?: string;
   /**
-  * Whether the argument is required or not.
-  */
+   * Whether the argument is required or not.
+   */
   required?: true;
   /**
-  * Whether the argument allow multiple values or not.
-  */
+   * Whether the argument allow multiple values or not.
+   */
   multiple?: true;
   /**
-  * Whether the negatable option for `boolean` type
-  */
+   * Whether the negatable option for `boolean` type
+   */
   negatable?: boolean;
   /**
-  * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
-  */
+   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+   */
   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.
-  */
+   * The default value of the argument.
+   * if the type is 'enum', the default value must be one of the allowed values.
+   */
   default?: string | boolean | number;
   /**
-  * Whether to convert the argument name to kebab-case.
-  */
+   * Whether to convert the argument name to kebab-case.
+   */
   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
-  */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   * 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
+   */
   parse?: (value: string) => any;
 }
 /**
-* An object that contains {@link ArgSchema | argument schema}.
-*/
+ * An object that contains {@link ArgSchema | argument schema}.
+ */
 interface Args {
   [option: string]: ArgSchema;
 }
 /**
-* An object that contains the values of the arguments.
-*/
+ * An object that contains the values of the 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;
 };
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
 /**
-* @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;
+ * @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;
 /**
-* @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;
+ * @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;
 /**
-* @internal
-*/
+ * @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] };
 /**
-* @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] };
+ * @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] };
+/**
+ * An arguments for {@link resolveArgs | resolve arguments}.
+ */
 
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ */
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+/**
+ * Resolve 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}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
 //#endregion
 //#region ../gunshi/src/types.d.ts
-/**
-* An arguments for {@link resolveArgs | resolve arguments}.
-*/
 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}.
+ * @since v0.27.0
  */
 type ExtendContext = Record<string, unknown>;
 /**
  * Gunshi unified parameter type.
  * This type combines both argument definitions and command context extensions.
+ * @since v0.27.0
  */
 interface GunshiParams<P extends {
   args?: Args;
@@ -184,11 +221,13 @@ interface GunshiParams<P extends {
 }
 /**
  * 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.
+ * @since v0.27.0
  */
 type GunshiParamsConstraint = GunshiParams<any> | {
   extensions: ExtendContext;
@@ -198,6 +237,11 @@ type GunshiParamsConstraint = GunshiParams<any> | {
  * @internal
  */
 type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
+/**
+ * Type helper to extract explicitly provided argument flags from G
+ * @internal
+ */
+type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs<G>>;
 /**
  * Type helper to extract extensions from G
  * @internal
@@ -285,16 +329,19 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
   /**
    * Hook that runs before any command execution
    * @see {@link 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}
+   * @since v0.27.0
    */
-  onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | void) => Awaitable<void>) | undefined;
+  onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>) | undefined;
   /**
    * Hook that runs when a command throws an error
    * @see {@link CliOptions.onErrorCommand}
+   * @since v0.27.0
    */
   onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
 }
@@ -331,6 +378,15 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    * The command arguments is same {@link Command.args}.
    */
   args: ExtractArgs<G>;
+  /**
+   * Whether arguments were explicitly provided by the user.
+   *
+   * - `true`: The argument was explicitly provided via command line
+   * - `false`: The argument was not explicitly provided. This means either:
+   *   - The value comes from a default value defined in the argument schema
+   *   - The value is `undefined` (no explicit input and no default value)
+   */
+  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}.
@@ -377,7 +433,8 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    */
   log: (message?: any, ...optionalParams: any[]) => void;
   /**
-   *  Command context extensions.
+   * Command context extensions.
+   * @since v0.27.0
    */
   extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
   /**
@@ -388,8 +445,36 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
 }
 /**
  * CommandContextCore type (base type without extensions)
+ * @since v0.27.0
  */
 
+/**
+ * Rendering control options
+ * @since v0.27.0
+ */
+interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Header rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  header?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Usage rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Validation errors rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
+}
 /**
  * Command interface.
  */
@@ -423,6 +508,24 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * If you will set to `true`, All {@link 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.
@@ -453,40 +556,36 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  * @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<void | string>; //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/utils.d.ts
-
+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 src/utils.d.ts
 /**
-* Entry point of utils.
-*
-* Note that this entry point is used by gunshi to import utility functions.
-*
-* @module
-*/
+ * Entry point of utils.
+ *
+ * Note that this entry point is used by gunshi to import utility functions.
+ *
+ * @module
+ */
 /**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
 declare function kebabnize(str: string): string;
-
 //#endregion
-//#region ../gunshi/src/utils.d.ts
 //#endregion
+//#region ../gunshi/src/utils.d.ts
 declare function isLazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: unknown): cmd is LazyCommand<G>;
 declare function resolveLazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: Commandable<G>, name?: string | undefined, needRunResolving?: boolean): Promise<Command<G>>;
 declare function create<T>(obj?: object | null): T;
 declare function log(...args: unknown[]): void;
 declare function deepFreeze<T extends Record<string, any>>(obj: T, ignores?: string[]): Readonly<T>;
-
-//#endregion
-//#region src/constants.d.ts
 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 };
 }
@@ -515,7 +614,6 @@ 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"];
-
 //#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] };
@@ -537,26 +635,88 @@ type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
  */
 type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
 /**
- * i18n built-in resource keys.
+ * Built-in resource keys.
  */
 type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
 /**
- * Command i18n built-in keys.
- * The command i18n built-in keys are used by the i18n plugin for translation.
+ * Command built-in keys.
  */
-type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys> | 'description' | 'examples';
+type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
 /**
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
  */
-type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
-
+type CommandArgKeys<A extends Args, C = {}, K extends string = GenerateNamespacedKey<Extract<KeyOfArgs<RemovedIndex<A>>, string>, typeof ARG_PREFIX>> = C extends {
+  name: infer N;
+} ? (N extends string ? GenerateNamespacedKey<K, N> : K) : K;
+/**
+ * Resolve translation keys for command context.
+ */
+type ResolveTranslationKeys<A extends Args, 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>> = CommandBuiltinKeys | O | T;
+/**
+ * Translation function interface
+ */
+interface Translation<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+K = ResolveTranslationKeys<A, C, E>> {
+  (key: K, values?: Record<string, unknown>): string;
+}
+//#endregion
+//#region src/localization.d.ts
+interface Localization<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {}> {
+  <K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>): 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
+ * @returns Localizable function
+ */
+declare function localizable<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
 //#endregion
 //#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.
+ * @returns Prefixed built-in key.
+ */
 declare function resolveBuiltInKey<K extends string = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
-declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K): GenerateNamespacedKey<K, typeof ARG_PREFIX>;
+/**
+ * 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.
+ * @returns Prefixed argument key.
+ */
+declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, ctx?: Readonly<CommandContext>): 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.
+ * @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 resolveExamples<G extends GunshiParamsConstraint = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>, examples?: string | CommandExamplesFetcher<G>): Promise<string>;
 declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K, typeof PLUGIN_PREFIX>;
-
+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, PLUGIN_PREFIX, RemovedIndex, create, deepFreeze, isLazyCommand, kebabnize, log, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, 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, 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.20.1/node_modules/args-tokens/lib/utils-N7UlhLbz.js
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/utils-N7UlhLbz.js
 /**
 * Entry point of utils.
 *
@@ -26,7 +26,9 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			name: cmd.commandName,
 			description: cmd.description,
 			args: cmd.args,
-			examples: cmd.examples
+			examples: cmd.examples,
+			internal: cmd.internal,
+			entry: cmd.entry
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
 		command = Object.assign(create(), baseCommand);
@@ -40,6 +42,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 				command.description = loaded.description;
 				command.args = loaded.args;
 				command.examples = loaded.examples;
+				command.internal = loaded.internal;
+				command.entry = loaded.entry;
 				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
 			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
 		}
@@ -135,11 +139,35 @@ var en_US_default = {
 
 //#endregion
 //#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.
+* @returns Prefixed built-in key.
+*/
 function resolveBuiltInKey(key) {
 	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
-function resolveArgKey(key) {
-	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${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.
+* @returns Prefixed argument key.
+*/
+function resolveArgKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.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.
+* @returns Prefixed non-built-in key.
+*/
+function resolveKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
 }
 async function resolveExamples(ctx, examples) {
 	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
@@ -147,6 +175,48 @@ async function resolveExamples(ctx, examples) {
 function namespacedId(id) {
 	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
 }
+function makeShortLongOptionPair(schema, name, toKebab) {
+	const displayName = toKebab || schema.toKebab ? kebabnize(name) : name;
+	let key = `--${displayName}`;
+	if (schema.short) key = `-${schema.short}, ${key}`;
+	return key;
+}
+
+//#endregion
+//#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
+* @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(namaspacedArgKey)) {
+			let argKey = key.slice(namaspacedArgKey.length);
+			let negatable = false;
+			if (argKey.startsWith(ARG_NEGATABLE_PREFIX)) {
+				argKey = argKey.slice(ARG_NEGATABLE_PREFIX.length);
+				negatable = true;
+			}
+			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 || "";
+		}
+		if (key === resolveKey("description", ctx)) return "";
+		else if (key === resolveKey("examples", ctx)) return await resolveExamples(ctx, cmd.examples);
+		else return key;
+	}
+	return localize;
+}
 
 //#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, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, isLazyCommand, kebabnize, log, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, 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, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/package.json

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