[ELY-2082] Optimise Tool Help Text

pom.xml

@@ -104,6 +104,7 @@
         <version.io.rest-assured>4.3.3</version.io.rest-assured>
         <version.net.sourceforge.htmlunit.htmlunit>2.40.0</version.net.sourceforge.htmlunit.htmlunit>
         <version.org.apache.santuario>2.3.0</version.org.apache.santuario>
+        <version.org.aesh>2.4</version.org.aesh>
 
         <test.level>INFO</test.level>
         <!-- Checkstyle configuration -->
@@ -456,6 +457,11 @@
              <!--
                  Local Modules
             -->
+            <dependency>
+                <groupId>org.aesh</groupId>
+                <artifactId>aesh</artifactId>
+                <version>${version.org.aesh}</version>
+            </dependency>
             <dependency>
                 <groupId>org.wildfly.security</groupId>
                 <artifactId>wildfly-elytron-asn1</artifactId>

tool/pom.xml

@@ -301,6 +301,10 @@
             <artifactId>jboss-logging-processor</artifactId>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>org.aesh</groupId>
+            <artifactId>aesh</artifactId>
+        </dependency>
         <!--
               Test Scope Only
          -->

tool/src/main/java/org/wildfly/security/tool/CredentialStoreCommand.java

@@ -46,7 +46,6 @@
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.DefaultParser;
-import org.apache.commons.cli.HelpFormatter;
 import org.apache.commons.cli.Option;
 import org.apache.commons.cli.OptionGroup;
 import org.apache.commons.cli.Options;
@@ -68,6 +67,10 @@
 import org.wildfly.security.password.Password;
 import org.wildfly.security.password.interfaces.ClearPassword;
 import org.wildfly.security.pem.Pem;
