openclacky 0.9.16 → 0.9.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e4f19a4e5cd22ab1ecc81bfb9c62db1b458a9823699ce853d6094a24b4d3496
-  data.tar.gz: b0916deb0e5cce5d68f2454ddf35e267409869c19c26e7c203adfd8215aeabe4
+  metadata.gz: 1dd996048847d73d0a71f8d4833f338e4c5ae2a58c6228122b817039f2d9fda4
+  data.tar.gz: 2003df86f0c4446d6f3d6b7d0c14eef19cc05246735acdd1f79910a0cfb0a324
 SHA512:
-  metadata.gz: fe1aeaeac77dddfbb06bfc702c4d09adbffb338b0815481902b3490ab8610448f38ec0921b8e7a6885154b722a89528f911995bb473025339890554399611094
-  data.tar.gz: ca2505ac215e2cf9430b2b5c7e9629f581108daa6798d6a379e61e8446c199def9537813218b835304c3bf412d8df452767e78fff1a39a05b7d125c93ec0a8f3
+  metadata.gz: ab9f7d2b510bdf5dc4736723dbfa602968a584f2d097d4747af4f5c74247f494e66d32a0420c7f7aa4b5e87662d5662671ab3c56e12bdb627bd7b4766504fda9
+  data.tar.gz: 4e5543ac5c01d46b5be821769c1505de6797746991fa9605788a1036ed334fa03d6a3c2d7546706dcd0bde5595d94812196acbd51df8e56008c7ba493c1058ec

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.17] - 2026-03-27
+
+### Added
+- **Browser screenshots now saved to disk**: every screenshot action automatically saves both the original full-resolution PNG and the compressed (800px) version to disk — the agent reports both file paths so you can reference, open, or pass the screenshots to other tools
+- **Provider "Get API Key" links in onboarding**: the setup wizard now shows a direct link to the provider's website when you select a provider that has a `website_url` — making it easier to sign up and get your API key without leaving the flow
+
+### Fixed
+- **WebSocket auto-reconnect for Feishu and WeCom channels**: the WebSocket clients for Feishu and WeCom now automatically retry the connection after failures — channels stay online without manual intervention after a network hiccup
+- **Brand command in simple install script**: the `clacky` brand command was incorrectly invoked in `install_simple.sh` — now fixed so the post-install branding step runs correctly
+- **Windows WSL2 and Hyper-V detection in PowerShell installer**: improved detection logic for WSL2 and Hyper-V environments in `install.ps1`, reducing false negatives on Windows machines with non-standard configurations
+
 ## [0.9.16] - 2026-03-27
 
 ### Fixed

data/lib/clacky/providers.rb

@@ -17,7 +17,8 @@ module Clacky
         "base_url" => "https://openrouter.ai/api/v1",
         "api" => "openai-responses",
         "default_model" => "anthropic/claude-sonnet-4-6",
-        "models" => []  # Dynamic - fetched from API
+        "models" => [],  # Dynamic - fetched from API
+        "website_url" => "https://openrouter.ai/keys"
       }.freeze,
 
       "minimax" => {
@@ -25,7 +26,8 @@ module Clacky
         "base_url" => "https://api.minimaxi.com/v1",
         "api" => "openai-completions",
         "default_model" => "MiniMax-M2.7",
-        "models" => ["MiniMax-M2.5", "MiniMax-M2.7"]
+        "models" => ["MiniMax-M2.5", "MiniMax-M2.7"],
+        "website_url" => "https://www.minimaxi.com/user-center/basic-information/interface-key"
       }.freeze,
 
       "kimi" => {
@@ -33,7 +35,8 @@ module Clacky
         "base_url" => "https://api.moonshot.cn/v1",
         "api" => "openai-completions",
         "default_model" => "kimi-k2.5",
-        "models" => ["kimi-k2.5"]
+        "models" => ["kimi-k2.5"],
+        "website_url" => "https://platform.moonshot.cn/console/api-keys"
       }.freeze,
 
       "anthropic" => {
@@ -41,7 +44,8 @@ module Clacky
         "base_url" => "https://api.anthropic.com",
         "api" => "anthropic-messages",
         "default_model" => "claude-sonnet-4.6",
-        "models" => ["claude-opus-4-6", "claude-sonnet-4.6", "claude-haiku-4.5"]
+        "models" => ["claude-opus-4-6", "claude-sonnet-4.6", "claude-haiku-4.5"],
+        "website_url" => "https://console.anthropic.com/settings/keys"
       }.freeze,
 
       "bedrock-jp" => {
@@ -52,7 +56,8 @@ module Clacky
         "models" => [
           "jp.anthropic.claude-sonnet-4-6",
           "jp.anthropic.claude-haiku-4-6"
-        ]
+        ],
+        "website_url" => "https://console.aws.amazon.com/iam/home#/security_credentials"
       }.freeze
 
     }.freeze

