@gunshi/definition 0.37.2 → 1.0.0-beta.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -42,20 +42,24 @@ interface ArgToken {
    */
   rawName?: string;
   /**
-   * Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
+   * Option value, e.g. `--foo=bar` => `bar`. The value of a short option, such as `bar` of
+   * `-x=bar`, `-1` of `-x=-1` or `-x-1`, and `''` of `-x=`, is in a token of its own after the
+   * option, which has no `name` and `rawName`.
    * If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
    */
-  value?: string;
+  value?: string | undefined;
   /**
-   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
+   * Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`, `-x-1` => `false`, since no `=`
+   * is written. Unlike Node.js `parseArgs`, `false` does not mean that the value is the next
+   * argument: the value token of `-x-1` has the `index` of that argument.
    */
-  inlineValue?: boolean;
+  inlineValue?: boolean | undefined;
 }
 /**
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.28.2/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -101,19 +105,25 @@ interface ArgSchema {
   /**
    * Type of the argument value.
    *
-   * - `'string'`: Text value (default if not specified)
-   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'string'`: Text value
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix). `--flag=true` and
+   *   `--flag=false` set the value explicitly; any other value after `=` is a type error
    * - `'number'`: Numeric value (parsed as integer or float)
-   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'enum'`: One of predefined string values (requires `choices` property, unless the argument
+   *   has a `parse` function)
    * - `'positional'`: Non-option argument by position
    * - `'custom'`: Custom parsing with user-defined `parse` function
    *
+   * Any other `type`, or no `type`, is a mistake that only untyped code can make: if the argument
+   * has no `parse` function, {@link resolveArgs} and `parse()` throw an `Error`, whether or not the
+   * argument is given.
+   *
    * @example
    * Different argument types:
    * ```ts
    * {
    *   name: { type: 'string' },        // --name value
-   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   verbose: { type: 'boolean' },     // --verbose (--no-verbose needs negatable: true)
    *   port: { type: 'number' },         // --port 3000
    *   level: { type: 'enum', choices: ['debug', 'info'] },
    *   file: { type: 'positional' },     // first positional arg
@@ -188,14 +198,32 @@ interface ArgSchema {
   /**
    * Marks the argument as required.
    *
-   * When `true`, the argument must be provided by the user.
-   * If missing, an `ArgResolveError` with type 'required' will be thrown.
-   *
-   * For single-value positional arguments, omitting `required` keeps the argument
-   * required for compatibility. Set `required: false` to make a positional argument
-   * optional. Optional positional arguments leave enough input values for later
+   * When `true`, the argument must be provided by the user. If it is missing, the error is an
+   * `ArgResolveError` with type 'required' and the code `err:arg:required-option`
+   * ({@link ArgsValidationErrorKeys}.requiredOption), or `err:arg:required-positional`
+   * ({@link ArgsValidationErrorKeys}.requiredPositional) for a positional argument. Its
+   * `values` has the `displayName` as in the message, such as `'--name'` for an option
+   * (`'--name' or '-n'` with the short name `n`) and `'file'` for a positional argument, and
+   * the `name`, which is the schema key.
+   * An option that is given without a value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue) instead, because the option itself was given.
+   * An explicit empty value, such as `--name=` or `-n ''`, is still reported as required, but the
+   * option counts as given: it is `true` in `explicit` and takes part in conflicts, as any other
+   * given option does.
+   *
+   * For single-value positional arguments, omitting `required` keeps the argument required for
+   * compatibility, unless it has a `default`, which makes it optional. A `multiple` positional
+   * argument is optional unless `required: true` is set. Set `required: false` to make a positional
+   * argument explicitly optional. Optional positional arguments leave enough input values for later
    * required positional arguments before consuming a value.
    *
+   * In the type of the values, such as {@link ArgValues}, a single-value positional argument whose
+   * `required` may be `false`, such as one of type `boolean`, is optional, as it may be missing,
+   * unless it has a `default`. An optional `required` of type `boolean`, as declared here, says
+   * nothing, and keeps it required. TypeScript widens a `required: true` to `boolean` in a schema
+   * written apart from the call, such as `{ type: 'positional' as const, required: true }`, which
+   * types the argument as optional: write such a schema `as const`.
+   *
    * @example
    * Required arguments:
    * ```ts
@@ -216,8 +244,9 @@ interface ArgSchema {
   /**
    * Allows the argument to accept multiple values.
    *
-   * When `true`, the resolved value becomes an array.
-   * For options: can be specified multiple times (--tag foo --tag bar)
+   * When `true`, the resolved value becomes an array. When the argument is not given and has no
+   * `default`, its value is `undefined`, not an empty array.
+   * For options: can be specified multiple times (--tags foo --tags bar)
    * For positional: collects remaining positional arguments after preserving values for
    * later required positional arguments.
    *
@@ -249,6 +278,12 @@ interface ArgSchema {
    *
    * Only applicable to `type: 'boolean'` arguments.
    *
+   * The negated name is always `no-` followed by the full option name. An option named
+   * `no-cache` is negated by `--no-no-cache`, and `--no-cache` sets it to `true`.
+   *
+   * The negated form does not take a value. `--no-flag=<value>` is reported as
+   * `err:arg:unexpected-value` ({@link ArgsValidationErrorKeys}.unexpectedValue).
+   *
    * @example
    * Negatable boolean:
    * ```ts
@@ -267,8 +302,17 @@ interface ArgSchema {
   /**
    * Array of allowed string values for enum-type arguments.
    *
-   * Required when `type: 'enum'`. The argument value must be one of these choices,
-   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   * Required when `type: 'enum'`, unless the argument has a `parse` function: if `choices` is
+   * missing or not an array, {@link resolveArgs} and `parse()` throw a `TypeError`, whether or not
+   * the argument is given. With a `parse` function and no `choices`, the value is passed to the
+   * function as for a `string` argument with a `parse` function.
+   *
+   * The argument value must be one of these choices, otherwise the error is an `ArgResolveError`
+   * with type 'type' and the code `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice).
+   *
+   * The value is checked before `parse` is called, so a `parse` function receives only one of
+   * these choices and can change it, for example to upper case.
    *
    * Supports both mutable arrays and readonly arrays for type safety.
    *
@@ -292,18 +336,37 @@ interface ArgSchema {
    */
   choices?: string[] | readonly string[];
   /**
-   * Default value used when the argument is not provided.
+   * Default value used when the argument is not provided. An option that is given without a value,
+   * or with a value that is rejected, also gets its default, along with the error.
    *
    * The type must match the argument's `type` property:
    * - `string` type: string default
    * - `boolean` type: boolean default
    * - `number` type: number default
-   * - `enum` type: must be one of the `choices` values
+   * - `enum` type: one of the `choices` values, or a value that a `parse` of your own returns
    * - `positional`/`custom` type: string, boolean, or number default
    *
-   * For single-value positional arguments, the default is used when the positional
-   * value is missing or when the value is preserved for later required positional
-   * arguments, unless `required: true` is set.
+   * The default is used as is and never goes through `parse`, including when an option is given
+   * without a value. An explicit empty value, such as `--name=` or `-n ''`, is a value, not a
+   * missing one: a `string` option without `parse` gets `''` instead of the default, unless it is
+   * `required`. What `parse` returns is a value too, even `undefined` or `null`, and the default
+   * does not replace it.
+   *
+   * The value of a `multiple` argument is an array, so its default becomes the only element of the
+   * array: `default: 'latest'` gives `['latest']`.
+   *
+   * The default of an `enum` option with `choices` is checked when it would be used, that is, when
+   * no value from the command line is used: one that is not one of the choices is reported as an
+   * `ArgResolveError` with type 'type' and the code `err:arg:invalid-default`
+   * ({@link ArgsValidationErrorKeys}.invalidDefault), and is not used. With a `parse` function of
+   * your own, or a `map()` transform, the default is a value that the function returns, which need
+   * not be one of the choices, and it is not checked. `choice()` returns the value as is, so its
+   * default is checked.
+   *
+   * For positional arguments, `multiple` ones included, the default is used when no value is left
+   * for the argument: when the positional values run out, or when the remaining ones are preserved
+   * for later required positional arguments. With `required: true`, the default is not used, and
+   * the argument is reported as required instead.
    *
    * @example
    * Default values by type:
@@ -336,7 +399,8 @@ interface ArgSchema {
    * When `true`, a property like `maxCount` becomes available as `--max-count`.
    * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
    *
-   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   * The `toKebab` option of {@link resolveArgs} and `parse()` applies it to all arguments, as in
+   * `resolveArgs(args, tokens, { toKebab: true })`.
    *
    * Note: Only `true` is allowed (not `false`) to make intent explicit.
    *
@@ -360,8 +424,19 @@ interface ArgSchema {
   /**
    * Names of other options that conflict with this option.
    *
-   * When this option is used together with any of the conflicting options,
-   * an `ArgResolveError` with type 'conflict' will be thrown.
+   * When this option is used together with any of the conflicting options, the error is an
+   * `ArgResolveError` with type 'conflict' and the code `err:arg:conflict`
+   * ({@link ArgsValidationErrorKeys}.conflict). Its `values` has the `displayName` and `name` of
+   * the argument whose `conflicts` names the other one, and the `conflictDisplayName` and
+   * `conflictName` of the other one. `displayName` and `conflictDisplayName` show an option as
+   * it was written, such as `'-p'`, and `name` and `conflictName` are the schema keys. When both
+   * name each other, `name` is the one that comes first in the schema.
+   *
+   * A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when
+   * it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as
+   * in its other errors. The message starts with the kind of the argument given as `name`:
+   * `Positional argument 'file' conflicts with '--stdin'` or
+   * `Optional argument '--stdin' conflicts with 'file'`.
    *
    * Conflicts only need to be defined on one side - if option A defines a conflict
    * with option B, the conflict is automatically detected when both are used,
@@ -399,7 +474,7 @@ interface ArgSchema {
    *     // No conflicts defined, but still cannot use with --summer
    *   }
    * }
-   * // Usage: --summer --autumn will throw error
+   * // Usage: --summer --autumn reports an error
    * // Error: "Optional argument '--summer' conflicts with '--autumn'"
    * ```
    *
@@ -451,6 +526,10 @@ interface ArgSchema {
    * Particularly useful for `type: 'custom'` arguments where the type
    * name would otherwise be unhelpful.
    *
+   * For a `custom` option that is given without a value, it is also the `expected` in the `values`
+   * of the `err:arg:missing-value` error ({@link ArgsValidationErrorKeys}.missingValue), which is
+   * `'custom'` without it.
+   *
    * @example
    * Metavar usage:
    * ```ts
@@ -467,13 +546,37 @@ interface ArgSchema {
    */
   metavar?: string;
   /**
-   * Custom parsing function for `type: 'custom'` arguments.
+   * Custom parsing function, used in place of the parsing of the argument's `type`.
    *
-   * Required when `type: 'custom'`. Receives the raw string value and must
-   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   * Required when `type: 'custom'`: if it is missing or not a function, {@link resolveArgs} and
+   * `parse()` throw a `TypeError`, whether or not the argument is given. The function receives the
+   * raw string value and must return the parsed result. It should throw an Error (or subclass) if
+   * parsing fails.
    *
    * The function's return type becomes the resolved argument type.
    *
+   * `parse` is called synchronously, and what it returns becomes the value, even `undefined` or
+   * `null`, so throw to reject a value. An `async` function returns a promise, and the promise
+   * becomes the value as is: it is not awaited, and its rejection is not reported as an error.
+   * Await the value, or each of its elements with `multiple` (for example with `Promise.all()`),
+   * and handle the rejection yourself: a rejection that nothing handles is an unhandled rejection,
+   * which ends a Node.js process by default.
+   *
+   * A `boolean` option calls `parse` with `'true'`, or `'false'` for the negated form. Other
+   * options call it only with a value from the command line: when the option is given without a
+   * value, `parse` is not called and the missing value is reported as `err:arg:missing-value`
+   * ({@link ArgsValidationErrorKeys}.missingValue). When that error may suggest the argument after
+   * the option as its value, such as `--port=-5` for `--port -5`, a `parse` function of your own
+   * is not called to check it either: only the `parse` functions of `string()`, `number()`,
+   * `integer()`, `float()` and `choice()`, which have no side effects, are called for that.
+   * An explicit empty value, such as `--name=` or `-n=`, is passed as `''` unless
+   * `required: true` is set.
+   *
+   * An `enum` option with `choices` calls it only with one of them. Any other value, an explicit
+   * empty one included, is reported as `err:arg:invalid-choice`
+   * ({@link ArgsValidationErrorKeys}.invalidChoice), except that a required option reports an
+   * explicit empty value as required.
+   *
    * @param value - Raw string value from command line
    * @returns Parsed value of any type
    * @throws {Error} Error or subclass when value is invalid
@@ -508,13 +611,6 @@ interface ArgSchema {
    */
   parse?: (value: string) => any;
 }
