@gunshi/bone 0.27.0-alpha.1 → 0.27.0-alpha.10

package/lib/index.d.ts

@@ -1,151 +1,186 @@
-//#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;
 }
 /**
-* Parser Options.
-*/
+ * Parser Options.
+ */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
+//#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}.
-*/
+ * 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
 /**
@@ -166,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.
@@ -197,6 +249,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
 /**
  * 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
@@ -293,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
@@ -513,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}.
@@ -583,6 +650,33 @@ interface CommandContextExtension<E extends GunshiParams['extensions'] = Default
   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.
  */
@@ -616,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.
@@ -714,4 +826,4 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
  */
 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.27.0-alpha.1",
+  "version": "0.27.0-alpha.10",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,15 +51,15 @@
     }
   },
   "devDependencies": {
-    "deno": "^2.4.0",
+    "deno": "^2.4.2",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.9",
-    "@gunshi/definition": "0.27.0-alpha.1",
-    "gunshi": "0.27.0-alpha.1",
-    "@gunshi/plugin-global": "0.27.0-alpha.1",
-    "@gunshi/plugin-renderer": "0.27.0-alpha.1"
+    "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",