@gunshi/shared 0.37.2 → 1.0.0-beta.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -42,20 +42,24 @@ interface ArgToken {
    */
   rawName?: string;
   /**
-   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * Option value, e.g. `--foo=bar` => `bar`. The value of a short option, such as `bar` of
+   * `-x=bar`, `-1` of `-x=-1` or `-x-1`, and `''` of `-x=`, is in a token of its own after the
+   * option, which has no `name` and `rawName`.
    * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
    */
-  value?: string;
+  value?: string | undefined;
   /**
-   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`, `-x-1` => `false`, since no `=`
+   * is written. Unlike Node.js `parseArgs`, `false` does not mean that the value is the next
+   * argument: the value token of `-x-1` has the `index` of that argument.
    */
-  inlineValue?: boolean;
+  inlineValue?: boolean | undefined;
 }
 /**
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -101,19 +105,25 @@ interface ArgSchema {
   /**
    * Type of the argument value.
    *
-   * - `'string'`: Text value (default if not specified)
-   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'string'`: Text value
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix). `--flag=true` and
+   *   `--flag=false` set the value explicitly; any other value after `=` is a type error
    * - `'number'`: Numeric value (parsed as integer or float)
-   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'enum'`: One of predefined string values (requires `choices` property, unless the argument
+   *   has a `parse` function)
    * - `'positional'`: Non-option argument by position
    * - `'custom'`: Custom parsing with user-defined `parse` function
    *
+   * Any other `type`, or no `type`, is a mistake that only untyped code can make: if the argument
+   * has no `parse` function, {@link resolveArgs} and `parse()` throw an `Error`, whether or not the
+   * argument is given.
+   *
    * @example
    * Different argument types:
    * ```ts
    * {
    *   name: { type: 'string' },        // --name value
-   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   verbose: { type: 'boolean' },     // --verbose (--no-verbose needs negatable: true)
    *   port: { type: 'number' },         // --port 3000
    *   level: { type: 'enum', choices: ['debug', 'info'] },
    *   file: { type: 'positional' },     // first positional arg
@@ -188,14 +198,32 @@ interface ArgSchema {
   /**
    * 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.
-   *
-   * 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
+   * When `true`, the argument must be provided by the user. If it is missing, the error is an
+   * `ArgResolveError` with type 'required' and the code `err:arg:required-option`
+   * ({@link ArgsValidationErrorKeys}.requiredOption), or `err:arg:required-positional`
+   * ({@link ArgsValidationErrorKeys}.requiredPositional) for a positional argument. Its
+   * `values` has the `displayName` as in the message, such as `'--name'` for an option
+   * (`'--name' or '-n'` with the short name `n`) and `'file'` for a positional argument, and
+   * the `name`, which is the schema key.
+   * An option that is given without a value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue) instead, because the option itself was given.
+   * An explicit empty value, such as `--name=` or `-n ''`, is still reported as required, but the
+   * option counts as given: it is `true` in `explicit` and takes part in conflicts, as any other
+   * given option does.
+   *
+   * For single-value positional arguments, omitting `required` keeps the argument required for
+   * compatibility, unless it has a `default`, which makes it optional. A `multiple` positional
+   * argument is optional unless `required: true` is set. Set `required: false` to make a positional
+   * argument explicitly optional. Optional positional arguments leave enough input values for later
    * required positional arguments before consuming a value.
    *
+   * In the type of the values, such as {@link ArgValues}, a single-value positional argument whose
+   * `required` may be `false`, such as one of type `boolean`, is optional, as it may be missing,
+   * unless it has a `default`. An optional `required` of type `boolean`, as declared here, says
+   * nothing, and keeps it required. TypeScript widens a `required: true` to `boolean` in a schema
+   * written apart from the call, such as `{ type: 'positional' as const, required: true }`, which
+   * types the argument as optional: write such a schema `as const`.
+   *
    * @example
    * Required arguments:
    * ```ts
@@ -216,8 +244,9 @@ interface ArgSchema {
   /**
    * 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)
+   * When `true`, the resolved value becomes an array. When the argument is not given and has no
+   * `default`, its value is `undefined`, not an empty array.
+   * For options: can be specified multiple times (--tags foo --tags bar)
    * For positional: collects remaining positional arguments after preserving values for
    * later required positional arguments.
    *
@@ -249,6 +278,12 @@ interface ArgSchema {
    *
    * Only applicable to `type: 'boolean'` arguments.
    *
+   * The negated name is always `no-` followed by the full option name. An option named
+   * `no-cache` is negated by `--no-no-cache`, and `--no-cache` sets it to `true`.
+   *
+   * The negated form does not take a value. `--no-flag=<value>` is reported as
+   * `err:arg:unexpected-value` ({@link ArgsValidationErrorKeys}.unexpectedValue).
+   *
    * @example
    * Negatable boolean:
    * ```ts
@@ -267,8 +302,17 @@ interface ArgSchema {
   /**
    * 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.
+   * Required when `type: 'enum'`, unless the argument has a `parse` function: if `choices` is
+   * missing or not an array, {@link resolveArgs} and `parse()` throw a `TypeError`, whether or not
+   * the argument is given. With a `parse` function and no `choices`, the value is passed to the
+   * function as for a `string` argument with a `parse` function.
+   *
+   * The argument value must be one of these choices, otherwise the error is an `ArgResolveError`
+   * with type 'type' and the code `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice).
+   *
+   * The value is checked before `parse` is called, so a `parse` function receives only one of
+   * these choices and can change it, for example to upper case.
    *
    * Supports both mutable arrays and readonly arrays for type safety.
    *
@@ -292,18 +336,37 @@ interface ArgSchema {
    */
   choices?: string[] | readonly string[];
   /**
-   * Default value used when the argument is not provided.
+   * Default value used when the argument is not provided. An option that is given without a value,
+   * or with a value that is rejected, also gets its default, along with the error.
    *
    * 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
+   * - `enum` type: one of the `choices` values, or a value that a `parse` of your own returns
    * - `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.
+   * The default is used as is and never goes through `parse`, including when an option is given
+   * without a value. An explicit empty value, such as `--name=` or `-n ''`, is a value, not a
+   * missing one: a `string` option without `parse` gets `''` instead of the default, unless it is
+   * `required`. What `parse` returns is a value too, even `undefined` or `null`, and the default
+   * does not replace it.
+   *
+   * The value of a `multiple` argument is an array, so its default becomes the only element of the
+   * array: `default: 'latest'` gives `['latest']`.
+   *
+   * The default of an `enum` option with `choices` is checked when it would be used, that is, when
+   * no value from the command line is used: one that is not one of the choices is reported as an
+   * `ArgResolveError` with type 'type' and the code `err:arg:invalid-default`
+   * ({@link ArgsValidationErrorKeys}.invalidDefault), and is not used. With a `parse` function of
+   * your own, or a `map()` transform, the default is a value that the function returns, which need
+   * not be one of the choices, and it is not checked. `choice()` returns the value as is, so its
+   * default is checked.
+   *
+   * For positional arguments, `multiple` ones included, the default is used when no value is left
+   * for the argument: when the positional values run out, or when the remaining ones are preserved
+   * for later required positional arguments. With `required: true`, the default is not used, and
+   * the argument is reported as required instead.
    *
    * @example
    * Default values by type:
@@ -336,7 +399,8 @@ interface ArgSchema {
    * 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 })`.
+   * The `toKebab` option of {@link resolveArgs} and `parse()` applies it to all arguments, as in
+   * `resolveArgs(args, tokens, { toKebab: true })`.
    *
    * Note: Only `true` is allowed (not `false`) to make intent explicit.
    *
@@ -360,8 +424,19 @@ interface ArgSchema {
   /**
    * 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.
+   * When this option is used together with any of the conflicting options, the error is an
+   * `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
+   * ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
+   * the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
+   * `conflictName` of the other one. `displayName` and `conflictDisplayName` show an option as
+   * it was written, such as `'-p'`, and `name` and `conflictName` are the schema keys. When both
+   * name each other, `name` is the one that comes first in the schema.
+   *
+   * A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
+   * it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as
+   * in its other errors. The message starts with the kind of the argument given as `name`:
+   * `Positional argument 'file' conflicts with '--stdin'` or
+   * `Optional argument '--stdin' conflicts with 'file'`.
    *
    * 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,
@@ -399,7 +474,7 @@ interface ArgSchema {
    *     // No conflicts defined, but still cannot use with --summer
    *   }
    * }
-   * // Usage: --summer --autumn will throw error
+   * // Usage: --summer --autumn reports an error
    * // Error: "Optional argument '--summer' conflicts with '--autumn'"
    * ```
    *
@@ -451,6 +526,10 @@ interface ArgSchema {
    * Particularly useful for `type: 'custom'` arguments where the type
    * name would otherwise be unhelpful.
    *
+   * For a `custom` option that is given without a value, it is also the `expected` in the `values`
+   * of the `err:arg:missing-value` error ({@link ArgsValidationErrorKeys}.missingValue), which is
+   * `'custom'` without it.
+   *
    * @example
    * Metavar usage:
    * ```ts
@@ -467,13 +546,37 @@ interface ArgSchema {
    */
   metavar?: string;
   /**
-   * Custom parsing function for `type: 'custom'` arguments.
+   * Custom parsing function, used in place of the parsing of the argument's `type`.
    *
-   * Required when `type: 'custom'`. Receives the raw string value and must
-   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   * Required when `type: 'custom'`: if it is missing or not a function, {@link resolveArgs} and
+   * `parse()` throw a `TypeError`, whether or not the argument is given. The function receives the
+   * raw string value and must return the parsed result. It should throw an Error (or subclass) if
+   * parsing fails.
    *
    * The function's return type becomes the resolved argument type.
    *
+   * `parse` is called synchronously, and what it returns becomes the value, even `undefined` or
+   * `null`, so throw to reject a value. An `async` function returns a promise, and the promise
+   * becomes the value as is: it is not awaited, and its rejection is not reported as an error.
+   * Await the value, or each of its elements with `multiple` (for example with `Promise.all()`),
+   * and handle the rejection yourself: a rejection that nothing handles is an unhandled rejection,
+   * which ends a Node.js process by default.
+   *
+   * A `boolean` option calls `parse` with `'true'`, or `'false'` for the negated form. Other
+   * options call it only with a value from the command line: when the option is given without a
+   * value, `parse` is not called and the missing value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue). When that error may suggest the argument after
+   * the option as its value, such as `--port=-5` for `--port -5`, a `parse` function of your own
+   * is not called to check it either: only the `parse` functions of `string()`, `number()`,
+   * `integer()`, `float()` and `choice()`, which have no side effects, are called for that.
+   * An explicit empty value, such as `--name=` or `-n=`, is passed as `''` unless
+   * `required: true` is set.
+   *
+   * An `enum` option with `choices` calls it only with one of them. Any other value, an explicit
+   * empty one included, is reported as `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice), except that a required option reports an
+   * explicit empty value as required.
+   *
    * @param value - Raw string value from command line
    * @returns Parsed value of any type
    * @throws {Error} Error or subclass when value is invalid
@@ -508,13 +611,6 @@ interface ArgSchema {
    */
   parse?: (value: string) => any;
 }
