@gunshi/plugin 0.27.0-alpha.9 → 0.27.0-beta.0

package/lib/index.d.ts

@@ -1,7 +1,8 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/parser-Cbxholql.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/parser-C6MbpZjd.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
+ *
  * @module
  */
 /**
@@ -14,6 +15,7 @@
  */
 /**
  * Argument token Kind.
+ *
  * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
  * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
  * - `positional`: positional token
@@ -53,91 +55,462 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-BoS-UnqX.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.0/node_modules/args-tokens/lib/resolver-D64nGlCD.d.ts
 //#region src/resolver.d.ts
 
 /**
- * An argument schema
- * This schema is similar to the schema of the `node:utils`.
- * difference is that:
- * - `required` property and `description` property are added
- * - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
- * - `default` property type, not support multiple types
+ * An argument schema definition for command-line argument parsing.
+ *
+ * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
+ * - Additional `required` and `description` properties
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
  */
 interface ArgSchema {
   /**
-   * Type of argument.
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
    */
   type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
   /**
-   * A single character alias for the argument.
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
    */
   short?: string;
   /**
-   * A description of the argument.
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
    */
   description?: string;
   /**
-   * Whether the argument is required or not.
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user.
+   * If missing, an `ArgResolveError` with type 'required' will be thrown.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
    */
   required?: true;
   /**
-   * Whether the argument allow multiple values or not.
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array.
+   * For options: can be specified multiple times (--tag foo --tag bar)
+   * For positional: collects remaining positional arguments
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
    */
   multiple?: true;
   /**
-   * Whether the negatable option for `boolean` type
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
    */
   negatable?: boolean;
   /**
-   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
    */
   choices?: string[] | readonly string[];
   /**
-   * The default value of the argument.
-   * if the type is 'enum', the default value must be one of the allowed values.
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
    */
   default?: string | boolean | number;
   /**
-   * Whether to convert the argument name to kebab-case.
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
    */
   toKebab?: true;
   /**
-   * A function to parse the value of the argument. if the type is 'custom', this function is required.
-   * If argument value will be invalid, this function have to throw an error.
-   * @param value
-   * @returns Parsed value
-   * @throws An Error, If the value is invalid. Error type should be `Error` or extends it
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * Conflicts only need to be defined on one side - if option A defines a conflict
+   * with option B, the conflict is automatically detected when both are used,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn will throw error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
    */
   parse?: (value: string) => any;
 }
 /**
  * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
  */
 interface Args {
   [option: string]: ArgSchema;
 }
 /**
  * An object that contains the values of the arguments.
+ *
+ * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
  */
 type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
   [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
 };
 type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
 /**
+ * Extracts the value type from the argument schema.
+ *
+ * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
+ *
  * @internal
  */
 type ExtractOptionValue<A extends ArgSchema> = A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? IsFunction<A['parse']> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A['parse']>>> : never : ResolveOptionValue<A, string | boolean | number>;
 type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
 /**
+ * Resolved argument values.
+ *
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
  * @internal
  */
 type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
 /**
+ * Filters the arguments based on their default values.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
+ *
  * @internal
  */
 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.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
  * @internal
  */
 type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
@@ -150,10 +523,15 @@ type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> =
  *
  * Each property indicates whether the corresponding argument was explicitly
  * provided (true) or is using a default value or not provided (false).
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
  */
 type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
 /**
  * Resolve command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ *
  * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
  * @param tokens - An array of {@link ArgToken | tokens}.
  * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
@@ -185,77 +563,106 @@ type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
 //#region ../gunshi/src/plugin/context.d.ts
 /**
  * Type helper to create GunshiParams from extracted args and extensions
+ *
  * @internal
  */
 type ExtractedParams<G extends GunshiParamsConstraint, L extends Record<string, unknown> = {}> = {
   args: ExtractArgs<G>;
-  extensions: ExtractExtensions$1<G> & L;
+  extensions: ExtractExtensions<G> & L;
 };
 /**
  * Gunshi plugin context interface.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command parameters.
+ *
  * @since v0.27.0
  */
 interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Get the global options
