@clerc/plugin-help 0.44.0 → 1.0.0-beta.10

package/dist/index.d.ts

@@ -1,70 +1,147 @@
-import * as _clerc_core from '@clerc/core';
+import { Plugin } from "@clerc/core";
 
-interface BlockSection {
-    type?: "block";
-    title: string;
-    body: string[];
+//#region ../parser/src/types.d.ts
+
+/**
+* Defines how a string input is converted to the target type T.
+*
+* @template T The target type.
+*/
+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;
 }
-interface InlineSection {
-    type: "inline";
-    items: {
-        title: string;
-        body: 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[];
 }
-type Section = BlockSection | InlineSection;
-interface Renderers {
-    renderSections?: (sections: Section[]) => Section[];
-    renderFlagName?: (name: string) => string;
-    renderType?: (type: any, hasDefault: boolean) => string;
-    renderDefault?: (default_: any) => string;
+//#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;
 }
-
-declare module "@clerc/core" {
-    interface CommandCustomProperties {
-        help?: {
-            renderers?: Renderers;
-            examples?: [string, string][];
-            notes?: 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][];
 }
-interface HelpPluginOptions {
-    /**
-     * Whether to register the help command.
-     *
-     * @default true
-     */
-    command?: boolean;
-    /**
-     * Whether to register the global help flag.
-     *
-     * @default true
-     */
-    flag?: boolean;
-    /**
-     * Whether to show help when no command is specified.
-     *
-     * @default true
-     */
-    showHelpWhenNoCommand?: boolean;
-    /**
-     * Global notes.
-     */
-    notes?: string[];
-    /**
-     * Global examples.
-     */
-    examples?: [string, string][];
+declare module "@clerc/core" {
+  interface CommandCustomOptions {
     /**
-     * Banner.
-     */
-    banner?: string;
+    * Help options for the command.
+    */
+    help?: CommandHelpOptions;
+  }
+  interface FlagCustomOptions {
     /**
-     * Renderers.
-     */
-    renderers?: Renderers;
+    * Help options for the flag.
+    */
+    help?: HelpOptions;
+  }
 }
-declare const helpPlugin: ({ command, flag, showHelpWhenNoCommand, notes, examples, banner, renderers, }?: HelpPluginOptions) => _clerc_core.Plugin<_clerc_core.Clerc<{}, {}>, _clerc_core.Clerc<{}, {}>>;
-
-export { HelpPluginOptions, helpPlugin };
+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,
+  flag,
+  showHelpWhenNoCommandSpecified,
+  notes,
+  examples,
+  banner,
+  formatters,
+  groups
+}?: HelpPluginOptions) => Plugin;
+//#endregion
+export { CommandHelpOptions, type GroupDefinition, type GroupsOptions, HelpOptions, HelpPluginOptions, defaultFormatters, helpPlugin };

package/dist/index.js

@@ -1,372 +1,264 @@
-import { Root, formatCommandName, definePlugin, withBrackets, NoSuchCommandError } from '@clerc/core';
-import { gracefulFlagName, toArray, resolveCommandStrict } from '@clerc/utils';
-import * as yc from 'yoctocolors';
-import stringWidth from 'string-width';
-import textTable from 'text-table';
+import { definePlugin, resolveCommand } from "@clerc/core";
+import stringWidth from "string-width";
+import textTable from "text-table";
+import * as yc from "yoctocolors";
 
-const locales = {
-  "en": {
-    "help.name": "Name:",
-    "help.version": "Version:",
-    "help.subcommand": "Subcommand:",
-    "help.commands": "Commands:",
-    "help.globalFlags": "Global Flags:",
-    "help.flags": "Flags:",
-    "help.description": "Description:",
-    "help.usage": "Usage:",
-    "help.examples": "Examples:",
-    "help.notes": "Notes:",
-    "help.noDescription": "(No description)",
-    "help.notes.1": "If no command is specified, show help for the CLI.",
-    "help.notes.2": "If a command is specified, show help for the command.",
-    "help.notes.3": "-h is an alias for --help.",
-    "help.examples.1": "Show help",
-    "help.examples.2": "Show help for a specific command",
-    "help.commandDescription": "Show help",
-    "help.default": "Default: %s"
-  },
-  "zh-CN": {
-    "help.name": "\u540D\u79F0:",
-    "help.version": "\u7248\u672C:",
-    "help.subcommand": "\u5B50\u547D\u4EE4:",
-    "help.commands": "\u547D\u4EE4:",
-    "help.globalFlags": "\u5168\u5C40\u6807\u5FD7:",
-    "help.flags": "\u6807\u5FD7:",
-    "help.description": "\u63CF\u8FF0:",
-    "help.usage": "\u4F7F\u7528:",
-    "help.examples": "\u793A\u4F8B:",
-    "help.notes": "\u5907\u6CE8:",
-    "help.noDescription": "(\u65E0\u63CF\u8FF0)",
-    "help.notes.1": "\u5982\u679C\u6CA1\u6709\u6307\u5B9A\u5C55\u793A\u54EA\u4E2A\u547D\u4EE4\u7684\u5E2E\u52A9\u4FE1\u606F\uFF0C\u9ED8\u8BA4\u5C55\u793ACLI\u7684\u3002",
-    "help.notes.2": "\u5982\u679C\u6307\u5B9A\u4E86\u5219\u5C55\u793A\u8BE5\u547D\u4EE4\u5E2E\u52A9\u4FE1\u606F\u3002",
-    "help.notes.3": "-h \u662F --help \u7684\u4E00\u4E2A\u522B\u540D\u3002",
-    "help.examples.1": "\u5C55\u793A CLI \u7684\u5E2E\u52A9\u4FE1\u606F",
-    "help.examples.2": "\u5C55\u793A\u6307\u5B9A\u547D\u4EE4\u7684\u5E2E\u52A9\u4FE1\u606F",
-    "help.commandDescription": "\u5C55\u793A\u5E2E\u52A9\u4FE1\u606F",
-    "help.default": "\u9ED8\u8BA4\u503C: %s"
-  }
-};
+//#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;
+	const innerType = type[0];
+	return `Array<${innerType.displayName ?? innerType.name}>`;
+}
 