-/**
- * Machine-readable error codes for {@link ArgsValidationError}.
- *
- * Each code identifies a validation failure category and is also suitable as an
- * i18n resource key for localized rendering.
- */
-
 /**
  * An object that contains {@link ArgSchema | argument schema}.
  *
@@ -526,6 +622,20 @@ interface Args {
 /**
  * An object that contains the values of the arguments.
  *
+ * The value of an argument whose schema is a union, such as
+ * `strict ? multiple(integer()) : string()` with the combinators, is typed as a value of any of its
+ * schemas: `number[] | string`. The argument is typed as present only when each schema of the
+ * union gives it a value, with a default, with `required: true` or as a required positional
+ * argument.
+ *
+ * When the type of one schema covers that of the other, as the type of `integer()` covers that of
+ * `multiple(integer())`, TypeScript types a `?:` expression of them as the covering schema alone:
+ * the value of `strict ? multiple(integer()) : integer()` is typed without the array, and
+ * `strict ? multiple(positional()) : positional()` as present, although it may be missing. Give
+ * each schema its own argument instead, or give the expression the type of both schemas with `as`,
+ * as in `(strict ? many : one) as typeof many | typeof one` for `const many = multiple(integer())`
+ * and `const one = integer()`.
+ *
  * @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]> }> : {
@@ -533,22 +643,41 @@ type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: Ext
 };
 /**
  * Extracts the value type from the argument schema.
+ * For a union of schemas, it is the union of the value types of its schemas.
  *
  * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
  *
  * @internal
  */