+   *
    * @returns A map of global options.
    */
   readonly globalOptions: Map<string, ArgSchema>;
   /**
    * Get the registered sub commands
+   *
    * @returns A map of sub commands.
    */
   readonly subCommands: ReadonlyMap<string, Command<G> | LazyCommand<G>>;
   /**
    * Add a global option.
-   * @param name An option name
-   * @param schema An {@link ArgSchema} for the option
+   *
+   * @param name - An option name
+   * @param schema - An {@linkcode ArgSchema} for the option
    */
   addGlobalOption(name: string, schema: ArgSchema): void;
   /**
    * Add a sub command.
-   * @param name Command name
-   * @param command Command definition
+   *
+   * @param name - Command name
+   * @param command - Command definition
    */
   addCommand(name: string, command: Command<G> | LazyCommand<G>): void;
   /**
    * Check if a command exists.
-   * @param name Command name
+   *
+   * @param name - Command name
    * @returns True if the command exists, false otherwise
    */
   hasCommand(name: string): boolean;
   /**
    * Decorate the header renderer.
+   *
+   * @typeParam L - An extensions type to specify the shape of {@linkcode CommandContext}'s extensions.
+   *
    * @param decorator - A decorator function that wraps the base header renderer.
    */
   decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the usage renderer.
+   *
+   * @typeParam L - An extensions type to specify the shape of {@linkcode CommandContext}'s extensions.
+   *
    * @param decorator - A decorator function that wraps the base usage renderer.
    */
   decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the validation errors renderer.
+   *
+   * @typeParam L - An extensions type to specify the shape of {@linkcode CommandContext}'s extensions.
+   *
    * @param decorator - A decorator function that wraps the base validation errors renderer.
    */
   decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>): void;
   /**
    * Decorate the command execution.
+   *
    * Decorators are applied in reverse order (last registered is executed first).
+   *
+   * @typeParam L - An extensions type to specify the shape of {@linkcode CommandContext}'s extensions.
+   *
    * @param decorator - A decorator function that wraps the command runner
    */
   decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>): void;
 }
-/**
- * Factory function for creating a plugin context.
- * @param decorators - A {@link Decorators} instance.
- * @param initialSubCommands - Initial sub commands map.
- * @returns A new {@link PluginContext} instance.
- */
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
+type ProcessDependency<D, A extends ExtendContext> = D extends string ? D extends keyof A ? { [K in D]: A[K] } : {} : D extends {
+  id: infer ID;
+  optional?: any;
+} ? ID extends string ? ID extends keyof A ? D extends {
+  optional: true;
+} ? { [K in ID]: A[K] | undefined } : { [K in ID]: A[K] } : {} : never : never;
+/**
+ * Helper type to infer dependency extensions with optional support
+ *
+ * @internal
+ */
+type InferDependencyExtensions<D extends ReadonlyArray<PluginDependency | string>, A extends ExtendContext> = D extends readonly [] ? {} : D extends readonly [infer First, ...infer Rest] ? ProcessDependency<First, A> & (Rest extends ReadonlyArray<PluginDependency | string> ? InferDependencyExtensions<Rest, A> : {}) : {};
 /**
  * Plugin dependency definition
+ *
  * @since v0.27.0
  */
 interface PluginDependency {
@@ -265,34 +672,68 @@ interface PluginDependency {
   id: string;
   /**
    * Optional dependency flag.
-   * If true, the plugin will not throw an error if the dependency is not found.
+   * If `true`, the plugin will not throw an error if the dependency is not found
    */
   optional?: boolean;
 }
 /**
  * Plugin function type
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the {@linkcode PluginContext}.
+ *
  * @since v0.27.0
  */
 type PluginFunction<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<PluginContext<G>>) => Awaitable<void>;
 /**
- * Plugin extension for CommandContext
+ * Plugin extension
+ *
+ * @typeParam T - The type of the extension object returned by the plugin extension function.
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of {@linkcode CommandContextCore}.
+ *
+ * @param ctx - The {@linkcode CommandContextCore | command context} core
+ * @param cmd - The {@linkcode Command | command} to which the plugin is being applied
+ * @returns An object of type T that represents the extension provided by the plugin
+ *
  * @since v0.27.0
  */
 type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = DefaultGunshiParams> = (ctx: CommandContextCore<G>, cmd: Command<G>) => Awaitable<T>;
 /**
- * Plugin extension callback type
+ * Plugin extension callback, which is called when the plugin is extended with `extension` option.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of {@linkcode CommandContext} and {@linkcode Command}.
+ *
+ * @param ctx - The {@linkcode CommandContext | command context}
+ * @param cmd - The {@linkcode Command | command}
+ *
  * @since v0.27.0
  */
 type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
