@gunshi/plugin 0.32.0 → 0.34.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/parser-D95CJBHr.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -55,7 +55,7 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -172,7 +172,10 @@ interface ArgSchema {
    * When `true`, the argument must be provided by the user.
    * If missing, an `ArgResolveError` with type 'required' will be thrown.
    *
-   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   * For single-value positional arguments, omitting `required` keeps the argument
+   * required for compatibility. Set `required: false` to make a positional argument
+   * optional. Optional positional arguments leave enough input values for later
+   * required positional arguments before consuming a value.
    *
    * @example
    * Required arguments:
@@ -196,7 +199,8 @@ interface ArgSchema {
    *
    * When `true`, the resolved value becomes an array.
    * For options: can be specified multiple times (--tag foo --tag bar)
-   * For positional: collects remaining positional arguments
+   * For positional: collects remaining positional arguments after preserving values for
+   * later required positional arguments.
    *
    * Note: Only `true` is allowed (not `false`) to make intent explicit.
    *
@@ -276,7 +280,11 @@ interface ArgSchema {
    * - `boolean` type: boolean default
    * - `number` type: number default
    * - `enum` type: must be one of the `choices` values
-   * - `positional`/`custom` type: any appropriate default
+   * - `positional`/`custom` type: string, boolean, or number default
+   *
+   * For single-value positional arguments, the default is used when the positional
+   * value is missing or when the value is preserved for later required positional
+   * arguments, unless `required: true` is set.
    *
    * @example
    * Default values by type:
@@ -533,7 +541,8 @@ type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends ke
  *
  * @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] };
+type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as IsRequiredPositionalArg<A[Arg]> extends true ? Arg : never]: V[Arg] };
+type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : A['required'] extends false ? A['default'] extends {} ? true : false : true : false;
 /**
  * An arguments for {@link resolveArgs | resolve arguments}.
  */
@@ -581,15 +590,6 @@ type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
  */
 //#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.
  *
@@ -638,7 +638,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @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;
+  decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the usage renderer.
    *
@@ -646,7 +646,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @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;
+  decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the validation errors renderer.
    *
@@ -654,7 +654,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @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;
+  decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>): void;
   /**
    * Decorate the command execution.
    *
@@ -664,7 +664,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @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;
+  decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
@@ -730,6 +730,36 @@ type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = Defau
 type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
 type IsStringLiteral<S extends string> = string extends S ? false : true;
 type MergeExtension<Id, ResolvedDepExt extends ExtendContext, PluginExt extends ExtendContext> = Id extends infer I ? I extends string ? IsStringLiteral<I> extends true ? ResolvedDepExt & { [K in I]: PluginExt } : ResolvedDepExt : ResolvedDepExt : ResolvedDepExt;
+/**
+ * Extensions resolved from the declared plugin dependencies.
+ *
+ * @internal
+ */
+type DependencyExtensions<Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext> = InferDependencyExtensions<Deps, Context>;
+/**
+ * Gunshi params available while a plugin extension resolves its dependencies.
+ *
+ * @internal
+ */
+type DependencyParams<Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext> = GunshiParams<{
+  args: Args;
+  extensions: DependencyExtensions<Deps, Context>;
+}>;
+/**
+ * Extensions available after applying the current plugin extension.
+ *
+ * @internal
+ */
+type MergedPluginExtensions<Id extends string, Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext, Ext extends ExtendContext> = MergeExtension<Id, DependencyExtensions<Deps, Context>, Ext>;
+/**
+ * Gunshi params available after applying the current plugin extension.
+ *
+ * @internal
+ */
+type MergedPluginParams<Id extends string, Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext, Ext extends ExtendContext> = GunshiParams<{
+  args: Args;
+  extensions: MergedPluginExtensions<Id, Deps, Context, Ext>;
+}>;
 /**
  * Plugin definition options
  *
@@ -743,13 +773,7 @@ Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | stri
 // for plugin dependencies
 Ext extends Record<string, unknown> = {},
 // for plugin extension type
-ResolvedDepExt extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, DepExt>;
-}>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, DepExt>, Awaited<ReturnType<PluginExt>>>;
-}>> {
+ResolvedDepExt extends GunshiParams = DependencyParams<Deps, DepExt>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = MergedPluginParams<Id, Deps, DepExt, Awaited<ReturnType<PluginExt>>>> {
   /**
    * Plugin unique identifier
    */
