Maven plugin feature parity - VenvManager cross-compile fix, SetupMojoTest parameter tests, maven example enhancements

Author: white

.output.txt

@@ -0,0 +1,300 @@
+Command finished with exit code 0.
+Command output:
+---
+tags:
+  - tasks
+---
+
+# Completed Tasks
+
+> Related: [[Tasks/active]] | [[2026-06-21 - Competitive Analysis & Strategic Positioning]]
+
+---
+
+## Protocol & Core Features
+
+### Binary Protocol (MessagePack)
+- [x] Binary protocol replacing JSON (MessagePack with length-prefixed frames)
+- [x] Python object handle system (reference by numeric ID)
+- [x] Streaming results (generator/yield support via Java Iterator)
+- [x] Type conversion: Python dict/list to Java Map/List via MessagePack extension types
+- [x] Batch execution: batchEval/batchExec (single round-trip, JSR-223 compatible)
+
+### Python to Java Callbacks
+- [x] _bridge.call() command with Java handler registration API
+- [x] Progress/log/intermediate result push via _bridge.push()
+- [x] Arity-specific callback handler architecture (CallbackHandler0-CallbackHandler5)
+- [x] Push handler with unknown name error reporting
+
+### Proxy Objects
+- [x] Java dynamic proxies for Python objects with handle lifecycle management
+- [x] Proxy method resolution caching (ConcurrentHashMap, CALL/GETATTR strategies)
+- [x] PythonEmbedPool.proxy() shortcut
+- [x] PythonHandle cleanup on pool scale-down (handle.release() + forgetHandle)
+
+---
+
+## Pool & Concurrency
+
+### PythonEmbedPool
+- [x] Auto-managed pool with round-robin/least-loaded task distribution
+- [x] Future/PythonValue/CompletableFuture async API
+- [x] Auto-restart with minPool guarantee on crash
+- [x] Pool-level batchEval/batchExec/ref support
+- [x] Pool close-timeout configurable via DisposableBean
+
+### Health & Stability
+- [x] Health check: periodic ping/pong with RSS memory, ref count, GC status
+- [x] Health check ping failure logging at WARNING level
+- [x] Python log forwarding to SLF4J via `python.*` logger namespace
+- [x] Crash isolation: Python segfaults never kill the JVM
+
+---
+
+## Developer Experience
+
+### API Improvements
+- [x] Include Python traceback in Java exceptions
+- [x] eval/exec timeout with configurable granularity
+- [x] Graceful shutdown (close with timeout, close-hook support)
+- [x] Unchecked API: PythonExecutionException extends RuntimeException
+- [x] Safe argument injection: PythonEmbed.arg(Object) with type conversion
+- [x] Stream timeout renaming: timeoutMs to pollTimeoutMs (old deprecated)
+- [x] PythonEmbed.execFile(Path) convenience method
+- [x] PythonEmbed.arg() datetime/time type support (Instant, LocalDateTime, etc.)
+- [x] PythonEmbed.eval() variable binding (Map of String, Object locals)
+- [x] PythonValue.toJson() convenience method
+
+### Builder API
+- [x] Fluent builders on PythonEmbed and PythonEmbedPool
+
+---
+
+## Build & Distribution
+
+### venv & Packaging
+- [x] requirements.txt support
+- [x] pyproject.toml support (auto-extract dependencies)
+- [x] Incremental venv: rebuild only on dependency changes
+- [x] PEP 440 venv path validation (normalize + validate)
+- [x] pip index URL / extra args support (GPU-ready)
+
+### Publishing
+- [x] python-embed-runtime v0.1.0-SNAPSHOT deployed to Maven Central (Sonatype OSSRH)
+- [x] python-embed-gradle-plugin v0.1.0-SNAPSHOT deployed to Gradle Plugin Portal
+- [x] Publishing plugin configuration (vanniktech/gradle-maven-publish-plugin 0.34.0)
+
+### Security Hardening
+- [x] Tar/ZipSlip path validation
+
+---
+
+## Test Coverage
+
+### Test Gap Closure
+| Date       | Description                                                                    | Tests Added |
+| ---------- | ------------------------------------------------------------------------------ | ----------- |
+| 2026-06-22 | PythonValue.asBytes(), VenvExtractor, MsgpackProtocol, pool batch              | +43         |
+| 2026-06-22 | resolveExplicitPath, findPythonInDir, push handler, cross-module contract      | +12         |
+| 2026-06-23 | PythonEmbedOptionsTest (22 unit), warmupScripts, getPid, stream close          | +26         |
+| 2026-06-23 | Spring Boot starter: options-build, health-indicator, auto-config, integration | +19         |
+
+### Flaky Test Fixes
+- [x] scaleDown_removesIdleInstancesAboveMinPool race condition fixed
+
+---
+
+## Planning & Analysis
+
+### Competitive Analysis (2026-06-22)
+- [x] python-embed vs JEP, GraalPy, Py4J, JPype across 6 dimensions
+- [x] 12 improvement recommendations with priority tiers
+- [x] See [[2026-06-21 - Competitive Analysis & Strategic Positioning]]
+
+### Development Plans (2026-06-23)
+- [x] [[2026-06-23 - Maven plugin development plan]]
+- [x] [[2026-06-23 - Spring Boot auto-configuration plan]]
+- [x] [[2026-06-23 - New API proposals plan]]
+
+### Spring Boot Auto-Configuration (2026-06-23)
+- [x] Example Spring Boot app: python-embed-examples/spring-boot-example/
+- [x] REST controller (/eval, /exec, /info) using auto-configured PythonEmbed bean
+- [x] Actuator health endpoint with PythonEmbedHealthIndicator
+- [x] SINGLE and POOL mode profiles (application.yml, application-pool.yml)
+
+### Decision Management
+- [x] 40 decision files tagged with status field (39 completed, 1 not_implemented)
+- [x] Bidirectional cross-references added to all decisions
+- [x] _Index.md rebuilt with 8 thematic clusters
+- [x] 5 topic groups consolidated (50 to 40 decisions)
+
+---
+
+## Documentation & Vault
+
+### Vault Organization (2026-06-22)
+- [x] Vault naming convention established
+- [x] Session files consolidated into active/completed task tracking
+- [x] All 19 vault files translated to English
+
+### Documentation Sync
+- [x] Projects/python-embed.md synchronized with current implementation
+- [x] Obsolete sections removed (e.g., Micrometer observability)
+
+### README
+- [x] Expanded from 26 lines to 308 lines
+- [x] Quick Start guide, architecture diagrams, 12 cookbook examples
+
+---
+
+## Environment & Tooling
+- [x] IntelliJ 'Unable to load class PythonEmbedPlugin' error fixed (stale .idea/gradle.xml)
+- [x] Close-hook support: PythonEmbed/PythonEmbedPool shutdown hook registration
+
+
+### 2026-06-23
+- [x] Commit working tree (v1.0.0 release prep: CHANGELOG, README updates, version bump to 1.0.1-SNAPSHOT)
+## Recently Completed
+
+### Maven Central & Gradle Plugin Publishing
+- [x] Publish python-embed-runtime to Maven Central v0.1.0-SNAPSHOT (commit 458165e)
+- [x] Publish plugin to Gradle Plugin Portal v0.1.0-SNAPSHOT
+
+### Spring Boot Auto-Configuration
+- [x] Module: python-embed-spring-boot-starter/
+- [x] PythonEmbedProperties, PythonEmbedAutoConfiguration (SINGLE + POOL)
+- [x] PythonEmbedHealthIndicator, AutoConfiguration.imports
+- [x] 35 tests (property 8 + health 7 + auto-config 8 + options-build 7 + integration 4)
+- [x] Example Spring Boot app: python-embed-examples/spring-boot-example/ with REST controller and Actuator health
+
+### Spring Boot Configuration Metadata (2026-06-24)
+- [x] spring-boot-configuration-processor added for auto-generated metadata
+- [x] 13 properties with Javadoc descriptions, types, and default values in spring-configuration-metadata.json
+- [x] 5 missing options added: maxCodeLength, startupTimeoutMs, pythonExecutable, warmupScripts, lenientWarmup
+- [x] 10 new unit tests for property-to-option mappings (27 total)
+- [x] Redundant additional-spring-configuration-metadata.json removed (processor auto-generates instead)
+
+### Documentation & Examples
+- [x] Quick Start guide integrated into README.md
+- [x] Cookbook: 12 examples in python-embed-examples/
+- [x] Architecture diagrams in README.md
+
+### New API Proposals
+- **Plan**: [[2026-06-23 - New API proposals plan]] (2026-06-23)
+- [x] PythonEmbed.execFile(Path) -- execute Python files directly
+- [x] PythonEmbed.arg() datetime/time type support
+- [x] PythonEmbed.eval() variable binding (Map<String, Object> locals)
+- [x] PythonValue.toJson() convenience method
+
+
+### v1.0.0 Release (2026-06-23)
+- [x] Publish python-embed-runtime to Maven Central v1.0.0
+- [x] Publish python-embed-gradle-plugin to Gradle Plugin Portal v1.0.0
+- [x] Publish python-embed-spring-boot-starter to Maven Central v1.0.0
+- [x] Remove SNAPSHOT from version, cleanup README pre-release warning
+- [x] Bump version to 1.0.1-SNAPSHOT for next development cycle
+
+### v1.0.1 Release (2026-06-23)
+- [x] Publish python-embed-runtime to Maven Central v1.0.1
+- [ ] Publish python-embed-gradle-plugin to Gradle Plugin Portal v1.0.1 (missing credentials, see [[2026-06-23 - Gradle Plugin Portal credential gap]])
+- [x] Publish python-embed-spring-boot-starter to Maven Central v1.0.1
+- [x] Bump version to 1.0.2-SNAPSHOT for next development cycle
+
+### targetOs Cross-Compilation (2026-06-24)
+- [x] Add targetOs property to PythonEmbedExtension
+- [x] Wire targetOs from extension to VenvTask in PythonEmbedPlugin
+- [x] Add resolveTargetOs(), isTargetWindows() helpers; update detectTargetTriple(), findPythonInDir(), makeExecutables()
+- [x] Add 10 tests for detectTargetTriple and findPythonInDir with explicit target OS
+- [x] Commit
+
+- **2026-06-24** Documentation overhaul and CI examples — completed all 5 steps: README reduced to landing page, MkDocs documentation site with 30+ pages, GitHub Actions for docs deployment and CI examples, aggregate runAllExamples Gradle task with per-example timeouts
+- [x] MkDocs documentation review and fixes (2026-06-24): Fixed wrong method names, wrong defaults, missing properties, inaccurate health check response, incomplete plugin docs, missing datetime types
+
+
+### runAllExamples ClassNotFoundException fix (2026-06-24)
+- [x] Add evaluationDependsOnChildren() and dependsOn classes tasks to runAllExamples
+- [x] Commit (9dd28e2)
+
+### Documentation Review and Fixes (2026-06-24)
+- [x] Fix wrong method names in docs (`5dcb926`)
+- [x] Fix wrong defaults in documentation
+- [x] Fix emoji rendering with pymdownx.emoji extension (`663d323`)
+- [x] Simplify architecture and batch documentation
+- [x] Remove unmeasured performance claims and library comparisons (`f11ea25`)
+- [x] Add missing datetime types to documentation
+- [x] Commit (`c6922f5`)
+
+### AGENTS.md Vault Rename (2026-06-24)
+- [x] Rename vault from `agent-memory` to `python-embed`
+- [x] Simplify paths (remove `Projects/` prefix)
+- [x] Streamline workflow instructions
+- [x] Commit (`085f28c`)
+
+### README Fix (2026-06-25)
+- [x] Add missing dependency declaration in Gradle example
+- [x] Commit (`0f645a1`)
+
+### Spring Boot HealthIndicator NoClassDefFoundError Fix (2026-06-25)
+- [x] Isolate HealthIndicator beans in static inner class with `@ConditionalOnClass`
+- [x] Starter version bumped to 1.0.3
+- [x] Commit (`5dcb926`, `915077e`)
+- **Decision**: [[2026-06-25 - Spring Boot HealthIndicator NoClassDefFoundError fix]]
+
+### Fingerprint Edge-Case Coverage (2026-06-26)
+- [x] Add 3 edge-case tests: null pythonSource, python version mismatch, missing python executable
+- [x] 129 lines of test coverage for incremental venv rebuild skip logic
+- [x] Commit (`7b62bf0`)
+- **Decision**: [[2026-06-26 - Fingerprint edge-case coverage]]
+
+### Builder Validation (2026-06-26)
+- [x] Add input validation in PythonEmbed.Options.Builder.build()
+- [x] Validate timeoutMs > 0, maxCodeLength > 0, startupTimeoutMs > 0
+- [x] Throw IllegalArgumentException with descriptive messages
+- [x] 3 unit tests for Builder validation
+- [x] Commit (7b2c610)
+- **Decision**: [[2026-06-26 - Builder validation]]
+
+### Test Coverage Enhancement (2026-06-26)
+- [x] Add 2 pool exhaustion tests (CallerRunsPolicy backpressure)
+- [x] Add 11 PythonValue null-safety tests
+- [x] Add 1 integration test for code length validation
+- [x] 14 total new tests across 3 test classes
+- [x] Commit (7b2c610)
+- **Decision**: [[2026-06-26 - Test coverage enhancement]]
+
+
+### Fail-fast Parameter Validation for PythonEmbed (2026-06-26)
+- [x] Add null/blank validation to all public PythonEmbed methods (eval, exec, execFile, warmup, batchEval, batchExec, stream, ref)
+- [x] Add variables null check to eval/exec with variables
+- [x] Create PythonEmbedValidationTest with 24 test cases
+- [x] All existing tests (runtime + spring-boot-starter) pass
+- **Decision**: [[2026-06-26 - Fail-fast parameter validation for PythonEmbed]]
+
+### CHANGELOG Updates for 1.0.4 / Gradle Plugin 1.0.3 (2026-06-26)
+- [x] Root CHANGELOG.md updated with 1.0.4 entry (build-common, maven-plugin, gradle-plugin refactoring, CI workflow split)
+- [x] Gradle plugin CHANGELOG.md updated with 1.0.3 entry (build-common extraction, VenvTask simplification, new properties)
+- [x] Build-common and maven-plugin CHANGELOGs verified complete
+
+
+---
+
+## Pool Cancel & Graceful Shutdown + Refactoring (2026-06-27)
+
+**Goal**: Add task cancel and graceful shutdown to PythonEmbedPool, reduce code duplication.
+
+- [x] D2 Task Cancel — CompletableFuture.cancel(true) interrupts thread, marks instance dirty, auto-replaces contaminated instance
+- [x] D3 Graceful close() — waits for in-flight tasks before shutdown; close(0, SECONDS) preserves immediate forced shutdown
+- [x] CloseReason.CANCELLED enum value added
+- [x] PythonEmbed.java refactored — timeout-less methods delegate to timeout variants (~51 lines removed)
+- [x] PythonEmbedPool.java refactored — extracted submitWithEmbed helper, ~216 lines removed
+- [x] All 87 tests pass (PythonEmbedPoolTest: 58 tests including 4 new cancel/graceful-close tests)
+- **Decision**: [[2026-06-27 - Pool cancel and graceful shutdown|Pool Cancel & Graceful Shutdown]]
+
+
+## Vault Cleanup (2026-06-27)
+
+- [x] Move orphan files to Decisions/ (2026-06-26 - Maven plugin deploy readiness.md, 2026-06-26 - Fail-fast parameter validation for PythonEmbed.md)
+- [x] Fix broken Session reference in _Index.md (2026-06-23 - python-embed ghost file)
+- [x] Update D4 description reflecting Micrometer YAGNI decision
+- [x] Add new Decisions to _Index.md
+- [x] Rebuild _Index.md