+type IsStringLiteral<S extends string> = string extends S ? false : true;
+type MergeExtension<Id, ResolvedDepExt extends ExtendContext, PluginExt extends ExtendContext> = Id extends infer I ? I extends string ? IsStringLiteral<I> extends true ? ResolvedDepExt & { [K in I]: PluginExt } : ResolvedDepExt : ResolvedDepExt : ResolvedDepExt;
 /**
  * Plugin definition options
+ *
  * @since v0.27.0
  */
-interface PluginOptions<T extends Record<string, unknown> = Record<never, never>, G extends GunshiParams = DefaultGunshiParams> {
+interface PluginOptions<DepExt extends ExtendContext = DefaultGunshiParams['extensions'],
+// for plugin dependency extensions
+Id extends string = string,
+// for plugin id
+Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | string)[],
+// for plugin dependencies
+Ext extends Record<string, unknown> = {},
+// for plugin extension type
+ResolvedDepExt extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: InferDependencyExtensions<Deps, DepExt>;
+}>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, DepExt>, Awaited<ReturnType<PluginExt>>>;
+}>> {
   /**
    * Plugin unique identifier
    */
-  id: string;
+  id: Id;
   /**
    * Plugin name
    */
@@ -300,24 +741,28 @@ interface PluginOptions<T extends Record<string, unknown> = Record<never, never>
   /**
    * Plugin dependencies
    */
-  dependencies?: (PluginDependency | string)[];
+  dependencies?: Deps;
   /**
    * Plugin setup function
    */
-  setup?: PluginFunction<G>;
+  setup?: PluginFunction<MergedExt>;
   /**
    * Plugin extension
    */
-  extension?: PluginExtension<T, G>;
+  extension?: PluginExt;
   /**
    * Callback for when the plugin is extended with `extension` option.
    */
-  onExtension?: OnPluginExtension<G>;
+  onExtension?: OnPluginExtension<MergedExt>;
 }
 /**
  * Gunshi plugin, which is a function that receives a PluginContext.
- * @param ctx - A {@link PluginContext}.
- * @returns An {@link Awaitable} that resolves when the plugin is loaded.
+ *
+ * @typeParam E - A type extending {@link GunshiParams} to specify the shape of {@linkcode CommandContext}'s extensions.
+ *
+ * @param ctx - A {@linkcode PluginContext}.
+ * @returns An {@linkcode Awaitable} that resolves when the plugin is loaded.
+ *
  * @since v0.27.0
  */
 type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> = PluginFunction & {
@@ -327,68 +772,153 @@ type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensio
   extension?: CommandContextExtension<E>;
 };
 /**
- * Plugin return type with extension
- * @internal
+ * Plugin return type with extension, which includes the plugin ID, name, dependencies, and extension.
+ *
+ * This type is used to define a plugin at `plugin` function.
+ *
+ * @typeParam E - A type extending {@link GunshiParams} to specify the shape of {@linkcode CommandContext}'s extensions.
  */
 interface PluginWithExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
+  /**
+   * Plugin identifier
+   */
   id: string;
+  /**
+   * Plugin name
+   */
   name: string;
+  /**
+   * Plugin dependencies
+   */
   dependencies?: (PluginDependency | string)[];
+  /**
+   * Plugin extension
+   */
   extension: CommandContextExtension<E>;
 }
 /**
- * Plugin return type without extension
- * @internal
+ * Plugin return type without extension, which includes the plugin ID, name, and dependencies, but no extension.
+ *
+ * This type is used to define a plugin at `plugin` function without extension.
+ *
+ * @typeParam E - A type extending {@link GunshiParams} to specify the shape of {@linkcode CommandContext}'s extensions.
  */
 interface PluginWithoutExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
+  /**
+   * Plugin identifier
+   */
   id: string;
+  /**
+   * Plugin name
+   */
   name: string;
