@gunshi/plugin-renderer 0.37.2 → 1.0.0-beta.0

package/README.md

@@ -6,7 +6,7 @@
 
 > 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.
+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. Description columns are aligned by the width a terminal draws, including full-width names; emoji sequences joined with ZWJ may still differ by terminal.
 
 ## 💿 Installation
 
@@ -136,7 +136,9 @@ 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.
+- **`loadCommands<G>(): Promise<Command<G>[]>`**: Load and cache commands for rendering command lists. At the top level, the list also includes the CLI's entry command when plugins registered the subcommands without adding the entry to the registry. Results are cached after the first call for performance.
+
+- **`localizeCommandDescription(cmd): Promise<string>`**: Resolve the description of a command in the command list. Localized when `@gunshi/plugin-i18n` is installed and the command has a resource of its own; otherwise `Command.description`.
 
 ### Usage Example
 
@@ -214,13 +216,15 @@ await cli(args, command, {
   plugins: [
     i18n({
       locale: 'ja-JP',
-      resources // Uses built-in resources from `@gunshi/resources`
+      builtinResources: resources // Uses built-in resources from `@gunshi/resources`
     }),
     renderer() // Will use Japanese translations
   ]
 })
 ```
 
+The renderer imports its error guards from `@gunshi/plugin`, which bundles its own copy of the error classes. It still recognizes and localizes validation errors thrown by `gunshi` or `@gunshi/bone`. Keep `gunshi` and all `@gunshi/*` packages on the same version: when an older copy throws an argument validation error such as a missing required option, the renderer cannot recognize it and falls back to the English message.
+
 ### Custom Rendering
 
 You can create custom plugins that use the renderer functions while adding your own branding or logic:

package/lib/index.d.ts

@@ -35,8 +35,8 @@ type CommonArgType = {
 };
 declare const COMMON_ARGS: CommonArgType;
 declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
-declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option"];
-declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found"];
+declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
+declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
 //#endregion
 //#region ../plugin-i18n/src/types.d.ts
@@ -161,9 +161,21 @@ interface UsageRendererExtension<G extends GunshiParams<any> = DefaultGunshiPara
    *
    * @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.
+   * @returns A list of commands loaded from the usage renderer plugin. At the top-level entry,
+   * the list includes the CLI entry command even when a plugin registered the other commands
+   * without adding the entry to `env.subCommands`.
    */
   loadCommands: <G extends GunshiParams = DefaultGunshiParams>() => Promise<Command<G>[]>;
+  /**
+   * Resolve the description of a command in the command list.
+   *
+   * The description is localized when `@gunshi/plugin-i18n` is installed and the command has a
+   * resource of its own, and falls back to {@link Command.description} otherwise.
+   *
+   * @param cmd - A command from {@link UsageRendererExtension.loadCommands}.
+   * @returns The description to show for the command.
+   */
+  localizeCommandDescription: (cmd: Command) => Promise<string>;
 }
 //#endregion
 //#region src/header.d.ts

package/lib/index.js

