fix: pass headless JVM flags so macOS does not show Dock icon

Objective: On macOS, every CLI run pops a Java icon in the Dock and
steals focus from the active window — so any batch or repeated PDF
conversion turns into a flickering, focus-thrashing experience.

Approach: Pass -Djava.awt.headless=true and -Dapple.awt.UIElement=true
as JVM args ahead of -jar at every spawn site (Node wrapper, Python
wrapper, scripts/run-cli.sh, npm export-options). The CLI never opens
a UI — it only manipulates BufferedImages and renders PDFBox pages off
screen — so headless is safe everywhere. apple.awt.UIElement is the
macOS-specific flag the launcher reads to skip Dock registration; it
is harmless on other OSes.

Evidence: Ran the built jar and the Node wrapper against a sample PDF
on macOS.

Before: every invocation surfaced a Java Dock icon and stole focus.
After (java -D... -jar):    PDF processed, JSON written, no Dock icon.
After (Node convert() API): variant resolved successfully, no Dock icon.

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

Author: bundolee

node/opendataloader-pdf/src/index.ts

@@ -37,7 +37,16 @@ function executeJar(args: string[], executionOptions: JarExecutionOptions = {}):
     }
 
     const command = 'java';
-    const commandArgs = ['-jar', jarPath, ...args];
+    // Force headless AWT so macOS doesn't surface a Dock icon (and steal focus)
+    // every time the JVM touches ImageIO/PDFBox rendering. Safe on all OSes —
+    // the CLI never opens a UI window, only manipulates BufferedImages.
+    const commandArgs = [
+      '-Djava.awt.headless=true',
+      '-Dapple.awt.UIElement=true',
+      '-jar',
+      jarPath,
+      ...args,
+    ];
 
     const javaProcess = spawn(command, commandArgs);
 

package.json

@@ -4,7 +4,7 @@
   "description": "OpenDataLoader PDF - Monorepo workspace",
   "scripts": {
     "build-java": "bash scripts/build-java.sh",
-    "export-options": "npm run build-java && java -jar java/opendataloader-pdf-cli/target/opendataloader-pdf-cli-0.0.0.jar --export-options > options.json",
+    "export-options": "npm run build-java && java -Djava.awt.headless=true -Dapple.awt.UIElement=true -jar java/opendataloader-pdf-cli/target/opendataloader-pdf-cli-0.0.0.jar --export-options > options.json",
     "generate-options": "node scripts/generate-options.mjs",
     "sync-options": "npm run export-options && npm run generate-options",
     "generate-schema": "node scripts/generate-schema.mjs",

python/opendataloader-pdf/src/opendataloader_pdf/runner.py

@@ -16,7 +16,18 @@ def run_jar(args: List[str], quiet: bool = False) -> str:
         # Access the embedded JAR inside the package
         jar_ref = resources.files("opendataloader_pdf").joinpath("jar", _JAR_NAME)
         with resources.as_file(jar_ref) as jar_path:
-            command = ["java", "-jar", str(jar_path), *args]
+            # Force headless AWT so macOS doesn't surface a Dock icon (and
+            # steal focus) every time the JVM touches ImageIO/PDFBox
+            # rendering. Safe on all OSes — the CLI never opens a UI window,
+            # only manipulates BufferedImages.
+            command = [
+                "java",
+                "-Djava.awt.headless=true",
+                "-Dapple.awt.UIElement=true",
+                "-jar",
+                str(jar_path),
+                *args,
+            ]
 
             if quiet:
                 # Quiet mode → capture all output

scripts/run-cli.sh

@@ -54,5 +54,6 @@ else
     ARGS=("$@")
 fi
 
-# Run the CLI
-java -jar "$JAR_PATH" "${ARGS[@]}"
+# Run the CLI. Headless flags suppress the macOS Dock icon / focus theft when
+# AWT/ImageIO/PDFBox initialize. Safe on all OSes — the CLI never opens a UI.
+java -Djava.awt.headless=true -Dapple.awt.UIElement=true -jar "$JAR_PATH" "${ARGS[@]}"