@gunshi/bone 0.26.3 → 0.27.0-alpha.10

package/lib/index.d.ts

@@ -1,153 +1,188 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/parser-FiQIAw-2.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/parser-Cbxholql.d.ts
 //#region src/parser.d.ts
 /**
-* Entry point of argument parser.
-* @module
-*/
-/**
-* forked from `nodejs/node` (`pkgjs/parseargs`)
-* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
-* code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
-*
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-/**
-* 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
-*/
-type ArgTokenKind = "option" | "option-terminator" | "positional";
-/**
-* Argument token.
-*/
+ * Entry point of argument parser.
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * 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
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
 interface ArgToken {
   /**
-  * Argument token kind.
-  */
+   * Argument token kind.
+   */
   kind: ArgTokenKind;
   /**
-  * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
-  */
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
   index: number;
   /**
-  * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
-  */
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
   name?: string;
   /**
-  * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
-  */
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
   rawName?: string;
   /**
-  * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
-  * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
-  */
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
   value?: string;
   /**
-  * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
-  */
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
   inlineValue?: boolean;
-} //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
-
+}
 /**
-* Parser Options.
-*/
+ * Parser Options.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-BoS-UnqX.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
+ * 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
+ */
 interface ArgSchema {
   /**
-  * Type of argument.
-  */
-  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
+   * Type of argument.
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
   /**
-  * A single character alias for the argument.
-  */
+   * A single character alias for the argument.
+   */
   short?: string;
   /**
-  * A description of the argument.
-  */
+   * A description of the argument.
+   */
   description?: string;
   /**
-  * Whether the argument is required or not.
-  */
+   * Whether the argument is required or not.
+   */
   required?: true;
   /**
-  * Whether the argument allow multiple values or not.
-  */
+   * Whether the argument allow multiple values or not.
+   */
   multiple?: true;
   /**
-  * Whether the negatable option for `boolean` type
-  */
+   * Whether the negatable option for `boolean` type
+   */
   negatable?: boolean;
   /**
-  * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
-  */
+   * The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
+   */
   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.
-  */
+   * The default value of the argument.
+   * if the type is 'enum', the default value must be one of the allowed values.
+   */
   default?: string | boolean | number;
   /**
-  * Whether to convert the argument name to kebab-case.
-  */
+   * Whether to convert the argument name to kebab-case.
+   */
   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
-  */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   * 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
+   */
   parse?: (value: string) => any;
 }
 /**
-* An object that contains {@link ArgSchema | argument schema}.
-*/
+ * An object that contains {@link ArgSchema | argument schema}.
+ */
 interface Args {
   [option: string]: ArgSchema;
 }
 /**
-* An object that contains the values of the arguments.
-*/
+ * An object that contains the values of the 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;
 };
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
 /**
-* @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;
+ * @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;
 /**
-* @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;
+ * @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;
 /**
-* @internal
-*/
+ * @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] };
 /**
-* @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] };
+ * @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] };
+/**
+ * An arguments for {@link resolveArgs | resolve arguments}.
+ */
 
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ */
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+/**
+ * Resolve 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}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
-/**
-* An arguments for {@link resolveArgs | resolve arguments}.
-*/
 /**
  * Type helper to create GunshiParams from extracted args and extensions
  * @internal
@@ -158,6 +193,7 @@ type ExtractedParams<G extends GunshiParamsConstraint, L extends Record<string,
 };
 /**
  * Gunshi plugin context interface.
+ * @since v0.27.0
  */
 interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   /**
@@ -165,12 +201,29 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    * @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
    */
   addGlobalOption(name: string, schema: ArgSchema): void;
+  /**
+   * Add a sub command.
+   * @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
+   * @returns True if the command exists, false otherwise
+   */
+  hasCommand(name: string): boolean;
   /**
    * Decorate the header renderer.
    * @param decorator - A decorator function that wraps the base header renderer.
@@ -193,16 +246,17 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    */
   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;
 }
