@gunshi/plugin-renderer 0.27.0-alpha.9 → 0.27.0-beta.0

package/README.md

@@ -1,5 +1,9 @@
 # @gunshi/plugin-renderer
 
+[![Version][npm-version-src]][npm-version-href]
+[![InstallSize][install-size-src]][install-size-src]
+[![JSR][jsr-src]][jsr-href]
+
 > 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.
@@ -26,8 +30,8 @@ bun add @gunshi/plugin-renderer
 ## 🚀 Usage
 
 ```ts
-import renderer from '@gunshi/plugin-renderer'
 import { cli, define } from 'gunshi'
+import renderer from '@gunshi/plugin-renderer'
 
 const command = define({
   name: 'deploy',
@@ -80,7 +84,7 @@ This plugin automatically handles rendering for:
 
 The plugin provides smart text rendering with automatic fallback:
 
-- **With i18n plugin**: Uses translations from the i18n plugin
+- **With i18n plugin**: Uses translations from the `@gunshi/plugin-i18n`
 - **Without i18n plugin**: Falls back to default English messages and descriptions
 
 ### Rendered Example
@@ -130,8 +134,8 @@ Available extensions:
 ### Usage Example
 
 ```ts
-import renderer from '@gunshi/plugin-renderer'
 import { cli, define } from 'gunshi'
