@gunshi/plugin-renderer 0.27.0-alpha.8 → 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,53 +1,11 @@
-import { Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
-import { Args, Args as Args$1 } from "args-tokens";
+import { Args, Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
+import { Args as Args$1 } from "args-tokens";
 
-//#region rolldown:runtime
-
-//#endregion
-//#region ../gunshi/src/types.d.ts
-/**
- * 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$1<P extends {
-  args?: Args;
-  extensions?: ExtendContext;
-} = {
-  args: Args;
-  extensions: {};
-}> {
-  /**
-   * Command argument definitions
-   */
-  args: P extends {
-    args: infer A extends Args;
-  } ? A : Args;
-  /**
-   * Command context extensions
-   */
-  extensions: P extends {
-    extensions: infer E extends ExtendContext;
-  } ? E : {};
-}
-/**
- * Default Gunshi parameters
- * @since v0.27.0
- */
-type DefaultGunshiParams$1 = GunshiParams$1;
+//#region ../shared/src/constants.d.ts
 /**
- * Generic constraint for command-related types.
- * This type constraint allows both GunshiParams and objects with extensions.
- * @since v0.27.0
- */
-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 };
-}
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 /**
  * @author kazuya kawaguchi (a.k.a. kazupon)
  * @license MIT
@@ -56,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';
@@ -76,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.
@@ -88,47 +50,75 @@ 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];
 /**
- * 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$1> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
+type CommandArgKeys<A extends Args$1, 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;
 /**
- * Translation function interface
+ * Resolve translation keys for command context.
  */
-//#endregion
-//#region ../shared/src/localize.d.ts
-interface Localization<T extends string = CommandBuiltinKeys, G extends GunshiParams$1<any> = DefaultGunshiParams$1> {
-  <O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>): Promise<string>;
-}
+type ResolveTranslationKeys<A extends Args$1, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
+  name: infer N;
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = CommandBuiltinKeys | O | T;
 //#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: Localization<CommandBuiltinKeys, G>;
