Scriptella 1.4: Release hardening, JDK 17 compatibility, and dependency modernization

[ejboy]

Scriptella 1.4: Release hardening, JDK 17 compatibility, and dependency modernization

Target: Scriptella 1.4

JDK experiment: #31

Summary

The Scriptella 1.3 publication run exposed two test-environment defects and
several release-procedure gaps. Scriptella 1.4 must address them alongside a
JDK 17 compatibility upgrade and comprehensive dependency modernization, so
future releases have deterministic validation, current supported libraries,
correctly signed Central uploads, and clearer operator recovery steps.

Scriptella 1.3 is immutable. This ticket does not authorize a 1.3.1 release.
Whether Java 17 becomes the required baseline or is supported alongside Java 8
is explicitly TBD and must be decided from the compatibility audit before
implementation locks the compiler target or public requirements.

Observed problems

1. Cancellation test contaminates later JMX tests

scriptella.execution.CancellationTest interrupts the Maven/Surefire test
runner thread from a helper thread. The helper is neither coordinated nor
joined. In tagged release builds this intermittently left an interrupted
state that caused scriptella.execution.JmxEtlManagerITest to fail with
EtlCancelledException.

The affected release-build symptoms were:

• CancellationTest assertion failure; and
• JmxEtlManagerITest receiving an unexpected cancellation.

The same clean test gate passed on retry, confirming a test-isolation/race
problem rather than a release artifact defect.

2. Launcher extension detection depends on the full absolute path

scriptella.tools.launcher.EtlLauncher.resolveFile determines whether an
input has an extension with name.indexOf('.'). When name is an absolute
path and a parent directory contains a dot (for example a worktree named
scriptella-1.3-validation), the launcher believes an extension is already
present and does not try the expected .etl.xml suffix.

This made EtlLauncherTest fail in a dotted disposable worktree even though
the fixture files existed. A dot-free worktree allowed the same tests to pass.

3. GPG signing needs an explicit interactive preflight

Non-interactive Maven invocations failed with Inappropriate ioctl for device
when the GPG agent was locked. An interactive detached-sign operation in the
operator terminal correctly unlocked the key, after which Maven signing
succeeded.

4. release:perform needs local checkout and propagated release flags

The repository's Maven SCM metadata uses an SSH developer connection, while
the release workstation authenticated Git over HTTPS. The default
release:perform clone failed with Permission denied (publickey).

Using -DlocalCheckout=true allowed Maven Release Plugin to use the already
pushed local tag. The first Central deployment then failed validation because
performRelease=true was not propagated into the checkout build, so Central
received unsigned POMs and JARs. Retrying with both of these arguments
produced a manually managed VALIDATED deployment:

-DlocalCheckout=true
-Darguments="-DperformRelease=true -Dgpg.keyname=<full-fingerprint>"

The failed deployment had to be dropped before retrying.

Required changes

Test reliability

1. Refactor CancellationTest to use explicit synchronization for the helper
   thread and the ETL start/cancel boundary.
2. Join the helper thread before test completion and assert that it completed
   normally.
3. Ensure the test runner's interrupted status is cleared or asserted at the
   test boundary so later tests cannot inherit cancellation state.
4. Keep the cancellation behavior assertions: cancellation is reported, the
   operation terminates promptly, and temporary tables are cleaned up.
5. Add a regression sequence that exercises cancellation followed by the JMX
   integration path repeatedly under Java 8.

Launcher path handling

1. Change EtlLauncher.resolveFile to inspect the final filename component
   when deciding whether to append .etl.xml; do not use dots in parent
   directories as evidence of a filename extension.
2. Preserve existing behavior for explicit filenames, relative paths, and the
   default etl.xml file.
3. Add tests covering extensionless absolute ETL paths below a directory whose
   name contains a dot, plus explicit .etl.xml filenames.

Java 17 and dependency modernization

1. Inventory every direct, transitive, bundled, test, and build-plugin
   dependency, including copies shipped in standalone and examples archives.
