refactor(core): move CLIOptions to core api.cli package (#475)

* refactor(core): move CLIOptions to core api.cli package

Objective: Downstream tools (opendataloader-pdfua) need CLI option
parsing logic to populate Config from a CommandLine. They had to
depend on opendataloader-pdf-cli, which is not published to Maven
Central — forcing a local `mvn install` step before any build.

Approach: Move CLIOptions to core under org.opendataloader.pdf.api.cli
so downstream tools depend only on core (which is already on Central).
The cli module keeps CLIMain as the executable entry point and adds
an import to the new package. Stable members for downstream use are
documented on the class: defineOptions, addAllTo, applyAllTo, FOLDER_OPTION.

Evidence:
- mvn test in core: 634/634 pass (incl. moved CLIOptionsTest,
  CLIOptionsContentSafetyTest)
- mvn test in cli: 5/5 pass
- npm test (vitest, node wrapper): 32/32 pass
- pytest (python wrapper, cli_options + convert_integration): 13/13 pass
- `--export-options` byte-level diff vs existing options.json: identical
- shaded jar manifest: Main-Class still org.opendataloader.pdf.cli.CLIMain

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: tighten CLIOptions stability contract + cover addAllTo edge cases

Objective: Code review on #475 flagged that the class-level Javadoc
declared four "stable" members but did nothing to discourage downstream
from depending on the dozens of other public statics (option-name
constants, createConfigFromCommandLine, exportOptionsAsJson). Also
asked for direct test coverage of the addAllTo external-Options pattern
that pdfua relies on.

Approach:
- Rewrite the class Javadoc to explicitly mark all non-listed public
  members as internal — public visibility for cross-package access
  only, may change in any release. Add a usage example so the
  intended pattern (custom Options + addAllTo + applyAllTo) is visible
  at the top of the file.
- Add two tests covering the contract pdfua actually depends on:
  addAllTo preserves pre-existing downstream options, and addAllTo
  is idempotent (commons-cli's silent-replace-by-long-name behavior
  is pinned so a future commons-cli upgrade that changes it surfaces
  here).

Evidence:
- mvn test CLIOptionsTest: 61/61 pass (incl. 2 new)
- mvn install: BUILD SUCCESS
- mvn javadoc:jar -P release: BUILD SUCCESS (doclint passes new Javadoc)
- Probe of commons-cli 1.11 confirms Options.addOption silently replaces
  by long-name (count stays 1, last description wins) — test pins this.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bundolee

java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIMain.java

@@ -18,6 +18,7 @@
 import org.apache.commons.cli.*;
 import org.opendataloader.pdf.api.Config;
 import org.opendataloader.pdf.api.OpenDataLoaderPDF;
+import org.opendataloader.pdf.api.cli.CLIOptions;
 import org.opendataloader.pdf.containers.StaticLayoutContainers;
 
 import java.io.File;

java/opendataloader-pdf-core/pom.xml

@@ -77,6 +77,10 @@
             <artifactId>jackson-databind</artifactId>
             <version>${jackson.databind.version}</version>
         </dependency>
+        <dependency>
+            <groupId>commons-cli</groupId>
+            <artifactId>commons-cli</artifactId>
+        </dependency>
         <dependency>
             <groupId>com.squareup.okhttp3</groupId>
             <artifactId>okhttp</artifactId>

…g/opendataloader/pdf/cli/CLIOptions.java …endataloader/pdf/api/cli/CLIOptions.javajava/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIOptions.java renamed to java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/cli/CLIOptions.java java/opendataloader-pdf-cli/src/main/java/org/opendataloader/pdf/cli/CLIOptions.java renamed to java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/api/cli/CLIOptions.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.opendataloader.pdf.cli;
+package org.opendataloader.pdf.api.cli;
 
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.Option;
@@ -30,6 +30,37 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+/**
+ * Adapter that maps Apache Commons CLI options to {@link Config} / {@link HybridConfig}.
+ *
+ * <p><b>Stable API for downstream tools</b> (e.g. opendataloader-pdfua) — these four
+ * members are the supported integration surface and will not break compatibly:
+ * <ul>
+ *   <li>{@link #defineOptions()} — get a fully populated {@code Options} instance</li>
+ *   <li>{@link #addAllTo(Options)} — add core options into an externally-built {@code Options}</li>
+ *   <li>{@link #applyAllTo(Config, CommandLine)} — populate a {@code Config} from a parsed line</li>
+ *   <li>{@link #FOLDER_OPTION} — short option name for {@code --output-dir}</li>
+ * </ul>
+ *
+ * <p><b>Everything else is internal.</b> The numerous other public {@code static} members
+ * (option-name constants, helpers like {@code createConfigFromCommandLine},
+ * {@code exportOptionsAsJson}) exist for the CLI module ({@code CLIMain}) and the
+ * options-export tooling that drives Node/Python binding generation. Their visibility
+ * is {@code public} only for cross-package access within this codebase; they are
+ * <i>not</i> part of the supported API and may be renamed, moved, or removed in any
+ * release. Downstream consumers depending on them do so at their own risk.
+ *
+ * <p>Pdfua's usage pattern (build your own {@code Options}, add core's, parse, then
+ * populate {@code Config}):
+ * <pre>{@code
+ *   Options options = new Options();
+ *   options.addOption(...);              // your tool-specific options
+ *   CLIOptions.addAllTo(options);        // add core's options
+ *   CommandLine cmd = parser.parse(options, args);
+ *   Config core = new Config();
+ *   CLIOptions.applyAllTo(core, cmd);
+ * }</pre>
+ */
 public class CLIOptions {
 
     // ===== Output Directory =====

…pdf/cli/CLIOptionsContentSafetyTest.java …api/cli/CLIOptionsContentSafetyTest.javajava/opendataloader-pdf-cli/src/test/java/org/opendataloader/pdf/cli/CLIOptionsContentSafetyTest.java renamed to java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/api/cli/CLIOptionsContentSafetyTest.java java/opendataloader-pdf-cli/src/test/java/org/opendataloader/pdf/cli/CLIOptionsContentSafetyTest.java renamed to java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/api/cli/CLIOptionsContentSafetyTest.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.opendataloader.pdf.cli;
+package org.opendataloader.pdf.api.cli;
 
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;

…endataloader/pdf/cli/CLIOptionsTest.java …taloader/pdf/api/cli/CLIOptionsTest.javajava/opendataloader-pdf-cli/src/test/java/org/opendataloader/pdf/cli/CLIOptionsTest.java renamed to java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/api/cli/CLIOptionsTest.java java/opendataloader-pdf-cli/src/test/java/org/opendataloader/pdf/cli/CLIOptionsTest.java renamed to java/opendataloader-pdf-core/src/test/java/org/opendataloader/pdf/api/cli/CLIOptionsTest.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.opendataloader.pdf.cli;
+package org.opendataloader.pdf.api.cli;
 
 import org.apache.commons.cli.CommandLine;
 import org.apache.commons.cli.CommandLineParser;
@@ -639,4 +639,29 @@ void testApplyAllTo_appliesCoreOptions() throws ParseException {
         // downstream-only is not consumed by applyAllTo — that is the caller's job.
         assertEquals("value", cmd.getOptionValue("downstream-only"));
     }
+
+    @Test
+    void testAddAllTo_preservesPreexistingDownstreamOptions() {
+        Options ext = new Options();
+        ext.addOption(null, "ua-foo", true, "Pdfua-specific option");
+        ext.addOption(null, "ua-bar", false, "Pdfua-specific flag");
+        CLIOptions.addAllTo(ext);
+
+        assertTrue(ext.hasOption("ua-foo"));
+        assertTrue(ext.hasOption("ua-bar"));
+        assertTrue(ext.hasOption("hybrid"));
+        assertTrue(ext.hasOption("threads"));
+    }
+
+    @Test
+    void testAddAllTo_calledTwice_isIdempotent() {
+        Options ext = new Options();
+        CLIOptions.addAllTo(ext);
+        int afterFirst = ext.getOptions().size();
+        // commons-cli's Options.addOption silently replaces by long-name, so calling
+        // addAllTo twice does not throw and does not duplicate. Pin this so a future
+        // commons-cli upgrade that changes the behavior surfaces here.
+        CLIOptions.addAllTo(ext);
+        assertEquals(afterFirst, ext.getOptions().size());
+    }
 }