@gunshi/shared 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.
  *
@@ -582,7 +581,7 @@ type ExtendContext = Record<string, unknown>;
  *
  * @since v0.27.0
  */
-interface GunshiParams<P$1 extends {
+interface GunshiParams<P extends {
   args?: Args;
   extensions?: ExtendContext;
 } = {
@@ -592,13 +591,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 : {};
 }
@@ -827,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.
@@ -939,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.
@@ -966,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.
  *
@@ -985,7 +1063,7 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  */
 type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/utils.d.ts
 //#region src/utils.d.ts
 /**
  * Entry point of utils.
@@ -1037,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.
  *
@@ -1111,9 +1196,9 @@ type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
  */
-type CommandArgKeys<A extends Args, C = {}, K$1 extends string = GenerateNamespacedKey<Extract<KeyOfArgs<RemovedIndex<A>>, string>, typeof ARG_PREFIX>> = C extends {
+type CommandArgKeys<A extends Args, C = {}, K extends string = GenerateNamespacedKey<Extract<KeyOfArgs<RemovedIndex<A>>, string>, typeof ARG_PREFIX>> = C extends {
   name: infer N;
-} ? (N extends string ? GenerateNamespacedKey<K$1, N> : K$1) : K$1;
+} ? (N extends string ? GenerateNamespacedKey<K, N> : K) : K;
 /**
  * Resolve translation keys for command context.
  */
@@ -1131,8 +1216,8 @@ interface Translation<A extends Args, C = {},
 // for CommandContext
 E extends Record<string, string> = {},
 // for extended resources
-K$1 = ResolveTranslationKeys<A, C, E>> {
-  (key: K$1, values?: Record<string, unknown>): string;
+K = ResolveTranslationKeys<A, C, E>> {
+  (key: K, values?: Record<string, unknown>): string;
 }
 //#endregion
 //#region src/localization.d.ts
@@ -1146,7 +1231,7 @@ K$1 = ResolveTranslationKeys<A, C, E>> {
 interface Localization<A extends Args, C = {},
 // for CommandContext
 E extends Record<string, string> = {}> {
-  <K$1 = ResolveTranslationKeys<A, C, E>>(key: K$1, values?: Record<string, unknown>): Promise<string>;
+  <K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>): Promise<string>;
 }
 /**
  * Create a localizable function for a command.
@@ -1166,7 +1251,7 @@ declare function localizable<A extends Args, C = {},
 // for CommandContext
 E extends Record<string, string> = {},
 // for extended resources
-K$1 = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K$1>): Localization<A, C, E>;
+K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
 //#endregion
 //#region ../resources/locales/en-US.d.ts
 declare let COMMAND: string;
@@ -1197,7 +1282,7 @@ declare namespace __json_default_export {
  * @param key - The built-in key to resolve.
  * @returns Prefixed built-in key.
  */
-declare function resolveBuiltInKey<K$1 extends string = CommandBuiltinResourceKeys>(key: K$1): GenerateNamespacedKey<K$1>;
+declare function resolveBuiltInKey<K extends string = CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
 /**
  * Resolve a namespaced key for argument resources.
  *
@@ -1210,7 +1295,7 @@ declare function resolveBuiltInKey<K$1 extends string = CommandBuiltinResourceKe
  * @param name - The command name.
  * @returns Prefixed argument key.
  */
-declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K$1 extends string = KeyOfArgs<RemovedIndex<A>>>(key: K$1, name?: string): string;
+declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, name?: string): string;
 /**
  * Resolve a namespaced key for non-built-in resources.
  *
@@ -1222,7 +1307,7 @@ declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K$1
  * @param name - The command name.
  * @returns Prefixed non-built-in key.
  */
-declare function resolveKey<T extends Record<string, string> = {}, K$1 extends string = (keyof T extends string ? keyof T : string)>(key: K$1, name?: string): string;
+declare function resolveKey<T extends Record<string, string> = {}, K extends string = (keyof T extends string ? keyof T : string)>(key: K, name?: string): string;
 /**
  * Resolve command examples.
  *
@@ -1241,7 +1326,7 @@ declare function resolveExamples<G extends GunshiParamsConstraint = DefaultGunsh
  * @param id - A plugin id to generate a namespaced key.
  * @returns A namespaced key for the plugin.
  */
-declare function namespacedId<K$1 extends string>(id: K$1): GenerateNamespacedKey<K$1, typeof PLUGIN_PREFIX>;
+declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K, typeof PLUGIN_PREFIX>;
 /**
  * Generate a short and long option pair for command arguments.
  *
@@ -1252,4 +1337,4 @@ declare function namespacedId<K$1 extends string>(id: K$1): GenerateNamespacedKe
  */
 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

@@ -1,4 +1,4 @@
-//#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.
 *
@@ -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.5",
+  "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.5",
-    "gunshi": "0.27.5"
+    "@gunshi/resources": "0.28.0",
+    "gunshi": "0.28.0"
   },
   "scripts": {
     "build": "tsdown",