-/**
- * Machine-readable error codes for {@link ArgsValidationError}.
- *
- * Each code identifies a validation failure category and is also suitable as an
- * i18n resource key for localized rendering.
- */
-
 /**
  * An object that contains {@link ArgSchema | argument schema}.
  *
@@ -526,6 +622,20 @@ interface Args {
 /**
  * An object that contains the values of the arguments.
  *
+ * The value of an argument whose schema is a union, such as
+ * `strict ? multiple(integer()) : string()` with the combinators, is typed as a value of any of its
+ * schemas: `number[] | string`. The argument is typed as present only when each schema of the
+ * union gives it a value, with a default, with `required: true` or as a required positional
+ * argument.
+ *
+ * When the type of one schema covers that of the other, as the type of `integer()` covers that of
+ * `multiple(integer())`, TypeScript types a `?:` expression of them as the covering schema alone:
+ * the value of `strict ? multiple(integer()) : integer()` is typed without the array, and
+ * `strict ? multiple(positional()) : positional()` as present, although it may be missing. Give
+ * each schema its own argument instead, or give the expression the type of both schemas with `as`,
+ * as in `(strict ? many : one) as typeof many | typeof one` for `const many = multiple(integer())`
+ * and `const one = integer()`.
+ *
  * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
  */
 type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
