[
https://issues.apache.org/jira/browse/CAMEL-23236?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Claus Ibsen updated CAMEL-23236:
--------------------------------
Fix Version/s: 4.21.0
> camel-jbang - Improve beginner UX with interactive init, top-level doc, and
> contextual shell help
> -------------------------------------------------------------------------------------------------
>
> Key: CAMEL-23236
> URL: https://issues.apache.org/jira/browse/CAMEL-23236
> Project: Camel
> Issue Type: Improvement
> Components: camel-jbang
> Reporter: Guillaume Nodet
> Assignee: Guillaume Nodet
> Priority: Major
> Labels: beginner-experience, ux
> Fix For: 4.21.0
>
>
> h2. Overview
> This is an umbrella improvement to make the Camel JBang CLI more approachable
> for beginners. The current CLI is powerful but assumes users already know
> what they want — component names, template file extensions, command
> hierarchy. These changes reduce the "I don't know where to start" friction
> without compromising the experience for power users.
> *Key principles:*
> * _Opt-in interactivity_ — interactive features only activate when no
> arguments are given; scripted/CI usage is never affected
> * _Don't reinvent_ — build on existing infrastructure (CatalogDoc,
> SuggestSimilarHelper, JLine 4 ShellBuilder, plugin system)
> * _Keep commands flat_ — prefer top-level aliases over deeply nested
> subcommands
> h2. Detailed Plan
> h3. 1. {{camel doc}} as a top-level alias (trivial)
> {{camel catalog doc kafka}} already works and is comprehensive (URI syntax,
> path/query params, dependencies, "did you mean?" fuzzy matching,
> {{--open-url}} for browser). The problem is discoverability — beginners don't
> think to look under {{catalog}}.
> *Change:* Register {{CatalogDoc}} as a top-level subcommand {{doc}} in
> {{CamelJBangMain}}, in addition to its existing location under {{catalog}}.
> This is a ~5-line change.
> *Optionally:* Add a {{--example}} flag that prints a minimal working route
> snippet for the given component (e.g., a timer-to-log YAML route for the
> {{timer}} component). Data can come from the catalog or curated snippets.
> h3. 2. Context-aware shell banner (low effort)
> The shell already prints a banner on startup ("Apache Camel JBang Shell
> v4.19.0"). Make it context-aware:
> {code}
> Apache Camel JBang Shell v4.19.0
> No routes found in current directory.
> Quick start: init MyRoute.yaml && run *
> Templates: init --list
> Docs: doc <component>
> Need help? help
> {code}
> When routes *are* present, show a different hint:
> {code}
> Apache Camel JBang Shell v4.19.0
> Found 3 routes in current directory.
> Run: run *
> Watch: run * --dev
> {code}
> This replaces the idea of a first-run wizard — it's non-blocking,
> informative, and doesn't interrupt experienced users. Implementation lives in
> {{Shell.printBanner()}}.
> h3. 3. Interactive {{camel init}} template picker (medium effort)
> When {{camel init}} is invoked with *no arguments* in an interactive
> terminal, show an interactive template picker using JLine instead of printing
> an error.
> *Behavior:*
> * Present categories (Routes, Kamelets, Pipes, REST) with numbered options
> * User picks a category, then a template
> * Prompt for filename
> * Generate the file and print "Next steps" instructions
> *Non-interactive behavior is unchanged:* {{camel init MyRoute.yaml}} works
> exactly as before. The interactive picker is only triggered when: no
> positional arg is given AND stdin is a TTY AND not in CI.
> *Consider also:* Recipe-style templates that produce working examples (e.g.,
> "timer to log", "REST API with mock data", "file polling to Kafka") rather
> than empty scaffolds. These would be additional {{.tmpl}} files selected
> through the picker.
> h3. 4. {{camel run --example}} — zero to running in one command (medium
> effort)
> Allow running built-in examples without creating any files first:
> {code}
> camel run --example timer-log
> camel run --example rest-api
> camel run --example file-to-kafka
> {code}
> This is the absolute fastest on-ramp for beginners. Internally, these are
> bundled route files (YAML or Java) that are extracted to a temp directory and
> run. Combine with {{--dev}} mode for a "playground" experience.
> {{camel run --example --list}} would show available examples.
> h3. 5. Extend "did you mean?" to more commands (low effort)
> {{SuggestSimilarHelper}} is already used in {{CatalogDoc}} for fuzzy matching
> component/kamelet names. Extend its usage to:
> * {{camel run}} — when a component fails to resolve at runtime
> * {{camel get component <name>}} — when querying a non-existent component
> * Any other command that takes component/kamelet names as arguments
> h3. 6. {{camel doctor}} diagnostic command (medium effort)
> A diagnostic command that checks the environment and reports issues:
> {code}
> camel doctor
> Java: 21.0.2 (OK)
> JBang: 0.119.0 (OK)
> Camel: 4.19.0
> Maven: reachable (OK)
> Docker: running (OK)
> Disk space: OK
> Known issues: none
> {code}
> Checks to include:
> * Java version (21+ required)
> * JBang version
> * Maven central reachability
> * Docker daemon status (relevant for testcontainers)
> * Common port conflicts (8080, etc.)
> * Disk space in temp/cache directories
> h3. 7. Camel-Kit discoverability (low effort)
> camel-kit already works as a plugin ({{camel plugin add kit --gav
> io.github.luigidemasi:camel-jbang-plugin-kit:0.3.1}}). The problem is no one
> knows it exists.
> *Changes:*
> * Add a mention in {{camel init --help}} footer: "Tip: For AI-assisted
> project scaffolding, try: camel plugin add kit"
> * Mention in the shell banner when no routes are detected
> * Consider adding {{kit}} to the {{PluginType}} enum so {{camel plugin get
> --all}} shows it as a known plugin
> *Do NOT bundle camel-kit* as a built-in dependency — it's an external
> project. Keep the loose coupling via the plugin system.
> h2. Implementation Order
> ||Priority||Item||Effort||Impact||
> |1|{{camel doc}} top-level alias|Trivial|High|
> |2|Context-aware shell banner|Low|High|
> |3|Interactive {{camel init}} picker|Medium|High|
> |4|{{camel run --example}}|Medium|Very High|
> |5|Extend "did you mean?" suggestions|Low|Medium|
> |6|{{camel doctor}} command|Medium|Medium|
> |7|Camel-Kit discoverability|Low|Medium|
> Items 1-2 can be done in a single PR. Items 3-4 are the highest-impact
> changes and could be separate PRs. Items 5-7 are incremental improvements.
> h2. Related
> * PR [#22193|https://github.com/apache/camel/pull/22193] — Adds example usage
> snippets to CLI help text (complements this work)
> * PR [#22197|https://github.com/apache/camel/pull/22197] — TUI dashboards
> (camel monitor, camel catalog-tui)
> * [camel-kit|https://github.com/luigidemasi/camel-kit] — AI-assisted Camel
> development plugin
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
