clerc 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/index.d.ts

@@ -2,6 +2,21 @@ import { Plugin } from "@clerc/core";
 export * from "@clerc/core";
 
 //#region ../plugin-completions/src/index.d.ts
+declare module "@clerc/core" {
+  interface CommandCustomOptions {
+    /**
+    * Completions options for the command.
+    */
+    completions?: {
+      /**
+      * Whether to show the command in completions output.
+      *
+      * @default true
+      */
+      show?: boolean;
+    };
+  }
+}
 interface CompletionsPluginOptions {
   /**
   * Whether to register the `completions install` and `completions uninstall` commands.
@@ -25,35 +40,131 @@ declare const friendlyErrorPlugin: ({
 *
 * @template T The target type.
 */
-type FlagTypeFunction<T = unknown> = (value: string) => T;
+type FlagTypeFunction<T = unknown> = ((value: string) => T) & {
+  /**
+  * Optional display name for the type, useful in help output.
+  * If provided, this will be shown instead of the function name.
+  */
+  displayName?: string;
+};
 type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
 //#endregion
 //#region ../plugin-help/src/types.d.ts
 interface Formatters {
   formatFlagType: (type: FlagType) => string;
 }
+/**
+* A group definition as a tuple of [key, displayName].
+* The key is used in help options to assign items to groups.
+* The displayName is shown in the help output.
+*/
+type GroupDefinition = [key: string, name: string];
+/**
+* Options for defining groups in help output.
+*/
+interface GroupsOptions {
+  /**
+  * Groups for commands.
+  * Each group is defined as `[key, name]`.
+  */
+  commands?: GroupDefinition[];
+  /**
+  * Groups for command-specific flags.
+  * Each group is defined as `[key, name]`.
+  */
+  flags?: GroupDefinition[];
+  /**
+  * Groups for global flags.
+  * Each group is defined as `[key, name]`.
+  */
+  globalFlags?: GroupDefinition[];
+}
 //#endregion
 //#region ../plugin-help/src/formatters.d.ts
 declare const defaultFormatters: Formatters;
 //#endregion
 //#region ../plugin-help/src/index.d.ts
+interface HelpOptions {
+  /**
+  * The group this item belongs to.
+  * The group must be defined in the `groups` option of `helpPlugin()`.
+  */
+  group?: string;
+}
+interface CommandHelpOptions extends HelpOptions {
+  /**
+  * Whether to show the command in help output.
+  *
+  * @default true
+  */
+  show?: boolean;
+  /**
+  * Notes to show in the help output.
+  */
+  notes?: string[];
+  /**
+  * Examples to show in the help output.
+  * Each example is a tuple of `[command, description]`.
+  */
+  examples?: [string, string][];
+}
 declare module "@clerc/core" {
   interface CommandCustomOptions {
-    help?: {
-      showInHelp?: boolean;
-      notes?: string[];
-      examples?: [string, string][];
-    };
+    /**
+    * Help options for the command.
+    */
+    help?: CommandHelpOptions;
+  }
+  interface FlagCustomOptions {
+    /**
+    * Help options for the flag.
+    */
+    help?: HelpOptions;
   }
 }
 interface HelpPluginOptions {
+  /**
+  * Whether to register the `help` command.
+  *
+  * @default true
+  */
   command?: boolean;
+  /**
+  * Whether to register the `--help` global flag.
+  *
+  * @default true
+  */
   flag?: boolean;
+  /**
+  * Whether to show help when no command is specified.
+  *
+  * @default true
+  */
   showHelpWhenNoCommandSpecified?: boolean;
+  /**
+  * Notes to show in the help output.
+  */
   notes?: string[];
+  /**
+  * Examples to show in the help output.
+  * Each example is a tuple of `[command, description]`.
+  */
   examples?: [string, string][];
+  /**
+  * A banner to show before the help output.
+  */
   banner?: string;
+  /**
+  * Custom formatters for rendering help.
+  */
   formatters?: Partial<Formatters>;
+  /**
+  * Group definitions for commands and flags.
+  * Groups allow organizing commands and flags into logical sections in help output.
+  * Each group is defined as `[key, name]` where `key` is the identifier used in help options
+  * and `name` is the display name shown in help output.
+  */
+  groups?: GroupsOptions;
 }
 declare const helpPlugin: ({
   command,
@@ -62,7 +173,8 @@ declare const helpPlugin: ({
   notes,
   examples,
   banner,
-  formatters
+  formatters,
+  groups
 }?: HelpPluginOptions) => Plugin;
 //#endregion
 //#region ../plugin-not-found/src/index.d.ts
@@ -91,4 +203,4 @@ declare const versionPlugin: ({
   flag
 }?: VersionPluginOptions) => Plugin;
 //#endregion
-export { CompletionsPluginOptions, FriendlyErrorPluginOptions, HelpPluginOptions, completionsPlugin, defaultFormatters, friendlyErrorPlugin, helpPlugin, notFoundPlugin, strictFlagsPlugin, versionPlugin };
+export { CommandHelpOptions, CompletionsPluginOptions, FriendlyErrorPluginOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, completionsPlugin, defaultFormatters, friendlyErrorPlugin, helpPlugin, notFoundPlugin, strictFlagsPlugin, versionPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clerc",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc: The full-featured cli library.",
@@ -44,13 +44,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@clerc/core": "1.0.0-beta.2",
-    "@clerc/plugin-help": "1.0.0-beta.2",
-    "@clerc/plugin-completions": "1.0.0-beta.2",
-    "@clerc/plugin-not-found": "1.0.0-beta.2",
-    "@clerc/plugin-friendly-error": "1.0.0-beta.2",
-    "@clerc/plugin-strict-flags": "1.0.0-beta.2",
-    "@clerc/plugin-version": "1.0.0-beta.2"
+    "@clerc/core": "1.0.0-beta.3",
+    "@clerc/plugin-completions": "1.0.0-beta.3",
+    "@clerc/plugin-friendly-error": "1.0.0-beta.3",
+    "@clerc/plugin-help": "1.0.0-beta.3",
+    "@clerc/plugin-not-found": "1.0.0-beta.3",
+    "@clerc/plugin-version": "1.0.0-beta.3",
+    "@clerc/plugin-strict-flags": "1.0.0-beta.3"
   },
   "scripts": {
     "build": "tsdown",