cli: normalize command line args

pom.xml

@@ -143,7 +143,7 @@
         <jsoup.version>1.15.3</jsoup.version>
         <freemarker.version>2.3.30</freemarker.version>
         <commons-io.version>2.14.0</commons-io.version>
-        <commons-cli.version>1.4</commons-cli.version>
+        <commons-cli.version>1.10.0</commons-cli.version>
         <commons-csv.version>1.8</commons-csv.version>
         <commons-compress.version>1.21</commons-compress.version>
         <commons-lang3.version>3.18.0</commons-lang3.version>

znai-cli/src/main/java/org/testingisdocumenting/znai/cli/ZnaiCliApp.java

@@ -69,7 +69,7 @@ public static void start(ZnaiCliConfig cliConfig) {
 
     public static void main(String[] args) {
         ConsoleOutputs.add(new AnsiConsoleOutput());
-        start(new ZnaiCliConfig(args));
+        start(new ZnaiCliConfig(System::exit, args));
     }
 
     private String getDocId() {

znai-cli/src/test/groovy/org/testingisdocumenting/znai/cli/ZnaiCliConfigTest.groovy

@@ -1,4 +1,5 @@
 /*
+ * Copyright 2025 znai maintainers
  * Copyright 2019 TWO SIGMA OPEN SOURCE, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,18 +17,157 @@
 
 package org.testingisdocumenting.znai.cli
 
+import org.apache.commons.cli.Options
+import org.junit.BeforeClass
 import org.junit.Test
+import org.testingisdocumenting.znai.console.ConsoleOutputs
+import org.testingisdocumenting.znai.console.ansi.AnsiConsoleOutput
+
+import static org.testingisdocumenting.znai.cli.ZnaiCliConfig.Command
+import static org.testingisdocumenting.znai.cli.ZnaiCliConfig.OptionKey
 
 class ZnaiCliConfigTest {
+    static AnsiConsoleOutput consoleOutput = new AnsiConsoleOutput()
+
+    @BeforeClass
+    static void init() {
+        ConsoleOutputs.add(consoleOutput)
+    }
+
+    @BeforeClass
+    static void tearDown() {
+        ConsoleOutputs.remove(consoleOutput)
+    }
+
     @Test
-    void "mode as string"() {
+    void "legacy mode as string"() {
         mode('--deploy=location').should == 'build'
         mode('--doc-id=my-doc').should == 'build'
         mode('--preview').should == 'preview'
         mode('--export=my-dir').should == 'export'
     }
 
+    @Test
+    void "new command mode as string"() {
+        mode('build', '--deploy=location').should == 'build'
+        mode('build', '--doc-id=my-doc').should == 'build'
+        mode('preview').should == 'preview'
+        mode('preview', '--port=4000').should == 'preview'
+        mode('export', 'my-dir').should == 'export'
+        mode('new').should == 'scaffold new'
+        mode('serve').should == 'serve'
+    }
+
+    @Test
+    void "defaults to build when no command specified"() {
+        mode('--source=docs').should == 'build'
+        mode('some-path').should == 'build'
+    }
+
+    @Test
+    void "preview command includes server and SSL options"() {
+        def options = createOptionsForCommand(Command.PREVIEW, '--source=test')
+
+        assertOnlyTheseOptions(options,
+            OptionKey.HOST,
+            OptionKey.PORT,
+            OptionKey.DEPLOY,
+            OptionKey.SSL_JKS_PATH,
+            OptionKey.SSL_JKS_PASSWORD,
+            OptionKey.SSL_PEM_CERT_PATH,
+            OptionKey.SSL_PEM_KEY_PATH,
+            OptionKey.SOURCE,
+            OptionKey.MARKUP_TYPE,
+            OptionKey.HELP,
+            OptionKey.VERSION,
+            OptionKey.VALIDATE_EXTERNAL_LINKS,
+            OptionKey.ACTOR,
+            OptionKey.MODIFIED_TIME,
+            OptionKey.LOOKUP_PATHS
+        )
+    }
+
+    @Test
+    void "build command includes doc-id but not server options"() {
+        def options = createOptionsForCommand(Command.BUILD, '--source=test')
+
+        assertOnlyTheseOptions(options,
+            OptionKey.DOC_ID,
+            OptionKey.DEPLOY,
+            OptionKey.SOURCE,
+            OptionKey.MARKUP_TYPE,
+            OptionKey.HELP,
+            OptionKey.VERSION,
+            OptionKey.VALIDATE_EXTERNAL_LINKS,
+            OptionKey.ACTOR,
+            OptionKey.MODIFIED_TIME,
+            OptionKey.LOOKUP_PATHS
+        )
+    }
+
+    @Test
+    void "export command includes export option but not server options"() {
+        def options = createOptionsForCommand(Command.EXPORT, '--source=test')
+
+        assertOnlyTheseOptions(options,
+            OptionKey.EXPORT,
+            OptionKey.SOURCE,
+            OptionKey.MARKUP_TYPE,
+            OptionKey.HELP,
+            OptionKey.VERSION,
+            OptionKey.VALIDATE_EXTERNAL_LINKS,
+            OptionKey.ACTOR,
+            OptionKey.MODIFIED_TIME,
+            OptionKey.LOOKUP_PATHS
+        )
+    }
+
+    @Test
+    void "new command shows only common options"() {
+        def options = createOptionsForCommand(Command.NEW, '--source=test')
+
+        assertOnlyTheseOptions(options,
+            OptionKey.SOURCE,
+            OptionKey.MARKUP_TYPE,
+            OptionKey.HELP,
+            OptionKey.VERSION,
+            OptionKey.VALIDATE_EXTERNAL_LINKS,
+            OptionKey.ACTOR,
+            OptionKey.MODIFIED_TIME,
+            OptionKey.LOOKUP_PATHS
+        )
+    }
+
+    private static createConfig(String... args) {
+        return new ZnaiCliConfig((exitCode) -> { println "exit code: ${exitCode}" }, args)
+
+    }
+
     private static String mode(String... args) {
-        return new ZnaiCliConfig(args).modeAsString
+        return createConfig(args).modeAsString
+    }
+
+    private static Options createOptionsForCommand(Command command, String... args) {
+        def commandName = command.getName()
+        def allArgs = [commandName] + args.toList()
+        def config = createConfig(allArgs as String[])
+        return config.createOptionsForCommand(command)
+    }
+
+    private static void assertOnlyTheseOptions(Options options, OptionKey... expectedKeys) {
+        def allKeys = OptionKey.values()
+
+        expectedKeys.each { key ->
+            def optionName = key.getKey()
+            assert options.hasOption(optionName), "Expected option ${optionName} (${key}) to be present"
+        }
+
+        def expectedSet = expectedKeys as Set
+        allKeys.each { key ->
+            if (!expectedSet.contains(key)) {
+                def optionName = key.getKey()
+                assert !options.hasOption(optionName), "Unexpected option ${optionName} (${key}) should not be present"
+            }
+        }
     }
-}
+}

znai-docs/znai/hub/setup.md

@@ -11,7 +11,7 @@ Create the enterprise config file and set the path where Znai will store uploade
 
 Run Znai in server mode in the directory with the config file:
 ```cli
-znai --serve --port=<port>
+znai serve --port=<port>
 ```
 
 # Upload Documentation

znai-docs/znai/introduction/getting-started.md

@@ -28,7 +28,7 @@ Note: consider adding a separate module for documentation in the multi module ma
 To create a minimum set of files for your documentation execute 
 
 ```tabs
-CLI: :include-cli-command: znai --new
+CLI: :include-cli-command: znai new
 Maven: :include-cli-command: mvn znai:new
 ```
 
@@ -53,7 +53,7 @@ to navigates to the right page and highlights the changes.
 To start preview mode, navigate to the documentation directory (`znai` if you used scaffold) and run
 
 ```tabs
-CLI: :include-cli-command: znai --preview [--port port-number]
+CLI: :include-cli-command: znai preview [--port port-number]
 Maven: 
 
 :include-cli-command: mvn znai:preview

znai-docs/znai/snippets/faq-collection/2022-07-15-preview.md

@@ -3,5 +3,5 @@
 To run Znai in preview mode
 
 ```cli
-znai --preview
+znai preview
 ```

znai-maven-plugin/src/main/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenBuildRunner.groovy

@@ -40,7 +40,7 @@ class ZnaiMavenBuildRunner extends AbstractMojo {
 
     @Override
     void execute() throws MojoExecutionException, MojoFailureException {
-        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), [
+        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), ["build"], [
                 'doc-id': docId,
                 source  : sourceRoot,
                 deploy  : deployRoot,

znai-maven-plugin/src/main/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenExportRunner.groovy

@@ -30,14 +30,9 @@ class ZnaiMavenExportRunner extends AbstractMojo {
     @Parameter(defaultValue = '${project.build.directory}/znai-export')
     private String exportRoot
 
-    @Parameter(defaultValue = "3333")
-    private Integer port
-
     @Override
     void execute() throws MojoExecutionException, MojoFailureException {
-        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), [
-                export: exportRoot,
-                port  : port.toString(),
+        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), ["export", exportRoot], [
                 source: sourceRoot,
         ])
     }

znai-maven-plugin/src/main/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenNewRunner.groovy

@@ -29,8 +29,6 @@ class ZnaiMavenNewRunner extends AbstractMojo {
 
     @Override
     void execute() throws MojoExecutionException, MojoFailureException {
-        def args = [new: null, source: sourceRoot]
-
-        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), args)
+        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), ["new"], [source: sourceRoot])
     }
 }

znai-maven-plugin/src/main/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenPreviewRunner.groovy

@@ -32,8 +32,7 @@ class ZnaiMavenPreviewRunner extends AbstractMojo {
 
     @Override
     void execute() throws MojoExecutionException, MojoFailureException {
-        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), [
-                preview: null,
+        ZnaiMavenRunner.run(new MavenPluginConsoleOuput(getLog()), ["preview"], [
                 port   : port.toString(),
                 source : sourceRoot,
         ])

znai-maven-plugin/src/main/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenRunner.groovy

@@ -21,24 +21,27 @@ import org.testingisdocumenting.znai.console.ConsoleOutputs
 import org.testingisdocumenting.znai.cli.ZnaiCliApp
 import org.testingisdocumenting.znai.cli.ZnaiCliConfig
 
+import java.util.stream.Stream
+
 class ZnaiMavenRunner {
-    static void run(ConsoleOutput consoleOutput, Map<String, String> argsMap) {
+    static void run(ConsoleOutput consoleOutput, List<String> freeFormArgs, Map<String, String> argsMap) {
         ConsoleOutputs.add(consoleOutput)
 
         try {
-            String[] args = constructArgs(argsMap)
-            def config = new ZnaiCliConfig(args)
+            String[] args = constructArgs(freeFormArgs, argsMap)
+            def config = new ZnaiCliConfig(System::exit, args)
 
             ZnaiCliApp.start(config)
         } finally {
             ConsoleOutputs.remove(consoleOutput)
         }
     }
 
-    static String[] constructArgs(Map<String, String> args) {
-        return args.entrySet().stream()
-        .map { entry -> argToString(entry) }
-        .toArray { size -> new String[size] }
+    static String[] constructArgs(List<String> freeFormArgs, Map<String, String> args) {
+        return Stream.concat(freeFormArgs.stream(),
+                args.entrySet().stream()
+                        .map { entry -> argToString(entry) })
+                .toArray { size -> new String[size] }
     }
 
     private static String argToString(Map.Entry<String, String> entry) {

znai-maven-plugin/src/test/groovy/org/testingisdocumenting/znai/maven/ZnaiMavenRunnerTest.groovy

@@ -21,7 +21,7 @@ import org.junit.Test
 class ZnaiMavenRunnerTest {
     @Test
     void "should handle params with no values"() {
-        def args = ZnaiMavenRunner.constructArgs([
+        def args = ZnaiMavenRunner.constructArgs([], [
                 noValue: null,
                 foo: 'bar',
         ])

znai-testing-examples/examples/webtauexamples/imageCapture.groovy

@@ -2,7 +2,7 @@ package webtauexamples
 
 import static org.testingisdocumenting.webtau.WebTauGroovyDsl.*
 
-def homeSearchInput = $('input[id*="search"]')
+def homeSearchInput = $('input[class*="search-input"]')
 def resultSearchInput = $("#search_form_input")
 def result = $('article[data-testid="result"]')
 

znai-tests/src/test/groovy/scenarios/installationCheck.groovy

@@ -24,8 +24,8 @@ def scaffoldedDocRoot = cache.value("scaffoldedNewDocs")
 
 scenario('shows help') {
     znai.run() {
-        output.should contain('--new')
-        output.should contain('create new documentation with minimal')
+        output.should contain('new')
+        output.should contain('Create new documentation with sample content and basic setup')
 
         exitCode.should == 1
     }