@@ -533,22 +643,41 @@ type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: Ext
 };
 /**
  * Extracts the value type from the argument schema.
+ * For a union of schemas, it is the union of the value types of its schemas.
  *
  * @typeParam A - {@link ArgSchema | Argument schema} which is an object that defines command line arguments.
  *
  * @internal
  */
-type ExtractOptionValue<A extends ArgSchema> = undefined extends A['parse'] ? A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? never : ResolveOptionValue<A, string | boolean | number> : A['parse'] extends ((value: string) => infer R) ? ResolveOptionValue<A, R> : never;
+type ExtractOptionValue<A extends ArgSchema> = A extends ArgSchema ? ExtractSchemaValue<A> : never;
+/**
+ * The value type of one schema, which {@link ExtractOptionValue} takes for each schema of a union.
+ */
+type ExtractSchemaValue<A extends ArgSchema> = undefined extends A['parse'] ? A['type'] extends 'string' ? ResolveOptionValue<A, string> : A['type'] extends 'boolean' ? ResolveOptionValue<A, boolean> : A['type'] extends 'number' ? ResolveOptionValue<A, number> : A['type'] extends 'positional' ? ResolveOptionValue<A, string> : A['type'] extends 'enum' ? A['choices'] extends string[] | readonly string[] ? ResolveOptionValue<A, A['choices'][number]> : never : A['type'] extends 'custom' ? never : ResolveOptionValue<A, string | boolean | number> : A['parse'] extends ((value: string) => infer R) ? ResolveOptionValue<A, R> : never;
 type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T[] : T;
 /**
  * Resolved argument values.
  *
+ * Each argument is mapped as optional, and the ones that are present, as {@link IsPresentArg}
+ * says, are mapped again as present. The optional mapping types a present argument as `unknown`:
+ * TypeScript does not reduce an intersection such as
+ * `(string | number[] | undefined) & (string | number[])`, of a value type that is a union with an
+ * object type. It maps all the keys without renaming them, which lets TypeScript relate the values
+ * of related type parameters, so that a conversion such as `values as ArgValues<A>` compiles.
+ *
  * @typeParam A - {@link Arguments | Args} which is an object that defines the command line arguments.
  * @typeParam V - Resolvable argument values.
  *
  * @internal
  */
