@clo4/cli 1.0.0 → 3.0.0

package/dist/index.d.ts

@@ -34,13 +34,22 @@ type CommandPath = readonly [Spec, ...Subcommand[]];
 interface OptionArgs {
   /** Escape hatch: the underlying map of option names to values. */
   readonly options: Map<string, string[]>;
-  /** Get every argument supplied to a option. */
+  /**
+   * Get every argument supplied to a option, or the defaults of its arguments
+   * if it wasn't supplied.
+   */
   all(name: string): string[] | undefined;
-  /** Get the first argument supplied to a option. */
+  /**
+   * Get the first argument supplied to a option, or the default of its first
+   * argument if it wasn't supplied.
+   */
   get(name: string): string | undefined;
-  /** Check whether a option was supplied. */
+  /** Check whether a option was supplied. Defaults don't count. */
   has(name: string): boolean;
-  /** Count option values, useful for repeatable options. */
+  /**
+   * Count option values, useful for repeatable options. It's 0 for an option
+   * that wasn't supplied, even if its arguments have defaults.
+   */
   count(name: string): number;
 }
 /** The data an action receives. */
@@ -62,7 +71,8 @@ interface ActionInit {
     /** Suggest the closest choice for an incorrect input. */
     didYouMean?: {
       input: string;
-      choices: readonly string[];
+      /** Names to suggest. The names in one array are one command or option. */
+      choices: readonly (string | readonly string[])[];
     };
     /** Alternative command path to render help for. */
     path?: NonEmptyArray<Subcommand>;
@@ -99,14 +109,31 @@ interface Subcommand {
     optionsMustPrecedeArguments?: boolean;
     /** Separators that can attach a option argument to a option token. */
     optionArgSeparators?: SingleOrArrayOrEmpty<string>;
-    /** Match subcommands by shortest unique prefix instead of exact name. */
+    /**
+     * Match subcommands by shortest unique prefix instead of exact name.
+     * Hidden subcommands still only match their exact name.
+     */
     subcommandsMatchUniquePrefix?: boolean;
   };
   /** Hide this command from help. */
   hidden?: true;
-  /** Require a subcommand; without one, print usage. */
+  /**
+   * Allow descendant commands to use this command as a subcommand too, like
+   * `{ ...helpCommand, isPersistent: true }`. There it only matches its exact
+   * name, a descendant's own subcommand with the same name wins, and help
+   * doesn't list it. Where a descendant takes positional arguments, its first
+   * argument can't be this command's name without `--` before it.
+   */
+  isPersistent?: true;
+  /**
+   * Require a subcommand, so the command takes no arguments. Without a
+   * subcommand, the command's action runs, or its help prints if it has none.
+   */
   requiresSubcommand?: true;
-  /** Action to run when this command is selected. */
+  /**
+   * Action to run when this command is selected. A command without an action
+   * prints its help.
+   */
   action?: Action;
   /**
    * This property never exists. It prevents accidental structural assignment
@@ -130,7 +157,12 @@ interface Option {
   hidden?: true;
   /** Only allow arguments to be supplied with a separator. */
   requiresSeparator?: true | string;
-  /** Allow this option to be supplied multiple times. */
+  /**
+   * Allow this option to be supplied multiple times. `true` allows any number
+   * of uses, and a number is the most uses allowed. An option with arguments
+   * collects the values from every use, in order. Without arguments, each use
+   * adds an empty string, so `count()` returns the number of uses.
+   */
   isRepeatable?: true | number;
   /** Require this option to be supplied before the selected action runs. */
   isRequired?: true;
@@ -176,9 +208,8 @@ interface Suggestion {
 /**
  * Generates dynamic completion suggestions.
  *
- * Generators run by re-invoking the CLI's hidden `completion
- * generate-suggestions` command, so `custom` executes in the CLI's own
- * process. Completions only — no effect on parsing.
+ * `custom` runs inside the CLI when the shell asks it for completions. It only
+ * affects completion and has no effect on parsing.
  */
 interface Generator {
   /** Produce suggestions from the current command-line tokens. */
@@ -188,12 +219,29 @@ interface Generator {
 interface Arg {
   /** Name shown in generated help. */
   name?: string;
-  /** Description for documentation or future help output. */
+  /**
+   * Description shown in help. A command's positional arguments are listed
+   * with their descriptions and defaults. An option argument's description
+   * isn't shown.
+   */
   description?: string;
   /** Allow this argument to take unlimited values. */
   isVariadic?: true;
   /** Allow this argument to be omitted. */
   isOptional?: true;
+  /**
+   * The value used when this argument is left out.
+   *
+   * - A positional argument's default is added to `args`, so the argument
+   *   must be optional.
+   * - An optional option argument's default is added when the option is used
+   *   without it, so a bare `--inspect` can mean `--inspect=9229`.
+   * - A required option argument's default is what `get` and `all` return
+   *   when the option isn't used. `has` and `count` still say it wasn't.
+   *
+   * Help shows an option's defaults after its description.
+   */
+  default?: string;
   /** Completions: complete file or folder paths for this argument. */
   template?: Template;
   /** Completions: static suggestions offered while typing this argument. */
@@ -202,22 +250,32 @@ interface Arg {
   generators?: SingleOrArray<Generator>;
 }
 /** Shells that {@link getCompletion} can generate scripts for. */
-type Shell = "bash" | "zsh" | "fish";
+type Shell = "bash" | "zsh" | "fish" | "powershell" | "nushell";
 /** A subcommand that prints a shell completion script for the whole CLI. */
 export declare const completion: Subcommand;
-/** A subcommand that prints help for its parent or a sibling command. */
+/**
+ * A subcommand that prints help for its parent, or for the command the names
+ * after it lead to from there, so `cli help a b` prints the help of `cli a b`.
+ * It reads names until one isn't a subcommand. A token where the command takes
+ * arguments, or where it has no subcommands, ends the names, so
+ * `cli help completion zsh` prints the help of `completion`. Any other token
+ * is an unknown command. Add `{ ...helpCommand, isPersistent: true }` instead
+ * to make `cli a b help` work too.
+ */
 export declare const helpCommand: Subcommand;
 /** A persistent help option that prints help for the selected command. */
 export declare const help: Option;
+/** Print `Error:` and the given values to stderr, separated by spaces. */
+export declare function printError(...strings: unknown[]): void;
 /**
  * Parse argv and execute the selected action.
  *
- * The final command action runs unless a parsed option has an action. Option
- * actions take precedence so helpers like `--help` can run without satisfying
- * the selected command's required arguments.
+ * The selected command's action runs unless a parsed option has an action.
+ * Option actions take precedence so helpers like `--help` can run without
+ * satisfying the selected command's required arguments. A command without an
+ * action prints its help.
  */
 export declare function run(spec: Spec, args?: readonly string[]): Promise<number>;
-export declare function printError(...strings: unknown[]): void;
 declare const _default: {
   completion: Subcommand;
   help: Option;