-
-//#endregion
-//#region ../gunshi/src/plugin/core.d.ts
 /**
  * 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
 /**
  * Plugin dependency definition
+ * @since v0.27.0
  */
 interface PluginDependency {
   /**
@@ -216,17 +270,20 @@ interface PluginDependency {
   optional?: boolean;
 }
 /**
- *  Plugin function type
+ * Plugin function type
+ * @since v0.27.0
  */
 type PluginFunction<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<PluginContext<G>>) => Awaitable<void>;
 /**
  * Plugin extension for CommandContext
+ * @since v0.27.0
  */
 
 /**
  * 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.
+ * @since v0.27.0
  */
 type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> = PluginFunction & {
   id: string;
@@ -234,21 +291,22 @@ type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensio
   dependencies?: (PluginDependency | string)[];
   extension?: CommandContextExtension<E>;
 };
-
-//#endregion
-//#region ../gunshi/src/types.d.ts
 /**
  * Plugin return type with extension
  * @internal
  */
+//#endregion
+//#region ../gunshi/src/types.d.ts
 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}.
+ * @since v0.27.0
  */
 type ExtendContext = Record<string, unknown>;
 /**
  * Gunshi unified parameter type.
  * This type combines both argument definitions and command context extensions.
+ * @since v0.27.0
  */
 interface GunshiParams<P extends {
   args?: Args;
@@ -272,11 +330,13 @@ interface GunshiParams<P extends {
 }
 /**
  * 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.
+ * @since v0.27.0
  */
 type GunshiParamsConstraint = GunshiParams<any> | {
   extensions: ExtendContext;
@@ -286,6 +346,11 @@ type GunshiParamsConstraint = GunshiParams<any> | {
  * @internal
  */
 type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
+/**
+ * Type helper to extract explicitly provided argument flags from G
+ * @internal
+ */
+type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs<G>>;
 /**
  * Type helper to extract extensions from G
  * @internal
@@ -378,16 +443,19 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
   /**
    * Hook that runs before any command execution
    * @see {@link 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}
+   * @since v0.27.0
    */
-  onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | void) => Awaitable<void>) | undefined;
+  onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>) | undefined;
   /**
    * Hook that runs when a command throws an error
    * @see {@link CliOptions.onErrorCommand}
+   * @since v0.27.0
    */
   onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
 }
@@ -450,23 +518,27 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
   /**
    * 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
    */
-  onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | void) => Awaitable<void>;
+  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
    */
   onErrorCommand?: (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>;
 }
@@ -499,6 +571,15 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    * The command arguments is same {@link Command.args}.
    */
   args: ExtractArgs<G>;
+  /**
+   * Whether arguments were explicitly provided by the user.
+   *
+   * - `true`: The argument was explicitly provided via command line
+   * - `false`: The argument was not explicitly provided. This means either:
+   *   - The value comes from a default value defined in the argument schema
+   *   - The value is `undefined` (no explicit input and no default value)
+   */
+  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}.
@@ -545,7 +626,8 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    */
   log: (message?: any, ...optionalParams: any[]) => void;
   /**
-   *  Command context extensions.
+   * Command context extensions.
+   * @since v0.27.0
    */
   extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
   /**
@@ -556,16 +638,45 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
 }
 /**
  * CommandContextCore type (base type without extensions)
+ * @since v0.27.0
  */
 type CommandContextCore<G extends GunshiParamsConstraint = DefaultGunshiParams> = Readonly<CommandContext<G>>;
 /**
  * Command context extension
+ * @since v0.27.0
  */
 interface CommandContextExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> {
   readonly key: symbol;
   readonly factory: (ctx: CommandContextCore, cmd: Command) => Awaitable<E>;
   readonly onFactory?: (ctx: Readonly<CommandContext>, cmd: Readonly<Command>) => Awaitable<void>;
 }
+/**
+ * Rendering control options
+ * @since v0.27.0
+ */
+interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Header rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  header?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Usage rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Validation errors rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
+}
 /**
  * Command interface.
  */
