@gunshi/plugin 1.0.0-beta.2 → 1.0.0-rc.2

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -56,7 +56,7 @@ interface ArgToken {
   inlineValue?: boolean | undefined;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -1397,6 +1397,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;
@@ -1420,6 +1423,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;
   /**
@@ -1451,10 +1460,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>;
@@ -1623,9 +1636,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/lib/index.js

@@ -176,7 +176,7 @@ function getCommandName(cmd) {
 "-".codePointAt(0);
 "=".codePointAt(0);
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -285,7 +285,7 @@ function isArgsValidationError$1(error) {
 	return typeof values === "object" && values !== null;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/index.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT

package/package.json

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