MID-8842 ninja - help command + updated -h behavior (by default only …

…lists commands)

(cherry picked from commit b8cfff1)

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/Main.java

@@ -14,7 +14,6 @@
 import java.util.List;
 import java.util.Objects;
 
-import com.beust.jcommander.IUsageFormatter;
 import com.beust.jcommander.JCommander;
 import com.beust.jcommander.ParameterException;
 import org.apache.commons.io.IOUtils;
@@ -122,7 +121,10 @@ public void setErr(@NotNull PrintStream err) {
             try {
                 action.init(context, options);
 
-                context.getLog().info(ConsoleFormat.formatActionStartMessage(action));
+                String startMessage = ConsoleFormat.formatActionStartMessage(action);
+                if (startMessage != null) {
+                    context.getLog().info(startMessage);
+                }
 
                 Object result = action.execute();
                 if (result instanceof ActionResult) {
@@ -200,15 +202,8 @@ private void printException(String message, Exception ex, boolean verbose) {
     }
 
     private void printHelp(JCommander jc, String parsedCommand) {
-        StringBuilder sb = new StringBuilder();
-
-        IUsageFormatter formatter = jc.getUsageFormatter();
-        if (parsedCommand != null) {
-            formatter.usage(parsedCommand, sb);
-        } else {
-            formatter.usage(sb);
-        }
+        String help = NinjaUtils.createHelp(jc, parsedCommand);
 
-        out.println(sb);
+        out.println(help);
     }
 }

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/action/HelpAction.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (C) 2010-2023 Evolveum and contributors
+ *
+ * This work is dual-licensed under the Apache License 2.0
+ * and European Union Public License. See LICENSE file for details.
+ */
+
+package com.evolveum.midpoint.ninja.action;
+
+import java.util.List;
+
+import com.beust.jcommander.JCommander;
+import org.apache.commons.lang3.StringUtils;
+
+import com.evolveum.midpoint.ninja.util.NinjaUtils;
+
+public class HelpAction extends Action<HelpOptions, ActionResult> {
+
+    @Override
+    public String getOperationName() {
+        return null;
+    }
+
+    @Override
+    public ActionResult execute() throws Exception {
+        String command = options.getCommand();
+
+        JCommander jc = NinjaUtils.setupCommandLineParser();
+
+        if (StringUtils.isNotEmpty(command)) {
+            JCommander specific = jc.getCommands().get(command);
+            if (specific == null) {
+                log.error(
+                        "Unknown command {}, known commands: {}",
+                        command,
+                        StringUtils.join(", ", List.of(jc.getCommands().keySet()).stream().sorted()));
+                return new ActionResult(null, 1);
+            }
+        }
+
+        String help = NinjaUtils.createHelp(jc, command);
+        context.out.println(help);
+
+        return new ActionResult<>(null, 0);
+    }
+}

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/action/HelpOptions.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2010-2023 Evolveum and contributors
+ *
+ * This work is dual-licensed under the Apache License 2.0
+ * and European Union Public License. See LICENSE file for details.
+ */
+
+package com.evolveum.midpoint.ninja.action;
+
+import com.beust.jcommander.Parameter;
+import com.beust.jcommander.Parameters;
+
+/**
+ * Created by Viliam Repan (lazyman).
+ */
+@Parameters(resourceBundle = "messages", commandDescriptionKey = "help")
+public class HelpOptions {
+
+    @Parameter(descriptionKey = "help.command")
+    private String command;
+
+    public String getCommand() {
+        return command;
+    }
+
+    public void setCommand(String command) {
+        this.command = command;
+    }
+}

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/impl/Command.java

@@ -54,7 +54,9 @@ public enum Command {
 
     UPGRADE_OBJECTS("upgrade-objects", UpgradeObjectsOptions.class, UpgradeObjectsAction.class),
 
-    PRE_UPGRADE_CHECK("pre-upgrade-check", PreUpgradeCheckOptions.class, PreUpgradeCheckAction.class);
+    PRE_UPGRADE_CHECK("pre-upgrade-check", PreUpgradeCheckOptions.class, PreUpgradeCheckAction.class),
+
+    HELP("help", HelpOptions.class, HelpAction.class);
 
     private final String commandName;
 

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/impl/NinjaUsageFormatter.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2010-2023 Evolveum and contributors
+ *
+ * This work is dual-licensed under the Apache License 2.0
+ * and European Union Public License. See LICENSE file for details.
+ */
+
+package com.evolveum.midpoint.ninja.impl;
+
+import java.util.Map;
+
+import com.beust.jcommander.DefaultUsageFormatter;
+import com.beust.jcommander.JCommander;
+import com.beust.jcommander.Parameters;
+
+public class NinjaUsageFormatter extends DefaultUsageFormatter {
+
+    private JCommander commander;
+
+    public NinjaUsageFormatter(JCommander commander) {
+        super(commander);
+
+        this.commander = commander;
+    }
+
+    @Override
+    public void appendCommands(StringBuilder out, int indentCount, int descriptionIndent, String indent) {
+        out.append(indent + "\n  Commands:\n\n");
+
+        int maxCommandNameLength = commander.getRawCommands().keySet().stream()
+                .map(pn -> pn.getDisplayName().length())
+                .max(Integer::compareTo).orElse(0);
+
+        // The magic value 3 is the number of spaces between the name of the option and its description
+        for (Map.Entry<JCommander.ProgramName, JCommander> commands : commander.getRawCommands().entrySet()) {
+            Object arg = commands.getValue().getObjects().get(0);
+            Parameters p = arg.getClass().getAnnotation(Parameters.class);
+
+            if (p == null || !p.hidden()) {
+                JCommander.ProgramName progName = commands.getKey();
+                String dispName = progName.getDisplayName() + s(maxCommandNameLength - progName.getDisplayName().length() + 3);
+
+                String description = indent + s(4) + dispName + getCommandDescription(progName.getName());
+
+                wrapDescription(out, indentCount + descriptionIndent, description);
+                out.append("\n");
+            }
+        }
+    }
+}

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/util/ConsoleFormat.java

@@ -5,6 +5,8 @@
 import com.evolveum.midpoint.ninja.action.Action;
 import com.evolveum.midpoint.ninja.impl.LogLevel;
 
+import javax.annotation.Nullable;
+
 public final class ConsoleFormat {
 
     public enum Color {
@@ -37,8 +39,12 @@ public static boolean isBatchMode() {
         return Ansi.isEnabled();
     }
 
-    public static String formatActionStartMessage(Action action) {
+    public static @Nullable String formatActionStartMessage(Action action) {
         String operation = action.getOperationName();
+        if (operation == null) {
+            return null;
+        }
+
         return Ansi.ansi().a("Starting ").fgGreen().a(operation).reset().toString();
     }
 

tools/ninja/src/main/java/com/evolveum/midpoint/ninja/util/NinjaUtils.java

@@ -17,7 +17,11 @@
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipOutputStream;
 
+import com.beust.jcommander.IUsageFormatter;
 import com.beust.jcommander.JCommander;
+
+import com.evolveum.midpoint.ninja.impl.NinjaUsageFormatter;
+
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.FilenameUtils;
 
@@ -79,6 +83,7 @@ public static JCommander setupCommandLineParser() {
         jc.setProgramName("java [-Dloader.path=<jdbc_driver_jar_path>] -jar ninja.jar");
         jc.setColumnSize(110);
         jc.setAtFileCharset(Charset.forName(base.getCharset()));
+        jc.setUsageFormatter(new NinjaUsageFormatter(jc));
 
         return jc;
     }
@@ -308,4 +313,17 @@ public static String printFormatted(String message, Object... args) {
 
         return sb.toString();
     }
+
+    public static String createHelp(JCommander jc, String parsedCommand) {
+        StringBuilder sb = new StringBuilder();
+
+        IUsageFormatter formatter = jc.getUsageFormatter();
+        if (parsedCommand != null) {
+            formatter.usage(parsedCommand, sb);
+        } else {
+            formatter.usage(sb);
+        }
+
+        return sb.toString();
+    }
 }

tools/ninja/src/main/resources/messages.properties

@@ -144,3 +144,5 @@ upgradeObjects.priorities=Upgrade priority.
 downloadDistribution=Download target midPoint distribution (latest LTS).
 upgradeObjects.skipUpgradeWarning=Skip warning about files being updated.
 upgradeDistribution.distributionDirectory=Distribution directory where distribution ZIP file should be expanded as output of this command.
+help=Print this help, or prints help for specific command.
+help.command=[Command name]

tools/ninja/src/test/java/com/evolveum/midpoint/ninja/HelpVersionTest.java

@@ -9,6 +9,8 @@
 
 import java.io.File;
 import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
 
 import org.apache.commons.io.FileUtils;
 import org.assertj.core.api.Assertions;
@@ -23,19 +25,42 @@ public class HelpVersionTest implements NinjaTestMixin {
 
     @Test
     public void test100FullHelp() throws Exception {
-        executeTest(list -> Assertions.assertThat(list).isNotEmpty(),
-                EMPTY_STREAM_VALIDATOR,
-                "-h");
+        validateHelp(null);
     }
 
     @Test
     public void test200HelpForCommands() throws Exception {
         for (Command command : Command.values()) {
-            executeTest(
-                    list -> Assertions.assertThat(list).isNotEmpty(),
-                    EMPTY_STREAM_VALIDATOR,
-                    "-h", command.getCommandName());
+            validateHelp(command.getCommandName());
+        }
+    }
+
+    private void validateHelp(String command) throws Exception {
+
+        String[] args;
+        if (command == null) {
+            args = new String[] { "-h" };
+        } else {
+            args = new String[] { "-h", command };
+        }
+
+        List<String> result1 = new ArrayList<>();
+        executeTest(list -> result1.addAll(list),
+                EMPTY_STREAM_VALIDATOR,
+                args);
+
+        if (command == null) {
+            args = new String[] { "help" };
+        } else {
+            args = new String[] { "help", command };
         }
+
+        List<String> result2 = new ArrayList<>();
+        executeTest(list -> result2.addAll(list),
+                EMPTY_STREAM_VALIDATOR,
+                args);
+
+        Assertions.assertThat(result1).isEqualTo(result2);
     }
 
     @Test