diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..64a6ede6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +# Windows shell entry points must reach the user with CRLF line endings. +# +# install.cmd is documented as a `curl -O` download from raw.githubusercontent.com, +# which serves the stored blob byte for byte — no checkout-time eol conversion ever +# runs. `-text` keeps git from normalising the CRLF out of the blob, so the file a +# user downloads is the file cmd.exe was designed to read. (LF-only batch files are +# a known source of failures around labels and multi-line blocks.) +*.cmd -text +*.bat -text diff --git a/README.md b/README.md index 13cb4f77..3f9f2711 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,11 @@ curl -fsSL https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/ irm https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/install.ps1 | iex ``` +**Windows (cmd.exe, when `.ps1` files are blocked):** download `install.cmd` and `install.ps1` side by side. It takes the same flags as `install.ps1` and only launches it with `-ExecutionPolicy Bypass`, for that one process. +```bat +install.cmd +``` + ### Connect and Query ```bash diff --git a/build.sbt b/build.sbt index a6c9fc0e..ac14c27d 100644 --- a/build.sbt +++ b/build.sbt @@ -20,7 +20,7 @@ ThisBuild / organization := "app.softnetwork" name := "softclient4es" -ThisBuild / version := "0.20.4-SNAPSHOT" +ThisBuild / version := "0.20.4" ThisBuild / scalaVersion := scala213 diff --git a/documentation/client/repl.md b/documentation/client/repl.md index b1ad04c5..0ee93738 100644 --- a/documentation/client/repl.md +++ b/documentation/client/repl.md @@ -88,6 +88,44 @@ Invoke-WebRequest -Uri https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftCli .\install.ps1 ``` +#### Windows (cmd.exe — when `.ps1` scripts are blocked) + +The piped one-liner above is unaffected by the execution policy (`iex` runs a +string, not a script file), but `.\install.ps1` on a **downloaded** file is: the +Windows client default is `Restricted`, and the machine may also be set to +`AllSigned`. `install.cmd` is the way in — it is a wrapper that runs +`install.ps1` with `-ExecutionPolicy Bypass` **for that one process**, changing +nothing on the machine and needing no elevation. + +Download **both** files, keep them in the same directory, then: + +```bat +curl -O https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/install.cmd +curl -O https://raw.githubusercontent.com/SOFTNETWORK-APP/SoftClient4ES/main/install.ps1 +install.cmd +``` + +`install.cmd` accepts exactly the flags `install.ps1` does and forwards them +verbatim, so every option, default and fallback documented below applies +unchanged — there is no second implementation to drift: + +```bat +install.cmd -ListVersions -EsVersion 8 +install.cmd -Target "C:\tools\softclient4es" -EsVersion 8 -Version 0.20.4 +install.cmd -EsVersion 9 -NoExtensions +install.cmd -Help +``` + +> **When even the wrapper cannot help:** `-ExecutionPolicy Bypass` is +> deliberately overridden when the policy is enforced through **Group Policy** +> (the `MachinePolicy` / `UserPolicy` scopes). Check with +> `Get-ExecutionPolicy -List`: if the winning entry is one of those two scopes, +> no wrapper can work around it — ask your administrator, or unpack an install +> by hand from the assembly jar (see [Directory Structure](#directory-structure)). +> Note that this affects **installing** only: the launcher the installer writes, +> `bin\softclient4es.bat`, is a plain batch file, so *running* the REPL never +> needs PowerShell. + ### List Available Versions Before installing, you can list all available versions for a specific Elasticsearch version: @@ -104,6 +142,12 @@ Before installing, you can list all available versions for a specific Elasticsea .\install.ps1 -ListVersions -EsVersion 8 ``` +Or, when `.ps1` scripts are blocked, the same flags through the wrapper: + +```bat +install.cmd -ListVersions -EsVersion 8 +``` + **Example output:** ``` @@ -325,6 +369,13 @@ $env:PATH += ";$env:USERPROFILE\softclient4es\bin" ~\softclient4es\uninstall.ps1 ``` +The installer writes the uninstaller as a `.ps1`, so a host that blocks `.ps1` +blocks it too. Run it the same way `install.cmd` runs the installer: + +```bat +powershell -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\softclient4es\uninstall.ps1" +``` + --- ## Connection diff --git a/install.cmd b/install.cmd new file mode 100644 index 00000000..2fc4aec1 --- /dev/null +++ b/install.cmd @@ -0,0 +1,41 @@ +@echo off +rem =========================================================================== +rem SoftClient4ES Installation Script - cmd.exe entry point +rem =========================================================================== +rem +rem Why this file exists: on a host whose PowerShell execution policy is +rem Restricted or AllSigned (the Windows client default is Restricted), +rem double-clicking or calling install.ps1 fails before it runs a single line. +rem This wrapper is the supported way in: -ExecutionPolicy Bypass applies to +rem THIS process only, changes nothing on the machine, and needs no elevation. +rem +rem It is a wrapper and nothing else - every option, default, fallback and +rem message lives in install.ps1, so the two entry points can never drift. +rem Pass the same flags you would pass to install.ps1: +rem +rem install.cmd +rem install.cmd -ListVersions -EsVersion 8 +rem install.cmd -Target "C:\tools\softclient4es" -EsVersion 8 -Version 1.0.0 +rem install.cmd -EsVersion 7 -Version 0.20.4 -NoExtensions +rem install.cmd -Help +rem +rem Caveat worth knowing: -ExecutionPolicy Bypass is overridden when the policy +rem is enforced through Group Policy (the MachinePolicy / UserPolicy scopes). +rem That is deliberate on Microsoft's side and no wrapper can work around it - +rem on such a host, ask your administrator, or run the REPL from the jar by +rem hand (see documentation/client/repl.md). +rem =========================================================================== + +setlocal + +set "PS1=%~dp0install.ps1" + +if not exist "%PS1%" ( + echo [ERROR] install.ps1 was not found next to install.cmd. 1>&2 + echo [ERROR] Expected: %PS1% 1>&2 + echo [ERROR] Download both files from the same release and keep them together. 1>&2 + exit /b 1 +) + +powershell -NoProfile -ExecutionPolicy Bypass -File "%PS1%" %* +exit /b %ERRORLEVEL%