+import org.wildfly.security.tool.help.DescriptionSection;
+import org.wildfly.security.tool.help.HelpCommand;
+import org.wildfly.security.tool.help.OptionsSection;
+import org.wildfly.security.tool.help.UsageSection;
 
 /**
  * Credential Store Command
@@ -958,13 +961,15 @@ protected Set<String> aliases() {
      */
     @Override
     public void help() {
-        HelpFormatter help = new HelpFormatter();
-        help.setWidth(WIDTH);
-        help.printHelp(ElytronToolMessages.msg.cmdHelp(getToolCommand(), CREDENTIAL_STORE_COMMAND),
-                ElytronToolMessages.msg.cmdLineCredentialStoreHelpHeader().concat(ElytronToolMessages.msg.cmdLineActionsHelpHeader()),
-                options,
-                "",
-                true);
+        OptionsSection optionsSection = new OptionsSection(ElytronToolMessages.msg.cmdLineActionsHelpHeader(), options);
+        UsageSection usageSection = new UsageSection(CREDENTIAL_STORE_COMMAND, null);
+        DescriptionSection descriptionSection = new DescriptionSection(ElytronToolMessages.msg.cmdLineCredentialStoreHelpHeader());
+        HelpCommand helpCommand = HelpCommand.HelpCommandBuilder.builder()
+                .description(descriptionSection)
+                .usage(usageSection)
+                .options(optionsSection)
+                .build();
+        helpCommand.printHelp();
     }
 
     static Map<String, String> parseCredentialStoreProperties(final String attributeString) {

tool/src/main/java/org/wildfly/security/tool/ElytronTool.java

@@ -20,10 +20,17 @@
 import org.apache.commons.cli.AlreadySelectedException;
 import org.apache.commons.cli.Option;
 import org.wildfly.security.WildFlyElytronProvider;
+import org.wildfly.security.tool.help.CommandsSection;
+import org.wildfly.security.tool.help.DescriptionSection;
+import org.wildfly.security.tool.help.HelpCommand;
+import org.wildfly.security.tool.help.OptionsSection;
+import org.wildfly.security.tool.help.UsageSection;
 
 import java.security.Security;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.SortedMap;
+import java.util.TreeMap;
 
 /**
  * Elytron Tool main class which drives all registered commands.
@@ -122,15 +129,26 @@ public static void main(String[] args) {
     }
 
     private void generalHelp() {
-        System.out.print(ElytronToolMessages.msg.generalHelpTitle());
-        System.out.println();
-        for (Command c: commandRegistry.values()) {
-            if (scriptName != null) {
-                c.setToolCommand(scriptName);
-            }
-            c.help();
-            System.out.println();
-        }
+        DescriptionSection descriptionSection = new DescriptionSection(ElytronToolMessages.msg.cmdElytronToolDescription());
+        UsageSection usageSection = new UsageSection(null, null);
+        OptionsSection optionsSection = new OptionsSection(ElytronToolMessages.msg.generalHelpOptionsOpening(), null);
+
+        // Using SortedMap so commands are in alphabetical order
+        SortedMap<String, String> commandsMap = new TreeMap<>();
+        commandsMap.put(CredentialStoreCommand.CREDENTIAL_STORE_COMMAND, ElytronToolMessages.msg.cmdLineCredentialStoreHelpHeader());
+        commandsMap.put(VaultCommand.VAULT_COMMAND, ElytronToolMessages.msg.cmdVaultHelpHeader());
+        commandsMap.put(FileSystemRealmCommand.FILE_SYSTEM_REALM_COMMAND, ElytronToolMessages.msg.cmdFileSystemRealmHelpHeader());
+        commandsMap.put(FileSystemEncryptRealmCommand.FILE_SYSTEM_ENCRYPT_COMMAND, ElytronToolMessages.msg.cmdFileSystemEncryptHelpHeader());
+        commandsMap.put(MaskCommand.MASK_COMMAND, ElytronToolMessages.msg.cmdMaskHelpHeader());
+        CommandsSection commandsSection = new CommandsSection(commandsMap);
+
+        HelpCommand helpCommand = HelpCommand.HelpCommandBuilder.builder()
+                .description(descriptionSection)
+                .usage(usageSection)
+                .options(optionsSection)
+                .commands(commandsSection)
+                .build();
+        helpCommand.printHelp();
     }
 
     Command findCommand(String commandName) {

tool/src/main/java/org/wildfly/security/tool/ElytronToolMessages.java

@@ -99,25 +99,25 @@ public interface ElytronToolMessages extends BasicLogger {
             "Provider must be installed through java.security file or through service loader from properly packaged jar file on classpath.")
     String cmdLineCustomCredentialStoreProviderDesc();
 
-    @Message(id = NONE, value = "Create credential store (Action)")
+    @Message(id = NONE, value = "* Create credential store")
     String cmdLineCreateCredentialStoreDesc();
 
     @Message(id = NONE, value = "Credential store type")
     String cmdLineCredentialStoreTypeDesc();
 
-    @Message(id = NONE, value = "Add new alias to the credential store (Action)")
+    @Message(id = NONE, value = "* Add new alias to the credential store")
     String cmdLineAddAliasDesc();
 
-    @Message(id = NONE, value = "Remove alias from the credential store (Action)")
+    @Message(id = NONE, value = "* Remove alias from the credential store")
     String cmdLineRemoveAliasDesc();
 
-    @Message(id = NONE, value = "Check if alias exists within the credential store (Action)")
+    @Message(id = NONE, value = "* Check if alias exists within the credential store")
     String cmdLineCheckAliasDesc();
 
-    @Message(id = NONE, value = "Display all aliases (Action)")
+    @Message(id = NONE, value = "* Display all aliases")
     String cmdLineAliasesDesc();
 
-    @Message(id = NONE, value = "Display all types of stored credentials for given alias (Action)")
+    @Message(id = NONE, value = "* Display all types of stored credentials for given alias")
     String cmdLineAliasTypes();
 
     @Message(id = NONE, value = "Generate private and public key pair and store them as a KeyPairCredential")
@@ -153,7 +153,7 @@ public interface ElytronToolMessages extends BasicLogger {
     @Message(id = NONE, value = "Print summary, especially command how to create this credential store")
     String cmdLinePrintSummary();
 
-    @Message(id = NONE, value = "Get help with usage of this command (Action)")
+    @Message(id = NONE, value = "* Get help with usage of this command")
     String cmdLineHelp();
 
     @Message(id = NONE, value = "Alias \"%s\" exists")
@@ -275,7 +275,7 @@ public interface ElytronToolMessages extends BasicLogger {
     @Message(id = NONE, value = "CLI command to add new credential store:%n")
     String cliCommandToNewCredentialStore();
 
-    @Message(id = NONE, value = "Bulk conversion with options listed in description file. All options have no default value and should be set in the file. (Action)%n" +
+    @Message(id = NONE, value = "* Bulk conversion with options listed in description file. All options have no default value and should be set in the file.%n" +
                                 "All options are required with the exceptions:%n" +
                                 " - \"properties\" option%n - \"type\" option (defaults to \"KeyStoreCredentialStore\")%n - \"credential-store-provider\" option%n - \"other-providers\" option%n" +
                                 " - \"salt\" and \"iteration\" options can be omitted when plain-text password is used%n" +
@@ -400,7 +400,7 @@ public interface ElytronToolMessages extends BasicLogger {
     String longOptionDescription(String option, String longOption);
 
     // filesystem-realm command
-    @Message(id = NONE, value = "'FileSystemRealm' command is used to convert legacy properties files and scripts to an Elytron FileSystemRealm.")
+    @Message(id = NONE, value = "\"filesystem-realm\" command is used to convert legacy properties files and scripts to an Elytron FileSystemRealm.")
     String cmdFileSystemRealmHelpHeader();
 
     @Message(id = NONE, value = "The relative or absolute path to the users file.")
@@ -463,7 +463,7 @@ public interface ElytronToolMessages extends BasicLogger {
     @Message(id = NONE, value = "Name of the security-domain to be configured.")
     String cmdFileSystemRealmSecurityDomainNameDesc();
 
-    @Message(id = NONE, value = "Bulk conversion with options listed in description file. Optional options have default values, required options do not. (Action) %n" +
+    @Message(id = NONE, value = "* Bulk conversion with options listed in description file. Optional options have default values, required options do not.%n" +
             "The options fileSystemRealmName and securityDomainName are optional. %n" +
             "These optional options have default values of: converted-properties-filesystem-realm and converted-properties-security-domain. %n" +
             "Values are required for the following options: users-file, roles-file, and output-location. %n" +
@@ -472,7 +472,7 @@ public interface ElytronToolMessages extends BasicLogger {
             "Blocks of options must be separated by a blank line.")
     String cmdFileSystemRealmBulkConvertDesc();
 
-    @Message(id = NONE, value = "Bulk conversion with options listed in description file. Optional options have default values, required options do not. (Action) %n" +
+    @Message(id = NONE, value = "* Bulk conversion with options listed in description file. Optional options have default values, required options do not. %n" +
             "The options realm-name, hash-encoding, levels, secret-key, create, and populate are optional. %n" +
             "Values are required for the following options: input-location, output-location, and credential-store. %n" +
             "The default values of realm-name, hash-encoding, levels, secret-key, create, and populate are encrypted-filesystem-realm, BASE64, 2, key, true, and true respectively. %n" +
@@ -482,7 +482,7 @@ public interface ElytronToolMessages extends BasicLogger {
     String cmdFileSystemRealmEncryptBulkConvertDesc();
 
     // filesystem-realm encrypt command
-    @Message(id = NONE, value = "'FileSystemRealmEncrypt' command is used to convert un-encrypted FileSystemSecurityRealm(s) to encrypted FileSystemSecurityRealm(s) with a SecretKey.")
+    @Message(id = NONE, value = "\"filesystem-realm-encrypt\" command is used to convert un-encrypted FileSystemSecurityRealm(s) to encrypted FileSystemSecurityRealm(s) with a SecretKey.")
     String cmdFileSystemEncryptHelpHeader();
 
     @Message(id = NONE, value = "The populate parameter was set to false and the Secret Key did not exist in the Credential Store.")
@@ -540,7 +540,7 @@ public interface ElytronToolMessages extends BasicLogger {
     @Message(id = NONE, value = "Should file %s be overwritten? (y/n) ")
     String shouldFileBeOverwritten(String file);
 
-    @Message(id = NONE, value = "\nSome of the parameters below are mutually exclusive actions which are marked with (Action) in the description.")
+    @Message(id = NONE, value = "Some of the parameters below are mutually exclusive actions which are marked with * in the description.")
     String cmdLineActionsHelpHeader();
 
     @Message(id = NONE, value = "Key size (bits).")
@@ -603,8 +603,13 @@ public interface ElytronToolMessages extends BasicLogger {
     @Message(id = NONE, value = "No Credential Store location or Secret Key Alias specified.")
     MissingOptionException missingCredentialStoreSecretKey();
 
+    @Message(id = NONE, value = "To get list of options for specific command, please specify the command by using ./elytron-tool.sh [command] --help")
+    String generalHelpOptionsOpening();
+
+    @Message(id = NONE, value = "A tool that assists with Elytron configuration")
+    String cmdElytronToolDescription();
+
     // Numeric Errors
     @Message(id = 35, value = "Only one of '%s' and '%s' can be specified at the same time")
     IllegalArgumentException mutuallyExclusiveOptions(String first, String second);
-
 }

tool/src/main/java/org/wildfly/security/tool/FileSystemEncryptRealmCommand.java

@@ -38,7 +38,6 @@
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.DefaultParser;
-import org.apache.commons.cli.HelpFormatter;
 import org.apache.commons.cli.Option;
 import org.apache.commons.cli.Options;
 import org.wildfly.security.auth.realm.FileSystemRealmUtil;
@@ -50,6 +49,10 @@
 import org.wildfly.security.encryption.SecretKeyUtil;
 import org.wildfly.security.password.WildFlyElytronPasswordProvider;
 import org.wildfly.security.password.spec.Encoding;
+import org.wildfly.security.tool.help.DescriptionSection;
+import org.wildfly.security.tool.help.HelpCommand;
+import org.wildfly.security.tool.help.OptionsSection;
+import org.wildfly.security.tool.help.UsageSection;
 
 /**
  * Elytron-Tool command to convert un-encrypted FileSystemRealms into an encrypted realm with the use of a SecretKey.
@@ -429,13 +432,15 @@ public void execute(String[] args) throws Exception {
      */
     @Override
     public void help() {
-        HelpFormatter help = new HelpFormatter();
-        help.setWidth(WIDTH);
-        help.printHelp(ElytronToolMessages.msg.cmdHelp(getToolCommand(), FILE_SYSTEM_ENCRYPT_COMMAND),
-                ElytronToolMessages.msg.cmdFileSystemEncryptHelpHeader(),
-                options,
-                "",
-                true);
+        OptionsSection optionsSection = new OptionsSection(ElytronToolMessages.msg.cmdLineActionsHelpHeader(), options);
+        UsageSection usageSection = new UsageSection(FILE_SYSTEM_ENCRYPT_COMMAND, null);
+        DescriptionSection descriptionSection = new DescriptionSection(ElytronToolMessages.msg.cmdFileSystemEncryptHelpHeader());
+        HelpCommand helpCommand = HelpCommand.HelpCommandBuilder.builder()
+                .description(descriptionSection)
+                .usage(usageSection)
+                .options(optionsSection)
+                .build();
+        helpCommand.printHelp();
     }
 
     /**

tool/src/main/java/org/wildfly/security/tool/FileSystemRealmCommand.java

@@ -36,7 +36,6 @@
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.DefaultParser;
-import org.apache.commons.cli.HelpFormatter;
 import org.apache.commons.cli.Option;
 import org.apache.commons.cli.Options;
 import org.apache.commons.lang3.ArrayUtils;
@@ -51,6 +50,10 @@
 import org.wildfly.security.password.interfaces.DigestPassword;
 import org.wildfly.security.password.spec.DigestPasswordSpec;
 import org.wildfly.security.password.spec.PasswordSpec;
+import org.wildfly.security.tool.help.DescriptionSection;
+import org.wildfly.security.tool.help.HelpCommand;
+import org.wildfly.security.tool.help.OptionsSection;
+import org.wildfly.security.tool.help.UsageSection;
 
 /**
  * Elytron-Tool command to convert legacy properties file into a FileSystemRealm.
@@ -297,13 +300,15 @@ public void execute(String[] args) throws Exception {
      */
     @Override
     public void help() {
-        HelpFormatter help = new HelpFormatter();
-        help.setWidth(WIDTH);
-        help.printHelp(ElytronToolMessages.msg.cmdHelp(getToolCommand(), FILE_SYSTEM_REALM_COMMAND),
-                ElytronToolMessages.msg.cmdFileSystemRealmHelpHeader().concat(ElytronToolMessages.msg.cmdLineActionsHelpHeader()),
-                options,
-                "",
-                true);
+        OptionsSection optionsSection = new OptionsSection(ElytronToolMessages.msg.cmdLineActionsHelpHeader(), options);
+        UsageSection usageSection = new UsageSection(FILE_SYSTEM_REALM_COMMAND, null);
+        DescriptionSection descriptionSection = new DescriptionSection(ElytronToolMessages.msg.cmdFileSystemRealmHelpHeader());
+        HelpCommand helpCommand = HelpCommand.HelpCommandBuilder.builder()
+                .description(descriptionSection)
+                .usage(usageSection)
+                .options(optionsSection)
+                .build();
+        helpCommand.printHelp();
     }
 
     /**

tool/src/main/java/org/wildfly/security/tool/MaskCommand.java

@@ -23,9 +23,12 @@
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.DefaultParser;
-import org.apache.commons.cli.HelpFormatter;
 import org.apache.commons.cli.Option;
 import org.apache.commons.cli.Options;
+import org.wildfly.security.tool.help.DescriptionSection;
+import org.wildfly.security.tool.help.HelpCommand;
+import org.wildfly.security.tool.help.OptionsSection;
+import org.wildfly.security.tool.help.UsageSection;
 import org.wildfly.security.util.PasswordBasedEncryptionUtil;
 
 import static org.wildfly.security.util.PasswordUtil.generateSecureRandomString;
@@ -159,12 +162,14 @@ static char[] decryptMasked(String maskedPassword) throws GeneralSecurityExcepti
      */
     @Override
     public void help() {
-        HelpFormatter help = new HelpFormatter();
-        help.setWidth(WIDTH);
-        help.printHelp(ElytronToolMessages.msg.cmdHelp(getToolCommand(), MASK_COMMAND),
-                ElytronToolMessages.msg.cmdMaskHelpHeader().concat(ElytronToolMessages.msg.cmdLineActionsHelpHeader()),
-                options,
-                "",
-                true);
+        OptionsSection optionsSection = new OptionsSection(ElytronToolMessages.msg.cmdLineActionsHelpHeader(), options);
+        UsageSection usageSection = new UsageSection(MASK_COMMAND, null);
+        DescriptionSection descriptionSection = new DescriptionSection(ElytronToolMessages.msg.cmdMaskHelpHeader());
+        HelpCommand helpCommand = HelpCommand.HelpCommandBuilder.builder()
+                .description(descriptionSection)
+                .usage(usageSection)
+                .options(optionsSection)
+                .build();
+        helpCommand.printHelp();
     }
 }