start/setup/update.sh: refuse to run on a Windows-hosted shell

A Windows user running the bash helper scripts (WSL, or Git Bash /
MSYS2 / MinGW / Cygwin) used to fail deep in the venv/PC-SC logic - under
WSL the Linux guest cannot reach the Windows PC/SC readers, and a
mingw/msys shell has the wrong (bin/) venv layout.  Each helper now
detects Windows (WSL via /proc/version, mingw/msys/cygwin via uname -s)
up front and exits 2 with a pointer at the matching .bat script.  Users
who deliberately want the WSL/Cygwin flow can run the underlying commands
directly, without the helpers.

Bumps VERSION to 3.40.4 and the SW cache to simple-v490.

CHANGELOG.md

@@ -9,6 +9,19 @@ every change carries a descriptive commit message.
 
 ## [Unreleased]
 
+## [3.40.4] — 2026-11-04
+
+### Added
+
+- **Windows guard in the helper scripts.**  `setup.sh`, `start.sh` and
+  `update.sh` now detect a Windows-hosted bash (WSL via `/proc/version`, and
+  Git Bash / MSYS2 / MinGW / Cygwin via `uname -s`) and exit with a clear
+  error pointing at the matching `.bat` script, instead of failing deep in the
+  venv/PC-SC logic.  Under WSL the Linux guest cannot reach the Windows PC/SC
+  readers, and a mingw/msys shell uses the wrong (`bin/`) venv layout; users
+  who deliberately want the WSL/Cygwin flow can run the underlying commands
+  directly, without the helper scripts.
+
 ## [3.40.3] — 2026-10-27
 
 ### Fixed

frontend/index.html

@@ -1990,7 +1990,7 @@
 // ===== Version =====
 // Single source of truth for the PWA version: shown in the header and used
 // by the server version check in pysimConnect().
-const SIMPLE_VERSION = '3.40.3';
+const SIMPLE_VERSION = '3.40.4';
 document.getElementById('app-version').textContent = 'v' + SIMPLE_VERSION;
 
 // ===== view history (the browser Back/Forward buttons) =====

frontend/sw.js

