@gunshi/plugin 0.37.3 → 1.0.0-beta.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.29.0/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.29.0/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
@@ -513,6 +616,10 @@ interface ArgSchema {
  *
  * Each code identifies a validation failure category and is also suitable as an
  * i18n resource key for localized rendering.
+ *
+ * {@link resolveArgs} and `parse()` do not report `unknownOption`. An option that is not in the
+ * schema takes the argument after it as its value, unless that argument is an option, and the value
+ * is dropped: with no `foo` in the schema, `--foo bar` gives no positional argument.
  */
 declare const ArgsValidationErrorKeys: {
   readonly requiredOption: 'err:arg:required-option';
@@ -521,6 +628,10 @@ declare const ArgsValidationErrorKeys: {
   readonly invalidChoice: 'err:arg:invalid-choice';
   readonly customParse: 'err:arg:custom-parse';
   readonly unknownOption: 'err:arg:unknown-option';
+  readonly unexpectedValue: 'err:arg:unexpected-value';
+  readonly missingValue: 'err:arg:missing-value';
+  readonly conflict: 'err:arg:conflict';
+  readonly invalidDefault: 'err:arg:invalid-default';
 };
 /**
  * A machine-readable argument validation error code.
@@ -546,7 +657,7 @@ declare class ArgsValidationError extends Error {
    *
    * This code can also be used as an i18n resource key.
    */
-  readonly code?: ArgsValidationErrorCode;
+  readonly code?: ArgsValidationErrorCode | undefined;
   /**
    * Interpolation values for `code`.
    */
@@ -574,6 +685,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]> }> : {
@@ -581,22 +706,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.
  *
@@ -606,17 +750,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}.
  */
@@ -624,8 +768,12 @@ 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.
  */
@@ -817,7 +965,9 @@ Ext extends Record<string, unknown> = {},
 // for plugin extension type
 ResolvedDepExt extends GunshiParams = DependencyParams<Deps, DepExt>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = MergedPluginParams<Id, Deps, DepExt, Awaited<ReturnType<PluginExt>>>> {
   /**
-   * Plugin unique identifier
+   * Plugin unique identifier.
+   *
+   * Must be a non-empty string. {@linkcode plugin} and the installer both reject an empty id.
    */
   id: Id;
   /**
@@ -1149,7 +1299,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}
@@ -1168,6 +1322,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.
    */
@@ -1246,7 +1420,13 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    */
   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
    */
   usageSilent?: boolean;
   /**
@@ -1805,6 +1985,20 @@ declare const CommandNotFoundErrorKeys: {
  * Command not found error code.
  */
 type CommandNotFoundErrorCode = (typeof CommandNotFoundErrorKeys)[keyof typeof CommandNotFoundErrorKeys];
+/**
+ * Command resolution error resource keys.
+ *
+ * These errors describe an ambiguity or inconsistency while choosing a command from arguments.
+ * They are kept separate from {@link CommandNotFoundError} so consumers can distinguish a typo
+ * from an input whose command interpretation is not unique.
+ */
+declare const CommandResolutionErrorKeys: {
+  readonly ambiguous: "err:cmd:ambiguous";
+  readonly inconsistentOptions: "err:cmd:inconsistent-options";
+  readonly lazySchemaMismatch: "err:cmd:lazy-schema-mismatch";
+};
+/** Command resolution error code. */
+type CommandResolutionErrorCode = (typeof CommandResolutionErrorKeys)[keyof typeof CommandResolutionErrorKeys];
 /**
  * Options for {@link CommandNotFoundError}.
  */
@@ -1834,6 +2028,19 @@ type CommandNotFoundErrorOptions = {
    */
   cause?: unknown;
 };
+/** Options for {@link CommandResolutionError}. */
+type CommandResolutionErrorOptions = {
+  /** Localization resource key for the resolution failure. */
+  code?: CommandResolutionErrorCode;
+  /** Values used when localizing the message. */
+  values?: Record<string, unknown>;
+  /** Command path at which the resolution failed. */
+  commandPath?: readonly string[];
+  /** Candidate command paths considered by the resolver. */
+  candidatePaths?: readonly (readonly string[])[];
+  /** Underlying cause. */
+  cause?: unknown;
+};
 /**
  * Error raised when a command cannot be resolved.
  *
@@ -1855,6 +2062,26 @@ declare class CommandNotFoundError extends Error {
    */
   constructor(message: string, options: CommandNotFoundErrorOptions);
 }
