@gunshi/plugin-renderer 0.26.3

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# @gunshi/plugin-renderer
+
+> 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.
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @gunshi/plugin-renderer
+
+# pnpm
+pnpm add @gunshi/plugin-renderer
+
+# yarn
+yarn add @gunshi/plugin-renderer
+
+# deno
+deno add jsr:@gunshi/plugin-renderer
+
+# bun
+bun add @gunshi/plugin-renderer
+```
+
+## 🚀 Usage
+
+```ts
+import renderer from '@gunshi/plugin-renderer'
+import { cli, define } from 'gunshi'
+
+const command = define({
+  name: 'deploy',
+  description: 'Deploy your application',
+  args: {
+    environment: {
+      type: 'string',
+      description: 'Target environment',
+      required: true
+    },
+    force: {
+      type: 'boolean',
+      short: 'f',
+      description: 'Force deployment without confirmation'
+    }
+  },
+  examples: '$ deploy production --force',
+  run: async ctx => {
+    console.log(`Deploying to ${ctx.values.environment}...`)
+  }
+})
+
+await cli(process.argv.slice(2), command, {
+  name: 'deploy-cli',
+  version: '1.0.0',
+  plugins: [
+    renderer() // Adds automatic help/usage rendering
+  ]
+})
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> The renderer plugin automatically decorates the header, usage, and validation error renderers. When users run `--help` or encounter validation errors, the plugin displays the information in a clean, readable format.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## ✨ Features
+
+### Automatic Rendering
+
+This plugin automatically handles rendering for:
+
+- **Command Headers**: Displays command name and description
+- **Usage Information**: Shows usage syntax, arguments, options, examples, and subcommands
+- **Validation Errors**: Formats validation errors in a user-friendly way
+
+### Internationalization Text Rendering
+
+The plugin provides smart text rendering with automatic fallback:
+
+- **With i18n plugin**: Uses translations from the i18n plugin
+- **Without i18n plugin**: Falls back to default English messages and descriptions
+
+### Rendered Example
+
+When a user runs `--help`, the output looks like:
+
+```sh
+deploy - Deploy your application
+
+USAGE
+  $ deploy [options] <environment>
+
+ARGUMENTS
+  environment  Target environment
+
+OPTIONS
+  -f, --force  Force deployment without confirmation
+  -h, --help   Display this help message
+
+EXAMPLES
+  $ deploy production --force
+```
+
+### Exported Functions
+
+- **`renderHeader(ctx: CommandContext): Promise<string>`**: Renders the command header section
+- **`renderUsage(ctx: CommandContext): Promise<string>`**: Renders the complete usage/help information
+- **`renderValidationErrors(ctx: CommandContext, error: AggregateError): Promise<string>`**: Renders validation errors
+
+## 🧩 Context Extensions
+
+When using the renderer plugin, your command context is extended via `ctx.extensions['g:renderer']`.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> This plugin extension is namespaced in `CommandContext.extensions` using this plugin ID `g:renderer` by the gunshi plugin system.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Available extensions:
+
+- **`text<K>(key: K, values?: Record<string, unknown>): Promise<string>`**: Render text with optional i18n support. Handles built-in keys, argument descriptions, and custom keys intelligently.
+
+- **`loadCommands<G>(): Promise<Command<G>[]>`**: Load and cache subcommands for rendering command lists. Results are cached after the first call for performance.
+
+### Usage Example
+
+```ts
+import renderer from '@gunshi/plugin-renderer'
+import { cli, define } from 'gunshi'
+
+const deploy = define({
+  name: 'deploy',
+  description: 'Deploy the application',
+  run: async ctx => {
+    console.log('Deploying...')
+  }
+})
+
+const test = define({
+  name: 'test',
+  description: 'Run tests',
+  run: async ctx => {
+    console.log('Running tests...')
+  }
+})
+
+const entry = define({
+  name: 'tools',
+  run: async ctx => {
+    // Access renderer extensions
+    const { text, loadCommands } = ctx.extensions['g:renderer']
+
+    // Render built-in message
+    const usageHeader = await text('_:USAGE') // "USAGE" or translated
+    console.log(usageHeader)
+
+    // Load and display subcommands
+    const subCommands = await loadCommands()
+    console.log('\nAvailable commands:')
+    for (const cmd of subCommands) {
+      console.log(`  ${cmd.name}: ${cmd.description}`)
+    }
+  }
+})
+
+// Create subCommands Map
+const subCommands = new Map()
+subCommands.set(deploy.name, deploy)
+subCommands.set(test.name, test)
+
+await cli(process.argv.slice(2), command, {
+  name: 'tools-cli',
+  version: '1.0.0',
+  subCommands,
+  plugins: [renderer()],
+
+  // Optional: Custom renderers
+  renderHeader: async ctx => {
+    return `=== ${ctx.env.name} v${ctx.env.version} ===`
+  },
+  renderUsage: async ctx => {
+    // Your custom usage renderer
+  }
+})
+```
+
+### 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:
+
+```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
+    }),
+    renderer() // Will use Japanese translations including custom messages
+  ]
+})
+```
+
+### Custom Rendering
+
+You can create custom plugins that use the renderer functions while adding your own branding or logic:
+
+```ts
+import { plugin } from '@gunshi/plugin'
+import { renderUsage } from '@gunshi/plugin-renderer'
+
+const customPlugin = plugin({
+  id: 'my:custom',
+  name: 'Custom Plugin',
+
+  setup: ctx => {
+    // Decorate with custom logic while using renderer functions
+    ctx.decorateUsageRenderer(async (baseRenderer, cmdCtx) => {
+      // Render usage via built-in usage renderer
+      const standardUsage = await renderUsage(cmdCtx)
+
+      // Add custom branding
+      return `
+╔══════════════════════════════════╗
+║        MY AWESOME CLI            ║
+╚══════════════════════════════════╝
+
+${standardUsage}
+
+© 2025 Your Company
+`
+    })
+  }
+})
+```
+
+## 📚 API References
+
+See the [API References](./docs/index.md)
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)T)