-type ExtractOptionValue<A extends ArgSchema> = undefined extends A['parse'] ? 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' ? never : ResolveOptionValue<A, string | boolean | number> : A['parse'] extends ((value: string) => infer R) ? ResolveOptionValue<A, R> : never;
+type ExtractOptionValue<A extends ArgSchema> = A extends ArgSchema ? ExtractSchemaValue<A> : never;
+/**
+ * The value type of one schema, which {@link ExtractOptionValue} takes for each schema of a union.
+ */
+type ExtractSchemaValue<A extends ArgSchema> = undefined extends A['parse'] ? 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' ? never : ResolveOptionValue<A, string | boolean | number> : A['parse'] extends ((value: string) => infer R) ? ResolveOptionValue<A, R> : never;
 type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
 /**
  * Resolved argument values.
  *
+ * Each argument is mapped as optional, and the ones that are present, as {@link IsPresentArg}
+ * says, are mapped again as present. The optional mapping types a present argument as `unknown`:
+ * TypeScript does not reduce an intersection such as
+ * `(string | number[] | undefined) & (string | number[])`, of a value type that is a union with an
+ * object type. It maps all the keys without renaming them, which lets TypeScript relate the values
+ * of related type parameters, so that a conversion such as `values as ArgValues<A>` compiles.
+ *
  * @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;
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: IsPresentArg<A[Arg]> extends true ? unknown : V[Arg] } & { -readonly [Arg in keyof A as IsPresentArg<A[Arg]> extends true ? Arg : never]: V[Arg] } extends (infer P) ? { [K in keyof P]: P[K] } : never;
+/**
+ * Whether an argument with the schema `S` has a value: with a default, with `required: true` or as
+ * a required positional argument. For a union of schemas, only when each schema of the union has
+ * one. A `default` or `required` typed as `any`, and a schema typed as `any`, count as giving a
+ * value, as {@link FilterArgs} does.
+ */
+type IsPresentArg<S extends ArgSchema> = S extends ArgSchema ? true extends (S['default'] extends {} ? true : S['required'] extends true ? true : false) ? true : IsRequiredPositionalArg<S> : never;
 /**
  * Filters the arguments based on their default values.
  *
@@ -558,17 +687,17 @@ type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -r
  *
  * @internal
  */