+  /**
+   * Plugin dependencies
+   */
   dependencies?: (PluginDependency | string)[];
 }
 /**
- * Define a plugin with extension capabilities
- * @param options - {@link PluginOptions | plugin options}
- * @return A defined plugin with extension capabilities.
+ * Define a plugin with extension compatibility and typed dependency extensions
+ *
+ * @typeParam Context - A type extending {@linkcode ExtendContext} to specify the shape of plugin dependency extensions.
+ * @typeParam Id - A string type to specify the plugin ID.
+ * @typeParam Deps - A readonly array of {@linkcode PluginDependency} or string to specify the plugin dependencies.
+ * @typeParam Extension - A type to specify the shape of the plugin extension object.
+ *
+ * @param options - {@linkcode PluginOptions | plugin options}
+ * @returns A defined plugin with extension
+ *
  * @since v0.27.0
  */
-declare function plugin<I extends string, P extends PluginExtension<any, DefaultGunshiParams>>(options: {
-  id: I;
+declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'],
+// for plugin dependency extensions
+Id extends string = string,
+// for plugin id
+Deps extends ReadonlyArray<PluginDependency | string> = [],
+// for plugin dependencies
+Extension extends {} = {},
+// for plugin extension type
+ResolvedDepExtensions extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: InferDependencyExtensions<Deps, Context>;
+}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
+}>>(options: {
+  id: Id;
   name?: string;
-  dependencies?: (PluginDependency | string)[];
+  dependencies?: Deps;
   setup?: (ctx: Readonly<PluginContext<GunshiParams<{
     args: Args;
-    extensions: { [K in I]: Awaited<ReturnType<P>> };
+    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
   }>>>) => Awaitable<void>;
-  extension: P;
-  onExtension?: OnPluginExtension<{
-    args: Args;
-    extensions: { [K in I]: Awaited<ReturnType<P>> };
-  }>;
-}): PluginWithExtension<Awaited<ReturnType<P>>>;
+  extension: PluginExt;
+  onExtension?: OnPluginExtension<MergedExtensions>;
+}): PluginWithExtension<Awaited<ReturnType<PluginExt>>>;
 /**
- * Define a plugin without extension capabilities
- * @param options - {@link PluginOptions | plugin options} without extension
- * @returns A defined plugin without extension capabilities.
+ * Define a plugin without extension and typed dependency extensions
+ *
+ * @typeParam Context - A type extending {@linkcode ExtendContext} to specify the shape of plugin dependency extensions.
+ * @typeParam Id - A string type to specify the plugin ID.
+ * @typeParam Deps - A readonly array of {@linkcode PluginDependency} or string to specify the plugin dependencies.
+ * @typeParam Extension - A type to specify the shape of the plugin extension object.
+ *
+ * @param options - {@linkcode PluginOptions | plugin options} without extension
+ * @returns A defined plugin without extension
+ *
  * @since v0.27.0
  */
-declare function plugin(options: {
-  id: string;
+declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'],
+// for plugin dependency extensions
+Id extends string = string,
+// for plugin id
+Deps extends ReadonlyArray<PluginDependency | string> = [],
+// for plugin dependencies
+Extension extends Record<string, unknown> = {},
+// for plugin extension type
+ResolvedDepExtensions extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: InferDependencyExtensions<Deps, Context>;
+}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
+  args: Args;
+  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
+}>>(options: {
+  id: Id;
   name?: string;
-  dependencies?: (PluginDependency | string)[];
-  setup?: (ctx: Readonly<PluginContext<DefaultGunshiParams>>) => Awaitable<void>;
-  onExtension?: OnPluginExtension<DefaultGunshiParams>;
+  dependencies?: Deps;
+  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
+    args: Args;
+    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
+  }>>>) => Awaitable<void>;
+  onExtension?: OnPluginExtension<MergedExtensions>;
 }): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
 //#endregion
 //#region ../gunshi/src/types.d.ts