package/lib/index.d.ts

@@ -0,0 +1,123 @@
+import { Command, CommandContext, DefaultGunshiParams, GunshiParams, PluginWithExtension } from "@gunshi/plugin";
+import { Args } 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 };
+}
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+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';
+    readonly short: 'h';
+    readonly description: string;
+  };
+  readonly version: {
+    readonly type: 'boolean';
+    readonly short: 'v';
+    readonly description: string;
+  };
+};
+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 ../shared/src/types.d.ts
+type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+/**
+ * Remove index signature from object or record type.
+ */
+type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
+/**
+ * Generate a namespaced key.
+ */
+type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
+/**
+ * Command i18n built-in arguments keys.
+ */
+type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
+/**
+ * Command i18n built-in resource keys.
+ */
+type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
+/**
+ * i18n 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.
+ */
+type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys> | 'description' | 'examples';
+/**
+ * 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>;
+
+//#endregion
+//#region src/types.d.ts
+/**
+ * Extended command context which provides utilities via usage renderer plugin.
+ * These utilities are available via `CommandContext.extensions['g:renderer']`.
+ */
+interface UsageRendererCommandContext<G extends GunshiParams<any> = DefaultGunshiParams> {
+  /**
+   * Render the text message
+   */
+  text: <T extends string = CommandBuiltinKeys, O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>) => Promise<string>;
+  /**
+   * Load commands
+   * @returns A list of commands loaded from the command loader plugin.
+   */
+  loadCommands: <G extends GunshiParams = DefaultGunshiParams>() => Promise<Command<G>[]>;
+}
+
+//#endregion
+//#region src/header.d.ts
+/**
+ * Render the header.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A rendered header.
+ */
+declare function renderHeader<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>;
+
+//#endregion
+//#region src/usage.d.ts
+/**
+ * Render the usage.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A rendered usage.
+ */
+declare function renderUsage<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>;
+
+//#endregion
+//#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
+ * @returns A rendered validation error.
+ */
+declare function renderValidationErrors<G extends GunshiParams = DefaultGunshiParams>(_ctx: CommandContext<G>, error: AggregateError): Promise<string>;
+
+//#endregion
+//#region src/index.d.ts
+/**
+ * usage renderer plugin
+ */
+declare function renderer(): PluginWithExtension<UsageRendererCommandContext>;
+
+//#endregion
+export { UsageRendererCommandContext, renderer as default, renderHeader, renderUsage, renderValidationErrors };

package/lib/index.js

