CURSOR.md

Feature

nvm-windows Node.js 偵測支援

Goal

讓 Windows 上使用 nvm-windows 的使用者，在 Qclaw 環境檢查與 Gateway 啟動時能正確偵測到其管理的 Node.js，而非回退至內建安裝。

Scope (MVP)

• checkNode() 在 Windows 上能透過 NVM_HOME 或 %APPDATA%\nvm 偵測 nvm-windows 安裝的 Node
• resolveNodeInstallStrategy() 在 Windows 上能正確回傳 'nvm'（含路徑大小寫不一致的情況）
• resolveQualifiedNodeRuntime() 在 Windows 上能列舉 nvm-windows 版本（已完成）

Out of Scope (for now)

• 透過 Qclaw UI 自動安裝 Node 至 nvm-windows（nvm install）
• nvm-windows 版本切換 UI
• 支援其他 Windows Node 版本管理器（如 fnm、Volta）

UX

使用者操作路徑（top-down）：

EnvCheck.tsx（掛載後延遲觸發 runChecks）
  → window.api.checkNode()
  → preload: ipcRenderer.invoke('env:checkNode')
  → ipc-handlers.ts: ipcMain.handle('env:checkNode', () => checkNode())
  → cli.ts: checkNode()
       ├─ 第 1332 行：const nvmDir = !isWin ? await detectNvmDir() : null
       │   ⚠ Windows 上 nvmDir 恆為 null → nvmNode 恆為 null
       │   ⚠ detectNvmDir() 是 cli.ts 內的 private 函式，非 nvm-node-runtime.ts 的
       ├─ resolveNodeFromShell()  → where node / which node
       ├─ selectPreferredNodeRuntime({ shellNode, nvmNode: null, nvmDir: null })
       └─ listNodeExecutableCandidates → 逐個嘗試

Gateway 啟動路徑：
  ensureRuntimeReady() → checkNode()  → 同上

子程序路徑（已修改，不經過 checkNode）：
  runNodeEvalWithQualifiedRuntime() → resolveQualifiedNodeRuntime()
       ├─ win32: detectNvmWindowsDir + listInstalledNvmWindowsNodeExePaths ✅
       └─ 非 win32: detectNvmDir (from nvm-node-runtime.ts) ✅

成功回饋：環境檢查頁 Node 版本顯示綠勾，installStrategy 為 'nvm' 失敗回饋：偵測不到 Node → 提示安裝

Technical Notes

問題 1：checkNode() 未接入 nvm-windows

• cli.ts 第 1332 行 !isWin 硬跳過 → 需改為 Windows 上呼叫 nvm-windows 偵測
• cli.ts 內有私有 detectNvmDir()（第 1385 行），只處理 POSIX nvm
• 需在 checkNode() 加入：Windows 上呼叫 detectNvmWindowsDir()，並用結果掃描版本

問題 2：路徑比較大小寫敏感

• resolveNodeInstallStrategy() 在 node-runtime-selection.ts
• 目前用 .startsWith() 比較正規化後的路徑
• Windows 路徑大小寫不敏感：C:\Users\ == c:\users\
• 需加 .toLowerCase() 再比較

檔案觸碰點

檔案	改動
electron/main/cli.ts	checkNode() 加入 nvm-windows 偵測
electron/main/node-runtime-selection.ts	路徑比較加 toLowerCase()
electron/main/__tests__/nvm-node-runtime.test.ts	補大小寫邊界測試
electron/main/__tests__/node-runtime-selection.test.ts	補大小寫邊界測試

Test Checklist

正常情況

• [x] nvm-windows 安裝的 Node 能被 resolveQualifiedNodeRuntime 偵測（已有）
• [ ] nvm-windows 安裝的 Node 能被 checkNode() 偵測
• [x] POSIX nvm 偵測不受影響（已有）

邊界情況

• [ ] Windows 路徑大小寫不一致時 resolveNodeInstallStrategy 仍回傳 'nvm' 例：binDir='C:\Users\Jason\AppData\Roaming\NVM\v22' vs nvmDir='c:\users\jason\appdata\roaming\nvm'
• [ ] NVM_HOME 環境變數不存在但 %APPDATA%\nvm 存在（已有，需驗證 checkNode 路徑）
• [ ] NVM_HOME 和 APPDATA 都不存在 → 回退 installer（已有）

錯誤情況

• [x] nvm-windows 目錄無法讀取 → 回傳空陣列（已有）
• [x] POSIX nvm 目錄不存在 → 回傳 null（已有）