Merge pull request #335 from midagedev/feat/issue-284-classpath-auto-discovery

[node][runtime] Harden Java classpath auto-discovery fallback (#284)

Author: midagedev

CHANGELOG.md

@@ -35,6 +35,7 @@ All notable changes to this project are documented in this file.
 - Added Node debug bundle collector CLI and issue template for reproducible support reports.
 - Added startup latency telemetry hook for launch attempts (including auto fallback success/failure events).
 - Added `node:doctor` launcher preflight diagnostics command with structured report output.
+- Added Java classpath auto-discovery fallback hardening for `auto`/`java` launch modes with configurable probe command/cwd.
 
 ## [0.1.3] - 2026-02-24
 

docs/NODE_TROUBLESHOOTING_PLAYBOOK.md

@@ -16,6 +16,7 @@ Use this playbook when `@jongodb/memory-server` startup or test-runtime integrat
 | `No launcher runtime configured` | neither binary nor Java classpath resolved | set `binaryPath` / `JONGODB_BINARY_PATH`, or set `classpath` / `JONGODB_CLASSPATH` |
 | `Binary launch mode requested but no binary was found` | `launchMode: "binary"` but executable is not resolvable | provide explicit `binaryPath` or set `JONGODB_BINARY_PATH` |
 | `Java launch mode requested but Java classpath is not configured` | `launchMode: "java"` without classpath | pass `classpath` option or export `JONGODB_CLASSPATH` |
+| `Classpath auto-discovery probe failed` | Gradle classpath probe command/cwd is invalid or unavailable | set explicit `classpath`/`JONGODB_CLASSPATH`, or fix `classpathDiscoveryCommand`/`classpathDiscoveryWorkingDirectory` |
 | `Failed to start jongodb with available launch configurations` | all launch candidates failed (binary/java) | inspect aggregated `[binary:...]` / `[java:...]` messages and fix per candidate |
 | `Launcher emitted empty JONGODB_URI line` | launcher started but did not emit valid URI contract | verify launcher command args/env; update runtime/binary to a compatible build |
 | `Requested topologyProfile=singleNodeReplicaSet but URI is missing replicaSet query` | topology profile and emitted URI are mismatched | ensure launcher emits `?replicaSet=<name>` or switch to `topologyProfile: "standalone"` |
@@ -34,6 +35,13 @@ Resolve Java classpath in repo:
 export JONGODB_CLASSPATH="$(./.tooling/gradle-8.10.2/bin/gradle --no-daemon -q printLauncherClasspath | tail -n 1)"
 ```
 
+Customize classpath auto-discovery probe:
+
+```bash
+export JONGODB_CLASSPATH_DISCOVERY_CMD="./.tooling/gradle-8.10.2/bin/gradle"
+export JONGODB_CLASSPATH_DISCOVERY_CWD="$PWD"
+```
+
 Run node compatibility smoke after fix:
 
 ```bash
@@ -50,6 +58,7 @@ rm -f .jongodb/jest-memory-server.json
 ## Configuration Sanity Checklist
 
 - `launchMode` is one of `auto`, `binary`, `java`.
+- `classpathDiscovery` is `auto` or `off` (`auto` default).
 - `host`, `port`, `databaseName` values are valid/non-empty.
 - `topologyProfile` and `replicaSetName` match expected URI contract.
 - `envVarName` / `envVarNames` are valid and unique for your test runtime.

packages/memory-server/README.md

@@ -254,6 +254,11 @@ Bundled targets:
 
 Java fallback:
 - set `classpath` option or `JONGODB_CLASSPATH`
+- if both are missing, classpath auto-discovery probes:
+  - command: `options.classpathDiscoveryCommand` -> `JONGODB_CLASSPATH_DISCOVERY_CMD` -> repo-local Gradle -> `gradle`
+  - args: `--no-daemon -q printLauncherClasspath`
+  - working directory: `options.classpathDiscoveryWorkingDirectory` -> `JONGODB_CLASSPATH_DISCOVERY_CWD` -> `process.cwd()`
+  - disable probe: `classpathDiscovery: "off"` or `JONGODB_CLASSPATH_DISCOVERY=off`
 
 Launcher contract:
 - stdout ready line: `JONGODB_URI=mongodb://...`
@@ -294,6 +299,9 @@ Core:
 - `launchMode`: `auto` | `binary` | `java` (default: `auto`)
 - `binaryPath`: binary executable override path
 - `classpath`: Java classpath string or string array
+- `classpathDiscovery`: `auto` | `off` (default: `auto`)
+- `classpathDiscoveryCommand`: override command used for classpath auto-discovery probe
+- `classpathDiscoveryWorkingDirectory`: cwd for classpath auto-discovery probe
 - `javaPath`: Java executable path (default: `java`)
 - `launcherClass`: Java launcher class (default: `org.jongodb.server.TcpMongoServerLauncher`)
 - `topologyProfile`: `standalone` | `singleNodeReplicaSet` (default: `standalone`)
@@ -358,6 +366,7 @@ const runtime = createJongodbEnvRuntime({
 - `No launcher runtime configured`: set `binaryPath` / `JONGODB_BINARY_PATH` / `classpath` / `JONGODB_CLASSPATH`
 - `Binary launch mode requested but no binary was found`: provide `binaryPath` or `JONGODB_BINARY_PATH`
 - `Java launch mode requested but Java classpath is not configured`: provide `classpath` or `JONGODB_CLASSPATH`
+- `Classpath auto-discovery probe failed`: set explicit `classpath` / `JONGODB_CLASSPATH`, or fix Gradle probe command/cwd
 - `spawn ... ENOENT`: missing runtime executable path
 - startup timeout: launcher did not emit `JONGODB_URI=...`
 - `Launcher URI topology options are out of sync`: emitted URI query does not match requested `topologyProfile`/`replicaSetName`