CAMEL-25489: Add semantic CLI command group

[luigidemasi]

Description

Adds scriptable access to the semantic runtime tooling introduced by #27602:

• camel semantic defaults to camel semantic get, listing definitions and experts. --expert exposes an expert's operations and parameter contracts.
• camel semantic eval evaluates a named definition using a sample body, headers and variables, or calls an expert operation directly with typed inputs and parameters.

Text listings use the CLI's standard tables, and --json produces one machine-readable document. Usage errors retain picocli suggestions and help in text mode; a generic usage-error hook handles JSON diagnostics. Known runtime versions older than Camel 4.23 fail immediately with exit code 3. Exit 1 reports runtime/action failures, while exit 70 distinguishes unexpected local CLI errors, including request-file I/O failures.

The CLI and semantic TUI requests use a shared RuntimeHelper overload that publishes independent request files atomically, waits for complete JSON responses and cleans up on success, timeout or interruption. The existing raw-text helper API remains compatible. Removing an unfinished request asks the connector to cancel it; provider interruption remains cooperative.

Includes help examples, usage and exit-code documentation, a link from the semantic language page, and regenerated command references, metadata and catalog documentation.

The root semantic command is registered in the AI help category. This fixes the missing category reported by GroupedCommandHelpRendererTest.noBuiltInCommandFallsIntoOther in CI run 38030361672.

Validation

• 72 focused CLI, grouped-help, request-helper, command-registration and expression-evaluator tests passed with retries disabled. The existing help-category regression failed before the category fix and passed afterward. The new expert-failure and text parse-error regressions also failed against the previous implementation and pass with the fixes.
• Full TUI suite: 1,853 passed, one skipped, with retries disabled. Includes partial-response polling and isolation from late replies after timeout.
• Runtime smoke test through the real file connector and semantic consoles using a local test expert: metadata, contracts, sample selectors, typed values, false results, error diagnostics, stopped-console rejection and restart.
• Full 704-module repository build passed: ./mvnw -B -ntp -T 4 -Dmaven.build.cache.enabled=false clean install -DskipTests.
• Antora validation passed for the staged documentation, including the new language-to-CLI link.

Target

• Targets main, after the merge of CAMEL-25491: Add metadata-driven semantic tooling to Camel TUI #27602.

Tracking

• CAMEL-25489

Apache Camel coding standards and style

• Commits have meaningful subjects and bodies.
• Full root build completed; formatting, import sorting and code generation ran, and generated changes are included.

AI-assisted contributions

• AI-assisted code has a Co-authored-by trailer.

Generated by OpenAI Codex via /oss-fix-ci-errors on behalf of Luigi De Masi (@luigidemasi).

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

[gnodet-bot]

Well-structured CLI feature with thorough input validation, consistent error handling (structured exit codes, JSON error output on stderr), atomic file I/O for the connector protocol, UUID-based file naming preventing concurrent client collision, and comprehensive test coverage including concurrency, timeout, IO failure, and all validation edge cases. ✅

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[github-actions]

🧪 CI tested the following changed modules:

• catalog/camel-catalog
• components/camel-ai/camel-semantic
• docs
• dsl/camel-jbang/camel-jbang-core
• dsl/camel-jbang/camel-jbang-plugin-tui

🔁 1 test passed only after a retry on JDK 25 (1 retried attempt)

Recovered flaky tests on JDK 25 (1)

Module	Test	Failed attempts	First failure
components/camel-ai/camel-semantic	SemanticConsoleTest.directEvaluationValidatesOperationParametersInputAndOutput	1	Expecting AtomicInteger(0) to have value: 1 but did not.

ℹ️ These tests did not fail the build. Surefire retried them and they passed.
Retries are enabled project-wide by surefire.rerunFailingTestsCount in parent/pom.xml.

---

🔬 Scalpel shadow comparison — Scalpel: 11 of 704 tested, 24 compile-only — current: 11 all tested

Maveniverse Scalpel detected 11 affected modules (current approach: 11).

Skip-tests mode would test 11 modules (5 direct + 9 downstream), skip tests for 24 (generated code, meta-modules)

Modules Scalpel would test (11)

• camel-jbang-mcp ← downstream of org.apache.camel:camel-catalog
• camel-jbang-plugin-mcp ← downstream of org.apache.camel:camel-jbang-core
• camel-jbang-plugin-route-parser ← downstream of org.apache.camel:camel-jbang-core
• camel-jbang-plugin-tui ← dsl/camel-jbang/camel-jbang-plugin-tui/src/main/java/org/apache/camel/dsl/jbang/core/commands/tui/MonitorContext.java
• camel-jbang-plugin-validate ← downstream of org.apache.camel:camel-jbang-core
• camel-launcher-container ← downstream of org.apache.camel:camel-launcher
• camel-semantic ← components/camel-ai/camel-semantic/src/main/docs/semantic-language.adoc
• camel-typesafe-ai ← downstream of org.apache.camel:camel-semantic
• camel-wolf-defender ← downstream of org.apache.camel:camel-semantic
• camel-yaml-dsl-validator ← downstream of org.apache.camel:camel-catalog
• camel-yaml-dsl-validator-maven-plugin ← downstream of org.apache.camel:camel-yaml-dsl-validator

