@gunshi/plugin 1.0.0-rc.1 → 1.0.0-rc.3

package/lib/index.d.ts

@@ -1297,7 +1297,8 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    * 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}.
+   * includes the entry command only when the CLI has sub-commands, given with {@linkcode CliOptions.subCommands}
+   * or with {@linkcode Command.subCommands} of the entry command.
    * It is not frozen, like the commands in {@linkcode CommandEnvironment.subCommands}.
    */
   entryCommand?: Command<any> | LazyCommand<any>;
@@ -1372,8 +1373,11 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   version?: string;
   /**
    * Sub commands.
+   *
+   * An object or a Map keyed by the sub-command names, or an array of commands, which are keyed by their names.
+   * When this is not given, the {@linkcode Command.subCommands} of the entry command are the sub-commands.
    */
-  subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable>;
+  subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
   /**
    * Left margin of the command output.
    */
@@ -1397,6 +1401,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 +1427,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 +1464,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 +1640,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;
 }
@@ -1690,10 +1709,13 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    *
    * Allows building command trees like `git remote add`.
    * Each key is the sub-command name, and the value is a command or lazy command.
+   * An array of commands is keyed by the names of the commands.
+   *
+   * On the entry command, these are the top-level sub-commands when {@linkcode CliOptions.subCommands} is not given.
    *
    * @since v0.28.0
    */
-  subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable>;
+  subCommands?: Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[];
 }
 /**
  * Lazy command interface.
@@ -1770,7 +1792,7 @@ interface SubCommandable {
    * @see {@link Command.subCommands}
    * @since v0.28.0
    */
-  subCommands?: Record<string, any> | Map<string, any>;
+  subCommands?: Record<string, any> | Map<string, any> | readonly any[];
   /**
    * Index signature to allow additional properties
    */

package/package.json

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