-type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, 'default'> & FilterArgs<A, V, 'required'> & FilterPositionalArgs<A, V> extends (infer P) ? { [K in keyof P]: P[K] } : never;
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: IsPresentArg<A[Arg]> extends true ? unknown : V[Arg] } & { -readonly [Arg in keyof A as IsPresentArg<A[Arg]> extends true ? Arg : never]: V[Arg] } extends (infer P) ? { [K in keyof P]: P[K] } : never;
+/**
+ * Whether an argument with the schema `S` has a value: with a default, with `required: true` or as
+ * a required positional argument. For a union of schemas, only when each schema of the union has
+ * one. A `default` or `required` typed as `any`, and a schema typed as `any`, count as giving a
+ * value, as {@link FilterArgs} does.
+ */
+type IsPresentArg<S extends ArgSchema> = S extends ArgSchema ? true extends (S['default'] extends {} ? true : S['required'] extends true ? true : false) ? true : IsRequiredPositionalArg<S> : never;
 /**
  * Filters the arguments based on their default values.
  *
@@ -558,17 +687,17 @@ type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -r
  *
  * @internal
  */
-type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as K extends 'required' ? A[Arg][K] extends true ? Arg : never : A[Arg][K] extends {} ? Arg : never]: V[Arg] };
+
+type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : MayBeUnrequired<A> extends true ? A['default'] extends {} ? true : false : true : false;
 /**
- * Filters positional arguments from the argument schema.
- *
- * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
- * @typeParam V - Resolvable argument values.
- *
- * @internal
+ * Whether the `required` of `A` may be `false`. An optional `required` of type `boolean`, as in
+ * {@link ArgSchema}, says nothing, and is read as missing, so that a positional argument with it is
+ * required. A `required` that `A` always has may be `false` when its type is `boolean` or
+ * `boolean | undefined`.
  */
