gunshi 0.33.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 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-CUdYQC8F.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
 /**

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-XndHBbIz.d.ts → constants-Dmeogxy-.d.ts}

@@ -1,4 +1,4 @@
-import { m as DefaultGunshiParams, n as CliOptions } from "./types-CUdYQC8F.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-CUdYQC8F.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
 

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 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-CUdYQC8F.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

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-CUdYQC8F.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 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-CUdYQC8F.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-XndHBbIz.js";
+import { t as ANONYMOUS_COMMAND_NAME } from "./constants-Dmeogxy-.js";
 
 //#region ../plugin-i18n/src/types.d.ts
 /**

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 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-CUdYQC8F.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-XndHBbIz.js";
+import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-Dmeogxy-.js";
 
 //#region src/plugin.d.ts
 /**

package/lib/renderer.d.ts

@@ -1,4 +1,4 @@
-import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-CUdYQC8F.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-CUdYQC8F.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
 /**

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-CUdYQC8F.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.33.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/plugin-global": "0.33.0",
-    "@gunshi/plugin-renderer": "0.33.0",
-    "@gunshi/shared": "0.33.0",
-    "@gunshi/resources": "0.33.0",
-    "@gunshi/plugin-i18n": "0.33.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",