gunshi 0.32.0 → 0.34.0

package/lib/bone.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues } from "./resolver-CIPNDx1a.js";
-import { C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, S as NormalizeToGunshiParams, T as RenderingOptions, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues } from "./resolver-eOZBRWlR.js";
+import { C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, O as ValidationErrorsDecorator, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-DZ8CuO6z.js";
 
 //#region src/cli/bone.d.ts
 /**
@@ -54,4 +54,4 @@ declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[
 */
 
 //#endregion
-export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli };
+export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli };

package/lib/bone.js

@@ -1,4 +1,4 @@
-import { t as cliCore } from "./core-BKtZQ6dG.js";
+import { t as cliCore } from "./core-C83Uo6wC.js";
 //#region src/cli/bone.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{cli-DfaFk6tk.js → cli-CS4q7S8l.js}

@@ -1,6 +1,6 @@
 import { t as plugin } from "./core-D1daCTTE.js";
-import { a as namespacedId, o as COMMON_ARGS, t as renderer } from "./src-dTYUlEw_.js";
-import { t as cliCore } from "./core-BKtZQ6dG.js";
+import { a as namespacedId, o as COMMON_ARGS, t as renderer } from "./src-Cs21MA7o.js";
+import { t as cliCore } from "./core-C83Uo6wC.js";
 //#region ../plugin-global/src/types.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/combinators.d.ts

@@ -1,6 +1,6 @@
-import { i as Args, n as ArgSchema } from "./resolver-CIPNDx1a.js";
+import { i as Args, n as ArgSchema } from "./resolver-eOZBRWlR.js";
 
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/combinators.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/combinators.d.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -242,6 +242,7 @@ type ArgSchemaPositionalType = {
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -262,6 +263,7 @@ declare function positional<T>(parser: CombinatorSchema<T>): CombinatorSchema<T>
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -511,10 +513,11 @@ type CombinatorUnrequired = {
 /**
  * Mark a combinator schema as not required.
  *
- * Useful for overriding a base combinator that was created with `required: true`.
+ * Useful for overriding a base combinator that was created with `required: true`,
+ * or for making a positional argument explicitly optional.
  * The original schema is not modified.
  *
- * @typeParam T - The schema's parsed type.
+ * @typeParam T - The schema type.
  *
  * @param schema - The base combinator schema.
  * @returns A new schema with `required: false`.
@@ -522,13 +525,14 @@ type CombinatorUnrequired = {
  * @example
  * ```ts
  * const args = {
- *   name: unrequired(string({ required: true }))
+ *   name: unrequired(string({ required: true })),
+ *   query: unrequired(positional())
  * }
  * ```
  *
  * @experimental
  */
-declare function unrequired<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorUnrequired;
+declare function unrequired<T extends ArgSchema>(schema: T): Omit<T, 'required'> & CombinatorUnrequired;
 /**
  * Recursively merge a tuple of {@link Args} types.
  * Later types override earlier ones on key conflicts.

package/lib/combinators.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/combinators.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/combinators.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -179,7 +179,8 @@ function positional(parser) {
 		parse: parser.parse,
 		metavar: parser.metavar,
 		...parser.description != null ? { description: parser.description } : {},
-		...parser.required != null ? { required: parser.required } : {}
+		...parser.required != null ? { required: parser.required } : {},
+		...parser.default != null ? { default: parser.default } : {}
 	};
 	const opts = parser;
 	return {
@@ -437,10 +438,11 @@ function describe(schema, text) {
 /**
 * Mark a combinator schema as not required.
 *
-* Useful for overriding a base combinator that was created with `required: true`.
+* Useful for overriding a base combinator that was created with `required: true`,
+* or for making a positional argument explicitly optional.
 * The original schema is not modified.
 *
-* @typeParam T - The schema's parsed type.
+* @typeParam T - The schema type.
 *
 * @param schema - The base combinator schema.
 * @returns A new schema with `required: false`.
@@ -448,7 +450,8 @@ function describe(schema, text) {
 * @example
 * ```ts
 * const args = {
-*   name: unrequired(string({ required: true }))
+*   name: unrequired(string({ required: true })),
+*   query: unrequired(positional())
 * }
 * ```
 *

package/lib/{constants-CPTXtFxe.d.ts → constants-Dmeogxy-.d.ts}

@@ -1,4 +1,4 @@
-import { m as DefaultGunshiParams, n as CliOptions } from "./types-CyyzAaDx.js";
+import { m as DefaultGunshiParams, n as CliOptions } from "./types-DZ8CuO6z.js";
 
 //#region src/constants.d.ts
 /**

package/lib/context.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, o as ArgToken, r as ArgValues } from "./resolver-CIPNDx1a.js";
-import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { i as Args, o as ArgToken, r as ArgValues } from "./resolver-eOZBRWlR.js";
+import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams } from "./types-DZ8CuO6z.js";
 
 //#region src/context.d.ts
 
@@ -8,7 +8,16 @@ import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g a
  *
  * @internal
  */
-type ExtractExtensions<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}
  */
@@ -95,9 +104,6 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   commandPath,
   omitted,
   validationError
-}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions<E>;
-}>>>>;
+}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
-export { CommandContextParams, ExtractExtensions, createCommandContext };
+export { CommandContextParams, ExtractExtensionValues, createCommandContext };