+/**
+ * Awaitable type.
+ *
+ * @typeParam T - The type of the value that can be awaited.
+ */
 type Awaitable<T> = T | Promise<T>;
 /**
- * Extend command context type. This type is used to extend the command context with additional properties at {@link CommandContext.extensions}.
+ * Prettify a type by flattening its structure.
+ *
+ * @typeParam T - The type to be prettified.
+ */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Extend command context type. This type is used to extend the command context with additional properties at {@linkcode CommandContext.extensions}.
+ *
  * @since v0.27.0
  */
 type ExtendContext = Record<string, unknown>;
 /**
  * Gunshi unified parameter type.
+ *
  * This type combines both argument definitions and command context extensions.
+ *
+ * @typeParam P - The type of parameters, which can include `args` and `extensions`.
+ *
  * @since v0.27.0
  */
 interface GunshiParams<P extends {
@@ -399,50 +929,65 @@ interface GunshiParams<P extends {
   extensions: {};
 }> {
   /**
-   * Command argument definitions
+   * Command argument definitions.
    */
   args: P extends {
     args: infer A extends Args;
   } ? A : Args;
   /**
-   * Command context extensions
+   * Command context extensions.
    */
   extensions: P extends {
     extensions: infer E extends ExtendContext;
   } ? E : {};
 }
 /**
- * Default Gunshi parameters
+ * Default Gunshi parameters.
+ *
  * @since v0.27.0
  */
 type DefaultGunshiParams = GunshiParams;
 /**
  * Generic constraint for command-related types.
- * This type constraint allows both GunshiParams and objects with extensions.
+ *
+ * This type constraint allows both {@linkcode GunshiParams} and objects with extensions.
+ *
  * @since v0.27.0
  */
 type GunshiParamsConstraint = GunshiParams<any> | {
+  args: Args;
+} | {
   extensions: ExtendContext;
 };
 /**
- * Type helper to extract args from G
+ * Type helper to extract args
+ *
+ * @typeParam G - The type of {@linkcode GunshiParams} or an object with {@linkcode Args}.
+ *
  * @internal
  */
-type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
+type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : G extends {
+  args: infer A extends Args;
+} ? A : Args;
 /**
- * Type helper to extract explicitly provided argument flags from G
+ * Type helper to extract explicitly provided argument flags.
+ *
+ * @typeParam G - The type of {@linkcode GunshiParams}.
+ *
  * @internal
  */
 type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs<G>>;
 /**
  * Type helper to extract extensions from G
+ *
  * @internal
  */
-type ExtractExtensions$1<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
+type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
   extensions: infer E;
 } ? E : {};
 /**
  * Type helper to normalize G to GunshiParams
+ *
  * @internal
  */
 type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
@@ -453,62 +998,73 @@ type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
 }> : DefaultGunshiParams;
 /**
  * Command environment.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command environments.
  */
 interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Current working directory.
-   * @see {@link CliOptions.cwd}
+   *
+   * @see {@linkcode CliOptions.cwd}
    */
   cwd: string | undefined;
   /**
    * Command name.
-   * @see {@link CliOptions.name}
+   *
+   * @see {@linkcode CliOptions.name}
    */
   name: string | undefined;
   /**
    * Command description.
-   * @see {@link CliOptions.description}
    *
+   * @see {@linkcode CliOptions.description}
    */
   description: string | undefined;
   /**
    * Command version.
-   * @see {@link CliOptions.version}
+   *
+   * @see {@linkcode CliOptions.version}
    */
   version: string | undefined;
   /**
    * Left margin of the command output.
+   *
    * @default 2
-   * @see {@link CliOptions.leftMargin}
+   * @see {@linkcode CliOptions.leftMargin}
    */
   leftMargin: number;
   /**
    * Middle margin of the command output.
+   *
    * @default 10
-   * @see {@link CliOptions.middleMargin}
+   * @see {@linkcode CliOptions.middleMargin}
    */
   middleMargin: number;
   /**
    * Whether to display the usage option type.
+   *
    * @default false
-   * @see {@link CliOptions.usageOptionType}
+   * @see {@linkcode CliOptions.usageOptionType}
    */
   usageOptionType: boolean;
   /**
    * Whether to display the option value.
+   *
    * @default true
-   * @see {@link CliOptions.usageOptionValue}
+   * @see {@linkcode CliOptions.usageOptionValue}
    */
   usageOptionValue: boolean;
   /**
    * Whether to display the command usage.
+   *
    * @default false
-   * @see {@link CliOptions.usageSilent}
+   * @see {@linkcode CliOptions.usageSilent}
    */
   usageSilent: boolean;
   /**
    * Sub commands.
-   * @see {@link CliOptions.subCommands}
+   *
+   * @see {@linkcode CliOptions.subCommands}
    */
   subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
   /**
@@ -525,25 +1081,30 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
   renderValidationErrors: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null | undefined;
   /**
    * Hook that runs before any command execution
-   * @see {@link CliOptions.onBeforeCommand}
+   *
+   * @see {@linkcode CliOptions.onBeforeCommand}
    * @since v0.27.0
    */
   onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
   /**
    * Hook that runs after successful command execution
-   * @see {@link CliOptions.onAfterCommand}
+   *
+   * @see {@linkcode CliOptions.onAfterCommand}
    * @since v0.27.0
    */
   onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>) | undefined;
   /**
    * Hook that runs when a command throws an error
-   * @see {@link CliOptions.onErrorCommand}
+   *
+   * @see {@linkcode CliOptions.onErrorCommand}
    * @since v0.27.0
    */
   onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
 }
 /**
- * CLI options of `cli` function.
+ * CLI options of {@linkcode cli} function.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of cli options.
  */
 interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
