@gunshi/plugin 0.26.3 → 0.27.0-alpha.10

package/lib/index.d.ts

@@ -1,161 +1,395 @@
-//#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/types.d.ts
+//#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;
+};
+/**
+ * Gunshi plugin context interface.
+ * @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
+   */
+  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.
+   */
+  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.
+   * @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.
+   * @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).
+   * @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
+/**
+ * Plugin dependency definition
+ * @since v0.27.0
+ */
+interface PluginDependency {
+  /**
+   * Dependency plugin id
+   */
+  id: string;
+  /**
+   * Optional dependency flag.
+   * If true, the plugin will not throw an error if the dependency is not found.
+   */
+  optional?: boolean;
+}
+/**
+ * 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
+ */
+type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = DefaultGunshiParams> = (ctx: CommandContextCore<G>, cmd: Command<G>) => Awaitable<T>;
+/**
+ * Plugin extension callback type
+ * @since v0.27.0
+ */
+type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
+/**
+ * Plugin definition options
+ * @since v0.27.0
+ */
+interface PluginOptions<T extends Record<string, unknown> = Record<never, never>, G extends GunshiParams = DefaultGunshiParams> {
+  /**
+   * Plugin unique identifier
+   */
+  id: string;
+  /**
+   * Plugin name
+   */
+  name?: string;
+  /**
+   * Plugin dependencies
+   */
+  dependencies?: (PluginDependency | string)[];
+  /**
+   * Plugin setup function
+   */
+  setup?: PluginFunction<G>;
+  /**
+   * Plugin extension
+   */
+  extension?: PluginExtension<T, G>;
+  /**
+   * Callback for when the plugin is extended with `extension` option.
+   */
+  onExtension?: OnPluginExtension<G>;
+}
 /**
-* An arguments for {@link resolveArgs | resolve arguments}.
-*/
+ * 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;
+  name?: string;
+  dependencies?: (PluginDependency | string)[];
+  extension?: CommandContextExtension<E>;
+};
+/**
+ * Plugin return type with extension
+ * @internal
+ */
+interface PluginWithExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
+  id: string;
+  name: string;
+  dependencies?: (PluginDependency | string)[];
+  extension: CommandContextExtension<E>;
+}
+/**
+ * Plugin return type without extension
+ * @internal
+ */
+interface PluginWithoutExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
+  id: string;
+  name: string;
+  dependencies?: (PluginDependency | string)[];
+}
+/**
+ * Define a plugin with extension capabilities
+ * @param options - {@link PluginOptions | plugin options}
+ * @return A defined plugin with extension capabilities.
+ * @since v0.27.0
+ */
+declare function plugin<I extends string, P extends PluginExtension<any, DefaultGunshiParams>>(options: {
+  id: I;
+  name?: string;
+  dependencies?: (PluginDependency | string)[];
+  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
+    args: Args;
+    extensions: { [K in I]: Awaited<ReturnType<P>> };
+  }>>>) => Awaitable<void>;
+  extension: P;
+  onExtension?: OnPluginExtension<{
+    args: Args;
+    extensions: { [K in I]: Awaited<ReturnType<P>> };
+  }>;
+}): PluginWithExtension<Awaited<ReturnType<P>>>;
+/**
+ * Define a plugin without extension capabilities
+ * @param options - {@link PluginOptions | plugin options} without extension
+ * @returns A defined plugin without extension capabilities.
+ * @since v0.27.0
+ */
+declare function plugin(options: {
+  id: string;
+  name?: string;
+  dependencies?: (PluginDependency | string)[];
+  setup?: (ctx: Readonly<PluginContext<DefaultGunshiParams>>) => Awaitable<void>;
+  onExtension?: OnPluginExtension<DefaultGunshiParams>;
+}): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
+//#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;
@@ -179,11 +413,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;
@@ -193,11 +429,16 @@ 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
  */
-type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
+type ExtractExtensions$1<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
   extensions: infer E;
 } ? E : {};
 /**
@@ -285,23 +526,105 @@ 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;
 }
 /**
  * CLI options of `cli` function.
  */
