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

package/dist/index.d.ts

@@ -1,70 +1,30 @@
-import * as _clerc_core from '@clerc/core';
-
-interface BlockSection {
-    type?: "block";
-    title: string;
-    body: string[];
-}
-interface InlineSection {
-    type: "inline";
-    items: {
-        title: string;
-        body: string;
-    }[];
-}
-type Section = BlockSection | InlineSection;
-interface Renderers {
-    renderSections?: (sections: Section[]) => Section[];
-    renderFlagName?: (name: string) => string;
-    renderType?: (type: any, hasDefault: boolean) => string;
-    renderDefault?: (default_: any) => string;
-}
+import { Plugin } from "@clerc/core";
 
+//#region src/index.d.ts
 declare module "@clerc/core" {
-    interface CommandCustomProperties {
-        help?: {
-            renderers?: Renderers;
-            examples?: [string, string][];
-            notes?: string[];
-        };
-    }
+  interface CommandCustomOptions {
+    help?: {
+      showInHelp?: boolean;
+      notes?: string[];
+      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][];
-    /**
-     * Banner.
-     */
-    banner?: string;
-    /**
-     * Renderers.
-     */
-    renderers?: Renderers;
+  command?: boolean;
+  flag?: boolean;
+  showHelpWhenNoCommandSpecified?: boolean;
+  notes?: string[];
+  examples?: [string, string][];
+  banner?: string;
 }
-declare const helpPlugin: ({ command, flag, showHelpWhenNoCommand, notes, examples, banner, renderers, }?: HelpPluginOptions) => _clerc_core.Plugin<_clerc_core.Clerc<{}, {}>, _clerc_core.Clerc<{}, {}>>;
-
-export { HelpPluginOptions, helpPlugin };
+declare const helpPlugin: ({
+  command,
+  flag,
+  showHelpWhenNoCommandSpecified,
+  notes,
+  examples,
+  banner
+}?: HelpPluginOptions) => Plugin;
+//#endregion
+export { HelpPluginOptions, helpPlugin };

package/dist/index.js

@@ -1,372 +1,180 @@
-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 { formatFlagName, formatVersion, isTruthy, objectIsEmpty, toArray } from "@clerc/utils";
+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 src/utils.ts
+function formatFlagType(type) {
+	if (typeof type === "function") return type.name;
+	return `Array<${type[0].name}>`;
+}
 
+//#endregion
+//#region src/renderer.ts
 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);
-}
-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 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 {
+	constructor(_cli, _globalFlags, _command, _notes, _examples) {
+		this._cli = _cli;
+		this._globalFlags = _globalFlags;
+		this._command = _command;
+		this._notes = _notes;
+		this._examples = _examples;
+	}
+	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(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");
+	}
+	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(", ")}` : "";
+		return { body: [`${headerLine}${description ? ` ${DELIMITER} ${description}` : ""}`, alias] };
+	}
+	renderUsage() {
+		const { _scriptName } = this._cli;
+		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]";
+		return {
+			title: "Usage",
+			body: [usage]
+		};
+	}
+	renderCommands() {
+		const commands = this._cli._commands;
+		if (this._command || commands.size === 0) return;
+		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))
+		};
+	}
+	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 = 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)
+			];
+		});
+	}
+	renderCommandFlags() {
+		const command = this._command;
+		if (!command?.flags || objectIsEmpty(command.flags)) return;
+		return {
+			title: "Flags",
+			body: splitTable(this.renderFlags(command.flags))
+		};
+	}
+	renderGlobalFlags() {
+		if (!this._globalFlags || objectIsEmpty(this._globalFlags)) return;
+		return {
+			title: "Global Flags",
+			body: splitTable(this.renderFlags(this._globalFlags))
+		};
+	}
+	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 } = {}) => definePlugin({ setup: (cli) => {
+	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(cli, cli._globalFlags, command$1, command$1 ? command$1.help?.notes : effectiveNotes, command$1 ? command$1.help?.examples : effectiveExamples).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(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(cli, cli._globalFlags, void 0, effectiveNotes, effectiveExamples).render());
+			else await next();
+		}
+	});
+} });
 
-export { helpPlugin };
+//#endregion
+export { helpPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "0.44.0",
+  "version": "1.0.0-beta.1",
   "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,21 @@
     "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",
+    "@clerc/utils": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@clerc/parser": "1.0.0-beta.1",
+    "@clerc/core": "1.0.0-beta.1"
   },
   "peerDependencies": {
     "@clerc/core": "*"
   },
   "scripts": {
-    "build": "pkgroll",
-    "watch": "pkgroll --watch"
+    "build": "tsdown",
+    "watch": "tsdown --watch"
   }
 }