@@ -566,7 +1127,7 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Sub commands.
    */
-  subCommands?: Map<string, Command<any> | LazyCommand<any>>;
+  subCommands?: Record<string, Command<any> | LazyCommand<any>> | Map<string, Command<any> | LazyCommand<any>>;
   /**
    * Left margin of the command output.
    */
@@ -599,19 +1160,29 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Render function the validation errors.
    */
   renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
+  /**
+   * Whether to fallback to entry command when the sub-command is not found.
+   *
+   * @default false
+   * @since v0.27.0
+   */
+  fallbackToEntry?: boolean;
   /**
    * User plugins.
+   *
    * @since v0.27.0
    */
   plugins?: Plugin[];
   /**
    * Hook that runs before any command execution
+   *
    * @param ctx - The command context
    * @since v0.27.0
    */
   onBeforeCommand?: (ctx: Readonly<CommandContext<G>>) => Awaitable<void>;
   /**
    * Hook that runs after successful command execution
+   *
    * @param ctx - The command context
    * @param result - The command execution result
    * @since v0.27.0
@@ -619,6 +1190,7 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
   /**
    * Hook that runs when a command throws an error
+   *
    * @param ctx - The command context
    * @param error - The error thrown during execution
    * @since v0.27.0
@@ -627,31 +1199,37 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
 }
 /**
  * Command call mode.
+ *
+ * - `entry`: The command is executed as an entry command.
+ * - `subCommand`: The command is executed as a sub-command.
  */
 type CommandCallMode = 'entry' | 'subCommand' | 'unexpected';
 /**
  * Command context.
+ *
  * Command context is the context of the command execution.
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  */
 interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
    * Command name, that is the command that is executed.
-   * The command name is same {@link CommandEnvironment.name}.
+   * The command name is same {@linkcode CommandEnvironment.name}.
    */
   name: string | undefined;
   /**
    * Command description, that is the description of the command that is executed.
-   * The command description is same {@link CommandEnvironment.description}.
+   * The command description is same {@linkcode CommandEnvironment.description}.
    */
   description: string | undefined;
   /**
    * Command environment, that is the environment of the command that is executed.
-   * The command environment is same {@link CommandEnvironment}.
+   * The command environment is same {@linkcode CommandEnvironment}.
    */
   env: Readonly<CommandEnvironment<G>>;
   /**
    * Command arguments, that is the arguments of the command that is executed.
-   * The command arguments is same {@link Command.args}.
+   * The command arguments is same {@linkcode Command.args}.
    */
   args: ExtractArgs<G>;
   /**
@@ -665,7 +1243,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   explicit: ExtractArgExplicitlyProvided<G>;
   /**
    * Command values, that is the values of the command that is executed.
-   * Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
+   * Resolve values with `resolveArgs` from command arguments and {@linkcode Command.args}.
    */
   values: ArgValues<ExtractArgs<G>>;
   /**
@@ -697,22 +1275,24 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   callMode: CommandCallMode;
   /**
    * Whether to convert the camel-case style argument name to kebab-case.
-   * This context value is set from {@link Command.toKebab} option.
+   * This context value is set from {@linkcode Command.toKebab} option.
    */
   toKebab?: boolean;
   /**
    * Output a message.
-   * If {@link CommandEnvironment.usageSilent} is true, the message is not output.
-   * @param message an output message, @see {@link console.log}
-   * @param optionalParams an optional parameters, @see {@link console.log}
-   * @internal
+   *
+   * If {@linkcode CommandEnvironment.usageSilent} is true, the message is not output.
+   *
+   * @param message - an output message, see {@linkcode console.log}
+   * @param optionalParams - an optional parameters, see {@linkcode console.log}
    */
   log: (message?: any, ...optionalParams: any[]) => void;
   /**
    * Command context extensions.
+   *
    * @since v0.27.0
    */
