gunshi 0.28.0 → 0.28.2

package/lib/bone.d.ts

@@ -1,4 +1,4 @@
-import { A as SubCommandable, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, O as RendererDecorator, S as ExtractExtensions, T as LazyCommand, _ as Commandable, a as Awaitable, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, h as CommandLoader, i as Args, j as ValidationErrorsDecorator, k as RenderingOptions, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, o as CliOptions, p as CommandEnvironment, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-DSyU38G8.js";
+import { B as Args, C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, H as ArgToken, R as ArgSchema, 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, z as ArgValues } from "./types-Doxo8g3Y.js";
 
 //#region src/cli/bone.d.ts
 /**

package/lib/{constants-Cqazor4w.d.ts → constants-C7V6-RNo.d.ts}

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

package/lib/context.d.ts

@@ -1,4 +1,4 @@
-import { C as GunshiParams, T as LazyCommand, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, i as Args, l as CommandContext, n as ArgToken, o as CliOptions, r as ArgValues, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-DSyU38G8.js";
+import { B as Args, H as ArgToken, _ 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, z as ArgValues } from "./types-Doxo8g3Y.js";
 
 //#region src/context.d.ts
 

package/lib/definition.d.ts

@@ -1,4 +1,4 @@
-import { C as GunshiParams, D as Prettify, S as ExtractExtensions, T as LazyCommand, g as CommandRunner, h as CommandLoader, i as Args, r as ArgValues, s as Command, t as ArgSchema, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext } from "./types-DSyU38G8.js";
+import { B as Args, C as Prettify, R as ArgSchema, _ 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, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { T as LazyCommand, o as CliOptions, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-DSyU38G8.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-Doxo8g3Y.js";
 
 //#region src/generator.d.ts
 

package/lib/index.d.ts

@@ -1,8 +1,7 @@
-import { A as SubCommandable, B as plugin, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, F as PluginExtension, I as PluginFunction, L as PluginOptions, M as OnPluginExtension, N as Plugin, O as RendererDecorator, P as PluginDependency, R as PluginWithExtension, S as ExtractExtensions, T as LazyCommand, V as PluginContext, _ as Commandable, a as Awaitable, b as ExtractArgExplicitlyProvided, c as CommandCallMode, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, h as CommandLoader, i as Args, j as ValidationErrorsDecorator, k as RenderingOptions, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, o as CliOptions, p as CommandEnvironment, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext, z as PluginWithoutExtension } from "./types-DSyU38G8.js";
+import { A as PluginDependency, B as Args, C as Prettify, D as ValidationErrorsDecorator, E as SubCommandable, F as PluginWithoutExtension, H as ArgToken, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, R as ArgSchema, S as NormalizeToGunshiParams, T as RenderingOptions, U as parseArgs, V as resolveArgs, _ 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, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
-import { t as ANONYMOUS_COMMAND_NAME } from "./constants-Cqazor4w.js";
-import { parseArgs, resolveArgs } from "args-tokens";
+import { t as ANONYMOUS_COMMAND_NAME } from "./constants-C7V6-RNo.js";
 
 //#region ../plugin-i18n/src/types.d.ts
 

package/lib/plugin.d.ts

@@ -1,4 +1,4 @@
-import { B as plugin, C as GunshiParams, D as Prettify, E as NormalizeToGunshiParams, F as PluginExtension, I as PluginFunction, L as PluginOptions, M as OnPluginExtension, N as Plugin, O as RendererDecorator, P as PluginDependency, R as PluginWithExtension, S as ExtractExtensions, T as LazyCommand, V as PluginContext, a as Awaitable, d as CommandContextExtension, f as CommandDecorator, g as CommandRunner, i as Args, j as ValidationErrorsDecorator, l as CommandContext, m as CommandExamplesFetcher, n as ArgToken, r as ArgValues, s as Command, t as ArgSchema, u as CommandContextCore, v as DefaultGunshiParams, w as GunshiParamsConstraint, x as ExtractArgs, y as ExtendContext, z as PluginWithoutExtension } from "./types-DSyU38G8.js";
+import { A as PluginDependency, B as Args, C as Prettify, D as ValidationErrorsDecorator, F as PluginWithoutExtension, H as ArgToken, I as plugin, L as PluginContext, M as PluginFunction, N as PluginOptions, O as OnPluginExtension, P as PluginWithExtension, R as ArgSchema, 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, z as ArgValues } from "./types-Doxo8g3Y.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
-import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-Cqazor4w.js";
+import { n as CLI_OPTIONS_DEFAULT, t as ANONYMOUS_COMMAND_NAME } from "./constants-C7V6-RNo.js";
 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 };

package/lib/renderer.d.ts

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

package/lib/{types-DSyU38G8.d.ts → types-Doxo8g3Y.d.ts}

@@ -1,11 +1,633 @@
-import { ArgExplicitlyProvided, ArgSchema, ArgSchema as ArgSchema$1, ArgToken, ArgToken as ArgToken$1, ArgValues, ArgValues as ArgValues$1, Args, Args as Args$1 } from "args-tokens";
-
-//#region src/plugin/context.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/parser.d.ts
+//#region src/parser.d.ts
+/**
+ * Entry point of argument parser.
+ *
+ * @module
+ */
+/**
+ * forked from `nodejs/node` (`pkgjs/parseargs`)
+ * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
+ * code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
+ *
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Argument token Kind.
+ *
+ * - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
+ * - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
+ * - `positional`: positional token
+ */
+type ArgTokenKind = 'option' | 'option-terminator' | 'positional';
+/**
+ * Argument token.
+ */
+interface ArgToken {
+  /**
+   * Argument token kind.
+   */
+  kind: ArgTokenKind;
+  /**
+   * Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
+   */
+  index: number;
+  /**
+   * Option name, e.g. `--foo` => `foo`, `-x` => `x`.
+   */
+  name?: string;
+  /**
+   * Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
+   */
+  rawName?: string;
+  /**
+   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
+   */
+  value?: string;
+  /**
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   */
+  inlineValue?: boolean;
+}
+/**
+ * Parser Options.
+ */
+interface ParserOptions {
+  /**
+   * [Node.js parseArgs](https://nodejs.org/api/util.html#parseargs-tokens) tokens compatible mode.
+   *
+   * @default false
+   */
+  allowCompatible?: boolean;
+}
+/**
+ * Parse command line arguments.
+ *
+ * @param args - command line arguments
+ * @param options - parse options, about details see {@link ParserOptions}
+ * @returns Argument tokens.
+ *
+ * @example
+ * ```js
+ * import { parseArgs } from 'args-tokens' // for Node.js and Bun
+ * // import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno
+ *
+ * const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
+ * // do something with using tokens
+ * // ...
+ * console.log('tokens:', tokens)
+ * ```
+ */
+declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
 /**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
+ * Check if `arg` is a short option (e.g. `-f`).
+ *
+ * @param arg - An argument to check
+ * @returns Whether `arg` is a short option.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/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
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
+ */
+interface ArgSchema {
+  /**
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
+  /**
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
+   */
+  short?: string;
+  /**
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
+   */
+  description?: string;
+  /**
+   * 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.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
+   */
+  required?: true;
+  /**
+   * Allows the argument to accept multiple values.
+   *
+   * 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
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
+   */
+  multiple?: true;
+  /**
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
+   */
+  negatable?: boolean;
+  /**
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
+   */
+  choices?: string[] | readonly string[];
+  /**
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
+   */
+  default?: string | boolean | number;
+  /**
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
+   */
+  toKebab?: true;
+  /**
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * Conflicts only need to be defined on one side - if option A defines a conflict
+   * with option B, the conflict is automatically detected when both are used,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn will throw error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  parse?: (value: string) => any;
+}
+/**
+ * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
+ */
+interface Args {
+  [option: string]: ArgSchema;
+}
+/**
+ * An object that contains the values of the arguments.
+ *
+ * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
+ */
+type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
+  [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
+};
+type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
+/**
+ * Extracts the value type from the argument schema.
+ *
+ * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
+ *
+ * @internal
+ */
+type ExtractOptionValue<A extends ArgSchema> = A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? IsFunction<A['parse']> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A['parse']>>> : never : ResolveOptionValue<A, string | boolean | number>;
+type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
+/**
+ * Resolved argument values.
+ *
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @internal
+ */
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
+/**
+ * Filters the arguments based on their default values.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
+ *
+ * @internal
+ */
+type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+/**
+ * Filters positional arguments from the argument schema.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam V - Resolvable argument values.
+ *
+ * @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] };
+/**
+ * An arguments for {@link resolveArgs | resolve arguments}.
+ */
+interface ResolveArgs {
+  /**
+   * Whether to group short arguments.
+   *
+   * @see guideline 5 in https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html
+   *
+   * @default false
+   */
+  shortGrouping?: boolean;
+  /**
+   * Skip positional arguments index.
+   *
+   * @default -1
+   */
+  skipPositional?: number;
+  /**
+   * Whether to convert the argument name to kebab-case. This option is applied to all arguments as `toKebab: true`, if set to `true`.
+   *
+   * @default false
+   */
+  toKebab?: boolean;
+}
+/**
+ * Tracks which arguments were explicitly provided by the user.
+ *
+ * Each property indicates whether the corresponding argument was explicitly
+ * provided (true) or is using a default value or not provided (false).
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ */
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+/**
+ * Resolve command line arguments.
+ *
+ * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
+ *
+ * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
+ * @param tokens - An array of {@link ArgToken | tokens}.
+ * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
+ * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
+ *
+ * @example
+ * ```typescript
+ * // passed tokens: --port 3000
+ *
+ * const { values, explicit } = resolveArgs({
+ *   port: {
+ *     type: 'number',
+ *     default: 8080
+ *   },
+ *   host: {
+ *     type: 'string',
+ *     default: 'localhost'
+ *   }
+ * }, parsedTokens)
+ *
+ * values.port // 3000
+ * values.host // 'localhost'
+ *
+ * explicit.port // true (explicitly provided)
+ * explicit.host // false (not provided, fallback to default)
+ * ```
+ */
+declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], {
+  shortGrouping,
+  skipPositional,
+  toKebab
+}?: ResolveArgs): {
+  values: ArgValues<A>;
+  positionals: string[];
+  rest: string[];
+  error: AggregateError | undefined;
+  explicit: ArgExplicitlyProvided<A>;
+};
+/**
+ * An error type for {@link ArgResolveError}.
+ */
+//#endregion
+//#region src/plugin/context.d.ts
 /**
  * Type helper to create GunshiParams from extracted args and extensions
  *
@@ -1037,4 +1659,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 { SubCommandable as A, plugin as B, GunshiParams as C, Prettify as D, NormalizeToGunshiParams as E, PluginExtension as F, PluginFunction as I, PluginOptions as L, OnPluginExtension as M, Plugin as N, RendererDecorator as O, PluginDependency as P, PluginWithExtension as R, ExtractExtensions as S, LazyCommand as T, PluginContext as V, Commandable as _, Awaitable as a, ExtractArgExplicitlyProvided as b, CommandCallMode as c, CommandContextExtension as d, CommandDecorator as f, CommandRunner as g, CommandLoader as h, Args$1 as i, ValidationErrorsDecorator as j, RenderingOptions as k, CommandContext as l, CommandExamplesFetcher as m, ArgToken$1 as n, CliOptions as o, CommandEnvironment as p, ArgValues$1 as r, Command as s, ArgSchema$1 as t, CommandContextCore as u, DefaultGunshiParams as v, GunshiParamsConstraint as w, ExtractArgs as x, ExtendContext as y, PluginWithoutExtension as z };
+export { PluginDependency as A, Args as B, Prettify as C, ValidationErrorsDecorator as D, SubCommandable as E, PluginWithoutExtension as F, ArgToken as H, plugin as I, PluginContext as L, PluginFunction as M, PluginOptions as N, OnPluginExtension as O, PluginWithExtension as P, ArgSchema as R, NormalizeToGunshiParams as S, RenderingOptions as T, parseArgs as U, resolveArgs as V, 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, ArgValues as z };

package/lib/utils.d.ts

@@ -1,12 +1,29 @@
-import { T as LazyCommand, _ as Commandable, s as Command, v as DefaultGunshiParams, w as GunshiParamsConstraint } from "./types-DSyU38G8.js";
-import { kebabnize } from "args-tokens/utils";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-Doxo8g3Y.js";
+
+//#region ../../node_modules/.pnpm/args-tokens@0.23.1/node_modules/args-tokens/lib/utils.d.ts
 
 //#region src/utils.d.ts
 /**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
+ * Entry point of utils.
+ *
+ * Note that this entry point is used by gunshi to import utility functions.
+ *
+ * @module
+ */
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Convert a string to kebab-case.
+ *
+ * @param str - A string to convert
+ * @returns Converted string into kebab-case.
+ */
+declare function kebabnize(str: string): string;
+//#endregion
+//#endregion
+//#region src/utils.d.ts
 /**
  * Check if the given command is a {@link LazyCommand}.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -103,11 +103,11 @@
     "publint": "^0.3.16",
     "tsdown": "0.15.12",
     "zod": "^4.2.1",
-    "@gunshi/plugin-global": "0.28.0",
-    "@gunshi/plugin-i18n": "0.28.0",
-    "@gunshi/resources": "0.28.0",
-    "@gunshi/shared": "0.28.0",
-    "@gunshi/plugin-renderer": "0.28.0"
+    "@gunshi/plugin-global": "0.28.2",
+    "@gunshi/plugin-i18n": "0.28.2",
+    "@gunshi/resources": "0.28.2",
+    "@gunshi/plugin-renderer": "0.28.2",
+    "@gunshi/shared": "0.28.2"
   },
   "scripts": {
     "build": "tsdown",