Adopt jDeploy to provide a managed Java runtime for Seed4J CLI

[renanfranca]

Context

Seed4J CLI is distributed through npm but runs as a Java application compiled for Java 25.

The current npm launcher uses the first java executable available on the user's PATH. It already validates that Java 25 or higher is installed and provides actionable errors when Java is missing or incompatible. Implemented below:

• validate Java version before launching CLI #268

This prevents low-level failures such as UnsupportedClassVersionError, but it does not eliminate the underlying installation friction: every Seed4J CLI user must install and manage Java 25+, even when generating a frontend-only project such as Vue.

The generated frontend project may not require Java, but the CLI currently does.

Proposal

Adopt jDeploy to provide a private, compatible Java runtime for Seed4J CLI installations distributed through npm.

The intended user experience would be:

npm install -g seed4j-cli
seed4j --version

Users should not need to install Java, change JAVA_HOME, or manage the Java version used internally by the CLI.

The managed runtime must remain an implementation detail of Seed4J CLI. It must not become the Java toolchain of generated projects. A generated Java project will still require its own appropriate JDK, while a frontend-only project will require only its frontend toolchain.

Expected benefits

• Remove Java installation and version management from the CLI setup.
• Prevent conflicts with the Java version selected by the user for other projects.
• Improve the experience for frontend-only users.
• Provide a consistent runtime across supported operating systems.
• Reduce installation failures and support requests caused by incompatible Java versions.
• Preserve npm as the primary installation channel.

Required proof of concept

Before changing the release process, create a focused jDeploy proof of concept that validates:

• Java 25 runtime provisioning.
• Linux, macOS, and Windows support.
• x64 and arm64 architectures where supported.
• Standard runtime mode.
• Extension runtime mode and child Java processes.
• CLI argument, exit code, signal, stdin, stdout, and stderr forwarding.
• First execution without system Java installed.
• Subsequent execution without network access.
• Corporate proxy behavior and actionable download failures.
• Runtime cache location, lifecycle, updates, and cleanup.
• Compatibility with the existing npm publishing workflow and provenance.
• Package installation through both npm install -g and npx.

Acceptance criteria

jDeploy should be adopted only if the proof of concept demonstrates that:

• seed4j runs without system Java installed.
• Seed4J CLI consistently uses Java 25 or higher.
• The user's JAVA_HOME and java on PATH do not affect the CLI runtime.
• Standard and extension modes retain their current behavior.
• The managed runtime does not alter generated project requirements.
• Runtime download and startup failures produce clear, actionable messages.
• Release and maintenance complexity remain acceptable.

Migration considerations

If the proof of concept succeeds:

• Replace the current system-Java launcher with the jDeploy launcher.
• Update npm package preparation and release workflows.
• Add cross-platform installation smoke tests.
• Update the README to remove system Java as a CLI prerequisite.
• Document first-run runtime download and offline behavior.
• Consider retaining system-Java validation only for development workflows that execute the JAR directly.

Decision to make

Should Seed4J CLI adopt jDeploy so npm users receive a managed Java runtime and no longer need to install Java solely to run the CLI?