CAMEL-23838: Fix camel-jbang TUI help (F1/? broken)

[ammachado]

Description

Fixes the broken context-sensitive help in the camel tui (camel-jbang TUI plugin). See CAMEL-23838.

Two independent problems:

1. F1 threw java.lang.NoClassDefFoundError: org/commonmark/renderer/markdown/MarkdownRenderer$MarkdownRendererExtension.

The camel-launcher fat-jar bundles every ASF plugin on a single flat classpath. Maven dependency mediation resolved a split commonmark:

• org.commonmark:commonmark (core) → 0.21.0, via camel-jbang-plugin-generate → openapi-generator:7.23.0 (declared first).
• org.commonmark:commonmark-ext-* → 0.28.0, via camel-jbang-plugin-tui → tamboui-markdown:0.4.0.

commonmark 0.21.0 does not contain the org.commonmark.renderer.markdown.MarkdownRenderer class at all (added later), so the TUI markdown help view (tamboui MarkdownView) blew up. Fixed by pinning org.commonmark:commonmark to 0.28.0 in camel-launcher's dependencyManagement so the core matches the extension modules. openapi-generator only uses the stable Parser/HtmlRenderer builder APIs, which are unchanged in 0.28.0, so it remains safe. The on-demand camel-jbang-main path was never affected, as it downloads only the requested plugin into its own classloader.

2. ? did nothing.

Only KeyCode.F1 was bound to help. ? is now bound to open/toggle help in CamelMonitor (guarded so it does not trigger while typing in a search/filter input), and HelpOverlay also closes on ? so the binding is a true toggle.

Also: documented the ? shortcut in camel-jbang-tui.adoc and added tests (HelpOverlayTest for close-on-?, F1/q regression, and that an unrelated key keeps the overlay open).

Review follow-up

Refinements from PR review:

• Extracted CamelMonitor.opensHelp(KeyEvent, boolean) so the F1/? open guard is unit-testable, and added CamelMonitorTest asserting ? is suppressed while a text input is focused but F1 is not.
• Removed an unreachable helpOverlay.close() branch in handleGlobalKeys: while the overlay is visible, dispatch already delegates to HelpOverlay.handleKeyEvent before reaching that code, so it only ever opened the overlay.
• Advertised ? alongside F1 in the overlay's close hint.
• Verified the commonmark pin at the bytecode level: openapi-generator's only commonmark consumer (Markdown.class) uses exactly Parser.builder()/parse(String) and HtmlRenderer.builder()/render(Node), all present with identical signatures in 0.28.0.

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 Adriano Machado.

[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-plugin-tui
• dsl/camel-jbang/camel-launcher

✅ POM dependency changes: targeted tests included

Modules affected by dependency changes (3)

• :camel-jbang-plugin-tui
• :camel-launcher
• :docs

💡 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 (4 modules)

• Camel :: Docs
• Camel :: JBang :: Plugin :: TUI
• Camel :: Launcher
• Camel :: Launcher :: Container

---

⚙️ View full build and test results

[ammachado]

Note on the upgrade guide (conscious omission): this PR intentionally does not add a camel-4x-upgrade-guide-4_21.adoc entry.

The change is a bugfix (the markdown help overlay threw NoClassDefFoundError because of a commonmark version clash on the launcher's flat classpath) plus an additive ? keybinding that is just an alias for the existing F1 help toggle. The TUI itself is new in 4.21, and there is no changed default, removed/renamed option, or behavior an upgrading user must act on, so an upgrade-guide entry would add noise rather than value. The user-facing keybinding reference (camel-jbang-tui.adoc) is updated instead.

Claude Code on behalf of Adriano Machado

[davsclaus]

Nice work, @ammachado — thorough investigation and a clean fix for both the commonmark version split and the missing ? binding.

Verified:

• The removed helpOverlay.close() branch in handleGlobalKeys was indeed unreachable: the dispatch flow (lines 389-390) delegates to helpOverlay.handleKeyEvent() and returns before handleGlobalKeys is reached when the overlay is visible.
• The commonmark 0.28.0 pin in camel-launcher/pom.xml is correctly scoped to the flat-classpath launcher only.
• opensHelp() extracted as static package-private is a good design choice for testability.

One minor suggestion: the comment in CamelMonitorTest (line 30) references (CAMEL-23838) — per project conventions, code comments shouldn't reference the current ticket (that context belongs in the PR/commit). The constraint explanation itself (why ? is treated differently from F1) is valuable, just without the ticket reference.

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