+//#endregion
+//#region src/formatters.ts
+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 primitiveMap = /* @__PURE__ */ new Map([
-  [Boolean, void 0],
-  [String, "string"],
-  [Number, "number"]
-]);
-function stringifyType(type, hasDefault = false) {
-  const res = primitiveMap.has(type) ? primitiveMap.get(type) : "value";
-  return res ? hasDefault ? `[${res}]` : `<${res}>` : "";
-}
-function sortName(a, b) {
-  if (a === Root) {
-    return -1;
-  }
-  if (b === Root) {
-    return 1;
-  }
-  return a.length - b.length;
-}
 const DELIMITER = yc.yellow("-");
-function print(s) {
-  process.stdout.write(s);
+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 generateCliDetail(sections, cli, subcommand) {
-  var _a;
-  const { t } = cli.i18n;
-  const items = [
-    {
-      title: t("help.name"),
-      body: yc.red(cli._name)
-    },
-    {
-      title: t("help.version"),
-      body: yc.yellow(cli._version)
-    }
-  ];
-  if (subcommand) {
-    items.push({
-      title: t("help.subcommand"),
-      body: yc.green(
-        `${cli._scriptName} ${formatCommandName(subcommand.name)}`
-      )
-    });
-  }
-  sections.push({
-    type: "inline",
-    items
-  });
-  sections.push({
-    title: t("help.description"),
-    body: [(_a = subcommand == null ? void 0 : subcommand.description) != null ? _a : cli._description]
-  });
+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)"}`);
 }
