@gunshi/plugin 0.37.3 → 1.0.0-beta.1

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,21 @@ 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 +102,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 +195,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 +241,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 +275,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 +299,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 +333,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 +396,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 +421,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 +471,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 +523,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 +543,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 +613,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 +625,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 +654,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,62 +682,85 @@ 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]> }> : {
+type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]>; }> : {
   [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
 };
 /**
  * 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.
  *
- * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
- * @typeParam V - Resolvable argument values.
- *
- * @internal
- */
-type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends (infer P) ? { [K in keyof P]: P[K] } : never;
-/**
- * Filters the arguments based on their default values.
+ * 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 Args | Arguments}, which is an object that defines the command line arguments.
+ * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
  * @typeParam V - Resolvable argument values.
- * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
  *
  * @internal
  */
-type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as K extends 'required' ? A[Arg][K] extends true ? Arg : never : A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+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;
 /**
- * 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 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 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 IsPresentArg<S extends ArgSchema> = S extends ArgSchema ? true extends (S['default'] extends {} ? true : S['required'] extends true ? true : false) ? true : IsRequiredPositionalArg<S> : never;
+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;
 /**
- * An arguments for {@link resolveArgs | resolve arguments}.
+ * 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 MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] extends [{
+  required: unknown;
+}] ? true : boolean | undefined extends A['required'] ? false : true : false;
 /**
  * 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 };
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean; };
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
 /**
@@ -710,12 +841,12 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
-type ProcessDependency<D, A extends ExtendContext> = D extends string ? D extends keyof A ? { [K in D]: A[K] } : {} : D extends {
+type ProcessDependency<D, A extends ExtendContext> = D extends string ? D extends keyof A ? { [K in D]: A[K]; } : {} : D extends {
   id: infer ID;
   optional?: any;
 } ? ID extends string ? ID extends keyof A ? D extends {
   optional: true;
-} ? { [K in ID]: A[K] | undefined } : { [K in ID]: A[K] } : {} : never : never;
+} ? { [K in ID]: A[K] | undefined; } : { [K in ID]: A[K]; } : {} : never : never;
 /**
  * Helper type to infer dependency extensions with optional support
  *
@@ -771,7 +902,7 @@ type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = Defau
  */
 type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
 type IsStringLiteral<S extends string> = string extends S ? false : true;
-type MergeExtension<Id, ResolvedDepExt extends ExtendContext, PluginExt extends ExtendContext> = Id extends infer I ? I extends string ? IsStringLiteral<I> extends true ? ResolvedDepExt & { [K in I]: PluginExt } : ResolvedDepExt : ResolvedDepExt : ResolvedDepExt;
+type MergeExtension<Id, ResolvedDepExt extends ExtendContext, PluginExt extends ExtendContext> = Id extends (infer I) ? I extends string ? IsStringLiteral<I> extends true ? ResolvedDepExt & { [K in I]: PluginExt; } : ResolvedDepExt : ResolvedDepExt : ResolvedDepExt;
 /**
  * Extensions resolved from the declared plugin dependencies.
  *
@@ -807,17 +938,15 @@ type MergedPluginParams<Id extends string, Deps extends ReadonlyArray<PluginDepe
  *
  * @since v0.27.0
  */
-interface PluginOptions<DepExt extends ExtendContext = DefaultGunshiParams['extensions'],
-// for plugin dependency extensions
-Id extends string = string,
-// for plugin id
-Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | string)[],
-// for plugin dependencies
-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>>>> {
+interface PluginOptions<DepExt extends ExtendContext = DefaultGunshiParams['extensions'] // for plugin dependency extensions
+, Id extends string = string // for plugin id
+, Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | string)[] // for plugin dependencies
+, 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;
   /**
@@ -916,15 +1045,11 @@ interface PluginWithoutExtension<E extends GunshiParams['extensions'] = DefaultG
  *
  * @since v0.27.0
  */
-declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'],
-// for plugin dependency extensions
-Id extends string = string,
-// for plugin id
-Deps extends ReadonlyArray<PluginDependency | string> = [],
-// for plugin dependencies
-Extension extends {} = {},
-// for plugin extension type
-ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
+declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'] // for plugin dependency extensions
+, Id extends string = string // for plugin id
+, Deps extends ReadonlyArray<PluginDependency | string> = [] // for plugin dependencies
+, Extension extends {} = {} // for plugin extension type
+, ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
@@ -945,15 +1070,11 @@ ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, Pl
  *
  * @since v0.27.0
  */
-declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'],
-// for plugin dependency extensions
-Id extends string = string,
-// for plugin id
-Deps extends ReadonlyArray<PluginDependency | string> = [],
-// for plugin dependencies
-Extension extends Record<string, unknown> = {},
-// for plugin extension type
-ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
+declare function plugin<Context extends ExtendContext = DefaultGunshiParams['extensions'] // for plugin dependency extensions
+, Id extends string = string // for plugin id
+, Deps extends ReadonlyArray<PluginDependency | string> = [] // for plugin dependencies
+, Extension extends Record<string, unknown> = {} // for plugin extension type
+, ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
@@ -973,7 +1094,7 @@ type Awaitable<T> = T | Promise<T>;
  *
  * @typeParam T - The type to be prettified.
  */
-type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type Prettify<T> = { [K in keyof T]: T[K]; } & {};
 /**
  * Extend command context type. This type is used to extend the command context with additional properties at {@linkcode CommandContext.extensions}.
  *
@@ -1149,7 +1270,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 +1293,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 +1391,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;
   /**
@@ -1696,7 +1847,7 @@ declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
  *
  * @internal
  */
-type ExtractExtensionValues<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+type ExtractExtensionValues<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never; };
 /**
  * Return type of {@link createCommandContext}
  *
@@ -1777,22 +1928,7 @@ interface CommandContextParams<G extends GunshiParams | {
  * @param param - A {@link CommandContextParams | parameters} to create a command context.
  * @returns A {@link CommandContext | command context}, which is readonly.
  */
-declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = {}>({
-  args,
-  explicit,
-  values,
-  positionals,
-  rest,
-  argv,
-  tokens,
-  command,
-  extensions,
-  cliOptions,
-  callMode,
-  commandPath,
-  omitted,
-  validationError
-}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
+declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = {}>({ args, explicit, values, positionals, rest, argv, tokens, command, extensions, cliOptions, callMode, commandPath, omitted, validationError }: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
 //#region ../gunshi/src/error.d.ts
 /**
@@ -1805,6 +1941,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 +1984,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 +2018,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 +2050,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}.
  *
@@ -1894,11 +2084,4 @@ declare function isArgsValidationError(error: unknown): error is ArgsValidationE
  */
 declare function hasPriorityValidationError(error: AggregateError | undefined): boolean;
 //#endregion
-//#region src/index.d.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
-//#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, type ArgsValidationErrorCode, ArgsValidationErrorKeys, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, CommandNotFoundError, type CommandNotFoundErrorCode, CommandNotFoundErrorKeys, type CommandNotFoundErrorOptions, CommandResolutionError, type CommandResolutionErrorCode, CommandResolutionErrorKeys, type CommandResolutionErrorOptions, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, 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.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -52,11 +52,11 @@
   },
   "devDependencies": {
     "deno": "^2.7.14",
+    "gunshi": "1.0.0-beta.1",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
-    "tsdown": "0.21.0",
-    "gunshi": "0.37.3"
+    "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",