-type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as K extends 'required' ? A[Arg][K] extends true ? Arg : never : A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+
+type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : MayBeUnrequired<A> extends true ? A['default'] extends {} ? true : false : true : false;
 /**
- * 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
+ * Whether the `required` of `A` may be `false`. An optional `required` of type `boolean`, as in
+ * {@link ArgSchema}, says nothing, and is read as missing, so that a positional argument with it is
+ * required. A `required` that `A` always has may be `false` when its type is `boolean` or
+ * `boolean | undefined`.
  */
-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;
+type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] extends [{
+  required: unknown;
+}] ? true : boolean | undefined extends A['required'] ? false : true : false;
 /**
  * An arguments for {@link resolveArgs | resolve arguments}.
  */
@@ -576,44 +705,16 @@ type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positiona
 /**
  * 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).
+ * Each property is `true` when the argument is given on the command line, and `false` when it is
+ * not, whether it has a default or not. An option is given when one of its forms is, such as
+ * `--port`, `-p` or `--no-color`, even if its value is missing or rejected: the error is reported,
+ * and if no value from the command line is used, its default, if any, fills in the value. A
+ * positional argument is given when a positional value is used for it, even if `parse` rejects
+ * the value: the error is reported, and its default is not used.
  *
  * @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)
- * ```
- */
 //#endregion
 //#region ../gunshi/src/types.d.ts
 /**
@@ -760,7 +861,11 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    */
   usageOptionValue: boolean;
   /**
-   * Whether to display the command usage.
+   * Whether to keep usage, header, version, and validation-error text off the terminal
+   * (they are still returned as strings) and to silence {@linkcode CommandContext.log}.
+   *
+   * Output that must still appear — machine-readable results for an agent, warnings for the
+   * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
    *
    * @default false
    * @see {@linkcode CliOptions.usageSilent}
@@ -779,6 +884,26 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    * @see {@linkcode CliOptions.subCommands}
    */
   subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
