[ELY-2082] Optimise Tool Help Text

pom.xml

@@ -100,6 +100,7 @@
         <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.keycloak.keycloak-services>3.1.0.Final</version.org.keycloak.keycloak-services>
+        <version.org.aesh>2.7</version.org.aesh>
 
         <test.level>INFO</test.level>
         <!-- Checkstyle configuration -->
@@ -1001,6 +1002,11 @@
                 <artifactId>jose4j</artifactId>
                 <version>${version.org.bitbucket.b_c.jose4j}</version>
             </dependency>
+            <dependency>
+                <groupId>org.aesh</groupId>
+                <artifactId>aesh</artifactId>
+                <version>${version.org.aesh}</version>
+            </dependency>
 
             <!--
                   Test Scope Only

tool/pom.xml

@@ -304,6 +304,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;
@@ -69,6 +68,10 @@
 import org.wildfly.security.password.interfaces.ClearPassword;
 import org.wildfly.security.pem.Pem;
 import org.wildfly.security.ssh.util.SshUtil;
+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 static org.wildfly.security.tool.Params.ALIAS_PARAM;
 import static org.wildfly.security.tool.Params.CREATE_CREDENTIAL_STORE_PARAM;
@@ -959,13 +962,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.
@@ -131,15 +138,27 @@ private static void configureLogManager() {
     }
 
     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());
+        commandsMap.put(FileSystemRealmIntegrityCommand.FILE_SYSTEM_REALM_INTEGRITY_COMMAND, ElytronToolMessages.msg.cmdFileSystemIntegrityHelpHeader());
+        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

@@ -105,25 +105,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")
@@ -159,7 +159,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")
@@ -281,7 +281,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" +
@@ -406,7 +406,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.")
@@ -489,7 +489,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" +
@@ -498,7 +498,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, populate, keystore, type, password, password-env, and key-pair 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, hash-charset, levels, secret-key, create, and populate are encrypted-filesystem-realm, BASE64, UTF-8, 2, key, true, and true respectively. %n" +
@@ -508,7 +508,7 @@ public interface ElytronToolMessages extends BasicLogger {
             "Blocks of options must be separated by a blank line.")
     String cmdFileSystemRealmEncryptBulkConvertDesc();
 
-    @Message(id = NONE, value = "Bulk conversion with options listed in description file. (Action)" +
+    @Message(id = NONE, value = "* Bulk conversion with options listed in description file. " +
             "Optional options have defaults and can be skipped ([type, default_or_NULL]), required options do not (<type>). %n" +
             "One of either password or password-env is required. %n" +
             "Blocks of options must be separated by a blank line; order is not important. Syntax: %n" +
@@ -519,7 +519,7 @@ public interface ElytronToolMessages extends BasicLogger {
     String cmdFileSystemRealmIntegrityBulkConvertDesc();
 
     // filesystem-realm encrypt command
-    @Message(id = NONE, value = "'FileSystemRealmEncrypt' command is used to convert non-empty, un-encrypted FileSystemSecurityRealm(s) to encrypted FileSystemSecurityRealm(s) with a SecretKey.")
+    @Message(id = NONE, value = "\"filesystem-realm-encrypt\" command is used to convert non-empty, un-encrypted FileSystemSecurityRealm(s) to encrypted FileSystemSecurityRealm(s) with a SecretKey.")
     String cmdFileSystemEncryptHelpHeader();
 
     @Message(id = NONE, value = "Secret Key was not found in the Credential Store at %s, and populate option was not set. Skipping descriptor file block number %d.")
@@ -669,7 +669,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).")
@@ -738,8 +738,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 a 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

@@ -65,14 +65,17 @@
 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;
 import org.wildfly.security.auth.realm.FileSystemRealmUtil;
 import org.wildfly.security.auth.realm.FileSystemSecurityRealm;
 import org.wildfly.security.auth.realm.FileSystemSecurityRealmBuilder;
 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.
@@ -576,13 +579,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

@@ -48,7 +48,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;
@@ -63,6 +62,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.
@@ -298,13 +301,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();
     }
 
     @Override