@gunshi/plugin 0.26.3

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# `@gunshi/plugin`
+
+> utilities for gunshi plugin
+
+This package provides APIs and type definitions for making plugins for gunshi.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> **The APIs and type definitions available in this package are the same as those in the `gunshi/plugin` entry in the `gunshi` package.**
+> This package is smaller in file size than the `gunshi` package, making it suitable for use when you want to reduce the size of the 'node_modules' in the plugin package you are creating.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @gunshi/plugin
+
+## pnpm
+pnpm add @gunshi/plugin
+
+## yarn
+yarn add @gunshi/plugin
+
+## deno
+deno add jsr:@gunshi/plugin
+
+## bun
+bun add @gunshi/plugin
+```
+
+## 🚀 Usage
+
+```js
+// TODO(kazupon): prepare the example
+```
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)

package/lib/index.d.ts

@@ -0,0 +1,667 @@
+//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/parser-FiQIAw-2.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.
+*/
+interface ArgToken {
+  /**
+  * Argument token kind.
+  */
+  kind: ArgTokenKind;
+  /**
+  * 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`.
+  */
+  name?: string;
+  /**
+  * 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.
+  */
+  value?: string;
+  /**
+  * 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.
+*/
+//#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
+*/
+interface ArgSchema {
+  /**
+  * Type of argument.
+  */
+  type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
+  /**
+  * A single character alias for the argument.
+  */
+  short?: string;
+  /**
+  * A description of the argument.
+  */
+  description?: string;
+  /**
+  * Whether the argument is required or not.
+  */
+  required?: true;
+  /**
+  * Whether the argument allow multiple values or not.
+  */
+  multiple?: true;
+  /**
+  * 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'.
+  */
+  choices?: string[] | readonly string[];
+  /**
+  * The default value of the argument.
+  * if the type is 'enum', the default value must be one of the allowed values.
+  */
+  default?: string | boolean | number;
+  /**
+  * 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
+  parse?: (value: string) => any;
+}
+/**
+* An object that contains {@link ArgSchema | argument schema}.
+*/
+interface Args {
+  [option: string]: ArgSchema;
+}
+/**
+* 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 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 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] };
+
+//#endregion
+//#region ../gunshi/src/types.d.ts
+/**
+* An arguments for {@link resolveArgs | resolve arguments}.
+*/
+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}.
+ */
+type ExtendContext = Record<string, unknown>;
+/**
+ * Gunshi unified parameter type.
+ * This type combines both argument definitions and command context extensions.
+ */
+interface GunshiParams<P extends {
+  args?: Args;
+  extensions?: ExtendContext;
+} = {
+  args: Args;
+  extensions: {};
+}> {
+  /**
+   * Command argument definitions
+   */
+  args: P extends {
+    args: infer A extends Args;
+  } ? A : Args;
+  /**
+   * Command context extensions
+   */
+  extensions: P extends {
+    extensions: infer E extends ExtendContext;
+  } ? E : {};
+}
+/**
+ * Default Gunshi parameters
+ */
+type DefaultGunshiParams = GunshiParams;
+/**
+ * Generic constraint for command-related types.
+ * This type constraint allows both GunshiParams and objects with extensions.
+ */
+type GunshiParamsConstraint = GunshiParams<any> | {
+  extensions: ExtendContext;
+};
+/**
+ * Type helper to extract args from G
+ * @internal
+ */
+type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
+/**
+ * Type helper to extract extensions from G
+ * @internal
+ */
+type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
+  extensions: infer E;
+} ? E : {};
+/**
+ * Type helper to normalize G to GunshiParams
+ * @internal
+ */
+type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
+  extensions: ExtendContext;
+} ? GunshiParams<{
+  args: Args;
+  extensions: G['extensions'];
+}> : DefaultGunshiParams;
+/**
+ * Command environment.
+ */
+interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Current working directory.
+   * @see {@link CliOptions.cwd}
+   */
+  cwd: string | undefined;
+  /**
+   * Command name.
+   * @see {@link CliOptions.name}
+   */
+  name: string | undefined;
+  /**
+   * Command description.
+   * @see {@link CliOptions.description}
+   *
+   */
+  description: string | undefined;
+  /**
+   * Command version.
+   * @see {@link CliOptions.version}
+   */
+  version: string | undefined;
+  /**
+   * Left margin of the command output.
+   * @default 2
+   * @see {@link CliOptions.leftMargin}
+   */
+  leftMargin: number;
+  /**
+   * Middle margin of the command output.
+   * @default 10
+   * @see {@link CliOptions.middleMargin}
+   */
+  middleMargin: number;
+  /**
+   * Whether to display the usage option type.
+   * @default false
+   * @see {@link CliOptions.usageOptionType}
+   */
+  usageOptionType: boolean;
+  /**
+   * Whether to display the option value.
+   * @default true
+   * @see {@link CliOptions.usageOptionValue}
+   */
+  usageOptionValue: boolean;
+  /**
+   * Whether to display the command usage.
+   * @default false
+   * @see {@link CliOptions.usageSilent}
+   */
+  usageSilent: boolean;
+  /**
+   * Sub commands.
+   * @see {@link CliOptions.subCommands}
+   */
+  subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
+  /**
+   * Render function the command usage.
+   */
+  renderUsage: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | undefined;
+  /**
+   * Render function the header section in the command usage.
+   */
+  renderHeader: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | undefined;
+  /**
+   * Render function the validation errors.
+   */
+  renderValidationErrors: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null | undefined;
+  /**
+   * Hook that runs before any command execution
+   * @see {@link CliOptions.onBeforeCommand}
+   */
+  onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
+  /**
+   * Hook that runs after successful command execution
+   * @see {@link CliOptions.onAfterCommand}
+   */
+  onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | void) => Awaitable<void>) | undefined;
+  /**
+   * Hook that runs when a command throws an error
+   * @see {@link CliOptions.onErrorCommand}
+   */
+  onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
+}
+/**
+ * CLI options of `cli` function.
+ */
+
+/**
+ * Command call mode.
+ */
+type CommandCallMode = 'entry' | 'subCommand' | 'unexpected';
+/**
+ * Command context.
+ * Command context is the context of the command execution.
+ */
+interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Command name, that is the command that is executed.
+   * The command name is same {@link CommandEnvironment.name}.
+   */
+  name: string | undefined;
+  /**
+   * Command description, that is the description of the command that is executed.
+   * The command description is same {@link CommandEnvironment.description}.
+   */
+  description: string | undefined;
+  /**
+   * Command environment, that is the environment of the command that is executed.
+   * The command environment is same {@link CommandEnvironment}.
+   */
+  env: Readonly<CommandEnvironment<G>>;
+  /**
+   * Command arguments, that is the arguments of the command that is executed.
+   * The command arguments is same {@link Command.args}.
+   */
+  args: ExtractArgs<G>;
+  /**
+   * Command values, that is the values of the command that is executed.
+   * Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
+   */
+  values: ArgValues<ExtractArgs<G>>;
+  /**
+   * Command positionals arguments, that is the positionals of the command that is executed.
+   * Resolve positionals with `resolveArgs` from command arguments.
+   */
+  positionals: string[];
+  /**
+   * Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`.
+   */
+  rest: string[];
+  /**
+   * Original command line arguments.
+   * This argument is passed from `cli` function.
+   */
+  _: string[];
+  /**
+   * Argument tokens, that is parsed by `parseArgs` function.
+   */
+  tokens: ArgToken[];
+  /**
+   * Whether the currently executing command has been executed with the sub-command name omitted.
+   */
+  omitted: boolean;
+  /**
+   * Command call mode.
+   * The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command.
+   */
+  callMode: CommandCallMode;
+  /**
+   * Whether to convert the camel-case style argument name to kebab-case.
+   * This context value is set from {@link Command.toKebab} option.
+   */
+  toKebab?: boolean;
+  /**
+   * Output a message.
+   * If {@link CommandEnvironment.usageSilent} is true, the message is not output.
+   * @param message an output message, @see {@link console.log}
+   * @param optionalParams an optional parameters, @see {@link console.log}
+   * @internal
+   */
+  log: (message?: any, ...optionalParams: any[]) => void;
+  /**
+   *  Command context extensions.
+   */
+  extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
+  /**
+   * Validation error from argument parsing.
+   * This will be set if argument validation fails during CLI execution.
+   */
+  validationError?: AggregateError;
+}
+/**
+ * CommandContextCore type (base type without extensions)
+ */
+type CommandContextCore<G extends GunshiParamsConstraint = DefaultGunshiParams> = Readonly<CommandContext<G>>;
+/**
+ * Command context extension
+ */
+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>;
+}
+/**
+ * Command interface.
+ */
+interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Command name.
+   * It's used to find command line arguments to execute from sub commands, and it's recommended to specify.
+   */
+  name?: string;
+  /**
+   * Command description.
+   * It's used to describe the command in usage and it's recommended to specify.
+   */
+  description?: string;
+  /**
+   * Command arguments.
+   * Each argument can include a description property to describe the argument in usage.
+   */
+  args?: ExtractArgs<G>;
+  /**
+   * Command examples.
+   * examples of how to use the command.
+   */
+  examples?: string | CommandExamplesFetcher<G>;
+  /**
+   * Command runner. it's the command to be executed
+   */
+  run?: CommandRunner<G>;
+  /**
+   * Whether to convert the camel-case style argument name to kebab-case.
+   * If you will set to `true`, All {@link Command.args} names will be converted to kebab-case.
+   */
+  toKebab?: boolean;
+}
+/**
+ * Lazy command interface.
+ * Lazy command that's not loaded until it is executed.
+ */
+type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
+  /**
+   * Command load function
+   */
+  (): Awaitable<Command<G> | CommandRunner<G>>;
+  /**
+   * Command name
+   */
+  commandName?: string;
+} & Omit<Command<G>, 'run' | 'name'>;
+/**
+ * Define a command type.
+ */
+
+/**
+ * Command examples fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched command examples.
+ */
+type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
+/**
+ * Command runner.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns void or string (for CLI output)
+ */
+type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<void | string>;
+/**
+ * Command loader.
+ * A function that returns a command or command runner.
+ * This is used to lazily load commands.
+ * @returns A command or command runner
+ */
+
+/**
+ * Command decorator.
+ * A function that wraps a command runner to add or modify its behavior.
+ * @param baseRunner The base command runner to decorate
+ * @returns The decorated command runner
+ */
+type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<void | string>;
+/**
+ * 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
+ */
+type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>) => Promise<T>, ctx: Readonly<CommandContext<G>>) => Promise<T>;
+/**
+ * Validation errors renderer decorator type.
+ * A function that wraps a validation errors renderer to add or modify its behavior.
+ * @param baseRenderer The base validation errors renderer function to decorate
+ * @param ctx The command context
+ * @param error The aggregate error containing validation errors
+ * @returns The decorated result
+ */
+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 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<G> & L;
+};
+/**
+ * Gunshi plugin context interface.
+ */
+interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Get the global options
+   * @returns A map of global options.
+   */
+  readonly globalOptions: Map<string, ArgSchema>;
+  /**
+   * Add a global option.
+   * @param name An option name
+   * @param schema An {@link ArgSchema} for the option
+   */
+  addGlobalOption(name: string, schema: ArgSchema): void;
+  /**
+   * 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;
+}
+
+//#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 {
+  /**
+   * 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
+ */
+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> {
+  /**
+   * 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>;
+}
+/**
+ * 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)[];
+}
+/**
+ * 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']>;
+
+//#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 };

package/lib/index.js

@@ -0,0 +1,45 @@
+//#region ../gunshi/src/plugin/core.ts
+/**
+* Define a plugin
+* @param options - {@link PluginOptions | plugin options}
+* @returns A defined plugin.
+*/
+function plugin(options) {
+	const { id, name, setup, extension, onExtension, dependencies } = options;
+	const pluginFn = async (ctx) => {
+		if (setup) await setup(ctx);
+	};
+	return Object.defineProperties(pluginFn, {
+		id: {
+			value: id,
+			writable: false,
+			enumerable: true,
+			configurable: true
+		},
+		...name && { name: {
+			value: name,
+			writable: false,
+			enumerable: true,
+			configurable: true
+		} },
+		...dependencies && { dependencies: {
+			value: dependencies,
+			writable: false,
+			enumerable: true,
+			configurable: true
+		} },
+		...extension && { extension: {
+			value: {
+				key: Symbol(id),
+				factory: extension,
+				onFactory: onExtension
+			},
+			writable: false,
+			enumerable: true,
+			configurable: true
+		} }
+	});
+}
+
+//#endregion
+export { plugin };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@gunshi/plugin",
+  "description": "utilities for gunshi plugin",
+  "version": "0.26.3",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/plugin"
+  },
+  "keywords": [
+    "gunshi",
+    "plugin",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "devDependencies": {
+    "deno": "^2.3.3",
+    "jsr": "^0.13.4",
+    "jsr-exports-lint": "^0.4.1",
+    "publint": "^0.3.12",
+    "tsdown": "^0.12.3",
+    "gunshi": "0.26.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+  }
+}