CAMEL-23703: camel-launcher - package distribution (JReleaser packagers + website installers)

docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_22.adoc

@@ -80,6 +80,47 @@ The Gentoo `java-config` auto-detection and the IBM AIX `$JAVA_HOME/jre/sh/java`
 removed; set `JAVA_HOME` or `JAVACMD` explicitly on those platforms.
 `JAVA_OPTS` handling is unchanged: when unset, the default `-Xmx512m` heap is applied.
 
+==== Website installers for the Camel CLI
+
+Two canonical installer scripts are now available for installing the
+xref:camel-jbang-launcher.adoc[Camel CLI Launcher] without a package manager:
+
+[source,bash]
+----
+curl -fsSL https://camel.apache.org/install.sh | sh
+----
+
+[source,powershell]
+----
+irm https://camel.apache.org/install.ps1 | iex
+----
+
+With no arguments, both installers resolve and install the latest published release. An exact
+version can be requested instead with `--version X.Y.Z` (`install.sh`) or `-Version X.Y.Z`
+(`install.ps1`); the requested version is validated and matched against the fetched manifest
+before anything is downloaded.
+
+Both installers download the release archive from Maven Central, verify it against a SHA-256
+recorded in a signed-path manifest before extracting it, and reject archives containing absolute
+paths, `../` traversal, escaping symlinks/reparse points, or more than one top-level directory.
+The staged launcher is then run once to confirm a Java 17+ runtime can be discovered (see
+"Camel CLI launcher Java runtime discovery" above); if that check fails, the previously active
+installation, if any, is left untouched and the installer exits nonzero.
+
+Installation is always per-user and never requires elevation or `sudo`:
+
+* POSIX (`install.sh`) installs under `${XDG_DATA_HOME:-$HOME/.local/share}/camel-cli/versions/<version>`
+  and activates it via a symlink at `$HOME/.local/bin/camel`. The installer never writes to shell
+  profile files (`.bashrc`, `.profile`, etc.); if `$HOME/.local/bin` is not already on `PATH`, it
+  prints guidance instead.
+* Windows (`install.ps1`) installs under `%LOCALAPPDATA%\Apache Camel\cli\versions\<version>` and
+  activates it via a `camel.cmd` shim at `%LOCALAPPDATA%\Apache Camel\bin\camel.cmd` that delegates
+  to the staged `camel.exe`. The bin directory is added once, case-insensitively, to the current
+  user's `PATH`; the machine `PATH` is never modified.
+
+Previously installed version directories are left in place after an upgrade, downgrade, or
+reinstall and must be removed manually.
+
 === camel-langchain4j-agent
 
 The `Agent.chat()` method return type has changed from `String` to `Result<String>` (from `dev.langchain4j.service.Result`).

dsl/camel-jbang/camel-launcher/jreleaser.yml