Modules with tests skipped (24)

• apache-camel
• camel-allcomponents
• camel-catalog-console
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• camel-endpointdsl
• camel-endpointdsl-support
• camel-itest
• camel-jbang-it
• camel-jbang-main
• camel-jbang-plugin-edit
• camel-jbang-plugin-generate
• camel-jbang-plugin-kubernetes
• camel-jbang-plugin-test
• camel-kamelet-main
• camel-launcher
• camel-report-maven-plugin
• camel-route-parser
• camel-yaml-dsl
• camel-yaml-dsl-deserializers
• camel-yaml-dsl-maven-plugin
• coverage
• dummy-component

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

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

• dsl/camel-jbang/camel-jbang-core: 2 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 (38 modules, 6m 21s total)

Total reactor time: 6m 21s

Module	Duration	Status
Camel :: JBang :: Plugin :: TUI	50.6s	SUCCESS
Camel :: Launcher	50.2s	SUCCESS
Camel :: JBang :: MCP	39.0s	SUCCESS
Camel :: Catalog :: Camel Catalog	20.5s	SUCCESS
Camel :: Component DSL	18.3s	SUCCESS
Camel :: YAML DSL :: Validator	18.2s	SUCCESS
Camel :: YAML DSL	18.2s	SUCCESS
Camel :: AI :: TypeSafe AI	18.1s	SUCCESS
Camel :: JBang :: Plugin :: Kubernetes	15.9s	SUCCESS
Camel :: JBang :: Plugin :: Validate	15.9s	SUCCESS
Camel :: AI :: Semantic Evaluation	14.5s	SUCCESS
Camel :: JBang :: Plugin :: Testing	13.8s	SUCCESS
Camel :: Kamelet Main	12.7s	SUCCESS
Camel :: Docs	11.2s	SUCCESS
Camel :: AI :: Wolf-Defender	10.0s	SUCCESS
Camel :: Catalog :: Camel Report Maven Plugin	10.0s	SUCCESS
Camel :: YAML DSL :: Deserializers	7.1s	SUCCESS
Camel :: Catalog :: Camel Route Parser	6.7s	SUCCESS
Camel :: All Components Sync point	5.1s	SUCCESS
Camel :: YAML DSL :: Validator Maven Plugin	4.1s	SUCCESS
Camel :: Catalog :: Maven	2.9s	SUCCESS
Camel :: Catalog :: Suggest (deprecated)	2.7s	SUCCESS
Camel :: YAML DSL :: Maven Plugins	2.5s	SUCCESS
Camel :: JBang :: Main	1.5s	SUCCESS
Camel :: JBang :: Plugin :: Edit	1.5s	SUCCESS
Camel :: Coverage	1.4s	SUCCESS
Camel :: Catalog :: Dummy Component	1.3s	SUCCESS
Camel :: Assembly	1.2s	SUCCESS
Camel :: JBang :: Integration tests	1.1s	SUCCESS
Camel :: JBang :: Plugin :: Generate	1.0s	SUCCESS
Camel :: JBang :: Plugin :: MCP	1.0s	SUCCESS
Camel :: Endpoint DSL :: Support	0.8s	SUCCESS
Camel :: Catalog :: Console	0.7s	SUCCESS
Camel :: Launcher :: Container	0.6s	SUCCESS
Camel :: JBang :: Plugin :: Route Parser	0.6s	SUCCESS
Camel :: Endpoint DSL	n/a
Camel :: Integration Tests	n/a
Camel :: JBang :: Core	n/a

Top 20 slowest modules:

• Camel :: JBang :: Plugin :: TUI (50.6s)
• Camel :: Launcher (50.2s)
• Camel :: JBang :: MCP (39.0s)
• Camel :: Catalog :: Camel Catalog (20.5s)
• Camel :: Component DSL (18.3s)
• Camel :: YAML DSL :: Validator (18.2s)
• Camel :: YAML DSL (18.2s)
• Camel :: AI :: TypeSafe AI (18.1s)
• Camel :: JBang :: Plugin :: Kubernetes (15.9s)
• Camel :: JBang :: Plugin :: Validate (15.9s)
• Camel :: AI :: Semantic Evaluation (14.5s)
• Camel :: JBang :: Plugin :: Testing (13.8s)
• Camel :: Kamelet Main (12.7s)
• Camel :: Docs (11.2s)
• Camel :: AI :: Wolf-Defender (10.0s)
• Camel :: Catalog :: Camel Report Maven Plugin (10.0s)
• Camel :: YAML DSL :: Deserializers (7.1s)
• Camel :: Catalog :: Camel Route Parser (6.7s)
• Camel :: All Components Sync point (5.1s)
• Camel :: YAML DSL :: Validator Maven Plugin (4.1s)

---

⚙️ View full build and test results

[davsclaus]

I wonder if semantic should be under its own group

camel semantic get (default) so you can omit get, ie camel semantic
camel semantic eval

[davsclaus]

