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

package/dist/index.d.ts

@@ -11,7 +11,7 @@ type FlagDefaultValue<T = unknown> = T | FlagDefaultValueFunction<T>;
 *
 * @template T The target type.
 */
-interface FlagTypeFunction<T = unknown> {
+interface TypeFunction<T = unknown> {
   (value: string): T;
   /**
   * Optional display name for the type, useful in help output.
@@ -19,7 +19,7 @@ interface FlagTypeFunction<T = unknown> {
   */
   display?: string;
 }
-type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
+type FlagType<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
 //#endregion
 //#region src/types.d.ts
 interface Formatters {

package/dist/index.js

@@ -51,35 +51,50 @@ 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 {
-	_commandGroups;
-	_flagGroups;
-	_globalFlagGroups;
-	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, _examples, _notes) {
 		this._formatters = _formatters;
 		this._cli = _cli;
 		this._globalFlags = _globalFlags;
-		this._command = _command;
-		this._notes = _notes;
+		this._getGroups = _getGroups;
 		this._examples = _examples;
-		this._commandGroups = groupDefinitionsToMap(groups?.commands);
-		this._flagGroups = groupDefinitionsToMap(groups?.flags);
-		this._globalFlagGroups = groupDefinitionsToMap(groups?.globalFlags);
+		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.renderParameters(),
-			this.renderCommands(),
-			this.renderGlobalFlags(),
 			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(withIndent).join("\n")}`;
-		}).join("\n\n");
+			this.renderGlobalFlags(),
+			this.renderCommands(),
+			this.renderExamples(),
+			this.renderNotes()
+		];
+		return this.renderSections(sections);
 	}
 	renderHeader() {
 		const { _name, _version, _description } = this._cli;
@@ -123,26 +138,15 @@ var HelpRenderer = class {
 	}
 	getSubcommands(parentCommandName) {
 		const subcommands = /* @__PURE__ */ new Map();
-		if (!parentCommandName) return subcommands;
+		if (parentCommandName === "") return subcommands;
 		const prefix = `${parentCommandName} `;
-		for (const [name, command] of this._cli._commands) if (name.startsWith(prefix) && name !== 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;
 	}
-	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;
+	buildGroupedCommandsBody(commandsToShow, prefix) {
 		const groupedCommands = /* @__PURE__ */ new Map();
 		const defaultCommands = [];
 		let rootCommand = [];
@@ -171,6 +175,33 @@ var HelpRenderer = class {
 				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;
+		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,
 			body
@@ -284,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: {
@@ -295,9 +335,14 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		let command$1;
 		if (commandName.length > 0) {
 			[command$1] = resolveCommand(cli._commands, commandName);
-			if (!command$1) throw new NoSuchCommandError(commandName.join(" "));
+			if (!command$1) {
+				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",
@@ -309,9 +354,13 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		handler: async (ctx, next) => {
 			if (ctx.flags.help) {
 				const command$1 = ctx.command;
-				if (!command$1 && ctx.rawParsed.parameters.length > 0) await next();
-				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());
-			} else if (showHelpWhenNoCommandSpecified && !ctx.command && ctx.rawParsed.parameters.length === 0) printHelp(new HelpRenderer(mergedFormatters, cli, cli._globalFlags, void 0, effectiveNotes, effectiveExamples, groups).render());
+				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.19",
+  "version": "1.0.0-beta.20",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -52,9 +52,9 @@
   },
   "devDependencies": {
     "kons": "^0.7.1",
-    "@clerc/core": "1.0.0-beta.19",
-    "@clerc/parser": "1.0.0-beta.19",
-    "@clerc/utils": "1.0.0-beta.19"
+    "@clerc/parser": "1.0.0-beta.20",
+    "@clerc/core": "1.0.0-beta.20",
+    "@clerc/utils": "1.0.0-beta.20"
   },
   "peerDependencies": {
     "@clerc/core": "*"