@@ -0,0 +1,123 @@
+#
+# 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.
+#
+
+# NOTE: field names and packager semantics verified against the JReleaser 1.25.0
+# reference (ctx7 docs, cross-checked with `mvn help:describe` and actual
+# `jreleaser:prepare` dry-run output against the pinned plugin JAR) before
+# authoring this file. Key findings that shaped this configuration:
+#   - `type: JAVA_BINARY` (not BINARY): Homebrew's automatic `openjdk` dependency is
+#     documented as applying to "applicable Java distributions"; confirmed the
+#     generated formula includes `depends_on "openjdk@17"`.
+#   - SDKMAN has no boolean "default" flag; `command: MAJOR` publishes and sets the
+#     new version as the candidate default, `command: MINOR` publishes without
+#     moving the default. SDKMAN produces no local `prepare` output (API-only), so
+#     channel-specific MAJOR/MINOR selection only matters at Phase 5 publish time.
+#   - `{{ Env.X }}` reads real OS environment variables (java.lang.System#getenv),
+#     not Maven -D system properties, so the wrappers export CAMEL_PKG_* before
+#     invoking JReleaser. Enum-typed fields (active, sdkman.command) are parsed
+#     before Mustache templates resolve, so `{{ Env.X }}` cannot be used on them.
+#   - Artifact paths are relative to the repo root: empirically (mvn jreleaser:config),
+#     the JReleaser Maven plugin's basedir defaults to the multi-module reactor root,
+#     not this file's directory, unlike the standalone JReleaser CLI.
+#   - Per-channel packager selection (e.g. excluding `scoop` on the `lts` channel)
+#     is done via the jreleaser:prepare/jreleaser:package Mojo's own
+#     `-Djreleaser.packagers` include filter, not via a templated `active` field.
+#   - Every packager overrides `downloadUrl` to the Maven Central coordinates
+#     (matching Phase 3A's installers and docs/getting-started.adoc); JReleaser's
+#     default download URL points at a GitHub release asset, which this project
+#     does not publish artifacts to.
+#   - `project.vendor` and `distributions.camel-cli.tags` are required fields in
+#     practice (validation fails without them) despite docs implying defaults.
+# This file renders no package content itself; per-packager overrides live under
+# src/jreleaser/distributions/camel-cli/<packager>/.
+#
+# KNOWN GAP: `--channel stable --lts-line X.Y` is specified to also publish a
+# versioned Homebrew formula (`camel@X.Y`) alongside the unversioned `camel`
+# formula. This file declares only one `brew` packager per distribution, so today
+# it only ever produces the single formula selected by CAMEL_PKG_BREW_FORMULA.
+# Producing both formulae from one release is deferred to a follow-up task.
+# Empirically confirmed (jreleaser:prepare with CAMEL_PKG_BREW_FORMULA=camel@4.20):
+# JReleaser does not apply Homebrew's "AT" naming convention to `formulaName`, so a
+# literal "camel@4.20" renders an invalid Ruby class (`class Camel@4.20 < Formula`)
+# and a wrong output filename (`20.rb` instead of `camel@4.20.rb`). Producing a
+# correct versioned formula needs formulaName pre-converted to Homebrew's
+# convention (e.g. "CamelAT420") as part of the same follow-up task above.
+
+project:
+  name: camel-cli
+  description: Apache Camel CLI
+  links:
+    homepage: https://camel.apache.org/
+  authors:
+    - The Apache Camel Team
+  license: Apache-2.0
+  vendor: The Apache Software Foundation
+  languages:
+    java:
+      groupId: org.apache.camel
+      version: 17
+
+distributions:
+  camel-cli:
+    type: JAVA_BINARY
+    tags:
+      - cli
+    executable:
+      name: camel
+      # The zip/tar bin/ directory ships `camel.sh` (Unix) and `camel.bat`/`camel.exe`
+      # (Windows) per src/main/assembly/bin.xml; without this, `distributionExecutableUnix`
+      # defaults to the bare distribution name ("camel"), which does not exist on disk and
+      # produces a broken symlink in the Homebrew/Scoop/Chocolatey templates. Windows already
+      # defaults correctly to `bat`.
+      unixExtension: sh
+    artifacts:
+      - path: "dsl/camel-jbang/camel-launcher/target/camel-launcher-{{projectVersion}}-bin.zip"
+    brew:
+      active: RELEASE
+      formulaName: "{{ Env.CAMEL_PKG_BREW_FORMULA }}"
+      downloadUrl: "https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/{{projectVersion}}/{{artifactFile}}"
+      # templateDirectory defaults to "src/jreleaser/distributions/#{distribution.name}/brew"
+      # resolved against the JReleaser basedir, which is the multi-module reactor root (see
+      # NOTE above), not this module's directory. Empirically confirmed (jreleaser:prepare
+      # trace.log): without this override the module's formula.rb.tpl is silently ignored
+      # and JReleaser falls back to its embedded default template.
+      templateDirectory: "dsl/camel-jbang/camel-launcher/src/jreleaser/distributions/camel-cli/brew"
+      extraProperties:
+        # Non-empty only for versioned formulae (e.g. "camel@4.20"); used by
+        # formula.rb.tpl as a Mustache truthiness check (empty string == falsy)
+        # to add `keg_only :versioned_formula` and its PATH caveat.
+        versionedFormula: "{{ Env.CAMEL_PKG_BREW_VERSIONED }}"
+    sdkman:
+      active: RELEASE
+      candidate: camel
+      downloadUrl: "https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/{{projectVersion}}/{{artifactFile}}"
+      # command (MAJOR/MINOR) defaults to MAJOR here (correct for `stable`); see the
+      # NOTE above on why per-channel selection is deferred to Phase 5 publish.
+    winget:
+      active: RELEASE
+      downloadUrl: "https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/{{projectVersion}}/{{artifactFile}}"
+      package:
+        identifier: Apache.CamelCLI
+        name: Camel CLI
+    scoop:
+      active: RELEASE
+      downloadUrl: "https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/{{projectVersion}}/{{artifactFile}}"
+    chocolatey:
+      active: RELEASE
+      packageName: camel
+      remoteBuild: true
+      downloadUrl: "https://repo1.maven.org/maven2/org/apache/camel/camel-launcher/{{projectVersion}}/{{artifactFile}}"

