gunshi 0.33.0 → 0.35.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-mxPNDBm_.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-DZ0S_FSe.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-xgWIcbHL.js";
 //#region src/cli/bone.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{cli-DfaFk6tk.js → cli-DoX4INTi.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 { t as plugin } from "./core-CFEvRYOJ.js";
+import { a as namespacedId, o as COMMON_ARGS, t as renderer } from "./src-B4uHG_qb.js";
+import { t as cliCore } from "./core-xgWIcbHL.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-mxPNDBm_.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.27.0/node_modules/args-tokens/lib/combinators.d.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -46,6 +46,10 @@ interface BaseOptions {
    * Human-readable description for help text generation.
    */
   description?: string;
+  /**
+   * Hide from generated help or usage output.
+   */
+  hidden?: boolean;
   /**
    * Single character short alias.
    */
@@ -242,6 +246,7 @@ type ArgSchemaPositionalType = {
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -262,6 +267,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
  * }
  * ```
  *
@@ -502,6 +508,33 @@ type CombinatorDescribe<D extends string> = {
  * @experimental
  */
 declare function describe<T, D extends string>(schema: CombinatorSchema<T>, text: D): CombinatorSchema<T> & CombinatorDescribe<D>;
+/**
+ * Options for the {@link hidden} combinator.
+ */
+type CombinatorHidden = {
+  hidden: true;
+};
+/**
+ * Hide a combinator schema from generated help or usage output.
+ *
+ * The original schema is not modified. This only marks renderer metadata and
+ * does not change parsing, validation, defaults, conflicts, or resolved values.
+ *
+ * @typeParam T - The schema type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `hidden: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   legacy: hidden(string())
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function hidden<T extends ArgSchema>(schema: T): Omit<T, 'hidden'> & CombinatorHidden;
 /**
  * Options for the {@link unrequired} combinator.
  */
@@ -511,10 +544,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 +556,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.
@@ -643,4 +678,4 @@ declare function extend<T extends Args, U extends Args>(base: T, overrides: U):
 */
 
 //#endregion
