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

package/dist/index.d.ts

@@ -1,41 +1,143 @@
 import { Plugin } from "@clerc/core";
 
 //#region ../parser/src/types.d.ts
-
+interface FlagDefaultValueFunction<T> {
+  (): T;
+  display?: string;
+}
+type FlagDefaultValue<T = unknown> = T | FlagDefaultValueFunction<T>;
 /**
 * Defines how a string input is converted to the target type T.
 *
 * @template T The target type.
 */
-type FlagTypeFunction<T = unknown> = (value: string) => T;
-type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
+interface TypeFunction<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.
+  */
+  display?: string;
+}
+type FlagType<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
 //#endregion
 //#region src/types.d.ts
 interface Formatters {
   formatFlagType: (type: FlagType) => string;
+  formatFlagDefault: <T>(value: FlagDefaultValue<T>) => 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 +146,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

@@ -1,55 +1,108 @@
-import { definePlugin, resolveCommand } from "@clerc/core";
-import { formatFlagName, formatVersion, isTruthy, objectIsEmpty, toArray } from "@clerc/utils";
+import { NoSuchCommandError, definePlugin, normalizeFlagValue, resolveCommand } from "@clerc/core";
 import stringWidth from "string-width";
 import textTable from "text-table";
 import * as yc from "yoctocolors";
 
+//#region ../utils/src/index.ts
+const toArray = (a) => Array.isArray(a) ? a : [a];
+const kebabCase = (s) => s.replace(/([A-Z])/g, (_, c) => `-${c.toLowerCase()}`);
+const formatFlagName = (n) => n.length <= 1 ? `-${n}` : `--${kebabCase(n)}`;
+const formatVersion = (v) => v.length === 0 ? "" : v.startsWith("v") ? v : `v${v}`;
+const isTruthy = Boolean;
+const objectIsEmpty = (obj) => Object.keys(obj).length === 0;
+
+//#endregion
 //#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.display ?? type.name;
+	const innerType = type[0];
+	return `Array<${innerType.displayName ?? innerType.name}>`;
+}
+function formatFlagDefault(value) {
+	if (typeof value === "function" && "display" in value && value.display) return value.display;
+	return String(value);
+}
+function formatCommandName(name) {
+	if (name === "") return "(root)";
+	return name;
 }
 
 //#endregion
 //#region src/formatters.ts
-const defaultFormatters = { formatFlagType };
+const defaultFormatters = {
+	formatFlagType,
+	formatFlagDefault
+};
 
 //#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("-");