@@ -1,4 +1,4 @@
-const CACHE = 'simple-v489';
+const CACHE = 'simple-v490';
 const URLS = [
   'index.html',
   'help.html',

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pysim-simple-server"
-version = "3.40.3"
+version = "3.40.4"
 description = "HTTP REST server wrapping pysim for the SIMple PWA"
 license = { text = "GPL-2.0-or-later" }
 requires-python = ">=3.9"

pysim_simple_server/server.py

@@ -37,7 +37,7 @@ from osmocom.tlv import BER_TLV_IE
 from osmocom.utils import rpad
 
 
-VERSION = '3.40.3'
+VERSION = '3.40.4'
 
 MAX_ENVELOPE_SEGMENTS = 5  # max SMS segments for outgoing C-APDU in ENVELOPE
 

setup.sh

@@ -4,6 +4,19 @@ set -e
 # pysim-simple-server setup script
 # Creates a venv and installs pysim and its dependencies.
 
+# Windows guard: setup.sh is the native Linux/macOS helper.  Under WSL the
+# Linux guest cannot reach the Windows PC/SC readers, and a Git Bash / MSYS2 /
+# MinGW / Cygwin shell has the wrong (bin/) venv layout - use setup.bat, which
+# drives the Windows Python and the built-in PC/SC stack.  A deliberate
+# WSL/Cygwin flow can run the underlying pip/venv commands without this script.
+if grep -qi microsoft /proc/version 2>/dev/null || \
+   uname -s 2>/dev/null | grep -qiE 'MINGW|MSYS|CYGWIN'; then
+    echo "Error: setup.sh is the Linux/macOS helper and cannot run on Windows"
+    echo "(WSL / MSYS2 / MinGW / Cygwin detected)."
+    echo "Use setup.bat from a Windows command prompt (cmd.exe / PowerShell) instead."
+    exit 2
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 VENV_DIR="$SCRIPT_DIR/.venv"
 

start.sh

@@ -7,6 +7,19 @@ set -e
 # Every run is mirrored to simple_lastrun.log (overwritten on each start) so the
 # latest server output can be read without copy-pasting the console.
 
+# Windows guard: start.sh is the native Linux/macOS helper.  Under WSL the
+# Linux guest cannot reach the Windows PC/SC readers, and a Git Bash / MSYS2 /
+# MinGW / Cygwin shell has the wrong (bin/) venv layout - use start.bat, which
+# drives the Windows Python and the built-in PC/SC stack.  A deliberate
+# WSL/Cygwin flow can run the server without this script.
+if grep -qi microsoft /proc/version 2>/dev/null || \
+   uname -s 2>/dev/null | grep -qiE 'MINGW|MSYS|CYGWIN'; then
+    echo "Error: start.sh is the Linux/macOS helper and cannot run on Windows"
+    echo "(WSL / MSYS2 / MinGW / Cygwin detected)."
+    echo "Use start.bat from a Windows command prompt (cmd.exe / PowerShell) instead."
+    exit 2
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 VENV_DIR="$SCRIPT_DIR/.venv"
 

tests/test_pcsc_startup.py

@@ -165,6 +165,18 @@ class SourcePins(unittest.TestCase):
         self.assertIn('%HTTP_HOST%:%HTTP_PORT%', src)
         self.assertNotIn('http://127.0.0.1:8080', src)
 
+    def test_the_start_script_guards_windows_and_points_to_start_bat(self):
+        src = (Path(m.__file__).parent.parent / 'start.sh').read_text()
+        self.assertIn('microsoft /proc/version', src)
+        self.assertIn('MINGW|MSYS|CYGWIN', src)
+        self.assertIn('Use start.bat from a Windows command prompt', src)
+
+    def test_the_update_script_guards_windows_and_points_to_update_bat(self):
+        src = (Path(m.__file__).parent.parent / 'update.sh').read_text()
+        self.assertIn('microsoft /proc/version', src)
+        self.assertIn('MINGW|MSYS|CYGWIN', src)
+        self.assertIn('Use update.bat from a Windows command prompt', src)
+
 
 if __name__ == '__main__':
     unittest.main()

tests/test_setup_scripts.py

@@ -39,6 +39,11 @@ class SetupShTests(unittest.TestCase):
                              capture_output=True, text=True)
         self.assertEqual(res.returncode, 0, res.stderr)
 
+    def test_windows_guard_points_to_setup_bat(self):
+        self.assertIn('microsoft /proc/version', self.src)
+        self.assertIn('MINGW|MSYS|CYGWIN', self.src)
+        self.assertIn('Use setup.bat from a Windows command prompt', self.src)
+
 
 class SetupBatTests(unittest.TestCase):
     def setUp(self):

update.sh

@@ -2,6 +2,19 @@
 # Update this packaged SIMple install in place (see tools/update.py --help).
 # The .venv is reused - pysim and its prerequisites are not re-installed.
 set -e
+
+# Windows guard: update.sh is the native Linux/macOS helper.  Under WSL the
+# Linux guest cannot reach the Windows PC/SC readers, and a Git Bash / MSYS2 /
+# MinGW / Cygwin shell has the wrong (bin/) venv layout - use update.bat.  A
+# deliberate WSL/Cygwin flow can run tools/update.py without this script.
+if grep -qi microsoft /proc/version 2>/dev/null || \
+   uname -s 2>/dev/null | grep -qiE 'MINGW|MSYS|CYGWIN'; then
+    echo "Error: update.sh is the Linux/macOS helper and cannot run on Windows"
+    echo "(WSL / MSYS2 / MinGW / Cygwin detected)."
+    echo "Use update.bat from a Windows command prompt (cmd.exe / PowerShell) instead."
+    exit 2
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 if [ -x "$SCRIPT_DIR/.venv/bin/python" ]; then
     PY="$SCRIPT_DIR/.venv/bin/python"