CAMEL-23335: camel-jbang - Lazy plugin discovery and resolved-classpath cache

[ammachado]

Description

Two related changes to remove per-invocation plugin overhead from camel:

• CamelJBangMain.execute now consults a new PluginHelper.shouldDiscoverPlugins
  gate before calling addPlugins. Built-in commands that do not consume plugins
  (e.g. version, get, ps, stop) short-circuit the plugin JSON read and
  FACTORY_FINDER classpath scan entirely. Plugin-consuming built-ins
  (run, export, cmd, shell), unknown subcommands (likely plugin-provided),
  and no-args/help still discover so plugin commands remain visible.

• PluginHelper.resolvePlugin now reads a resolved block from the per-plugin
  entry in ~/.camel-jbang-plugins.json. When present and valid (Camel version,
  gav, repos match; cached jars and the plugin POM unchanged by size+mtime), the
  plugin is loaded directly from a URLClassLoader over the cached jars, skipping
  FACTORY_FINDER and the Maven downloader. The resolved block is populated on
  the first successful Maven resolution; SNAPSHOT plugins rebuilt locally are
  picked up automatically via the mtime check.

Tests cover the gate's classification, cache hit, mtime-based invalidation, the
write path, and a paired before/after demonstration of the cache fast path
(no resolved block -> resolver invoked and quits; resolved block present ->
plugin loaded from the cached jar without invoking the resolver). The existing
testCacheInvalidatedOnMtimeChange is cleaned up to use assertThrows
instead of a try/empty-catch block.

Upgrade guide updated.

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com

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.

[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-jbang-core

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• dsl/camel-jbang/camel-jbang-core: 1 test(s) disabled on GitHub Actions

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-jbang-core. 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 (6 modules)

• Camel :: JBang :: Core
• Camel :: JBang :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Validate
• Camel :: Launcher :: Container

---

⚙️ View full build and test results

[davsclaus]

So I guess this makes this part a little bit faster - especially when you have custom plugins installed like forage

[davsclaus]

LGTM

[Croway]

@ammachado can you rebase on main and resolve the upgrade guide conflict please? once done, it is good to merge

[davsclaus]

@ammachado can you rebase on main and resolve the upgrade guide conflict please? once done, it is good to merge

I did that, the web editor is okay for some tasks like this