CAMEL-23703: tooling/camel-exe - native camel.exe bootstrap for Windows

[ammachado]

Description

Slice of the larger CAMEL-23703 unified Camel CLI package distribution effort. This branch targets main.

It adds a native x64 bin/camel.exe to the camel-launcher Windows distribution, alongside bin/camel.bat. camel.exe is a thin bootstrap: it locates the adjacent camel.bat, forwards all arguments verbatim (preserving spaces and Unicode), inherits the standard streams, and returns the child exit code. It performs no Java discovery or option parsing itself; that all remains in camel.bat.

The executable exists so package managers that require a genuine executable command (such as WinGet's portable installer) can expose camel directly. Direct users may keep invoking bin\camel.bat; both behave identically. Windows ARM64 is not yet supported.

Module split

Native build logic lives in a new standalone module, tooling/camel-exe, with no Java upstream dependencies:

• camel.c source, MSVC Maven profile, and attached exe artifact
• CamelExeBootstrapTest (Windows-only behavioral tests)
• Release gate: -Dcamel.exe.requireWindowsExe=true

camel-launcher consumes the camel-exe:exe artifact on Windows (copy into target/ before assembly). User-visible distribution layout is unchanged: bin/camel.exe still ships inside camel-launcher-*-bin.zip.

Native bootstrap design

camel.exe (~130 lines of C) uses wide-char Windows APIs throughout:

• get_exe_dir() resolves the exe directory with a doubling-buffer loop, supporting paths beyond MAX_PATH (260) on Windows 10+ with long-path support enabled
• skip_argv0() strips argv[0] from the raw command line, preserving the caller's quoting
• Forwards via cmd.exe /S /C ""<dir>\camel.bat" <args>" to handle spaces and Unicode in paths
• All return values (_snwprintf_s, GetExitCodeProcess, CreateProcessW) are checked with diagnostics on failure

CI

The Windows workflow (.github/workflows/camel-launcher-windows.yml) uses path-filtered jobs with shallow clones:

Job	Paths	Command
camel-exe	tooling/camel-exe/**	mvn -pl tooling/camel-exe verify -Dcamel.exe.requireWindowsExe=true

This avoids building the full jbang plugin tree on every native-bootstrap change.

Also included: upgrade-guide note in camel-4x-upgrade-guide-4_22.adoc.

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.
• I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

AI-assisted contributions

• If this PR includes AI-generated code, commits have proper co-authorship attribution (e.g., Co-authored-by trailers) and the PR description identifies the AI tool used.

---

Claude Code on behalf of ammachado

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• docs
• dsl/camel-jbang/camel-launcher
• tooling
• tooling/camel-exe
• tooling/maven/camel-repackager-maven-plugin

---

🔬 Scalpel shadow comparison — Scalpel: 5 tested, 0 compile-only — current: 3 all tested

Maveniverse Scalpel detected 5 affected modules (current approach: 3).

⚠️ Modules only in Scalpel (2)

• camel-launcher
• docs

Skip-tests mode would test 5 modules (4 direct + 1 downstream), skip tests for 0 (generated code, meta-modules)

Modules Scalpel would test (5)

• camel-exe
• camel-launcher
• camel-launcher-container
• camel-repackager-maven-plugin
• docs

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-launcher. The related integration tests in dsl/camel-jbang/camel-jbang-it are excluded from CI. Consider running them manually:

mvn verify -f dsl/camel-jbang/camel-jbang-it -Djbang-it-test

All tested modules (5 modules)

• Camel :: Docs
• Camel :: Exe
• Camel :: Launcher
• Camel :: Launcher :: Container
• Camel :: Maven Plugins :: Repackager

---

⚙️ View full build and test results

[ammachado]

For the reviewers: should this feature trigger a camel-launcher build, or that can be handled during the release?

[gnodet]

Review: CAMEL-23703 — native camel.exe bootstrap for Windows

Verdict: COMMENT (no blocking issues found)
Confidence: HIGH

This is a well-structured contribution that adds a thin native Windows bootstrap (camel.exe) for the Camel CLI launcher, primarily to support WinGet's portable installer requirement for a genuine .exe command. The design choice to keep the exe as a pure forwarder to camel.bat (no Java discovery, no option parsing) is sound and minimizes the security and maintenance surface.

Strengths

• Clean C code: ~100 lines, well-commented, correct Windows API usage (wide-char throughout, proper handle cleanup, ZeroMemory initialization).
• Good test coverage: 5 behavioral tests covering argument forwarding, spaces in arguments, Unicode, exit code propagation, and spaced directory paths. The PowerShell-based UTF-8 capture approach for Unicode testing is clever.
• Proper module split: Separating camel-exe from camel-launcher avoids rebuilding the heavy jbang dependency graph for native bootstrap changes.
• CI workflow: Path-filtered Windows CI jobs avoid unnecessary builds. Change detection using git diff (instead of dorny/paths-filter) avoids fork PR failures.
• Documentation: Upgrade guide, module README, and native README are all present.

Findings

[MEDIUM] Silent truncation risk in _snwprintf_s — tooling/camel-exe/src/main/native/camel.c line 85. The _snwprintf_s call uses _TRUNCATE, which means if the formatted string exceeds cap, it silently truncates rather than failing. While the current +64 margin (31 chars of fixed overhead) makes this practically impossible for any realistic path, checking the return value for -1 (truncation indicator) would make the code more robust and prevent silent malformation. This is not a security issue (the user is trusted) but could cause confusing failures.

[LOW] MAX_PATH (260) limitation — tooling/camel-exe/src/main/native/camel.c line 54. On Windows 10+ with long path support enabled, paths can exceed 260 characters. The GetModuleFileNameW call with a fixed MAX_PATH buffer would fail for such installations. A dynamic allocation loop (doubling the buffer on ERROR_INSUFFICIENT_BUFFER) would future-proof this. Not a blocker since the vast majority of Windows installations operate within MAX_PATH.

[LOW] skip_argv0 does not handle escaped quotes — tooling/camel-exe/src/main/native/camel.c lines 33-49. The function stops at the first closing " when argv[0] is quoted, but Windows CommandLineToArgvW treats \" as a literal quote within a quoted argument. In practice, argv[0] comes from GetModuleFileNameW and will never contain escaped quotes, so this is purely academic.

[INFO] CI failure in camel-launcher-windows job — The camel-launcher-windows CI job fails, but the failure is in camel-management (a pre-existing test failure in an unrelated core module pulled in by -am). The camel-exe job passes cleanly. The launcher job's Maven command (-pl tooling/camel-exe,dsl/camel-jbang/camel-launcher -am install) pulls in the entire upstream dependency tree, which is why an unrelated failure surfaces.

[INFO] Scope overlap with merged PR #24666 — The first two commits (CAMEL-24053 .gitattributes fixes) were already included in merged PR #24666. After rebasing on latest main, these will become no-ops. This is expected stacking behavior and not an issue.

[INFO] POM packaging with test compilation — camel-exe uses <packaging>pom</packaging> but manually wires up build-helper-maven-plugin, maven-compiler-plugin, and maven-surefire-plugin for test compilation and execution. This is unconventional but pragmatic — there is no Java main source (the main artifact is the C-compiled exe), so pom packaging avoids the jar lifecycle overhead.

Scanner coverage

No static analysis tools (SonarCloud, SpotBugs, Error Prone) ran as part of this review. The C code (camel.c) falls outside the Java static analysis toolchain. Manual review was performed for memory safety, command injection, and Windows API correctness. This review does not replace specialized tools such as CodeRabbit or Sourcery.

---

Claude Code review on behalf of @gnodet

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

Thanks for this contribution @ammachado — the C code is clean, the test coverage is thorough (especially the Unicode capture workaround), and the module split makes sense.

The camel-launcher-windows CI job is currently failing: the assembled ZIP does not contain bin/camel.exe. The camel-exe job itself passes (native build + tests are green), so the issue is in the launcher integration — likely the maven-dependency-plugin:copy at generate-resources doesn't stage the file in time for the assembly, or the assembly doesn't pick it up. Worth investigating the phase ordering.

Minor observations (non-blocking):

• The assembly descriptor (bin.xml) unconditionally includes camel.exe from target/. On non-Windows builds this is silently skipped (intended), so the enforcer profile is the safety net — which is fine.
• The camel-exe module ordering in tooling/pom.xml looks correct (no downstream Java dependencies).

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of davsclaus

[davsclaus]

Review: CAMEL-23703 — tooling/camel-exe - native camel.exe bootstrap for Windows

Well-structured PR. The module split (tooling/camel-exe separate from camel-launcher) is clean and well-justified. The C code is solid — proper error handling on all paths, Unicode support via wide-char APIs, and long-path support via a doubling-buffer loop.

Findings

[LOW] Potential path mismatch in CamelLauncherWindowsExeIT.binArchiveIncludesCamelExe() — The test uses archive.getEntry("bin/camel.exe") but the assembly descriptor (bin.xml) has no <includeBaseDirectory>false</includeBaseDirectory>, so Maven Assembly Plugin defaults to true — entries would be prefixed with camel-launcher-VERSION-bin/bin/camel.exe. The CI PowerShell assertion handles this correctly with wildcard */bin/camel.exe, but the Java test would return null from getEntry. This test is double-gated (@EnabledOnOs(OS.WINDOWS) + @EnabledIfSystemProperty), so it doesn't block CI — but a developer running mvn verify -Dcamel.launcher.requireWindowsExe=true on Windows could hit this.

Positive observations

• C code quality: Both AI-review comments from the earlier review (truncation risk, MAX_PATH) flagged issues that were already handled in the code.
• Tests: Good coverage — behavioral tests with a fake camel.bat covering argument forwarding, Unicode preservation, exit code propagation, spaced paths, and graceful failure.
• Repackager guard: The non-jar artifact filter in RepackageMojo prevents the .exe from being embedded in BOOT-INF/lib. Well-tested.
• Conventions: Upgrade guide updated, license headers present, commit format correct.

This review does not replace specialized AI review tools (CodeRabbit, Sourcery) or static analysis (SonarCloud).

This review was generated by an AI agent (Claude Code on behalf of davsclaus) and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

[LOW] archive.getEntry("bin/camel.exe") uses an exact path, but the assembly descriptor (bin.xml) does not set <includeBaseDirectory>false</includeBaseDirectory> — Maven Assembly Plugin defaults to true, which prefixes entries with camel-launcher-VERSION-bin/. This means getEntry("bin/camel.exe") would return null.

The CI PowerShell assertion handles this correctly with wildcard matching (*/bin/camel.exe). Consider iterating entries with a suffix match here as well, or setting includeBaseDirectory to false in the assembly descriptor if that's the intended layout.

This test is double-gated (@EnabledOnOs(OS.WINDOWS) + @EnabledIfSystemProperty) so it doesn't affect CI, but would fail for a developer running mvn verify -Dcamel.launcher.requireWindowsExe=true on Windows.

[ammachado]

Good catch, same root cause as the CI assertion bug, fixed in f76de4f (suffix match instead of exact bin/camel.exe lookup, since includeBaseDirectory defaults to true in the assembly descriptor).

While digging into this I found a bigger gap worth flagging: the official release pipeline (Jenkinsfile.deploy) runs on ubuntu, and build-windows-exe / include-camel-exe only activate via <os><family>windows</family>. Neither camel.exe.requireWindowsExe nor camel.launcher.requireWindowsExe is set anywhere in that pipeline, so on an actual release the native compile is skipped, the camel.exe fileSet in bin.xml matches nothing, and the released camel-launcher-*-bin.zip ships without camel.exe, no error, just silently missing. That would break the Winget packaging from the other PR.

@davsclaus since you know the release process better than I do: is there already a place a Windows-hosted build step could hook into (e.g. a separate agent on the release Jenkins job), or should this be a post-release GitHub Actions job that builds the Windows artifact and uploads it alongside the rest of the release? Happy to put a PR together once there's a direction.

Claude Code on behalf of @ammachado
AI-generated review, so it may get things wrong. Please check any suggestion before you act on it.

[gnodet]

Good progress on the native camel.exe bootstrap. Previous review feedback has been addressed (truncation check on _snwprintf_s, get_exe_dir doubling loop for long paths, failsGracefullyWhenCamelBatIsMissing test). The C code is clean, the RepackageMojo fix is correct, and CI passes.

Two minor observations:

1. ZipFile handle leak in CI workflow (low)

In camel-launcher-windows.yml, the PowerShell assertion step chains:

$names = [System.IO.Compression.ZipFile]::OpenRead($zip.FullName).Entries.FullName

The ZipArchive returned by OpenRead is IDisposable but is never assigned to a variable for disposal, leaking a file handle. Practical impact is minimal since this is the last CI step and the runner is ephemeral. Fix is trivial: assign to variable and wrap in try/finally with $archive.Dispose().

2. Potential test hang from blocking readAllBytes (low)

In CamelExeBootstrapTest.run(), p.getInputStream().readAllBytes() blocks until the process closes stdout. If camel.exe hangs, the 60-second waitFor timeout on the next line is never reached and the test thread hangs indefinitely. Additionally, the process is never destroyed on timeout failure (no finally block). Practical risk is low with the controlled fake bat scripts, but worth fixing defensively — consider reading the stream asynchronously or wrapping in assertTimeout.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of @gnodet