+  /**
+   * The entry command of the CLI, marked with `entry: true`.
+   *
+   * It is available whether or not the CLI has sub-commands, while {@linkcode CommandEnvironment.subCommands}
+   * includes the entry command only when the sub-commands are given with {@linkcode CliOptions.subCommands}.
+   * It is not frozen, like the commands in {@linkcode CommandEnvironment.subCommands}.
+   */
+  entryCommand?: Command<any> | LazyCommand<any>;
+  /**
+   * The global options that are in effect for the command being executed.
+   *
+   * A plugin registers a global option with `addGlobalOption`, and gunshi merges it into the arguments
+   * of the command that runs. An argument that the command declares under the same name replaces it,
+   * and the option is then not in effect: the value under that name is the command's, and the plugin
+   * that registered it must not read it as its own.
+   *
+   * The schema is the one in effect, which may have given up its short name to an argument of the
+   * command that claims the same letter.
+   */
+  globalOptions?: ReadonlyMap<string, ArgSchema>;
   /**
    * Render function the command usage.
    */
@@ -1126,7 +1251,7 @@ type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiPara
  */
 type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>;
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.d.ts
 //#region src/utils.d.ts
 /**
  * Entry point of utils.
@@ -1146,24 +1271,24 @@ type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ct
  * @returns Converted string into kebab-case.
  */
 declare function kebabnize(str: string): string;
-/**
- * Format allowed argument choices for validation error values and fallback messages.
- *
- * @param choices - Choice values to format
- * @returns JSON-quoted choices joined with `, `.
- */
 //#endregion
 //#region ../gunshi/src/utils.d.ts
 /**
  * Check if the given command is a {@link LazyCommand}.
  *
  * @param cmd - A command to check
- * @returns `true` if the command is a {@link LazyCommand}, otherwise `false
+ * @returns `true` if the command is a {@link LazyCommand}, otherwise `false`
+ *
+ * A lazy command is identified by its `commandName` property. The property may be
+ * `undefined` when the lazy command has no definition name.
  */
 declare function isLazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams>(cmd: unknown): cmd is LazyCommand<G>;
 /**
  * Resolve a lazy command to a {@link Command}.
  *
+ * If the loader returns a command, the properties of the loaded command take precedence,
+ * and the properties that it does not define fall back to the definition that is given to `lazy`.
+ *
  * @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
  * @param name - Optional name of the command, if not provided, it will use the name from the command itself.
  * @param needRunResolving - Whether to run the resolving function of the lazy command.
@@ -1177,6 +1302,19 @@ declare function resolveLazyCommand<G extends GunshiParamsConstraint = DefaultGu
  * @returns A new object with the specified prototype
  */
 declare function create<T>(obj?: object | null): T;