@@ -0,0 +1,488 @@
+import { plugin } from "@gunshi/plugin";
+
+//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/utils-N7UlhLbz.js
+/**
+* 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
+*/
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
+
+//#endregion
+//#region ../gunshi/src/utils.ts
+function isLazyCommand(cmd) {
+	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+}
+async function resolveLazyCommand(cmd, name, needRunResolving = false) {
+	let command;
+	if (isLazyCommand(cmd)) {
+		const baseCommand = {
+			name: cmd.commandName,
+			description: cmd.description,
+			args: cmd.args,
+			examples: cmd.examples
+		};
+		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
+		command = Object.assign(create(), baseCommand);
+		if (needRunResolving) {
+			const loaded = await cmd();
+			if (typeof loaded === "function") command.run = loaded;
+			else if (typeof loaded === "object") {
+				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
+				command.run = loaded.run;
+				command.name = loaded.name;
+				command.description = loaded.description;
+				command.args = loaded.args;
+				command.examples = loaded.examples;
+				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
+			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
+		}
+	} else command = Object.assign(create(), cmd);
+	if (command.name == null && name) command.name = name;
+	return deepFreeze(command);
+}
+function create(obj = null) {
+	return Object.create(obj);
+}
+function deepFreeze(obj, ignores = []) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (ignores.includes(key)) continue;
+		if (typeof value === "object" && value !== null) deepFreeze(value, ignores);
+	}
+	return Object.freeze(obj);
+}
+
+//#endregion
+//#region ../shared/src/constants.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const BUILT_IN_PREFIX = "_";
+const PLUGIN_PREFIX = "g";
+const ARG_PREFIX = "arg";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const ARG_PREFIX_AND_KEY_SEPARATOR = `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const ARG_NEGATABLE_PREFIX = "no-";
+const COMMON_ARGS = {
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "Display this help message"
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "Display this version"
+	}
+};
+
+//#endregion
+//#region ../resources/locales/en-US.json
+var COMMAND = "COMMAND";
+var COMMANDS = "COMMANDS";
+var SUBCOMMAND = "SUBCOMMAND";
+var USAGE = "USAGE";
+var ARGUMENTS = "ARGUMENTS";
+var OPTIONS = "OPTIONS";
+var EXAMPLES = "EXAMPLES";
+var FORMORE = "For more info, run any command with the `--help` flag";
+var NEGATABLE = "Negatable of";
+var DEFAULT = "default";
+var CHOICES = "choices";
+var help = "Display this help message";
+var version = "Display this version";
+var en_US_default = {
+	COMMAND,
+	COMMANDS,
+	SUBCOMMAND,
+	USAGE,
+	ARGUMENTS,
+	OPTIONS,
+	EXAMPLES,
+	FORMORE,
+	NEGATABLE,
+	DEFAULT,
+	CHOICES,
+	help,
+	version
+};
+
+//#endregion
+//#region ../shared/src/utils.ts
+function resolveBuiltInKey(key) {
+	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+function resolveArgKey(key) {
+	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+async function resolveExamples$1(ctx, examples) {
+	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
+}
+function namespacedId(id) {
+	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
+}
+
+//#endregion
+//#region src/header.ts
+/**
+* Render the header.
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered header.
+*/
+function renderHeader(ctx) {
+	const title = ctx.env.description || ctx.env.name || "";
+	return Promise.resolve(title ? `${title} (${ctx.env.name || ""}${ctx.env.version ? ` v${ctx.env.version}` : ""})` : title);
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* The unique identifier for usage renderer plugin.
+*/
+const pluginId = namespacedId("renderer");
+
+//#endregion
+//#region src/usage.ts
+const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
+/**
+* Render the usage.
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered usage.
+*/
+async function renderUsage(ctx) {
+	const messages = [];
+	if (!ctx.omitted) {
+		const description = await resolveDescription(ctx);
+		if (description) messages.push(description, "");
+	}
+	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), "");
+	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}
+* @returns A rendered arguments section
+*/
+async function renderPositionalArgsSection(ctx) {
+	const messages = [];
+	messages.push(`${await ctx.extensions[pluginId].text(resolveBuiltInKey("ARGUMENTS"))}:`);
+	messages.push(await generatePositionalArgsUsage(ctx));
+	return messages;
+}
+/**
+* Render the optional arguments section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered options section
+*/
+async function renderOptionalArgsSection(ctx) {
+	const messages = [];
+	messages.push(`${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}:`);
+	messages.push(await generateOptionalArgsUsage(ctx, getOptionalArgsPairs(ctx)));
+	return messages;
+}
+/**
+* Render the examples section
+* @param ctx A {@link CommandContext | command context}
+* @returns A rendered examples section
+*/
+async function renderExamplesSection(ctx) {
+	const messages = [];
+	const resolvedExamples = await resolveExamples(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);
+	}
+	return messages;
+}
+/**
+* Render the usage section
+* @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));
+	}
+	return messages;
+}
+/**
+* Render the commands section
+* @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 desc = cmd.description || "";
+		const command = `${key.padEnd(commandMaxLength + 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`;
+		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
+	}));
+	return messages;
+}
+/**
+* Resolve the entry command name
+* @param ctx A {@link CommandContext | command context}
+* @returns The entry command name
+*/
+async function resolveEntry(ctx) {
+	return ctx.env.name || await ctx.extensions[pluginId].text(resolveBuiltInKey("COMMAND"));
+}
+/**
+* Resolve the sub command name
+* @param ctx A {@link CommandContext | command context}
+* @returns The sub command name
+*/
+async function resolveSubCommand(ctx) {
+	return ctx.name || await ctx.extensions[pluginId].text(resolveBuiltInKey("SUBCOMMAND"));
+}
+/**
+* Resolve the command description
+* @param ctx A {@link CommandContext | command context}
+* @returns resolved command description
+*/
+async function resolveDescription(ctx) {
+	return await ctx.extensions[pluginId].text("description") || ctx.description || "";
+}
+/**
+* Resolve the command examples
+* @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");
+	if (ret) return ret;
+	const command = ctx.env.subCommands?.get(ctx.name || "");
+	return await resolveExamples$1(ctx, command?.examples);
+}
+/**
+* Check if the command has sub commands
+* @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;
+}
+/**
+* Check if the command has optional arguments
+* @param ctx A {@link CommandContext | command context}
+* @returns True if the command has options
+*/
+function hasOptionalArgs(ctx) {
+	return !!(ctx.args && Object.values(ctx.args).some((arg) => arg.type !== "positional"));
+}
+/**
+* Check if the command has positional arguments
+* @param ctx A {@link CommandContext | command context}
+* @returns True if the command has options
+*/
+function hasPositionalArgs(ctx) {
+	return !!(ctx.args && Object.values(ctx.args).some((arg) => arg.type === "positional"));
+}
+/**
+* Check if all options have default values
+* @param ctx A {@link CommandContext | command context}
+* @returns True if all options have default values
+*/
+function hasAllDefaultOptions(ctx) {
+	return !!(ctx.args && Object.values(ctx.args).every((arg) => arg.default));
+}
+/**
+* Generate options symbols for usage
+* @param ctx A {@link CommandContext | command context}
+* @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"))}>` : "";
+}
+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;
+}
+/**
+* Get optional arguments pairs for usage
+* @param ctx A {@link CommandContext | command context}
+* @returns Options pairs for usage
+*/
+function getOptionalArgsPairs(ctx) {
+	return Object.entries(ctx.args).reduce((acc, [name, schema]) => {
+		if (schema.type === "positional") return acc;
+		let key = makeShortLongOptionPair(schema, name, ctx.toKebab);
+		if (schema.type !== "boolean") {
+			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
+			key = schema.default ? `${key} [${displayName}]` : `${key} <${displayName}>`;
+		}
+		acc[name] = key;
+		if (schema.type === "boolean" && schema.negatable && !COMMON_ARGS_KEYS.includes(name)) {
+			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
+			acc[`${ARG_NEGATABLE_PREFIX}${name}`] = `--${ARG_NEGATABLE_PREFIX}${displayName}`;
+		}
+		return acc;
+	}, Object.create(null));
+}
+const resolveNegatableKey = (key) => key.split(ARG_NEGATABLE_PREFIX)[1];
+function resolveNegatableType(key, ctx) {
+	return ctx.args[key.startsWith(ARG_NEGATABLE_PREFIX) ? resolveNegatableKey(key) : key].type;
+}
+async function generateDefaultDisplayValue(ctx, schema) {
+	return `${await ctx.extensions[pluginId].text(resolveBuiltInKey("DEFAULT"))}: ${schema.default}`;
+}
+async function resolveDisplayValue(ctx, key) {
+	if (COMMON_ARGS_KEYS.includes(key)) return "";
+	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 choices = `${await ctx.extensions[pluginId].text(resolveBuiltInKey("CHOICES"))}: ${schema.choices.join(" | ")}`;
+		return `(${_default ? `${_default}, ${choices}` : choices})`;
+	}
+	return "";
+}
+/**
+* Generate optional arguments 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));
+		if (!rawDesc && key.startsWith(ARG_NEGATABLE_PREFIX)) {
+			const name = resolveNegatableKey(key);
+			const schema = ctx.args[name];
+			const optionKey = makeShortLongOptionPair(schema, name, ctx.toKebab);
+			rawDesc = `${await ctx.extensions[pluginId].text(resolveBuiltInKey("NEGATABLE"))} ${optionKey}`;
+		}
+		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}` : ""}`;
+		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
+	}));
+	return usages.join("\n");
+}
+function getPositionalArgs(ctx) {
+	return Object.entries(ctx.args).filter(([_, schema]) => schema.type === "positional");
+}
+async function generatePositionalArgsUsage(ctx) {
+	const positionals = getPositionalArgs(ctx);
+	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 || "";
+		const arg = `${name.padEnd(argsMaxLength + ctx.env.middleMargin)} ${desc}`;
+		return `${arg.padStart(ctx.env.leftMargin + arg.length)}`;
+	}));
+	return usages.join("\n");
+}
+function generatePositionalSymbols(ctx) {
+	return hasPositionalArgs(ctx) ? getPositionalArgs(ctx).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
+* @returns A rendered validation error.
+*/
+function renderValidationErrors(_ctx, error) {
+	const messages = [];
+	for (const err of error.errors) messages.push(err.message);
+	return Promise.resolve(messages.join("\n"));
+}
+
+//#endregion
+//#region src/index.ts
+const i18nPluginId = namespacedId("i18n");
+/**
+* usage renderer plugin
+*/
+function renderer() {
+	return plugin({
+		id: pluginId,
+		name: "usage renderer",
+		dependencies: [{
+			id: i18nPluginId,
+			optional: true
+		}],
+		extension: (ctx, cmd) => {
+			const { extensions: { [i18nPluginId]: i18n } } = ctx;
+			let cachedCommands;
+			async function loadCommands() {
+				if (cachedCommands) return cachedCommands;
+				const subCommands = [...ctx.env.subCommands || []];
+				cachedCommands = await Promise.all(subCommands.map(async ([name, cmd$1]) => await resolveLazyCommand(cmd$1, name)));
+				return cachedCommands;
+			}
+			async function text(key, values = Object.create(null)) {
+				if (i18n) return i18n.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);
+					let negatable = false;
+					if (argKey.startsWith(ARG_NEGATABLE_PREFIX)) {
+						argKey = argKey.slice(ARG_NEGATABLE_PREFIX.length);
+						negatable = true;
+					}
+					const schema = ctx.args[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);
+				else return key;
+			}
+			return {
+				text,
+				loadCommands
+			};
+		},
+		setup: (ctx) => {
+			ctx.decorateHeaderRenderer(async (_baseRenderer, cmdCtx) => await renderHeader(cmdCtx));
+			ctx.decorateUsageRenderer(async (_baseRenderer, cmdCtx) => await renderUsage(cmdCtx));
+			ctx.decorateValidationErrorsRenderer(async (_baseRenderer, cmdCtx, error) => await renderValidationErrors(cmdCtx, error));
+		}
+	});
+}
+
+//#endregion
+export { renderer as default, renderHeader, renderUsage, renderValidationErrors };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@gunshi/plugin-renderer",
+  "description": "usage renderer plugin for gunshi",
+  "version": "0.26.3",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/plugin-renderer"
+  },
+  "keywords": [
+    "gunshi",
+    "usage",
+    "renderer",
+    "plugin",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@gunshi/plugin": "0.26.3"
+  },
+  "peerDependencies": {
+    "@gunshi/plugin-i18n": "0.26.3"
+  },
+  "devDependencies": {
+    "deno": "^2.3.3",
+    "jsr": "^0.13.4",
+    "jsr-exports-lint": "^0.4.1",
+    "publint": "^0.3.12",
+    "tsdown": "^0.12.3",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "@gunshi/shared": "0.26.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "typedoc --excludeInternal",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+  }
+}