+  text: <A extends Args = G['args'], C = {},
+  // for CommandContext
+  E extends Record<string, string> = {},
+  // for extended resources
+  K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>) => string;
   /**
    * Load commands
-   * @returns A list of commands loaded from the command loader 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>[]>;
 }
@@ -136,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>;
@@ -144,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>;
@@ -152,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>;
@@ -161,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 { 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 { plugin } from "@gunshi/plugin";
+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 { 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)) {
@@ -125,35 +158,108 @@ var en_US_default = {
 
 //#endregion
 //#region ../shared/src/utils.ts
+/**
+* Resolve a namespaced key for built-in resources.
+*
+* Built-in keys are prefixed with "_:".
+*
+* @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) {
 	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").
+*
+* @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, name) {
+	return `${name ? `${name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
-async function resolveExamples$1(ctx, examples) {
+/**
+* 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").
+*
+* @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, 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;
 }
 
 //#endregion
-//#region ../shared/src/localize.ts
+//#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.
+*
+* @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);
-		else 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;
-		} else if (key.startsWith(ARG_PREFIX_AND_KEY_SEPARATOR)) {
-			let argKey = key.slice(ARG_PREFIX_AND_KEY_SEPARATOR.length);
+		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;
 			if (argKey.startsWith(ARG_NEGATABLE_PREFIX)) {
 				argKey = argKey.slice(ARG_NEGATABLE_PREFIX.length);
@@ -162,8 +268,9 @@ function localizable(ctx, cmd, translate) {
 			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 || "";
-		} else if (key === "description") return "";
-		else if (key === "examples") 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;
@@ -173,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) {
@@ -193,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) {
@@ -204,15 +313,16 @@ async function renderUsage(ctx) {
 	}
 	messages.push(...await renderUsageSection(ctx), "");
 	if (ctx.omitted && await hasCommands(ctx)) messages.push(...await renderCommandsSection(ctx), "");
-	if (hasPositionalArgs(ctx)) messages.push(...await renderPositionalArgsSection(ctx), "");
-	if (hasOptionalArgs(ctx)) messages.push(...await renderOptionalArgsSection(ctx), "");
+	if (hasPositionalArgs(ctx.args)) messages.push(...await renderPositionalArgsSection(ctx), "");
+	if (hasOptionalArgs(ctx.args)) messages.push(...await renderOptionalArgsSection(ctx), "");
 	const examples = await renderExamplesSection(ctx);
 	if (examples.length > 0) messages.push(...examples, "");
 	return messages.join("\n");
 }
 /**
 * 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) {
@@ -223,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) {
@@ -234,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);
@@ -248,49 +360,73 @@ 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) {
 	const messages = [`${await ctx.extensions[pluginId].text(resolveBuiltInKey("USAGE"))}:`];
-	if (ctx.omitted) {
-		const defaultCommand = `${await resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${await resolveSubCommand(ctx)}]` : ""} ${[await generateOptionsSymbols(ctx), generatePositionalSymbols(ctx)].filter(Boolean).join(" ")}`;
-		messages.push(defaultCommand.padStart(ctx.env.leftMargin + defaultCommand.length));
-		if (await hasCommands(ctx)) {
-			const commandsUsage = `${await resolveEntry(ctx)} <${await ctx.extensions[pluginId].text(resolveBuiltInKey("COMMANDS"))}>`;
-			messages.push(commandsUsage.padStart(ctx.env.leftMargin + commandsUsage.length));
-		}
-	} else {
-		const usageStr = `${await resolveEntry(ctx)} ${await resolveSubCommand(ctx)} ${[await generateOptionsSymbols(ctx), generatePositionalSymbols(ctx)].filter(Boolean).join(" ")}`;
-		messages.push(usageStr.padStart(ctx.env.leftMargin + usageStr.length));
-	}
+	const usageStr = await makeUsageSymbols(ctx);
+	messages.push(usageStr.padStart(ctx.env.leftMargin + usageStr.length));
 	return messages;
 }
+async function makeUsageSymbols(ctx) {
+	const messages = [await resolveEntry(ctx)];
+	if (ctx.omitted) if (await hasCommands(ctx)) messages.push(` [${await ctx.extensions[pluginId].text(resolveBuiltInKey("COMMANDS"))}]`);
+	else messages.push(`${ctx.callMode === "subCommand" ? ` ${await resolveSubCommand(ctx)}` : ""}`);
+	else messages.push(`${ctx.callMode === "subCommand" ? ` ${await resolveSubCommand(ctx)}` : ""}`);
+	const optionsSymbols = await generateOptionsSymbols(ctx, ctx.args);
+	if (optionsSymbols) messages.push(" ", optionsSymbols);
+	const positionalSymbols = generatePositionalSymbols(ctx.args);
+	if (positionalSymbols) messages.push(" ", positionalSymbols);
+	return messages.join("");
+}
 /**
 * 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) {
 	const messages = [`${await ctx.extensions[pluginId].text(resolveBuiltInKey("COMMANDS"))}:`];
 	const loadedCommands = await ctx.extensions?.[pluginId].loadCommands() || [];
 	const commandMaxLength = Math.max(...loadedCommands.map((cmd) => (cmd.name || "").length));
-	const commandsStr = await Promise.all(loadedCommands.map((cmd) => {
-		const key = cmd.name || "";
+	const commandsStr = await Promise.all(loadedCommands.map(async (cmd) => {
 		const desc = cmd.description || "";
-		const command = `${key.padEnd(commandMaxLength + ctx.env.middleMargin)}${desc} `;
-		return `${command.padStart(ctx.env.leftMargin + command.length)} `;
+		const optionSymbol = await generateOptionsSymbols(ctx, ctx.args);
+		const positionalSymbol = generatePositionalSymbols(ctx.args);
+		const commandStr = await makeCommandSymbol(ctx, cmd);
+		const symbolLength = desc.length > 0 ? commandMaxLength + optionSymbol.length + positionalSymbol.length : 0;
+		const command = `${commandStr.padEnd(symbolLength + ctx.env.middleMargin)}${desc}`;
+		return `${command.padStart(ctx.env.leftMargin + command.length)}`;
 	}));
 	messages.push(...commandsStr, "", `${await ctx.extensions[pluginId].text(resolveBuiltInKey("FORMORE"))}:`);
 	messages.push(...loadedCommands.map((cmd) => {
-		const commandHelp = `${ctx.env.name} ${cmd.name} --help`;
+		let commandStr = cmd.entry ? "" : cmd.name || "";
+		if (commandStr) commandStr += " ";
+		const commandHelp = `${ctx.env.name} ${commandStr}--help`;
 		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
 	}));
 	return messages;
 }
+async function makeCommandSymbol(ctx, cmd) {
+	const optionSymbol = await generateOptionsSymbols(ctx, ctx.args);
+	const positionalSymbol = generatePositionalSymbols(ctx.args);
+	let commandStr = cmd.entry ? cmd.name === void 0 || cmd.name === ANONYMOUS_COMMAND_NAME ? "" : `[${cmd.name}]` : cmd.name || "";
+	if (optionSymbol) {
+		if (commandStr) commandStr += " ";
+		commandStr += `${optionSymbol}`;
+	}
+	if (positionalSymbol) {
+		if (commandStr) commandStr += " ";
+		commandStr += `${positionalSymbol}`;
+	}
+	return commandStr;
+}
 /**
 * 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) {
@@ -298,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) {
@@ -306,67 +443,75 @@ 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("description") || 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("examples");
+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 ctx A {@link CommandContext | command context}
+*
+* @param args - A {@link Args | command optional arguments}
 * @returns True if the command has options
 */