-type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as IsRequiredPositionalArg<A[Arg]> extends true ? Arg : never]: V[Arg] };
-type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : A['required'] extends false ? A['default'] extends {} ? true : false : true : false;
+type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] extends [{
+  required: unknown;
+}] ? true : boolean | undefined extends A['required'] ? false : true : false;
 /**
  * An arguments for {@link resolveArgs | resolve arguments}.
  */
@@ -576,44 +705,16 @@ type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positiona
 /**
  * Tracks which arguments were explicitly provided by the user.
  *
- * Each property indicates whether the corresponding argument was explicitly
- * provided (true) or is using a default value or not provided (false).
+ * Each property is `true` when the argument is given on the command line, and `false` when it is
+ * not, whether it has a default or not. An option is given when one of its forms is, such as
+ * `--port`, `-p` or `--no-color`, even if its value is missing or rejected: the error is reported,
+ * and if no value from the command line is used, its default, if any, fills in the value. A
+ * positional argument is given when a positional value is used for it, even if `parse` rejects
+ * the value: the error is reported, and its default is not used.
  *
  * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
  */
 type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
-/**
- * Resolve command line arguments.
- *
- * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
- *
- * @param args - An arguments that contains {@link ArgSchema | arguments schema}.
- * @param tokens - An array of {@link ArgToken | tokens}.
- * @param resolveArgs - An arguments that contains {@link ResolveArgs | resolve arguments}.
- * @returns An object that contains the values of the arguments, positional arguments, rest arguments, {@link AggregateError | validation errors}, and explicit provision status.
- *
- * @example
- * ```typescript
- * // passed tokens: --port 3000
- *
- * const { values, explicit } = resolveArgs({
- *   port: {
- *     type: 'number',
- *     default: 8080
- *   },
- *   host: {
- *     type: 'string',
- *     default: 'localhost'
- *   }
- * }, parsedTokens)
- *
- * values.port // 3000
- * values.host // 'localhost'
- *
- * explicit.port // true (explicitly provided)
- * explicit.host // false (not provided, fallback to default)
- * ```
- */
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
 /**
@@ -923,7 +1024,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}
@@ -942,6 +1047,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.
    */