data/lib/clacky/server/channel/adapters/feishu/ws_client.rb

@@ -53,6 +53,11 @@ module Clacky
 
           private
 
+          # Timeout for IO.select on the read loop. Feishu server sends pings every
+          # @ping_interval seconds (default 90s). Allow two missed pings before
+          # treating the connection as dead.
+          READ_TIMEOUT_MULTIPLIER = 2.5
+
           def connect_and_listen
             Clacky::Logger.info("[feishu-ws] Fetching WebSocket endpoint...")
             endpoint = fetch_ws_endpoint
@@ -92,9 +97,22 @@ module Clacky
 
             start_ping_thread
 
+            # read_timeout is based on the server-provided ping interval so it
+            # automatically adapts if Feishu changes the cadence.
+            read_timeout = (@ping_interval * READ_TIMEOUT_MULTIPLIER).ceil
+
             loop do
               break unless @running
-              data = socket.readpartial(4096)
+
+              # Use IO.select with a timeout to detect silent connection drops
+              # (NAT expiry, firewall idle-kill) that never send a TCP FIN/RST.
+              ready = IO.select([socket], nil, nil, read_timeout)
+              unless ready
+                Clacky::Logger.warn("[feishu-ws] read timeout (#{read_timeout}s), reconnecting...")
+                return
+              end
+
+              data = socket.read_nonblock(4096)
               @incoming << data
               while (frame = @incoming.next)
                 case frame.type
@@ -106,13 +124,14 @@ module Clacky
                 when :ping
                   send_raw_frame(:pong, frame.data)
                 when :close
-                  Clacky::Logger.info("[feishu-ws] WebSocket closed, will reconnect")
+                  Clacky::Logger.info("[feishu-ws] WebSocket closed by server, will reconnect")
                   return
                 end
               end
             end
-          rescue EOFError, Errno::ECONNRESET
-            Clacky::Logger.warn("[feishu-ws] Connection lost, reconnecting in #{RECONNECT_DELAY}s...")
+          rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE,
+                 Errno::ETIMEDOUT, OpenSSL::SSL::SSLError => e
+            Clacky::Logger.warn("[feishu-ws] Connection lost (#{e.class}: #{e.message}), reconnecting in #{RECONNECT_DELAY}s...")
           ensure
             @ws_open = false
             @ws_socket = nil
@@ -254,7 +273,10 @@ module Clacky
                     headers: { "type" => "ping" }
                   )
                 rescue => e
-                  warn "[feishu-ws] ping failed: #{e.message}"
+                  Clacky::Logger.warn("[feishu-ws] ping failed (#{e.class}: #{e.message}), forcing reconnect")
+                  # Close the socket so IO.select in the read loop immediately
+                  # returns nil / read_nonblock raises IOError, triggering reconnect.
+                  @ws_socket&.close rescue nil
                   break
                 end
               end

data/lib/clacky/server/channel/adapters/wecom/ws_client.rb

@@ -117,6 +117,13 @@ module Clacky
 
           private
 
