@clerc/plugin-help 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/index.d.ts

@@ -1,24 +1,30 @@
 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) & {
+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.
   */
-  displayName?: string;
-};
-type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
+  display?: string;
+}
+type TypeValue<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
 //#endregion
 //#region src/types.d.ts
 interface Formatters {
-  formatFlagType: (type: FlagType) => string;
+  formatTypeValue: (type: TypeValue) => string;
+  formatFlagDefault: <T>(value: FlagDefaultValue<T>) => string;
 }
 /**
 * A group definition as a tuple of [key, displayName].
@@ -118,9 +124,13 @@ interface HelpPluginOptions {
   */
   examples?: [string, string][];
   /**
-  * A banner to show before the help output.
+  * Header to show before the help output.
+  */
+  header?: string;
+  /**
+  * Footer to show after the help output.
   */
-  banner?: string;
+  footer?: string;
   /**
   * Custom formatters for rendering help.
   */
@@ -139,7 +149,8 @@ declare const helpPlugin: ({
   showHelpWhenNoCommandSpecified,
   notes,
   examples,
-  banner,
+  header,
+  footer,
   formatters,
   groups
 }?: HelpPluginOptions) => Plugin;

package/dist/index.js

@@ -1,26 +1,47 @@
-import { definePlugin, resolveCommand } from "@clerc/core";
-import { formatFlagName, formatVersion, isTruthy, objectIsEmpty, toArray } from "@clerc/utils";
+import { DOUBLE_DASH, NoSuchCommandError, definePlugin, normalizeFlagValue, normalizeParameterValue, 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.displayName ?? type.name;
+function formatTypeValue(type) {
+	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 = {
+	formatTypeValue,
+	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 DELIMITER = "-";
+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);
@@ -30,39 +51,58 @@ 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, groups) {
+	_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, _getExamples, _notes) {
 		this._formatters = _formatters;
 		this._cli = _cli;
 		this._globalFlags = _globalFlags;
-		this._command = _command;
+		this._getGroups = _getGroups;
+		this._getExamples = _getExamples;
 		this._notes = _notes;
-		this._examples = _examples;
-		this._commandGroups = groupDefinitionsToMap(groups?.commands);
-		this._flagGroups = groupDefinitionsToMap(groups?.flags);
-		this._globalFlagGroups = groupDefinitionsToMap(groups?.globalFlags);
+	}
+	setCommand(command) {
+		if (command) {
+			this._command = command;
+			this._getExamples = () => 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.underline(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((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");
+			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 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(", ")}` : void 0;
+		const description = command ? command.description : _description;
+		const formattedCommandName = command?.name ? ` ${yc.bold(command.name)}` : "";
+		const headerLine = command ? `${yc.dim(_name)}${formattedCommandName}` : `${yc.bold(_name)} ${formatVersion(_version)}`;
+		const alias = command?.alias ? `Alias${toArray(command.alias).length > 1 ? "es" : ""}: ${toArray(command.alias).map((a) => yc.bold(a)).join(", ")}` : void 0;
 		return { body: [`${headerLine}${description ? ` ${DELIMITER} ${description}` : ""}`, alias] };
 	}
 	renderUsage() {
@@ -71,58 +111,122 @@ var HelpRenderer = class {
 		let usage = `$ ${_scriptName}`;
 		if (command) {
 			if (command.name) usage += ` ${command.name}`;
-			if (command.parameters) usage += ` ${command.parameters.join(" ")}`;
-		}
-		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += " [FLAGS]";
+			if (command.parameters) {
+				const doubleDashIndex = command.parameters.indexOf(DOUBLE_DASH);
+				const hasRequiredAfterDoubleDash = doubleDashIndex !== -1 && command.parameters.slice(doubleDashIndex + 1).some((p) => {
+					return (typeof p === "string" ? p : p.key).startsWith("<");
+				});
+				const items = command.parameters.map((p) => {
+					let key = typeof p === "string" ? p : p.key;
+					if (key === DOUBLE_DASH) key = hasRequiredAfterDoubleDash ? DOUBLE_DASH : `[${DOUBLE_DASH}]`;
+					return key;
+				});
+				usage += ` ${items.join(" ")}`;
+			}
+		} else if (this._cli._commands.size > 0 && !(this._cli._commands.has("") && this._cli._commands.size === 1)) usage += this._cli._commands.has("") ? ` ${yc.dim("[command]")}` : ` ${yc.dim("<command>")}`;
+		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += ` ${yc.dim("[flags]")}`;
 		return {
 			title: "Usage",
 			body: [usage]
 		};
 	}
-	renderCommands() {
-		const commands = this._cli._commands;
-		if (this._command || commands.size === 0) return;
+	renderParameters() {
+		const command = this._command;
+		if (!command?.parameters || command.parameters.length === 0) return;
+		return {
+			title: "Parameters",
+			body: splitTable(command.parameters.map(normalizeParameterValue).filter((parameter) => parameter.key !== DOUBLE_DASH).map(({ key, type, description }) => {
+				const formattedType = type ? this._formatters.formatTypeValue(type) : "string";
+				return [
+					yc.bold(key),
+					yc.dim(formattedType),
+					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 = [];
-		for (const command of commands.values()) {
+		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(command.name)}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description];
-			if (group && group !== DEFAULT_GROUP_KEY) {
+			const item = [`${yc.bold(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)}`);
-				for (const line of splitTable(items)) body.push(`  ${line}`);
+				body.push(...splitTable(items).map(withIndent));
 			}
 		}
-		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 body;
+	}
+	renderAvailableSubcommands(parentCommandName) {
+		const subcommands = this.getSubcommands(parentCommandName);
+		if (subcommands.size === 0) return null;
+		const prefix = `${parentCommandName} `;
+		const body = this.buildGroupedCommandsBody(subcommands, prefix);
+		if (body.length === 0) return null;
+		const sections = [{ body: `${this._cli._name} ${yc.bold(parentCommandName)} not found` }, {
+			title: "Available Subcommands",
+			body
+		}];
+		return this.renderSections(sections);
+	}
+	renderCommands() {
+		const commands = this._cli._commands;
+		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",
+			title,
 			body
 		};
 	}
 	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);
+		flag = normalizeFlagValue(flag);
+		let flagName = formatFlagName(name);
+		if (flag.short) flagName += `, ${formatFlagName(flag.short)}`;
+		const type = this._formatters.formatTypeValue(flag.type);
+		const default_ = flag.default !== void 0 && yc.dim(`[default: ${yc.bold(this._formatters.formatFlagDefault(flag.default))}]`);
 		return [
-			yc.blue([flagName, aliases].filter(Boolean).join(", ")),
-			yc.gray(type),
+			yc.bold(flagName),
+			yc.dim(type),
 			flag.description,
-			flag.default !== void 0 && yc.gray(`[default: ${String(flag.default)}]`)
+			default_
 		].filter(isTruthy);
 	}
 	renderGroupedFlags(flags, groupMap, itemType) {
@@ -139,19 +243,15 @@ var HelpRenderer = class {
 			} 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)}`);
-				for (const line of splitTable(items)) body.push(`  ${line}`);
+				body.push(...splitTable(items).map(withIndent));
 			}
 		}
-		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() {
@@ -177,10 +277,11 @@ var HelpRenderer = class {
 		};
 	}
 	renderExamples() {
-		if (!this._examples?.length) return;
+		const examples = this._getExamples();
+		if (!examples?.length) return;
 		return {
 			title: "Examples",
-			body: splitTable(this._examples.map(([command, description]) => {
+			body: splitTable(examples.map(([command, description]) => {
 				return [
 					command,
 					DELIMITER,
@@ -191,9 +292,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, groups } = {}) => definePlugin({ setup: (cli) => {
+const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecified = true, notes, examples, header, footer, formatters, groups = {} } = {}) => definePlugin({ setup: (cli) => {
+	addStoreApi(cli, { groups });
 	const mergedFormatters = {
 		...defaultFormatters,
 		...formatters
@@ -203,22 +315,32 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		"If a command is specified, show help for the command.",
 		flag && "-h is an alias for --help."
 	].filter(isTruthy);
-	const generalHelpExamples = [
+	const getGeneralHelpExamples = () => [
 		command && [`$ ${cli._scriptName} help`, "Show help"],
 		command && [`$ ${cli._scriptName} help <command>`, "Show help for a specific command"],
 		flag && [`$ ${cli._scriptName} <command> --help`, "Show help for a specific command"]
 	].filter(isTruthy);
 	const effectiveNotes = notes ?? generalHelpNotes;
-	const effectiveExamples = examples ?? generalHelpExamples;
+	const getEffectiveExamples = () => examples ?? getGeneralHelpExamples();
 	function printHelp(s) {
-		if (banner) console.log(banner);
+		if (header) console.log(header);
 		console.log(s);
+		if (footer) console.log(footer);
+	}
+	const renderer = new HelpRenderer(mergedFormatters, cli, cli._globalFlags, () => groups, getEffectiveExamples, 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: {
 			notes: generalHelpNotes,
-			examples: generalHelpExamples
+			examples: getGeneralHelpExamples()
 		}
 	}).on("help", (ctx) => {
 		const commandName = ctx.parameters.command;
@@ -226,22 +348,31 @@ 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, groups).render());
+		renderer.setCommand(command$1);
+		printHelp(renderer.render());
 	});
 	if (flag) cli.globalFlag("help", "Show help", {
-		alias: "h",
+		short: "h",
 		type: Boolean,
 		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, 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());
+			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.3",
+  "version": "1.0.0-beta.30",
   "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.3"
+    "yoctocolors": "^2.1.2"
   },
   "devDependencies": {
-    "@clerc/core": "1.0.0-beta.3",
-    "@clerc/parser": "1.0.0-beta.3"
+    "kons": "^0.7.1",
+    "@clerc/core": "1.0.0-beta.30",
+    "@clerc/utils": "1.0.0-beta.30",
+    "@clerc/parser": "1.0.0-beta.30"
   },
   "peerDependencies": {
     "@clerc/core": "*"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch"
   }
 }