-
+interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Current working directory.
+   */
+  cwd?: string;
+  /**
+   * Command program name.
+   */
+  name?: string;
+  /**
+   * Command program description.
+   *
+   */
+  description?: string;
+  /**
+   * Command program version.
+   */
+  version?: string;
+  /**
+   * Sub commands.
+   */
+  subCommands?: Map<string, Command<any> | LazyCommand<any>>;
+  /**
+   * Left margin of the command output.
+   */
+  leftMargin?: number;
+  /**
+   * Middle margin of the command output.
+   */
+  middleMargin?: number;
+  /**
+   * Whether to display the usage optional argument type.
+   */
+  usageOptionType?: boolean;
+  /**
+   * Whether to display the optional argument value.
+   */
+  usageOptionValue?: boolean;
+  /**
+   * Whether to display the command usage.
+   */
+  usageSilent?: boolean;
+  /**
+   * Render function the command usage.
+   */
+  renderUsage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Render function the header section in the command usage.
+   */
+  renderHeader?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Render function the validation errors.
+   */
+  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 | 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>;
+}
 /**
  * Command call mode.
  */
@@ -331,6 +654,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}.
@@ -377,9 +709,10 @@ 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>;
+  extensions: keyof ExtractExtensions$1<G> extends never ? undefined : ExtractExtensions$1<G>;
   /**
    * Validation error from argument parsing.
    * This will be set if argument validation fails during CLI execution.
@@ -388,16 +721,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.
  */
@@ -431,6 +793,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.
@@ -461,7 +841,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.
@@ -474,14 +854,16 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
  * 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>;
 /**
@@ -491,177 +873,101 @@ 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/plugin/context.d.ts
+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/constants.d.ts
+declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
+declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
+//#endregion
+//#region ../gunshi/src/context.d.ts
 /**
- * Type helper to create GunshiParams from extracted args and extensions
+ * Extract extension return types from extensions record
  * @internal
  */
-type ExtractedParams<G extends GunshiParamsConstraint, L extends Record<string, unknown> = {}> = {
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions<G> & L;
-};
+type ExtractExtensions<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
 /**
- * Gunshi plugin context interface.
+ * Parameters of {@link createCommandContext}
  */
-interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
-  /**
-   * Get the global options
-   * @returns A map of global options.
-   */
-  readonly globalOptions: Map<string, ArgSchema>;
+interface CommandContextParams<G extends GunshiParams | {
+  extensions: ExtendContext;
+}, V extends ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>> {
   /**
-   * Add a global option.
-   * @param name An option name
-   * @param schema An {@link ArgSchema} for the option
+   * An arguments of target command
    */
-  addGlobalOption(name: string, schema: ArgSchema): void;
+  args: ExtractArgs<G>;
   /**
-   * Decorate the header renderer.
-   * @param decorator - A decorator function that wraps the base header renderer.
+   * Explicitly provided arguments
    */
-  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;
+  explicit: ExtractArgExplicitlyProvided<G>;
   /**
-   * Decorate the usage renderer.
-   * @param decorator - A decorator function that wraps the base usage renderer.
+   * A values of target command
    */
-  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;
+  values: V;
   /**
-   * Decorate the validation errors renderer.
-   * @param decorator - A decorator function that wraps the base validation errors renderer.
+   * A positionals arguments, which passed to the target command
    */
-  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;
+  positionals: string[];
   /**
-   * Decorate the command execution.
-   * Decorators are applied in reverse order (last registered is executed first).
-   * @param decorator - A decorator function that wraps the command runner
+   * A rest arguments, which passed to the target command
    */
-  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.
- * @returns A new {@link PluginContext} instance.
- */
-/**
- * Plugin dependency definition
- */
-interface PluginDependency {
+  rest: string[];
   /**
-   * Dependency plugin id
+   * Original command line arguments
    */
-  id: string;
+  argv: string[];
   /**
-   * Optional dependency flag.
-   * If true, the plugin will not throw an error if the dependency is not found.
+   * Argument tokens that are parsed by the `parseArgs` function
    */
-  optional?: boolean;
-}
-/**
- *  Plugin function type
- */
-type PluginFunction<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<PluginContext<G>>) => Awaitable<void>;
-/**
- * Plugin extension for CommandContext
- */
-type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = DefaultGunshiParams> = (ctx: CommandContextCore<G>, cmd: Command<G>) => T;
-/**
- * Plugin extension callback type
- */
-type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => void;
-/**
- * Plugin definition options
- */
-interface PluginOptions<T extends Record<string, unknown> = Record<never, never>, G extends GunshiParams = DefaultGunshiParams> {
+  tokens: ArgToken[];
   /**
-   * Plugin unique identifier
+   * Whether the command is omitted
    */
-  id: string;
+  omitted: boolean;
   /**
-   * Plugin name
+   * Command call mode.
    */
-  name?: string;
+  callMode: CommandCallMode;
   /**
-   * Plugin dependencies
+   * A target command
    */
-  dependencies?: (PluginDependency | string)[];
+  command: C;
   /**
-   * Plugin setup function
+   * Plugin extensions to apply as the command context extension.
    */
-  setup?: PluginFunction<G>;
+  extensions?: E;
   /**
-   * Plugin extension
+   * A command options, which is spicialized from `cli` function
    */
-  extension?: PluginExtension<T, G>;
+  cliOptions: CliOptions<G>;
   /**
-   * Callback for when the plugin is extended with `extension` option.
+   * Validation error from argument parsing.
    */
-  onExtension?: OnPluginExtension<G>;
-}
-/**
- * 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.
- */
-type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> = PluginFunction & {
-  id: string;
-  name?: string;
-  dependencies?: (PluginDependency | string)[];
-  extension?: CommandContextExtension<E>;
-};
-/**
- * Plugin return type with extension
- * @internal
- */
-interface PluginWithExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
-  id: string;
-  name: string;
-  dependencies?: (PluginDependency | string)[];
-  extension: CommandContextExtension<E>;
-}
-/**
- * Plugin return type without extension
- * @internal
- */
-interface PluginWithoutExtension<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> extends Plugin<E> {
-  id: string;
-  name: string;
-  dependencies?: (PluginDependency | string)[];
+  validationError?: AggregateError;
 }
 /**
- * Define a plugin with extension capabilities
- * @param options - {@link PluginOptions | plugin options}
- * @return A defined plugin with extension capabilities.
- */
-declare function plugin<I extends string, P extends PluginExtension<any, DefaultGunshiParams>>(options: {
-  id: I;
-  name?: string;
-  dependencies?: (PluginDependency | string)[];
-  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
-    args: Args;
-    extensions: { [K in I]: ReturnType<P> };
-  }>>>) => Awaitable<void>;
-  extension: P;
-  onExtension?: OnPluginExtension<{
-    args: Args;
-    extensions: { [K in I]: ReturnType<P> };
-  }>;
-}): PluginWithExtension<ReturnType<P>>;
-/**
- * Define a plugin without extension capabilities
- * @param options - {@link PluginOptions | plugin options} without extension
- * @returns A defined plugin without extension capabilities.
- */
-declare function plugin(options: {
-  id: string;
-  name?: string;
-  dependencies?: (PluginDependency | string)[];
-  setup?: (ctx: Readonly<PluginContext<DefaultGunshiParams>>) => Awaitable<void>;
-}): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
-
+ * 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
+ */
+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,
+  explicit,
+  values,
+  positionals,
+  rest,
+  argv,
+  tokens,
+  command,
+  extensions,
+  cliOptions,
+  callMode,
+  omitted,
+  validationError
+}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
+  args: ExtractArgs<G>;
+  extensions: ExtractExtensions<E>;
+}>>>>;
 //#endregion
-export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, Command, CommandContext, CommandContextCore, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, RendererDecorator, ValidationErrorsDecorator, plugin };
+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 };