2. Upgrade each dependency and Maven plugin to a currently supported stable
   version compatible with the selected 1.4 Java baseline; record the old and
   new coordinates, licenses, transitive changes, and compatibility impact.
3. Resolve API and namespace migrations deliberately, including the
   javax.*/jakarta.* transition for mail-related integrations, Spring API
   compatibility, Rhino/JSR-223 behavior, Ant integration, and supported JDBC
   driver behavior. Do not silently replace public APIs or change module
   coordinates.
4. Decide and document the Java baseline after the audit: either require Java
   17 or retain Java 8 compatibility while making Java 17 a supported runtime.
   Update compiler configuration, runtime documentation, examples, CI, and
   release validation consistently with that decision.
5. Reconcile Maven dependencies with all bundled distribution and sample
   libraries. Update license notices and verify required byte-identical copies
   where the archives intentionally share artifacts.
6. Remove, replace, or explicitly defer obsolete reporting/build plugins only
   after confirming they are not part of the supported release path.

Reusable release runbook

Update docs/releases/RELEASE-RUNBOOK.md with these durable steps:

1. Before each signed Maven phase, verify GPG-agent/pinentry using an
   interactive detached-sign check. Do not put the passphrase on a command
   line.
2. Name disposable worktrees without dots when launcher/path smoke tests are
   part of validation until the launcher fix is available.
3. When the SCM developer connection is SSH but the operator uses HTTPS,
   invoke release:perform with -DlocalCheckout=true after the approved tag
   is pushed.
4. Always propagate -DperformRelease=true and the approved full GPG
   fingerprint through release:perform -Darguments=....
5. Before accepting Central validation, inspect the staged bundle/deployment
   for .asc signatures for every required POM and JAR.
6. On a FAILED Central deployment, capture sanitized errors, drop the
   unpublished deployment, correct the invocation/configuration, and rerun
   validation without changing an already-pushed tag unless separately
   authorized.
7. Note that an unpublished GitHub draft can use an untagged-... URL while
   still correctly carrying the selected release tag; verify tagName, draft
   state, title, prerelease state, and exact asset count instead of relying on
   the draft URL shape.
8. Treat Maven release-plugin backup POMs and release.properties as expected
   local state needed for release:perform; keep them out of Git and clean
   them only after release execution/evidence retention is complete.

Acceptance criteria

• Core tests pass repeatedly under Temurin Java 8 with no cancellation/JMX
  cross-test contamination.
• Tools launcher tests pass from dotted and dot-free absolute worktree paths.
• A reviewed dependency inventory accounts for every direct, transitive,
  bundled, test, and build-plugin dependency, with modern supported versions
  selected and license/compatibility changes documented.
• The Java 17 baseline decision is explicitly recorded and validated with the
  corresponding runtime/compiler matrix; no Java compatibility promise changes
  implicitly.
• Maven, Ant, standalone distributions, examples, and representative drivers
  pass their smoke tests using the modernized dependency set.
• The full Java 8 Maven/Ant/DTDDoc no-upload release gate passes with the
  documented test totals (Core 149, Drivers 141, Tools 12; 302 total), or the
  test environment and totals are deliberately updated for the selected 1.4
  Java baseline.
• A no-upload signed Maven build produces detached signatures for every
  Central POM/JAR.
• A manual Central validation rehearsal uses the documented local-checkout
  invocation and reaches VALIDATED with complete signatures, without
  automatic publication.
• The runbook contains the new preflight, invocation, verification, recovery,
  and draft-release guidance without credentials, private paths, or passphrases.

Evidence to link when opening the issue

• Scriptella 1.3 tag and release URL.
• Sanitized Maven/Ant validation summaries and test totals.
• The failed unsigned Central deployment's sanitized validation reason and the
  successful validated deployment ID/state, if appropriate for public issue
  history.

Do not include tokens, passwords, passphrases, private-key material,
authentication headers, private Maven settings, or credential-bearing logs.