+/**
+ * Resolve the arguments of a command, the way gunshi parses and renders them.
+ *
+ * The global options belong to no command definition, so they are merged into the arguments of the
+ * command that runs. An argument of the command shadows the global option of the same name, and it
+ * shadows the same way by short name: a global option gives up its short name to an argument of the
+ * command that claims the same letter, and keeps its long name.
+ *
+ * @param globalOptions - The global options that plugins registered with `addGlobalOption`
+ * @param args - The arguments that the command declares
+ * @returns The merged arguments
+ */
+declare function resolveCommandArgs<A extends Args = Args>(globalOptions?: ReadonlyMap<string, ArgSchema>, args?: A): A;
 /**
  * Log a message to the console.
  *
@@ -1227,8 +1365,8 @@ type CommonArgType = {
 };
 declare const COMMON_ARGS: CommonArgType;
 declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
-declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option"];
-declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found"];
+declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
+declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
 //#endregion
 //#region src/types.d.ts
@@ -1375,7 +1513,14 @@ declare const _exports: {
   "err:arg:invalid-choice": string;
   "err:arg:custom-parse": string;
   "err:arg:unknown-option": string;
+  "err:arg:unexpected-value": string;
+  "err:arg:missing-value": string;
+  "err:arg:conflict": string;
+  "err:arg:invalid-default": string;
   "err:cmd:not-found": string;
+  "err:cmd:ambiguous": string;
+  "err:cmd:inconsistent-options": string;
+  "err:cmd:lazy-schema-mismatch": string;
   "err:suggestion:did-you-mean": string;
 };
 //#endregion
@@ -1444,6 +1589,26 @@ declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K,
  * @returns A string representing the short and long option pair.
  */
 declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKebab?: boolean): string;
+/**
+ * Resolve the name that an argument is parsed and rendered under.
+ *
+ * @param name - The key of the argument.
+ * @param schema - The {@linkcode ArgSchema | argument schema}.
+ * @param toKebab - Whether to convert the name to kebab-case.
+ * @returns The name of the argument, kebab-cased when `toKebab` asks for it.
+ */
+declare function resolveDisplayName(name: string, schema: ArgSchema, toKebab?: boolean): string;
+/**
+ * Collect the names that the arguments are parsed and rendered under.
+ *
+ * A positional argument is left out: it is never spelled as an option, so it cannot take the name of
+ * one. A `hidden` argument is counted, because it still owns the name that it parses.
+ *
+ * @param args - The {@linkcode Args | arguments} of a command, global options included.
+ * @param toKebab - Whether the command converts its names to kebab-case.
+ * @returns The set of names.
+ */
+declare function resolveOptionNames(args: Args, toKebab?: boolean): Set<string>;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -1452,4 +1617,4 @@ declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKeba
 */
 
 //#endregion
