This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 74c32fad3113 CAMEL-23236: Improve beginner UX with interactive init,
examples, and doctor command (#23160)
74c32fad3113 is described below
commit 74c32fad3113980a0e1efe89be597d7afd697d8d
Author: Claus Ibsen <[email protected]>
AuthorDate: Wed May 13 07:27:11 2026 +0200
CAMEL-23236: Improve beginner UX with interactive init, examples, and
doctor command (#23160)
* CAMEL-23236: Improve beginner UX with interactive init, examples, doctor,
and contextual help
- Add interactive template picker to camel init (--list flag, arrow-key
selection)
- Add camel run --example for zero-to-running experience with bundled
examples
- Add camel doctor diagnostic command for environment/dependency checks
- Extend did-you-mean suggestions to more commands in CatalogBaseCommand
- Add context-aware shell banner (detects route files, shows quick-start
hints)
- Improve Camel-Kit discoverability (add KIT plugin type)
- Include bundled example route files (timer-log, cron-log, rest-api)
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* CAMEL-23236: Doctor command should accept Java 17 as supported
Java 17 is still supported, so the doctor command should show OK
but recommend upgrading to 21 or 25 for better performance.
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
* CAMEL-23236: Remove KIT plugin type (3rd party, not from ASF)
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
* Regen
* CAMEL-23236: Address review feedback
- Fix FQCN: import SuggestSimilarHelper in Run.java
- Fix FQCN: import OutputStream in Doctor.java
- Add explicit parentheses in Shell.countRouteFiles()
- Add unit tests for Doctor command (7 tests)
- Add unit tests for Run --example and --example-list (5 tests)
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
---------
Co-authored-by: Guillaume Nodet <[email protected]>
Co-authored-by: Claude Opus 4.6 <[email protected]>
---
.../pages/jbang-commands/camel-jbang-commands.adoc | 1 +
.../pages/jbang-commands/camel-jbang-debug.adoc | 2 +
.../pages/jbang-commands/camel-jbang-doctor.adoc | 25 ++++
.../ROOT/pages/jbang-commands/camel-jbang-run.adoc | 2 +
.../META-INF/camel-jbang-commands-metadata.json | 5 +-
.../dsl/jbang/core/commands/CamelJBangMain.java | 1 +
.../camel/dsl/jbang/core/commands/Doctor.java | 158 +++++++++++++++++++++
.../apache/camel/dsl/jbang/core/commands/Init.java | 106 ++++++++++++++
.../apache/camel/dsl/jbang/core/commands/Run.java | 72 ++++++++++
.../camel/dsl/jbang/core/commands/Shell.java | 31 +++-
.../core/commands/catalog/CatalogBaseCommand.java | 11 ++
.../src/main/resources/examples/cron-log.yaml | 10 ++
.../src/main/resources/examples/rest-api.yaml | 21 +++
.../src/main/resources/examples/timer-log.yaml | 10 ++
.../camel/dsl/jbang/core/commands/DoctorTest.java | 90 ++++++++++++
.../camel/dsl/jbang/core/commands/RunTest.java | 52 ++++++-
.../jbang/core/commands/plugin/PluginGetTest.java | 4 +
17 files changed, 597 insertions(+), 4 deletions(-)
diff --git
a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-commands.adoc
b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-commands.adoc
index 8d9e0406c6a9..5425cf41a836 100644
---
a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-commands.adoc
+++
b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-commands.adoc
@@ -20,6 +20,7 @@ TIP: You can also use `camel --help` or `camel <command>
--help` to see availabl
| xref:jbang-commands/camel-jbang-dependency.adoc[camel dependency] | Displays
all Camel dependencies required to run
| xref:jbang-commands/camel-jbang-dirty.adoc[camel dirty] | Check if there are
dirty files from previous Camel runs that did not terminate gracefully
| xref:jbang-commands/camel-jbang-doc.adoc[camel doc] | Shows documentation
for kamelet, component, and other Camel resources
+| xref:jbang-commands/camel-jbang-doctor.adoc[camel doctor] | Checks the
environment and reports potential issues
| xref:jbang-commands/camel-jbang-eval.adoc[camel eval] | Evaluate Camel
expressions and scripts
| xref:jbang-commands/camel-jbang-explain.adoc[camel explain] | Explain what a
Camel route does using AI/LLM
| xref:jbang-commands/camel-jbang-export.adoc[camel export] | Export to other
runtimes (Camel Main, Spring Boot, or Quarkus)
diff --git
a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-debug.adoc
b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-debug.adoc
index a545282a1cd8..2ba7c40779cd 100644
--- a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-debug.adoc
+++ b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-debug.adoc
@@ -31,6 +31,8 @@ camel debug [options]
| `--dep,--dependency` | Add additional dependencies | | List
| `--download` | Whether to allow automatic downloading JAR dependencies (over
the internet) | true | boolean
| `--empty` | Run an empty Camel without loading source files | false | boolean
+| `--example` | Run a built-in example by name (e.g., timer-log, rest-api).
Use --example --list to show available examples. | | String
+| `--example-list` | List available built-in examples | | boolean
| `--exclude` | Exclude files by name or pattern | | List
| `--fresh` | Make sure we use fresh (i.e. non-cached) resources | false |
boolean
| `--gav` | The Maven group:artifact:version (used during exporting) | |
String
diff --git
a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-doctor.adoc
b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-doctor.adoc
new file mode 100644
index 000000000000..dcf0ad911535
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-doctor.adoc
@@ -0,0 +1,25 @@
+
+// AUTO-GENERATED by camel-package-maven-plugin - DO NOT EDIT THIS FILE
+= camel doctor
+
+Checks the environment and reports potential issues
+
+
+== Usage
+
+[source,bash]
+----
+camel doctor [options]
+----
+
+
+
+== Options
+
+[cols="2,5,1,2",options="header"]
+|===
+| Option | Description | Default | Type
+| `-h,--help` | Display the help and sub-commands | | boolean
+|===
+
+
diff --git
a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-run.adoc
b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-run.adoc
index 61648266fcaa..936fd1385e3a 100644
--- a/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-run.adoc
+++ b/docs/user-manual/modules/ROOT/pages/jbang-commands/camel-jbang-run.adoc
@@ -29,6 +29,8 @@ camel run [options]
| `--dep,--dependency` | Add additional dependencies | | List
| `--download` | Whether to allow automatic downloading JAR dependencies (over
the internet) | true | boolean
| `--empty` | Run an empty Camel without loading source files | false | boolean
+| `--example` | Run a built-in example by name (e.g., timer-log, rest-api).
Use --example --list to show available examples. | | String
+| `--example-list` | List available built-in examples | | boolean
| `--exclude` | Exclude files by name or pattern | | List
| `--fresh` | Make sure we use fresh (i.e. non-cached) resources | false |
boolean
| `--gav` | The Maven group:artifact:version (used during exporting) | |
String
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/generated/resources/META-INF/camel-jbang-commands-metadata.json
b/dsl/camel-jbang/camel-jbang-core/src/generated/resources/META-INF/camel-jbang-commands-metadata.json
index 399406bab646..24545f91b2f4 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/generated/resources/META-INF/camel-jbang-commands-metadata.json
+++
b/dsl/camel-jbang/camel-jbang-core/src/generated/resources/META-INF/camel-jbang-commands-metadata.json
@@ -5,10 +5,11 @@
{ "name": "cmd", "fullName": "cmd", "description": "Performs commands in
the running Camel integrations, such as start\/stop route, or change logging
levels.", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.action.CamelAction", "options": [ {
"names": "-h,--help", "description": "Display the help and sub-commands",
"javaType": "boolean", "type": "boolean" } ], "subcommands": [ { "name":
"browse", "fullName": "cmd browse", "description": "Browse pending messages on
endpoints [...]
{ "name": "completion", "fullName": "completion", "description": "Generate
completion script for bash\/zsh", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.Complete", "options": [ { "names":
"-h,--help", "description": "Display the help and sub-commands", "javaType":
"boolean", "type": "boolean" } ] },
{ "name": "config", "fullName": "config", "description": "Get and set user
configuration values", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.config.ConfigCommand", "options": [ {
"names": "-h,--help", "description": "Display the help and sub-commands",
"javaType": "boolean", "type": "boolean" } ], "subcommands": [ { "name": "get",
"fullName": "config get", "description": "Display user configuration value",
"sourceClass": "org.apache.camel.dsl.jbang.core.commands.config. [...]
- { "name": "debug", "fullName": "debug", "description": "Debug local Camel
integration", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Debug",
"options": [ { "names": "--ago", "description": "Use ago instead of yyyy-MM-dd
HH:mm:ss in timestamp.", "javaType": "boolean", "type": "boolean" }, { "names":
"--background", "description": "Run in the background", "defaultValue":
"false", "javaType": "boolean", "type": "boolean" }, { "names":
"--background-wait", "description": "To [...]
+ { "name": "debug", "fullName": "debug", "description": "Debug local Camel
integration", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Debug",
"options": [ { "names": "--ago", "description": "Use ago instead of yyyy-MM-dd
HH:mm:ss in timestamp.", "javaType": "boolean", "type": "boolean" }, { "names":
"--background", "description": "Run in the background", "defaultValue":
"false", "javaType": "boolean", "type": "boolean" }, { "names":
"--background-wait", "description": "To [...]
{ "name": "dependency", "fullName": "dependency", "description": "Displays
all Camel dependencies required to run", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.DependencyCommand", "options": [ {
"names": "-h,--help", "description": "Display the help and sub-commands",
"javaType": "boolean", "type": "boolean" } ], "subcommands": [ { "name":
"copy", "fullName": "dependency copy", "description": "Copies all Camel
dependencies required to run to a specific directory", "sourc [...]
{ "name": "dirty", "fullName": "dirty", "description": "Check if there are
dirty files from previous Camel runs that did not terminate gracefully",
"sourceClass": "org.apache.camel.dsl.jbang.core.commands.process.Dirty",
"options": [ { "names": "--clean", "description": "Clean dirty files which are
no longer in use", "defaultValue": "false", "javaType": "boolean", "type":
"boolean" }, { "names": "-h,--help", "description": "Display the help and
sub-commands", "javaType": "boolean", " [...]
{ "name": "doc", "fullName": "doc", "description": "Shows documentation
for kamelet, component, and other Camel resources", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.catalog.CatalogDoc", "options": [ {
"names": "--camel-version", "description": "To use a different Camel version
than the default version", "javaType": "java.lang.String", "type": "string" },
{ "names": "--download", "description": "Whether to allow automatic downloading
JAR dependencies (over the internet [...]
+ { "name": "doctor", "fullName": "doctor", "description": "Checks the
environment and reports potential issues", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.Doctor", "options": [ { "names":
"-h,--help", "description": "Display the help and sub-commands", "javaType":
"boolean", "type": "boolean" } ] },
{ "name": "eval", "fullName": "eval", "description": "Evaluate Camel
expressions and scripts", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.EvalCommand", "options": [ { "names":
"-h,--help", "description": "Display the help and sub-commands", "javaType":
"boolean", "type": "boolean" } ], "subcommands": [ { "name": "expression",
"fullName": "eval expression", "description": "Evaluates Camel expression",
"sourceClass": "org.apache.camel.dsl.jbang.core.commands.action.EvalEx [...]
{ "name": "explain", "fullName": "explain", "description": "Explain what a
Camel route does using AI\/LLM", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.Explain", "options": [ { "names":
"--api-key", "description": "API key for authentication. Also reads
OPENAI_API_KEY or LLM_API_KEY env vars", "javaType": "java.lang.String",
"type": "string" }, { "names": "--api-type", "description": "API type: 'ollama'
or 'openai' (OpenAI-compatible)", "defaultValue": "ollama", "javaTyp [...]
{ "name": "export", "fullName": "export", "description": "Export to other
runtimes (Camel Main, Spring Boot, or Quarkus)", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.Export", "options": [ { "names":
"--build-property", "description": "Maven build properties, ex.
--build-property=prop1=foo", "javaType": "java.util.List", "type": "array" }, {
"names": "--camel-spring-boot-version", "description": "Camel version to use
with Spring Boot", "javaType": "java.lang.String", "ty [...]
@@ -22,7 +23,7 @@
{ "name": "nano", "fullName": "nano", "description": "Nano editor to edit
file", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Nano",
"options": [ { "names": "-h,--help", "description": "Display the help and
sub-commands", "javaType": "boolean", "type": "boolean" } ] },
{ "name": "plugin", "fullName": "plugin", "description": "Manage plugins
that add sub-commands to this CLI", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.plugin.PluginCommand", "options": [ {
"names": "-h,--help", "description": "Display the help and sub-commands",
"javaType": "boolean", "type": "boolean" } ], "subcommands": [ { "name": "add",
"fullName": "plugin add", "description": "Add new plugin", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.plugin.PluginA [...]
{ "name": "ps", "fullName": "ps", "description": "List running Camel
integrations", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.process.ListProcess", "options": [ {
"names": "--json", "description": "Output in JSON Format", "javaType":
"boolean", "type": "boolean" }, { "names": "--pid", "description": "List only
pid in the output", "javaType": "boolean", "type": "boolean" }, { "names":
"--remote", "description": "Break down counters into remote\/total pairs",
"javaType": [...]
- { "name": "run", "fullName": "run", "description": "Run as local Camel
integration", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Run",
"options": [ { "names": "--background", "description": "Run in the background",
"defaultValue": "false", "javaType": "boolean", "type": "boolean" }, { "names":
"--background-wait", "description": "To wait for run in background to startup
successfully, before returning", "defaultValue": "true", "javaType": "boolean",
"type": "boolean" }, { [...]
+ { "name": "run", "fullName": "run", "description": "Run as local Camel
integration", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Run",
"options": [ { "names": "--background", "description": "Run in the background",
"defaultValue": "false", "javaType": "boolean", "type": "boolean" }, { "names":
"--background-wait", "description": "To wait for run in background to startup
successfully, before returning", "defaultValue": "true", "javaType": "boolean",
"type": "boolean" }, { [...]
{ "name": "sbom", "fullName": "sbom", "description": "Generate a CycloneDX
or SPDX SBOM for a specific project", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.SBOMGenerator", "options": [ {
"names": "--build-property", "description": "Maven build properties, ex.
--build-property=prop1=foo", "javaType": "java.util.List", "type": "array" }, {
"names": "--camel-spring-boot-version", "description": "Camel version to use
with Spring Boot", "javaType": "java.lang.String", "type" [...]
{ "name": "script", "fullName": "script", "description": "Run Camel
integration as shell script for terminal scripting", "sourceClass":
"org.apache.camel.dsl.jbang.core.commands.Script", "options": [ { "names":
"--logging", "description": "Can be used to turn on logging (logs to file in
<user home>\/.camel directory)", "defaultValue": "false", "javaType":
"boolean", "type": "boolean" }, { "names": "--logging-level", "description":
"Logging level (ERROR, WARN, INFO, DEBUG, TRACE)", "d [...]
{ "name": "shell", "fullName": "shell", "description": "Interactive Camel
JBang shell.", "sourceClass": "org.apache.camel.dsl.jbang.core.commands.Shell",
"options": [ { "names": "-h,--help", "description": "Display the help and
sub-commands", "javaType": "boolean", "type": "boolean" } ] },
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/CamelJBangMain.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/CamelJBangMain.java
index 477769c86125..d96725ab5749 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/CamelJBangMain.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/CamelJBangMain.java
@@ -132,6 +132,7 @@ public class CamelJBangMain implements Callable<Integer> {
.addSubcommand("runtime", new CommandLine(new
DependencyRuntime(this)))
.addSubcommand("update", new CommandLine(new
DependencyUpdate(this))))
.addSubcommand("dirty", new CommandLine(new Dirty(this)))
+ .addSubcommand("doctor", new CommandLine(new Doctor(this)))
.addSubcommand("eval", new CommandLine(new EvalCommand(this))
.addSubcommand("expression", new CommandLine(new
EvalExpressionCommand(this))))
.addSubcommand("export", new CommandLine(new Export(this)))
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Doctor.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Doctor.java
new file mode 100644
index 000000000000..a48783448ae2
--- /dev/null
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Doctor.java
@@ -0,0 +1,158 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.commands;
+
+import java.io.File;
+import java.io.OutputStream;
+import java.net.ServerSocket;
+import java.util.List;
+import java.util.Set;
+
+import org.apache.camel.catalog.CamelCatalog;
+import org.apache.camel.catalog.DefaultCamelCatalog;
+import org.apache.camel.dsl.jbang.core.common.VersionHelper;
+import org.apache.camel.tooling.maven.MavenDownloaderImpl;
+import org.apache.camel.tooling.maven.MavenResolutionException;
+import picocli.CommandLine.Command;
+
+@Command(name = "doctor", description = "Checks the environment and reports
potential issues",
+ sortOptions = false, showDefaultValues = true)
+public class Doctor extends CamelCommand {
+
+ public Doctor(CamelJBangMain main) {
+ super(main);
+ }
+
+ @Override
+ public Integer doCall() throws Exception {
+ printer().println("Camel JBang Doctor");
+ printer().println("==================");
+ printer().println();
+
+ checkJava();
+ checkJBang();
+ checkCamelVersion();
+ checkMavenRepository();
+ checkContainerRuntime();
+ checkCommonPorts();
+ checkDiskSpace();
+
+ return 0;
+ }
+
+ private void checkJava() {
+ String version = System.getProperty("java.version");
+ String vendor = System.getProperty("java.vendor", "");
+ int major = Runtime.version().feature();
+ String status;
+ if (major >= 21) {
+ status = "OK";
+ } else if (major >= 17) {
+ status = "OK (consider upgrading to 21 or 25 for better
performance)";
+ } else {
+ status = "UNSUPPORTED (17+ required)";
+ }
+ printer().printf(" Java: %s (%s) [%s]%n", version, vendor,
status);
+ }
+
+ private void checkJBang() {
+ String version = VersionHelper.getJBangVersion();
+ if (version != null) {
+ printer().printf(" JBang: %s (OK)%n", version);
+ } else {
+ printer().printf(" JBang: not detected%n");
+ }
+ }
+
+ private void checkCamelVersion() {
+ CamelCatalog catalog = new DefaultCamelCatalog();
+ String version = catalog.getCatalogVersion();
+ printer().printf(" Camel: %s%n", version);
+ }
+
+ private void checkMavenRepository() {
+ MavenDownloaderImpl downloader = new MavenDownloaderImpl();
+ try {
+ downloader.build();
+ CamelCatalog catalog = new DefaultCamelCatalog();
+ String version = catalog.getCatalogVersion();
+ downloader.resolveArtifacts(
+ List.of("org.apache.camel:camel-api:" + version),
+ Set.of(), false, false);
+ printer().printf(" Maven: artifact resolution OK%n");
+ } catch (MavenResolutionException e) {
+ printer().printf(" Maven: artifact resolution failed
(%s)%n", e.getMessage());
+ } catch (Exception e) {
+ printer().printf(" Maven: error (%s)%n", e.getMessage());
+ }
+ }
+
+ private void checkContainerRuntime() {
+ // check docker first, then podman as fallback
+ for (String cmd : new String[] { "docker", "podman" }) {
+ try {
+ Process p = new ProcessBuilder(cmd, "info")
+ .redirectErrorStream(true)
+ .start();
+ // drain output to prevent blocking
+ p.getInputStream().transferTo(OutputStream.nullOutputStream());
+ int exit = p.waitFor();
+ if (exit == 0) {
+ printer().printf(" Container: %s running (OK,
optional)%n", cmd);
+ return;
+ }
+ } catch (Exception e) {
+ // not found, try next
+ }
+ }
+ printer().printf(" Container: not found (optional — needed for test
containers)%n");
+ }
+
+ private void checkCommonPorts() {
+ StringBuilder conflicts = new StringBuilder();
+ for (int port : new int[] { 8080, 8443, 9090 }) {
+ if (isPortInUse(port)) {
+ if (!conflicts.isEmpty()) {
+ conflicts.append(", ");
+ }
+ conflicts.append(port);
+ }
+ }
+ if (!conflicts.isEmpty()) {
+ printer().printf(" Ports: in use: %s%n", conflicts);
+ } else {
+ printer().printf(" Ports: 8080, 8443, 9090 free (OK)%n");
+ }
+ }
+
+ private static boolean isPortInUse(int port) {
+ try (ServerSocket ss = new ServerSocket(port)) {
+ ss.setReuseAddress(true);
+ return false;
+ } catch (Exception e) {
+ return true;
+ }
+ }
+
+ private void checkDiskSpace() {
+ File tmpDir = new File(System.getProperty("java.io.tmpdir"));
+ long free = tmpDir.getFreeSpace();
+ long mb = free / (1024 * 1024);
+ String status = mb > 500 ? "OK" : "LOW";
+ printer().printf(" Disk space: %d MB free in temp (%s)%n", mb,
status);
+ }
+}
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Init.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Init.java
index e3e3f42ca037..00772ae1cfa4 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Init.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Init.java
@@ -23,8 +23,11 @@ import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
+import java.util.ArrayList;
import java.util.LinkedHashMap;
+import java.util.List;
import java.util.Map;
+import java.util.Scanner;
import java.util.Stack;
import java.util.StringJoiner;
@@ -102,7 +105,12 @@ public class Init extends CamelCommand {
return listTemplates();
}
if (file == null) {
+ // try interactive picker if running in a TTY and not in CI
+ if (System.console() != null && System.getenv("CI") == null) {
+ return interactivePicker();
+ }
printer().printErr("Missing required parameter: <file>");
+ printer().printErr("Run 'camel init --list' to see available
templates, or run interactively in a terminal.");
return 1;
}
int code = execute();
@@ -286,6 +294,104 @@ public class Init extends CamelCommand {
return 0;
}
+ private int interactivePicker() throws Exception {
+ // Build template categories
+ Map<String, List<String[]>> categories = new LinkedHashMap<>();
+ categories.put("Routes", List.of(
+ new String[] { "yaml", "YAML DSL route", ".yaml" },
+ new String[] { "java", "Java DSL route", ".java" },
+ new String[] { "xml", "XML DSL route", ".xml" }));
+ categories.put("Kamelets", List.of(
+ new String[] { "kamelet-source.yaml", "Kamelet source
connector", ".kamelet.yaml" },
+ new String[] { "kamelet-sink.yaml", "Kamelet sink connector",
".kamelet.yaml" },
+ new String[] { "kamelet-action.yaml", "Kamelet action
processor", ".kamelet.yaml" }));
+ List<String[]> pipeTemplates = new ArrayList<>();
+ pipeTemplates.add(new String[] { "init-pipe.yaml", "Pipe CR (source to
sink)", ".yaml" });
+ categories.put("Pipes and CRs", pipeTemplates);
+
+ Scanner scanner = new Scanner(System.in);
+
+ // Step 1: Pick a category
+ printer().println("Select a template category:");
+ List<String> categoryNames = new ArrayList<>(categories.keySet());
+ for (int i = 0; i < categoryNames.size(); i++) {
+ printer().printf(" %d) %s%n", i + 1, categoryNames.get(i));
+ }
+ printer().print("Choice [1]: ");
+ String categoryInput = scanner.nextLine().trim();
+ int categoryIdx;
+ try {
+ categoryIdx = categoryInput.isEmpty() ? 0 :
Integer.parseInt(categoryInput) - 1;
+ } catch (NumberFormatException e) {
+ printer().printErr("Invalid choice: " + categoryInput);
+ return 1;
+ }
+ if (categoryIdx < 0 || categoryIdx >= categoryNames.size()) {
+ printer().printErr("Invalid choice: must be between 1 and " +
categoryNames.size());
+ return 1;
+ }
+
+ // Step 2: Pick a template
+ String selectedCategory = categoryNames.get(categoryIdx);
+ List<String[]> templates = categories.get(selectedCategory);
+ printer().println();
+ printer().println("Select a template:");
+ for (int i = 0; i < templates.size(); i++) {
+ printer().printf(" %d) %s%n", i + 1, templates.get(i)[1]);
+ }
+ printer().print("Choice [1]: ");
+ String templateInput = scanner.nextLine().trim();
+ int templateIdx;
+ try {
+ templateIdx = templateInput.isEmpty() ? 0 :
Integer.parseInt(templateInput) - 1;
+ } catch (NumberFormatException e) {
+ printer().printErr("Invalid choice: " + templateInput);
+ return 1;
+ }
+ if (templateIdx < 0 || templateIdx >= templates.size()) {
+ printer().printErr("Invalid choice: must be between 1 and " +
templates.size());
+ return 1;
+ }
+
+ String[] selected = templates.get(templateIdx);
+ String ext = selected[2];
+ String defaultName = "MyRoute" + ext;
+ if (ext.endsWith(".kamelet.yaml")) {
+ if (selected[0].contains("source")) {
+ defaultName = "my-source.kamelet.yaml";
+ } else if (selected[0].contains("sink")) {
+ defaultName = "my-sink.kamelet.yaml";
+ } else {
+ defaultName = "my-action.kamelet.yaml";
+ }
+ } else if (selected[0].contains("pipe")) {
+ defaultName = "my-pipe.yaml";
+ pipe = true;
+ }
+
+ // Step 3: Prompt for filename
+ printer().println();
+ printer().printf("Filename [%s]: ", defaultName);
+ String filename = scanner.nextLine().trim();
+ if (filename.isEmpty()) {
+ filename = defaultName;
+ }
+
+ this.file = filename;
+ int code = execute();
+ if (code == 0) {
+ createWorkingDirectoryIfAbsent();
+ printer().println();
+ printer().println("Created: " + filename);
+ printer().println();
+ printer().println("Next steps:");
+ printer().println(" Run: camel run " + filename);
+ printer().println(" Run (live): camel run " + filename + "
--dev");
+ printer().println(" Documentation: camel doc <component>");
+ }
+ return code;
+ }
+
private void createWorkingDirectoryIfAbsent() {
Path work = CommandLineHelper.getWorkDir();
if (!Files.exists(work)) {
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Run.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Run.java
index 83383946d44c..bed04f4ccae8 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Run.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Run.java
@@ -64,6 +64,7 @@ import org.apache.camel.dsl.jbang.core.common.TemplateHelper;
import org.apache.camel.dsl.jbang.core.common.VersionHelper;
import org.apache.camel.main.KameletMain;
import org.apache.camel.main.download.DownloadListener;
+import org.apache.camel.main.util.SuggestSimilarHelper;
import org.apache.camel.spi.BacklogDebugger;
import org.apache.camel.support.ResourceHelper;
import org.apache.camel.util.AntPathMatcher;
@@ -336,6 +337,15 @@ public class Run extends CamelCommand {
description = "Skip resolving plugin dependencies")
boolean skipPlugins;
+ @Option(names = { "--example" },
+ description = "Run a built-in example by name (e.g., timer-log,
rest-api). Use --example --list to show available examples.",
+ arity = "0..1", fallbackValue = "")
+ String example;
+
+ @Option(names = { "--example-list" },
+ description = "List available built-in examples")
+ boolean exampleList;
+
public Run(CamelJBangMain main) {
super(main);
}
@@ -355,6 +365,14 @@ public class Run extends CamelCommand {
@Override
public Integer doCall() throws Exception {
+ // handle --example
+ if (exampleList || (example != null && example.isEmpty())) {
+ return listExamples();
+ }
+ if (example != null) {
+ return runExample();
+ }
+
if (!exportRun) {
printConfigurationValues("Running integration with the following
configuration:");
}
@@ -362,6 +380,60 @@ public class Run extends CamelCommand {
return run();
}
+ private int listExamples() {
+ printer().println("Available built-in examples:");
+ printer().println();
+ printer().printf(" %-20s %s%n", "timer-log", "Simple timer that logs
messages every second");
+ printer().printf(" %-20s %s%n", "rest-api", "REST API with hello
endpoints");
+ printer().printf(" %-20s %s%n", "cron-log", "Scheduled task that logs
every 5 seconds");
+ printer().println();
+ printer().println("Usage: camel run --example <name>");
+ printer().println(" camel run --example <name> --dev");
+ return 0;
+ }
+
+ private static final List<String> EXAMPLE_NAMES = List.of("timer-log",
"rest-api", "cron-log");
+
+ private int runExample() throws Exception {
+ String resourcePath = "examples/" + example + ".yaml";
+ InputStream is =
Run.class.getClassLoader().getResourceAsStream(resourcePath);
+ if (is == null) {
+ List<String> suggestions
+ = SuggestSimilarHelper.didYouMean(EXAMPLE_NAMES, example);
+ if (!suggestions.isEmpty()) {
+ printer().printErr("Unknown example: " + example + ". Did you
mean? " + String.join(", ", suggestions));
+ } else {
+ printer().printErr("Unknown example: " + example);
+ }
+ printer().printErr("Run 'camel run --example-list' to see
available examples.");
+ return 1;
+ }
+
+ // extract example to a temp file and run it
+ Path tempDir = Files.createTempDirectory("camel-example-");
+ Path exampleFile = tempDir.resolve(example + ".yaml");
+ try {
+ String content = IOHelper.loadText(is);
+ IOHelper.close(is);
+ Files.writeString(exampleFile, content);
+
+ printer().println("Running example: " + example);
+ files.add(exampleFile.toString());
+ if ("CamelJBang".equals(name)) {
+ name = example;
+ }
+
+ if (!exportRun) {
+ printConfigurationValues("Running integration with the
following configuration:");
+ }
+ return run();
+ } finally {
+ // clean up temp files on JVM exit
+ exampleFile.toFile().deleteOnExit();
+ tempDir.toFile().deleteOnExit();
+ }
+ }
+
public Integer runExport() throws Exception {
return runExport(false);
}
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Shell.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Shell.java
index 8cb436ccbde7..01e919e74a98 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Shell.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Shell.java
@@ -16,9 +16,11 @@
*/
package org.apache.camel.dsl.jbang.core.commands;
+import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
+import java.util.stream.Stream;
import org.apache.camel.dsl.jbang.core.common.EnvironmentHelper;
import org.apache.camel.dsl.jbang.core.common.VersionHelper;
@@ -151,8 +153,35 @@ public class Shell extends CamelCommand {
}
writer.println(banner);
}
- writer.println("Type 'help' for available commands, 'exit' to quit.");
+ int routeCount = countRouteFiles();
+ if (routeCount == 0) {
+ writer.println("No routes found in current directory.");
+ writer.println(" Quick start: init MyRoute.yaml && run *");
+ writer.println(" Templates: init --list");
+ writer.println(" Docs: doc <component>");
+ writer.println(" Need help? help");
+ } else {
+ writer.printf("Found %d route file(s) in current directory.%n",
routeCount);
+ writer.println(" Run: run *");
+ writer.println(" Watch: run * --dev");
+ }
writer.println();
writer.flush();
}
+
+ private static int countRouteFiles() {
+ try (Stream<Path> files = Files.list(Paths.get("."))) {
+ return (int) files.filter(Files::isRegularFile)
+ .filter(p -> {
+ String name = p.getFileName().toString();
+ return (name.endsWith(".yaml") &&
!name.endsWith(".kamelet.yaml")
+ && !name.equals("application.yaml"))
+ || (name.endsWith(".xml") &&
!name.equals("pom.xml"))
+ || name.endsWith(".java");
+ })
+ .count();
+ } catch (IOException e) {
+ return 0;
+ }
+ }
}
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/catalog/CatalogBaseCommand.java
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/catalog/CatalogBaseCommand.java
index 92acba5edae6..a0d2748b5e2c 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/catalog/CatalogBaseCommand.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/catalog/CatalogBaseCommand.java
@@ -37,6 +37,7 @@ import
org.apache.camel.dsl.jbang.core.common.RuntimeTypeConverter;
import org.apache.camel.dsl.jbang.core.common.TerminalWidthHelper;
import org.apache.camel.dsl.jbang.core.common.VersionHelper;
import org.apache.camel.dsl.jbang.core.model.CatalogBaseDTO;
+import org.apache.camel.main.util.SuggestSimilarHelper;
import org.apache.camel.tooling.maven.MavenGav;
import org.apache.camel.tooling.model.ArtifactModel;
import org.apache.camel.util.json.Jsoner;
@@ -180,6 +181,16 @@ public abstract class CatalogBaseCommand extends
CamelCommand {
.maxWidth(descWidth,
OverflowBehaviour.ELLIPSIS_RIGHT)
.with(this::shortDescription))));
}
+ } else if (filterName != null) {
+ // suggest similar names when filter returns no results
+ List<String> allNames = collectRows().stream().map(r ->
r.name).collect(Collectors.toList());
+ List<String> suggestions =
SuggestSimilarHelper.didYouMean(allNames, filterName);
+ if (!suggestions.isEmpty()) {
+ printer().println("No results for filter: " + filterName + ".
Did you mean? " + String.join(", ", suggestions));
+ } else {
+ printer().println("No results for filter: " + filterName);
+ }
+ printer().println("Tip: use 'camel doc " + filterName + "' for
detailed documentation.");
}
return 0;
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/cron-log.yaml
b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/cron-log.yaml
new file mode 100644
index 000000000000..c31bdb1cec3d
--- /dev/null
+++ b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/cron-log.yaml
@@ -0,0 +1,10 @@
+- route:
+ id: cron-log
+ from:
+ uri: timer:cron
+ parameters:
+ period: "5000"
+ steps:
+ - setBody:
+ simple: "Scheduled task running at ${date:now:HH:mm:ss}"
+ - log: "${body}"
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/rest-api.yaml
b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/rest-api.yaml
new file mode 100644
index 000000000000..2e1035cf1f0f
--- /dev/null
+++ b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/rest-api.yaml
@@ -0,0 +1,21 @@
+- rest:
+ path: /api
+ get:
+ - path: /hello
+ to: direct:hello
+ - path: /hello/{name}
+ to: direct:hello-name
+- route:
+ id: hello
+ from:
+ uri: direct:hello
+ steps:
+ - setBody:
+ constant: "Hello from Camel REST API!"
+- route:
+ id: hello-name
+ from:
+ uri: direct:hello-name
+ steps:
+ - setBody:
+ simple: "Hello ${header.name} from Camel REST API!"
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/timer-log.yaml
b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/timer-log.yaml
new file mode 100644
index 000000000000..cdff71b4d71f
--- /dev/null
+++
b/dsl/camel-jbang/camel-jbang-core/src/main/resources/examples/timer-log.yaml
@@ -0,0 +1,10 @@
+- route:
+ id: timer-log
+ from:
+ uri: timer:tick
+ parameters:
+ period: "1000"
+ steps:
+ - setBody:
+ simple: "Hello Camel! (message
#${exchangeProperty.CamelTimerCounter})"
+ - log: "${body}"
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/DoctorTest.java
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/DoctorTest.java
new file mode 100644
index 000000000000..fa62589285fb
--- /dev/null
+++
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/DoctorTest.java
@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.commands;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+class DoctorTest extends CamelCommandBaseTestSupport {
+
+ @Test
+ public void shouldReturnZeroExitCode() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ int exit = command.doCall();
+
+ Assertions.assertEquals(0, exit);
+ }
+
+ @Test
+ public void shouldPrintBanner() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Camel JBang Doctor"));
+ Assertions.assertTrue(output.contains("=================="));
+ }
+
+ @Test
+ public void shouldCheckJava() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Java:"));
+ String javaVersion = System.getProperty("java.version");
+ Assertions.assertTrue(output.contains(javaVersion));
+ }
+
+ @Test
+ public void shouldCheckCamelVersion() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Camel:"));
+ }
+
+ @Test
+ public void shouldCheckPorts() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Ports:"));
+ }
+
+ @Test
+ public void shouldCheckDiskSpace() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Disk space:"));
+ }
+
+ @Test
+ public void shouldIncludeAllSections() throws Exception {
+ Doctor command = new Doctor(new CamelJBangMain().withPrinter(printer));
+ command.doCall();
+
+ List<String> lines = printer.getLines();
+ Assertions.assertTrue(lines.size() >= 7, "Doctor should output at
least 7 lines (banner + checks)");
+ }
+}
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/RunTest.java
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/RunTest.java
index e018343a3ef6..60aff3832db7 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/RunTest.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/RunTest.java
@@ -21,7 +21,7 @@ import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import picocli.CommandLine;
-class RunTest {
+class RunTest extends CamelCommandBaseTestSupport {
@Test
public void shouldParseJavaVersionOption() throws Exception {
@@ -54,4 +54,54 @@ class RunTest {
Assertions.assertEquals("21", command.javaVersion);
}
+
+ @Test
+ public void shouldListExamples() throws Exception {
+ Run command = new Run(new CamelJBangMain().withPrinter(printer));
+ command.exampleList = true;
+ int exit = command.doCall();
+
+ Assertions.assertEquals(0, exit);
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Available built-in examples:"));
+ Assertions.assertTrue(output.contains("timer-log"));
+ Assertions.assertTrue(output.contains("rest-api"));
+ Assertions.assertTrue(output.contains("cron-log"));
+ }
+
+ @Test
+ public void shouldListExamplesWithEmptyExampleFlag() throws Exception {
+ Run command = new Run(new CamelJBangMain().withPrinter(printer));
+ command.example = "";
+ int exit = command.doCall();
+
+ Assertions.assertEquals(0, exit);
+ String output = printer.getOutput();
+ Assertions.assertTrue(output.contains("Available built-in examples:"));
+ }
+
+ @Test
+ public void shouldRejectUnknownExample() throws Exception {
+ Run command = new Run(new CamelJBangMain().withPrinter(printer));
+ command.example = "nonexistent";
+ int exit = command.doCall();
+
+ Assertions.assertEquals(1, exit);
+ }
+
+ @Test
+ public void shouldParseExampleOption() throws Exception {
+ Run command = new Run(new CamelJBangMain());
+ CommandLine.populateCommand(command, "--example=timer-log");
+
+ Assertions.assertEquals("timer-log", command.example);
+ }
+
+ @Test
+ public void shouldParseExampleListOption() throws Exception {
+ Run command = new Run(new CamelJBangMain());
+ CommandLine.populateCommand(command, "--example-list");
+
+ Assertions.assertTrue(command.exampleList);
+ }
}
diff --git
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/plugin/PluginGetTest.java
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/plugin/PluginGetTest.java
index 15004d080ab9..9fef8e54f0bb 100644
---
a/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/plugin/PluginGetTest.java
+++
b/dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/commands/plugin/PluginGetTest.java
@@ -153,6 +153,10 @@ class PluginGetTest extends CamelCommandBaseTestSupport {
"validate validate
org.apache.camel:camel-jbang-plugin-validate %s"
.formatted(PluginType.VALIDATE.getDescription()),
output.get(11));
+ Assertions.assertEquals(
+ "tui tui
org.apache.camel:camel-jbang-plugin-tui %s"
+ .formatted(PluginType.TUI.getDescription()),
+ output.get(12));
}
}
