gunshi 0.27.6 → 0.28.2

package/lib/bone.d.ts

@@ -1,4 +1,4 @@
-import { A as SubCommandable, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, O as RendererDecorator, S as ExtractExtensions, T as LazyCommand, _ as Commandable, a as Awaitable, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, h as CommandLoader, i as Args, j as ValidationErrorsDecorator, k as RenderingOptions, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, o as CliOptions, p as CommandEnvironment, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-RXstkMKh.js";
+import { B as Args, C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, H as ArgToken, R as ArgSchema, S as NormalizeToGunshiParams, T as RenderingOptions, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
 
 //#region src/cli/bone.d.ts
 /**

package/lib/bone.js

@@ -1,4 +1,4 @@
-import { t as cliCore } from "./core-BEHAY3pE.js";
+import { t as cliCore } from "./core-C9P_Gd_f.js";
 
 //#region src/cli/bone.ts
 /**

package/lib/{cli-BzfnVXOV.js → cli-l4AYjN-O.js}

@@ -1,6 +1,6 @@
-import { t as cliCore } from "./core-BEHAY3pE.js";
+import { t as cliCore } from "./core-C9P_Gd_f.js";
 import { t as plugin } from "./core-eN5xmB3s.js";
-import { a as namespacedId, s as COMMON_ARGS, t as renderer } from "./src-DulE0ns5.js";
+import { a as namespacedId, s as COMMON_ARGS, t as renderer } from "./src-CfO5ab2f.js";
 
 //#region ../plugin-global/src/types.ts
 /**

package/lib/{constants-BbfDN8vC.d.ts → constants-C7V6-RNo.d.ts}

@@ -1,4 +1,4 @@
-import { o as CliOptions, v as DefaultGunshiParams } from "./types-RXstkMKh.js";
+import { m as DefaultGunshiParams, n as CliOptions } from "./types-Doxo8g3Y.js";
 
 //#region src/constants.d.ts
 /**

package/lib/{context-2cGqZAlo.js → context-CHDIbgwd.js}

@@ -1,4 +1,4 @@
-import { i as log, n as deepFreeze, r as isLazyCommand, t as create } from "./utils-A01g1U8-.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-DNS9AIR_.js";
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
 
 //#region src/context.ts
@@ -23,7 +23,7 @@ import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from
 * @param param - A {@link CommandContextParams | parameters} to create a command context.
 * @returns A {@link CommandContext | command context}, which is readonly.
 */
-async function createCommandContext({ args = {}, explicit = {}, values = {}, positionals = [], rest = [], argv = [], tokens = [], command = {}, extensions = {}, cliOptions = {}, callMode = "entry", omitted = false, validationError = void 0 }) {
+async function createCommandContext({ args = {}, explicit = {}, values = {}, positionals = [], rest = [], argv = [], tokens = [], command = {}, extensions = {}, cliOptions = {}, callMode = "entry", commandPath = [], omitted = false, validationError = void 0 }) {
 	/**
 	* normailize the options schema and values, to avoid prototype pollution
 	*/
@@ -52,6 +52,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 		description: command.description,
 		omitted,
 		callMode,
+		commandPath,
 		env,
 		args: _args,
 		explicit,

package/lib/context.d.ts

@@ -1,4 +1,4 @@
-import { C as GunshiParams, T as LazyCommand, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, i as Args, l as CommandContext, n as ArgToken, o as CliOptions, r as ArgValues, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-RXstkMKh.js";
+import { B as Args, H as ArgToken, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
 
 //#region src/context.d.ts
 
@@ -52,6 +52,10 @@ interface CommandContextParams<G extends GunshiParams | {
    * Command call mode.
    */
   callMode?: CommandCallMode;
+  /**
+   * The path of nested sub-commands resolved to reach the current command.
+   */
+  commandPath?: string[];
   /**
    * A target command
    */
@@ -87,6 +91,7 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   extensions,
   cliOptions,
   callMode,
+  commandPath,
   omitted,
   validationError
 }: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{

package/lib/context.js

@@ -1,3 +1,3 @@
-import { t as createCommandContext } from "./context-2cGqZAlo.js";
+import { t as createCommandContext } from "./context-CHDIbgwd.js";
 
 export { createCommandContext };

package/lib/{core-BEHAY3pE.js → core-C9P_Gd_f.js}

@@ -1,6 +1,6 @@
-import { a as resolveLazyCommand, o as kebabnize, r as isLazyCommand, t as create } from "./utils-A01g1U8-.js";
+import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-DNS9AIR_.js";
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
-import { t as createCommandContext } from "./context-2cGqZAlo.js";
+import { t as createCommandContext } from "./context-CHDIbgwd.js";
 
 //#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/parser.js
 const HYPHEN_CHAR = "-";
@@ -664,16 +664,18 @@ async function cliCore(argv, entry, options, plugins) {
 	const resolvedPlugins = await applyPlugins(pluginContext, [...plugins, ...options.plugins || []]);
 	const cliOptions = normalizeCliOptions(options, decorators, pluginContext);
 	const tokens = parseArgs(argv);
-	const subCommand = getSubCommand(tokens);
-	const { commandName: name, command, callMode } = resolveCommand(subCommand, entry, cliOptions);
+	const resolved = resolveCommandTree(tokens, entry, cliOptions);
+	const { commandName: name, command, callMode, commandPath, depth, levelSubCommands } = resolved;
 	if (!command) throw new Error(`Command not found: ${name || ""}`);
 	const args = resolveArguments(pluginContext, getCommandArgs(command));
+	const skipPositional = depth > 0 ? depth - 1 : -1;
 	const { explicit, values, positionals, rest, error } = resolveArgs(args, tokens, {
 		shortGrouping: true,
 		toKebab: command.toKebab,
-		skipPositional: callMode === "subCommand" && cliOptions.subCommands.size > 0 ? 0 : -1
+		skipPositional
 	});
-	const omitted = !subCommand;
+	const omitted = resolved.omitted;
+	if (levelSubCommands) cliOptions.subCommands = levelSubCommands;
 	const resolvedCommand = isLazyCommand(command) ? await resolveLazyCommand(command, name, true) : command;
 	return await executeCommand(resolvedCommand, await createCommandContext({
 		args,
@@ -685,6 +687,7 @@ async function cliCore(argv, entry, options, plugins) {
 		tokens,
 		omitted,
 		callMode,
+		commandPath,
 		command: resolvedCommand,
 		extensions: getPluginExtensions(resolvedPlugins),
 		validationError: error,
@@ -721,9 +724,12 @@ function createInitialSubCommands(options, entryCmd) {
 	const subCommands = new Map(options.subCommands instanceof Map ? options.subCommands : []);
 	if (!(options.subCommands instanceof Map) && isObject(options.subCommands)) for (const [name, cmd] of Object.entries(options.subCommands)) subCommands.set(name, cmd);
 	if (hasSubCommands) {
-		if (isLazyCommand(entryCmd) || typeof entryCmd === "object") {
-			entryCmd.entry = true;
-			subCommands.set(resolveEntryName(entryCmd), entryCmd);
+		if (isLazyCommand(entryCmd)) {
+			const entryCopy = Object.assign((...args) => entryCmd(...args), entryCmd, { entry: true });
+			subCommands.set(resolveEntryName(entryCopy), entryCopy);
+		} else if (typeof entryCmd === "object") {
+			const entryCopy = Object.assign(create(), entryCmd, { entry: true });
+			subCommands.set(resolveEntryName(entryCopy), entryCopy);
 		} else if (typeof entryCmd === "function") {
 			const name = entryCmd.name || ANONYMOUS_COMMAND_NAME;
 			subCommands.set(name, {
@@ -743,48 +749,102 @@ function normalizeCliOptions(options, decorators, pluginContext) {
 	if (resolvedOptions.renderValidationErrors === void 0) resolvedOptions.renderValidationErrors = decorators.getValidationErrorsRenderer();
 	return resolvedOptions;
 }
-function getSubCommand(tokens) {
-	const firstToken = tokens[0];
-	return firstToken && firstToken.kind === "positional" && firstToken.index === 0 && firstToken.value ? firstToken.value : "";
+function getPositionalTokens(tokens) {
+	return tokens.filter((t) => t.kind === "positional").map((t) => t.value).filter((v) => !!v);
 }
-const CANNOT_RESOLVE_COMMAND = { callMode: "unexpected" };
-function resolveCommand(sub, entry, options) {
-	const omitted = !sub;
-	function doResolveCommand() {
+function resolveCommandTree(tokens, entry, options) {
+	const positionals = getPositionalTokens(tokens);
+	function resolveAsEntry() {
 		if (typeof entry === "function") if ("commandName" in entry && entry.commandName) return {
 			commandName: entry.commandName,
 			command: entry,
-			callMode: "entry"
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
 		};
 		else return {
 			command: {
 				run: entry,
 				entry: true
 			},
-			callMode: "entry"
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
 		};
 		else if (typeof entry === "object") return {
 			commandName: resolveEntryName(entry),
 			command: entry,
-			callMode: "entry"
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
 		};
-		else return CANNOT_RESOLVE_COMMAND;
-	}
-	if (omitted || options.subCommands?.size === 0) return doResolveCommand();
-	const cmd = options.subCommands?.get(sub);
-	if (cmd == null) {
-		if (options.fallbackToEntry) return doResolveCommand();
-		return {
-			commandName: sub,
-			callMode: "unexpected"
+		else return {
+			callMode: "unexpected",
+			commandPath: [],
+			depth: 0,
+			omitted: false,
+			levelSubCommands: void 0
 		};
 	}
-	if (isLazyCommand(cmd) && cmd.commandName == null) cmd.commandName = sub;
-	else if (typeof cmd === "object" && cmd.name == null) cmd.name = sub;
+	if (positionals.length === 0 || options.subCommands.size === 0) return resolveAsEntry();
+	let currentSubCommands = options.subCommands;
+	let resolvedCommand;
+	let resolvedName;
+	const commandPath = [];
+	let depth = 0;
+	for (let i = 0; i < positionals.length; i++) {
+		const token = positionals[i];
+		const cmd = currentSubCommands.get(token);
+		if (cmd == null) {
+			if (depth === 0) {
+				if (options.fallbackToEntry) return resolveAsEntry();
+				return {
+					commandName: token,
+					callMode: "unexpected",
+					commandPath: [],
+					depth: 0,
+					omitted: false,
+					levelSubCommands: void 0
+				};
+			}
+			break;
+		}
+		let resolved = cmd;
+		if (typeof cmd === "function" && cmd.commandName == null) resolved = Object.assign((...args) => cmd(...args), cmd, { commandName: token });
+		else if (typeof cmd === "object" && cmd.name == null) resolved = Object.assign(create(), cmd, { name: token });
+		resolvedCommand = resolved;
+		resolvedName = token;
+		commandPath.push(token);
+		depth++;
+		const nestedSubCommands = getCommandSubCommands(cmd);
+		if (nestedSubCommands && nestedSubCommands.size > 0) currentSubCommands = nestedSubCommands;
+		else break;
+	}
+	if (!resolvedCommand) return resolveAsEntry();
+	const resolvedSubCommands = getCommandSubCommands(resolvedCommand);
+	const omitted = resolvedSubCommands != null && resolvedSubCommands.size > 0;
+	let levelSubCommands;
+	if (omitted && resolvedSubCommands) {
+		levelSubCommands = new Map(resolvedSubCommands);
+		let entryCopy;
+		if (typeof resolvedCommand === "function") entryCopy = Object.assign((...args) => resolvedCommand(...args), resolvedCommand, { entry: true });
+		else entryCopy = Object.assign(create(), resolvedCommand, { entry: true });
+		levelSubCommands.set(resolvedName || resolveEntryName(entryCopy), entryCopy);
+	}
 	return {
-		commandName: sub,
-		command: cmd,
-		callMode: "subCommand"
+		commandName: resolvedName,
+		command: resolvedCommand,
+		callMode: depth > 0 ? "subCommand" : "entry",
+		commandPath,
+		depth,
+		omitted,
+		levelSubCommands
 	};
 }
 function resolveEntryName(entry) {

package/lib/definition.d.ts

@@ -1,4 +1,4 @@
-import { C as GunshiParams, D as Prettify, S as ExtractExtensions, T as LazyCommand, g as CommandRunner, h as CommandLoader, i as Args, r as ArgValues, s as Command, t as ArgSchema, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-RXstkMKh.js";
+import { B as Args, C as Prettify, R as ArgSchema, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts

package/lib/definition.js

@@ -1,4 +1,4 @@
-import { t as createCommandContext } from "./context-2cGqZAlo.js";
+import { t as createCommandContext } from "./context-CHDIbgwd.js";
 
 //#region src/definition.ts
 /**
@@ -63,6 +63,7 @@ function lazy(loader, definition) {
 		lazyCommand.internal = definition.internal;
 		lazyCommand.entry = definition.entry;
 		lazyCommand.toKebab = definition.toKebab;
+		if (definition.subCommands) lazyCommand.subCommands = definition.subCommands;
 		if ("resource" in definition) lazyCommand.resource = definition.resource;
 	}
 	return lazyCommand;

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { T as LazyCommand, o as CliOptions, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-RXstkMKh.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-Doxo8g3Y.js";
 
 //#region src/generator.d.ts
 
@@ -18,6 +18,6 @@ type GenerateOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> = C
  * @param options - A {@linkcode GenerateOptions | cli options}
  * @returns A rendered usage.
  */
-declare function generate<G extends GunshiParamsConstraint = DefaultGunshiParams>(command: string | null, entry: Command<G> | LazyCommand<G>, options?: GenerateOptions<G>): Promise<string>;
+declare function generate<G extends GunshiParamsConstraint = DefaultGunshiParams>(command: string | string[] | null, entry: Command<G> | LazyCommand<G>, options?: GenerateOptions<G>): Promise<string>;
 //#endregion
 export { GenerateOptions, generate };

package/lib/generator.js

@@ -1,7 +1,7 @@
-import "./core-BEHAY3pE.js";
-import { t as create } from "./utils-A01g1U8-.js";
-import "./src-DulE0ns5.js";
-import { t as cli } from "./cli-BzfnVXOV.js";
+import "./core-C9P_Gd_f.js";
+import { t as create } from "./utils-DNS9AIR_.js";
+import "./src-CfO5ab2f.js";
+import { t as cli } from "./cli-l4AYjN-O.js";
 
 //#region src/generator.ts
 /**
@@ -30,7 +30,10 @@ import { t as cli } from "./cli-BzfnVXOV.js";
 */
 async function generate(command, entry, options = {}) {
 	const args = ["-h"];
-	if (command != null) args.unshift(command);
+	if (command != null) {
+		const parts = Array.isArray(command) ? command : command.split(" ");
+		args.unshift(...parts);
+	}
 	return await cli(args, entry, {
 		...create(),
 		...options,

package/lib/index.d.ts

@@ -1,8 +1,7 @@
-import { A as SubCommandable, B as plugin, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, F as PluginExtension, I as PluginFunction, L as PluginOptions, M as OnPluginExtension, N as Plugin, O as RendererDecorator, P as PluginDependency, R as PluginWithExtension, S as ExtractExtensions, T as LazyCommand, V as PluginContext, _ as Commandable, a as Awaitable, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, h as CommandLoader, i as Args, j as ValidationErrorsDecorator, k as RenderingOptions, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, o as CliOptions, p as CommandEnvironment, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext, z as PluginWithoutExtension } from "./types-RXstkMKh.js";
+import { A as PluginDependency, B as Args, C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, F as PluginWithoutExtension, H as ArgToken, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, R as ArgSchema, S as NormalizeToGunshiParams, T as RenderingOptions, U as parseArgs, V as resolveArgs, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, j as PluginExtension, k as Plugin, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
-import { t as ANONYMOUS_COMMAND_NAME } from "./constants-BbfDN8vC.js";
-import { parseArgs, resolveArgs } from "args-tokens";
+import { t as ANONYMOUS_COMMAND_NAME } from "./constants-C7V6-RNo.js";
 
 //#region ../plugin-i18n/src/types.d.ts
 

package/lib/index.js

@@ -1,10 +1,10 @@
-import { n as resolveArgs, r as parseArgs } from "./core-BEHAY3pE.js";
+import { n as resolveArgs, r as parseArgs } from "./core-C9P_Gd_f.js";
 import { t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
-import { t as createCommandContext } from "./context-2cGqZAlo.js";
+import { t as createCommandContext } from "./context-CHDIbgwd.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
 import { t as plugin } from "./core-eN5xmB3s.js";
-import { a as namespacedId, o as BUILT_IN_PREFIX } from "./src-DulE0ns5.js";
-import { t as cli } from "./cli-BzfnVXOV.js";
+import { a as namespacedId, o as BUILT_IN_PREFIX } from "./src-CfO5ab2f.js";
+import { t as cli } from "./cli-l4AYjN-O.js";
 
 //#region ../plugin-i18n/src/translation.ts
 /**

package/lib/plugin.d.ts

@@ -1,4 +1,4 @@
-import { B as plugin, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, F as PluginExtension, I as PluginFunction, L as PluginOptions, M as OnPluginExtension, N as Plugin, O as RendererDecorator, P as PluginDependency, R as PluginWithExtension, S as ExtractExtensions, T as LazyCommand, V as PluginContext, a as Awaitable, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, i as Args, j as ValidationErrorsDecorator, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext, z as PluginWithoutExtension } from "./types-RXstkMKh.js";
+import { A as PluginDependency, B as Args, C as Prettify, D as ValidationErrorsDecorator, F as PluginWithoutExtension, H as ArgToken, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, R as ArgSchema, S as NormalizeToGunshiParams, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, f as CommandRunner, h as ExtendContext, j as PluginExtension, k as Plugin, m as DefaultGunshiParams, o as CommandContextCore, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
-import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-BbfDN8vC.js";
+import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-C7V6-RNo.js";
 export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, plugin };

package/lib/plugin.js

@@ -1,5 +1,5 @@
 import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
-import { t as createCommandContext } from "./context-2cGqZAlo.js";
+import { t as createCommandContext } from "./context-CHDIbgwd.js";
 import { t as plugin } from "./core-eN5xmB3s.js";
 
 export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT, createCommandContext, plugin };

package/lib/renderer.d.ts

@@ -1,4 +1,4 @@
-import { C as GunshiParams, l as CommandContext, v as DefaultGunshiParams } from "./types-RXstkMKh.js";
+import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-Doxo8g3Y.js";
 
 //#region ../plugin-renderer/src/header.d.ts
 /**

package/lib/renderer.js

@@ -1,3 +1,3 @@
-import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-DulE0ns5.js";
+import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-CfO5ab2f.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{src-DulE0ns5.js → src-CfO5ab2f.js}

@@ -1,4 +1,4 @@
-import { a as resolveLazyCommand, o as kebabnize } from "./utils-A01g1U8-.js";
+import { o as resolveLazyCommand, s as kebabnize } from "./utils-DNS9AIR_.js";
 import { t as ANONYMOUS_COMMAND_NAME } from "./constants-WviiKqbt.js";
 import { t as plugin } from "./core-eN5xmB3s.js";
 
@@ -213,7 +213,7 @@ const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
 */
 async function renderUsage(ctx) {
 	const messages = [];
-	if (!ctx.omitted) {
+	if (ctx.callMode === "subCommand") {
 		const description = await resolveDescription(ctx);
 		if (description) messages.push(description, "");
 	}
@@ -307,10 +307,11 @@ async function renderCommandsSection(ctx) {
 		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;
 	messages.push(...loadedCommands.map((cmd) => {
 		let commandStr = cmd.entry ? "" : cmd.name || "";
 		if (commandStr) commandStr += " ";
-		const commandHelp = `${ctx.env.name} ${commandStr}--help`;
+		const commandHelp = `${basePath} ${commandStr}--help`;
 		return `${commandHelp.padStart(ctx.env.leftMargin + commandHelp.length)}`;
 	}));
 	return messages;
@@ -345,6 +346,7 @@ async function resolveEntry(ctx) {
 * @returns The sub command name
 */
 async function resolveSubCommand(ctx) {
+	if (ctx.commandPath && ctx.commandPath.length > 0) return ctx.commandPath.join(" ");
 	return ctx.name || await ctx.extensions[pluginId].text(resolveBuiltInKey("SUBCOMMAND"));
 }
 /**

package/lib/{types-RXstkMKh.d.ts → types-Doxo8g3Y.d.ts}

@@ -1,11 +1,633 @@
-import { ArgExplicitlyProvided, ArgSchema, ArgSchema as ArgSchema$1, ArgToken, ArgToken as ArgToken$1, ArgValues, ArgValues as ArgValues$1, Args, Args as Args$1 } from "args-tokens";
-
-//#region src/plugin/context.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/parser.d.ts
+//#region src/parser.d.ts
+/**
+ * Entry point of argument parser.
+ *
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Argument token Kind.
+ *
+ * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
+ * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+ * - `positional`: positional token
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
+interface ArgToken {
+  /**
+   * Argument token kind.
+   */
+  kind: ArgTokenKind;
+  /**
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
+  index: number;
+  /**
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
+  name?: string;
+  /**
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
+  rawName?: string;
+  /**
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
+  value?: string;
+  /**
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
+  inlineValue?: boolean;
+}
 /**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
+ * Parser Options.
+ */
+interface ParserOptions {
+  /**
+   * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode.
+   *
+   * @default false
+   */
+  allowCompatible?: boolean;
+}
+/**
+ * Parse command line arguments.
+ *
+ * @param args - command line arguments
+ * @param options - parse options, about details see {@link ParserOptions}
+ * @returns Argument tokens.
+ *
+ * @example
+ * ```js
+ * import { parseArgs } from 'args-tokens' // for Node.js and Bun
+ * // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+ *
+ * const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+ * // do something with using tokens
+ * // ...
+ * console.log('tokens:', tokens)
+ * ```
+ */
+declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
+/**
+ * Check if `arg` is a short option (e.g. `-f`).
+ *
+ * @param arg - An argument to check
+ * @returns Whether `arg` is a short option.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/resolver.d.ts
+//#region src/resolver.d.ts
+/**
+ * An argument schema definition for command-line argument parsing.
+ *
+ * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
+ * - Additional `required` and `description` properties
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
+ */
+interface ArgSchema {
+  /**
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
+  /**
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
+   */
+  short?: string;
+  /**
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
+   */
+  description?: string;
+  /**
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user.
+   * If missing, an `ArgResolveError` with type 'required' will be thrown.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
+   */
+  required?: true;
+  /**
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array.
+   * For options: can be specified multiple times (--tag foo --tag bar)
+   * For positional: collects remaining positional arguments
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
+   */
+  multiple?: true;
+  /**
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
+   */
+  negatable?: boolean;
+  /**
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
+   */
+  choices?: string[] | readonly string[];
+  /**
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
+   */
+  default?: string | boolean | number;
+  /**
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
+   */
+  toKebab?: true;
+  /**
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * Conflicts only need to be defined on one side - if option A defines a conflict
+   * with option B, the conflict is automatically detected when both are used,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn will throw error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  parse?: (value: string) => any;
+}
+/**
+ * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
+ */
+interface Args {
+  [option: string]: ArgSchema;
+}
+/**
+ * An object that contains the values of the arguments.
+ *
+ * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
+ */
+type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
+  [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
+};
+type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
+/**
+ * Extracts the value type from the argument schema.
+ *
+ * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
+ *
+ * @internal
+ */
+type ExtractOptionValue<A extends ArgSchema> = A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? IsFunction<A['parse']> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A['parse']>>> : never : ResolveOptionValue<A, string | boolean | number>;
+type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
+/**
+ * Resolved argument values.
+ *
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @internal
+ */
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
+/**
+ * Filters the arguments based on their default values.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
+ *
+ * @internal
+ */
+type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+/**
+ * Filters positional arguments from the argument schema.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @internal
+ */
+type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
+/**
+ * An arguments for {@link resolveArgs | resolve arguments}.
+ */
+interface ResolveArgs {
+  /**
+   * Whether to group short arguments.
+   *
+   * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
+   *
+   * @default false
+   */
+  shortGrouping?: boolean;
+  /**
+   * Skip positional arguments index.
+   *
+   * @default -1
+   */
+  skipPositional?: number;
+  /**
+   * Whether to convert the argument name to kebab-case. This option is applied to all arguments as `toKebab: true`, if set to `true`.
+   *
+   * @default false
+   */
+  toKebab?: boolean;
+}
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ */
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+/**
+ * Resolve command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ *
+ * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
+declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
+  shortGrouping,
+  skipPositional,
+  toKebab
+}?: ResolveArgs): {
+  values: ArgValues<A>;
+  positionals: string[];
+  rest: string[];
+  error: AggregateError | undefined;
+  explicit: ArgExplicitlyProvided<A>;
+};
+/**
+ * An error type for {@link ArgResolveError}.
+ */
+//#endregion
+//#region src/plugin/context.d.ts
 /**
  * Type helper to create GunshiParams from extracted args and extensions
  *
@@ -718,6 +1340,15 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    * The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command.
    */
   callMode: CommandCallMode;
+  /**
+   * The path of nested sub-commands that were resolved to reach the current command.
+   *
+   * For example, if the user runs `git remote add`, `commandPath` would be `['remote', 'add']`.
+   * For the entry command, this is an empty array.
+   *
+   * @since v0.28.0
+   */
+  commandPath: string[];
   /**
    * Whether to convert the camel-case style argument name to kebab-case.
    * This context value is set from {@linkcode Command.toKebab} option.
@@ -859,6 +1490,15 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * @since v0.27.0
    */
   rendering?: RenderingOptions<G>;
+  /**
+   * Nested sub-commands for this command.
+   *
+   * Allows building command trees like `git remote add`.
+   * Each key is the sub-command name, and the value is a command or lazy command.
+   *
+   * @since v0.28.0
+   */
+  subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable>;
 }
 /**
  * Lazy command interface.
@@ -935,6 +1575,13 @@ interface SubCommandable {
    * see {@link LazyCommand.commandName}
    */
   commandName?: string;
+  /**
+   * Nested sub-commands for this command.
+   *
+   * @see {@link Command.subCommands}
+   * @since v0.28.0
+   */
+  subCommands?: Record<string, any> | Map<string, any>;
   /**
    * Index signature to allow additional properties
    */
@@ -1012,4 +1659,4 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
  */
 type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
 //#endregion
-export { SubCommandable as A, plugin as B, GunshiParams as C, Prettify as D, NormalizeToGunshiParams as E, PluginExtension as F, PluginFunction as I, PluginOptions as L, OnPluginExtension as M, Plugin as N, RendererDecorator as O, PluginDependency as P, PluginWithExtension as R, ExtractExtensions as S, LazyCommand as T, PluginContext as V, Commandable as _, Awaitable as a, ExtractArgExplicitlyProvided as b, CommandCallMode as c, CommandContextExtension as d, CommandDecorator as f, CommandRunner as g, CommandLoader as h, Args$1 as i, ValidationErrorsDecorator as j, RenderingOptions as k, CommandContext as l, CommandExamplesFetcher as m, ArgToken$1 as n, CliOptions as o, CommandEnvironment as p, ArgValues$1 as r, Command as s, ArgSchema$1 as t, CommandContextCore as u, DefaultGunshiParams as v, GunshiParamsConstraint as w, ExtractArgs as x, ExtendContext as y, PluginWithoutExtension as z };
+export { PluginDependency as A, Args as B, Prettify as C, ValidationErrorsDecorator as D, SubCommandable as E, PluginWithoutExtension as F, ArgToken as H, plugin as I, PluginContext as L, PluginFunction as M, PluginOptions as N, OnPluginExtension as O, PluginWithExtension as P, ArgSchema as R, NormalizeToGunshiParams as S, RenderingOptions as T, parseArgs as U, resolveArgs as V, ExtractArgs as _, CommandContext as a, GunshiParamsConstraint as b, CommandDecorator as c, CommandLoader as d, CommandRunner as f, ExtractArgExplicitlyProvided as g, ExtendContext as h, CommandCallMode as i, PluginExtension as j, Plugin as k, CommandEnvironment as l, DefaultGunshiParams as m, CliOptions as n, CommandContextCore as o, Commandable as p, Command as r, CommandContextExtension as s, Awaitable as t, CommandExamplesFetcher as u, ExtractExtensions as v, RendererDecorator as w, LazyCommand as x, GunshiParams as y, ArgValues as z };

package/lib/{utils-A01g1U8-.js → utils-DNS9AIR_.js}

@@ -48,7 +48,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			args: cmd.args,
 			examples: cmd.examples,
 			internal: cmd.internal,
-			entry: cmd.entry
+			entry: cmd.entry,
+			subCommands: cmd.subCommands
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
 		command = Object.assign(create(), baseCommand);
@@ -64,6 +65,7 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 				command.examples = loaded.examples;
 				command.internal = loaded.internal;
 				command.entry = loaded.entry;
+				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}`);
 		}
@@ -89,6 +91,24 @@ function log(...args) {
 	console.log(...args);
 }
 /**
+* Get the sub-commands of a command as a normalized Map.
+*
+* @param cmd - A command or lazy command
+* @returns A Map of sub-commands, or undefined if the command has no sub-commands.
+*/
+function getCommandSubCommands(cmd) {
+	const subCommands = isLazyCommand(cmd) ? cmd.subCommands : typeof cmd === "object" ? cmd.subCommands : void 0;
+	if (!subCommands) return;
+	if (subCommands instanceof Map) return subCommands.size > 0 ? subCommands : void 0;
+	if (typeof subCommands === "object") {
+		const entries = Object.entries(subCommands);
+		if (entries.length === 0) return;
+		const map = /* @__PURE__ */ new Map();
+		for (const [name, cmd] of entries) map.set(name, cmd);
+		return map;
+	}
+}
+/**
 * Deep freeze an object, making it immutable.
 *
 * @param obj - The object to freeze
@@ -106,4 +126,4 @@ function deepFreeze(obj, ignores = []) {
 }
 
 //#endregion
-export { resolveLazyCommand as a, log as i, deepFreeze as n, kebabnize as o, isLazyCommand as r, create as t };
+export { log as a, isLazyCommand as i, deepFreeze as n, resolveLazyCommand as o, getCommandSubCommands as r, kebabnize as s, create as t };

package/lib/utils.d.ts

@@ -1,12 +1,29 @@
-import { T as LazyCommand, _ as Commandable, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-RXstkMKh.js";
-import { kebabnize } from "args-tokens/utils";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-Doxo8g3Y.js";
+
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/utils.d.ts
 
 //#region src/utils.d.ts
 /**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
+ * 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
+ */
+/**
+ * Convert a string to kebab-case.
+ *
+ * @param str - A string to convert
+ * @returns Converted string into kebab-case.
+ */
+declare function kebabnize(str: string): string;
+//#endregion
+//#endregion
+//#region src/utils.d.ts
 /**
  * Check if the given command is a {@link LazyCommand}.
  *
@@ -36,6 +53,13 @@ declare function create<T>(obj?: object | null): T;
  * @param args - Arguments to log
  */
 declare function log(...args: unknown[]): void;
+/**
+ * Get the sub-commands of a command as a normalized Map.
+ *
+ * @param cmd - A command or lazy command
+ * @returns A Map of sub-commands, or undefined if the command has no sub-commands.
+ */
+declare function getCommandSubCommands<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: Commandable<G> | Command<G> | LazyCommand<G>): Map<string, Command<G> | LazyCommand<G>> | undefined;
 /**
  * Deep freeze an object, making it immutable.
  *
@@ -45,4 +69,4 @@ declare function log(...args: unknown[]): void;
  */
 declare function deepFreeze<T extends Record<string, any>>(obj: T, ignores?: string[]): Readonly<T>;
 //#endregion
-export { create, deepFreeze, isLazyCommand, kebabnize, log, resolveLazyCommand };
+export { create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, log, resolveLazyCommand };

package/lib/utils.js

@@ -1,3 +1,3 @@
-import { a as resolveLazyCommand, i as log, n as deepFreeze, o as kebabnize, r as isLazyCommand, t as create } from "./utils-A01g1U8-.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-DNS9AIR_.js";
 
-export { create, deepFreeze, isLazyCommand, kebabnize, log, resolveLazyCommand };
+export { create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, log, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.27.6",
+  "version": "0.28.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -103,11 +103,11 @@
     "publint": "^0.3.16",
     "tsdown": "0.15.12",
     "zod": "^4.2.1",
-    "@gunshi/plugin-global": "0.27.6",
-    "@gunshi/plugin-renderer": "0.27.6",
-    "@gunshi/resources": "0.27.6",
-    "@gunshi/plugin-i18n": "0.27.6",
-    "@gunshi/shared": "0.27.6"
+    "@gunshi/plugin-global": "0.28.2",
+    "@gunshi/plugin-i18n": "0.28.2",
+    "@gunshi/resources": "0.28.2",
+    "@gunshi/plugin-renderer": "0.28.2",
+    "@gunshi/shared": "0.28.2"
   },
   "scripts": {
     "build": "tsdown",