+import renderer, { pluginId as rendererId } from '@gunshi/plugin-renderer'
 
 const deploy = define({
   name: 'deploy',
@@ -153,7 +157,7 @@ const entry = define({
   name: 'tools',
   run: async ctx => {
     // Access renderer extensions
-    const { text, loadCommands } = ctx.extensions['g:renderer']
+    const { text, loadCommands } = ctx.extensions[rendererId]
 
     // Render built-in message
     const usageHeader = await text('_:USAGE') // "USAGE" or translated
@@ -191,58 +195,21 @@ await cli(process.argv.slice(2), command, {
 
 ### Integration with i18n Plugin
 
-The renderer plugin has an optional dependency on the i18n plugin. When both plugins are used together, all rendered text automatically uses translations:
+The renderer plugin has an optional dependency on the `@gunshi/plugin-i18n`. When both plugins are used together, all rendered text automatically uses translations:
 
 ```ts
-import renderer from '@gunshi/plugin-renderer'
-import i18n from '@gunshi/plugin-i18n'
-import resources from '@gunshi/resources'
 import { cli } from 'gunshi'
-
-await cli(args, command, {
-  plugins: [
-    i18n({
-      locale: 'ja-JP',
-      resources // Uses built-in resources from @gunshi/resources
-    }),
-    renderer() // Will use Japanese translations
-  ]
-})
-```
-
-#### With Custom Resources
-
-You can extend the built-in resources with your own translations:
-
-```ts
 import renderer from '@gunshi/plugin-renderer'
 import i18n from '@gunshi/plugin-i18n'
 import resources from '@gunshi/resources'
-import { cli } from 'gunshi'
-
-// Extend built-in resources with custom messages
-const customResources = {
-  'en-US': {
-    ...resources['en-US'],
-    // Custom messages for your app
-    APP_WELCOME: 'Welcome to My CLI Tool!',
-    APP_PROCESSING: 'Processing your request...'
-  },
-  'ja-JP': {
-    ...resources['ja-JP'],
-    // Custom messages in Japanese
-    APP_WELCOME: '私のCLIツールへようこそ！',
-    APP_PROCESSING: 'リクエストを処理しています...'
-  }
-}
 
 await cli(args, command, {
   plugins: [
     i18n({
       locale: 'ja-JP',
-      resources: customResources
+      resources // Uses built-in resources from `@gunshi/resources`
     }),
-    renderer() // Will use Japanese translations including custom messages
+    renderer() // Will use Japanese translations
   ]
 })
 ```
@@ -286,4 +253,12 @@ See the [API References](./docs/index.md)
 
 ## ©️ License
 
-[MIT](http://opensource.org/licenses/MIT)T)
+[MIT](http://opensource.org/licenses/MIT)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/@gunshi/plugin-renderer?style=flat
+[npm-version-href]: https://npmjs.com/package/@gunshi/plugin-renderer@alpha
+[jsr-src]: https://jsr.io/badges/@gunshi/plugin-renderer
+[jsr-href]: https://jsr.io/@gunshi/plugin-renderer
+[install-size-src]: https://pkg-size.dev/badge/install/101075

package/lib/index.d.ts

@@ -1,10 +1,11 @@
 import { Args, Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
 import { Args as Args$1 } from "args-tokens";
 
-//#region rolldown:runtime
-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 };
-}
+//#region ../shared/src/constants.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 /**
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
@@ -13,9 +14,6 @@ declare const BUILT_IN_PREFIX = "_";
 declare const PLUGIN_PREFIX = "g";
 declare const ARG_PREFIX = "arg";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
-declare const BUILD_IN_PREFIX_AND_KEY_SEPARATOR: string;
-declare const ARG_PREFIX_AND_KEY_SEPARATOR: string;
-declare const ARG_NEGATABLE_PREFIX = "no-";
 type CommonArgType = {
   readonly help: {
     readonly type: 'boolean';
@@ -33,10 +31,17 @@ declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBC
 //#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)
+ */
+
 /**
  * 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$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.
@@ -45,11 +50,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.
  */
@@ -75,18 +80,33 @@ E extends Record<string, string> = {},
 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
- */
 //#endregion
 //#region src/types.d.ts
+/**
+ * The unique identifier for usage renderer plugin.
+ */
+declare const pluginId: GenerateNamespacedKey<'renderer', typeof PLUGIN_PREFIX>;
+/**
+ * Type representing the unique identifier for usage renderer plugin.
+ */
+type PluginId = typeof pluginId;
 /**
  * Extended command context which provides utilities via usage renderer plugin.
  * These utilities are available via `CommandContext.extensions['g:renderer']`.
+ *
+ * @typeParam G - A type extending {@link GunshiParams} to specify the shape of command parameters.
  */
-interface UsageRendererCommandContext<G extends GunshiParams<any> = DefaultGunshiParams> {
+interface UsageRendererExtension<G extends GunshiParams<any> = DefaultGunshiParams> {
   /**
-   * Render the text message
+   * Render the text message.
+   *
+   * @typeParam A - The type of {@linkcode Args | arguments} defined in the command parameters.
+   * @typeParam C - The type representing the command context.
+   * @typeParam E - The type representing extended resources for localization.
+   *
+   * @param key - The translation key to be resolved.
+   * @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
@@ -95,7 +115,10 @@ interface UsageRendererCommandContext<G extends GunshiParams<any> = DefaultGunsh
   K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>) => string;
   /**
    * Load commands
-   * @returns A list of commands loaded from the usage renderert plugin.
+   *
+   * @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.
    */
   loadCommands: <G extends GunshiParams = DefaultGunshiParams>() => Promise<Command<G>[]>;
 }
@@ -103,7 +126,8 @@ interface UsageRendererCommandContext<G extends GunshiParams<any> = DefaultGunsh
 //#region src/header.d.ts
 /**
  * Render the header.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @param ctx - A {@link CommandContext | command context}
  * @returns A rendered header.
  */
 declare function renderHeader<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>;
@@ -111,7 +135,8 @@ declare function renderHeader<G extends GunshiParams = DefaultGunshiParams>(ctx:
 //#region src/usage.d.ts
 /**
  * Render the usage.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @param ctx - A {@link CommandContext | command context}
  * @returns A rendered usage.
  */
 declare function renderUsage<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>;
@@ -119,8 +144,9 @@ declare function renderUsage<G extends GunshiParams = DefaultGunshiParams>(ctx:
 //#region src/validation.d.ts
 /**
  * Render the validation errors.
- * @param ctx A {@link CommandContext | command context}
- * @param error An {@link AggregateError} of option in `args-token` validation
+ *
+ * @param _ctx - A {@link CommandContext | command context}
+ * @param error - An {@link AggregateError} of option in `args-token` validation
  * @returns A rendered validation error.
  */
 declare function renderValidationErrors<G extends GunshiParams = DefaultGunshiParams>(_ctx: CommandContext<G>, error: AggregateError): Promise<string>;
@@ -128,7 +154,9 @@ declare function renderValidationErrors<G extends GunshiParams = DefaultGunshiPa
 //#region src/index.d.ts
 /**
  * usage renderer plugin
+ *
+ * @returns A defined plugin as usage renderer
  */
-declare function renderer(): PluginWithExtension<UsageRendererCommandContext>;
+declare function renderer(): PluginWithExtension<UsageRendererExtension>;
 //#endregion
-export { type UsageRendererCommandContext, renderer as default, renderHeader, renderUsage, renderValidationErrors };
+export { PluginId, UsageRendererExtension, renderer as default, pluginId, renderHeader, renderUsage, renderValidationErrors };

package/lib/index.js

@@ -1,6 +1,6 @@
 import { ANONYMOUS_COMMAND_NAME, plugin } from "@gunshi/plugin";
 
-//#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.
 *
@@ -12,15 +12,35 @@ import { ANONYMOUS_COMMAND_NAME, plugin } from "@gunshi/plugin";
 * @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)) {
@@ -53,9 +73,22 @@ 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);
 }
+/**
+* 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)) {
@@ -127,8 +160,12 @@ var en_US_default = {
 //#region ../shared/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) {
@@ -136,34 +173,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}`;
 }
-async function resolveExamples$1(ctx, examples) {
+/**
+* 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;
 }
@@ -172,20 +241,23 @@ function makeShortLongOptionPair(schema, name, toKebab) {
 //#region ../shared/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;
@@ -197,8 +269,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$1(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;
@@ -208,7 +280,8 @@ function localizable(ctx, cmd, translate) {
 //#region src/header.ts
 /**
 * Render the header.
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered header.
 */
 function renderHeader(ctx) {
@@ -228,7 +301,8 @@ const pluginId = namespacedId("renderer");
 const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
 /**
 * Render the usage.
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered usage.
 */
 async function renderUsage(ctx) {
@@ -247,7 +321,8 @@ async function renderUsage(ctx) {
 }
 /**
 * Render the positional arguments section
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered arguments section
 */
 async function renderPositionalArgsSection(ctx) {
@@ -258,7 +333,8 @@ async function renderPositionalArgsSection(ctx) {
 }
 /**
 * Render the optional arguments section
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered options section
 */
 async function renderOptionalArgsSection(ctx) {
@@ -269,12 +345,13 @@ async function renderOptionalArgsSection(ctx) {
 }
 /**
 * Render the examples section
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered examples section
 */
 async function renderExamplesSection(ctx) {
 	const messages = [];
-	const resolvedExamples = await resolveExamples(ctx);
+	const resolvedExamples = await resolveExamples$1(ctx);
 	if (resolvedExamples) {
 		const examples = resolvedExamples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
 		messages.push(`${await ctx.extensions[pluginId].text(resolveBuiltInKey("EXAMPLES"))}:`, ...examples);
@@ -283,7 +360,8 @@ async function renderExamplesSection(ctx) {
 }
 /**
 * Render the usage section
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered usage section
 */
 async function renderUsageSection(ctx) {
@@ -305,7 +383,8 @@ async function makeUsageSymbols(ctx) {
 }
 /**
 * Render the commands section
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns A rendered commands section
 */
 async function renderCommandsSection(ctx) {
@@ -346,7 +425,8 @@ async function makeCommandSymbol(ctx, cmd) {
 }
 /**
 * Resolve the entry command name
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns The entry command name
 */
 async function resolveEntry(ctx) {
@@ -354,7 +434,8 @@ async function resolveEntry(ctx) {
 }
 /**
 * Resolve the sub command name
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns The sub command name
 */
 async function resolveSubCommand(ctx) {
@@ -362,35 +443,38 @@ async function resolveSubCommand(ctx) {
 }
 /**
 * Resolve the command description
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns resolved command description
 */
 async function resolveDescription(ctx) {
-	return await ctx.extensions[pluginId].text(resolveKey("description", ctx)) || ctx.description || "";
+	return await ctx.extensions[pluginId].text(resolveKey("description", ctx.name)) || ctx.description || "";
 }
 /**
 * Resolve the command examples
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns resolved command examples, if not resolved, return empty string
 */
-async function resolveExamples(ctx) {
-	const ret = await ctx.extensions[pluginId].text(resolveKey("examples", ctx));
+async function resolveExamples$1(ctx) {
+	const ret = await ctx.extensions[pluginId].text(resolveKey("examples", ctx.name));
 	if (ret) return ret;
 	const command = ctx.env.subCommands?.get(ctx.name || "");
-	return await resolveExamples$1(ctx, command?.examples);
+	return await resolveExamples(ctx, command?.examples);
 }
 /**
 * Check if the command has sub commands
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns True if the command has sub commands
 */
 async function hasCommands(ctx) {
-	const loadedCommands = await ctx.extensions?.[pluginId].loadCommands() || [];
-	return loadedCommands.length > 1;
+	return (await ctx.extensions?.[pluginId].loadCommands() || []).length > 1;
 }
 /**
 * Check if the command has optional arguments
-* @param args A {@link Args | command optional arguments}
+*
+* @param args - A {@link Args | command optional arguments}
 * @returns True if the command has options
 */
 function hasOptionalArgs(args) {
@@ -398,7 +482,8 @@ function hasOptionalArgs(args) {
 }
 /**
 * Check if the command has positional arguments
-* @param args A {@link Args | command positional arguments}
+*
+* @param args - A {@link Args | command positional arguments}
 * @returns True if the command has options
 */
 function hasPositionalArgs(args) {
@@ -406,7 +491,8 @@ function hasPositionalArgs(args) {
 }
 /**
 * Check if all options have default values
-* @param args An {@link Args | command argument}
+*
+* @param args - An {@link Args | command argument}
 * @returns True if all options have default values
 */
 function hasAllDefaultOptions(args) {
@@ -414,7 +500,9 @@ function hasAllDefaultOptions(args) {
 }
 /**
 * Generate options symbols for usage
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param args - {@link Args | command arguments}
 * @returns Options symbols for usage
 */
 async function generateOptionsSymbols(ctx, args) {
@@ -422,7 +510,8 @@ async function generateOptionsSymbols(ctx, args) {
 }
 /**
 * Get optional arguments pairs for usage
-* @param ctx A {@link CommandContext | command context}
+*
+* @param ctx - A {@link CommandContext | command context}
 * @returns Options pairs for usage
 */
 function getOptionalArgsPairs(ctx) {
@@ -453,7 +542,7 @@ async function resolveDisplayValue(ctx, key) {
 	const schema = ctx.args[key];
 	if ((schema.type === "boolean" || schema.type === "number" || schema.type === "string" || schema.type === "custom") && schema.default !== void 0) return `(${await generateDefaultDisplayValue(ctx, schema)})`;
 	if (schema.type === "enum") {
-		const _default = schema.default !== void 0 ? await generateDefaultDisplayValue(ctx, schema) : "";
+		const _default = schema.default === void 0 ? "" : await generateDefaultDisplayValue(ctx, schema);
 		const choices = `${await ctx.extensions[pluginId].text(resolveBuiltInKey("CHOICES"))}: ${schema.choices.join(" | ")}`;
 		return `(${_default ? `${_default}, ${choices}` : choices})`;
 	}
@@ -461,15 +550,16 @@ async function resolveDisplayValue(ctx, key) {
 }
 /**
 * Generate optional arguments usage
-* @param ctx A {@link CommandContext | command context}
-* @param optionsPairs Options pairs for usage
+*
+* @param ctx - A {@link CommandContext | command context}
+* @param optionsPairs - Options pairs for usage
 * @returns Generated options usage
 */
 async function generateOptionalArgsUsage(ctx, optionsPairs) {
 	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
 	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
-	const usages = await Promise.all(Object.entries(optionsPairs).map(async ([key, value]) => {
-		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx));
+	return (await Promise.all(Object.entries(optionsPairs).map(async ([key, value]) => {
+		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx.name));
 		if (!rawDesc && key.startsWith(ARG_NEGATABLE_PREFIX)) {
 			const name = resolveNegatableKey(key);
 			const schema = ctx.args[name];
@@ -482,8 +572,7 @@ async function generateOptionalArgsUsage(ctx, optionsPairs) {
 		const descLength = desc.length + valueDesc.length;
 		const option = `${value.padEnd((descLength > 0 ? optionsMaxLength : 0) + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
 		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
-	}));
-	return usages.join("\n");
+	}))).join("\n");
 }
 function getPositionalArgs(args) {
 	return Object.entries(args).filter(([_, schema]) => schema.type === "positional");
@@ -491,12 +580,11 @@ function getPositionalArgs(args) {
 async function generatePositionalArgsUsage(ctx) {
 	const positionals = getPositionalArgs(ctx.args);
 	const argsMaxLength = Math.max(...positionals.map(([name]) => name.length));
-	const usages = await Promise.all(positionals.map(async ([name]) => {
-		const desc = await ctx.extensions[pluginId].text(resolveArgKey(name, ctx)) || ctx.args[name].description || "";
+	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}`;
 		return `${arg.padStart(ctx.env.leftMargin + arg.length)}`;
-	}));
-	return usages.join("\n");
+	}))).join("\n");
 }
 function generatePositionalSymbols(args) {
 	return hasPositionalArgs(args) ? getPositionalArgs(args).map(([name]) => `<${name}>`).join(" ") : "";
@@ -506,8 +594,9 @@ function generatePositionalSymbols(args) {
 //#region src/validation.ts
 /**
 * Render the validation errors.
-* @param ctx A {@link CommandContext | command context}
-* @param error An {@link AggregateError} of option in `args-token` validation
+*
+* @param _ctx - A {@link CommandContext | command context}
+* @param error - An {@link AggregateError} of option in `args-token` validation
 * @returns A rendered validation error.
 */
 function renderValidationErrors(_ctx, error) {
@@ -519,25 +608,27 @@ function renderValidationErrors(_ctx, error) {
 //#endregion
 //#region src/index.ts
 const i18nPluginId = namespacedId("i18n");
+const dependencies = [{
+	id: i18nPluginId,
+	optional: true
+}];
 /**
 * usage renderer plugin
+*
+* @returns A defined plugin as usage renderer
 */
 function renderer() {
 	return plugin({
 		id: pluginId,
 		name: "usage renderer",
-		dependencies: [{
-			id: i18nPluginId,
-			optional: true
-		}],
-		extension: (ctx, cmd) => {
-			const { extensions: { [i18nPluginId]: i18n } } = ctx;
+		dependencies,
+		extension: async (ctx, cmd) => {
+			const i18n = ctx.extensions[i18nPluginId];
 			let cachedCommands;
 			async function loadCommands() {
 				if (cachedCommands) return cachedCommands;
 				const subCommands = [...ctx.env.subCommands || []];
-				const allCommands = await Promise.all(subCommands.map(async ([name, cmd$1]) => await resolveLazyCommand(cmd$1, name)));
-				cachedCommands = allCommands.filter((cmd$1) => !cmd$1.internal).filter(Boolean);
+				cachedCommands = (await Promise.all(subCommands.map(async ([name, cmd$1]) => await resolveLazyCommand(cmd$1, name)))).filter((cmd$1) => !cmd$1.internal).filter(Boolean);
 				cachedCommands.sort((a, b) => {
 					if (a.entry && !b.entry) return -1;
 					if (!a.entry && b.entry) return 1;
@@ -562,4 +653,4 @@ function renderer() {
 }
 
 //#endregion
-export { renderer as default, renderHeader, renderUsage, renderValidationErrors };
+export { renderer as default, pluginId, renderHeader, renderUsage, renderValidationErrors };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "0.27.0-alpha.9",
+  "version": "0.27.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,20 +53,20 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.27.0-alpha.9"
+    "@gunshi/plugin": "0.27.0-beta.0"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "0.27.0-alpha.9"
+    "@gunshi/plugin-i18n": "0.27.0-beta.0"
   },
   "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",
-    "typedoc": "^0.28.7",
-    "typedoc-plugin-markdown": "^4.7.1",
-    "@gunshi/shared": "0.27.0-alpha.9"
+    "publint": "^0.3.14",
+    "tsdown": "^0.15.6",
+    "typedoc": "^0.28.13",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "@gunshi/shared": "0.27.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",