-function generateExamples(sections, examples, t) {
-  const examplesFormatted = examples.map(([command, description]) => [
-    command,
-    DELIMITER,
-    description
-  ]);
-  sections.push({
-    title: t("help.examples"),
-    body: splitTable(examplesFormatted)
-  });
-}
-const formatFlags = (flags, t, renderers) => Object.entries(flags).map(([name, flag]) => {
-  const hasDefault = flag.default !== void 0;
-  let flagNameWithAlias = [gracefulFlagName(name)];
-  if (flag.alias) {
-    flagNameWithAlias.push(gracefulFlagName(flag.alias));
-  }
-  flagNameWithAlias = flagNameWithAlias.map(renderers.renderFlagName);
-  const items = [
-    yc.blue(flagNameWithAlias.join(", ")),
-    renderers.renderType(flag.type, hasDefault)
-  ];
-  items.push(DELIMITER, flag.description || t("help.noDescription"));
-  if (hasDefault) {
-    items.push(
-      `(${t("help.default", renderers.renderDefault(flag.default))})`
-    );
-  }
-  return items;
-});
-
-const render = (sections) => {
-  const rendered = [];
-  for (const section of sections) {
-    if (section.type === "block" || !section.type) {
-      const indent = "    ";
-      const formattedBody = section.body.map((line) => indent + line);
-      formattedBody.unshift("");
-      const body = formattedBody.join("\n");
-      rendered.push(table([[yc.bold(`${section.title}`)], [body]]).toString());
-    } else if (section.type === "inline") {
-      const formattedBody = section.items.map((item) => [
-        yc.bold(`${item.title}`),
-        item.body
-      ]);
-      const tableGenerated = table(formattedBody);
-      rendered.push(tableGenerated.toString());
-    }
-    rendered.push("");
-  }
-  return rendered.join("\n");
-};
-const noop = (x) => x;
-const defaultRenderers = {
-  renderFlagName: noop,
-  renderSections: noop,
-  renderType: stringifyType,
-  renderDefault: JSON.stringify
+var HelpRenderer = class {
+	_commandGroups;
+	_flagGroups;
+	_globalFlagGroups;
+	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 [
+			this.renderHeader(),
+			this.renderUsage(),
+			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");
+	}
+	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;
+		return { body: [`${headerLine}${description ? ` ${DELIMITER} ${description}` : ""}`, alias] };
+	}
+	renderUsage() {
+		const { _scriptName } = this._cli;
+		const command = this._command;
+		let usage = `$ ${_scriptName}`;
+		if (command) {
+			if (command.name) usage += ` ${command.name}`;
+			if (command.parameters) usage += ` ${command.parameters.join(" ")}`;
+		} else usage += this._cli._commands.has("") ? " [command]" : " <command>";
+		if (command?.flags && !objectIsEmpty(command.flags) || !objectIsEmpty(this._globalFlags)) usage += " [flags]";
+		return {
+			title: "Usage",
+			body: [yc.magenta(usage)]
+		};
+	}
+	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)}`);
+				body.push(...splitTable(items).map(withIndent));
+			}
+		}
+		if (defaultCommands.length > 0) if (body.length > 0) {
+			body.push("");
+			body.push(`${yc.dim("Other")}`);
+			body.push(...splitTable(defaultCommands).map(withIndent));
+		} else body.push(...splitTable(defaultCommands));
+		return {
+			title: "Commands",
+			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);
+		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)}`);
+				body.push(...splitTable(items).map(withIndent));
+			}
+		}
+		if (defaultFlags.length > 0) if (body.length > 0) {
+			body.push("");
+			body.push(`${yc.dim("Other")}`);
+			body.push(...splitTable(defaultFlags).map(withIndent));
+		} else body.push(...splitTable(defaultFlags));
+		return body;
+	}
+	renderCommandFlags() {
+		const command = this._command;
+		if (!command?.flags || objectIsEmpty(command.flags)) return;
+		return {
+			title: "Flags",
+			body: this.renderGroupedFlags(command.flags, this._flagGroups, "flag")
+		};
+	}
+	renderGlobalFlags() {
+		if (!this._globalFlags || objectIsEmpty(this._globalFlags)) return;
+		return {
+			title: "Global Flags",
+			body: this.renderGroupedFlags(this._globalFlags, this._globalFlagGroups, "global flag")
+		};
+	}
+	renderNotes() {
+		if (!this._notes?.length) return;
+		return {
+			title: "Notes",
+			body: this._notes
+		};
+	}
+	renderExamples() {
+		if (!this._examples?.length) return;
+		return {
+			title: "Examples",
+			body: splitTable(this._examples.map(([command, description]) => {
+				return [
+					command,
+					DELIMITER,
+					description
+				];
+			}))
+		};
+	}
 };
 
-function generateHelp(render2, ctx, notes, examples, _renderers) {
-  const { cli } = ctx;
-  const { t } = cli.i18n;
-  let sections = [];
-  const renderers = Object.assign(
-    /* @__PURE__ */ Object.create(null),
-    defaultRenderers,
-    _renderers
-  );
-  generateCliDetail(sections, cli);
-  sections.push({
-    title: t("help.usage"),
-    body: [
-      yc.magenta(
-        `$ ${cli._scriptName} ${withBrackets(
-          "command",
-          ctx.hasRootOrAlias
-        )} [flags]`
-      )
-    ]
-  });
-  const commands = [
-    ...ctx.hasRoot ? [cli._commands[Root]] : [],
-    ...Object.values(cli._commands)
-  ].map((command) => {
-    var _a;
-    const commandNameWithAlias = [
-      typeof command.name === "symbol" ? "" : command.name,
-      ...toArray((_a = command.alias) != null ? _a : [])
-    ].sort(sortName).map(
-      (n) => n === "" || typeof n === "symbol" ? `${cli._scriptName}` : `${cli._scriptName} ${n}`
-    ).join(", ");
-    return [yc.cyan(commandNameWithAlias), DELIMITER, command.description];
-  });
-  if (commands.length > 0) {
-    sections.push({
-      title: t("help.commands"),
-      body: splitTable(commands)
-    });
-  }
-  const globalFlags = formatFlags(cli._flags, t, renderers);
-  if (globalFlags.length > 0) {
-    sections.push({
-      title: t("help.globalFlags"),
-      body: splitTable(globalFlags)
-    });
-  }
-  if (notes) {
-    sections.push({
-      title: t("help.notes"),
-      body: notes
-    });
-  }
-  if (examples) {
-    generateExamples(sections, examples, t);
-  }
-  sections = renderers.renderSections(sections);
-  return render2(sections);
-}
-function generateSubcommandHelp(render2, ctx, command) {
-  var _a, _b, _c, _d, _e, _f;
-  const { cli } = ctx;
-  const { t } = cli.i18n;
-  const [subcommand] = resolveCommandStrict(cli._commands, command, t);
-  if (!subcommand) {
-    throw new NoSuchCommandError(formatCommandName(command), t);
-  }
-  const renderers = Object.assign(
-    /* @__PURE__ */ Object.create(null),
-    defaultRenderers,
-    (_a = subcommand.help) == null ? void 0 : _a.renderers
-  );
-  let sections = [];
-  if (command === Root) {
-    generateCliDetail(sections, cli);
-  } else {
-    generateCliDetail(sections, cli, {
-      ...subcommand,
-      name: formatCommandName(command)
-    });
-  }
-  const parameters = (_c = (_b = subcommand.parameters) == null ? void 0 : _b.join(" ")) != null ? _c : void 0;
-  const commandName = command === Root ? "" : ` ${formatCommandName(command)}`;
-  const parametersString = parameters ? ` ${parameters}` : "";
-  const flagsString = subcommand.flags ? " [flags]" : "";
-  sections.push({
-    title: t("help.usage"),
-    body: [
-      yc.magenta(
-        `$ ${cli._scriptName}${commandName}${parametersString}${flagsString}`
-      )
-    ]
-  });
-  const globalFlags = formatFlags(cli._flags, t, renderers);
-  if (globalFlags.length > 0) {
-    sections.push({
-      title: t("help.globalFlags"),
-      body: splitTable(globalFlags)
-    });
-  }
-  if (subcommand.flags) {
-    sections.push({
-      title: t("help.flags"),
-      body: splitTable(formatFlags(subcommand.flags, t, renderers))
-    });
-  }
-  if ((_d = subcommand == null ? void 0 : subcommand.help) == null ? void 0 : _d.notes) {
-    sections.push({
-      title: t("help.notes"),
-      body: subcommand.help.notes
-    });
-  }
-  if ((_e = subcommand == null ? void 0 : subcommand.help) == null ? void 0 : _e.examples) {
-    generateExamples(sections, (_f = subcommand == null ? void 0 : subcommand.help) == null ? void 0 : _f.examples, t);
-  }
-  sections = renderers.renderSections(sections);
-  return render2(sections);
-}
-const helpPlugin = ({
-  command = true,
-  flag = true,
-  showHelpWhenNoCommand = true,
-  notes,
-  examples,
-  banner,
-  renderers
-} = {}) => definePlugin({
-  setup: (cli) => {
-    const { add, t } = cli.i18n;
-    add(locales);
-    function printHelp(s) {
-      banner && print(`${banner}
-`);
-      print(s);
-    }
-    if (command) {
-      cli = cli.command("help", t("help.commandDescription"), {
-        parameters: ["[command...]"],
-        help: {
-          notes: [
-            t("help.notes.1"),
-            t("help.notes.2"),
-            t("help.notes.3")
-          ],
-          examples: [
-            [`$ ${cli._scriptName} help`, t("help.examples.1")],
-            [`$ ${cli._scriptName} help <command>`, t("help.examples.2")],
-            [
-              `$ ${cli._scriptName} <command> --help`,
-              t("help.examples.2")
-            ]
-          ]
-        }
-      }).on("help", (ctx) => {
-        if (ctx.parameters.command.length > 0) {
-          printHelp(
-            generateSubcommandHelp(render, ctx, ctx.parameters.command)
-          );
-        } else {
-          printHelp(generateHelp(render, ctx, notes, examples, renderers));
-        }
-      });
-    }
-    if (flag) {
-      cli = cli.flag("help", t("help.commandDescription"), {
-        alias: "h",
-        type: Boolean,
-        default: false
-      });
-    }
-    cli.interceptor((ctx, next) => {
-      const shouldShowHelp = ctx.flags.help;
-      if (!ctx.hasRootOrAlias && ctx.raw._.length === 0 && showHelpWhenNoCommand && !shouldShowHelp) {
-        let str = `${t("core.noCommandGiven")}
-
-`;
-        str += generateHelp(render, ctx, notes, examples, renderers);
-        str += "\n";
-        printHelp(str);
-        process.exit(1);
-      } else if (shouldShowHelp) {
-        if (ctx.raw._.length > 0) {
-          if (ctx.called === Root) {
-            printHelp(generateSubcommandHelp(render, ctx, ctx.raw._));
-          } else {
-            if (ctx.name === Root) {
-              printHelp(
-                generateHelp(render, ctx, notes, examples, renderers)
-              );
-            } else {
-              printHelp(generateSubcommandHelp(render, ctx, ctx.raw._));
-            }
-          }
-        } else {
-          if (ctx.hasRootOrAlias) {
-            printHelp(generateSubcommandHelp(render, ctx, Root));
-          } else {
-            printHelp(generateHelp(render, ctx, notes, examples, renderers));
-          }
-        }
-      } else {
-        next();
-      }
-    });
-    return cli;
-  }
-});
+//#endregion
+//#region src/index.ts
+const helpPlugin = ({ command = true, flag = true, showHelpWhenNoCommandSpecified = true, notes, examples, banner, formatters, groups } = {}) => definePlugin({ setup: (cli) => {
+	const mergedFormatters = {
+		...defaultFormatters,
+		...formatters
+	};
+	const generalHelpNotes = [
+		"If no command is specified, show help for the CLI.",
+		"If a command is specified, show help for the command.",
+		flag && "-h is an alias for --help."
+	].filter(isTruthy);
+	const generalHelpExamples = [
+		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;
+	function printHelp(s) {
+		if (banner) console.log(banner);
+		console.log(s);
+	}
+	if (command) cli.command("help", "Show help", {
+		parameters: ["[command...]"],
+		help: {
+			notes: generalHelpNotes,
+			examples: generalHelpExamples
+		}
+	}).on("help", (ctx) => {
+		const commandName = ctx.parameters.command;
+		let command$1;
+		if (commandName.length > 0) {
+			[command$1] = resolveCommand(cli._commands, commandName);
+			if (!command$1) {
+				console.error(`Command "${commandName.join(" ")}" not found.`);
+				return;
+			}
+		}
+		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",
+		type: Boolean,
+		default: false
+	});
+	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, 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();
+		}
+	});
+} });
 
-export { helpPlugin };
+//#endregion
+export { defaultFormatters, helpPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "0.44.0",
+  "version": "1.0.0-beta.10",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc plugin help",
@@ -25,13 +25,10 @@
   "license": "MIT",
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    ".": "./dist/index.js"
   },
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "dist/index.d.ts",
   "typesVersions": {
     "*": {
@@ -48,17 +45,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@types/text-table": "^0.2.3",
-    "string-width": "^6.1.0",
+    "@types/text-table": "^0.2.5",
+    "string-width": "^8.1.0",
     "text-table": "^0.2.0",
-    "yoctocolors": "^1.0.0",
-    "@clerc/utils": "0.44.0"
+    "yoctocolors": "^2.1.2"
+  },
+  "devDependencies": {
+    "@clerc/core": "1.0.0-beta.10",
+    "@clerc/utils": "1.0.0-beta.10",
+    "@clerc/parser": "1.0.0-beta.10"
   },
   "peerDependencies": {
     "@clerc/core": "*"
-  },
-  "scripts": {
-    "build": "pkgroll",
-    "watch": "pkgroll --watch"
   }
 }