gunshi 0.28.2 → 0.29.1

package/lib/bone.d.ts

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

package/lib/bone.js

@@ -1,4 +1,4 @@
-import { t as cliCore } from "./core-C9P_Gd_f.js";
+import { t as cliCore } from "./core-CoMdwsPo.js";
 
 //#region src/cli/bone.ts
 /**

package/lib/{cli-l4AYjN-O.js → cli-C1Yws72G.js}

@@ -1,6 +1,6 @@
-import { t as cliCore } from "./core-C9P_Gd_f.js";
+import { t as cliCore } from "./core-CoMdwsPo.js";
 import { t as plugin } from "./core-eN5xmB3s.js";
-import { a as namespacedId, s as COMMON_ARGS, t as renderer } from "./src-CfO5ab2f.js";
+import { a as namespacedId, s as COMMON_ARGS, t as renderer } from "./src-h66U0DWW.js";
 
 //#region ../plugin-global/src/types.ts
 /**

package/lib/combinators.d.ts

@@ -0,0 +1,639 @@
+import { i as Args, n as ArgSchema } from "./resolver-BfQ_CoYR.js";
+
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/combinators.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+
+//#region src/combinators.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+ * A combinator produced by combinator factory functions.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+type Combinator<T> = {
+  /**
+   * The parse function that converts a string to the desired type.
+   *
+   * @param value - The input string value.
+   * @returns The parsed value of type T.
+   */
+  parse: (value: string) => T;
+};
+/**
+ * A schema produced by combinator factory functions.
+ * Any {@link ArgSchema} with a parse function qualifies.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+type CombinatorSchema<T> = ArgSchema & Combinator<T>;
+/**
+ * Common options shared by all base combinators.
+ *
+ * @experimental
+ */
+interface BaseOptions {
+  /**
+   * Human-readable description for help text generation.
+   */
+  description?: string;
+  /**
+   * Single character short alias.
+   */
+  short?: string;
+  /**
+   * Mark as required.
+   */
+  required?: boolean;
+}
+/**
+ * Options for the {@link string} combinator.
+ *
+ * @experimental
+ */
+interface StringOptions extends BaseOptions {
+  /**
+   * Minimum string length.
+   */
+  minLength?: number;
+  /**
+   * Maximum string length.
+   */
+  maxLength?: number;
+  /**
+   * Regular expression pattern the value must match.
+   */
+  pattern?: RegExp;
+}
+/**
+ * Create a string argument schema with optional validation.
+ *
+ * @param opts - Validation options.
+ * @returns A combinator schema that resolves to string.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: string({ minLength: 1, maxLength: 50 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function string(opts?: StringOptions): CombinatorSchema<string>;
+/**
+ * Options for the {@link number} combinator.
+ *
+ * @experimental
+ */
+interface NumberOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create a number argument schema with optional range validation.
+ *
+ * Accepts any numeric value (integer or float).
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   timeout: number({ min: 0, max: 30000 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function number(opts?: NumberOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link integer} combinator.
+ *
+ * @experimental
+ */
+interface IntegerOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create an integer argument schema with optional range validation.
+ *
+ * Only accepts integer values (no decimals).
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number (integer).
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   retries: integer({ min: 0, max: 10 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function integer(opts?: IntegerOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link float} combinator.
+ *
+ * @experimental
+ */
+interface FloatOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create a floating-point argument schema with optional range validation.
+ *
+ * Rejects `NaN` and `Infinity` values.
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number (float).
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   ratio: float({ min: 0, max: 1 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function float(opts?: FloatOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link boolean} combinator.
+ *
+ * @experimental
+ */
+interface BooleanOptions extends BaseOptions {
+  /**
+   * Enable negation with `--no-` prefix.
+   */
+  negatable?: boolean;
+}
+/**
+ * Create a boolean argument schema.
+ *
+ * Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
+ * to the parse function based on the presence or negation of the flag.
+ *
+ * @param opts - Boolean options.
+ * @returns A combinator schema for boolean flags.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   color: boolean({ negatable: true })
+ * }
+ * // Usage: --color (true), --no-color (false)
+ * ```
+ *
+ * @experimental
+ */
+declare function boolean(opts?: BooleanOptions): CombinatorSchema<boolean>;
+/**
+ * Positional argument schema type.
+ */
+type ArgSchemaPositionalType = {
+  type: 'positional';
+};
+/**
+ * Create a positional argument schema.
+ *
+ * Without a parser, resolves to string.
+ * With a parser (e.g., `positional(integer())`), resolves to the parser's return type.
+ *
+ * @typeParam T - The parser's resolved type.
+ *
+ * @param parser - The parser combinator schema.
+ * @returns A positional argument schema resolving to the parser's type.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   command: positional(),           // resolves to string
+ *   port: positional(integer()),     // resolves to number
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function positional<T>(parser: CombinatorSchema<T>): CombinatorSchema<T> & ArgSchemaPositionalType;
+/**
+ * Create a positional argument schema.
+ *
+ * Without a parser, resolves to string.
+ * With a parser (e.g., `positional(integer())`), resolves to the parser's return type.
+ *
+ * @param parser - Optional base options (description, short, required).
+ * @returns A positional argument schema resolving to string.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   command: positional(),           // resolves to string
+ *   port: positional(integer()),     // resolves to number
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function positional(parser?: BaseOptions): ArgSchema & ArgSchemaPositionalType;
+/**
+ * Create an enum-like argument schema with literal type inference.
+ *
+ * Uses `const T` generic to infer literal union types from the values array.
+ *
+ * @typeParam T - The readonly array of allowed string values.
+ *
+ * @param values - Allowed values.
+ * @param opts - Common options (description, short, required).
+ * @returns A combinator schema that resolves to a union of the allowed values.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   level: choice(['debug', 'info', 'warn', 'error'] as const)
+ * }
+ * // typeof values.level === 'debug' | 'info' | 'warn' | 'error'
+ * ```
+ *
+ * @experimental
+ */
+declare function choice<const T extends readonly string[]>(values: T, opts?: BaseOptions): CombinatorSchema<T[number]>;
+/**
+ * Options for the {@link combinator} factory function.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+interface CombinatorOptions<T> extends BaseOptions {
+  /**
+   * The parse function that converts a string to the desired type.
+   *
+   * @param value - The input string value.
+   * @returns The parsed value of type T.
+   */
+  parse: (value: string) => T;
+  /**
+   * Display name hint for help text generation.
+   *
+   * @default 'custom'
+   */
+  metavar?: string;
+}
+/**
+ * Create a custom argument schema with a user-defined parse function.
+ *
+ * This is the most general custom combinator. Use it when none of the built-in
+ * base combinators ({@link string}, {@link number}, {@link integer},
+ * {@link float}, {@link boolean}, {@link choice}) fit your needs.
+ *
+ * The returned schema has `type: 'custom'`.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @param config - Configuration with a parse function and optional metavar.
+ * @returns A combinator schema that resolves to the parse function's return type.
+ *
+ * @example
+ * ```ts
+ * const date = combinator({
+ *   parse: (value) => {
+ *     const d = new Date(value)
+ *     if (isNaN(d.getTime())) {
+ *       throw new Error('Invalid date format')
+ *     }
+ *     return d
+ *   },
+ *   metavar: 'date'
+ * })
+ * ```
+ *
+ * @experimental
+ */
+declare function combinator<T>(config: CombinatorOptions<T>): CombinatorSchema<T>;
+/**
+ * Transform the output of a combinator schema.
+ *
+ * Creates a new schema that applies `transform` to the result of `schema.parse`.
+ * The original schema is not modified.
+ *
+ * @typeParam T - The input schema's parsed type.
+ * @typeParam U - The transformed type.
+ *
+ * @param schema - The base combinator schema.
+ * @param transform - The transformation function.
+ * @returns A new combinator schema that resolves to the transformed type.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   doubled: map(integer(), n => n * 2)
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function map<T, U>(schema: CombinatorSchema<T>, transform: (value: T) => U): CombinatorSchema<U>;
+/**
+ * Options for the {@link withDefault} combinator.
+ */
+type CombinatorWithDefault<T> = {
+  default: T;
+};
+/**
+ * Set a default value on a combinator schema.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @param defaultValue - The default value.
+ * @returns A new schema with the default value set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   port: withDefault(integer({ min: 1, max: 65535 }), 8080)
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function withDefault<T extends string | boolean | number>(schema: CombinatorSchema<T>, defaultValue: T): CombinatorSchema<T> & CombinatorWithDefault<T>;
+/**
+ * Options for the {@link multiple} combinator.
+ */
+type CombinatorMultiple = {
+  multiple: true;
+};
+/**
+ * Mark a combinator schema as accepting multiple values.
+ *
+ * The resolved value becomes an array. The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `multiple: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   tags: multiple(string())
+ * }
+ * // typeof values.tags === string[]
+ * ```
+ *
+ * @experimental
+ */
+declare function multiple<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorMultiple;
+/**
+ * Options for the {@link required} combinator.
+ */
+type CombinatorRequired = {
+  required: true;
+};
+/**
+ * Mark a combinator schema as required.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `required: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: required(string())
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function required<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorRequired;
+/**
+ * Options for the {@link short} combinator.
+ */
+type CombinatorShort<S extends string> = {
+  short: S;
+};
+/**
+ * Set a short alias on a combinator schema.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @typeParam S - The short alias string literal type.
+ *
+ * @param schema - The base combinator schema.
+ * @param alias - Single character short alias.
+ * @returns A new schema with the short alias set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   verbose: short(boolean(), 'v')
+ * }
+ * // Usage: -v or --verbose
+ * ```
+ *
+ * @experimental
+ */
+declare function short<T, S extends string>(schema: CombinatorSchema<T>, alias: S): CombinatorSchema<T> & CombinatorShort<S>;
+/**
+ * Options for the {@link describe} combinator.
+ */
+type CombinatorDescribe<D extends string> = {
+  description: D;
+};
+/**
+ * Set a description on a combinator schema for help text generation.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @typeParam D - The description string literal type.
+ *
+ * @param schema - The base combinator schema.
+ * @param text - Human-readable description.
+ * @returns A new schema with the description set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   port: describe(integer(), 'Port number to listen on')
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function describe<T, D extends string>(schema: CombinatorSchema<T>, text: D): CombinatorSchema<T> & CombinatorDescribe<D>;
+/**
+ * Options for the {@link unrequired} combinator.
+ */
+type CombinatorUnrequired = {
+  required: false;
+};
+/**
+ * Mark a combinator schema as not required.
+ *
+ * Useful for overriding a base combinator that was created with `required: true`.
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `required: false`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: unrequired(string({ required: true }))
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function unrequired<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorUnrequired;
+/**
+ * Recursively merge a tuple of {@link Args} types.
+ * Later types override earlier ones on key conflicts.
+ *
+ * @internal
+ */
+type MergeArgs<T extends Args[]> = T extends [infer Only extends Args] ? Only : T extends [infer First extends Args, ...infer Rest extends Args[]] ? Omit<First, keyof MergeArgs<Rest>> & MergeArgs<Rest> : never;
+/**
+ * Type-safe schema factory.
+ *
+ * Returns the input unchanged at runtime, but provides type inference
+ * so that `satisfies Args` is not needed.
+ *
+ * @typeParam T - The exact schema type.
+ *
+ * @param fields - The argument schema object.
+ * @returns The same schema object with its type inferred.
+ *
+ * @example
+ * ```ts
+ * const common = args({
+ *   verbose: boolean(),
+ *   help: short(boolean(), 'h')
+ * })
+ * ```
+ *
+ * @experimental
+ */
+declare function args<T extends Args>(fields: T): T;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * On key conflicts the later schema wins (last-write-wins).
+ *
+ * @typeParam A - First schema type.
+ * @typeParam B - Second schema type.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @example
+ * ```ts
+ * const common = args({ verbose: boolean() })
+ * const network = args({ host: required(string()), port: withDefault(integer(), 8080) })
+ * const schema = merge(common, network)
+ * ```
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args>(a: A, b: B): Omit<A, keyof B> & B;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @param c - Third schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args, C extends Args>(a: A, b: B, c: C): Omit<Omit<A, keyof B | keyof C> & Omit<B, keyof C>, never> & C;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @param c - Third schema.
+ * @param d - Fourth schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args, C extends Args, D extends Args>(a: A, b: B, c: C, d: D): MergeArgs<[A, B, C, D]>;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param schemas - The schemas to merge.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<T extends Args[]>(...schemas: T): MergeArgs<T>;
+/**
+ * Extend a schema by overriding or adding fields.
+ *
+ * Equivalent to `merge(base, overrides)` but communicates the intent of
+ * intentional overrides rather than general composition.
+ *
+ * @typeParam T - Base schema type.
+ * @typeParam U - Overrides schema type.
+ *
+ * @param base - The base schema to extend.
+ * @param overrides - Fields to override or add.
+ * @returns A new schema with overrides applied.
+ *
+ * @example
+ * ```ts
+ * const base = args({ port: withDefault(integer(), 8080) })
+ * const strict = extend(base, { port: required(integer({ min: 1, max: 65535 })) })
+ * ```
+ *
+ * @experimental
+ */
+declare function extend<T extends Args, U extends Args>(base: T, overrides: U): Omit<T, keyof U> & U;
+//#endregion
+//#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 };