Thanks Luigi, this is a nice follow-up to #27602, and it is great to see the semantic tooling available to scripts and coding agents and not only the TUI.

What I checked:

• The request/reply protocol matches the connector on main: FileCliConnectorTransport scans {pid}-action-{id}.json, writes {pid}-output-{id}.json, and treats removal of the request file as cancellation. semantic-evaluate runs on the connector's own 2-thread pool, so the single-action-thread concern from the JIRA is already covered on the runtime side.
• The request keys (evaluation, body, headers, variables, expert, operation, input, parameters, timeout) and the 1–50000 ms bound match SemanticEvaluateConsole and LocalCliConnector.semanticResult.
• The client-side checks (no global: variables, direct call vs. named evaluation) follow the console, so bad input fails fast with exit 2 and no action file is written.
• The tests cover a lot: concurrency isolation, timeout cleanup that ignores a legacy -output.json, IO failure mapped to 70, parse errors as JSON. They use Awaitility, no Thread.sleep, and JUnit style is fine for this module.
• Docs use "Camel CLI" and next@ xrefs, the generated command pages and metadata are included, and CI is green.

I have a few points before merge (details inline):

1. Command naming. We already have camel eval expression --body --header --variable, so camel eval semantic could be the more natural home for the evaluate command. cmd semantic-evaluate also works. Command names are hard to change once released, so it would be good to settle this now.
2. camel get semantic prints tab-separated text, while the other camel get commands (including the single-integration get route-controller) render with AsciiTable.
3. Running against an application on an older Camel version waits the full 60 s and exits 4. The docs promise exit 3 for "unavailable semantic tooling".
4. The generic MissingPluginParameterExceptionHandler now knows about one concrete command type.

Smaller things, not tied to a line:

• The other cmd actions add a footer = {"%nExamples:", ...} to @Command. Adding one or two examples here would help --help users and agents.
• The "Developer consoles" section in semantic-language.adoc could link to the new CLI section in camel-jbang-managing.adoc, so readers of the language page find the commands.
• The exit code, stderr and JSON-error handling in SemanticActionCommand is a local version of what CAMEL-25389 and CAMEL-25391 (central error handling, ActionClient, shared --timeout) will provide. That is fine for now; please just keep it easy to switch over once those land.

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

[luigidemasi]

I wonder if semantic should be under its own group

camel semantic get (default) so you can omit get, ie camel semantic camel semantic eval

That gives to semantic a clearer home, I’ll adopt that layout and update the pr.

[luigidemasi]

@davsclaus, the five inline points each have a reply referencing cb9e3be25ada. The separate camel semantic [get|eval] layout from your earlier comment is implemented.

For the three additional points in your review:

1. Help examples: added @Command footers for the semantic group, get, and eval, including named-evaluation and direct-expert examples.
2. Language documentation link: added a link from “Developer consoles” to the CLI semantic section, regenerated the catalog mirror, and verified the link with Antora.
3. Future shared error handling and ActionClient: error rendering and exit codes remain in SemanticActionCommand; the generic UsageErrorHandler is the parse-error integration point. Request-file exchange now lives in a shared RuntimeHelper overload used by both the semantic CLI and TUI, so the transport implementation is no longer duplicated in the command. This keeps the later migration localized.

Validation passed: 68 focused tests, 1,853 TUI tests (one skipped), the runtime smoke test, the full 704-module build with tests skipped, and Antora. The new-head CI builds are still running.

AI-generated by OpenAI Codex on behalf of Luigi De Masi (@luigidemasi).

[davsclaus]

[camel-jbang-core] [ERROR] Failures:
[camel-jbang-core] [ERROR] org.apache.camel.dsl.jbang.core.commands.GroupedCommandHelpRendererTest.noBuiltInCommandFallsIntoOther
[camel-jbang-core] [ERROR] Run 1: GroupedCommandHelpRendererTest.noBuiltInCommandFallsIntoOther:80 An unmapped command fell into the 'Other' group — add it to a category in GroupedCommandHelpRenderer ==> expected: but was:
[camel-jbang-core] [ERROR] Run 2: GroupedCommandHelpRendererTest.noBuiltInCommandFallsIntoOther:80 An unmapped command fell into the 'Other' group — add it to a category in GroupedCommandHelpRenderer ==> expected: but was:
[camel-jbang-core] [ERROR] Run 3: GroupedCommandHelpRendererTest.noBuiltInCommandFallsIntoOther:80 An unmapped command fell into the 'Other' group — add it to a category in GroupedCommandHelpRenderer ==> expected: but was:

[davsclaus]

@luigidemasi there are test failures

[luigidemasi]

@davsclaus, fixed the help-category failure in 37da02c. I missed the category registration when moving semantic to the root commands. It now appears in the AI group.

The existing noBuiltInCommandFallsIntoOther test reproduced the failure before the one-line fix and passes afterward. All 72 selected CLI/help/helper tests passed with retries disabled, and the full 704-module build passed with tests skipped. The tests were left unchanged. Hosted CI has been triggered for the updated head.

AI-generated by OpenAI Codex on behalf of Luigi De Masi (@luigidemasi).