@clerc/plugin-help 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/index.d.ts

@@ -7,35 +7,131 @@ import { Plugin } from "@clerc/core";
 *
 * @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 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 src/formatters.d.ts
 declare const defaultFormatters: Formatters;
 //#endregion
 //#region 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,
@@ -44,7 +140,8 @@ declare const helpPlugin: ({
   notes,
   examples,
   banner,
-  formatters
+  formatters,
+  groups
 }?: HelpPluginOptions) => Plugin;
 //#endregion
-export { HelpPluginOptions, defaultFormatters, helpPlugin };
+export { CommandHelpOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, defaultFormatters, helpPlugin };

package/dist/index.js

@@ -6,8 +6,9 @@ import * as yc from "yoctocolors";
 
 //#region src/utils.ts
 function formatFlagType(type) {
-	if (typeof type === "function") return type.name;
-	return `Array<${type[0].name}>`;
+	if (typeof type === "function") return type.displayName ?? type.name;
+	const innerType = type[0];
+	return `Array<${innerType.displayName ?? innerType.name}>`;
 }
 
 //#endregion
@@ -16,17 +17,29 @@ const defaultFormatters = { formatFlagType };
 
 //#endregion
 //#region src/renderer.ts
+const DEFAULT_GROUP_KEY = "default";
 const table = (items) => textTable(items, { stringLength: stringWidth });
 const splitTable = (items) => table(items).split("\n");
 const DELIMITER = yc.yellow("-");