-export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResource, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandErrorResourceKeys, DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, ErrorResourceKeys, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, SuggestionErrorResourceKeys, Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResource, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandErrorResourceKeys, DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, ErrorResourceKeys, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, SuggestionErrorResourceKeys, Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *
@@ -29,14 +29,20 @@ function kebabnize(str) {
 * Check if the given command is a {@link LazyCommand}.
 *
 * @param cmd - A command to check
-* @returns `true` if the command is a {@link LazyCommand}, otherwise `false
+* @returns `true` if the command is a {@link LazyCommand}, otherwise `false`
+*
+* A lazy command is identified by its `commandName` property. The property may be
+* `undefined` when the lazy command has no definition name.
 */
 function isLazyCommand(cmd) {
-	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+	return typeof cmd === "function" && "commandName" in cmd;
 }
 /**
 * Resolve a lazy command to a {@link Command}.
 *
+* If the loader returns a command, the properties of the loaded command take precedence,
+* and the properties that it does not define fall back to the definition that is given to `lazy`.
+*
 * @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
 * @param name - Optional name of the command, if not provided, it will use the name from the command itself.
 * @param needRunResolving - Whether to run the resolving function of the lazy command.
@@ -52,6 +58,8 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			examples: cmd.examples,
 			internal: cmd.internal,
 			entry: cmd.entry,
+			toKebab: cmd.toKebab,
+			rendering: cmd.rendering,
 			subCommands: cmd.subCommands
 		};
 		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
@@ -61,13 +69,20 @@ async function resolveLazyCommand(cmd, name, needRunResolving = false) {
 			if (typeof loaded === "function") command.run = loaded;
 			else if (typeof loaded === "object") {
 				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
+				/**
+				* NOTE(kazupon): the loaded command wins, and the definition that is given to `lazy` is the fallback
+				* for what the loaded command does not define. A loader that returns `{ run }` keeps the whole definition,
+				* like a loader that returns the runner itself.
+				*/
 				command.run = loaded.run;
-				command.name = loaded.name;
-				command.description = loaded.description;
-				command.args = loaded.args;
-				command.examples = loaded.examples;
-				command.internal = loaded.internal;
-				command.entry = loaded.entry;
+				command.name = loaded.name ?? cmd.commandName;
+				command.description = loaded.description ?? cmd.description;
+				command.args = loaded.args ?? cmd.args;
+				command.examples = loaded.examples ?? cmd.examples;
+				command.internal = loaded.internal ?? cmd.internal;
+				command.entry = loaded.entry ?? cmd.entry;
+				command.toKebab = loaded.toKebab ?? cmd.toKebab;
+				command.rendering = loaded.rendering ?? cmd.rendering;
 				command.subCommands = loaded.subCommands || cmd.subCommands;
 				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
 			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
@@ -86,6 +101,37 @@ function create(obj = null) {
 	return Object.create(obj);
 }
 /**
+* Resolve the arguments of a command, the way gunshi parses and renders them.
+*
+* The global options belong to no command definition, so they are merged into the arguments of the
+* command that runs. An argument of the command shadows the global option of the same name, and it
+* shadows the same way by short name: a global option gives up its short name to an argument of the
+* command that claims the same letter, and keeps its long name.
+*
+* @param globalOptions - The global options that plugins registered with `addGlobalOption`
+* @param args - The arguments that the command declares
+* @returns The merged arguments
+*/
+function resolveCommandArgs(globalOptions, args) {
+	return Object.assign(create(), resolveGlobalOptions(globalOptions, args), args);
+}
+function resolveGlobalOptions(globalOptions, args) {
+	if (!globalOptions) return;
+	const shortNames = /* @__PURE__ */ new Set();
+	for (const schema of Object.values(args || {})) if (schema.type !== "positional" && schema.short) shortNames.add(schema.short);
+	const resolved = create();
+	for (const [name, schema] of globalOptions)
+ /**
+	* NOTE(kazupon): a copy, because the schema is the one that the plugin registered, which every
+	* command of the CLI shares. Only this command gives up the short name.
+	*/
+	resolved[name] = schema.short && shortNames.has(schema.short) ? {
+		...schema,
+		short: void 0
+	} : schema;
+	return resolved;
+}
+/**
 * Log a message to the console.
 *
 * @param args - Arguments to log
@@ -173,9 +219,18 @@ const ARG_ERROR_RESOURCE_KEYS = [
 	"err:arg:invalid-type",
 	"err:arg:invalid-choice",
 	"err:arg:custom-parse",
-	"err:arg:unknown-option"
+	"err:arg:unknown-option",
+	"err:arg:unexpected-value",
+	"err:arg:missing-value",
+	"err:arg:conflict",
+	"err:arg:invalid-default"
+];
+const COMMAND_ERROR_RESOURCE_KEYS = [
+	"err:cmd:not-found",
+	"err:cmd:ambiguous",
+	"err:cmd:inconsistent-options",
+	"err:cmd:lazy-schema-mismatch"
 ];
-const COMMAND_ERROR_RESOURCE_KEYS = ["err:cmd:not-found"];
 const SUGGESTION_ERROR_RESOURCE_KEYS = ["err:suggestion:did-you-mean"];
 //#endregion
 //#region ../resources/locales/en-US.json
@@ -199,7 +254,14 @@ var en_US_default = {
 	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
 	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
 	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:arg:unexpected-value": "Optional argument {$displayName} does not take a value",
+	"err:arg:missing-value": "Optional argument {$displayName} requires a value",
+	"err:arg:conflict": "{$displayName} conflicts with {$conflictDisplayName}",
+	"err:arg:invalid-default": "Invalid default for {$displayName}: {$actual} is not one of {$choices}",
 	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:cmd:ambiguous": "The command is ambiguous. Move options after the command name: {$candidatePaths}",
+	"err:cmd:inconsistent-options": "The options do not identify a consistent command. Move options after the command name.",
+	"err:cmd:lazy-schema-mismatch": "The lazy command definition does not match its loaded options. Declare leading options in the lazy definition or move options after the command name: {$commandPath}",
 	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
@@ -282,10 +344,36 @@ function namespacedId(id) {
 * @returns A string representing the short and long option pair.
 */
 function makeShortLongOptionPair(schema, name, toKebab) {
-	let key = `--${toKebab || schema.toKebab ? kebabnize(name) : name}`;
+	let key = `--${resolveDisplayName(name, schema, toKebab)}`;
 	if (schema.short) key = `-${schema.short}, ${key}`;
 	return key;
 }
+/**
+* Resolve the name that an argument is parsed and rendered under.
+*
+* @param name - The key of the argument.
+* @param schema - The {@linkcode ArgSchema | argument schema}.
+* @param toKebab - Whether to convert the name to kebab-case.
+* @returns The name of the argument, kebab-cased when `toKebab` asks for it.
+*/
+function resolveDisplayName(name, schema, toKebab) {
+	return toKebab || schema.toKebab ? kebabnize(name) : name;
+}
+/**
+* Collect the names that the arguments are parsed and rendered under.
+*
+* A positional argument is left out: it is never spelled as an option, so it cannot take the name of
+* one. A `hidden` argument is counted, because it still owns the name that it parses.
+*
+* @param args - The {@linkcode Args | arguments} of a command, global options included.
+* @param toKebab - Whether the command converts its names to kebab-case.
+* @returns The set of names.
+*/
+function resolveOptionNames(args, toKebab) {
+	const names = /* @__PURE__ */ new Set();
+	for (const [name, schema] of Object.entries(args)) if (schema.type !== "positional") names.add(resolveDisplayName(name, schema, toKebab));
+	return names;
+}
 //#endregion
 //#region src/localization.ts
 /**
@@ -313,15 +401,21 @@ function localizable(ctx, cmd, translate) {
 		if (key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key, key, values);
 		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
-			let argKey = key.slice(namaspacedArgKey.length);
-			let negatable = false;
+			const argKey = key.slice(namaspacedArgKey.length);
+			/**
+			* NOTE(kazupon): an argument describes itself, whatever it is called. `no-` is stripped only
+			* to reach the option that a negated form negates, and only when there is no argument under
+			* the name as written: `no-emoji` may be an argument of its own, and it then has nothing to do
+			* with `emoji`.
+			*/
+			const ownSchema = ctx.args[argKey];
+			if (ownSchema) return ownSchema.description || "";
 			if (argKey.startsWith("no-")) {
-				argKey = argKey.slice(3);
-				negatable = true;
+				const negatedKey = argKey.slice(3);
+				const schema = ctx.args[negatedKey];
+				if (schema && schema.type === "boolean" && schema.negatable) return `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, negatedKey, ctx.toKebab)}`;
 			}
-			const schema = ctx.args[argKey];
-			if (!schema) return argKey;
-			return negatable && schema.type === "boolean" && schema.negatable ? `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, argKey, ctx.toKebab)}` : schema.description || "";
+			return argKey;
 		}
 		if (key === resolveKey("description", ctx.name)) return "";
 		else if (key === resolveKey("examples", ctx.name)) return await resolveExamples(ctx, cmd.examples);
@@ -351,4 +445,4 @@ function formatResource(resource, values = Object.create(null)) {
 * @license MIT
 */
 //#endregion
-export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };
+export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "0.37.2",
+  "version": "1.0.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -55,8 +55,8 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "@gunshi/resources": "0.37.2",
-    "gunshi": "0.37.2"
+    "@gunshi/resources": "1.0.0-beta.0",
+    "gunshi": "1.0.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",