@gunshi/bone 0.27.5 → 0.28.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/parser-C6MbpZjd.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.
@@ -55,9 +55,8 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/resolver-D64nGlCD.d.ts
+//#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.
  *
@@ -504,7 +503,7 @@ type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -r
  *
  * @internal
  */
-type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K$1 extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K$1] extends {} ? Arg : never]: V[Arg] };
+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.
  *
@@ -717,7 +716,7 @@ type ExtendContext = Record<string, unknown>;
  *
  * @since v0.27.0
  */
-interface GunshiParams<P$1 extends {
+interface GunshiParams<P extends {
   args?: Args;
   extensions?: ExtendContext;
 } = {
@@ -727,13 +726,13 @@ interface GunshiParams<P$1 extends {
   /**
    * Command argument definitions.
    */
-  args: P$1 extends {
+  args: P extends {
     args: infer A extends Args;
   } ? A : Args;
   /**
    * Command context extensions.
    */
-  extensions: P$1 extends {
+  extensions: P extends {
     extensions: infer E extends ExtendContext;
   } ? E : {};
 }
@@ -1069,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.
@@ -1210,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.
@@ -1286,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

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/parser-M-ayhS1h.js
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/parser.js
 const HYPHEN_CHAR = "-";
 const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
 const EQUAL_CHAR = "=";
@@ -42,11 +42,11 @@ function parseArgs(args, options = {}) {
 				kind: "option-terminator",
 				index
 			});
-			const mapped = remainings.map((arg$1) => {
+			const mapped = remainings.map((arg) => {
 				return {
 					kind: "positional",
 					index: ++index,
-					value: arg$1
+					value: arg
 				};
 			});
 			tokens.push(...mapped);
@@ -196,7 +196,7 @@ function hasOptionValue(value) {
 }
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/utils-1LQrGCWG.js
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/utils-CxvkckUD.js
 /**
 * Entry point of utils.
 *
@@ -219,7 +219,16 @@ function kebabnize(str) {
 }
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/resolver-D0hj6HpX.js
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/resolver.js
+/**
+* Entry point of argument options resolver.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 const SKIP_POSITIONAL_DEFAULT = -1;
 /**
 * Resolve command line arguments.
@@ -262,7 +271,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	let currentShortOption;
 	const expandableShortOptions = [];
 	function toShortValue() {
-		if (expandableShortOptions.length === 0) return void 0;
+		if (expandableShortOptions.length === 0) return;
 		else {
 			const value = expandableShortOptions.map((token) => token.name).join("");
 			expandableShortOptions.length = 0;
@@ -369,11 +378,14 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				if (remainingPositionals.length > 0) {
 					values[rawArg] = remainingPositionals.map((p) => p.value);
 					positionalsCount += remainingPositionals.length;
+					explicit[rawArg] = true;
 				} else if (schema.required) errors.push(createRequireError(arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
-				if (positional != null) values[rawArg] = positional.value;
-				else errors.push(createRequireError(arg, schema));
+				if (positional != null) {
+					values[rawArg] = positional.value;
+					explicit[rawArg] = true;
+				} else errors.push(createRequireError(arg, schema));
 				positionalsCount++;
 			}
 			continue;
@@ -543,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);
@@ -559,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}`);
 		}
@@ -584,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
@@ -623,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
 	*/
@@ -652,6 +684,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 		description: command.description,
 		omitted,
 		callMode,
+		commandPath,
 		env,
 		args: _args,
 		explicit,
@@ -869,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,
@@ -890,6 +925,7 @@ async function cliCore(argv, entry, options, plugins) {
 		tokens,
 		omitted,
 		callMode,
+		commandPath,
 		command: resolvedCommand,
 		extensions: getPluginExtensions(resolvedPlugins),
 		validationError: error,
@@ -926,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, {
@@ -948,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.5",
+  "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.5",
-    "@gunshi/plugin-global": "0.27.5",
-    "@gunshi/plugin-renderer": "0.27.5",
-    "gunshi": "0.27.5"
+    "@gunshi/definition": "0.28.0",
+    "@gunshi/plugin-global": "0.28.0",
+    "@gunshi/plugin-renderer": "0.28.0",
+    "gunshi": "0.28.0"
   },
   "scripts": {
     "build": "tsdown",