gunshi 0.27.6 → 0.28.0

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 { 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-DSyU38G8.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-Cqazor4w.d.ts}

@@ -1,4 +1,4 @@
-import { o as CliOptions, v as DefaultGunshiParams } from "./types-RXstkMKh.js";
+import { o as CliOptions, v as DefaultGunshiParams } from "./types-DSyU38G8.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 { 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-DSyU38G8.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 { 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-DSyU38G8.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 { T as LazyCommand, o as CliOptions, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-DSyU38G8.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,7 +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 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-DSyU38G8.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 { t as ANONYMOUS_COMMAND_NAME } from "./constants-Cqazor4w.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#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 { 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-DSyU38G8.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-Cqazor4w.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 { C as GunshiParams, l as CommandContext, v as DefaultGunshiParams } from "./types-DSyU38G8.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-DSyU38G8.d.ts}

@@ -718,6 +718,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 +868,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 +953,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
    */

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,4 +1,4 @@
-import { T as LazyCommand, _ as Commandable, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-RXstkMKh.js";
+import { T as LazyCommand, _ as Commandable, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-DSyU38G8.js";
 import { kebabnize } from "args-tokens/utils";
 
 //#region src/utils.d.ts
@@ -36,6 +36,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 +52,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.0",
   "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.0",
+    "@gunshi/plugin-i18n": "0.28.0",
+    "@gunshi/resources": "0.28.0",
+    "@gunshi/shared": "0.28.0",
+    "@gunshi/plugin-renderer": "0.28.0"
   },
   "scripts": {
     "build": "tsdown",