@clerc/plugin-help 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { Plugin } from "@clerc/core";
 
 //#region ../parser/src/types.d.ts
-
+type FlagDefaultValue<T = unknown> = T | ((() => T) & {
+  display?: string;
+});
 /**
 * Defines how a string input is converted to the target type T.
 *
@@ -12,13 +14,14 @@ 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;
+  display?: string;
 };
 type FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<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].

package/dist/index.js

@@ -1,4 +1,4 @@
-import { definePlugin, resolveCommand } from "@clerc/core";
+import { NoSuchCommandError, definePlugin, resolveCommand } from "@clerc/core";
 import stringWidth from "string-width";
 import textTable from "text-table";
 import * as yc from "yoctocolors";
@@ -14,10 +14,14 @@ 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;
+	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;
@@ -25,7 +29,10 @@ function formatCommandName(name) {
 
 //#endregion
 //#region src/formatters.ts
-const defaultFormatters = { formatFlagType };
+const defaultFormatters = {
+	formatFlagType,
+	formatFlagDefault
+};
 
 //#endregion
 //#region src/renderer.ts
@@ -96,17 +103,36 @@ var HelpRenderer = class {
 			body: [yc.magenta(usage)]
 		};
 	}
+	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) && name !== parentCommandName) {
+			const subcommandName = name.slice(prefix.length);
+			subcommands.set(subcommandName, command);
+		}
+		return subcommands;
+	}
 	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 groupedCommands = /* @__PURE__ */ new Map();
 		const defaultCommands = [];
 		let rootCommand = [];
-		for (const command of commands.values()) {
+		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))}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description];
+			const item = [`${yc.cyan(formatCommandName(command.name.slice(prefix.length)))}${command.alias ? ` (${toArray(command.alias).join(", ")})` : ""}`, command.description];
 			if (command.name === "") rootCommand = item;
 			else if (group && group !== DEFAULT_GROUP_KEY) {
 				const groupItems = groupedCommands.get(group) ?? [];
@@ -128,7 +154,7 @@ var HelpRenderer = class {
 			}
 		}
 		return {
-			title: "Commands",
+			title,
 			body
 		};
 	}
@@ -140,7 +166,7 @@ var HelpRenderer = class {
 			yc.blue([flagName, aliases].filter(Boolean).join(", ")),
 			yc.gray(type),
 			flag.description,
-			flag.default !== void 0 && yc.gray(`[default: ${String(flag.default)}]`)
+			flag.default !== void 0 && yc.gray(`[default: ${this._formatters.formatFlagDefault(flag.default)}]`)
 		].filter(isTruthy);
 	}
 	renderGroupedFlags(flags, groupMap, itemType) {
@@ -239,10 +265,7 @@ const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecifie
 		let command$1;
 		if (commandName.length > 0) {
 			[command$1] = resolveCommand(cli._commands, commandName);
-			if (!command$1) {
-				console.error(`Command "${commandName.join(" ")}" not found.`);
-				return;
-			}
+			if (!command$1) throw new NoSuchCommandError(commandName.join(" "));
 		}
 		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());
 	});
@@ -252,10 +275,13 @@ 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, 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) 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());
 			else await next();
 		}
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -51,9 +51,10 @@
     "yoctocolors": "^2.1.2"
   },
   "devDependencies": {
-    "@clerc/core": "1.0.0-beta.12",
-    "@clerc/utils": "1.0.0-beta.12",
-    "@clerc/parser": "1.0.0-beta.12"
+    "kons": "^0.7.1",
+    "@clerc/core": "1.0.0-beta.14",
+    "@clerc/utils": "1.0.0-beta.14",
+    "@clerc/parser": "1.0.0-beta.14"
   },
   "peerDependencies": {
     "@clerc/core": "*"