From 887e209abc9c3007596838f446a32595be981010 Mon Sep 17 00:00:00 2001
From: KeiSei84 <2206745@gmail.com>
Date: Wed, 27 May 2026 14:34:48 +0800
Subject: [PATCH] =?UTF-8?q?feat(installer):=20friendly=20Windows=20+=20WSL?=
 =?UTF-8?q?2=20detection=20=E2=80=94=20no=20more=20silent=20death?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two related changes to make Windows users hit a useful message instead of
"unsupported OS: MINGW64_NT-10.0...; exit 1":

1. bootstrap.sh — WSL2 detection + Git Bash guidance:
   - If uname=Linux + /proc/version contains "Microsoft" or "WSL" → mark
     as WSL2, log it, continue as Linux. Full substrate works.
   - If uname matches MINGW*/MSYS*/CYGWIN* (Git Bash on bare Windows) →
     print step-by-step WSL2 setup guide:
       * PowerShell admin: wsl --install -d Ubuntu
       * Reboot, launch Ubuntu, re-run bootstrap.sh inside it
     + MCP-only fallback mention (kei-mcp-server-windows-x64.exe in releases).
     + Best-effort: copy "wsl --install -d Ubuntu" to Windows clipboard
       via clip.exe (Git Bash has it), so user can paste into PowerShell.
   - Anything else → friendly "supported: Darwin / Linux / WSL2" message.

2. install.sh — same 3-way OS guard added at top, before any lib-*.sh
   sourcing. Catches users who skip bootstrap.sh and run ./install.sh
   directly on Git Bash; gives them the same WSL guidance.

Smoke-tested all 5 OS branches (Darwin / Linux / WSL2 / MINGW64 / Haiku):
each takes the right path. Zero behavioural change on macOS / Linux.

This complements the v0.47 README Platforms section — UX side of the
honest answer "Windows works via WSL2; native PowerShell port not on
roadmap".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 bootstrap.sh | 50 +++++++++++++++++++++++++++++++++++++++++++++++---
 install.sh   | 22 ++++++++++++++++++++++
 2 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/bootstrap.sh b/bootstrap.sh
index 18d0876..9c4b38a 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -118,11 +118,55 @@ have() { command -v "$1" >/dev/null 2>&1; }
 OS="$(uname -s)"
 
 # --- 1. OS detection -----------------------------------------------------
+# Detect WSL2 (uname -s = Linux but kernel reports Microsoft) — full path works.
+# Detect Git Bash / Cygwin / MSYS on bare Windows — substrate cannot run there;
+# guide user to WSL2 instead of dying silently.
+IS_WSL=0
+if [ "$OS" = "Linux" ] && [ -r /proc/version ] && grep -qiE "microsoft|wsl" /proc/version 2>/dev/null; then
+    IS_WSL=1
+fi
+
 case "$OS" in
-    Darwin|Linux) ;;
-    *) err "unsupported OS: $OS (only Darwin / Linux for now)"; exit 1 ;;
+    Darwin|Linux)
+        if [ "$IS_WSL" = "1" ]; then
+            log "OS: WSL2 (Linux inside Windows) — full substrate path available"
+        else
+            log "OS: $OS"
+        fi
+        ;;
+    MINGW*|MSYS*|CYGWIN*)
+        err ""
+        err "Detected: bare Windows ($OS) via Git Bash / Cygwin / MSYS."
+        err ""
+        err "KeiSeiKit's substrate is Bash-only and needs apt/brew + full POSIX —"
+        err "it will not run reliably outside WSL2. Native PowerShell port is NOT"
+        err "on the roadmap (would double maintenance; WSL gives 100% coverage)."
+        err ""
+        err "Path forward (one-time setup, ~5 min + reboot):"
+        err ""
+        err "  1. Open PowerShell as Administrator."
+        err "  2. Run:        wsl --install -d Ubuntu"
+        err "  3. Reboot when prompted; Ubuntu auto-starts on next login."
+        err "  4. Inside Ubuntu, re-run this same bootstrap:"
+        err "       curl -fsSL https://raw.githubusercontent.com/KeiSeiLab/KeiSeiKit-1.0/main/bootstrap.sh | bash"
+        err ""
+        err "Alternative — MCP-only (no substrate, no skills, no hooks):"
+        err "  Grab kei-mcp-server-windows-x64.exe from a release and wire it"
+        err "  into Claude Desktop / VS Code MCP config. Gets you spawn_agent +"
+        err "  kei_bash/kei_edit/kei_write only. See README → Platforms section."
+        err ""
+        # Best-effort: copy the wsl --install command to clipboard if possible.
+        if command -v clip.exe >/dev/null 2>&1; then
+            printf 'wsl --install -d Ubuntu' | clip.exe 2>/dev/null && \
+                err "(I've copied 'wsl --install -d Ubuntu' to your Windows clipboard.)"
+        fi
+        exit 1
+        ;;
+    *)
+        err "unsupported OS: $OS (supported: Darwin / Linux / WSL2)"
+        exit 1
+        ;;
 esac
-log "OS: $OS"
 
 # --- 2. install jq -------------------------------------------------------
 install_jq() {
diff --git a/install.sh b/install.sh
index 3c9ded1..20df7c8 100755
--- a/install.sh
+++ b/install.sh
@@ -20,6 +20,28 @@
 
 set -euo pipefail
 
+# --- OS guard (v0.47): friendly message on bare Windows ------------------
+_uname_s="$(uname -s 2>/dev/null || echo unknown)"
+case "$_uname_s" in
+    Darwin|Linux) ;;  # ok
+    MINGW*|MSYS*|CYGWIN*)
+        echo "[install.sh] ERROR: bare Windows ($_uname_s) detected." >&2
+        echo "" >&2
+        echo "KeiSeiKit's substrate is Bash-only. Use WSL2 instead:" >&2
+        echo "  1. PowerShell (admin):  wsl --install -d Ubuntu" >&2
+        echo "  2. Reboot when prompted; launch Ubuntu." >&2
+        echo "  3. Inside Ubuntu, re-run this installer." >&2
+        echo "" >&2
+        echo "See README → 'Platforms' for the full path + MCP-only fallback." >&2
+        exit 1
+        ;;
+    *)
+        echo "[install.sh] ERROR: unsupported OS: $_uname_s (supported: Darwin / Linux / WSL2)" >&2
+        exit 1
+        ;;
+esac
+unset _uname_s
+
 # --- paths ----------------------------------------------------------------
 KIT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HOME_DIR="${HOME:?HOME not set}"