CAMEL-23638: camel-jbang - Add CLI meta-tools to camel ask

[gnodet]

CAMEL-23638

Summary

Currently camel ask has ~26 hardcoded tool definitions. New CLI features (like camel get error --diagram) are not automatically available to the LLM. This adds 3 CLI meta-tools that give the LLM progressive access to the entire 126-command CLI:

• cli_list_commands(filter?) — discover available commands from the auto-generated camel-jbang-commands-metadata.json
• cli_command_help(command) — get detailed help for a specific command
• cli_exec(command) — execute any CLI command in-process and return captured output

The existing curated tools are preserved for common operations. The meta-tools serve as an escape hatch for everything else.

How the LLM uses it

Example flow for camel get error --diagram:

1. User asks "why did my message fail?"
2. LLM calls cli_list_commands("error") → sees get error: Get captured routing errors...
3. LLM calls cli_command_help("get error") → sees --diagram, --detail, --last, etc.
4. LLM calls cli_exec("get error --diagram") → gets the diagram + error details

Design decisions

• Metadata loaded from the auto-generated JSON already on the classpath — cached after first read
• Execution via CamelJBangMain.getCommandLine().execute() in-process (no subprocess)
• Output captured by temporarily swapping both Printer and picocli PrintWriter (both restored in finally)
• Command tokenization handles quoted strings (--filter="my route")
• New CLI commands are automatically available without code changes to Ask.java

Test plan

• Verify cli_list_commands returns all commands from metadata
• Verify cli_list_commands with filter narrows results correctly
• Verify cli_command_help("get error") returns all options
• Verify cli_exec("catalog component --filter=kafka") returns output
• Verify existing curated tools still work unchanged
• Unit tests for command tokenization (quoted strings, extra spaces, edge cases)

Claude Code on behalf of Guillaume Nodet

[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:

• 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]

Nice addition — the three CLI meta-tools are a clean way to give the LLM progressive access to the full CLI without bloating the curated tool list. A few minor observations and questions:

1. Tests: No tests for the new metadata loading and command discovery logic (loadCommandMetadata, collectCommands, findCommand). These are easily unit-testable without an LLM and would catch regressions.

2. Metadata caching: loadCommandMetadata() re-reads and re-parses the classpath JSON on every tool call. Since it's static, caching it in a field would save repeated I/O in a chat session.

3. Question — quoted arguments: cli_exec splits on \s+, so get route --filter="my route" won't work as expected. Worth documenting in the tool description?

4. Question — picocli out/err restore: The finally block restores the Printer but not the commandLine.setOut()/setErr() writers. If an exception occurs, they stay swapped.

Overall the design is solid — in-process picocli execution, output truncation at 32KB, and the system prompt update for LLM discoverability are all good choices. Approving.

This review is a project-rules and conventions check. It does not replace specialized review tools such as CodeRabbit or SonarCloud.

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

Claude Code on behalf of Claus Ibsen

[davsclaus]

LGTM