@gunshi/shared 0.27.6 → 0.28.0

package/lib/index.d.ts

@@ -826,6 +826,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.
@@ -938,6 +947,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.
@@ -965,6 +983,67 @@ type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D exten
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command.
  */
 type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>;
+/**
+ * Sub-command entry type for use in subCommands.
+ *
+ * This type uses a loose structural match to bypass TypeScript's contravariance issues
+ * with function parameters, allowing any Command or LazyCommand to be used as a sub-command.
+ *
+ * @since v0.27.1
+ */
+interface SubCommandable {
+  /**
+   * see {@link Command.name}
+   */
+  name?: string;
+  /**
+   * see {@link Command.description}
+   */
+  description?: string;
+  /**
+   * see {@link Command.args}
+   */
+  args?: Args | Record<string, any>;
+  /**
+   * see {@link Command.examples}
+   */
+  examples?: string | ((...args: any[]) => any);
+  /**
+   * see {@link Command.run}
+   */
+  run?: (...args: any[]) => any;
+  /**
+   * see {@link Command.toKebab}
+   */
+  toKebab?: boolean;
+  /**
+   * see {@link Command.internal}
+   */
+  internal?: boolean;
+  /**
+   * see {@link Command.entry}
+   */
+  entry?: boolean;
+  /**
+   * see {@link Command.rendering}
+   */
+  rendering?: any;
+  /**
+   * 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
+   */
+  [key: string]: any;
+}
 /**
  * Command examples fetcher.
  *
@@ -1036,6 +1115,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.
  *
@@ -1251,4 +1337,4 @@ declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K,
  */
 declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKebab?: boolean): string;
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, DeepWriteable, __json_default_export as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, DeepWriteable, __json_default_export as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/lib/index.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
@@ -292,4 +312,4 @@ function localizable(ctx, cmd, translate) {
 }
 
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "0.27.6",
+  "version": "0.28.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -55,8 +55,8 @@
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.16",
     "tsdown": "0.15.12",
-    "@gunshi/resources": "0.27.6",
-    "gunshi": "0.27.6"
+    "@gunshi/resources": "0.28.0",
+    "gunshi": "0.28.0"
   },
   "scripts": {
     "build": "tsdown",