package/lib/index.js

@@ -1,11 +1,131 @@
+//#region ../gunshi/src/constants.ts
+const ANONYMOUS_COMMAND_NAME = "(anonymous)";
+const NOOP = () => {};
+const CLI_OPTIONS_DEFAULT = {
+	name: void 0,
+	description: void 0,
+	version: void 0,
+	cwd: void 0,
+	usageSilent: false,
+	subCommands: void 0,
+	leftMargin: 2,
+	middleMargin: 10,
+	usageOptionType: false,
+	usageOptionValue: true,
+	renderHeader: void 0,
+	renderUsage: void 0,
+	renderValidationErrors: void 0,
+	plugins: void 0
+};
+
+//#endregion
+//#region ../gunshi/src/utils.ts
+function isLazyCommand(cmd) {
+	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+}
+function create(obj = null) {
+	return Object.create(obj);
+}
+function log(...args) {
+	console.log(...args);
+}
+function deepFreeze(obj, ignores = []) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (ignores.includes(key)) continue;
+		if (typeof value === "object" && value !== null) deepFreeze(value, ignores);
+	}
+	return Object.freeze(obj);
+}
+
+//#endregion
+//#region ../gunshi/src/context.ts
+/**
+* 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
+*/
+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
+	*/
+	const _args = Object.entries(args).reduce((acc, [key, value]) => {
+		acc[key] = Object.assign(create(), value);
+		return acc;
+	}, create());
+	/**
+	* setup the environment
+	*/
+	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
+	*/
+	const core = Object.assign(create(), {
+		name: getCommandName(command),
+		description: command.description,
+		omitted,
+		callMode,
+		env,
+		args: _args,
+		explicit,
+		values,
+		positionals,
+		rest,
+		_: argv,
+		tokens,
+		toKebab: command.toKebab,
+		log: cliOptions.usageSilent ? NOOP : log,
+		validationError
+	});
+	/**
+	* extend the command context with extensions
+	*/
+	if (Object.keys(extensions).length > 0) {
+		const ext = create(null);
+		Object.defineProperty(core, "extensions", {
+			value: ext,
+			writable: false,
+			enumerable: true,
+			configurable: true
+		});
+		for (const [key, extension] of Object.entries(extensions)) {
+			ext[key] = await extension.factory(core, command);
+			if (extension.onFactory) await extension.onFactory(core, command);
+		}
+	}
+	const ctx = deepFreeze(core, ["extensions"]);
+	return ctx;
+}
+function getCommandName(cmd) {
+	if (isLazyCommand(cmd)) return cmd.commandName || cmd.name || ANONYMOUS_COMMAND_NAME;
+	else if (typeof cmd === "object") return cmd.name || ANONYMOUS_COMMAND_NAME;
+	else return ANONYMOUS_COMMAND_NAME;
+}
+
+//#endregion
 //#region ../gunshi/src/plugin/core.ts
+const NOOP_EXTENSION = () => {
+	return Object.create(null);
+};
 /**
 * Define a plugin
 * @param options - {@link PluginOptions | plugin options}
 * @returns A defined plugin.
+* @since v0.27.0
 */
 function plugin(options) {
-	const { id, name, setup, extension, onExtension, dependencies } = options;
+	const { id, name, setup, onExtension, dependencies } = options;
+	const extension = options.extension || NOOP_EXTENSION;
 	const pluginFn = async (ctx) => {
 		if (setup) await setup(ctx);
 	};
@@ -42,4 +162,4 @@ function plugin(options) {
 }
 
 //#endregion
-export { plugin };
+export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT, createCommandContext, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "utilities for gunshi plugin",
-  "version": "0.26.3",
+  "version": "0.27.0-alpha.10",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,12 +51,12 @@
     }
   },
   "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": "0.26.3"
+    "tsdown": "^0.13.0",
+    "gunshi": "0.27.0-alpha.10"
   },
   "scripts": {
     "build": "tsdown",