+          # Timeout for IO.select on the read loop. If no data arrives within this
+          # window we treat the connection as dead and reconnect. This catches the
+          # silent-drop case where the TCP stack never delivers a FIN/RST (e.g.
+          # NAT timeout, firewall idle-kill). The WeCom server sends pings every
+          # ~30 s, so 75 s gives two missed pings before we give up.
+          READ_TIMEOUT_S = 75
+
           def connect_and_listen
             uri = URI.parse(@ws_url)
             port = uri.port || 443
@@ -151,7 +158,17 @@ module Clacky
 
             loop do
               break unless @running
-              data = ssl.readpartial(4096)
+
+              # Use IO.select with a timeout so we detect silent connection drops
+              # (e.g. NAT expiry) that never deliver a TCP FIN/RST. Without this,
+              # readpartial blocks forever and the thread hangs permanently.
+              ready = IO.select([ssl], nil, nil, READ_TIMEOUT_S)
+              unless ready
+                Clacky::Logger.warn("[WecomWSClient] read timeout (#{READ_TIMEOUT_S}s), reconnecting...")
+                return
+              end
+
+              data = ssl.read_nonblock(4096)
               @incoming << data
               while (frame = @incoming.next)
                 case frame.type
@@ -160,13 +177,14 @@ module Clacky
                 when :ping
                   send_raw_frame(:pong, frame.data)
                 when :close
-                  Clacky::Logger.info("[WecomWSClient] connection closed")
+                  Clacky::Logger.info("[WecomWSClient] connection closed by server")
                   return
                 end
               end
             end
-          rescue EOFError, Errno::ECONNRESET
-            Clacky::Logger.info("[WecomWSClient] connection lost, reconnecting...")
+          rescue EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE,
+                 Errno::ETIMEDOUT, OpenSSL::SSL::SSLError => e
+            Clacky::Logger.info("[WecomWSClient] connection lost (#{e.class}: #{e.message}), reconnecting...")
           ensure
             @ws_open = false
             @ws_socket = nil
@@ -257,7 +275,15 @@ module Clacky
               loop do
                 sleep HEARTBEAT_INTERVAL
                 break unless @running
-                send_frame(cmd: "ping", req_id: generate_req_id("ping"))
+                begin
+                  send_frame(cmd: "ping", req_id: generate_req_id("ping"))
+                rescue => e
+                  Clacky::Logger.warn("[WecomWSClient] ping failed (#{e.class}: #{e.message}), forcing reconnect")
+                  # Close the socket so IO.select in the read loop immediately
+                  # returns nil / read_nonblock raises IOError, triggering reconnect.
+                  @ws_socket&.close rescue nil
+                  break
+                end
               end
             end
           end

data/lib/clacky/server/http_server.rb

@@ -1528,7 +1528,8 @@ module Clacky
             name:          preset["name"],
             base_url:      preset["base_url"],
             default_model: preset["default_model"],
-            models:        preset["models"] || []
+            models:        preset["models"] || [],
+            website_url:   preset["website_url"]
           }
         end
         json_response(res, 200, { providers: providers })

data/lib/clacky/tools/browser.rb

@@ -6,6 +6,9 @@ require "timeout"
 require "tmpdir"
 require "shellwords"
 require "yaml"
+require "base64"
+require "fileutils"
+require "securerandom"
 require_relative "base"
 
 module Clacky
@@ -159,11 +162,20 @@ module Clacky
         action = result[:action].to_s
 
         if action == "screenshot" && result[:image_data]
-          mime_type  = result[:mime_type] || "image/jpeg"
-          image_data = result[:image_data]
-          data_url   = "data:#{mime_type};base64,#{image_data}"
+          mime_type       = result[:mime_type] || "image/png"
+          image_data      = result[:image_data]
+          data_url        = "data:#{mime_type};base64,#{image_data}"
+          original_path   = result[:original_path]
+          compressed_path = result[:compressed_path]
+
+          text = "Screenshot captured."
+          if original_path || compressed_path
+            text += "\n- Original (full resolution): #{original_path || 'unavailable'}" \
+                    "\n- Compressed (800px, sent to AI): #{compressed_path || 'unavailable'}"
+          end
+
           return [
-            { type: "text",      text:      "Screenshot captured." },
+            { type: "text",      text:      text },
             { type: "image_url", image_url: { url: data_url } }
           ]
         end
