CAMEL-23236: Improve beginner UX with interactive init, examples, and doctor command

[davsclaus]

CAMEL-23236

Claude Code on behalf of Claus Ibsen

Replaces #22211 with a clean rebase and review feedback addressed.

Summary

Improve the beginner UX for Camel JBang by adding several features that help new users get started quickly:

• Interactive init template picker: When camel init is run without arguments in a TTY, presents a numbered menu to pick category (Routes, Kamelets, Pipes), template, and filename
• run --example: Bundled example routes (timer-log, cron-log, rest-api) that users can run immediately without creating files
• doctor command: Diagnostic command that checks environment setup (Java version, Maven artifact resolution, Docker/Podman, ports, disk space)
• Extended did-you-mean: Catalog commands now suggest similar names when a filter returns no results
• Context-aware shell banner: The interactive shell detects route files in the current directory and shows appropriate quick-start hints

Changes from original PR (#22211)

• Fixed: Doctor Java version check now correctly accepts Java 17 as supported (with a recommendation to upgrade to 21+)
• Removed: KIT plugin type (3rd party, not from ASF — should not be bundled)
• Cleaned: Rebased cleanly on main, removing all unrelated changes (upgrade guide deletions, route-diagram removal, eslint downgrades, elytron docs) that were rebase artifacts in the original PR

Review feedback addressed

• Fixed FQCN usage in Run.java (import SuggestSimilarHelper) and Doctor.java (import OutputStream)
• Added explicit parentheses in Shell.countRouteFiles() for readability
• Added unit tests: DoctorTest (7 tests), RunTest (5 new tests for --example and --example-list)

Test plan

• PluginGetTest passes with correct plugin count (no KIT)
• Full camel-jbang-core test suite passes (388 tests, 0 failures)
• DoctorTest — 7 tests covering banner, Java check, Camel version, ports, disk space
• RunTest — 5 new tests for --example-list, --example flag parsing, unknown example rejection
• camel init (no args, in TTY) shows interactive template picker
• camel run --example timer-log runs bundled example
• camel doctor reports environment diagnostics with correct Java 17 handling
• camel shell shows context-aware banner

🤖 Generated with Claude Code

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

Thanks for the work on improving the beginner UX — this is a nice set of features. A few items need attention before this can be merged.

Summary

1. FQCN in Run.java — uses org.apache.camel.main.util.SuggestSimilarHelper inline instead of importing it. The CI OpenRewrite check will flag this. (CatalogBaseCommand.java correctly imports it.)
2. FQCN in Doctor.java — uses java.io.OutputStream.nullOutputStream() inline instead of importing java.io.OutputStream.
3. Missing tests — three new features (Doctor command, interactive init picker, run --example) are added without unit tests. Per project conventions, every PR should include tests for new functionality. At minimum, Doctor, Run.runExample(), and Run.listExamples() should have basic coverage.
4. Minor: Shell.countRouteFiles() mixes && and || without explicit parentheses — correct by Java precedence, but parentheses would improve readability.

This review covers project rules and conventions only. It does not replace specialized review tools such as CodeRabbit, Sourcery, or SonarCloud.

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