+const INDENT = " ".repeat(2);
+const withIndent = (str) => `${INDENT}${str}`;
+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) {
+	_command;
+	get _commandGroups() {
+		return groupDefinitionsToMap(this._getGroups().commands);
+	}
+	get _flagGroups() {
+		return groupDefinitionsToMap(this._getGroups().flags);
+	}
+	get _globalFlagGroups() {
+		return groupDefinitionsToMap(this._getGroups().globalFlags);
+	}
+	constructor(_formatters, _cli, _globalFlags, _getGroups, _examples, _notes) {
 		this._formatters = _formatters;
 		this._cli = _cli;
 		this._globalFlags = _globalFlags;
-		this._command = _command;
-		this._notes = _notes;
+		this._getGroups = _getGroups;
 		this._examples = _examples;
+		this._notes = _notes;
+	}
+	setCommand(command) {
+		if (command) {
+			this._command = command;
+			this._examples = command?.help?.examples;
+			this._notes = command?.help?.notes;
+		}
+	}
+	renderSections(sections) {
+		return sections.filter(isTruthy).map((section) => {
+			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(withIndent).join("\n")}`;
+		}).join("\n\n");
 	}
 	render() {
-		return [
+		const sections = [
 			this.renderHeader(),
 			this.renderUsage(),
-			this.renderCommands(),
-			this.renderGlobalFlags(),
+			this.renderParameters(),
 			this.renderCommandFlags(),
-			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;
-			if (!section.title) return body;
-			return `${yc.bold(section.title)}\n${body.split("\n").map((line) => `  ${line}`).join("\n")}`;
-		}).join("\n\n");
+			this.renderGlobalFlags(),
+			this.renderCommands(),
+			this.renderExamples(),
+			this.renderNotes()
+		];
+		return this.renderSections(sections);
 	}
 	renderHeader() {
 		const { _name, _version, _description } = this._cli;
 		const command = this._command;
-		const description = command?.description ?? _description;
+		const description = command ? 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,54 +110,153 @@ var HelpRenderer = class {
 		const command = this._command;
 		let usage = `$ ${_scriptName}`;
 		if (command) {
-			usage += command.name ? ` ${command.name}` : "";
-			if (command.parameters) usage += ` ${command.parameters.join(" ")}`;
-		}
-		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += " [FLAGS]";
+			if (command.name) usage += ` ${command.name}`;
+			if (command.parameters) usage += ` ${command.parameters.map((p) => typeof p === "string" ? p : p.key).join(" ")}`;
+		} else usage += this._cli._commands.has("") ? " [command]" : " <command>";
+		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += " [flags]";
 		return {
 			title: "Usage",
-			body: [usage]
+			body: [yc.magenta(usage)]
 		};
 	}
+	renderParameters() {
+		const command = this._command;
+		if (!command?.parameters || command.parameters.length === 0) return;
+		return {
+			title: "Parameters",
+			body: splitTable(command.parameters.map((parameter) => {
+				const key = typeof parameter === "string" ? parameter : parameter.key;
+				const type = typeof parameter === "string" ? void 0 : parameter.type;
+				const description = typeof parameter === "string" ? void 0 : parameter.description;
+				return [
+					yc.blue(key),
+					type?.display ? yc.gray(type.display) : void 0,
+					description
+				].filter(isTruthy);
+			}))
+		};
+	}
+	getSubcommands(parentCommandName) {
+		const subcommands = /* @__PURE__ */ new Map();
+		if (parentCommandName === "") return subcommands;
+		const prefix = `${parentCommandName} `;
+		for (const [name, command] of this._cli._commands) if (name.startsWith(prefix)) {
+			const subcommandName = name.slice(prefix.length);
+			subcommands.set(subcommandName, command);
+		}
+		return subcommands;
+	}
+	buildGroupedCommandsBody(commandsToShow, prefix) {
+		const groupedCommands = /* @__PURE__ */ new Map();
+		const defaultCommands = [];
+		let rootCommand = [];
+		for (const command of commandsToShow.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(formatCommandName(command.name.slice(prefix.length)))}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description].filter(isTruthy);
+			if (command.name === "") rootCommand = item;
+			else if (group && group !== DEFAULT_GROUP_KEY) {
+				const groupItems = groupedCommands.get(group) ?? [];
+				groupItems.push(item);
+				groupedCommands.set(group, groupItems);
+			} else defaultCommands.push(item);
+		}
+		const body = [];
+		const defaultGroup = [];
+		if (rootCommand.length > 0) defaultGroup.push(rootCommand);
+		if (defaultCommands.length > 0) defaultGroup.push(...defaultCommands);
+		if (defaultGroup.length > 0) body.push(...splitTable(defaultGroup));
+		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)}`);
+				body.push(...splitTable(items).map(withIndent));
+			}
+		}
+		return body;
+	}
+	renderAvailableSubcommands(parentCommandName) {
+		const subcommands = this.getSubcommands(parentCommandName);
+		if (subcommands.size === 0) return "";
+		const prefix = `${parentCommandName} `;
+		const body = this.buildGroupedCommandsBody(subcommands, prefix);
+		if (body.length === 0) return "";
+		const sections = [{ body: `${yc.green(this._cli._name)} ${yc.cyan(parentCommandName)} not found` }, {
+			title: "Available Subcommands",
+			body
+		}];
+		return this.renderSections(sections);
+	}
 	renderCommands() {
 		const commands = this._cli._commands;
-		if (this._command || commands.size === 0) return;
+		let commandsToShow;
+		let title = "Commands";
+		let prefix = "";
+		if (this._command) {
+			prefix = this._command.name ? `${this._command.name} ` : "";
+			title = "Subcommands";
+			commandsToShow = this.getSubcommands(this._command.name);
+			if (commandsToShow.size === 0) return;
+		} else commandsToShow = commands;
+		if (commandsToShow.size === 0) return;
+		const body = this.buildGroupedCommandsBody(commandsToShow, prefix);
 		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))