@@ -1,5 +1,5 @@
-import { ANONYMOUS_COMMAND_NAME, ArgsValidationErrorKeys, isArgsValidationError, isCommandNotFoundError, plugin } from "@gunshi/plugin";
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/utils.js
+import { ANONYMOUS_COMMAND_NAME, ArgsValidationErrorKeys, createCommandContext, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin } from "@gunshi/plugin";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -30,14 +30,20 @@ function kebabnize(str) {
 * 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
+* @returns `true` if the command is a {@link LazyCommand}, otherwise `false`
+*
+* A lazy command is identified by its `commandName` property. The property may be
+* `undefined` when the lazy command has no definition name.
 */
 function isLazyCommand(cmd) {
-	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+	return typeof cmd === "function" && "commandName" in cmd;
 }
 /**
 * Resolve a lazy command to a {@link Command}.
 *
+* If the loader returns a command, the properties of the loaded command take precedence,
+* and the properties that it does not define fall back to the definition that is given to `lazy`.
+*
 * @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.
@@ -53,6 +59,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			examples: cmd.examples,
 			internal: cmd.internal,
 			entry: cmd.entry,
+			toKebab: cmd.toKebab,
+			rendering: cmd.rendering,
 			subCommands: cmd.subCommands
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
@@ -62,13 +70,20 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			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}`);
+				/**
+				* NOTE(kazupon): the loaded command wins, and the definition that is given to `lazy` is the fallback
+				* for what the loaded command does not define. A loader that returns `{ run }` keeps the whole definition,
+				* like a loader that returns the runner itself.
+				*/
 				command.run = loaded.run;
-				command.name = loaded.name;
-				command.description = loaded.description;
-				command.args = loaded.args;
-				command.examples = loaded.examples;
-				command.internal = loaded.internal;
-				command.entry = loaded.entry;
+				command.name = loaded.name ?? cmd.commandName;
+				command.description = loaded.description ?? cmd.description;
+				command.args = loaded.args ?? cmd.args;
+				command.examples = loaded.examples ?? cmd.examples;
+				command.internal = loaded.internal ?? cmd.internal;
+				command.entry = loaded.entry ?? cmd.entry;
+				command.toKebab = loaded.toKebab ?? cmd.toKebab;
+				command.rendering = loaded.rendering ?? cmd.rendering;
 				command.subCommands = loaded.subCommands || cmd.subCommands;
 				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
 			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
@@ -143,7 +158,14 @@ var en_US_default = {
 	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
 	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
 	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:arg:unexpected-value": "Optional argument {$displayName} does not take a value",
+	"err:arg:missing-value": "Optional argument {$displayName} requires a value",
+	"err:arg:conflict": "{$displayName} conflicts with {$conflictDisplayName}",
+	"err:arg:invalid-default": "Invalid default for {$displayName}: {$actual} is not one of {$choices}",
 	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:cmd:ambiguous": "The command is ambiguous. Move options after the command name: {$candidatePaths}",
+	"err:cmd:inconsistent-options": "The options do not identify a consistent command. Move options after the command name.",
+	"err:cmd:lazy-schema-mismatch": "The lazy command definition does not match its loaded options. Declare leading options in the lazy definition or move options after the command name: {$commandPath}",
 	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
@@ -226,10 +248,36 @@ function namespacedId(id) {
 * @returns A string representing the short and long option pair.
 */
 function makeShortLongOptionPair(schema, name, toKebab) {
-	let key = `--${toKebab || schema.toKebab ? kebabnize(name) : name}`;
+	let key = `--${resolveDisplayName(name, schema, toKebab)}`;
 	if (schema.short) key = `-${schema.short}, ${key}`;
 	return key;
 }
+/**
+* Resolve the name that an argument is parsed and rendered under.
+*
+* @param name - The key of the argument.
+* @param schema - The {@linkcode ArgSchema | argument schema}.
+* @param toKebab - Whether to convert the name to kebab-case.
+* @returns The name of the argument, kebab-cased when `toKebab` asks for it.
+*/
+function resolveDisplayName(name, schema, toKebab) {
+	return toKebab || schema.toKebab ? kebabnize(name) : name;
+}
+/**
+* Collect the names that the arguments are parsed and rendered under.
+*
+* A positional argument is left out: it is never spelled as an option, so it cannot take the name of
+* one. A `hidden` argument is counted, because it still owns the name that it parses.
+*
+* @param args - The {@linkcode Args | arguments} of a command, global options included.
+* @param toKebab - Whether the command converts its names to kebab-case.
+* @returns The set of names.
+*/
+function resolveOptionNames(args, toKebab) {
+	const names = /* @__PURE__ */ new Set();
+	for (const [name, schema] of Object.entries(args)) if (schema.type !== "positional") names.add(resolveDisplayName(name, schema, toKebab));
+	return names;
+}
 //#endregion
 //#region ../shared/src/localization.ts
 /**
@@ -257,15 +305,21 @@ function localizable(ctx, cmd, translate) {
 		if (key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key, key, values);
 		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
-			let argKey = key.slice(namaspacedArgKey.length);
-			let negatable = false;
+			const argKey = key.slice(namaspacedArgKey.length);
+			/**
+			* NOTE(kazupon): an argument describes itself, whatever it is called. `no-` is stripped only
+			* to reach the option that a negated form negates, and only when there is no argument under
+			* the name as written: `no-emoji` may be an argument of its own, and it then has nothing to do
+			* with `emoji`.
+			*/
+			const ownSchema = ctx.args[argKey];
+			if (ownSchema) return ownSchema.description || "";
 			if (argKey.startsWith("no-")) {
-				argKey = argKey.slice(3);
-				negatable = true;
+				const negatedKey = argKey.slice(3);
+				const schema = ctx.args[negatedKey];
+				if (schema && schema.type === "boolean" && schema.negatable) return `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, negatedKey, ctx.toKebab)}`;
 			}
-			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 || "";
+			return argKey;
 		}
 		if (key === resolveKey("description", ctx.name)) return "";
 		else if (key === resolveKey("examples", ctx.name)) return await resolveExamples$1(ctx, cmd.examples);
@@ -321,6 +375,63 @@ function renderHeader(ctx) {
 */
 const pluginId = namespacedId("renderer");
 //#endregion
+//#region src/width.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* NOTE(kazupon): the columns of the usage are aligned by padding, and padding by `String#length`
+* counts UTF-16 code units, which is not what a terminal draws: a full-width character takes two
+* columns, a combining mark takes none, and a joined emoji takes two however many code points it is
+* written with. The text is walked by grapheme, so that a mark or a joiner is part of the character
+* it belongs to, and each grapheme is measured by the code point it starts with.
+*
+* JavaScript has no `\p{East_Asian_Width=Wide}` escape. Wide columns are those the engine already
+* classifies as Han / Hiragana / Katakana / Hangul or emoji-presentation, plus the fullwidth slice
+* of Halfwidth and Fullwidth Forms. That covers CLI names; the rest of the East Asian Width table
+* is symbols that do not appear there. Unicode updates then come with the runtime.
+*/
+const WIDE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Emoji_Presentation}]/u;
+const ZERO_WIDTH = /[\p{Default_Ignorable_Code_Point}\p{Mn}]/u;
+function graphemeWidth(codePoint) {
+	const ch = String.fromCodePoint(codePoint);
+	if (ZERO_WIDTH.test(ch)) return 0;
+	/**
+	* Halfwidth and Fullwidth Forms: only the fullwidth slices are two columns. The rest of the
+	* block is halfwidth katakana / hangul, which `\p{Script=Katakana}` and `\p{Script=Hangul}`
+	* would otherwise count as wide.
+	*/
+	if (codePoint >= 65280 && codePoint <= 65519) {
+		if (codePoint >= 65281 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510) return 2;
+		return 1;
+	}
+	return WIDE.test(ch) ? 2 : 1;
+}
+const segmenter = new Intl.Segmenter();
+/**
+* Measure the columns a terminal draws a string in.
+*
+* @param value - A string to measure
+* @returns The number of columns
+*/
+function displayWidth(value) {
+	let width = 0;
+	for (const { segment } of segmenter.segment(value)) width += graphemeWidth(segment.codePointAt(0));
+	return width;
+}
+/**
+* Pad a string with spaces until it is drawn in the given number of columns.
+*
+* @param value - A string to pad
+* @param width - The number of columns to pad it to
+* @returns The padded string
+*/
+function padEndToWidth(value, width) {
+	const padding = width - displayWidth(value);
+	return padding > 0 ? value + " ".repeat(padding) : value;
+}
+//#endregion
 //#region src/usage.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -428,18 +539,21 @@ async function makeUsageSymbols(ctx) {
 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(async (cmd) => {
-		const desc = cmd.description || "";
-		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}`;
+	const commandSymbols = await Promise.all(loadedCommands.map(async (cmd) => await makeCommandSymbol(ctx, cmd)));
+	const symbolMaxLength = Math.max(...commandSymbols.map((symbol) => displayWidth(symbol)));
+	const commandsStr = (await Promise.all(loadedCommands.map(async (cmd) => await ctx.extensions[pluginId].localizeCommandDescription(cmd)))).map((desc, index) => {
+		const commandStr = commandSymbols[index];
+		const command = desc ? `${padEndToWidth(commandStr, symbolMaxLength + ctx.env.middleMargin)}${desc}` : commandStr;
 		return `${command.padStart(ctx.env.leftMargin + command.length)}`;
-	}));
+	});
 	messages.push(...commandsStr, "", `${await ctx.extensions[pluginId].text(resolveBuiltInKey("FORMORE"))}:`);
-	const basePath = ctx.commandPath && ctx.commandPath.length > 0 ? `${ctx.env.name} ${ctx.commandPath.join(" ")}` : ctx.env.name;
+	/**
+	* NOTE(kazupon): the CLI is named the same way the usage line and the entry row of the section
+	* above name it, because `CliOptions.name` is optional and the block would otherwise invite the
+	* reader to run `undefined --help`.
+	*/
+	const entry = await resolveEntry(ctx);
+	const basePath = ctx.commandPath && ctx.commandPath.length > 0 ? `${entry} ${ctx.commandPath.join(" ")}` : entry;
 	messages.push(...loadedCommands.map((cmd) => {
 		let commandStr = cmd.entry ? "" : cmd.name || "";
 		if (commandStr) commandStr += " ";
@@ -449,9 +563,15 @@ async function renderCommandsSection(ctx) {
 	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 || "";
+	/**
+	* NOTE(kazupon): the row describes `cmd`, so its symbols come from what `cmd` declares.
+	* A lazy command is described by the definition that is given to `lazy`, since the command
+	* list does not run the loader.
+	*/
+	const args = cmd.args || {};
+	const optionSymbol = await generateOptionsSymbols(ctx, args);
+	const positionalSymbol = generatePositionalSymbols(args);
+	let commandStr = cmd.entry ? cmd.name === void 0 || cmd.name === ANONYMOUS_COMMAND_NAME ? `[${await resolveEntry(ctx)}]` : `[${cmd.name}]` : cmd.name || "";
 	if (optionSymbol) {
 		if (commandStr) commandStr += " ";
 		commandStr += `${optionSymbol}`;
@@ -537,7 +657,11 @@ function hasPositionalArgs(args) {
 */
 function hasAllDefaultOptions(args) {
 	const visibleOptionalArgs = getVisibleOptionalArgs(args);
-	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default);
+	/**
+	* NOTE(kazupon): an argument has a default when one is declared, whatever its value. `0`, `''` and
+	* `false` are defaults like any other, and an option that has one is not required (#750).
+	*/
+	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default !== void 0);
 }
 /**
 * Generate options symbols for usage
@@ -556,23 +680,32 @@ async function generateOptionsSymbols(ctx, args) {
 * @returns Options pairs for usage
 */
 function getOptionalArgsPairs(ctx) {
+	/**
+	* NOTE(kazupon): an argument owns the name that it renders under, so the negated form of another
+	* option must not be listed under it (#732). The names are compared as they are rendered, because
+	* `toKebab` can bring two different keys under one name (#743). A `hidden` argument counts: it is
+	* not listed, and neither is a negated form that would take its name.
+	*/
+	const optionNames = resolveOptionNames(ctx.args, ctx.toKebab);
 	return getVisibleOptionalArgs(ctx.args).reduce((acc, [name, schema]) => {
+		const displayName = resolveDisplayName(name, schema, ctx.toKebab);
 		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}>`;
-		}
+		if (schema.type !== "boolean") key = schema.default === void 0 ? `${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[`no-${name}`] = `--no-${displayName}`;
+			const negatedName = `no-${displayName}`;
+			if (!optionNames.has(negatedName)) acc[`no-${name}`] = `--${negatedName}`;
 		}
 		return acc;
 	}, Object.create(null));
 }
-const resolveNegatableKey = (key) => key.split("no-")[1];
+const resolveNegatableKey = (key) => key.slice(3);
 function resolveNegatableType(key, ctx) {
-	return ctx.args[key.startsWith("no-") ? resolveNegatableKey(key) : key].type;
+	/**
+	* NOTE(kazupon): the key of an argument wins over the option that a negated form negates, and a
+	* negated form is a boolean flag whether or not the option it negates can be reached from here.
+	*/
+	return (ctx.args[key] ?? ctx.args[resolveNegatableKey(key)])?.type ?? "boolean";
 }
 async function generateDefaultDisplayValue(ctx, schema) {
 	return `${await ctx.extensions[pluginId].text(resolveBuiltInKey("DEFAULT"))}: ${schema.default}`;
@@ -598,21 +731,26 @@ async function resolveDisplayValue(ctx, key) {
 async function generateOptionalArgsUsage(ctx, optionsPairs) {
 	const optionsPairsEntries = Object.entries(optionsPairs);
 	if (optionsPairsEntries.length === 0) return "";
-	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([_, value]) => value.length));
-	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
+	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([_, value]) => displayWidth(value)));
+	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => displayWidth(resolveNegatableType(key, ctx)))) : 0;
 	return (await Promise.all(optionsPairsEntries.map(async ([key, value]) => {
 		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx.name));
-		if (!rawDesc && key.startsWith("no-")) {
+		if (!rawDesc && !ctx.args[key] && key.startsWith("no-")) {
+			/**
+			* NOTE(kazupon): only a key that no argument answers to may be read as the negated form of
+			* another option, and only when that option is there to be negated.
+			*/
 			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}`;
+			if (schema) {
+				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("no-") ? "" : await resolveDisplayValue(ctx, key);
-		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
-		const descLength = desc.length + valueDesc.length;
-		const option = `${value.padEnd((descLength > 0 ? optionsMaxLength : 0) + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
+		const desc = `${optionsSchema ? padEndToWidth(optionsSchema, optionSchemaMaxLength + 3) : ""}${rawDesc}`;
+		const option = `${padEndToWidth(value, (desc.length + valueDesc.length > 0 ? optionsMaxLength : 0) + ctx.env.middleMargin)}${desc}${valueDesc ? ` ${valueDesc}` : ""}`;
 		return `${option.padStart(ctx.env.leftMargin + option.length)}`;
 	}))).join("\n");
 }
@@ -622,10 +760,10 @@ function getPositionalArgs(args) {
 async function generatePositionalArgsUsage(ctx) {
 	const positionals = getPositionalArgs(ctx.args);
 	if (positionals.length === 0) return "";
-	const argsMaxLength = Math.max(...positionals.map(([name]) => name.length));
+	const argsMaxLength = Math.max(...positionals.map(([name]) => displayWidth(name)));
 	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}`;
+		const arg = `${padEndToWidth(name, argsMaxLength + ctx.env.middleMargin)} ${desc}`;
 		return `${arg.padStart(ctx.env.leftMargin + arg.length)}`;
 	}))).join("\n");
 }