-  extensions: keyof ExtractExtensions$1<G> extends never ? undefined : ExtractExtensions$1<G>;
+  extensions: keyof ExtractExtensions<G> extends never ? any : ExtractExtensions<G>;
   /**
    * Validation error from argument parsing.
    * This will be set if argument validation fails during CLI execution.
@@ -721,20 +1301,38 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
 }
 /**
  * CommandContextCore type (base type without extensions)
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
  * @since v0.27.0
  */
 type CommandContextCore<G extends GunshiParamsConstraint = DefaultGunshiParams> = Readonly<CommandContext<G>>;
 /**
  * Command context extension
+ *
+ * @typeParam E - A type extending {@linkcode GunshiParams.extensions} to specify the shape of the extension.
+ *
  * @since v0.27.0
  */
 interface CommandContextExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> {
+  /**
+   * Plugin identifier
+   */
   readonly key: symbol;
+  /**
+   * Plugin extension factory
+   */
   readonly factory: (ctx: CommandContextCore, cmd: Command) => Awaitable<E>;
+  /**
+   * Plugin extension factory after hook
+   */
   readonly onFactory?: (ctx: Readonly<CommandContext>, cmd: Readonly<Command>) => Awaitable<void>;
 }
 /**
  * Rendering control options
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of render options.
+ *
  * @since v0.27.0
  */
 interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
@@ -762,6 +1360,8 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
 }
 /**
  * Command interface.
+ *
+ * @typeParam G - The Gunshi parameters constraint
  */
 interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
@@ -790,89 +1390,108 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   run?: CommandRunner<G>;
   /**
    * Whether to convert the camel-case style argument name to kebab-case.
-   * If you will set to `true`, All {@link Command.args} names will be converted to kebab-case.
+   * If you will set to `true`, All {@linkcode Command.args} names will be converted to kebab-case.
    */
   toKebab?: boolean;
   /**
    * Whether this is an internal command.
    * Internal commands are not shown in help usage.
+   *
    * @default false
    * @since v0.27.0
    */
   internal?: boolean;
   /**
    * Whether this command is an entry command.
+   *
    * @default undefined
    * @since v0.27.0
    */
   entry?: boolean;
   /**
    * Rendering control options
+   *
    * @since v0.27.0
    */
   rendering?: RenderingOptions<G>;
 }
 /**
  * Lazy command interface.
+ *
  * Lazy command that's not loaded until it is executed.
+ *
+ * @typeParam G - The Gunshi parameters constraint
+ * @typeParam D - The partial command definition provided to lazy function
  */
-type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
+type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = {}> = {
   /**
    * Command load function
    */
   (): Awaitable<Command<G> | CommandRunner<G>>;
-  /**
-   * Command name
-   */
+} & (D extends {
+  name: infer N;
+} ? {
+  commandName: N;
+} : {
   commandName?: string;
-} & Omit<Command<G>, 'run' | 'name'>;
-/**
- * Define a command type.
- */
-
+}) & Omit<D, 'name' | 'run'> & Partial<Omit<Command<G>, keyof D | 'run' | 'name'>>;
 /**
  * Command examples fetcher.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param ctx - A {@link CommandContext | command context}
  * @returns A fetched command examples.
  */
 type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
 /**
  * Command runner.
- * @param ctx A {@link CommandContext | command context}
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param ctx - A {@link CommandContext | command context}
  * @returns void or string (for CLI output)
  */
 type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