dsl/camel-jbang/camel-launcher/pom.xml

@@ -55,6 +55,7 @@
         <commons-codec-version>1.22.0</commons-codec-version>
         <jcl-over-slf4j-version>${slf4j-version}</jcl-over-slf4j-version>
         <commonmark-version>0.29.0</commonmark-version>
+        <jreleaser-plugin-version>1.25.0</jreleaser-plugin-version>
     </properties>
 
     <dependencyManagement>
@@ -283,6 +284,12 @@
             <artifactId>junit-jupiter</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-compress</artifactId>
+            <version>${commons-compress-version}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -323,6 +330,51 @@
                     </execution>
                 </executions>
             </plugin>
+            <!--
+                JReleaser drives package-manager distribution (Homebrew, SDKMAN, WinGet, Scoop,
+                Chocolatey). It is intentionally NOT bound to any lifecycle phase and is
+                non-inherited: ordinary Camel builds never prepare or publish packages. The
+                camel-package.sh / camel-package.bat entry points invoke its goals explicitly.
+            -->
+            <plugin>
+                <groupId>org.jreleaser</groupId>
+                <artifactId>jreleaser-maven-plugin</artifactId>
+                <version>${jreleaser-plugin-version}</version>
+                <inherited>false</inherited>
+                <configuration>
+                    <configFile>${project.basedir}/jreleaser.yml</configFile>
+                    <gitRootSearch>true</gitRootSearch>
+                </configuration>
+            </plugin>
+            <!--
+                license-maven-plugin's default .bat header style does not recognize a header
+                that follows a leading `@echo off` line (unlike its shebang-aware .sh handling),
+                so `license:format` keeps prepending a duplicate header on every run. The file
+                already carries a correct, manually-verified header, so it is excluded here
+                rather than reordering `@echo off` out of the required first line.
+
+                formula.rb.tpl has no recognized comment-style mapping for the compound
+                ".rb.tpl" extension (license:format only inspects the final extension, ".tpl",
+                which is unmapped), so it fails outright rather than being reformatted. The
+                file is a Ruby (Homebrew Formula) template and already carries a manually
+                verified Ruby-style (#) header, so it is excluded here instead of adding a
+                repo-wide ".tpl" mapping that would assume a single comment style for every
+                future template of any language.
+            -->
+            <plugin>
+                <groupId>com.mycila</groupId>
+                <artifactId>license-maven-plugin</artifactId>
+                <configuration>
+                    <licenseSets>
+                        <licenseSet>
+                            <excludes combine.children="append">
+                                <exclude>src/jreleaser/bin/camel-package.bat</exclude>
+                                <exclude>src/jreleaser/distributions/camel-cli/brew/formula.rb.tpl</exclude>
+                            </excludes>
+                        </licenseSet>
+                    </licenseSets>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 </project>