+			title,
+			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) {
+		flag = normalizeFlagValue(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: ${this._formatters.formatFlagDefault(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 = [];
+		if (defaultFlags.length > 0) body.push(...splitTable(defaultFlags));
+		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)}`);
+				body.push(...splitTable(items).map(withIndent));
+			}
+		}
+		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() {
@@ -129,9 +281,20 @@ var HelpRenderer = class {
 	}
 };
 
+//#endregion
+//#region src/store.ts
+function addStoreApi(cli, { groups }) {
+	cli.store.help = { addGroup: (options) => {
+		if (options.commands) groups.commands = [...groups.commands ?? [], ...options.commands];
+		if (options.flags) groups.flags = [...groups.flags ?? [], ...options.flags];
+		if (options.globalFlags) groups.globalFlags = [...groups.globalFlags ?? [], ...options.globalFlags];
+	} };
+}
+
 //#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) => {
+	addStoreApi(cli, { groups });
 	const mergedFormatters = {
 		...defaultFormatters,
 		...formatters
@@ -152,6 +315,15 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		if (banner) console.log(banner);
 		console.log(s);
 	}
+	const renderer = new HelpRenderer(mergedFormatters, cli, cli._globalFlags, () => groups, effectiveExamples, effectiveNotes);
+	function tryPrintSubcommandsHelp(commandName) {
+		const subcommandsOutput = renderer.renderAvailableSubcommands(commandName);
+		if (subcommandsOutput) {
+			printHelp(subcommandsOutput);
+			return true;
+		}
+		return false;
+	}
 	if (command) cli.command("help", "Show help", {
 		parameters: ["[command...]"],
 		help: {
@@ -164,11 +336,13 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		if (commandName.length > 0) {
 			[command$1] = resolveCommand(cli._commands, commandName);
 			if (!command$1) {
-				console.error(`Command "${commandName.join(" ")}" not found.`);
-				return;
+				const parentCommandName = commandName.join(" ");
+				if (tryPrintSubcommandsHelp(parentCommandName)) return;
+				throw new NoSuchCommandError(parentCommandName);
 			}
 		}
-		printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, command$1, command$1 ? command$1.help?.notes : effectiveNotes, command$1 ? command$1.help?.examples : effectiveExamples).render());
+		renderer.setCommand(command$1);
+		printHelp(renderer.render());
 	});
 	if (flag) cli.globalFlag("help", "Show help", {
 		alias: "h",
@@ -176,10 +350,17 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		default: false
 	});
 	cli.interceptor({
-		enforce: "pre",
+		enforce: "post",
 		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) {
+				const command$1 = ctx.command;
+				if (!command$1 && ctx.rawParsed.parameters.length > 0) {
+					if (tryPrintSubcommandsHelp(ctx.rawParsed.parameters.join(" "))) return;
+					await next();
+				}
+				renderer.setCommand(command$1);
+				printHelp(renderer.render());
+			} else if (showHelpWhenNoCommandSpecified && !ctx.command && ctx.rawParsed.parameters.length === 0) printHelp(renderer.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.20",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -48,18 +48,15 @@
     "@types/text-table": "^0.2.5",
     "string-width": "^8.1.0",
     "text-table": "^0.2.0",
-    "yoctocolors": "^2.1.2",
-    "@clerc/utils": "1.0.0-beta.2"
+    "yoctocolors": "^2.1.2"
   },
   "devDependencies": {
-    "@clerc/parser": "1.0.0-beta.2",
-    "@clerc/core": "1.0.0-beta.2"
+    "kons": "^0.7.1",
+    "@clerc/parser": "1.0.0-beta.20",
+    "@clerc/core": "1.0.0-beta.20",
+    "@clerc/utils": "1.0.0-beta.20"
   },
   "peerDependencies": {
     "@clerc/core": "*"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch"
   }
 }