gunshi 0.17.0 → 0.19.0

package/lib/{cli-D2dWSSRj.js → cli-m93bHwFR.js}

@@ -1,6 +1,6 @@
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, create, resolveLazyCommand } from "./utils-BYPzZy9X.js";
-import { createCommandContext } from "./context-BROXRnNP.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-pNEj3FtQ.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, create, resolveLazyCommand } from "./utils-DWRmOGGa.js";
+import { createCommandContext } from "./context-CBDAvGDh.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BDs5T_Z4.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.ts
@@ -11,21 +11,24 @@ import { parseArgs, resolveArgs } from "args-tokens";
 * @param opts A {@link CommandOptions | command options}
 * @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
 */
-async function cli(args, entry, opts = {}) {
-	const tokens = parseArgs(args);
+async function cli(argv, entry, opts = {}) {
+	const tokens = parseArgs(argv);
 	const subCommand = getSubCommand(tokens);
 	const resolvedCommandOptions = resolveCommandOptions(opts, entry);
-	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
+	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions, true);
 	if (!command) throw new Error(`Command not found: ${name || ""}`);
-	const options = resolveArgOptions(command.options);
-	const { values, positionals, rest, error } = resolveArgs(options, tokens, { optionGrouping: true });
+	const args = resolveArguments(command.args);
+	const { values, positionals, rest, error } = resolveArgs(args, tokens, {
+		optionGrouping: true,
+		skipPositional: resolvedCommandOptions.subCommands.size > 0 ? 0 : -1
+	});
 	const omitted = !subCommand;
 	const ctx = await createCommandContext({
-		options,
+		args,
 		values,
 		positionals,
 		rest,
-		args,
+		argv,
 		tokens,
 		omitted,
 		command,
@@ -47,10 +50,11 @@ async function cli(args, entry, opts = {}) {
 		await showValidationErrors(ctx, error);
 		return;
 	}
+	if (!command.run) throw new Error(`'run' not found on Command \`${name || ""}\``);
 	await command.run(ctx);
 }
-function resolveArgOptions(options) {
-	return Object.assign(create(), options, COMMON_OPTIONS);
+function resolveArguments(options) {
+	return Object.assign(create(), options, COMMON_ARGS);
 }
 function resolveCommandOptions(options, entry) {
 	const subCommands = new Map(options.subCommands);
@@ -87,15 +91,15 @@ async function showValidationErrors(ctx, error) {
 	const render = ctx.env.renderValidationErrors || renderValidationErrors;
 	ctx.log(await render(ctx, error));
 }
-async function resolveCommand(sub, entry, options) {
+async function resolveCommand(sub, entry, options, needRunResolving = false) {
 	const omitted = !sub;
 	if (typeof entry === "function") return [void 0, { run: entry }];
-	else if (omitted) return typeof entry === "object" ? [resolveEntryName(entry), await resolveLazyCommand(entry)] : [void 0, void 0];
+	else if (omitted) return typeof entry === "object" ? [resolveEntryName(entry), await resolveLazyCommand(entry, "", needRunResolving)] : [void 0, void 0];
 	else {
-		if (options.subCommands == null || options.subCommands.size === 0) return [resolveEntryName(entry), await resolveLazyCommand(entry)];
+		if (options.subCommands == null || options.subCommands.size === 0) return [resolveEntryName(entry), await resolveLazyCommand(entry, "", needRunResolving)];
 		const cmd = options.subCommands?.get(sub);
 		if (cmd == null) return [sub, void 0];
-		return [sub, await resolveLazyCommand(cmd, sub)];
+		return [sub, await resolveLazyCommand(cmd, sub, needRunResolving)];
 	}
 }
 function resolveEntryName(entry) {

package/lib/{context-BROXRnNP.js → context-CBDAvGDh.js}

@@ -1,14 +1,17 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE$1 as DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveLazyCommand, resolveOptionKey } from "./utils-BYPzZy9X.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE$1 as DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveLazyCommand } from "./utils-DWRmOGGa.js";
 
 //#region src/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 = {
@@ -16,10 +19,13 @@ var en_US_default = {
 	COMMANDS,
 	SUBCOMMAND,
 	USAGE,
+	ARGUMENTS,
 	OPTIONS,
 	EXAMPLES,
 	FORMORE,
 	NEGATABLE,
+	DEFAULT,
+	CHOICES,
 	help,
 	version
 };
@@ -66,11 +72,11 @@ const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
 * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
 * @returns A {@link CommandContext | command context}, which is readonly
 */
-async function createCommandContext({ options, values, positionals, rest, args, tokens, command, commandOptions, omitted = false }) {
+async function createCommandContext({ args, values, positionals, rest, argv, tokens, command, commandOptions, omitted = false }) {
 	/**
 	* normailize the options schema and values, to avoid prototype pollution
 	*/
-	const _options = Object.entries(options).reduce((acc, [key, value]) => {
+	const _args = Object.entries(args).reduce((acc, [key, value]) => {
 		acc[key] = Object.assign(create(), value);
 		return acc;
 	}, create());
@@ -124,11 +130,11 @@ async function createCommandContext({ options, values, positionals, rest, args,
 		omitted,
 		locale,
 		env,
-		options: _options,
+		args: _args,
 		values,
 		positionals,
 		rest,
-		_: args,
+		_: argv,
 		tokens,
 		log: commandOptions.usageSilent ? NOOP : log,
 		loadCommands,
@@ -137,12 +143,12 @@ async function createCommandContext({ options, values, positionals, rest, args,
 	/**
 	* load the command resources
 	*/
-	const loadedOptionsResources = Object.entries(options).map(([key, option]) => {
-		const description = option.description || "";
+	const loadedOptionsResources = Object.entries(args).map(([key, arg]) => {
+		const description = arg.description || "";
 		return [key, description];
 	});
 	const defaultCommandResource = loadedOptionsResources.reduce((res, [key, value]) => {
-		res[resolveOptionKey(key)] = value;
+		res[resolveArgKey(key)] = value;
 		return res;
 	}, create());
 	defaultCommandResource.description = command.description || "";

package/lib/context.d.ts

@@ -1,20 +1,23 @@
-import { Command, CommandContext, CommandOptions } from "./types.d-DomXJWKH.js";
-import { ArgOptions, ArgToken, ArgValues } from "args-tokens";
+import { Command, CommandContext, CommandOptions } from "./types-BVZKXMbJ.js";
+import { ArgToken, ArgValues, Args } from "args-tokens";
 
 //#region src/context.d.ts
 /**
 * Parameters of {@link createCommandContext}
 */
 
-interface CommandContextParams<Options extends ArgOptions, Values> {
+/**
+ * Parameters of {@link createCommandContext}
+ */
+interface CommandContextParams<A extends Args, V> {
   /**
-   * An options of target command
+   * An arguments of target command
    */
-  options: Options;
+  args: A;
   /**
    * A values of target command
    */
-  values: Values;
+  values: V;
   /**
    * A positionals arguments, which passed to the target command
    */
@@ -26,7 +29,7 @@ interface CommandContextParams<Options extends ArgOptions, Values> {
   /**
    * Original command line arguments
    */
-  args: string[];
+  argv: string[];
   /**
    * Argument tokens that are parsed by the `parseArgs` function
    */
@@ -38,26 +41,26 @@ interface CommandContextParams<Options extends ArgOptions, Values> {
   /**
    * A target {@link Command | command}
    */
-  command: Command<Options>;
+  command: Command<A>;
   /**
    * A command options, which is spicialized from `cli` function
    */
-  commandOptions: CommandOptions<Options>;
-} /**
-  * Create a {@link CommandContext | command context}
-  * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
-  * @returns A {@link CommandContext | command context}, which is readonly
-  */
-
-declare function createCommandContext<Options extends ArgOptions = ArgOptions, Values extends ArgValues<Options> = ArgValues<Options>>({
-  options,
+  commandOptions: CommandOptions<A>;
+}
+/**
+ * Create a {@link CommandContext | command context}
+ * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
+ * @returns A {@link CommandContext | command context}, which is readonly
+ */
+declare function createCommandContext<A extends Args = Args, V extends ArgValues<A> = ArgValues<A>>({
+  args,
   values,
   positionals,
   rest,
-  args,
+  argv,
   tokens,
   command,
   commandOptions,
   omitted
-}: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>; //#endregion
+}: CommandContextParams<A, V>): Promise<Readonly<CommandContext<A, V>>>; //#endregion
 export { createCommandContext };

package/lib/context.js

@@ -1,4 +1,4 @@
-import "./utils-BYPzZy9X.js";
-import { createCommandContext } from "./context-BROXRnNP.js";
+import "./utils-DWRmOGGa.js";
+import { createCommandContext } from "./context-CBDAvGDh.js";
 
 export { createCommandContext };

package/lib/definition-Bdw7cMea.d.ts

@@ -0,0 +1,26 @@
+import { Command, CommandLoader, LazyCommand } from "./types-BVZKXMbJ.js";
+import { ArgSchema, ArgValues as ArgValues$1, Args, Args as Args$1 } from "args-tokens";
+
+//#region src/definition.d.ts
+/**
+* Define a {@link Command | command} with type inference
+* @param definition A {@link Command | command} definition
+* @returns A {@link Command | command} definition with type inference
+*/
+
+/**
+ * Define a {@link Command | command} with type inference
+ * @param definition A {@link Command | command} definition
+ * @returns A {@link Command | command} definition with type inference
+ */
+declare function define<A extends Args = Args>(definition: Command<A>): Command<A>;
+/**
+ * Define a {@link LazyCommand | lazy command} with command loader, which is attached with command definition as usage metadata.
+ * @param loader A {@link CommandLoader | command loader}
+ * @param definition A {@link Command | command} definition
+ * @returns A {@link LazyCommand | lazy command} loader
+ */
+declare function lazy<A extends Args = Args>(loader: CommandLoader<A>, definition?: Command<A>): LazyCommand<A>;
+
+//#endregion
+export { ArgSchema, ArgValues$1 as ArgValues, Args$1 as Args, define as define$1, lazy as lazy$1 };

package/lib/definition-DyVBFqB7.js

@@ -0,0 +1,28 @@
+//#region src/definition.ts
+/**
+* Define a {@link Command | command} with type inference
+* @param definition A {@link Command | command} definition
+* @returns A {@link Command | command} definition with type inference
+*/
+function define(definition) {
+	return definition;
+}
+/**
+* Define a {@link LazyCommand | lazy command} with command loader, which is attached with command definition as usage metadata.
+* @param loader A {@link CommandLoader | command loader}
+* @param definition A {@link Command | command} definition
+* @returns A {@link LazyCommand | lazy command} loader
+*/
+function lazy(loader, definition) {
+	if (definition != null) {
+		loader.commandName = definition.name;
+		loader.description = definition.description;
+		loader.args = definition.args;
+		loader.examples = definition.examples;
+		loader.resource = definition.resource;
+	}
+	return loader;
+}
+
+//#endregion
+export { define, lazy };

package/lib/definition.d.ts

@@ -1,3 +1,3 @@
-import "./types.d-DomXJWKH.js";
-import { ArgOptionSchema, ArgOptions, ArgValues, define$1 as define } from "./definition.d-wYlroF3H.js";
-export { ArgOptionSchema, ArgOptions, ArgValues, define };
+import "./types-BVZKXMbJ.js";
+import { ArgSchema, ArgValues, Args, define$1 as define, lazy$1 as lazy } from "./definition-Bdw7cMea.js";
+export { ArgSchema, ArgValues, Args, define, lazy };

package/lib/definition.js

@@ -1,3 +1,3 @@
-import { define } from "./definition-VzcnM0si.js";
+import { define, lazy } from "./definition-DyVBFqB7.js";
 
-export { define };
+export { define, lazy };

package/lib/generator.d.ts

@@ -1,5 +1,5 @@
-import { Command, CommandOptions } from "./types.d-DomXJWKH.js";
-import { ArgOptions } from "args-tokens";
+import { Command, CommandOptions } from "./types-BVZKXMbJ.js";
+import { Args } from "args-tokens";
 
 //#region src/generator.d.ts
 /**
@@ -10,7 +10,14 @@ import { ArgOptions } from "args-tokens";
 * @returns A rendered usage.
 */
 
-declare function generate<Options extends ArgOptions = ArgOptions>(command: string | null, entry: Command<Options>, opts?: CommandOptions<Options>): Promise<string>;
+/**
+ * Generate the command usage.
+ * @param command - usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`.
+ * @param entry - A {@link Command | entry command}
+ * @param opts - A {@link CommandOptions | command options}
+ * @returns A rendered usage.
+ */
+declare function generate<A extends Args = Args>(command: string | null, entry: Command<A>, opts?: CommandOptions<A>): Promise<string>;
 
 //#endregion
 export { generate };

package/lib/generator.js

@@ -1,7 +1,7 @@
-import { create } from "./utils-BYPzZy9X.js";
-import "./context-BROXRnNP.js";
-import "./renderer-pNEj3FtQ.js";
-import { cli } from "./cli-D2dWSSRj.js";
+import { create } from "./utils-DWRmOGGa.js";
+import "./context-CBDAvGDh.js";
+import "./renderer-BDs5T_Z4.js";
+import { cli } from "./cli-m93bHwFR.js";
 
 //#region src/generator.ts
 /**

package/lib/index.d.ts

@@ -1,6 +1,6 @@
-import { Command, CommandBuiltinKeys, CommandBuiltinOptionsKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandOptionKeys, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgOptions, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions } from "./types.d-DomXJWKH.js";
-import { define$1 as define } from "./definition.d-wYlroF3H.js";
-import { ArgOptionSchema, ArgOptions, ArgOptions as ArgOptions$1, ArgValues, parseArgs, resolveArgs } from "args-tokens";
+import { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions } from "./types-BVZKXMbJ.js";
+import { define$1 as define, lazy$1 as lazy } from "./definition-Bdw7cMea.js";
+import { ArgSchema, ArgValues, Args, Args as Args$1, parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.d.ts
 /**
@@ -11,7 +11,14 @@ import { ArgOptionSchema, ArgOptions, ArgOptions as ArgOptions$1, ArgValues, par
 * @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
 */
 
-declare function cli<Options extends ArgOptions$1 = ArgOptions$1>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
+/**
+ * Run the command.
+ * @param args Command line arguments
+ * @param entry A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
+ * @param opts A {@link CommandOptions | command options}
+ * @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
+ */
+declare function cli<A extends Args$1 = Args$1>(argv: string[], entry: Command<A> | CommandRunner<A>, opts?: CommandOptions<A>): Promise<string | undefined>;
 
 //#endregion
 //#region src/translation.d.ts
@@ -25,4 +32,4 @@ declare class DefaultTranslation implements TranslationAdapter {
 }
 
 //#endregion
-export { ArgOptionSchema, ArgOptions, ArgValues, Command, CommandBuiltinKeys, CommandBuiltinOptionsKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandOptionKeys, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, DefaultTranslation, GenerateNamespacedKey, KeyOfArgOptions, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, cli, define, parseArgs, resolveArgs };
+export { ArgSchema, ArgValues, Args, Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, DefaultTranslation, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, cli, define, lazy, parseArgs, resolveArgs };

package/lib/index.js

@@ -1,8 +1,8 @@
-import { DEFAULT_LOCALE$1 as DEFAULT_LOCALE } from "./utils-BYPzZy9X.js";
-import { DefaultTranslation } from "./context-BROXRnNP.js";
-import { define } from "./definition-VzcnM0si.js";
-import "./renderer-pNEj3FtQ.js";
-import { cli } from "./cli-D2dWSSRj.js";
+import { DEFAULT_LOCALE$1 as DEFAULT_LOCALE } from "./utils-DWRmOGGa.js";
+import { DefaultTranslation } from "./context-CBDAvGDh.js";
+import { define, lazy } from "./definition-DyVBFqB7.js";
+import "./renderer-BDs5T_Z4.js";
+import { cli } from "./cli-m93bHwFR.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
-export { DEFAULT_LOCALE, DefaultTranslation, cli, define, parseArgs, resolveArgs };
+export { DEFAULT_LOCALE, DefaultTranslation, cli, define, lazy, parseArgs, resolveArgs };

package/lib/locales/en-US.json

@@ -3,10 +3,13 @@
   "COMMANDS": "COMMANDS",
   "SUBCOMMAND": "SUBCOMMAND",
   "USAGE": "USAGE",
+  "ARGUMENTS": "ARGUMENTS",
   "OPTIONS": "OPTIONS",
   "EXAMPLES": "EXAMPLES",
   "FORMORE": "For more info, run any command with the `--help` flag:",
   "NEGATABLE": "Negatable of",
+  "DEFAULT": "default",
+  "CHOICES": "choices",
   "help": "Display this help message",
   "version": "Display this version"
 }

package/lib/locales/ja-JP.json

@@ -3,10 +3,13 @@
   "COMMANDS": "コマンド",
   "SUBCOMMAND": "サブコマンド",
   "USAGE": "使い方",
+  "ARGUMENTS": "引数",
   "OPTIONS": "オプション",
   "EXAMPLES": "例",
   "FORMORE": "詳細は、コマンドと`--help`フラグを実行してください:",
   "NEGATABLE": "否定可能な",
+  "DEFAULT": "デフォルト",
+  "CHOICES": "選択肢",
   "help": "このヘルプメッセージを表示",
   "version": "このバージョンを表示"
 }

package/lib/{renderer-pNEj3FtQ.js → renderer-BDs5T_Z4.js}

@@ -1,4 +1,4 @@
-import { create, resolveBuiltInKey, resolveOptionKey } from "./utils-BYPzZy9X.js";
+import { COMMON_ARGS, create, resolveArgKey, resolveBuiltInKey } from "./utils-DWRmOGGa.js";
 
 //#region src/renderer/header.ts
 /**
@@ -13,6 +13,7 @@ function renderHeader(ctx) {
 
 //#endregion
 //#region src/renderer/usage.ts
+const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
 /**
 * Render the usage.
 * @param ctx A {@link CommandContext | command context}
@@ -26,20 +27,32 @@ async function renderUsage(ctx) {
 	}
 	messages.push(...await renderUsageSection(ctx), "");
 	if (ctx.omitted && await hasCommands(ctx)) messages.push(...await renderCommandsSection(ctx), "");
-	if (hasOptions(ctx)) messages.push(...await renderOptionsSection(ctx), "");
+	if (hasPositionalArgs(ctx)) messages.push(...await renderPositionalArgsSection(ctx), "");
+	if (hasOptionalArgs(ctx)) messages.push(...await renderOptionalArgsSection(ctx), "");
 	const examples = renderExamplesSection(ctx);
 	if (examples.length > 0) messages.push(...examples, "");
 	return messages.join("\n");
 }
 /**
-* Render the options section
+* 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(`${ctx.translate(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 renderOptionsSection(ctx) {
+async function renderOptionalArgsSection(ctx) {
 	const messages = [];
 	messages.push(`${ctx.translate(resolveBuiltInKey("OPTIONS"))}:`);
-	messages.push(await generateOptionsUsage(ctx, getOptionsPairs(ctx)));
+	messages.push(await generateOptionalArgsUsage(ctx, getOptionalArgsPairs(ctx)));
 	return messages;
 }
 /**
@@ -64,14 +77,14 @@ function renderExamplesSection(ctx) {
 async function renderUsageSection(ctx) {
 	const messages = [`${ctx.translate(resolveBuiltInKey("USAGE"))}:`];
 	if (ctx.omitted) {
-		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${hasOptions(ctx) ? `<${ctx.translate(resolveBuiltInKey("OPTIONS"))}>` : ""} `;
+		const defaultCommand = `${resolveEntry(ctx)}${await hasCommands(ctx) ? ` [${resolveSubCommand(ctx)}]` : ""} ${[generateOptionsSymbols(ctx), generatePositionalSymbols(ctx)].filter(Boolean).join(" ")}`;
 		messages.push(defaultCommand.padStart(ctx.env.leftMargin + defaultCommand.length));
 		if (await hasCommands(ctx)) {
 			const commandsUsage = `${resolveEntry(ctx)} <${ctx.translate(resolveBuiltInKey("COMMANDS"))}>`;
 			messages.push(commandsUsage.padStart(ctx.env.leftMargin + commandsUsage.length));
 		}
 	} else {
-		const usageStr = `${resolveEntry(ctx)} ${resolveSubCommand(ctx)} ${generateOptionsSymbols(ctx)}`;
+		const usageStr = `${resolveEntry(ctx)} ${resolveSubCommand(ctx)} ${[generateOptionsSymbols(ctx), generatePositionalSymbols(ctx)].filter(Boolean).join(" ")}`;
 		messages.push(usageStr.padStart(ctx.env.leftMargin + usageStr.length));
 	}
 	return messages;
@@ -143,12 +156,20 @@ async function hasCommands(ctx) {
 	return loadedCommands.length > 1;
 }
 /**
-* Check if the command has options
+* Check if the command has optional arguments
 * @param ctx A {@link CommandContext | command context}
 * @returns True if the command has options
 */
-function hasOptions(ctx) {
-	return !!(ctx.options && Object.keys(ctx.options).length > 0);
+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
@@ -156,7 +177,7 @@ function hasOptions(ctx) {
 * @returns True if all options have default values
 */
 function hasAllDefaultOptions(ctx) {
-	return !!(ctx.options && Object.values(ctx.options).every((opt) => opt.default));
+	return !!(ctx.args && Object.values(ctx.args).every((arg) => arg.default));
 }
 /**
 * Generate options symbols for usage
@@ -164,7 +185,7 @@ function hasAllDefaultOptions(ctx) {
 * @returns Options symbols for usage
 */
 function generateOptionsSymbols(ctx) {
-	return hasOptions(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translate(resolveBuiltInKey("OPTIONS"))}]` : `<${ctx.translate(resolveBuiltInKey("OPTIONS"))}>` : "";
+	return hasOptionalArgs(ctx) ? hasAllDefaultOptions(ctx) ? `[${ctx.translate(resolveBuiltInKey("OPTIONS"))}]` : `<${ctx.translate(resolveBuiltInKey("OPTIONS"))}>` : "";
 }
 function makeShortLongOptionPair(schema, name) {
 	let key = `--${name}`;
@@ -172,47 +193,79 @@ function makeShortLongOptionPair(schema, name) {
 	return key;
 }
 /**
-* Get options pairs for usage
+* Get optional arguments pairs for usage
 * @param ctx A {@link CommandContext | command context}
 * @returns Options pairs for usage
 */
-function getOptionsPairs(ctx) {
-	return Object.entries(ctx.options).reduce((acc, [name, value]) => {
+function getOptionalArgsPairs(ctx) {
+	return Object.entries(ctx.args).reduce((acc, [name, value]) => {
+		if (value.type === "positional") return acc;
 		let key = makeShortLongOptionPair(value, name);
 		if (value.type !== "boolean") key = value.default ? `${key} [${name}]` : `${key} <${name}>`;
 		acc[name] = key;
-		if (value.type === "boolean" && value.negatable && !(name === "help" || name === "version")) acc[`no-${name}`] = `--no-${name}`;
+		if (value.type === "boolean" && value.negatable && !COMMON_ARGS_KEYS.includes(name)) acc[`no-${name}`] = `--no-${name}`;
 		return acc;
 	}, create());
 }
 const resolveNegatableKey = (key) => key.split("no-")[1];
 function resolveNegatableType(key, ctx) {
-	return ctx.options[key.startsWith("no-") ? resolveNegatableKey(key) : key].type;
+	return ctx.args[key.startsWith("no-") ? resolveNegatableKey(key) : key].type;
+}
+function generateDefaultDisplayValue(ctx, schema) {
+	return `${ctx.translate(resolveBuiltInKey("DEFAULT"))}: ${schema.default}`;
+}
+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.default !== void 0) return `(${generateDefaultDisplayValue(ctx, schema)})`;
+	if (schema.type === "enum") {
+		const _default = schema.default !== void 0 ? generateDefaultDisplayValue(ctx, schema) : "";
+		const choices = `${ctx.translate(resolveBuiltInKey("CHOICES"))}: ${schema.choices.join(" | ")}`;
+		return `(${_default ? `${_default}, ${choices}` : choices})`;
+	}
+	return "";
 }
 /**
-* Generate options usage
+* Generate optional arguments usage
 * @param ctx A {@link CommandContext | command context}
 * @param optionsPairs Options pairs for usage
 * @returns Generated options usage
 */
-async function generateOptionsUsage(ctx, optionsPairs) {
+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 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(([key, value]) => {
-		let rawDesc = ctx.translate(resolveOptionKey(key));
+		let rawDesc = ctx.translate(resolveArgKey(key));
 		if (!rawDesc && key.startsWith("no-")) {
 			const name = resolveNegatableKey(key);
-			const schema = ctx.options[name];
+			const schema = ctx.args[name];
 			const optionKey = makeShortLongOptionPair(schema, name);
 			rawDesc = `${ctx.translate(resolveBuiltInKey("NEGATABLE"))} ${optionKey}`;
 		}
 		const optionsSchema = ctx.env.usageOptionType ? `[${resolveNegatableType(key, ctx)}] ` : "";
+		const valueDesc = key.startsWith("no-") ? "" : resolveDisplayValue(ctx, key);
 		const desc = `${optionsSchema ? optionsSchema.padEnd(optionSchemaMaxLength + 3) : ""}${rawDesc}`;
-		const option = `${value.padEnd(optionsMaxLength + ctx.env.middleMargin)}${desc}`;
+		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(([name]) => {
+		const desc = ctx.translate(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/renderer/validation.ts

package/lib/renderer.d.ts

@@ -1,5 +1,5 @@
-import { CommandContext } from "./types.d-DomXJWKH.js";
-import { ArgOptions } from "args-tokens";
+import { CommandContext } from "./types-BVZKXMbJ.js";
+import { Args } from "args-tokens";
 
 //#region src/renderer/header.d.ts
 /**
@@ -8,26 +8,31 @@ import { ArgOptions } from "args-tokens";
 * @returns A rendered header.
 */
 
-declare function renderHeader<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+/**
+ * Render the header.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A rendered header.
+ */
+declare function renderHeader<A extends Args = Args>(ctx: Readonly<CommandContext<A>>): Promise<string>;
 
 //#endregion
 //#region src/renderer/usage.d.ts
 /**
-* Render the usage.
-* @param ctx A {@link CommandContext | command context}
-* @returns A rendered usage.
-*/
-declare function renderUsage<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+ * Render the usage.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A rendered usage.
+ */
+declare function renderUsage<A extends Args = Args>(ctx: Readonly<CommandContext<A>>): Promise<string>;
 
 //#endregion
 //#region src/renderer/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<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
+ * 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<A extends Args = Args>(_ctx: CommandContext<A>, error: AggregateError): Promise<string>;
 
 //#endregion
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/renderer.js

@@ -1,4 +1,4 @@
-import "./utils-BYPzZy9X.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-pNEj3FtQ.js";
+import "./utils-DWRmOGGa.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BDs5T_Z4.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{types.d-DomXJWKH.d.ts → types-BVZKXMbJ.d.ts}

@@ -1,18 +1,18 @@
-import { ArgOptions, ArgToken, ArgValues } from "args-tokens";
+import { ArgToken, ArgValues, Args } from "args-tokens";
 
 //#region rolldown:runtime
 declare namespace constants_d_exports {
-  export { BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, OPTION_PREFIX };
+  export { ARG_PREFIX, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, DEFAULT_LOCALE, NOOP };
 }
 /**
-* The default locale string, which format is BCP 47 language tag.
-*/
+ * The default locale string, which format is BCP 47 language tag.
+ */
 declare const DEFAULT_LOCALE = "en-US";
 declare const BUILT_IN_PREFIX = "_";
-declare const OPTION_PREFIX = "Option";
+declare const ARG_PREFIX = "arg";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
 declare const NOOP: () => void;
-type CommonOptionType = {
+type CommonArgType = {
   readonly help: {
     readonly type: 'boolean';
     readonly short: 'h';
@@ -24,52 +24,45 @@ type CommonOptionType = {
     readonly description: string;
   };
 };
-declare const COMMON_OPTIONS: CommonOptionType;
-declare const COMMAND_OPTIONS_DEFAULT: CommandOptions<ArgOptions>;
-declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE"];
+declare const COMMON_ARGS: CommonArgType;
+declare const COMMAND_OPTIONS_DEFAULT: CommandOptions<Args>;
+declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
 
 //#endregion
 //#region src/types.d.ts
 type Awaitable<T> = T | Promise<T>;
 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.
-*/
+ * Remove index signature from object or record type.
+ */
 type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
-type KeyOfArgOptions<Options extends ArgOptions> = keyof Options | { [K in keyof Options]: Options[K]['type'] extends 'boolean' ? Options[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof Options];
-
+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.
-*/
+ * 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 options keys.
-*/
-type CommandBuiltinOptionsKeys = keyof (typeof constants_d_exports)['COMMON_OPTIONS'];
-
+ * Command i18n built-in arguments keys.
+ */
+type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
 /**
-* Command i18n built-in resource keys.
-*/
+ * Command i18n built-in resource keys.
+ */
 type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
-
 /**
-* Command i18n built-in keys.
-* The command i18n built-in keys are used to {@link CommandContext.translate | translate} function.
-*/
-type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinOptionsKeys> | GenerateNamespacedKey<CommandBuiltinResourceKeys> | 'description' | 'examples';
-
+ * Command i18n built-in keys.
+ * The command i18n built-in keys are used to {@link CommandContext.translate | translate} function.
+ */
+type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinArgsKeys> | GenerateNamespacedKey<CommandBuiltinResourceKeys> | 'description' | 'examples';
 /**
-* Command i18n option keys.
-* The command i18n option keys are used to {@link CommandContext.translate | translate} function.
-*/
-type CommandOptionKeys<Options extends ArgOptions> = GenerateNamespacedKey<KeyOfArgOptions<RemovedIndex<Options>>, typeof OPTION_PREFIX>;
-
+ * Command i18n option keys.
+ * The command i18n option keys are used to {@link CommandContext.translate | translate} function.
+ */
+type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
 /**
-* Command environment.
-*/
-interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
+ * Command environment.
+ */
+interface CommandEnvironment<A extends Args = Args> {
   /**
    * Current working directory.
    * @see {@link CommandOptions.cwd}
@@ -109,10 +102,16 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
    * @see {@link CommandOptions.usageOptionType}
    */
   usageOptionType: boolean;
+  /**
+   * Whether to display the option value.
+   * @default true
+   * @see {@link CommandOptions.usageOptionValue}
+   */
+  usageOptionValue: boolean;
   /**
    * Whether to display the command usage.
    * @default false
-   * @see {@link}
+   * @see {@link CommandOptions.usageSilent}
    */
   usageSilent: boolean;
   /**
@@ -123,21 +122,20 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
   /**
    * Render function the command usage.
    */
-  renderUsage: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
+  renderUsage: ((ctx: CommandContext<A>) => Promise<string>) | null | undefined;
   /**
    * Render function the header section in the command usage.
    */
-  renderHeader: ((ctx: CommandContext<Options>) => Promise<string>) | null | undefined;
+  renderHeader: ((ctx: CommandContext<A>) => Promise<string>) | null | undefined;
   /**
    * Render function the validation errors.
    */
-  renderValidationErrors: ((ctx: CommandContext<Options>, error: AggregateError) => Promise<string>) | null | undefined;
+  renderValidationErrors: ((ctx: CommandContext<A>, error: AggregateError) => Promise<string>) | null | undefined;
 }
-
 /**
-* Command options.
-*/
-interface CommandOptions<Options extends ArgOptions = ArgOptions> {
+ * Command options.
+ */
+interface CommandOptions<A extends Args = Args> {
   /**
    * Current working directory.
    */
@@ -172,9 +170,13 @@ interface CommandOptions<Options extends ArgOptions = ArgOptions> {
    */
   middleMargin?: number;
   /**
-   * Whether to display the usage option type.
+   * Whether to display the usage optional argument type.
    */
   usageOptionType?: boolean;
+  /**
+   * Whether to display the optional argument value.
+   */
+  usageOptionValue?: boolean;
   /**
    * Whether to display the command usage.
    */
@@ -182,25 +184,25 @@ interface CommandOptions<Options extends ArgOptions = ArgOptions> {
   /**
    * Render function the command usage.
    */
-  renderUsage?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
+  renderUsage?: ((ctx: Readonly<CommandContext<A>>) => Promise<string>) | null;
   /**
    * Render function the header section in the command usage.
    */
-  renderHeader?: ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | null;
+  renderHeader?: ((ctx: Readonly<CommandContext<A>>) => Promise<string>) | null;
   /**
    * Render function the validation errors.
    */
-  renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
+  renderValidationErrors?: ((ctx: Readonly<CommandContext<A>>, error: AggregateError) => Promise<string>) | null;
   /**
    * Translation adapter factory.
    */
   translationAdapterFactory?: TranslationAdapterFactory;
 }
 /**
-* Command context.
-* Command context is the context of the command execution.
-*/
-interface CommandContext<Options extends ArgOptions = ArgOptions, Values = ArgValues<Options>> {
+ * Command context.
+ * Command context is the context of the command execution.
+ */
+interface CommandContext<A extends Args = Args, V = ArgValues<A>> {
   /**
    * Command name, that is the command that is executed.
    * The command name is same {@link CommandEnvironment.name}.
@@ -219,17 +221,17 @@ interface CommandContext<Options extends ArgOptions = ArgOptions, Values = ArgVa
    * Command environment, that is the environment of the command that is executed.
    * The command environment is same {@link CommandEnvironment}.
    */
-  env: Readonly<CommandEnvironment<Options>>;
+  env: Readonly<CommandEnvironment<A>>;
   /**
-   * Command options, that is the options of the command that is executed.
-   * The command options is same {@link Command.options}.
+   * Command arguments, that is the arguments of the command that is executed.
+   * The command arguments is same {@link Command.args}.
    */
-  options: Options;
+  args: A;
   /**
    * Command values, that is the values of the command that is executed.
-   * Resolve values with `resolveArgs` from command arguments and {@link Command.options}.
+   * Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
    */
-  values: Values;
+  values: V;
   /**
    * Command positionals arguments, that is the positionals of the command that is executed.
    * Resolve positionals with `resolveArgs` from command arguments.
@@ -264,19 +266,19 @@ interface CommandContext<Options extends ArgOptions = ArgOptions, Values = ArgVa
    * The loaded commands are cached and returned when called again.
    * @returns loaded commands.
    */
-  loadCommands: () => Promise<Command<Options>[]>;
+  loadCommands: () => Promise<Command<A>[]>;
   /**
    * Translate function.
    * @param key the key to be translated
    * @param values the values to be formatted
    * @returns A translated string.
    */
-  translate: <T extends string = CommandBuiltinKeys, O = CommandOptionKeys<Options>, Key = CommandBuiltinKeys | O | T>(key: Key, values?: Record<string, unknown>) => string;
-} /**
-  * Command interface.
-  */
-
-interface Command<Options extends ArgOptions = ArgOptions> {
+  translate: <T extends string = CommandBuiltinKeys, O = CommandArgKeys<A>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>) => string;
+}
+/**
+ * Command interface.
+ */
+interface Command<A extends Args = Args> {
   /**
    * Command name.
    * It's used to find command line arguments to execute from sub commands, and it's recommended to specify.
@@ -288,10 +290,10 @@ interface Command<Options extends ArgOptions = ArgOptions> {
    */
   description?: string;
   /**
-   * Command options.
-   * Each option can include a description property to describe the option in usage.
+   * Command arguments.
+   * Each argument can include a description property to describe the argument in usage.
    */
-  options?: Options;
+  args?: A;
   /**
    * Command examples.
    * examples of how to use the command.
@@ -300,16 +302,16 @@ interface Command<Options extends ArgOptions = ArgOptions> {
   /**
    * Command runner. it's the command to be executed
    */
-  run: CommandRunner<Options>;
+  run?: CommandRunner<A>;
   /**
    * Command resource fetcher.
    */
-  resource?: CommandResourceFetcher<Options>;
-} /**
-  * Command resource.
-  */
-
-type CommandResource<Options extends ArgOptions = ArgOptions> = {
+  resource?: CommandResourceFetcher<A>;
+}
+/**
+ * Command resource.
+ */
+type CommandResource<A extends Args = Args> = {
   /**
    * Command description.
    */
@@ -318,22 +320,22 @@ type CommandResource<Options extends ArgOptions = ArgOptions> = {
    * Examples usage.
    */
   examples: string;
-} & { [Option in GenerateNamespacedKey<KeyOfArgOptions<RemovedIndex<Options>>, typeof OPTION_PREFIX>]: string } & {
+} & { [Arg in GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>]: string } & {
   [key: string]: string;
-}; /**
-   * Command resource fetcher.
-   * @param ctx A {@link CommandContext | command context}
-   * @returns A fetched {@link CommandResource | command resource}.
-   */
-
-type CommandResourceFetcher<Options extends ArgOptions = ArgOptions, Values = ArgValues<Options>> = (ctx: Readonly<CommandContext<Options, Values>>) => Promise<CommandResource<Options>>; /**
-                                                                                                                                                                                           * Translation adapter factory.
-                                                                                                                                                                                           */
-
-type TranslationAdapterFactory = (options: TranslationAdapterFactoryOptions) => TranslationAdapter; /**
-                                                                                                    * Translation adapter factory options.
-                                                                                                    */
-
+};
+/**
+ * Command resource fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched {@link CommandResource | command resource}.
+ */
+type CommandResourceFetcher<A extends Args = Args, V = ArgValues<A>> = (ctx: Readonly<CommandContext<A, V>>) => Promise<CommandResource<A>>;
+/**
+ * Translation adapter factory.
+ */
+type TranslationAdapterFactory = (options: TranslationAdapterFactoryOptions) => TranslationAdapter;
+/**
+ * Translation adapter factory options.
+ */
 interface TranslationAdapterFactoryOptions {
   /**
    * A locale.
@@ -343,12 +345,12 @@ interface TranslationAdapterFactoryOptions {
    * A fallback locale.
    */
   fallbackLocale: string;
-} /**
-  * Translation adapter.
-  * This adapter is used to custom message formatter like {@link https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf | Intlify message format}, {@link https://github.com/tc39/proposal-intl-messageformat | `Intl.MessageFormat` (MF2)}, and etc.
-  * This adapter will support localization with your preferred message format.
-  */
-
+}
+/**
+ * Translation adapter.
+ * This adapter is used to custom message formatter like {@link https://github.com/intlify/vue-i18n/blob/master/spec/syntax.ebnf | Intlify message format}, {@link https://github.com/tc39/proposal-intl-messageformat | `Intl.MessageFormat` (MF2)}, and etc.
+ * This adapter will support localization with your preferred message format.
+ */
 interface TranslationAdapter<MessageResource = string> {
   /**
    * Get a resource of locale.
@@ -377,19 +379,29 @@ interface TranslationAdapter<MessageResource = string> {
    * @returns A translated message, if message is not translated, return `undefined`.
    */
   translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
-} /**
-  * Command runner.
-  * @param ctx A {@link CommandContext | command context}
-  */
-
-type CommandRunner<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>; /**
-                                                                                                                           * Lazy command interface.
-                                                                                                                           * Lazy command that's not loaded until it is executed.
-                                                                                                                           */
-
-type LazyCommand<Options extends ArgOptions = ArgOptions> = () => Awaitable<Command<Options>>; /**
-                                                                                               * Define a command type.
-                                                                                               */
-
-type Commandable<Options extends ArgOptions> = Command<Options> | LazyCommand<Options>; //#endregion
-export { Command, CommandBuiltinKeys, CommandBuiltinOptionsKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandOptionKeys, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgOptions, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions };
+}
+/**
+ * Command runner.
+ * @param ctx A {@link CommandContext | command context}
+ */
+type CommandRunner<A extends Args = Args> = (ctx: Readonly<CommandContext<A>>) => Awaitable<void>;
+type CommandLoader<A extends Args = Args> = () => Awaitable<Command<A> | CommandRunner<A>>;
+/**
+ * Lazy command interface.
+ * Lazy command that's not loaded until it is executed.
+ */
+type LazyCommand<A extends Args = Args> = {
+  /**
+   * Command load function
+   */
+  (): Awaitable<Command<A> | CommandRunner<A>>;
+  /**
+   * Command name
+   */
+  commandName?: string;
+} & Omit<Command<A>, 'run' | 'name'>;
+/**
+ * Define a command type.
+ */
+type Commandable<A extends Args> = Command<A> | LazyCommand<A>; //#endregion
+export { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions };

package/lib/{utils-BYPzZy9X.js → utils-DWRmOGGa.js}

@@ -4,10 +4,10 @@
 */
 const DEFAULT_LOCALE = "en-US";
 const BUILT_IN_PREFIX = "_";
-const OPTION_PREFIX = "Option";
+const ARG_PREFIX = "arg";
 const BUILT_IN_KEY_SEPARATOR = ":";
 const NOOP = () => {};
-const COMMON_OPTIONS = {
+const COMMON_ARGS = {
 	help: {
 		type: "boolean",
 		short: "h",
@@ -29,6 +29,7 @@ const COMMAND_OPTIONS_DEFAULT = {
 	leftMargin: 2,
 	middleMargin: 10,
 	usageOptionType: false,
+	usageOptionValue: true,
 	renderHeader: void 0,
 	renderUsage: void 0,
 	renderValidationErrors: void 0,
@@ -37,16 +38,38 @@ const COMMAND_OPTIONS_DEFAULT = {
 
 //#endregion
 //#region src/utils.ts
-async function resolveLazyCommand(cmd, name) {
-	const resolved = Object.assign(create(), typeof cmd == "function" ? await cmd() : cmd);
-	if (resolved.name == null && name) resolved.name = name;
-	return deepFreeze(resolved);
+async function resolveLazyCommand(cmd, name, needRunResolving = false) {
+	let command;
+	if (typeof cmd === "function") {
+		command = Object.assign(create(), {
+			name: cmd.commandName,
+			description: cmd.description,
+			args: cmd.args,
+			examples: cmd.examples,
+			resource: cmd.resource
+		});
+		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;
+				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 resolveBuiltInKey(key) {
 	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
-function resolveOptionKey(key) {
-	return `${OPTION_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+function resolveArgKey(key) {
+	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
 function mapResourceWithBuiltinKey(resource) {
 	return Object.entries(resource).reduce((acc, [key, value]) => {
@@ -70,4 +93,4 @@ function deepFreeze(obj) {
 }
 
 //#endregion
-export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE as DEFAULT_LOCALE$1, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveBuiltInKey, resolveLazyCommand, resolveOptionKey };
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, DEFAULT_LOCALE as DEFAULT_LOCALE$1, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveBuiltInKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -30,6 +30,7 @@
     "node": ">= 20"
   },
   "type": "module",
+  "sideEffects": false,
   "files": [
     "lib"
   ],
@@ -77,7 +78,7 @@
     }
   },
   "dependencies": {
-    "args-tokens": "^0.16.0"
+    "args-tokens": "^0.17.1"
   },
   "devDependencies": {
     "@eslint/markdown": "^6.4.0",
@@ -85,10 +86,10 @@
     "@kazupon/eslint-config": "^0.29.0",
     "@kazupon/prettier-config": "^0.1.1",
     "@types/node": "^22.15.3",
-    "@vitest/eslint-plugin": "^1.1.43",
+    "@vitest/eslint-plugin": "^1.1.44",
     "bumpp": "^10.1.0",
-    "deno": "^2.2.12",
-    "eslint": "^9.25.1",
+    "deno": "^2.3.1",
+    "eslint": "^9.26.0",
     "eslint-config-prettier": "^10.1.2",
     "eslint-import-resolver-typescript": "^4.3.4",
     "eslint-plugin-import": "^2.31.0",
@@ -98,27 +99,27 @@
     "eslint-plugin-regexp": "^2.7.0",
     "eslint-plugin-unicorn": "^58.0.0",
     "eslint-plugin-unused-imports": "^4.1.4",
-    "eslint-plugin-vue": "^10.0.1",
+    "eslint-plugin-vue": "^10.1.0",
     "eslint-plugin-vue-composable": "^1.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "gh-changelogen": "^0.2.8",
     "jsr": "^0.13.4",
     "jsr-exports-lint": "^0.2.0",
-    "knip": "^5.50.5",
+    "knip": "^5.53.0",
     "lint-staged": "^15.5.1",
     "messageformat": "4.0.0-10",
     "pkg-pr-new": "^0.0.43",
     "prettier": "^3.5.3",
     "publint": "^0.3.12",
-    "tsdown": "^0.10.0",
-    "typedoc": "^0.28.3",
+    "tsdown": "^0.10.2",
+    "typedoc": "^0.28.4",
     "typedoc-plugin-markdown": "^4.6.3",
     "typedoc-vitepress-theme": "^1.1.2",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.31.1",
     "vitepress": "^1.6.3",
     "vitepress-plugin-group-icons": "^1.5.2",
-    "vitepress-plugin-llms": "^1.1.1",
+    "vitepress-plugin-llms": "^1.1.3",
     "vitest": "^3.1.2",
     "vue": "^3.5.13"
   },

package/lib/definition-VzcnM0si.js

@@ -1,12 +0,0 @@
-//#region src/definition.ts
-/**
-* Define a {@link Command | command} with type inference
-* @param definition A {@link Command | command} definition
-* @returns A {@link Command | command} definition with type inference
-*/
-function define(definition) {
-	return definition;
-}
-
-//#endregion
-export { define };

package/lib/definition.d-wYlroF3H.d.ts

@@ -1,12 +0,0 @@
-import { Command } from "./types.d-DomXJWKH.js";
-import { ArgOptionSchema, ArgOptions, ArgOptions as ArgOptions$1, ArgValues as ArgValues$1 } from "args-tokens";
-
-//#region src/definition.d.ts
-/**
-* Define a {@link Command | command} with type inference
-* @param definition A {@link Command | command} definition
-* @returns A {@link Command | command} definition with type inference
-*/
-
-declare function define<Options extends ArgOptions = ArgOptions>(definition: Command<Options>): Command<Options>; //#endregion
-export { ArgOptionSchema, ArgOptions$1 as ArgOptions, ArgValues$1 as ArgValues, define as define$1 };