-function hasOptionalArgs(ctx) {
-	return !!(ctx.args && Object.values(ctx.args).some((arg) => arg.type !== "positional"));
+function hasOptionalArgs(args) {
+	return Object.values(args).some((arg) => arg.type !== "positional");
 }
 /**
 * Check if the command has positional arguments
-* @param ctx A {@link CommandContext | command context}
+*
+* @param args - A {@link Args | command positional arguments}
 * @returns True if the command has options
 */
-function hasPositionalArgs(ctx) {
-	return !!(ctx.args && Object.values(ctx.args).some((arg) => arg.type === "positional"));
+function hasPositionalArgs(args) {
+	return Object.values(args).some((arg) => arg.type === "positional");
 }
 /**
 * Check if all options have default values
-* @param ctx A {@link CommandContext | command context}
+*
+* @param args - An {@link Args | command argument}
 * @returns True if all options have default values
 */
-function hasAllDefaultOptions(ctx) {
-	return !!(ctx.args && Object.values(ctx.args).every((arg) => arg.default));
+function hasAllDefaultOptions(args) {
+	return !!(args && Object.values(args).every((arg) => arg.default));
 }
 /**
 * 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) {
-	return hasOptionalArgs(ctx) ? hasAllDefaultOptions(ctx) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
+async function generateOptionsSymbols(ctx, args) {
+	return hasOptionalArgs(args) ? hasAllDefaultOptions(args) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
 }
 /**
 * 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) {
@@ -397,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})`;
 	}
@@ -405,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));
+	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];
@@ -423,34 +569,34 @@ async function generateOptionalArgsUsage(ctx, optionsPairs) {
 		const optionsSchema = ctx.env.usageOptionType ? `[${resolveNegatableType(key, ctx)}] ` : "";
 		const valueDesc = key.startsWith(ARG_NEGATABLE_PREFIX) ? "" : await resolveDisplayValue(ctx, key);
 		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
-		const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
+		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(ctx) {
-	return Object.entries(ctx.args).filter(([_, schema]) => schema.type === "positional");
+function getPositionalArgs(args) {
+	return Object.entries(args).filter(([_, schema]) => schema.type === "positional");
 }
 async function generatePositionalArgsUsage(ctx) {
-	const positionals = getPositionalArgs(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.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(ctx) {
-	return hasPositionalArgs(ctx) ? getPositionalArgs(ctx).map(([name]) => `<${name}>`).join(" ") : "";
+function generatePositionalSymbols(args) {
+	return hasPositionalArgs(args) ? getPositionalArgs(args).map(([name]) => `<${name}>`).join(" ") : "";
 }
 
 //#endregion
 //#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) {
@@ -462,25 +608,36 @@ 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)));
-				return 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;
+					if (a.name && b.name) return a.name.localeCompare(b.name);
+					if (a.name && !b.name) return -1;
+					if (!a.name && b.name) return 1;
+					return 0;
+				});
+				return cachedCommands;
 			}
 			return {
 				text: localizable(ctx, cmd, i18n?.translate),
@@ -496,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.8",
+  "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.8"
+    "@gunshi/plugin": "0.27.0-beta.0"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "0.27.0-alpha.8"
+    "@gunshi/plugin-i18n": "0.27.0-beta.0"
   },
   "devDependencies": {
-    "deno": "^2.4.0",
+    "deno": "^2.5.4",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
-    "publint": "^0.3.12",
-    "tsdown": "^0.12.9",
-    "typedoc": "^0.28.7",
-    "typedoc-plugin-markdown": "^4.7.0",
-    "@gunshi/shared": "0.27.0-alpha.8"
+    "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",