package/lib/context.js

@@ -1,5 +1,5 @@
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-D_ixLD32.js";
-import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-jNy8sqR5.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-9CtzCGbg.js";
 //#region src/context.ts
 /**
 * The entry for gunshi context.

package/lib/{core-BKtZQ6dG.js → core-C83Uo6wC.js}

@@ -1,7 +1,7 @@
 import { n as CLI_OPTIONS_DEFAULT, r as NOOP } from "./constants-D_ixLD32.js";
-import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-jNy8sqR5.js";
+import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-9CtzCGbg.js";
 import { createCommandContext } from "./context.js";
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/parser.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/parser.js
 /**
 * forked from `nodejs/node` (`pkgjs/parseargs`)
 * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
@@ -206,7 +206,7 @@ function hasOptionValue(value) {
 	return !(value == null) && value.codePointAt(0) !== HYPHEN_CODE;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/resolver.js
 /**
 * Entry point of argument options resolver.
 *
@@ -349,6 +349,8 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	const errors = [];
 	const explicit = Object.create(null);
 	const actualInputNames = /* @__PURE__ */ new Map();
+	const argEntries = Object.entries(args);
+	let requiredPositionalsAfter;
 	function checkTokenName(option, schema, token) {
 		return token.name === (schema.type === "boolean" ? schema.negatable && token.name?.startsWith("no-") ? `no-${option}` : option : option);
 	}
@@ -356,14 +358,21 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 	function getPositionalSkipIndex() {
 		return Math.min(skipPositionalIndex, positionalItemCount);
 	}
+	function getRequiredPositionalsAfter(rawArg) {
+		requiredPositionalsAfter ??= createRequiredPositionalsAfter(argEntries);
+		return requiredPositionalsAfter[rawArg] ?? 0;
+	}
 	let positionalsCount = 0;
