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}")); + } +}