@@ -858,20 +882,11 @@ Deps extends ReadonlyArray<PluginDependency | string> = [],
 // for plugin dependencies
 Extension extends {} = {},
 // for plugin extension type
-ResolvedDepExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, Context>;
-}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-}>>(options: {
+ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
-  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
-    args: Args;
-    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-  }>>>) => Awaitable<void>;
+  setup?: (ctx: Readonly<PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>>) => Awaitable<void>;
   extension: PluginExt;
   onExtension?: OnPluginExtension<MergedExtensions>;
 }): PluginWithExtension<Awaited<ReturnType<PluginExt>>>;
@@ -896,20 +911,11 @@ Deps extends ReadonlyArray<PluginDependency | string> = [],
 // for plugin dependencies
 Extension extends Record<string, unknown> = {},
 // for plugin extension type
-ResolvedDepExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, Context>;
-}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-}>>(options: {
+ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
-  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
-    args: Args;
-    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-  }>>>) => Awaitable<void>;
+  setup?: (ctx: Readonly<PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>>) => Awaitable<void>;
   onExtension?: OnPluginExtension<MergedExtensions>;
 }): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
 //#endregion
@@ -1011,11 +1017,37 @@ type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G ex
  * @internal
  */
 type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
-  extensions: ExtendContext;
+  args: infer A extends Args;
+  extensions: infer E extends ExtendContext;
+} ? GunshiParams<{
+  args: A;
+  extensions: E;
+}> : G extends {
+  args: infer A extends Args;
+} ? GunshiParams<{
+  args: A;
+  extensions: {};
+}> : G extends {
+  extensions: infer E extends ExtendContext;
 } ? GunshiParams<{
   args: Args;
-  extensions: G['extensions'];
+  extensions: E;
 }> : DefaultGunshiParams;
+/**
+ * Type helper to merge command context extensions into G
+ *
+ * @internal
+ */
+type MergeGunshiExtensions<G extends GunshiParamsConstraint, E extends ExtendContext> = GunshiParams<{
+  /**
+   * Command argument definitions.
+   */
+  args: ExtractArgs<G>;
+  /**
+   * Merged command context extensions.
+   */
+  extensions: ExtractExtensions<G> & E;
+}>;
 /**
  * Command environment.
  *
@@ -1329,7 +1361,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   validationError?: AggregateError;
 }
 /**
- * CommandContextCore type (base type without extensions)
+ * Readonly command context available to a command context extension factory.
  *
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  *
@@ -1605,7 +1637,16 @@ declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
  *
  * @internal
  */
-type ExtractExtensions$1<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+type ExtractExtensionValues<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+/**
+ * Return type of {@link createCommandContext}
+ *
+ * @internal
+ */
+type CommandContextResult<G extends GunshiParamsConstraint, E extends Record<string, CommandContextExtension>> = {} extends ExtractExtensionValues<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
+  args: ExtractArgs<G>;
+  extensions: ExtractExtensionValues<E>;
+}>>>;
 /**
  * Parameters of {@link createCommandContext}
  */
@@ -1692,10 +1733,7 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   commandPath,
   omitted,
   validationError
-}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions$1<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions$1<E>;
-}>>>>;
+}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -1704,4 +1742,4 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,7 +56,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "gunshi": "0.32.0"
+    "gunshi": "0.34.0"
   },
   "scripts": {
     "build": "tsdown",