@gunshi/bone 0.27.6 → 0.28.0

package/lib/index.d.ts

@@ -1068,6 +1068,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.
@@ -1209,6 +1218,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.
@@ -1285,6 +1303,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/index.js

@@ -555,7 +555,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);
@@ -571,6 +572,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}`);
 		}
@@ -596,6 +598,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
@@ -635,7 +655,7 @@ function deepFreeze(obj, ignores = []) {
 * @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
 	*/
@@ -664,6 +684,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 		description: command.description,
 		omitted,
 		callMode,
+		commandPath,
 		env,
 		args: _args,
 		explicit,
@@ -881,16 +902,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,
@@ -902,6 +925,7 @@ async function cliCore(argv, entry, options, plugins) {
 		tokens,
 		omitted,
 		callMode,
+		commandPath,
 		command: resolvedCommand,
 		extensions: getPluginExtensions(resolvedPlugins),
 		validationError: error,
@@ -938,9 +962,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, {
@@ -960,48 +987,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/bone",
   "description": "gunshi minimum",
-  "version": "0.27.6",
+  "version": "0.28.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,10 +56,10 @@
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.16",
     "tsdown": "0.15.12",
-    "@gunshi/definition": "0.27.6",
-    "@gunshi/plugin-global": "0.27.6",
-    "@gunshi/plugin-renderer": "0.27.6",
-    "gunshi": "0.27.6"
+    "@gunshi/definition": "0.28.0",
+    "@gunshi/plugin-global": "0.28.0",
+    "@gunshi/plugin-renderer": "0.28.0",
+    "gunshi": "0.28.0"
   },
   "scripts": {
     "build": "tsdown",