@@ -669,6 +807,10 @@ async function renderValidationError(ctx, error) {
 		const message = await localize(ctx, error.code, error.values);
 		if (message && message !== error.code) return message;
 	}
+	if (isCommandResolutionError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
 	if (isArgsValidationError(error) && error.code) {
 		const values = await resolveValidationValues(ctx, error);
 		const message = await localize(ctx, error.code, values);
@@ -748,7 +890,10 @@ function renderer() {
 			async function loadCommands() {
 				if (cachedCommands) return cachedCommands;
 				const subCommands = [...ctx.env.subCommands || []];
-				cachedCommands = (await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)))).filter((cmd) => !cmd.internal).filter(Boolean);
+				const allCommands = await Promise.all(subCommands.map(async ([name, cmd]) => await resolveLazyCommand(cmd, name)));
+				const entryCommand = ctx.env.entryCommand;
+				if (ctx.callMode === "entry" && subCommands.length > 0 && entryCommand && !subCommands.some(([, command]) => command === entryCommand)) allCommands.push(await resolveLazyCommand(entryCommand, ANONYMOUS_COMMAND_NAME));
+				cachedCommands = allCommands.filter((cmd) => !cmd.internal).filter(Boolean);
 				cachedCommands.sort((a, b) => {
 					if (a.entry && !b.entry) return -1;
 					if (!a.entry && b.entry) return 1;
@@ -759,9 +904,33 @@ function renderer() {
 				});
 				return cachedCommands;
 			}
+			/**
+			* Resolve the description of a command in the command list.
+			*
+			* NOTE(kazupon): the description is localized the way the command's own help localizes it,
+			* which needs that command's resource. `text()` is bound to the command that is running, so it
+			* cannot answer for another one. The i18n plugin loads a resource into the adapter under the
+			* name of the command it is given, and `translate()` reads it back from there (#748).
+			*
+			* @param target - A command from `loadCommands`
+			* @returns The description to show for the command
+			*/
+			async function localizeCommandDescription(target) {
+				const fallback = target.description || "";
+				if (!i18n || !target.name) return fallback;
+				const commandCtx = await createCommandContext({
+					args: target.args,
+					command: target,
+					callMode: target.entry ? "entry" : "subCommand",
+					extensions: {}
+				});
+				await i18n.loadResource(i18n.locale, commandCtx, target);
+				return await i18n.translate(resolveKey("description", target.name)) || fallback;
+			}
 			return {
 				text: localizable(ctx, cmd, i18n?.translate),
-				loadCommands
+				loadCommands,
+				localizeCommandDescription
 			};
 		},
 		setup: (ctx) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-renderer",
   "description": "usage renderer plugin for gunshi",
-  "version": "0.37.2",
+  "version": "1.0.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,10 +53,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.37.2"
+    "@gunshi/plugin": "1.0.0-beta.0"
   },
   "peerDependencies": {
-    "@gunshi/plugin-i18n": "0.37.2"
+    "@gunshi/plugin-i18n": "1.0.0-beta.0"
   },
   "devDependencies": {
     "deno": "^2.7.14",
@@ -64,7 +64,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "@gunshi/shared": "0.37.2"
+    "@gunshi/shared": "1.0.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",