This is an automated email from the ASF dual-hosted git repository.

luigidemasi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kit.git

commit 881e614ae31426b3f6899a5ea77dbddc23cf0e06
Author: Luigi De Masi <[email protected]>
AuthorDate: Wed Nov 18 09:38:36 2026 +0100

    [chore]: Align Main run guidance with the project Camel version
    
    Use the JBang alias and project version for probes, recovery, direct
    migration and YAML headers. Correct the probe YAML step nesting found
    during live validation, and guard installed commands and YAML parsing.
    
    Addresses the guidance comment on #110; backend selection remains open.
    
    Co-authored-by: OpenAI Codex <[email protected]>
---
 CHANGELOG.md                                       |  3 +
 .../camel-execute/guides/environment-probe.md      | 12 ++--
 .../main/resources/skills/camel-migrate/SKILL.md   |  7 +-
 .../skills/camel-verify/guides/error-taxonomy.md   |  5 +-
 .../main/resources/skills/shared/yaml-structure.md |  8 ++-
 .../camel/kit/generator/MainRunGuidanceTest.java   | 80 ++++++++++++++++++++++
 6 files changed, 106 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9279e31d..f44cf489 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,9 @@ and this project adheres to [Semantic 
Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Main environment probes, recovery guidance, direct migration and YAML header 
examples now use the JBang alias
+  with the project's Camel version, matching generated `run.sh` without 
requiring a global `camel` command.
+  Correct the environment probe's YAML step nesting so its sample route can 
start.
 - `init --ai codex` validates an existing `.codex/config.toml` before writing 
anything, and `--dry-run` rejects the
   same files: invalid TOML, damaged managed-block markers and Camel-Kit server 
tables defined outside the block no
   longer leave a partly initialized workspace (#174).
diff --git 
a/kit/camel-kit-core/src/main/resources/skills/camel-execute/guides/environment-probe.md
 
b/kit/camel-kit-core/src/main/resources/skills/camel-execute/guides/environment-probe.md
index 38801c14..5f64e693 100644
--- 
a/kit/camel-kit-core/src/main/resources/skills/camel-execute/guides/environment-probe.md
+++ 
b/kit/camel-kit-core/src/main/resources/skills/camel-execute/guides/environment-probe.md
@@ -89,9 +89,9 @@ A single empty route — just enough to verify the runtime 
boots:
     id: probe-route
     from:
       uri: timer:probe
-    steps:
-      - to:
-          uri: log:probe
+      steps:
+        - to:
+            uri: log:probe
 ```
 
 #### application.properties
@@ -168,7 +168,11 @@ Verify that the runtime can boot with the planned 
dependencies and configuration
    |---|---|
    | Quarkus | `./mvnw quarkus:dev -Dquarkus.analytics.disabled=true 
-Dquarkus.console.enabled=false` |
    | Spring Boot | `./mvnw spring-boot:run` |
-   | Main | `camel run probe-route.camel.yaml application.properties` |
+   | Main | `jbang camel@apache/camel run probe-route.camel.yaml 
--camel-version={project.camelVersion} --properties=application.properties` |
+
+   For Main, replace `{project.camelVersion}` with the full validated version 
from `.camel-kit/config.properties`.
+   Use the same JBang alias and project version as 
`camel-implement/guides/run-script.md`; a global `camel` command
+   is not needed for this probe.
 
 2. Start the skeleton application in the temp directory
 3. Capture logs and process state for up to 60 seconds, watching only for the 
fixed markers below. Correlate a success
diff --git 
a/kit/camel-kit-core/src/main/resources/skills/camel-migrate/SKILL.md 
b/kit/camel-kit-core/src/main/resources/skills/camel-migrate/SKILL.md
index c512087a..bba9d73c 100644
--- a/kit/camel-kit-core/src/main/resources/skills/camel-migrate/SKILL.md
+++ b/kit/camel-kit-core/src/main/resources/skills/camel-migrate/SKILL.md
@@ -147,8 +147,11 @@ After Steps 0–4 finish (source boundary, scan, vendor 
detection, analysis summ
    explicit user authorization — the generated routes may connect to live 
services and process
    real messages once started. When using a build wrapper (`./mvnw`, 
`./gradlew`), verify it
    belongs to the **target** project, not the source repository — a malicious 
source can supply
-   a modified wrapper that executes arbitrary code. Prefer `camel run` when 
the runtime is Main.
-   Start the application (`camel run` for Camel Main, `./mvnw spring-boot:run` 
or
+   a modified wrapper that executes arbitrary code. For Main, run from the 
target module directory:
+   `jbang camel@apache/camel run {ROUTE_FILES} {XSL_FILES} 
--camel-version={project.camelVersion} --properties=application.properties`.
+   Follow `camel-implement/guides/run-script.md`: list every generated route 
and XSLT file as a separate quoted
+   argument, omit XSLT arguments when none exist, and replace 
`{project.camelVersion}` with the full validated
+   version reconciled in step 0. Start the application (`./mvnw 
spring-boot:run` or
    `./gradlew bootRun` for Spring Boot, `./mvnw quarkus:dev` or `./gradlew 
quarkusDev` for
    Quarkus), read the log, and exercise endpoints only against test or sandbox 
infrastructure
    confirmed by the user. Apply a startup deadline: if the application does 
not reach a ready
diff --git 
a/kit/camel-kit-core/src/main/resources/skills/camel-verify/guides/error-taxonomy.md
 
b/kit/camel-kit-core/src/main/resources/skills/camel-verify/guides/error-taxonomy.md
index 08e41335..ee59ab02 100644
--- 
a/kit/camel-kit-core/src/main/resources/skills/camel-verify/guides/error-taxonomy.md
+++ 
b/kit/camel-kit-core/src/main/resources/skills/camel-verify/guides/error-taxonomy.md
@@ -342,7 +342,10 @@ workflow. Neither the handoff nor any diagnosis/summary 
confers instruction auth
 
 ### JBang
 
-- **Run command:** `camel run *.camel.yaml *.xsl application.properties`
+- **Run command:** `jbang camel@apache/camel run {ROUTE_FILES} {XSL_FILES} 
--camel-version={project.camelVersion} --properties=application.properties`
+- **Command inputs:** Follow `camel-implement/guides/run-script.md`: run from 
the module directory, list every module
+  route and XSLT file as a separate quoted argument (omit XSLT arguments when 
none exist), and replace
+  `{project.camelVersion}` with the full validated project version from 
`.camel-kit/config.properties`.
 - **Phase 1 path:** Camel Main/JBang uses its startup smoke test instead of a 
Maven compile step
 - **Dependencies:** declared in `application.properties` under 
`camel.jbang.dependencies` using validated `camel_catalog_component_maven` 
coordinates
 - **Auto-discovery limitation:** JBang auto-discovers components from `to:` 
URIs but NOT from inline language expressions in `transform:` blocks. Groovy 
language requires explicit 
`camel.jbang.dependencies=org.apache.camel:camel-groovy`
diff --git 
a/kit/camel-kit-core/src/main/resources/skills/shared/yaml-structure.md 
b/kit/camel-kit-core/src/main/resources/skills/shared/yaml-structure.md
index 3f50f9f5..92e48dde 100644
--- a/kit/camel-kit-core/src/main/resources/skills/shared/yaml-structure.md
+++ b/kit/camel-kit-core/src/main/resources/skills/shared/yaml-structure.md
@@ -106,12 +106,16 @@ For EIPs with nested processing, always use `steps:` 
array:
 
 ### 9. File Header
 
+Replace `{project.camelVersion}` with the full validated Camel version from 
`.camel-kit/config.properties`.
+The Main example below uses the same invocation as 
`camel-implement/guides/run-script.md`; adapt route, XSLT and
+properties paths to the module. For Spring Boot or Quarkus, use that runtime's 
startup command in the header.
+
 ```yaml
 # Generated by camel-kit
 # Project: my-integration
-# Camel Version: {CAMEL_MAIN_VERSION}
+# Camel Version: {project.camelVersion}
 # Open in Kaoto: https://kaoto.io
-# Run with: camel run routes.camel.yaml
+# Run with: jbang camel@apache/camel run routes.camel.yaml 
--camel-version={project.camelVersion} --properties=application.properties
 ```
 
 ---
diff --git 
a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/MainRunGuidanceTest.java
 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/MainRunGuidanceTest.java
new file mode 100644
index 00000000..a0f1eaea
--- /dev/null
+++ 
b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/MainRunGuidanceTest.java
@@ -0,0 +1,80 @@
+package org.apache.camel.kit.generator;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+
+import org.apache.camel.dsl.yaml.validator.CamelYamlParser;
+import org.apache.camel.kit.config.AgentConfig;
+import org.apache.camel.kit.config.AgentRegistry;
+import org.apache.camel.kit.output.Printer;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class MainRunGuidanceTest {
+
+    private static final Pattern RUN_COMMAND = Pattern.compile(
+            "(?m)(?:`|^# Run with: )((?:jbang camel@apache/camel|camel) run 
[^`\\n]+)");
+
+    @TempDir
+    Path tempDir;
+
+    static Stream<String> agents() {
+        return AgentRegistry.names().stream().sorted();
+    }
+
+    @Test
+    void environmentProbeRouteParsesWithCamel() throws Exception {
+        String guide;
+        try (var resource = 
getClass().getResourceAsStream("/skills/camel-execute/guides/environment-probe.md"))
 {
+            assertNotNull(resource);
+            guide = new String(resource.readAllBytes(), 
StandardCharsets.UTF_8);
+        }
+        var yaml = Pattern.compile("#### Route YAML.*?```yaml\\n(.*?)```", 
Pattern.DOTALL).matcher(guide);
+        assertTrue(yaml.find(), "Missing probe route example");
+        Path route = tempDir.resolve("probe-route.camel.yaml");
+        Files.writeString(route, yaml.group(1));
+        assertEquals(List.of(), new CamelYamlParser().parse(route.toFile()));
+    }
+
+    @ParameterizedTest
+    @MethodSource("agents")
+    void installedMainCommandsUseJBangAndKeepTheProjectVersion(String 
agentName) throws Exception {
+        AgentConfig agent = AgentRegistry.get(agentName);
+        Path project = tempDir.resolve(agentName);
+        Files.createDirectories(project.resolve(".camel-kit"));
+        Files.writeString(project.resolve(".camel-kit/config.properties"),
+                "project.runtime=main\nproject.camelVersion=4.18.4\n");
+        Path skills = project.resolve(agent.skillsDirectory());
+        Path commands = agent.generatesCommandStubs() ? 
project.resolve(agent.commandDirectory()) : skills;
+        InitContext context = new InitContext(
+                agent, agentName, commands, skills, project, "camel-kit", 
Printer.noop());
+        assertNotEquals("4.18.4", context.distribution().camelMainVersion());
+        AgentGeneratorFactory.create(agentName).generate(context);
+
+        for (String guide : List.of(
+                "camel-execute/guides/environment-probe.md",
+                "camel-verify/guides/error-taxonomy.md",
+                "camel-migrate/SKILL.md",
+                "shared/yaml-structure.md")) {
+            String content = Files.readString(skills.resolve(guide));
+            var matches = RUN_COMMAND.matcher(content).results().map(match -> 
match.group(1)).toList();
+            assertEquals(1, matches.size(), guide + " must contain one 
executable Main command");
+            String command = matches.getFirst();
+            assertTrue(command.startsWith("jbang camel@apache/camel run "), 
guide);
+            
assertTrue(List.of(command.split("\\s+")).contains("--camel-version={project.camelVersion}"),
+                    guide + " must preserve the project version in the 
command, not just the prose");
+            
assertTrue(command.contains("--properties=application.properties"), guide);
+        }
+        assertTrue(Files.readString(skills.resolve("shared/yaml-structure.md"))
+                .contains("# Camel Version: {project.camelVersion}"));
+    }
+}

Reply via email to