docs/examples/maven-example.md

@@ -64,4 +64,15 @@ try (PythonEmbed py = PythonEmbed.create()) {
 }
 ```
 
+## Advanced Configuration
+
+The example `pom.xml` includes commented-out examples of advanced settings:
+
+- **Cross-compilation**: Use `<targetOs>` to build Python for a different OS (e.g., `windows`, `linux`, `macos`)
+- **Custom pip index**: Use `<pipIndexUrl>` to install from a custom package index (e.g., PyTorch CUDA)
+- **Extra pip arguments**: Use `<pipExtraArgs>` for flags like `--extra-index-url`
+- **pyproject.toml**: Use `<pyprojectTomlFile>` to install dependencies from a `pyproject.toml`
+- **Python version**: Use `<pythonVersion>` to specify the standalone Python version
+- **requirements.txt**: Use `<requirementsFile>` to load dependencies from `requirements.txt`
+
 See [Installation](../installation.md) for detailed Maven configuration.

python-embed-build-common/src/main/java/io/github/howtis/pythonembed/build/VenvManager.java

@@ -33,6 +33,7 @@ private VenvManager() {
     public static PythonEnvironment setup(VenvConfig config) throws IOException {
         Consumer<String> log = config.logger();
         Path venvDir = config.venvDir();
+        String resolvedTargetOs = PythonResolver.resolveTargetOs(config.targetOs());
 
         // Collect packages
         List<String> packages = new ArrayList<>(config.packages());
@@ -73,14 +74,14 @@ public static PythonEnvironment setup(VenvConfig config) throws IOException {
 
         // Check stored fingerprint
         FingerprintManager.Fingerprint stored = FingerprintManager.read(venvDir);
-        boolean pythonPresent = PythonResolver.findPythonInDir(venvDir) != null;
+        boolean pythonPresent = PythonResolver.findPythonInDir(venvDir, resolvedTargetOs) != null;
         boolean pythonVersionMatch = stored != null && pythonVersion.equals(stored.pythonVersion);
         boolean packagesMatch = stored != null && currentPackageHash.equals(stored.packageHash);
         boolean sourceKnown = stored != null && stored.pythonSource != null;
 
         if (pythonPresent && pythonVersionMatch && packagesMatch && sourceKnown) {
             log.accept("Python environment is up to date, skipping setup");
-            Path pythonExe = PythonResolver.findPythonInDir(venvDir);
+            Path pythonExe = PythonResolver.findPythonInDir(venvDir, resolvedTargetOs);
             return new PythonEnvironment(pythonExe, venvDir, stored.pythonSource);
         }
 
@@ -99,21 +100,19 @@ public static PythonEnvironment setup(VenvConfig config) throws IOException {
             if (systemPython != null && !systemPython.contains(java.io.File.separator)) {
                 // System Python found
                 pythonSource = "system";
-                String targetOs = PythonResolver.resolveTargetOs(config.targetOs());
                 log.accept("Creating venv...");
                 runCommand(log, systemPython, "-m", "venv", venvDir.toString());
                 pythonExe = PythonResolver.resolveVenvPython(venvDir);
             } else {
                 // Download python-build-standalone
                 pythonSource = "bundled";
-                String targetOs = PythonResolver.resolveTargetOs(config.targetOs());
                 Path cacheDir = Path.of(System.getProperty("user.home"),
                         ".python-embed");
                 log.accept("System Python not found. Downloading python-build-standalone...");
-                pythonExe = PythonDownloader.download(pythonVersion, targetOs, cacheDir, venvDir, log);
+                pythonExe = PythonDownloader.download(pythonVersion, resolvedTargetOs, cacheDir, venvDir, log);
             }
         } else {
-            pythonExe = PythonResolver.findPythonInDir(venvDir);
+            pythonExe = PythonResolver.findPythonInDir(venvDir, resolvedTargetOs);
             if (pythonExe == null) {
                 throw new IOException("Python executable not found in: " + venvDir);
             }