@gunshi/definition 1.0.0-rc.1 → 1.0.0-rc.2

package/lib/index.d.ts

@@ -1134,6 +1134,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * 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`.
    *
+   * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
+   * report them (see {@linkcode CliOptions.renderValidationErrors}).
+   *
    * @default false
    */
   usageSilent?: boolean;
@@ -1157,6 +1160,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   renderHeader?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
   /**
    * Render function the validation errors.
+   *
+   * With the global options plugin, the rendered message is printed to stderr, the exit code is set
+   * to `1`, {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
+   * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
+   * with the `AggregateError`. A renderer that returns an empty message, and
+   * {@linkcode CliOptions.usageSilent}, also leave them to the caller.
    */
   renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
   /**
@@ -1188,10 +1197,14 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    */
   onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
   /**
-   * Hook that runs when a command throws an error
+   * Hook that runs when a command throws an error, or when the arguments fail validation
+   *
+   * For the validation errors that the global options plugin has printed, the exit code is already `1`
+   * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
+   * error rejects `cli()` after the hook.
    *
    * @param ctx - The command context
-   * @param error - The error thrown during execution
+   * @param error - The error thrown during execution, or the `AggregateError` of the validation errors
    * @since v0.27.0
    */
   onErrorCommand?: (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>;
@@ -1360,9 +1373,11 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
   usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
   /**
    * Validation errors rendering configuration
-   * - `null`: Disable rendering
+   * - `null`: Disable rendering. `cli()` rejects with the validation errors, for the caller to report them
    * - `function`: Use custom renderer
    * - `undefined` (when omitted): Use default renderer
+   *
+   * See {@linkcode CliOptions.renderValidationErrors} for where the rendered message goes.
    */
   validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/definition",
   "description": "utilities for gunshi command definition",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -53,7 +53,7 @@
   },
   "devDependencies": {
     "deno": "^2.7.14",
-    "gunshi": "1.0.0-rc.1",
+    "gunshi": "1.0.0-rc.2",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",