closes #27; changed command description to only show operation summary

README.md

@@ -166,7 +166,7 @@ The following commands are added to the CLI by default:
 | `clear-auth` | Clears the auth value(s) for the specified authorization scheme.                                                                                                                                                                                                                              |
 | `set-auth`   | Sets the value(s) required to fulfill a given authorization scheme accepted/required by the API. A `set-auth` sub-command is created for each scheme defined in the spec's `securityDefinitions` object. You can type `help set-auth` at the CLI prompt to list the schemes available to use. |
 | `exit`       | Exits the current CLI session and returns to the host command prompt.                                                                                                                                                                                                                         |
-| `help`       | Lists each command available in the CLI with a brief description of each. The usage pattern, including required and optional parameters, is also specified for each command.                                                                                                                  |
+| `help`       | Lists each command available in the CLI with a brief description of each. The usage pattern, required and optional parameters, and security requirements are also specified for each command.                                                                                                 |
 
 ## Options
 

src/operation-command-builder.ts

@@ -3,6 +3,7 @@ import * as _ from 'lodash';
 import { CommandGroupTypes } from './command-group-types';
 import * as commandOptionNames from './command-option-names';
 import { OperationCommandAction } from './operation-command-action';
+import { OperationCommandHelp } from './operation-command-help';
 import { OperationCommandInfo } from './operation-command-info';
 import { OperationCommandValidator } from './operation-command-validator';
 import { Options } from './options';
@@ -14,20 +15,10 @@ export class OperationCommandBuilder {
   public build(vorpal, options: Options, commandInfo: OperationCommandInfo) {
     const commandString = buildCommandString(options, commandInfo);
 
-    const commandDescriptionBuilder = new TextBuilder();
-    commandDescriptionBuilder.addParagraph(commandInfo.operation.summary);
-    if (
-      commandInfo.operation.description &&
-      commandInfo.operation.description.length > 0
-    ) {
-      commandDescriptionBuilder.addParagraph(
-        commandInfo.operation.description,
-        '\n\n  '
-      );
-    }
-    const commandDescription = commandDescriptionBuilder.toString();
-
-    const command = vorpal.command(commandString, commandDescription);
+    const command = vorpal.command(
+      commandString,
+      commandInfo.operation.summary
+    );
 
     // add command alias if command is being grouped (to provide a shorter command string to invoke it with)
     if (
@@ -83,6 +74,14 @@ export class OperationCommandBuilder {
       command.option(optionString, optionDescription, optionAutocomplete);
     }
 
+    // help() does seem to support functions that return a promise, so the callback needs to be used
+    // to return the help text to be displayed
+    const help = new OperationCommandHelp(command, commandInfo);
+    command.help((commandStr, cb) => {
+      const helpText = help.build(commandStr);
+      cb(helpText);
+    });
+
     const validator = new OperationCommandValidator(commandInfo, vorpal);
     command.validate(args => validator.validate(args));
 

src/operation-command-help.ts

@@ -0,0 +1,63 @@
+import * as _ from 'lodash';
+
+import { OperationCommandInfo } from './operation-command-info';
+import { TextBuilder } from './text-builder';
+
+export class OperationCommandHelp {
+  constructor(private command, private commandInfo: OperationCommandInfo) {}
+
+  public build(command: string): string {
+    const helpBuilder = new TextBuilder();
+
+    // add the operation summary to the command description so it can be
+    // displayed using the default help logic, then reset to the original
+    // value afterwards
+    const oldDescription = this.command._description;
+    if (
+      this.commandInfo.operation.description &&
+      this.commandInfo.operation.description.length > 0
+    ) {
+      this.command._description +=
+        '\n\n  ' + this.commandInfo.operation.description;
+    }
+    helpBuilder.add(this.command.helpInformation());
+    this.command._description = oldDescription;
+
+    // list security requirements (and any required scopes)
+    if (
+      this.commandInfo.operation.security &&
+      this.commandInfo.operation.security.length > 0
+    ) {
+      let securityList = '';
+
+      for (const requirement of this.commandInfo.operation.security) {
+        securityList += '    - ';
+
+        const andSchemeNames = _.keys(requirement);
+        for (
+          let nameIndex = 0;
+          nameIndex < andSchemeNames.length;
+          nameIndex++
+        ) {
+          const name = andSchemeNames[nameIndex];
+
+          if (nameIndex > 0) {
+            securityList += '\n      ';
+          }
+
+          securityList += name;
+
+          const scopes = requirement[name];
+          if (scopes && scopes.length > 0) {
+            securityList += ' (' + scopes.join(', ') + ')';
+          }
+        }
+      }
+
+      helpBuilder.addParagraph('  Required Security:\n\n' + securityList, '\n');
+      helpBuilder.addLine();
+    }
+
+    return helpBuilder.toString();
+  }
+}