@@ -416,6 +428,9 @@ module Clacky
                    output: text.empty? ? "Screenshot captured." : text }
         end
 
+        # Save original (full-resolution) PNG to disk before any downscaling
+        original_path = save_screenshot_to_disk(image_block["data"], suffix: "original")
+
         image_data = png_downscale_base64(image_block["data"], SCREENSHOT_MAX_WIDTH)
 
         if image_data.bytesize > SCREENSHOT_MAX_BASE64_BYTES
@@ -424,8 +439,13 @@ module Clacky
                    output: "Screenshot too large after resize (#{size_kb}KB). Use action=snapshot instead." }
         end
 
+        # Save compressed (800px) PNG for AI reference
+        compressed_path = save_screenshot_to_disk(image_data, suffix: "compressed")
+
         { action: "screenshot", success: true, profile: "user",
-          image_data: image_data, mime_type: "image/png", output: "Screenshot captured." }
+          image_data: image_data, mime_type: "image/png",
+          original_path: original_path, compressed_path: compressed_path,
+          output: "Screenshot captured." }
       end
 
       private def png_downscale_base64(b64, max_width)
@@ -443,6 +463,25 @@ module Clacky
         result
       end
 
+      # Save a base64-encoded PNG screenshot to disk and return the file path.
+      # suffix: "original" or "compressed" — embedded in filename for clarity.
+      # Uses the same upload directory as other image files so the agent can
+      # reference, read, or pass the path to other tools.
+      private def save_screenshot_to_disk(base64_data, suffix: nil)
+        upload_dir = File.join(Dir.tmpdir, "clacky-uploads")
+        FileUtils.mkdir_p(upload_dir)
+        ts       = Time.now.strftime("%Y%m%d_%H%M%S")
+        hex      = SecureRandom.hex(4)
+        label    = suffix ? "_#{suffix}" : ""
+        filename = "screenshot_#{ts}_#{hex}#{label}.png"
+        path     = File.join(upload_dir, filename)
+        File.binwrite(path, Base64.strict_decode64(base64_data))
+        path
+      rescue => e
+        Clacky::Logger.error("screenshot_save_failed", error: e.message)
+        nil
+      end
+
       # -----------------------------------------------------------------------
       # Chrome MCP
       # -----------------------------------------------------------------------

data/lib/clacky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clacky
-  VERSION = "0.9.16"
+  VERSION = "0.9.17"
 end

data/lib/clacky/web/i18n.js