@@ -1020,7 +1145,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;
   /**
@@ -1682,7 +1813,8 @@ declare function lazy<A extends Args>(loader: CommandLoader<{
  * @typeParam D - A partial {@link Command} definition type with required `args`
  *
  * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
- * @param definition - A {@link Command | command} definition
+ * @param definition - A {@link Command | command} definition. Its `name` may be omitted,
+ *   including when the lazy command is used as the CLI entry command.
  * @returns A {@link LazyCommand | lazy command} that can be executed later
  */
 declare function lazy<D extends {
@@ -1704,7 +1836,8 @@ declare function lazy<D extends {
  * @typeParam D - A partial {@link Command} definition type
  *
  * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
- * @param definition - An optional {@link Command | command} definition
+ * @param definition - An optional {@link Command | command} definition. Its `name` may be omitted,
+ *   including when the lazy command is used as the CLI entry command.
  * @returns A {@link LazyCommand | lazy command} that can be executed later
  */
 declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = Partial<Command<G>>>(loader: CommandLoader<G>, definition?: D): LazyCommand<G, D>;

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)";
@@ -217,11 +220,14 @@ function defineWithTypes() {
 * Define a {@link LazyCommand | lazy command} with or without definition.
 *
 * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
-* @param definition - An optional {@link Command | command} definition
+* @param definition - An optional {@link Command | command} definition. Its `name` may be omitted,
+*   including when the lazy command is used as the CLI entry command.
 * @returns A {@link LazyCommand | lazy command} that can be executed later
 */
 function lazy(loader, definition) {
-	const lazyCommand = loader;
+	let lazyCommand = loader;
+	if ((definition != null || !("commandName" in lazyCommand)) && !Object.isExtensible(lazyCommand)) lazyCommand = Object.assign(() => loader(), loader);
+	if (definition == null && !("commandName" in lazyCommand)) lazyCommand.commandName = void 0;
 	if (definition != null) {
 		lazyCommand.commandName = definition.name;
 		lazyCommand.description = definition.description;
@@ -230,6 +236,7 @@ function lazy(loader, definition) {
 		lazyCommand.internal = definition.internal;
 		lazyCommand.entry = definition.entry;
 		lazyCommand.toKebab = definition.toKebab;
+		lazyCommand.rendering = definition.rendering;
 		if (definition.subCommands) lazyCommand.subCommands = definition.subCommands;
 		if ("resource" in definition) lazyCommand.resource = definition.resource;
 	}

package/package.json

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