-export { type BaseOptions, type BooleanOptions, type Combinator, type CombinatorOptions, type CombinatorSchema, type FloatOptions, type IntegerOptions, type NumberOptions, type StringOptions, args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };
+export { type BaseOptions, type BooleanOptions, type Combinator, type CombinatorOptions, type CombinatorSchema, type FloatOptions, type IntegerOptions, type NumberOptions, type StringOptions, args, boolean, choice, combinator, describe, extend, float, hidden, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

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.27.0/node_modules/args-tokens/lib/combinators.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -18,12 +18,13 @@
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function string(opts) {
 	return {
 		type: "string",
 		metavar: "string",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -51,12 +52,13 @@ function string(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function number(opts) {
 	return {
 		type: "number",
 		metavar: "number",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -85,12 +87,13 @@ function number(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function integer(opts) {
 	return {
 		type: "custom",
 		metavar: "integer",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -120,12 +123,13 @@ function integer(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function float(opts) {
 	return {
 		type: "custom",
 		metavar: "float",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -158,13 +162,14 @@ function float(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function boolean(opts) {
 	return {
 		type: "boolean",
 		...opts?.negatable != null ? { negatable: opts.negatable } : {},
 		metavar: "boolean",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -172,19 +177,22 @@ function boolean(opts) {
 		}
 	};
 }
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function positional(parser) {
 	if (parser && "parse" in parser) return {
 		type: "positional",
 		parse: parser.parse,
 		metavar: parser.metavar,
 		...parser.description != null ? { description: parser.description } : {},
-		...parser.required != null ? { required: parser.required } : {}
+		...parser.hidden != null ? { hidden: parser.hidden } : {},
+		...parser.required != null ? { required: parser.required } : {},
+		...parser.default != null ? { default: parser.default } : {}
 	};
 	const opts = parser;
 	return {
 		type: "positional",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {}
 	};
@@ -210,13 +218,14 @@ function positional(parser) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function choice(values, opts) {
 	return {
 		type: "enum",
 		metavar: values.join("|"),
 		choices: values,
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -255,12 +264,13 @@ function choice(values, opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function combinator(config) {
 	return {
 		type: "custom",
 		metavar: config.metavar ?? "custom",
 		...config.description != null ? { description: config.description } : {},
+		...config.hidden != null ? { hidden: config.hidden } : {},
 		...config.short != null ? { short: config.short } : {},
 		...config.required != null ? { required: config.required } : {},
 		parse: config.parse
@@ -288,7 +298,7 @@ function combinator(config) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function map(schema, transform) {
 	const baseParse = schema.parse;
 	return {
@@ -318,7 +328,7 @@ function map(schema, transform) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function withDefault(schema, defaultValue) {
 	return {
 		...schema,
@@ -344,7 +354,7 @@ function withDefault(schema, defaultValue) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function multiple(schema) {
 	return {
 		...schema,
@@ -370,7 +380,7 @@ function multiple(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function required(schema) {
 	return {
 		...schema,
@@ -399,7 +409,7 @@ function required(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function short(schema, alias) {
 	return {
 		...schema,
@@ -427,7 +437,7 @@ function short(schema, alias) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function describe(schema, text) {
 	return {
 		...schema,
@@ -435,12 +445,40 @@ function describe(schema, text) {
 	};
 }
 /**
+* Hide a combinator schema from generated help or usage output.
+*
+* The original schema is not modified. This only marks renderer metadata and
+* does not change parsing, validation, defaults, conflicts, or resolved values.
+*
+* @typeParam T - The schema type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `hidden: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   legacy: hidden(string())
+* }
+* ```
+*
+* @experimental
+*/
+// @__NO_SIDE_EFFECTS__
+function hidden(schema) {
+	return {
+		...schema,
+		hidden: true
+	};
+}
+/**
 * 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,13 +486,14 @@ function describe(schema, text) {
 * @example
 * ```ts
 * const args = {
-*   name: unrequired(string({ required: true }))
+*   name: unrequired(string({ required: true })),
+*   query: unrequired(positional())
 * }
 * ```
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function unrequired(schema) {
 	return {
 		...schema,
@@ -482,11 +521,11 @@ function unrequired(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function args(fields) {
 	return fields;
 }
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function merge(...schemas) {
 	const result = Object.create(null);
 	for (const schema of schemas) for (const key of Object.keys(schema)) result[key] = schema[key];
@@ -513,7 +552,7 @@ function merge(...schemas) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function extend(base, overrides) {
 	const result = Object.create(null);
 	for (const key of Object.keys(base)) result[key] = base[key];
@@ -527,4 +566,4 @@ function extend(base, overrides) {
 * @license MIT
 */
 //#endregion
-export { args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };
+export { args, boolean, choice, combinator, describe, extend, float, hidden, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

package/lib/{constants-XndHBbIz.d.ts → constants-BkgP86Yw.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-DZ0S_FSe.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-mxPNDBm_.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-DZ0S_FSe.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 { n as CLI_OPTIONS_DEFAULT, r as NOOP, t as ANONYMOUS_COMMAND_NAME } from "./constants-CQq1R_68.js";
+import { a as log, i as isLazyCommand, n as deepFreeze, t as create } from "./utils-DNVHO9MQ.js";
 //#region src/context.ts
 /**
 * The entry for gunshi context.

package/lib/{core-BKtZQ6dG.js → core-xgWIcbHL.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 { n as CLI_OPTIONS_DEFAULT, r as NOOP } from "./constants-CQq1R_68.js";
+import { i as isLazyCommand, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-DNVHO9MQ.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.27.0/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.27.0/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,39 +358,63 @@ 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++;
 			if (schema.multiple) {
-				const remainingPositionals = positionalTokens.slice(positionalsCount);
-				if (remainingPositionals.length > 0) {
-					if (typeof schema.parse === "function") {
-						const parsed = [];
-						for (const p of remainingPositionals) try {
-							parsed.push(schema.parse(p.value));
-						} catch (error) {
-							errors.push(error);
+				const availablePositionals = Math.max(positionalTokens.length - positionalsCount, 0);
+				if (availablePositionals > 0) {
+					const requiredPositionals = getRequiredPositionalsAfter(rawArg);
+					const positionalsToConsume = Math.max(availablePositionals - requiredPositionals, 0);
+					if (positionalsToConsume > 0) {
+						const endPositionals = positionalsCount + positionalsToConsume;
+						if (typeof schema.parse === "function") {
+							const parsed = [];
+							for (let i = positionalsCount; i < endPositionals; i++) {
+								const p = positionalTokens[i];
+								try {
+									parsed.push(schema.parse(p.value));
+								} catch (error) {
+									errors.push(error);
+								}
+							}
+							values[rawArg] = parsed;
+						} else {
+							const valuesArray = [];
+							for (let i = positionalsCount; i < endPositionals; i++) valuesArray.push(positionalTokens[i].value);
+							values[rawArg] = valuesArray;
 						}
-						values[rawArg] = parsed;
-					} else values[rawArg] = remainingPositionals.map((p) => p.value);
-					positionalsCount += remainingPositionals.length;
-					explicit[rawArg] = true;
+						positionalsCount = endPositionals;
+						explicit[rawArg] = true;
+					} else if (schema.required) errors.push(createRequireError(arg, schema));
 				} else if (schema.required) errors.push(createRequireError(arg, schema));
 			} else {
 				const positional = positionalTokens[positionalsCount];
+				if (shouldRequireMissingSinglePositional(schema)) {
+					if (positional != null) {
+						resolveSinglePositionalValue(values, errors, rawArg, schema, positional);
+						explicit[rawArg] = true;
+						positionalsCount++;
+					} else errors.push(createRequireError(arg, schema));
+					continue;
+				}
 				if (positional != null) {
-					if (typeof schema.parse === "function") try {
-						values[rawArg] = schema.parse(positional.value);
-					} catch (error) {
-						errors.push(error);
+					const requiredPositionals = getRequiredPositionalsAfter(rawArg);
+					if (Math.max(positionalTokens.length - positionalsCount, 0) > requiredPositionals) {
+						resolveSinglePositionalValue(values, errors, rawArg, schema, positional);
+						explicit[rawArg] = true;
+						positionalsCount++;
+						continue;
 					}
-					else values[rawArg] = positional.value;
-					explicit[rawArg] = true;
-				} else errors.push(createRequireError(arg, schema));
-				positionalsCount++;
+				}
+				if (hasDefault(schema)) values[rawArg] = schema.default;
 			}
 			continue;
 		}
@@ -457,6 +483,38 @@ 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 resolveSinglePositionalValue(values, errors, rawArg, schema, positional) {
+	if (typeof schema.parse === "function") try {
+		values[rawArg] = schema.parse(positional.value);
+	} catch (error) {
+		errors.push(error);
+	}
+	else values[rawArg] = positional.value;
+}
+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 +564,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.27.0/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-mxPNDBm_.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-DZ0S_FSe.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts
@@ -77,7 +77,7 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
 /**
  * Define a {@link Command | command} with types
  *
- * This helper function allows specifying the type parameter of {@link GunshiParams}
+ * This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
  * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
  *
  * @example
@@ -97,7 +97,7 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
  * })
  * ```
  *
- * @typeParam G - A {@link GunshiParams} type
+ * @typeParam G - A {@link GunshiParamsConstraint} type
  *
  * @returns A function that takes a command definition via {@link define}
  *
@@ -153,30 +153,39 @@ declare function lazy<A extends Args>(loader: CommandLoader<{
  * }, testDefinition)
  * ```
  *
- * @typeParam A - An {@link Args} type
- * @typeParam D - A partial {@link Command} definition type
+ * @typeParam D - A partial {@link Command} definition type with required `args`
  *
  * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
- * @param definition - An optional {@link Command | command} definition
+ * @param definition - A {@link Command | command} definition
  * @returns A {@link LazyCommand | lazy command} that can be executed later
  */
-declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends ExtractArgs<G> = ExtractArgs<G>, D extends Partial<Command<{
-  args: A;
-  extensions: {};
-}>> = Partial<Command<{
-  args: A;
+declare function lazy<D extends {
+  args: Args;
+} & Partial<Command<{
+  args: D['args'];
   extensions: {};
 }>>>(loader: CommandLoader<{
-  args: A;
+  args: D['args'];
   extensions: {};
 }>, definition: D): LazyCommand<{
-  args: A;
+  args: D['args'];
   extensions: {};
 }, D>;
+/**
+ * Define a {@link LazyCommand | lazy command} with explicit Gunshi parameters and optional definition.
+ *
+ * @typeParam G - A {@link GunshiParamsConstraint}
+ * @typeParam D - A partial {@link Command} definition type
+ *
+ * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
+ * @param definition - An optional {@link Command | command} definition
+ * @returns A {@link LazyCommand | lazy command} that can be executed later
+ */
+declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = Partial<Command<G>>>(loader: CommandLoader<G>, definition?: D): LazyCommand<G, D>;
 /**
  * Return type for lazyWithTypes
  *
- * @typeParam FullG - The normalized {@link GunshiParams} type
+ * @typeParam FullG - The normalized {@link GunshiParamsConstraint} type
  *
  * @internal
  */
@@ -184,7 +193,7 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
 /**
  * Define a {@link LazyCommand | lazy command} with specific type parameters.
  *
- * This helper function allows specifying the type parameter of {@link GunshiParams}
+ * This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
  * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
  *
  * @example
@@ -209,7 +218,7 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
  * )
  * ```
  *
- * @typeParam G - A {@link GunshiParams} type
+ * @typeParam G - A {@link GunshiParamsConstraint} type
  *
  * @returns A function that takes a lazy command definition via {@link lazy}
  *

package/lib/definition.js

@@ -18,7 +18,7 @@ function define(definition) {
 /**
 * Define a {@link Command | command} with types
 *
-* This helper function allows specifying the type parameter of {@link GunshiParams}
+* This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
 * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
 *
 * @example
@@ -38,7 +38,7 @@ function define(definition) {
 * })
 * ```
 *
-* @typeParam G - A {@link GunshiParams} type
+* @typeParam G - A {@link GunshiParamsConstraint} type
 *
 * @returns A function that takes a command definition via {@link define}
 *
@@ -74,7 +74,7 @@ function lazy(loader, definition) {
 /**
 * Define a {@link LazyCommand | lazy command} with specific type parameters.
 *
-* This helper function allows specifying the type parameter of {@link GunshiParams}
+* This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
 * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
 *
 * @example
@@ -99,7 +99,7 @@ function lazy(loader, definition) {
 * )
 * ```
 *
-* @typeParam G - A {@link GunshiParams} type
+* @typeParam G - A {@link GunshiParamsConstraint} type
 *
 * @returns A function that takes a lazy command definition via {@link lazy}
 *

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-DZ0S_FSe.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-DNVHO9MQ.js";
+import { t as cli } from "./cli-DoX4INTi.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-mxPNDBm_.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-DZ0S_FSe.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-BkgP86Yw.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 { t as ANONYMOUS_COMMAND_NAME } from "./constants-CQq1R_68.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 { t as plugin } from "./core-CFEvRYOJ.js";
+import { a as namespacedId } from "./src-B4uHG_qb.js";
+import { n as resolveArgs, r as parseArgs } from "./core-xgWIcbHL.js";
+import { t as cli } from "./cli-DoX4INTi.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-mxPNDBm_.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-DZ0S_FSe.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-BkgP86Yw.js";
 
 //#region src/plugin.d.ts
 /**

package/lib/plugin.js

@@ -1,6 +1,6 @@
-import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-D_ixLD32.js";
+import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-CQq1R_68.js";
 import { createCommandContext } from "./context.js";
-import { t as plugin } from "./core-D1daCTTE.js";
+import { t as plugin } from "./core-CFEvRYOJ.js";
 //#region src/plugin.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

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-DZ0S_FSe.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-B4uHG_qb.js";
 //#region src/renderer.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{resolver-CIPNDx1a.d.ts → resolver-mxPNDBm_.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.27.0/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -88,13 +88,13 @@ 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.27.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
  *
  * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
- * - Additional `required` and `description` properties
+ * - Additional `required`, `description`, and `hidden` properties
  * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
  * - Simplified `default` property (single type, not union types)
  *
@@ -199,13 +199,35 @@ interface ArgSchema {
    * ```
    */
   description?: string;
+  /**
+   * Hide the argument from generated help or usage output.
+   *
+   * This is metadata for renderers. It does not affect parsing, validation,
+   * required checks, defaults, conflicts, or resolved values.
+   *
+   * @example
+   * Hidden compatibility option:
+   * ```ts
+   * {
+   *   legacy: {
+   *     type: 'string',
+   *     hidden: true,
+   *     description: 'Deprecated compatibility option'
+   *   }
+   * }
+   * ```
+   */
+  hidden?: boolean;
   /**
    * Marks the argument as required.
    *
    * 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 +251,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 +332,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 +593,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-B4uHG_qb.js}

@@ -1,6 +1,6 @@
-import "./constants-D_ixLD32.js";
-import { o as resolveLazyCommand, s as kebabnize } from "./utils-jNy8sqR5.js";
-import { t as plugin } from "./core-D1daCTTE.js";
+import "./constants-CQq1R_68.js";
+import { o as resolveLazyCommand, s as kebabnize } from "./utils-DNVHO9MQ.js";
+import { t as plugin } from "./core-CFEvRYOJ.js";
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -202,6 +202,15 @@ const pluginId = namespacedId("renderer");
 * @license MIT
 */
 const COMMON_ARGS_KEYS = Object.keys(COMMON_ARGS);
+function isHiddenArg(schema) {
+	return schema.hidden === true;
+}
+function getVisibleOptionalArgs(args) {
+	return Object.entries(args).filter(([_, schema]) => schema.type !== "positional" && !isHiddenArg(schema));
+}
+function getVisiblePositionalArgs(args) {
+	return Object.entries(args).filter(([_, schema]) => schema.type === "positional" && !isHiddenArg(schema));
+}
 /**
 * Render the usage.
 *
@@ -383,7 +392,7 @@ async function hasCommands(ctx) {
 * @returns True if the command has options
 */
 function hasOptionalArgs(args) {
-	return Object.values(args).some((arg) => arg.type !== "positional");
+	return getVisibleOptionalArgs(args).length > 0;
 }
 /**
 * Check if the command has positional arguments
@@ -392,7 +401,7 @@ function hasOptionalArgs(args) {
 * @returns True if the command has options
 */
 function hasPositionalArgs(args) {
-	return Object.values(args).some((arg) => arg.type === "positional");
+	return getVisiblePositionalArgs(args).length > 0;
 }
 /**
 * Check if all options have default values
@@ -401,7 +410,8 @@ function hasPositionalArgs(args) {
 * @returns True if all options have default values
 */
 function hasAllDefaultOptions(args) {
-	return !!(args && Object.values(args).every((arg) => arg.default));
+	const visibleOptionalArgs = getVisibleOptionalArgs(args);
+	return visibleOptionalArgs.length > 0 && visibleOptionalArgs.every(([_, arg]) => arg.default);
 }
 /**
 * Generate options symbols for usage
@@ -411,7 +421,7 @@ function hasAllDefaultOptions(args) {
 * @returns Options symbols for usage
 */
 async function generateOptionsSymbols(ctx, args) {
-	return hasOptionalArgs(args) ? hasAllDefaultOptions(args) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
+	return getVisibleOptionalArgs(args).length > 0 ? hasAllDefaultOptions(args) ? `[${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}]` : `<${await ctx.extensions[pluginId].text(resolveBuiltInKey("OPTIONS"))}>` : "";
 }
 /**
 * Get optional arguments pairs for usage
@@ -420,8 +430,7 @@ async function generateOptionsSymbols(ctx, args) {
 * @returns Options pairs for usage
 */
 function getOptionalArgsPairs(ctx) {
-	return Object.entries(ctx.args).reduce((acc, [name, schema]) => {
-		if (schema.type === "positional") return acc;
+	return getVisibleOptionalArgs(ctx.args).reduce((acc, [name, schema]) => {
 		let key = makeShortLongOptionPair(schema, name, ctx.toKebab);
 		if (schema.type !== "boolean") {
 			const displayName = ctx.toKebab || schema.toKebab ? kebabnize(name) : name;
@@ -461,9 +470,11 @@ async function resolveDisplayValue(ctx, key) {
 * @returns Generated options usage
 */
 async function generateOptionalArgsUsage(ctx, optionsPairs) {
-	const optionsMaxLength = Math.max(...Object.entries(optionsPairs).map(([_, value]) => value.length));
-	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...Object.entries(optionsPairs).map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
-	return (await Promise.all(Object.entries(optionsPairs).map(async ([key, value]) => {
+	const optionsPairsEntries = Object.entries(optionsPairs);
+	if (optionsPairsEntries.length === 0) return "";
+	const optionsMaxLength = Math.max(...optionsPairsEntries.map(([_, value]) => value.length));
+	const optionSchemaMaxLength = ctx.env.usageOptionType ? Math.max(...optionsPairsEntries.map(([key]) => resolveNegatableType(key, ctx).length)) : 0;
+	return (await Promise.all(optionsPairsEntries.map(async ([key, value]) => {
 		let rawDesc = await ctx.extensions[pluginId].text(resolveArgKey(key, ctx.name));
 		if (!rawDesc && key.startsWith("no-")) {
 			const name = resolveNegatableKey(key);
@@ -480,10 +491,11 @@ async function generateOptionalArgsUsage(ctx, optionsPairs) {
 	}))).join("\n");
 }
 function getPositionalArgs(args) {
-	return Object.entries(args).filter(([_, schema]) => schema.type === "positional");
+	return getVisiblePositionalArgs(args);
 }
 async function generatePositionalArgsUsage(ctx) {
 	const positionals = getPositionalArgs(ctx.args);
+	if (positionals.length === 0) return "";
 	const argsMaxLength = Math.max(...positionals.map(([name]) => name.length));
 	return (await Promise.all(positionals.map(async ([name]) => {
 		const desc = await ctx.extensions[pluginId].text(resolveArgKey(name, ctx.name)) || ctx.args[name].description || "";
@@ -492,13 +504,21 @@ async function generatePositionalArgsUsage(ctx) {
 	}))).join("\n");
 }
 function generatePositionalSymbols(args) {
-	return hasPositionalArgs(args) ? getPositionalArgs(args).map(([name, arg]) => {
+	const visiblePositionalArgs = getVisiblePositionalArgs(args);
+	return visiblePositionalArgs.length > 0 ? visiblePositionalArgs.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-DZ0S_FSe.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-mxPNDBm_.js";
 
 //#region src/plugin/context.d.ts
 /**

package/lib/{utils-jNy8sqR5.js → utils-DNVHO9MQ.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.27.0/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-DZ0S_FSe.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.27.0/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-DNVHO9MQ.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.35.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -108,7 +108,7 @@
     }
   },
   "devDependencies": {
-    "args-tokens": "^0.25.0",
+    "args-tokens": "^0.27.0",
     "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-i18n": "0.35.0",
+    "@gunshi/plugin-global": "0.35.0",
+    "@gunshi/plugin-renderer": "0.35.0",
+    "@gunshi/resources": "0.35.0",
+    "@gunshi/shared": "0.35.0"
   },
   "scripts": {
     "build": "tsdown",