+function groupDefinitionsToMap(definitions) {
+	const map = /* @__PURE__ */ new Map();
+	if (definitions) for (const [key, name] of definitions) map.set(key, name);
+	return map;
+}
+function validateGroup(group, groupMap, itemType, itemName) {
+	if (group && group !== DEFAULT_GROUP_KEY && !groupMap.has(group)) throw new Error(`Unknown ${itemType} group "${group}" for "${itemName}". Available groups: ${[...groupMap.keys()].join(", ") || "(none)"}`);
+}
 var HelpRenderer = class {
-	constructor(_formatters, _cli, _globalFlags, _command, _notes, _examples) {
+	constructor(_formatters, _cli, _globalFlags, _command, _notes, _examples, groups) {
 		this._formatters = _formatters;
 		this._cli = _cli;
 		this._globalFlags = _globalFlags;
 		this._command = _command;
 		this._notes = _notes;
 		this._examples = _examples;
+		this._commandGroups = groupDefinitionsToMap(groups?.commands);
+		this._flagGroups = groupDefinitionsToMap(groups?.flags);
+		this._globalFlagGroups = groupDefinitionsToMap(groups?.globalFlags);
 	}
 	render() {
 		return [
@@ -38,7 +51,7 @@ var HelpRenderer = class {
 			this.renderNotes(),
 			this.renderExamples()
 		].filter(isTruthy).filter((section) => section.body.length > 0).map((section) => {
-			const body = Array.isArray(section.body) ? section.body.filter(Boolean).join("\n") : section.body;
+			const body = Array.isArray(section.body) ? section.body.filter((s) => s !== void 0).join("\n") : section.body;
 			if (!section.title) return body;
 			return `${yc.bold(section.title)}\n${body.split("\n").map((line) => `  ${line}`).join("\n")}`;
 		}).join("\n\n");
@@ -49,7 +62,7 @@ var HelpRenderer = class {
 		const description = command?.description ?? _description;
 		const formattedCommandName = command?.name ? ` ${yc.cyan(command.name)}` : "";
 		const headerLine = command ? `${yc.green(_name)}${formattedCommandName}` : `${yc.green(_name)} ${yc.yellow(formatVersion(_version))}`;
-		const alias = command?.alias ? `Alias${toArray(command.alias).length > 1 ? "es" : ""}: ${toArray(command.alias).map((a) => yc.cyan(a)).join(", ")}` : "";
+		const alias = command?.alias ? `Alias${toArray(command.alias).length > 1 ? "es" : ""}: ${toArray(command.alias).map((a) => yc.cyan(a)).join(", ")}` : void 0;
 		return { body: [`${headerLine}${description ? ` ${DELIMITER} ${description}` : ""}`, alias] };
 	}
 	renderUsage() {
@@ -57,7 +70,7 @@ var HelpRenderer = class {
 		const command = this._command;
 		let usage = `$ ${_scriptName}`;
 		if (command) {
-			usage += command.name ? ` ${command.name}` : "";
+			if (command.name) usage += ` ${command.name}`;
 			if (command.parameters) usage += ` ${command.parameters.join(" ")}`;
 		}
 		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += " [FLAGS]";
@@ -69,42 +82,91 @@ var HelpRenderer = class {
 	renderCommands() {
 		const commands = this._cli._commands;
 		if (this._command || commands.size === 0) return;
+		const groupedCommands = /* @__PURE__ */ new Map();
+		const defaultCommands = [];
+		for (const command of commands.values()) {
+			if (command.__isAlias || command.help?.show === false) continue;
+			const group = command.help?.group;
+			validateGroup(group, this._commandGroups, "command", command.name);
+			const item = [`${yc.cyan(command.name)}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description];
+			if (group && group !== DEFAULT_GROUP_KEY) {
+				const groupItems = groupedCommands.get(group) ?? [];
+				groupItems.push(item);
+				groupedCommands.set(group, groupItems);
+			} else defaultCommands.push(item);
+		}
+		const body = [];
+		for (const [key, name] of this._commandGroups) {
+			const items = groupedCommands.get(key);
+			if (items && items.length > 0) {
+				if (body.length > 0) body.push("");
+				body.push(`${yc.dim(name)}`);
+				for (const line of splitTable(items)) body.push(`  ${line}`);
+			}
+		}
+		if (defaultCommands.length > 0) if (body.length > 0) {
+			body.push("");
+			body.push(`${yc.dim("Other")}`);
+			for (const line of splitTable(defaultCommands)) body.push(`  ${line}`);
+		} else body.push(...splitTable(defaultCommands));
 		return {
 			title: "Commands",
-			body: splitTable([...commands.values()].map((command) => {
-				if (command.__isAlias || command.help?.showInHelp === false) return null;
-				return [`${yc.cyan(command.name)}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description];
-			}).filter(isTruthy))
+			body
 		};
 	}
-	renderFlags(flags) {
-		return Object.entries(flags).map(([name, flag]) => {
-			const flagName = formatFlagName(name);
-			const aliases = (Array.isArray(flag.alias) ? flag.alias : flag.alias ? [flag.alias] : []).map(formatFlagName).join(", ");
-			const description = flag.description ?? "";
-			const type = this._formatters.formatFlagType(flag.type);
-			const defaultValue = flag.default === void 0 ? "" : `[default: ${String(flag.default)}]`;
-			return [
-				yc.blue([flagName, aliases].filter(Boolean).join(", ")),
-				yc.gray(type),
-				description,
-				yc.gray(defaultValue)
-			];
-		});
+	renderFlagItem(name, flag) {
+		const flagName = formatFlagName(name);
+		const aliases = (Array.isArray(flag.alias) ? flag.alias : flag.alias ? [flag.alias] : []).map(formatFlagName).join(", ");
+		const type = this._formatters.formatFlagType(flag.type);
+		return [
+			yc.blue([flagName, aliases].filter(Boolean).join(", ")),
+			yc.gray(type),
+			flag.description,
+			flag.default !== void 0 && yc.gray(`[default: ${String(flag.default)}]`)
+		].filter(isTruthy);
+	}
+	renderGroupedFlags(flags, groupMap, itemType) {
+		const groupedFlags = /* @__PURE__ */ new Map();
+		const defaultFlags = [];
+		for (const [name, flag] of Object.entries(flags)) {
+			const group = flag.help?.group;
+			validateGroup(group, groupMap, itemType, name);
+			const item = this.renderFlagItem(name, flag);
+			if (group && group !== DEFAULT_GROUP_KEY) {
+				const groupItems = groupedFlags.get(group) ?? [];
+				groupItems.push(item);
+				groupedFlags.set(group, groupItems);
+			} else defaultFlags.push(item);
+		}
+		const body = [];
+		for (const [key, name] of groupMap) {
+			const items = groupedFlags.get(key);
+			if (items && items.length > 0) {
+				if (body.length > 0) body.push("");
+				body.push(`${yc.dim(name)}`);
+				for (const line of splitTable(items)) body.push(`  ${line}`);
+			}
+		}
+		if (defaultFlags.length > 0) if (body.length > 0) {
+			body.push("");
+			body.push(`${yc.dim("Other")}`);
+			for (const line of splitTable(defaultFlags)) body.push(`  ${line}`);
+		} else body.push(...splitTable(defaultFlags));
+		return body;
 	}
 	renderCommandFlags() {
 		const command = this._command;
 		if (!command?.flags || objectIsEmpty(command.flags)) return;
 		return {
 			title: "Flags",
-			body: splitTable(this.renderFlags(command.flags))
+			body: this.renderGroupedFlags(command.flags, this._flagGroups, "flag")
 		};
 	}
 	renderGlobalFlags() {
 		if (!this._globalFlags || objectIsEmpty(this._globalFlags)) return;
 		return {
 			title: "Global Flags",
-			body: splitTable(this.renderFlags(this._globalFlags))
+			body: this.renderGroupedFlags(this._globalFlags, this._globalFlagGroups, "global flag")
 		};
 	}
 	renderNotes() {
@@ -131,7 +193,7 @@ var HelpRenderer = class {
 
 //#endregion
 //#region src/index.ts
-const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecified = true, notes, examples, banner, formatters } = {}) => definePlugin({ setup: (cli) => {
+const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecified = true, notes, examples, banner, formatters, groups } = {}) => definePlugin({ setup: (cli) => {
 	const mergedFormatters = {
 		...defaultFormatters,
 		...formatters
@@ -168,7 +230,7 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 				return;
 			}
 		}
-		printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, command$1, command$1 ? command$1.help?.notes : effectiveNotes, command$1 ? command$1.help?.examples : effectiveExamples).render());
+		printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, command$1, command$1 ? command$1.help?.notes : effectiveNotes, command$1 ? command$1.help?.examples : effectiveExamples, groups).render());
 	});
 	if (flag) cli.globalFlag("help", "Show help", {
 		alias: "h",
@@ -178,8 +240,8 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 	cli.interceptor({
 		enforce: "pre",
 		handler: async (ctx, next) => {
-			if (ctx.flags.help) printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, ctx.command, ctx.command ? ctx.command.help?.notes : effectiveNotes, ctx.command ? ctx.command.help?.examples : effectiveExamples).render());
-			else if (showHelpWhenNoCommandSpecified && !ctx.command && ctx.rawParsed.parameters.length === 0) printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, void 0, effectiveNotes, effectiveExamples).render());
+			if (ctx.flags.help) printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, ctx.command, ctx.command ? ctx.command.help?.notes : effectiveNotes, ctx.command ? ctx.command.help?.examples : effectiveExamples, groups).render());
+			else if (showHelpWhenNoCommandSpecified && !ctx.command && ctx.rawParsed.parameters.length === 0) printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, void 0, effectiveNotes, effectiveExamples, groups).render());
 			else await next();
 		}
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -49,11 +49,11 @@
     "string-width": "^8.1.0",
     "text-table": "^0.2.0",
     "yoctocolors": "^2.1.2",
-    "@clerc/utils": "1.0.0-beta.2"
+    "@clerc/utils": "1.0.0-beta.4"
   },
   "devDependencies": {
-    "@clerc/parser": "1.0.0-beta.2",
-    "@clerc/core": "1.0.0-beta.2"
+    "@clerc/core": "1.0.0-beta.4",
+    "@clerc/parser": "1.0.0-beta.4"
   },
   "peerDependencies": {
     "@clerc/core": "*"