-	for (const [rawArg, schema] of Object.entries(args)) {
+	for (const [rawArg, schema] of argEntries) {
 		const arg = toKebab || schema.toKebab ? kebabnize(rawArg) : rawArg;
 		explicit[rawArg] = false;
 		if (schema.type === "positional") {
 			if (skipPositionalIndex > SKIP_POSITIONAL_DEFAULT) while (positionalsCount <= getPositionalSkipIndex()) positionalsCount++;
+			const requiredPositionals = getRequiredPositionalsAfter(rawArg);
+			const availablePositionals = Math.max(positionalTokens.length - positionalsCount, 0);
 			if (schema.multiple) {
-				const remainingPositionals = positionalTokens.slice(positionalsCount);
+				const positionalsToConsume = Math.max(availablePositionals - requiredPositionals, 0);
+				const remainingPositionals = positionalTokens.slice(positionalsCount, positionalsCount + positionalsToConsume);
 				if (remainingPositionals.length > 0) {
 					if (typeof schema.parse === "function") {
 						const parsed = [];
@@ -379,7 +388,7 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 				} else if (schema.required) errors.push(createRequireError(arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
-				if (positional != null) {
+				if (positional != null && (shouldRequireMissingSinglePositional(schema) || availablePositionals > requiredPositionals)) {
 					if (typeof schema.parse === "function") try {
 						values[rawArg] = schema.parse(positional.value);
 					} catch (error) {
@@ -387,8 +396,9 @@ function resolveArgs(args, tokens, { shortGrouping = false, skipPositional = SKI
 					}
 					else values[rawArg] = positional.value;
 					explicit[rawArg] = true;
-				} else errors.push(createRequireError(arg, schema));
-				positionalsCount++;
+					positionalsCount++;
+				} else if (shouldRequireMissingSinglePositional(schema)) errors.push(createRequireError(arg, schema));
+				else if (hasDefault(schema)) values[rawArg] = schema.default;
 			}
 			continue;
 		}
@@ -457,6 +467,30 @@ function parse(token, option, schema) {
 function createRequireError(option, schema) {
 	return new ArgResolveError(schema.type === "positional" ? `Positional argument '${option}' is required` : `Optional argument '--${option}' ${schema.short ? `or '-${schema.short}' ` : ""}is required`, option, "required", schema);
 }
+function hasDefault(schema) {
+	return schema.default != null;
+}
+function shouldRequireMissingSinglePositional(schema) {
+	if (schema.required === true) return true;
+	if (schema.required === false) return false;
+	return !hasDefault(schema);
+}
+function getRequiredPositionalInputCount(schema) {
+	if (schema.type !== "positional") return 0;
+	if (schema.multiple) return schema.required === true ? 1 : 0;
+	return shouldRequireMissingSinglePositional(schema) ? 1 : 0;
+}
+function createRequiredPositionalsAfter(argEntries) {
+	const requiredPositionalsAfter = Object.create(null);
+	let minimumRequiredPositionals = 0;
+	for (let i = argEntries.length - 1; i >= 0; i--) {
+		const [rawArg, schema] = argEntries[i];
+		if (schema.type !== "positional") continue;
+		requiredPositionalsAfter[rawArg] = minimumRequiredPositionals;
+		minimumRequiredPositionals += getRequiredPositionalInputCount(schema);
+	}
+	return requiredPositionalsAfter;
+}
 /**
 * An error that occurs when resolving arguments.
 * This error is thrown when the argument is not valid.
@@ -506,7 +540,7 @@ function checkConflicts(args, explicit, toKebab, actualInputNames) {
 	return [];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/index.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT

package/lib/definition.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-CIPNDx1a.js";
-import { C as Prettify, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, x as LazyCommand, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-eOZBRWlR.js";
+import { C as NormalizeToGunshiParams, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-DZ8CuO6z.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts
@@ -9,17 +9,23 @@ import { CommandContextParams, createCommandContext } from "./context.js";
 */
 
 /**
- * Infer command properties excluding for {@link define} function
+ * The result type of the {@link define} function
  *
  * @internal
  */
-type InferCommandProps<G extends GunshiParamsConstraint = DefaultGunshiParams> = Pick<Command<G>, Exclude<keyof Command<G>, keyof Command<G>>>;
+type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C = {}> = Prettify<Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<keyof Command<G>, keyof C>>>>;
 /**
- * The result type of the {@link define} function
+ * The command definition accepted by {@link define} helpers.
  *
  * @internal
  */
-type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> = Command<G>> = Prettify<Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<keyof Command<G>, keyof C>>>>;
+type CommandDefinition<A extends Args, E extends ExtendContext, C extends Partial<Command<{
+  args: A;
+  extensions: E;
+}>>> = C & Command<{
+  args: A;
+  extensions: E;
+}>;
 /**
  * Define a {@link Command | command}.
  *
@@ -50,10 +56,10 @@ type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiPar
  * @param definition - A {@link Command | command} definition
  * @returns A defined {@link Command | command}
  */
-declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends Args = ExtractArgs<G>, C extends InferCommandProps<G> = InferCommandProps<G>>(definition: C & Command<{
+declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends Args = ExtractArgs<G>, C extends Partial<Command<{
   args: A;
   extensions: ExtractExtensions<G>;
-}>): CommandDefinitionResult<G, C>;
+}>> = {}>(definition: CommandDefinition<A, ExtractExtensions<G>, C>): CommandDefinitionResult<G, C>;
 /**
  * Return type for defineWithTypes
  *
@@ -64,10 +70,7 @@ declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams,
 type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs extends Args> = <A extends DefaultArgs = DefaultArgs, C extends Partial<Command<{
   args: A;
   extensions: DefaultExtensions;
-}>> = {}>(definition: C & Command<{
-  args: A;
-  extensions: DefaultExtensions;
-}>) => CommandDefinitionResult<{
+}>> = {}>(definition: CommandDefinition<A, DefaultExtensions, C>) => CommandDefinitionResult<{
   args: A;
   extensions: DefaultExtensions;
 }, C>;
@@ -170,30 +173,6 @@ declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, A
   args: A;
   extensions: {};
 }, D>;
-/**
- * Normalize G to a full GunshiParams type
- *
- * @typeParam G - A {@link GunshiParamsConstraint} type
- *
- * @internal
- */
-type NormalizeGunshiParams<G extends GunshiParamsConstraint> = G extends GunshiParams<any> ? G : G extends {
-  args: infer A;
-  extensions: infer E;
-} ? {
-  args: A;
-  extensions: E;
-} : G extends {
-  args: infer A;
-} ? {
-  args: A;
-  extensions: {};
-} : G extends {
-  extensions: infer E;
-} ? {
-  args: Args;
-  extensions: E;
-} : DefaultGunshiParams;
 /**
  * Return type for lazyWithTypes
  *
@@ -236,6 +215,6 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
  *
  * @since v0.27.0
  */
-declare function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<NormalizeGunshiParams<G>>;
+declare function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<NormalizeToGunshiParams<G>>;
 //#endregion
 export { type ArgSchema, type ArgValues, type Args, type Command, type CommandContextParams, type CommandLoader, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type GunshiParams, type LazyCommand, createCommandContext, define, defineWithTypes, lazy, lazyWithTypes };

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-CyyzAaDx.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-DZ8CuO6z.js";
 
 //#region src/generator.d.ts
 

package/lib/generator.js

@@ -1,5 +1,5 @@
-import { t as create } from "./utils-jNy8sqR5.js";
-import { t as cli } from "./cli-DfaFk6tk.js";
+import { t as create } from "./utils-9CtzCGbg.js";
+import { t as cli } from "./cli-CS4q7S8l.js";
 //#region src/generator.ts
 /**
 * The entry for usage generator.

package/lib/index.d.ts

@@ -1,8 +1,8 @@
-import { a as resolveArgs, i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, s as parseArgs } from "./resolver-CIPNDx1a.js";
-import { A as PluginDependency, C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, F as PluginWithoutExtension, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, S as NormalizeToGunshiParams, T as RenderingOptions, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, j as PluginExtension, k as Plugin, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { a as resolveArgs, i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, s as parseArgs } from "./resolver-eOZBRWlR.js";
+import { A as Plugin, C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, j as PluginDependency, k as OnPluginExtension, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-DZ8CuO6z.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
-import { t as ANONYMOUS_COMMAND_NAME } from "./constants-CPTXtFxe.js";
+import { t as ANONYMOUS_COMMAND_NAME } from "./constants-Dmeogxy-.js";
 
 //#region ../plugin-i18n/src/types.d.ts
 /**
@@ -186,4 +186,4 @@ declare function cli(args: string[], entry: SubCommandable, options?: CliOptions
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, type CommandContextParams, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, DefaultTranslation, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli, createCommandContext, define, defineWithTypes, lazy, lazyWithTypes, parseArgs, plugin, resolveArgs };
+export { ANONYMOUS_COMMAND_NAME, ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, type CommandContextParams, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, DefaultTranslation, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, Prettify, RendererDecorator, RenderingOptions, SubCommandable, ValidationErrorsDecorator, cli, createCommandContext, define, defineWithTypes, lazy, lazyWithTypes, parseArgs, plugin, resolveArgs };

package/lib/index.js

@@ -1,9 +1,9 @@
 import { t as ANONYMOUS_COMMAND_NAME } from "./constants-D_ixLD32.js";
 import { createCommandContext } from "./context.js";
 import { t as plugin } from "./core-D1daCTTE.js";
-import { a as namespacedId } from "./src-dTYUlEw_.js";
-import { n as resolveArgs, r as parseArgs } from "./core-BKtZQ6dG.js";
-import { t as cli } from "./cli-DfaFk6tk.js";
+import { a as namespacedId } from "./src-Cs21MA7o.js";
+import { n as resolveArgs, r as parseArgs } from "./core-C83Uo6wC.js";
+import { t as cli } from "./cli-CS4q7S8l.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
 //#region ../plugin-i18n/src/translation.ts
 /**

package/lib/plugin.d.ts

@@ -1,7 +1,7 @@
-import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues } from "./resolver-CIPNDx1a.js";
-import { A as PluginDependency, C as Prettify, D as ValidationErrorsDecorator, F as PluginWithoutExtension, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, S as NormalizeToGunshiParams, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, f as CommandRunner, h as ExtendContext, j as PluginExtension, k as Plugin, m as DefaultGunshiParams, o as CommandContextCore, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as RendererDecorator, x as LazyCommand, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues } from "./resolver-eOZBRWlR.js";
+import { A as Plugin, C as NormalizeToGunshiParams, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, f as CommandRunner, h as ExtendContext, j as PluginDependency, k as OnPluginExtension, m as DefaultGunshiParams, o as CommandContextCore, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-DZ8CuO6z.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
-import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-CPTXtFxe.js";
+import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-Dmeogxy-.js";
 
 //#region src/plugin.d.ts
 /**
@@ -10,4 +10,4 @@ import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constan
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, plugin };

package/lib/renderer.d.ts

@@ -1,4 +1,4 @@
-import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-CyyzAaDx.js";
+import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-DZ8CuO6z.js";
 
 //#region ../plugin-renderer/src/header.d.ts
 /**

package/lib/renderer.js

@@ -1,4 +1,4 @@
-import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-dTYUlEw_.js";
+import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-Cs21MA7o.js";
 //#region src/renderer.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{resolver-CIPNDx1a.d.ts → resolver-eOZBRWlR.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.
@@ -88,7 +88,7 @@ declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
  * @returns Whether `arg` is a short option.
  */
 //#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.
@@ -205,7 +205,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:
@@ -229,7 +232,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.
    *
@@ -309,7 +313,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:
@@ -566,7 +574,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}.
  */

package/lib/{src-dTYUlEw_.js → src-Cs21MA7o.js}

@@ -1,5 +1,5 @@
 import "./constants-D_ixLD32.js";
-import { o as resolveLazyCommand, s as kebabnize } from "./utils-jNy8sqR5.js";
+import { o as resolveLazyCommand, s as kebabnize } from "./utils-9CtzCGbg.js";
 import { t as plugin } from "./core-D1daCTTE.js";
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -494,11 +494,18 @@ async function generatePositionalArgsUsage(ctx) {
 function generatePositionalSymbols(args) {
 	return hasPositionalArgs(args) ? getPositionalArgs(args).map(([name, arg]) => {
 		const elements = [];
-		if (!arg.multiple || arg.required) elements.push(`<${name}>`);
-		if (arg.multiple) elements.push(`[<${name}> ...]`);
+		if (arg.multiple) {
+			if (arg.required) elements.push(`<${name}>`);
+			elements.push(`[<${name}> ...]`);
+		} else elements.push(isRequiredSinglePositionalArg(arg) ? `<${name}>` : `[<${name}>]`);
 		return elements.join(" ");
 	}).join(" ") : "";
 }
+function isRequiredSinglePositionalArg(arg) {
+	if (arg.required === true) return true;
+	if (arg.required === false) return false;
+	return arg.default == null;
+}
 //#endregion
 //#region ../plugin-renderer/src/validation.ts
 /**

package/lib/{types-CyyzAaDx.d.ts → types-DZ8CuO6z.d.ts}

@@ -1,4 +1,4 @@
-import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, t as ArgExplicitlyProvided } from "./resolver-CIPNDx1a.js";
+import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, t as ArgExplicitlyProvided } from "./resolver-eOZBRWlR.js";
 
 //#region src/plugin/context.d.ts
 /**
@@ -6,15 +6,6 @@ import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, t as ArgExpli
 * @license MIT
 */
 
-/**
- * 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.
  *
@@ -63,7 +54,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.
    *
@@ -71,7 +62,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.
    *
@@ -79,7 +70,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.
    *
@@ -89,7 +80,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 src/plugin/core.d.ts
@@ -155,6 +146,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
  *
@@ -168,13 +189,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
    */
@@ -283,20 +298,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>>>;
@@ -321,20 +327,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
@@ -436,11 +433,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.
  *
@@ -754,7 +777,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.
  *
@@ -1037,4 +1060,4 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
  */
 type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
 //#endregion
-export { PluginDependency as A, Prettify as C, ValidationErrorsDecorator as D, SubCommandable as E, PluginWithoutExtension as F, plugin as I, PluginContext as L, PluginFunction as M, PluginOptions as N, OnPluginExtension as O, PluginWithExtension as P, NormalizeToGunshiParams as S, RenderingOptions as T, ExtractArgs as _, CommandContext as a, GunshiParamsConstraint as b, CommandDecorator as c, CommandLoader as d, CommandRunner as f, ExtractArgExplicitlyProvided as g, ExtendContext as h, CommandCallMode as i, PluginExtension as j, Plugin as k, CommandEnvironment as l, DefaultGunshiParams as m, CliOptions as n, CommandContextCore as o, Commandable as p, Command as r, CommandContextExtension as s, Awaitable as t, CommandExamplesFetcher as u, ExtractExtensions as v, RendererDecorator as w, LazyCommand as x, GunshiParams as y };
+export { Plugin as A, NormalizeToGunshiParams as C, SubCommandable as D, RenderingOptions as E, PluginWithExtension as F, PluginWithoutExtension as I, plugin as L, PluginExtension as M, PluginFunction as N, ValidationErrorsDecorator as O, PluginOptions as P, PluginContext as R, MergeGunshiExtensions as S, RendererDecorator as T, ExtractArgs as _, CommandContext as a, GunshiParamsConstraint as b, CommandDecorator as c, CommandLoader as d, CommandRunner as f, ExtractArgExplicitlyProvided as g, ExtendContext as h, CommandCallMode as i, PluginDependency as j, OnPluginExtension as k, CommandEnvironment as l, DefaultGunshiParams as m, CliOptions as n, CommandContextCore as o, Commandable as p, Command as r, CommandContextExtension as s, Awaitable as t, CommandExamplesFetcher as u, ExtractExtensions as v, Prettify as w, LazyCommand as x, GunshiParams as y };

package/lib/{utils-jNy8sqR5.js → utils-9CtzCGbg.js}

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *

package/lib/utils.d.ts

@@ -1,6 +1,6 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-CyyzAaDx.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-DZ8CuO6z.js";
 
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/utils.d.ts
 
 //#region src/utils.d.ts
 /**

package/lib/utils.js

@@ -1,2 +1,2 @@
-import { a as log, i as isLazyCommand, n as deepFreeze, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-jNy8sqR5.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-9CtzCGbg.js";
 export { create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, log, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -108,7 +108,7 @@
     }
   },
   "devDependencies": {
-    "args-tokens": "^0.25.0",
+    "args-tokens": "^0.26.1",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
@@ -116,11 +116,11 @@
     "std-env": "^4.1.0",
     "tsdown": "0.21.0",
     "zod": "^4.4.3",
-    "@gunshi/shared": "0.32.0",
-    "@gunshi/plugin-i18n": "0.32.0",
-    "@gunshi/plugin-global": "0.32.0",
-    "@gunshi/resources": "0.32.0",
-    "@gunshi/plugin-renderer": "0.32.0"
+    "@gunshi/plugin-global": "0.34.0",
+    "@gunshi/plugin-i18n": "0.34.0",
+    "@gunshi/resources": "0.34.0",
+    "@gunshi/shared": "0.34.0",
+    "@gunshi/plugin-renderer": "0.34.0"
   },
   "scripts": {
     "build": "tsdown",