@@ -599,6 +710,24 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * If you will set to `true`, All {@link 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.
@@ -629,7 +758,7 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  * @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<void | string>;
+type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
 /**
  * Command loader.
  * A function that returns a command or command runner.
@@ -642,14 +771,16 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
  * A function that wraps a command runner to add or modify its behavior.
  * @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<void | string>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<void | string>;
+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
  * @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>;
 /**
@@ -659,9 +790,9 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
  * @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>;
-
 //#endregion
 //#region ../gunshi/src/cli/bone.d.ts
 /**
@@ -694,6 +825,5 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
  * @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
  */
 declare function cli<G extends GunshiParams = DefaultGunshiParams>(argv: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
-
 //#endregion
-export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, RendererDecorator, ValidationErrorsDecorator, cli };
+export { type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, RendererDecorator, RenderingOptions, ValidationErrorsDecorator, cli };

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/parser-Dr4iAGaX.js
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/parser-Dr4iAGaX.js
 const HYPHEN_CHAR = "-";
 const HYPHEN_CODE = HYPHEN_CHAR.codePointAt(0);
 const EQUAL_CHAR = "=";
@@ -188,7 +188,7 @@ function hasOptionValue(value) {
 }
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/utils-N7UlhLbz.js
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/utils-N7UlhLbz.js
 /**
 * Entry point of utils.
 *
@@ -205,14 +205,36 @@ function kebabnize(str) {
 }
 
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-Q4k2fgTW.js
+//#region ../../node_modules/.pnpm/args-tokens@0.22.0/node_modules/args-tokens/lib/resolver-Bcd8oyPt.js
 const SKIP_POSITIONAL_DEFAULT = -1;
 /**
 * Resolve 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}.
-* @returns An object that contains the values of the arguments, positional arguments, rest arguments, and {@link AggregateError | validation errors}.
+* @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+*
+* @example
+* ```typescript
+* // passed tokens: --port 3000
+*
+* const { values, explicit } = resolveArgs({
+*   port: {
+*     type: 'number',
+*     default: 8080
+*   },
+*   host: {
+*     type: 'string',
+*     default: 'localhost'
+*   }
+* }, parsedTokens)
+*
+* values.port // 3000
+* values.host // 'localhost'
+*
+* explicit.port // true (explicitly provided)
+* explicit.host // false (not provided, fallback to default)
+* ```
 */
 function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKIP_POSITIONAL_DEFAULT, toKebab = false } = {}) {
 	const skipPositionalIndex = typeof skipPositional === "number" ? Math.max(skipPositional, SKIP_POSITIONAL_DEFAULT) : SKIP_POSITIONAL_DEFAULT;
@@ -312,6 +334,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	*/
 	const values = Object.create(null);
 	const errors = [];
+	const explicit = Object.create(null);
 	function checkTokenName(option, schema, token) {
 		return token.name === (schema.type === "boolean" ? schema.negatable && token.name?.startsWith("no-") ? `no-${option}` : option : option);
 	}
@@ -322,6 +345,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	let positionalsCount = 0;
 	for (const [rawArg, schema] of Object.entries(args)) {
 		const arg = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
+		explicit[rawArg] = false;
 		if (schema.required) {
 			const found = optionTokens.find((token) => {
 				return schema.short && token.name === schema.short || token.rawName && hasLongOptionPrefix(token.rawName) && token.name === arg;
@@ -347,6 +371,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 					errors.push(invalid);
 					continue;
 				}
+				explicit[rawArg] = true;
 				if (schema.type === "boolean") token.value = void 0;
 				const [parsedValue, error] = parse(token, arg, schema);
 				if (error) errors.push(error);
@@ -362,7 +387,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 		values,
 		positionals: positionalTokens.map((token) => token.value),
 		rest,
-		error: errors.length > 0 ? new AggregateError(errors) : void 0
+		error: errors.length > 0 ? new AggregateError(errors) : void 0,
+		explicit
 	};
 }
 function parse(token, option, schema) {
@@ -421,7 +447,7 @@ function createTypeError(option, schema) {
 //#region ../gunshi/src/constants.ts
 const ANONYMOUS_COMMAND_NAME = "(anonymous)";
 const NOOP = () => {};
-const COMMAND_OPTIONS_DEFAULT = {
+const CLI_OPTIONS_DEFAULT = {
 	name: void 0,
 	description: void 0,
 	version: void 0,
@@ -450,7 +476,9 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			name: cmd.commandName,
 			description: cmd.description,
 			args: cmd.args,
-			examples: cmd.examples
+			examples: cmd.examples,
+			internal: cmd.internal,
+			entry: cmd.entry
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
 		command = Object.assign(create(), baseCommand);
@@ -464,6 +492,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 				command.description = loaded.description;
 				command.args = loaded.args;
 				command.examples = loaded.examples;
+				command.internal = loaded.internal;
+				command.entry = loaded.entry;
 				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
 			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
 		}
@@ -494,7 +524,7 @@ function deepFreeze(obj, ignores = []) {
 * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
 * @returns A {@link CommandContext | command context}, which is readonly
 */
-async function createCommandContext({ args, values, positionals, rest, argv, tokens, command, extensions = {}, cliOptions, callMode = "entry", omitted = false, validationError }) {
+async function createCommandContext({ args, explicit, values, positionals, rest, argv, tokens, command, extensions = {}, cliOptions, callMode = "entry", omitted = false, validationError }) {
 	/**
 	* normailize the options schema and values, to avoid prototype pollution
 	*/
@@ -505,7 +535,16 @@ async function createCommandContext({ args, values, positionals, rest, argv, tok
 	/**
 	* setup the environment
 	*/
-	const env = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, cliOptions);
+	const env = Object.assign(create(), CLI_OPTIONS_DEFAULT, cliOptions);
+	/**
+	* apply Command definition's rendering option with highest priority
+	*/
+	if (command.rendering) {
+		const { header, usage, validationErrors } = command.rendering;
+		if (header !== void 0) env.renderHeader = header;
+		if (usage !== void 0) env.renderUsage = usage;
+		if (validationErrors !== void 0) env.renderValidationErrors = validationErrors;
+	}
 	/**
 	* create the command context
 	*/
@@ -516,6 +555,7 @@ async function createCommandContext({ args, values, positionals, rest, argv, tok
 		callMode,
 		env,
 		args: _args,
+		explicit,
 		values,
 		positionals,
 		rest,
@@ -619,13 +659,15 @@ function createDecorators() {
 /**
 * 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.
 */
-function createPluginContext(decorators) {
+function createPluginContext(decorators, initialSubCommands) {
 	/**
 	* private states
 	*/
 	const globalOptions = new Map();
+	const subCommands = new Map(initialSubCommands || []);
 	/**
 	* public interfaces
 	*/
@@ -638,6 +680,17 @@ function createPluginContext(decorators) {
 			if (globalOptions.has(name)) throw new Error(`Global option '${name}' is already registered`);
 			globalOptions.set(name, schema);
 		},
+		get subCommands() {
+			return new Map(subCommands);
+		},
+		addCommand(name, command) {
+			if (!name) throw new Error("Command name must be a non-empty string");
+			if (subCommands.has(name)) throw new Error(`Command '${name}' is already registered`);
+			subCommands.set(name, command);
+		},
+		hasCommand(name) {
+			return subCommands.has(name);
+		},
 		decorateHeaderRenderer(decorator) {
 			decorators.addHeaderDecorator(decorator);
 		},
@@ -695,15 +748,16 @@ function resolveDependencies(plugins) {
 //#region ../gunshi/src/cli/core.ts
 async function cliCore(argv, entry, options, plugins) {
 	const decorators = createDecorators();
-	const pluginContext = createPluginContext(decorators);
+	const initialSubCommands = createInitialSubCommands(options, entry);
+	const pluginContext = createPluginContext(decorators, initialSubCommands);
 	const resolvedPlugins = await applyPlugins(pluginContext, [...plugins, ...options.plugins || []]);
-	const cliOptions = normalizeCliOptions(options, entry, decorators);
+	const cliOptions = normalizeCliOptions(options, decorators, pluginContext);
 	const tokens = parseArgs(argv);
 	const subCommand = getSubCommand(tokens);
 	const { commandName: name, command, callMode } = await resolveCommand(subCommand, entry, cliOptions);
 	if (!command) throw new Error(`Command not found: ${name || ""}`);
 	const args = resolveArguments(pluginContext, getCommandArgs(command));
-	const { values, positionals, rest, error } = resolveArgs(args, tokens, {
+	const { explicit, values, positionals, rest, error } = resolveArgs(args, tokens, {
 		shortGrouping: true,
 		toKebab: command.toKebab,
 		skipPositional: cliOptions.subCommands.size > 0 ? 0 : -1
@@ -711,6 +765,7 @@ async function cliCore(argv, entry, options, plugins) {
 	const omitted = !subCommand;
 	const commandContext = await createCommandContext({
 		args,
+		explicit,
 		values,
 		positionals,
 		rest,
@@ -749,13 +804,17 @@ function getCommandArgs(cmd) {
 function resolveArguments(pluginContext, args) {
 	return Object.assign(create(), Object.fromEntries(pluginContext.globalOptions), args);
 }
-function normalizeCliOptions(options, entry, decorators) {
+function createInitialSubCommands(options, entryCmd) {
 	const subCommands = new Map(options.subCommands);
-	if (options.subCommands) {
-		if (isLazyCommand(entry)) subCommands.set(entry.commandName, entry);
-		else if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
+	if ((options.subCommands || subCommands.size > 0) && (isLazyCommand(entryCmd) || typeof entryCmd === "object")) {
+		entryCmd.entry = true;
+		subCommands.set(resolveEntryName(entryCmd), entryCmd);
 	}
-	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	return subCommands;
+}
+function normalizeCliOptions(options, decorators, pluginContext) {
+	const subCommands = new Map(pluginContext.subCommands);
+	const resolvedOptions = Object.assign(create(), CLI_OPTIONS_DEFAULT, options, { subCommands });
 	if (resolvedOptions.renderHeader === void 0) resolvedOptions.renderHeader = decorators.getHeaderRenderer();
 	if (resolvedOptions.renderUsage === void 0) resolvedOptions.renderUsage = decorators.getUsageRenderer();
 	if (resolvedOptions.renderValidationErrors === void 0) resolvedOptions.renderValidationErrors = decorators.getValidationErrorsRenderer();
@@ -775,7 +834,10 @@ async function resolveCommand(sub, entry, options) {
 			callMode: "entry"
 		};
 		else return {
-			command: { run: entry },
+			command: {
+				run: entry,
+				entry: true
+			},
 			callMode: "entry"
 		};
 		else if (typeof entry === "object") return {
@@ -800,7 +862,7 @@ async function resolveCommand(sub, entry, options) {
 	};
 }
 function resolveEntryName(entry) {
-	return entry.name || ANONYMOUS_COMMAND_NAME;
+	return isLazyCommand(entry) ? entry.commandName || ANONYMOUS_COMMAND_NAME : entry.name || ANONYMOUS_COMMAND_NAME;
 }
 function getPluginExtensions(plugins) {
 	const extensions = create();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/bone",
   "description": "gunshi minimum",
-  "version": "0.26.3",
+  "version": "0.27.0-alpha.10",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,15 +51,15 @@
     }
   },
   "devDependencies": {
-    "deno": "^2.3.3",
-    "jsr": "^0.13.4",
+    "deno": "^2.4.2",
+    "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.3",
-    "@gunshi/definition": "0.26.3",
-    "@gunshi/plugin-renderer": "0.26.3",
-    "@gunshi/plugin-global": "0.26.3",
-    "gunshi": "0.26.3"
+    "tsdown": "^0.13.0",
+    "@gunshi/definition": "0.27.0-alpha.10",
+    "@gunshi/plugin-global": "0.27.0-alpha.10",
+    "@gunshi/plugin-renderer": "0.27.0-alpha.10",
+    "gunshi": "0.27.0-alpha.10"
   },
   "scripts": {
     "build": "tsdown",