-/**
- * Command loader.
- * A function that returns a command or command runner.
- * This is used to lazily load commands.
- * @returns A command or command runner
- */
-
 /**
  * Command decorator.
+ *
  * A function that wraps a command runner to add or modify its behavior.
- * @param baseRunner The base command runner to decorate
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param baseRunner - The base command runner to decorate
  * @returns The decorated command runner
+ *
  * @since v0.27.0
  */
 type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
 /**
  * Renderer decorator type.
+ *
  * A function that wraps a base renderer to add or modify its behavior.
- * @param baseRenderer The base renderer function to decorate
- * @param ctx The command context
+ *
+ * @typeParam T - The type of the rendered result.
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param baseRenderer - The base renderer function to decorate
+ * @param ctx - The command context
  * @returns The decorated result
+ *
  * @since v0.27.0
  */
 type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>) => Promise<T>, ctx: Readonly<CommandContext<G>>) => Promise<T>;
 /**
  * Validation errors renderer decorator type.
  * A function that wraps a validation errors renderer to add or modify its behavior.
- * @param baseRenderer The base validation errors renderer function to decorate
- * @param ctx The command context
- * @param error The aggregate error containing validation errors
+ *
+ * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
+ *
+ * @param baseRenderer - The base validation errors renderer function to decorate
+ * @param ctx - The command context
+ * @param error - The aggregate error containing validation errors
  * @returns The decorated result
+ *
  * @since v0.27.0
  */
 type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
@@ -884,55 +1503,58 @@ declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
 //#region ../gunshi/src/context.d.ts
 /**
  * Extract extension return types from extensions record
+ *
  * @internal
  */
-type ExtractExtensions<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+type ExtractExtensions$1<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
 /**
  * Parameters of {@link createCommandContext}
  */
 interface CommandContextParams<G extends GunshiParams | {
+  args: Args;
+} | {
   extensions: ExtendContext;
 }, V extends ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>> {
   /**
    * An arguments of target command
    */
-  args: ExtractArgs<G>;
+  args?: ExtractArgs<G>;
   /**
    * Explicitly provided arguments
    */
-  explicit: ExtractArgExplicitlyProvided<G>;
+  explicit?: ExtractArgExplicitlyProvided<G>;
   /**
    * A values of target command
    */
-  values: V;
+  values?: V;
   /**
    * A positionals arguments, which passed to the target command
    */
-  positionals: string[];
+  positionals?: string[];
   /**
    * A rest arguments, which passed to the target command
    */
-  rest: string[];
+  rest?: string[];
   /**
    * Original command line arguments
    */
-  argv: string[];
+  argv?: string[];
   /**
    * Argument tokens that are parsed by the `parseArgs` function
    */
-  tokens: ArgToken[];
+  tokens?: ArgToken[];
   /**
    * Whether the command is omitted
    */
-  omitted: boolean;
+  omitted?: boolean;
   /**
    * Command call mode.
    */
-  callMode: CommandCallMode;
+  callMode?: CommandCallMode;
   /**
    * A target command
    */
-  command: C;
+  command?: C;
   /**
    * Plugin extensions to apply as the command context extension.
    */
@@ -940,16 +1562,17 @@ interface CommandContextParams<G extends GunshiParams | {
   /**
    * A command options, which is spicialized from `cli` function
    */
-  cliOptions: CliOptions<G>;
+  cliOptions?: CliOptions<G>;
   /**
    * Validation error from argument parsing.
    */
   validationError?: AggregateError;
 }
 /**
- * Create a {@link CommandContext | command context}
- * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
- * @returns A {@link CommandContext | command context}, which is readonly
+ * Create a command context.
+ *
+ * @param param - A {@link CommandContextParams | parameters} to create a command context.
+ * @returns A {@link CommandContext | command context}, which is readonly.
  */
 declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = {}>({
   args,
@@ -965,9 +1588,9 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   callMode,
   omitted,
   validationError
-}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
+}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions$1<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
   args: ExtractArgs<G>;
-  extensions: ExtractExtensions<E>;
+  extensions: ExtractExtensions$1<E>;
 }>>>>;
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };