@clerc/plugin-help 0.19.0 → 0.21.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { definePlugin, resolveCommand, NoSuchCommandError, SingleCommand } from '@clerc/core';
-import { toArray, gracefulFlagName, kebabCase } from '@clerc/utils';
+import { definePlugin, SingleCommand, resolveCommand, NoSuchCommandError } from '@clerc/core';
+import { toArray, gracefulFlagName } from '@clerc/utils';
 import pc from 'picocolors';
 import getFuncName from 'get-func-name';
 import { Table } from '@clerc/toolkit';
@@ -39,7 +39,7 @@ const render = (sections) => {
   const rendered = [];
   for (const section of sections) {
     if (section.type === "block" || !section.type) {
-      const indent = " ".repeat(4);
+      const indent = "    ";
       const formattedBody = section.body.map((line) => indent + line);
       formattedBody.unshift("");
       const body = formattedBody.join("\n");
@@ -55,22 +55,36 @@ const render = (sections) => {
 };
 
 const DELIMITER = pc.yellow("-");
-const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : "<Single Command>";
+const NO_DESCRIPTION = "(No description)";
+const SINGLE_COMMAND = "<Single Command>";
+const NAME = "Name:";
+const VERSION = "Version:";
+const COMMANDS = "Commands:";
+const SUBCOMMAND = "Subcommand:";
+const FLAGS = "Flags:";
+const DESCRIPTION = "Description:";
+const USAGE = "Usage:";
+const EXAMPLES = "Examples:";
+const NOTES = "Notes:";
+const print = (s) => {
+  process.stdout.write(s);
+};
+const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : SINGLE_COMMAND;
 const generateCliDetail = (sections, cli, subcommand) => {
   const items = [
     {
-      title: "Name:",
+      title: NAME,
       body: pc.red(cli._name)
     },
     {
-      title: "Version:",
+      title: VERSION,
       body: pc.yellow(cli._version)
     }
   ];
   if (subcommand) {
     items.push({
-      title: "Subcommand:",
-      body: pc.green(formatCommandName(subcommand.name))
+      title: SUBCOMMAND,
+      body: pc.green(`${cli._name} ${formatCommandName(subcommand.name)}`)
     });
   }
   sections.push({
@@ -78,53 +92,55 @@ const generateCliDetail = (sections, cli, subcommand) => {
     items
   });
   sections.push({
-    title: "Description:",
+    title: DESCRIPTION,
     body: [(subcommand == null ? void 0 : subcommand.description) || cli._description]
   });
 };
 const generateExamples = (sections, examples) => {
   const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
   sections.push({
-    title: "Examples:",
+    title: EXAMPLES,
     body: splitTable(...examplesFormatted)
   });
 };
-const showHelp = (ctx, notes, examples) => {
+const generateHelp = (ctx, notes, examples) => {
   const { cli } = ctx;
   const sections = [];
   generateCliDetail(sections, cli);
-  if (ctx.isSingleCommand) {
-    sections.push({
-      title: "Usage:",
-      body: [pc.magenta(`$ ${cli._name} [flags]`)]
-    });
-  } else {
-    sections.push({
-      title: "Usage:",
-      body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
-    });
-  }
-  if (!ctx.isSingleCommand) {
-    sections.push({
-      title: "Commands:",
-      body: splitTable(...Object.values(cli._commands).map((command) => {
-        const commandNameWithAlias = [command.name, ...toArray(command.alias || [])].join(", ");
-        return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
-      }))
-    });
-  }
+  sections.push({
+    title: USAGE,
+    body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
+  });
+  const commands = [...ctx.hasSingleCommand ? [cli._commands[SingleCommand]] : [], ...Object.values(cli._commands)].map((command) => {
+    const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].sort((a, b) => {
+      if (a === SingleCommand) {
+        return -1;
+      }
+      if (b === SingleCommand) {
+        return 1;
+      }
+      return a.length - b.length;
+    }).map((n) => {
+      return n === "" || typeof n === "symbol" ? `${cli._name}` : `${cli._name} ${n}`;
+    }).join(", ");
+    return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
+  });
+  sections.push({
+    title: COMMANDS,
+    body: splitTable(...commands)
+  });
   if (notes) {
     sections.push({
-      title: "Notes:",
+      title: NOTES,
       body: notes
     });
   }
   if (examples) {
     generateExamples(sections, examples);
   }
-  process.stdout.write(render(sections));
+  return render(sections);
 };
-const showSubcommandHelp = (ctx, command) => {
+const generateSubcommandHelp = (ctx, command) => {
   var _a;
   const { cli } = ctx;
   const subcommand = resolveCommand(cli._commands, command);
@@ -132,25 +148,26 @@ const showSubcommandHelp = (ctx, command) => {
     throw new NoSuchCommandError(formatCommandName(command));
   }
   const sections = [];
-  generateCliDetail(sections, cli, ctx.isSingleCommand ? void 0 : subcommand);
+  generateCliDetail(sections, cli, subcommand);
   const parameters = ((_a = subcommand.parameters) == null ? void 0 : _a.join(" ")) || void 0;
+  const commandName = ctx.name === SingleCommand ? "" : ` ${formatCommandName(subcommand.name)}`;
+  const parametersString = parameters ? ` ${parameters}` : "";
+  const flagsString = subcommand.flags ? " [flags]" : "";
   sections.push({
-    title: "Usage:",
-    body: [pc.magenta(`$ ${cli._name}${ctx.isSingleCommand ? "" : ` ${formatCommandName(subcommand.name)}`}${parameters ? ` ${parameters}` : ""} [flags]`)]
+    title: USAGE,
+    body: [pc.magenta(`$ ${cli._name}${commandName}${parametersString}${flagsString}`)]
   });
   if (subcommand.flags) {
     sections.push({
-      title: "Flags:",
+      title: FLAGS,
       body: splitTable(
         ...Object.entries(subcommand.flags).map(([name, flag]) => {
           const flagNameWithAlias = [gracefulFlagName(name)];
           if (flag.alias) {
             flagNameWithAlias.push(gracefulFlagName(flag.alias));
           }
-          const items = [pc.blue(flagNameWithAlias.map(kebabCase).join(", "))];
-          if (flag.description) {
-            items.push(DELIMITER, flag.description);
-          }
+          const items = [pc.blue(flagNameWithAlias.join(", "))];
+          items.push(DELIMITER, flag.description || NO_DESCRIPTION);
           if (flag.type) {
             const type = stringifyType(flag.type);
             items.push(pc.gray(`(${type})`));
@@ -162,14 +179,14 @@ const showSubcommandHelp = (ctx, command) => {
   }
   if (subcommand.notes) {
     sections.push({
-      title: "Notes:",
+      title: NOTES,
       body: subcommand.notes
     });
   }
   if (subcommand.examples) {
     generateExamples(sections, subcommand.examples);
   }
-  process.stdout.write(render(sections));
+  return render(sections);
 };
 const helpPlugin = ({
   command = true,
@@ -195,24 +212,31 @@ const helpPlugin = ({
         ]
       }).on("help", (ctx) => {
         if (ctx.parameters.command.length) {
-          showSubcommandHelp(ctx, ctx.parameters.command);
+          print(generateSubcommandHelp(ctx, ctx.parameters.command));
         } else {
-          showHelp(ctx, notes, examples);
+          print(generateHelp(ctx, notes, examples));
         }
       });
     }
     cli.inspector((ctx, next) => {
-      if (!ctx.isSingleCommand && !ctx.raw._.length && showHelpWhenNoCommand) {
-        showHelp(ctx, notes, examples);
-      } else if (ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help) {
+      const hasHelpFlag = ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help;
+      if (!ctx.hasSingleCommandOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !hasHelpFlag) {
+        let str = "No command supplied.\n\n";
+        str += generateHelp(ctx, notes, examples);
+        str += "\n";
+        print(str);
+        process.exit(1);
+      } else if (hasHelpFlag) {
         if (ctx.raw._.length) {
-          showSubcommandHelp(ctx, ctx.raw._);
-        } else {
-          if (!ctx.isSingleCommand) {
-            showHelp(ctx, notes, examples);
-          } else {
-            showSubcommandHelp(ctx, SingleCommand);
+          if (ctx.called !== SingleCommand) {
+            if (ctx.name === SingleCommand) {
+              print(generateHelp(ctx, notes, examples));
+            } else {
+              print(generateSubcommandHelp(ctx, ctx.raw._));
+            }
           }
+        } else {
+          print(generateHelp(ctx, notes, examples));
         }
       } else {
         next();

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { definePlugin, resolveCommand, NoSuchCommandError, SingleCommand } from '@clerc/core';
-import { toArray, gracefulFlagName, kebabCase } from '@clerc/utils';
+import { definePlugin, SingleCommand, resolveCommand, NoSuchCommandError } from '@clerc/core';
+import { toArray, gracefulFlagName } from '@clerc/utils';
 import pc from 'picocolors';
 import getFuncName from 'get-func-name';
 import { Table } from '@clerc/toolkit';
@@ -39,7 +39,7 @@ const render = (sections) => {
   const rendered = [];
   for (const section of sections) {
     if (section.type === "block" || !section.type) {
-      const indent = " ".repeat(4);
+      const indent = "    ";
       const formattedBody = section.body.map((line) => indent + line);
       formattedBody.unshift("");
       const body = formattedBody.join("\n");
@@ -55,22 +55,36 @@ const render = (sections) => {
 };
 
 const DELIMITER = pc.yellow("-");
-const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : "<Single Command>";
+const NO_DESCRIPTION = "(No description)";
+const SINGLE_COMMAND = "<Single Command>";
+const NAME = "Name:";
+const VERSION = "Version:";
+const COMMANDS = "Commands:";
+const SUBCOMMAND = "Subcommand:";
+const FLAGS = "Flags:";
+const DESCRIPTION = "Description:";
+const USAGE = "Usage:";
+const EXAMPLES = "Examples:";
+const NOTES = "Notes:";
+const print = (s) => {
+  process.stdout.write(s);
+};
+const formatCommandName = (name) => Array.isArray(name) ? name.join(" ") : typeof name === "string" ? name : SINGLE_COMMAND;
 const generateCliDetail = (sections, cli, subcommand) => {
   const items = [
     {
-      title: "Name:",
+      title: NAME,
       body: pc.red(cli._name)
     },
     {
-      title: "Version:",
+      title: VERSION,
       body: pc.yellow(cli._version)
     }
   ];
   if (subcommand) {
     items.push({
-      title: "Subcommand:",
-      body: pc.green(formatCommandName(subcommand.name))
+      title: SUBCOMMAND,
+      body: pc.green(`${cli._name} ${formatCommandName(subcommand.name)}`)
     });
   }
   sections.push({
@@ -78,53 +92,55 @@ const generateCliDetail = (sections, cli, subcommand) => {
     items
   });
   sections.push({
-    title: "Description:",
+    title: DESCRIPTION,
     body: [(subcommand == null ? void 0 : subcommand.description) || cli._description]
   });
 };
 const generateExamples = (sections, examples) => {
   const examplesFormatted = examples.map(([command, description]) => [command, DELIMITER, description]);
   sections.push({
-    title: "Examples:",
+    title: EXAMPLES,
     body: splitTable(...examplesFormatted)
   });
 };
-const showHelp = (ctx, notes, examples) => {
+const generateHelp = (ctx, notes, examples) => {
   const { cli } = ctx;
   const sections = [];
   generateCliDetail(sections, cli);
-  if (ctx.isSingleCommand) {
-    sections.push({
-      title: "Usage:",
-      body: [pc.magenta(`$ ${cli._name} [flags]`)]
-    });
-  } else {
-    sections.push({
-      title: "Usage:",
-      body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
-    });
-  }
-  if (!ctx.isSingleCommand) {
-    sections.push({
-      title: "Commands:",
-      body: splitTable(...Object.values(cli._commands).map((command) => {
-        const commandNameWithAlias = [command.name, ...toArray(command.alias || [])].join(", ");
-        return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
-      }))
-    });
-  }
+  sections.push({
+    title: USAGE,
+    body: [pc.magenta(`$ ${cli._name} [command] [flags]`)]
+  });
+  const commands = [...ctx.hasSingleCommand ? [cli._commands[SingleCommand]] : [], ...Object.values(cli._commands)].map((command) => {
+    const commandNameWithAlias = [typeof command.name === "symbol" ? "" : command.name, ...toArray(command.alias || [])].sort((a, b) => {
+      if (a === SingleCommand) {
+        return -1;
+      }
+      if (b === SingleCommand) {
+        return 1;
+      }
+      return a.length - b.length;
+    }).map((n) => {
+      return n === "" || typeof n === "symbol" ? `${cli._name}` : `${cli._name} ${n}`;
+    }).join(", ");
+    return [pc.cyan(commandNameWithAlias), DELIMITER, command.description];
+  });
+  sections.push({
+    title: COMMANDS,
+    body: splitTable(...commands)
+  });
   if (notes) {
     sections.push({
-      title: "Notes:",
+      title: NOTES,
       body: notes
     });
   }
   if (examples) {
     generateExamples(sections, examples);
   }
-  process.stdout.write(render(sections));
+  return render(sections);
 };
-const showSubcommandHelp = (ctx, command) => {
+const generateSubcommandHelp = (ctx, command) => {
   var _a;
   const { cli } = ctx;
   const subcommand = resolveCommand(cli._commands, command);
@@ -132,25 +148,26 @@ const showSubcommandHelp = (ctx, command) => {
     throw new NoSuchCommandError(formatCommandName(command));
   }
   const sections = [];
-  generateCliDetail(sections, cli, ctx.isSingleCommand ? void 0 : subcommand);
+  generateCliDetail(sections, cli, subcommand);
   const parameters = ((_a = subcommand.parameters) == null ? void 0 : _a.join(" ")) || void 0;
+  const commandName = ctx.name === SingleCommand ? "" : ` ${formatCommandName(subcommand.name)}`;
+  const parametersString = parameters ? ` ${parameters}` : "";
+  const flagsString = subcommand.flags ? " [flags]" : "";
   sections.push({
-    title: "Usage:",
-    body: [pc.magenta(`$ ${cli._name}${ctx.isSingleCommand ? "" : ` ${formatCommandName(subcommand.name)}`}${parameters ? ` ${parameters}` : ""} [flags]`)]
+    title: USAGE,
+    body: [pc.magenta(`$ ${cli._name}${commandName}${parametersString}${flagsString}`)]
   });
   if (subcommand.flags) {
     sections.push({
-      title: "Flags:",
+      title: FLAGS,
       body: splitTable(
         ...Object.entries(subcommand.flags).map(([name, flag]) => {
           const flagNameWithAlias = [gracefulFlagName(name)];
           if (flag.alias) {
             flagNameWithAlias.push(gracefulFlagName(flag.alias));
           }
-          const items = [pc.blue(flagNameWithAlias.map(kebabCase).join(", "))];
-          if (flag.description) {
-            items.push(DELIMITER, flag.description);
-          }
+          const items = [pc.blue(flagNameWithAlias.join(", "))];
+          items.push(DELIMITER, flag.description || NO_DESCRIPTION);
           if (flag.type) {
             const type = stringifyType(flag.type);
             items.push(pc.gray(`(${type})`));
@@ -162,14 +179,14 @@ const showSubcommandHelp = (ctx, command) => {
   }
   if (subcommand.notes) {
     sections.push({
-      title: "Notes:",
+      title: NOTES,
       body: subcommand.notes
     });
   }
   if (subcommand.examples) {
     generateExamples(sections, subcommand.examples);
   }
-  process.stdout.write(render(sections));
+  return render(sections);
 };
 const helpPlugin = ({
   command = true,
@@ -195,24 +212,31 @@ const helpPlugin = ({
         ]
       }).on("help", (ctx) => {
         if (ctx.parameters.command.length) {
-          showSubcommandHelp(ctx, ctx.parameters.command);
+          print(generateSubcommandHelp(ctx, ctx.parameters.command));
         } else {
-          showHelp(ctx, notes, examples);
+          print(generateHelp(ctx, notes, examples));
         }
       });
     }
     cli.inspector((ctx, next) => {
-      if (!ctx.isSingleCommand && !ctx.raw._.length && showHelpWhenNoCommand) {
-        showHelp(ctx, notes, examples);
-      } else if (ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help) {
+      const hasHelpFlag = ctx.raw.mergedFlags.h || ctx.raw.mergedFlags.help;
+      if (!ctx.hasSingleCommandOrAlias && !ctx.raw._.length && showHelpWhenNoCommand && !hasHelpFlag) {
+        let str = "No command supplied.\n\n";
+        str += generateHelp(ctx, notes, examples);
+        str += "\n";
+        print(str);
+        process.exit(1);
+      } else if (hasHelpFlag) {
         if (ctx.raw._.length) {
-          showSubcommandHelp(ctx, ctx.raw._);
-        } else {
-          if (!ctx.isSingleCommand) {
-            showHelp(ctx, notes, examples);
-          } else {
-            showSubcommandHelp(ctx, SingleCommand);
+          if (ctx.called !== SingleCommand) {
+            if (ctx.name === SingleCommand) {
+              print(generateHelp(ctx, notes, examples));
+            } else {
+              print(generateSubcommandHelp(ctx, ctx.raw._));
+            }
           }
+        } else {
+          print(generateHelp(ctx, notes, examples));
         }
       } else {
         next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/plugin-help",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "author": "Ray <nn_201312@163.com> (https://github.com/so1ve)",
   "description": "Clerc plugin help",
   "keywords": [
@@ -53,11 +53,11 @@
   "dependencies": {
     "get-func-name": "^2.0.0",
     "picocolors": "^1.0.0",
-    "@clerc/toolkit": "0.19.0",
-    "@clerc/utils": "0.19.0"
+    "@clerc/toolkit": "0.21.0",
+    "@clerc/utils": "0.21.0"
   },
   "devDependencies": {
-    "@clerc/core": "0.19.0"
+    "@clerc/core": "0.21.0"
   },
   "scripts": {
     "build": "puild",