+/**
+ * Error raised when command routing cannot produce one consistent command.
+ *
+ * The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
+ * guard, the new guard deliberately has no name-based fallback because this error type is new and
+ * must not classify arbitrary errors from older versions.
+ */
+declare class CommandResolutionError extends Error {
+  readonly code?: CommandResolutionErrorCode;
+  readonly values: Record<string, unknown>;
+  readonly commandPath: readonly string[];
+  readonly candidatePaths: readonly (readonly string[])[];
+  /**
+   * Create a command resolution error with structured routing metadata.
+   *
+   * @param message - Human-readable fallback message
+   * @param options - Error code and command-routing metadata
+   */
+  constructor(message: string, options?: CommandResolutionErrorOptions);
+}
 /**
  * Check whether an error is a {@link CommandNotFoundError}.
  *
@@ -1867,6 +2094,13 @@ declare class CommandNotFoundError extends Error {
  * @returns `true` if the error is a {@link CommandNotFoundError}
  */
 declare function isCommandNotFoundError(error: unknown): error is CommandNotFoundError;
+/**
+ * Check whether an error is a {@link CommandResolutionError}.
+ *
+ * @param error - An unknown error
+ * @returns `true` when the error has the command-resolution brand and shape
+ */
+declare function isCommandResolutionError(error: unknown): error is CommandResolutionError;
 /**
  * Check whether an error is an {@link ArgsValidationError}.
  *
@@ -1901,4 +2135,4 @@ declare function hasPriorityValidationError(error: AggregateError | undefined):
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, ArgsValidationErrorCode, ArgsValidationErrorKeys, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandNotFoundError, CommandNotFoundErrorCode, CommandNotFoundErrorKeys, CommandNotFoundErrorOptions, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, ArgsValidationErrorCode, ArgsValidationErrorKeys, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandNotFoundError, CommandNotFoundErrorCode, CommandNotFoundErrorKeys, CommandNotFoundErrorOptions, CommandResolutionError, CommandResolutionErrorCode, CommandResolutionErrorKeys, CommandResolutionErrorOptions, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };

package/lib/index.js

@@ -36,10 +36,13 @@ const CLI_OPTIONS_DEFAULT = {
 * 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;
 }
 /**
 * Create an object with the specified prototype. A shorthand for `Object.create`.
@@ -155,7 +158,7 @@ async function createCommandContext({ args = {}, explicit = {}, values = {}, pos
 			if (extension.onFactory) await extension.onFactory(core, command);
 		}
 	}
-	return deepFreeze(core, ["extensions"]);
+	return deepFreeze(core, ["extensions", "entryCommand"]);
 }
 function getCommandName(cmd) {
 	if (isLazyCommand(cmd)) return cmd.commandName || cmd.name || "(anonymous)";
@@ -173,7 +176,11 @@ function getCommandName(cmd) {
 "-".codePointAt(0);
 "=".codePointAt(0);
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/resolver.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 /**
 * Entry point of argument options resolver.
 *
@@ -188,6 +195,10 @@ function getCommandName(cmd) {
 *
 * Each code identifies a validation failure category and is also suitable as an
 * i18n resource key for localized rendering.
+*
+* {@link resolveArgs} and `parse()` do not report `unknownOption`. An option that is not in the
+* schema takes the argument after it as its value, unless that argument is an option, and the value
+* is dropped: with no `foo` in the schema, `--foo bar` gives no positional argument.
 */
 const ArgsValidationErrorKeys = {
 	requiredOption: "err:arg:required-option",
@@ -195,7 +206,11 @@ const ArgsValidationErrorKeys = {
 	invalidType: "err:arg:invalid-type",
 	invalidChoice: "err:arg:invalid-choice",
 	customParse: "err:arg:custom-parse",
-	unknownOption: "err:arg:unknown-option"
+	unknownOption: "err:arg:unknown-option",
+	unexpectedValue: "err:arg:unexpected-value",
+	missingValue: "err:arg:missing-value",
+	conflict: "err:arg:conflict",
+	invalidDefault: "err:arg:invalid-default"
 };
 /**
 * Brand that marks {@link ArgsValidationError} instances.
@@ -270,7 +285,7 @@ function isArgsValidationError$1(error) {
 	return typeof values === "object" && values !== null;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.29.0/node_modules/args-tokens/lib/index.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -290,6 +305,18 @@ function isArgsValidationError$1(error) {
 */
 const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
 /**
+* Command resolution error resource keys.
+*
+* These errors describe an ambiguity or inconsistency while choosing a command from arguments.
+* They are kept separate from {@link CommandNotFoundError} so consumers can distinguish a typo
+* from an input whose command interpretation is not unique.
+*/
+const CommandResolutionErrorKeys = {
+	ambiguous: "err:cmd:ambiguous",
+	inconsistentOptions: "err:cmd:inconsistent-options",
+	lazySchemaMismatch: "err:cmd:lazy-schema-mismatch"
+};
+/**
 * Brand that marks {@link CommandNotFoundError} instances.
 *
 * The brand is looked up in the global symbol registry with `Symbol.for`, so it stays
@@ -298,6 +325,7 @@ const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
 * another copy, where `instanceof` cannot match.
 */
 const COMMAND_NOT_FOUND_ERROR_BRAND = Symbol.for("gunshi.CommandNotFoundError");
+const COMMAND_RESOLUTION_ERROR_BRAND = Symbol.for("gunshi.CommandResolutionError");
 /**
 * Error raised when a command cannot be resolved.
 *
@@ -334,6 +362,39 @@ var CommandNotFoundError = class extends Error {
 	}
 };
 /**
+* Error raised when command routing cannot produce one consistent command.
+*
+* The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
+* guard, the new guard deliberately has no name-based fallback because this error type is new and
+* must not classify arbitrary errors from older versions.
+*/
+var CommandResolutionError = class extends Error {
+	code;
+	values;
+	commandPath;
+	candidatePaths;
+	/**
+	* Create a command resolution error with structured routing metadata.
+	*
+	* @param message - Human-readable fallback message
+	* @param options - Error code and command-routing metadata
+	*/
+	constructor(message, options = {}) {
+		super(message, { cause: options.cause });
+		this.name = "CommandResolutionError";
+		this.code = options.code;
+		this.values = options.values || {};
+		this.commandPath = options.commandPath || [];
+		this.candidatePaths = options.candidatePaths || [];
+		Object.defineProperty(this, COMMAND_RESOLUTION_ERROR_BRAND, {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		});
+	}
+};
+/**
 * Check whether an error is a {@link CommandNotFoundError}.
 *
 * `instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
@@ -351,6 +412,17 @@ function isCommandNotFoundError(error) {
 	return error instanceof Error && error.name === "CommandNotFoundError";
 }
 /**
+* Check whether an error is a {@link CommandResolutionError}.
+*
+* @param error - An unknown error
+* @returns `true` when the error has the command-resolution brand and shape
+*/
+function isCommandResolutionError(error) {
+	if (error instanceof CommandResolutionError) return true;
+	if (!isRecord(error) || !hasCommandResolutionErrorShape(error)) return false;
+	return Object.hasOwn(error, COMMAND_RESOLUTION_ERROR_BRAND) && error[COMMAND_RESOLUTION_ERROR_BRAND] === true;
+}
+/**
 * Check whether an error is an {@link ArgsValidationError}.
 *
 * Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
@@ -394,6 +466,9 @@ function hasOptionalStringCode(error) {
 function hasCommandNotFoundErrorShape(error) {
 	return hasOptionalStringCode(error) && isRecord(error.values) && typeof error.commandName === "string" && isStringArray(error.candidates) && isStringArray(error.commandPath);
 }
+function hasCommandResolutionErrorShape(error) {
+	return hasOptionalStringCode(error) && isRecord(error.values) && isStringArray(error.commandPath) && Array.isArray(error.candidatePaths) && error.candidatePaths.every((path) => isStringArray(path));
+}
 function hasArgsValidationErrorShape(error) {
 	return hasOptionalStringCode(error) && isRecord(error.values);
 }
@@ -404,7 +479,7 @@ function hasArgsValidationErrorShape(error) {
 * @returns `true` if the validation error must be handled with priority
 */
 function hasPriorityValidationError(error) {
-	return error?.errors.some((error) => isCommandNotFoundError(error) || isArgsValidationError(error) && error.code === ArgsValidationErrorKeys.unknownOption) ?? false;
+	return error?.errors.some((error) => isCommandNotFoundError(error) || isCommandResolutionError(error) || isArgsValidationError(error) && error.code === ArgsValidationErrorKeys.unknownOption) ?? false;
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.ts
@@ -425,6 +500,7 @@ const NOOP_EXTENSION = () => {
 */
 function plugin(options = {}) {
 	const { id, name, setup, onExtension, dependencies } = options;
+	if (typeof id !== "string" || id.length === 0) throw new Error("Plugin id must be a non-empty string");
 	const extension = options.extension || NOOP_EXTENSION;
 	const pluginFn = async (ctx) => {
 		if (setup) await setup(ctx);
@@ -470,4 +546,4 @@ function plugin(options = {}) {
 * @license MIT
 */
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandNotFoundError, CommandNotFoundErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, plugin };
+export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandNotFoundError, CommandNotFoundErrorKeys, CommandResolutionError, CommandResolutionErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "0.37.3",
+  "version": "1.0.0-beta.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,7 +56,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "gunshi": "0.37.3"
+    "gunshi": "1.0.0-beta.0"
   },
   "scripts": {
     "build": "tsdown",