@@ -181,6 +181,7 @@ const I18n = (() => {
       "settings.models.field.model":      "Model",
       "settings.models.field.baseurl":    "Base URL",
       "settings.models.field.apikey":     "API Key",
+      "settings.models.field.getApiKey":  "How to get →",
       "settings.models.placeholder.provider": "— Choose provider —",
       "settings.models.placeholder.model":    "e.g. claude-sonnet-4-5",
       "settings.models.placeholder.baseurl":  "https://api.anthropic.com",
@@ -254,6 +255,7 @@ const I18n = (() => {
       "onboard.key.model":          "Model",
       "onboard.key.baseurl":        "Base URL",
       "onboard.key.apikey":         "API Key",
+      "onboard.key.getApiKey":      "How to get →",
       "onboard.key.btn.test":       "Test & Continue →",
       "onboard.key.btn.back":       "← Back",
       "onboard.provider.custom":    "Custom",
@@ -454,6 +456,7 @@ const I18n = (() => {
       "settings.models.field.model":      "Model",
       "settings.models.field.baseurl":    "Base URL",
       "settings.models.field.apikey":     "API Key",
+      "settings.models.field.getApiKey":  "如何获取 →",
       "settings.models.placeholder.provider": "— 选择服务商 —",
       "settings.models.placeholder.model":    "如 claude-sonnet-4-5",
       "settings.models.placeholder.baseurl":  "https://api.anthropic.com",
@@ -527,6 +530,7 @@ const I18n = (() => {
       "onboard.key.model":          "模型",
       "onboard.key.baseurl":        "Base URL",
       "onboard.key.apikey":         "API Key",
+      "onboard.key.getApiKey":      "如何获取 →",
       "onboard.key.btn.test":       "测试并继续 →",
       "onboard.key.btn.back":       "← 返回",
       "onboard.provider.custom":    "自定义",

data/lib/clacky/web/index.html

@@ -553,7 +553,10 @@
       </div>
 
       <div class="setup-field">
-        <label class="setup-label" data-i18n="onboard.key.apikey">API Key</label>
+        <label class="setup-label">
+          <span data-i18n="onboard.key.apikey">API Key</span>
+          <a id="setup-get-apikey-link" href="#" target="_blank" rel="noopener" style="display:none;margin-left:8px;font-size:12px;color:var(--accent,#6366f1);text-decoration:none;opacity:0.85;" data-i18n="onboard.key.getApiKey">How to get →</a>
+        </label>
         <div class="setup-input-row">
           <input id="setup-api-key" type="password" class="setup-input" data-i18n-placeholder="settings.models.placeholder.apikey" placeholder="sk-…">
           <button id="setup-toggle-key" class="btn-toggle-key" title="Show/hide">

data/lib/clacky/web/onboard.js

@@ -180,16 +180,27 @@ const Onboard = (() => {
       dropdown.classList.remove("open");
       trigger.classList.remove("open");
 
+      const getApiKeyLink = $("setup-get-apikey-link");
       if (value === "__custom__") {
         // Custom: clear presets so the user can fill in their own values
         $("setup-model").value    = "";
         $("setup-base-url").value = "";
+        if (getApiKeyLink) getApiKeyLink.style.display = "none";
       } else if (value) {
         const preset = _providers.find(p => p.id === value);
         if (preset) {
           $("setup-model").value    = preset.default_model || "";
           $("setup-base-url").value = preset.base_url      || "";
+          // Show "how to get" link if provider has a website_url
+          if (getApiKeyLink && preset.website_url) {
+            getApiKeyLink.href         = preset.website_url;
+            getApiKeyLink.style.display = "";
+          } else if (getApiKeyLink) {
+            getApiKeyLink.style.display = "none";
+          }
         }
+      } else if (getApiKeyLink) {
+        getApiKeyLink.style.display = "none";
       }
     });
 

data/lib/clacky/web/settings.js

@@ -105,7 +105,10 @@ const Settings = (() => {
             placeholder="${I18n.t("settings.models.placeholder.baseurl")}" value="${_esc(model.base_url)}">
         </label>
         <label class="model-field">
-          <span class="field-label">${I18n.t("settings.models.field.apikey")}</span>
+          <span class="field-label">
+            ${I18n.t("settings.models.field.apikey")}
+            <a class="get-apikey-link" data-index="${index}" href="#" target="_blank" rel="noopener" style="display:none;margin-left:8px;font-size:12px;color:var(--accent,#6366f1);text-decoration:none;opacity:0.85;">${I18n.t("settings.models.field.getApiKey")}</a>
+          </span>
           <div class="field-input-row">
             <input type="password" class="field-input api-key-input" data-key="api_key" data-index="${index}"
               placeholder="${I18n.t("settings.models.placeholder.apikey")}" value="${_esc(model.api_key_masked)}">
@@ -179,6 +182,7 @@ const Settings = (() => {
         trigger.classList.remove("open");
         
         // Auto-fill model & base_url if a provider preset was selected
+        const getApiKeyLink = card.querySelector(`.get-apikey-link[data-index="${index}"]`);
         if (value && value !== "custom") {
           const preset = _providers.find(p => p.id === value);
           if (preset) {
@@ -186,7 +190,16 @@ const Settings = (() => {
             const baseUrlInput = card.querySelector(`[data-key="base_url"]`);
             if (modelInput)   modelInput.value   = preset.default_model || "";
             if (baseUrlInput) baseUrlInput.value = preset.base_url       || "";
+            // Show "how to get" link if provider has a website_url
+            if (getApiKeyLink && preset.website_url) {
+              getApiKeyLink.href = preset.website_url;
+              getApiKeyLink.style.display = "";
+            } else if (getApiKeyLink) {
+              getApiKeyLink.style.display = "none";
+            }
           }
+        } else if (getApiKeyLink) {
+          getApiKeyLink.style.display = "none";
         }
       });
     });

data/scripts/install.ps1

@@ -1,6 +1,6 @@
 #Requires -Version 5
 # OpenClacky Windows Installation Script
-# Usage: powershell -c "irm https://oss.1024code.com/install.ps1 | iex"
+# Usage: powershell -c "irm https://oss.1024code.com/clacky-ai/openclacky/main/scripts/install.ps1 | iex"
 #
 # If WSL is not installed, this script will install it and ask you to reboot.
 # After rebooting, run the same command again to complete installation.
@@ -9,10 +9,11 @@ Set-StrictMode -Version Latest
 $ErrorActionPreference = "Stop"
 
 $CLACKY_CDN_BASE_URL = "https://oss.1024code.com"
-$INSTALL_PS1_COMMAND = "powershell -c `"irm $CLACKY_CDN_BASE_URL/install.ps1 | iex`""
-$INSTALL_SCRIPT_URL  = "$CLACKY_CDN_BASE_URL/install.sh"
+$INSTALL_PS1_COMMAND = "powershell -c `"irm $CLACKY_CDN_BASE_URL/clacky-ai/openclacky/main/scripts/install.ps1 | iex`""
+$INSTALL_SCRIPT_URL  = "$CLACKY_CDN_BASE_URL/clacky-ai/openclacky/main/scripts/install_simple.sh"
 $UBUNTU_WSL_URL      = "$CLACKY_CDN_BASE_URL/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz"
-$WSL_UPDATE_URL      = "$CLACKY_CDN_BASE_URL/wsl_update_x64.msi"
+$WSL_UPDATE_URL      = "$CLACKY_CDN_BASE_URL/wsl_update_x64.msi"  # Windows 10
+$WSL_UPDATE_URL_WIN11 = "$CLACKY_CDN_BASE_URL/wsl.2.6.3.0.x64.msi"  # Windows 11
 $UBUNTU_WSL_DIR     = "C:\WSL\Ubuntu"
 
 # ---------------------------------------------------------------------------
@@ -34,27 +35,28 @@ function Test-IsAdmin {
 }
 
 # exit 1 = WSL feature not enabled (stub wsl.exe)
-# exit -1 = feature enabled but kernel missing
 # exit 0 = fully functional
-function Test-WslFeatureEnabled {
-    & wsl.exe --list 2>&1 | Out-Null
-    return ($LASTEXITCODE -ne 1)
-}
-
-# Returns $true if WSL2 kernel is present (exit 0)
-function Test-WslKernel {
-    & wsl.exe --list 2>&1 | Out-Null
-    return ($LASTEXITCODE -eq 0)
+#
+# Use cmd.exe to run wsl and discard stderr: native wsl.exe writes localized
+# install hints to stderr; in Windows PowerShell 5.x with $ErrorActionPreference
+# Stop, stderr merged via 2>&1 becomes NativeCommandError and can terminate the
+# script (and mojibake when console encoding mismatches).
+function Invoke-WslListExitCode {
+    cmd.exe /c "wsl.exe --list 1>nul 2>nul"
+    return $LASTEXITCODE
 }
 
 # Returns $true if an Ubuntu distro is already registered
+# wsl --list outputs UTF-16LE; temporarily switch OutputEncoding to decode correctly
 function Test-UbuntuInstalled {
+    $prev = [Console]::OutputEncoding
+    [Console]::OutputEncoding = [System.Text.Encoding]::Unicode
     try {
-        $out = & wsl --list --quiet 2>&1 | Out-String
-        return ($out -match '(?im)^ubuntu')
-    } catch {
-        return $false
+        $out = (wsl.exe --list --quiet 2>$null) -join "`n"
+    } finally {
+        [Console]::OutputEncoding = $prev
     }
+    return ($out -match '(?im)^ubuntu')
 }
 
 function Prompt-Reboot {
@@ -63,28 +65,52 @@ function Prompt-Reboot {
     Write-Warn "After restarting, run the same command again:"
     Write-Host "  $INSTALL_PS1_COMMAND" -ForegroundColor Yellow
     Write-Host ""
+    Read-Host "Press Enter to exit"
     exit 0
 }
 
-# Enable WSL via dism — works offline, no dependency on Microsoft download servers
+# Enable WSL via dism — works offline, no dependency on Microsoft download servers.
+# Also installs the WSL2 kernel MSI immediately so that after reboot wsl.exe is
+# fully functional and won't show the "WSL must be updated" interactive prompt,
+# which would cause this script to loop endlessly on re-run.
 function Enable-WslFeatures {
     Write-Step "Enabling WSL components (requires admin)..."
     dism /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart | Out-Null
     dism /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart | Out-Null
     Write-Success "WSL components enabled."
+
+    # Install kernel MSI right away — without this the stub wsl.exe keeps
+    # returning exit code 1 ("must be updated") after every reboot, causing
+    # this script to re-enable features and prompt for reboot in a loop.
+    Install-WslKernel
+
     Prompt-Reboot
 }
 
 function Install-WslKernel {
+    $build = [System.Environment]::OSVersion.Version.Build
+
+    # WSL2 requires Windows 10 build 19041 (version 2004) or later
+    if ($build -lt 19041) {
+        Write-Fail "Your Windows version is too old to run OpenClacky."
+        Write-Fail "Please upgrade to Windows 10 (2020 or later) or Windows 11."
+        exit 1
+    }
+
+    # Windows 11 (build >= 22000) requires the new full WSL2 package MSI;
+    # the legacy wsl_update_x64.msi (v5.x) fails with error 1603 on Windows 11.
+    $isWin11 = ($build -ge 22000)
+    $url = if ($isWin11) { $WSL_UPDATE_URL_WIN11 } else { $WSL_UPDATE_URL }
+
     $msiPath = "$env:TEMP\wsl_update.msi"
     Write-Step "Downloading WSL2 kernel update..."
     $curlOk = $false
-    try { curl -L --progress-bar $WSL_UPDATE_URL -o $msiPath; $curlOk = ($LASTEXITCODE -eq 0) } catch {}
+    try { curl -L --progress-bar $url -o $msiPath; $curlOk = ($LASTEXITCODE -eq 0) } catch {}
     if (-not $curlOk) {
-        Invoke-WebRequest -Uri $WSL_UPDATE_URL -OutFile $msiPath -UseBasicParsing
+        Invoke-WebRequest -Uri $url -OutFile $msiPath -UseBasicParsing
     }
     Write-Info "Download complete. Installing WSL2 kernel..."
-    Start-Process msiexec -Verb RunAs -Wait -ArgumentList "/i","$msiPath","/quiet","/norestart"
+    Start-Process msiexec -Wait -ArgumentList "/i","$msiPath","/quiet","/norestart"
     Write-Success "WSL2 kernel installed."
 }
 
@@ -112,28 +138,39 @@ function Install-Ubuntu {
 }
 
 function Install-Wsl {
-    if (-not (Test-IsAdmin)) {
-        Write-Fail "Please re-run this script as Administrator:"
-        Write-Host ""
-        Write-Host "  Right-click PowerShell -> 'Run as administrator', then:" -ForegroundColor Yellow
-        Write-Host "  $INSTALL_PS1_COMMAND" -ForegroundColor Yellow
-        exit 1
-    }
+    Write-Step "Checking WSL status..."
+    $wslCode = Invoke-WslListExitCode
+    Write-Info "WSL check result: exit code $wslCode"
 
-    if (-not (Test-WslFeatureEnabled)) {
+    if ($wslCode -eq 1) {
         Enable-WslFeatures
         # Enable-WslFeatures exits after prompting reboot
     }
 
-    if (-not (Test-WslKernel)) {
-        Install-WslKernel
-    }
-
     if (-not (Test-UbuntuInstalled)) {
         Install-Ubuntu
     }
 }
 
+# ---------------------------------------------------------------------------
+# Ensure Hyper-V hypervisor is active (required for WSL2)
+# ---------------------------------------------------------------------------
+function Ensure-HyperV {
+    $hypervisorPresent = (Get-CimInstance -ClassName Win32_ComputerSystem).HypervisorPresent
+    if ($hypervisorPresent) { return }
+
+    Write-Step "Enabling Hyper-V hypervisor..."
+    bcdedit /set hypervisorlaunchtype auto | Out-Null
+    Write-Success "Hyper-V enabled."
+    Write-Host ""
+    Write-Warn "A restart is required to apply the changes."
+    Write-Warn "After restarting, run the same command again:"
+    Write-Host "  $INSTALL_PS1_COMMAND" -ForegroundColor Yellow
+    Write-Host ""
+    Read-Host "Press Enter to restart now"
+    Restart-Computer -Force
+}
+
 # ---------------------------------------------------------------------------
 # Install OpenClacky inside WSL
 # ---------------------------------------------------------------------------
@@ -173,6 +210,16 @@ Write-Host ""
 Write-Host "OpenClacky Installation Script (Windows)" -ForegroundColor Cyan
 Write-Host ""
 
+# All subsequent operations (bcdedit, dism, wsl) require admin privileges
+if (-not (Test-IsAdmin)) {
+    Write-Fail "Please re-run this script as Administrator:"
+    Write-Host ""
+    Write-Host "  Right-click PowerShell -> 'Run as administrator', then:" -ForegroundColor Yellow
+    Write-Host "  $INSTALL_PS1_COMMAND" -ForegroundColor Yellow
+    exit 1
+}
+
+Ensure-HyperV
 Install-Wsl
 
 Write-Success "WSL is ready."

data/scripts/install_simple.sh

@@ -434,18 +434,19 @@ setup_gem_home() {
 
     export GEM_HOME="$HOME/.gem/ruby/${ruby_api}"
     export GEM_PATH="$HOME/.gem/ruby/${ruby_api}"
-    export PATH="$HOME/.gem/ruby/${ruby_api}/bin:$PATH"
+    export PATH="$HOME/.local/bin:$HOME/.gem/ruby/${ruby_api}/bin:$PATH"
 
     print_info "System Ruby detected — gems will install to ~/.gem/ruby/${ruby_api}"
 
     # Persist to shell rc (use $HOME so the line is portable)
+    # Also add ~/.local/bin so brand wrapper commands installed there are found
     if [ -n "$SHELL_RC" ] && ! grep -q "GEM_HOME" "$SHELL_RC" 2>/dev/null; then
         {
             echo ""
             echo "# Ruby user gem dir (added by openclacky installer)"
             echo "export GEM_HOME=\"\$HOME/.gem/ruby/${ruby_api}\""
             echo "export GEM_PATH=\"\$HOME/.gem/ruby/${ruby_api}\""
-            echo "export PATH=\"\$HOME/.gem/ruby/${ruby_api}/bin:\$PATH\""
+            echo "export PATH=\"\$HOME/.local/bin:\$HOME/.gem/ruby/${ruby_api}/bin:\$PATH\""
         } >> "$SHELL_RC"
         print_info "GEM_HOME written to $SHELL_RC"
     fi

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openclacky
 version: !ruby/object:Gem::Version
-  version: 0.9.16
+  version: 0.9.17
 platform: ruby
 authors:
 - windy