# ข้อเสนอแผนพัฒนา JUJU ให้รองรับ Windows (v0.8)

เอกสารสำหรับนำเสนอ/ตัดสินใจ · จัดทำ 10 กันยายน 2026 · อ้างอิงจากการ audit โค้ดจริง 2 รอบ
(รอบแรก 9 ก.ย. ตรวจ 99 ประเด็น ยืนยันโดย reviewer อิสระ 2 ชั้น เหลือ 86 ประเด็นจริง;
รอบสอง 10 ก.ย. ตรวจเฉพาะโมดูลใหม่ของรุ่น 0.4–0.7)
รายละเอียดเชิงเทคนิคเต็ม: [WINDOWS_PLAN.md](WINDOWS_PLAN.md)

---

## 1. บทสรุปผู้บริหาร

- **สถานะวันนี้**: JUJU 0.7.2 รองรับ macOS (ผ่านเทสต์เต็ม 414 ข้อ) และ Linux (ผ่าน CI)
  ส่วน **Windows แบบ native ยังใช้ไม่ได้เลย** — `juju start` และ `juju stdio` ตายทันที
  ตั้งแต่วินาทีแรกที่ผูก IPC socket
- **ผู้ใช้ Windows มีทางใช้งานชั่วคราวแล้ว 2 ทาง**: (1) เป็น client ต่อเข้า server
  บน Mac/Linux ผ่าน tunnel — ใช้ได้เต็มรูปแบบวันนี้ (2) รัน server ใน WSL2 —
  ใช้ได้เพราะนับเป็น Linux
- **ข้อเสนอ**: พัฒนา Windows native v1 ในสโคป "รองรับแบบไม่มี OS sandbox และ
  hard-kill เท่านั้น" ใช้แรงงานประมาณ **51 วันงานวิศวกร (ช่วง 40–65)**
  แบ่งเป็น 4 เฟส มี CI `windows-latest` เป็นเครื่องตรวจหลัก
  และการทดสอบมือบนเครื่อง Windows 11 จริง 1 รอบเป็นด่านสุดท้ายก่อนประกาศรองรับ
- **ความเสี่ยงหลัก**ไม่ใช่เทคนิคที่แก้ไม่ได้ แต่คือ (ก) ช่องโหว่ความปลอดภัยเฉพาะ NTFS
  2 จุดที่ต้องปิดแบบ fail-closed ก่อนประกาศ (ข) ความไม่เสถียรของเทสต์บน Windows CI
  (ค) การไม่มีเครื่อง Windows จริงทำให้รอบ debug ช้า

---

## 2. สถานะปัจจุบัน (หลักฐานจริง ไม่ใช่การคาดเดา)

| แพลตฟอร์ม | สถานะ | หลักฐาน |
|---|---|---|
| macOS arm64 | ✅ รองรับเต็ม | release gate 414/414 เทสต์ + ผู้ใช้จริงผ่าน ChatGPT ครบ 74 ความสามารถ |
| Linux x64 | ✅ รองรับ (CI gate) | ชุดเทสต์เดียวกันบน ubuntu ใน CI |
| Windows (WSL2) | ✅ ใช้ได้ (นับเป็น Linux) | ข้อจำกัด: ไม่มี desktop tools / speech |
| Windows native | ❌ ไม่รองรับ | audit 9 ก.ย.: ตายที่ IPC bind + hard stop อีก 4 จุด |

### ถ้าผู้ใช้ลอง `npm install -g juju-mcp` บน Windows วันนี้ จะเจออะไร

1. ติดตั้งได้ (better-sqlite3 มี prebuilt win32-x64) และคำสั่ง offline ใช้ได้:
   `juju --version / init / doctor / trust / auth add-client`
2. **`juju start` และ `juju stdio` ล้มทันที**: โค้ดส่ง path ไฟล์ `.sock` ให้
   `net.Server.listen` ซึ่งบน Windows ต้องเป็น named pipe (`\\.\pipe\...`) —
   comment ในโค้ดที่ว่า "named pipes handled elsewhere" ไม่มีอยู่จริง
3. ต่อให้ผ่านข้อ 2 ไปได้ ยังติด hard stop อิสระอีก 4 จุด:
   - shell ของ `run_command` hard-code `/bin/bash` → ทุกคำสั่งล้ม
   - การหาโปรแกรม (`exec_command`/`run_task`) เช็ค execute bit แบบ POSIX
     และไม่ลองนามสกุล `.exe/.cmd` → หาอะไรไม่เจอเลย
   - LSP resolver มีปัญหาเดียวกัน → `juju lsp add` ใช้ไม่ได้
   - การยกเลิกงานใช้ `process.kill(-pid)` ซึ่ง throw บน Windows → job รั่ว
4. **ช่องโหว่ความปลอดภัยเฉพาะ Windows 2 จุด** (ต้องปิดก่อนประกาศรองรับ):
   - NTFS Alternate Data Stream และชื่อสั้น 8.3 (`.env::$DATA`, `GIT~1/config`)
     **ทะลุ secret guard ได้** — ไฟล์ลับที่ระบบสัญญาว่าปกป้องจะถูกอ่าน/เขียนได้
   - Windows ค้นหาโปรแกรมจาก cwd ก่อน PATH → repo ที่แอบวาง `git.exe` ไว้
     จะถูกรันด้วยสิทธิ์ trusted (repo-supplies-executable ซึ่งขัด security model)

---

## 3. เป้าหมายและขอบเขตของ v1

### สิ่งที่ v1 จะรองรับ
- Windows 10/11 x64, Node 22/24, ทั้ง `juju start` (HTTP+OAuth) และ `juju stdio`
- เครื่องมือ coding ครบ: อ่าน/ค้น/แก้ไฟล์, preview→apply→rollback, git,
  run_command/parallel/background jobs, TS/JS semantics, LSP (เฉพาะ server
  ที่เป็น `.exe`), assistance, schedules
- multimodal: media/ffmpeg/Whisper/Playwright browser/game/workflow
  (ทุกตัวมีเวอร์ชัน Windows) — speech เป็น NOT_SUPPORTED (คำสั่ง `say` มีแค่ macOS)
- compact/hybrid/full tool surface — ไม่ผูกกับ OS ใช้ได้ทันที
- แนะนำติดตั้ง Git for Windows (ใช้ bash.exe เป็น shell หลัก, fallback cmd.exe)

### สิ่งที่ v1 จะประกาศเป็นข้อจำกัด (ตั้งใจ ไม่ใช่ทำไม่ทัน)
- **ไม่มี OS sandbox** — Windows ไม่มีของเทียบ `sandbox-exec`/`bwrap` ที่ Node
  เรียกได้โดยตรง (ทางเลือกอนาคต: AppContainer/Job Objects ต้องมี native addon)
- **ยกเลิกงานแบบ hard-kill เท่านั้น** (`taskkill /T /F`) — ไม่มี SIGTERM grace
- desktop tools (จับหน้าจอ/ควบคุมหน้าต่าง) = NOT_SUPPORTED
  (ตัว backend เป็น Swift/macOS; ระบบ gate ปัจจุบันจัดการให้เรียบร้อยแล้ว)
- POSIX file mode เป็น no-op บน NTFS → ใช้ ACL ของโปรไฟล์ผู้ใช้แทน (ระบุใน SECURITY.md)
- UNC path (`\\server\share`) ไม่รองรับในโหมด cmd, Windows ARM64 ยังไม่ตรวจ

---

## 4. งานหลัก แบ่งเป็น 4 กลุ่มปัญหา

| กลุ่ม | ปัญหา | แนวแก้ที่ตัดสินใจแล้ว |
|---|---|---|
| A. Transport/IPC | Unix socket ใช้ไม่ได้; สิทธิ์ 0600 ไม่มีความหมายบน named pipe | named pipe `\\.\pipe\juju-<hash>` + **token ลับต่อ boot** เก็บในไฟล์ ACL เฉพาะเจ้าของ ใช้ทุกแพลตฟอร์มให้พฤติกรรมเดียวกัน |
| B. Process/Shell/Exec | `/bin/bash`, exec bit, `process.kill(-pid)`, `.cmd` spawn ไม่ได้ตรง ๆ | shellSpec: Git-bash ก่อน → cmd.exe `/d /s /c`; resolver กลางรองรับ PATHEXT; ฆ่า tree ด้วย `taskkill /T /F` path เต็ม |
| C. Path security (NTFS) | ADS/8.3 ทะลุ secret guard; case-insensitive; ชื่อต้องห้าม (CON, NUL) | canonicalize ด้วย `realpathSync.native` + เทียบ segment แบบ case-insensitive แล้วเช็ค secret ซ้ำบน path จริง; ห้าม `:` ในทุก segment; ปฏิเสธชื่ออุปกรณ์ |
| D. Ecosystem | git/rg โดน cwd-first hijack; env ลูกขาดตัวแปร Windows; CRLF/BOM; rename ทับไฟล์ read-only/AV lock | spawn ด้วย absolute path เท่านั้น; BASE_ALLOWED ชุด Windows; retry แบบ bounded บน EPERM/EBUSY; รองรับ CRLF ใน edit/search |

---

## 5. แผนดำเนินการ — 4 เฟส 15 ขั้น (แผนหลัก 39.5 วัน)

> ตารางเต็มพร้อมรายชื่อไฟล์ต่อขั้นอยู่ใน [WINDOWS_PLAN.md](WINDOWS_PLAN.md)
> หลักการเรียง: ตั้งเครื่องตรวจก่อน → ทำให้บูตได้ → ปิดช่องความปลอดภัย → ประกาศ

### เฟส 0 — เครื่องตรวจ (1 วัน)
| ขั้น | งาน | วัน |
|---|---|---|
| 1 | เพิ่ม CI `windows-latest` (Node 22/24) แบบ allow-fail + helper `itWin/itPosix` + บันทึก baseline สีแดงแรก | 1 |

### เฟส 1 — บูตและรันได้ (13 วัน)
| ขั้น | งาน | วัน |
|---|---|---|
| 2 | IPC → named pipe + token ต่อ boot (ทุกแพลตฟอร์ม) | 2.5 |
| 3 | Process management: `taskkill /T /F`, detached:false + windowsHide, กัน slot รั่ว | 3 |
| 4 | Resolver กลาง `execResolve.ts`: PATHEXT, ห้าม cwd, ปิดช่อง git/rg hijack | 2.5 |
| 5 | Shell strategy: Git-bash → cmd.exe, batch ผ่าน `cmd /d /s /c` + validation เข้ม | 4 |
| 6 | Env ลูกชุด Windows (SYSTEMROOT, APPDATA, LOCALAPPDATA, PATHEXT, …) | 1 |

**จุดตรวจรับเฟส 1**: `juju stdio` + `juju start` บูตบน windows-latest,
เขียน/แก้ไฟล์/รันคำสั่ง/ยกเลิกงานได้จริงใน CI

### เฟส 2 — ความปลอดภัยและความถูกต้อง (16 วัน)
| ขั้น | งาน | วัน |
|---|---|---|
| 7 | LSP บน Windows (.exe เท่านั้น + ชี้ทาง node.exe สำหรับ shim) | 2 |
| 8 | git/ripgrep: absolute path, longpaths, autocrlf, staging ผ่าน stdin | 3 |
| 9 | **Path policy NTFS (หัวใจความปลอดภัย)**: ADS/8.3/case/ชื่อต้องห้าม | 5 |
| 10 | ตำแหน่ง state → `%LOCALAPPDATA%\juju` + icacls + doctor เตือน | 1.5 |
| 11 | Atomic write บน NTFS: read-only/AV lock retry, no fsync-dir | 2 |
| 12 | CRLF/BOM ใน read/edit/search ครบวงจร | 2.5 |

**จุดตรวจรับเฟส 2**: เทสต์ security ชุด `.env::$DATA` / `GIT~1` / repo-planted
`git.exe` ต้องเขียวบน windows-latest ทุกข้อ

### เฟส 3 — เทสต์ เอกสาร และประกาศ (9.5 วัน)
| ขั้น | งาน | วัน |
|---|---|---|
| 13 | แปลงชุดเทสต์เดิมให้ portable + เทสต์เฉพาะ Windows ใหม่ | 5 |
| 14 | เอกสาร: COMPATIBILITY/SECURITY/README/LSP/ADR | 1.5 |
| 15 | Claim gate: CI เป็น required + ทดสอบมือ Windows 11 จริง 1 รอบ → เปลี่ยนสถานะเป็น "supported" | 3 |

---

## 6. งานเพิ่มจากฟีเจอร์รุ่น 0.4–0.7 (ตรวจใหม่ 10 ก.ย. — เพิ่ม 11.5 วัน)

แผนหลักทำไว้ตอนระบบมี 43 tools ปัจจุบันมี 74 การสแกนโมดูลใหม่พบว่า
ส่วนใหญ่เขียนแบบ portable อยู่แล้ว เหลืองานเพิ่มดังนี้

| โมดูล | วันเพิ่ม | สาระสำคัญ |
|---|---|---|
| Owner-control / `juju kill` / schedules | **6** | ก้อนใหญ่สุด: ระบบยืนยันตัวตน socket ใช้ POSIX uid/inode ซึ่งไม่มีบน Windows ต้องย้ายเป็นโมเดล token เดียวกับขั้นที่ 2; `juju kill` มี gate ปฏิเสธ win32 อยู่แล้วต้องเขียนเส้นทางใหม่; schedule default `sandbox:true` จะล้มบน Windows ต้อง degrade อย่างประกาศ |
| Multimodal (media/browser/game/workflow) | **3** | เกือบทั้งหมด portable; blocker เดียวคือ Playwright launch แทนที่ env ทั้งชุด (ลูกไม่ได้ SYSTEMROOT → Chromium ไม่ขึ้น); ที่เหลือคือ `O_NOFOLLOW` เป็น no-op, `rmSync` ต้อง retry, ข้าม chmod |
| Assistance / large-inputs | **1.5** | เพดาน argv ต้องอิง CreateProcess 32,767 chars; ไฟล์สคริปต์ส่วนตัว mode 0600 → ACL |
| Desktop | **1** | สร้างมาพร้อม platform gate ที่สะอาดมาก — บน Windows ตอบ NOT_SUPPORTED ถูกต้องอยู่แล้ว เหลือแก้ข้อความ/กัน `desktop allow --persist` บันทึกสิทธิ์ที่ใช้ไม่ได้ (การทำ desktop จริงบน Windows ด้วย UIAutomation ≈ +20 วัน เป็นตัวเลือกอนาคต ไม่รวมใน v1) |

---

## 7. งบเวลารวมและทางเลือกดำเนินการ

| รายการ | วันงาน |
|---|---|
| แผนหลัก 15 ขั้น | 39.5 |
| งานเพิ่มจาก 0.4–0.7 | 11.5 |
| **รวม v1 (สโคป 0.7.x เต็ม)** | **51 (ช่วง 40–65)** |

### ทางเลือกลดสโคปเพื่อออกเร็วขึ้น
- **ตัด LSP ภายนอก + git system-config reinjection ไปรุ่นถัดไป**: เหลือ ~45 วัน
- **v1-lite เฉพาะ STDIO coding** (ไม่รวม HTTP/OAuth บน Windows — ผู้ใช้ Windows
  ใช้กับ Codex/Claude ในเครื่อง ส่วน ChatGPT ใช้ server บน Mac/Linux ต่อไป):
  ตัดขั้นที่เกี่ยว HTTP acceptance ลงได้อีก ~4–5 วัน
- เพดานเสี่ยงสุด: ถ้าต้องทำ cmd.exe เป็น first-class เต็มรูปแบบ (ผู้ใช้ไม่มี
  Git for Windows) ค่าใช้จ่าย quoting จะดันไปทางขอบบนของช่วง

### ปัจจัยเครื่องทดสอบ (ตัวแปรสำคัญที่สุดของตาราง)
| สภาพ | ผล |
|---|---|
| มีเครื่อง Windows 11 จริง | รอบ debug เร็ว, ตารางตามแผน |
| ใช้ CI อย่างเดียว | ทำได้ (แผนออกแบบมาเผื่อแล้ว — ขั้นที่ 1 คือ CI ก่อนเพื่อการนี้) แต่รอบแก้-รอ-ดูผลช้ากว่ามาก บวกเวลา ~15–25% และขั้นที่ 15 ยังต้องมีเครื่องจริงอย่างน้อย 1 ครั้งเพื่อทดสอบสิ่งที่ runner ทำไม่ได้ (ผู้ใช้คนที่สองเข้า pipe, Defender จริง, OneDrive, Claude Desktop/Cursor จริง) |

---

## 8. เกณฑ์ปิดงาน (นิยามคำว่า "รองรับ Windows")

จะเปลี่ยนสถานะใน COMPATIBILITY.md จาก "not supported" เป็น "supported" ก็ต่อเมื่อ**ครบทุกข้อ**:

1. CI `windows-latest` (Node 22 และ 24) รันชุดเทสต์เต็มเป็น **required job** และเขียว
   — การ skip ทำได้เฉพาะข้อที่ตรงกับข้อจำกัดที่ประกาศไว้ (เช่น sandbox, speech)
2. เทสต์ความปลอดภัยเฉพาะ Windows เขียวทั้งหมด: ADS/8.3 ถูกปฏิเสธ,
   repo-planted executable ไม่ถูกรัน, token IPC กันผู้ใช้อื่น
3. ทดสอบมือบนเครื่อง Windows 11 x64 จริง 1 รอบตาม checklist ใน MANUAL_ACCEPTANCE
   (ติดตั้งสด, start/stdio/status/stop, client จริง 1 ตัว, Defender เปิด,
   ผู้ใช้ OS คนที่สองเข้าถึง IPC ไม่ได้) และบันทึกผลใน TEST_REPORT.md
4. เอกสารข้อจำกัดครบ (ไม่มี sandbox, hard-kill, desktop/speech NOT_SUPPORTED,
   ACL แทน POSIX mode)
5. ไม่มีการอ้างผลที่ไม่ได้รันจริง — มาตรฐานเดียวกับทุกรุ่นที่ผ่านมา

---

## 9. ความเสี่ยงหลักและการรับมือ

| ความเสี่ยง | ระดับ | การรับมือ |
|---|---|---|
| ช่อง NTFS (ADS/8.3) ปิดไม่สนิท | สูงสุดในเชิงผลกระทบ | ขั้นที่ 9 ทำแบบ fail-closed + เทสต์ adversarial เฉพาะทาง + ทบทวนโดย reviewer อิสระก่อน merge (ใช้กระบวนการเดียวกับ compact gateway ที่เพิ่งทำ) |
| เทสต์ flaky บน Windows CI (AV/file lock/timing) | สูงในเชิงเวลา | retry แบบ bounded ใน helper, แยกเทสต์ timing-sensitive, งบเวลาขั้นที่ 13 ตั้งเผื่อไว้แล้ว 5 วัน |
| shell/batch edge cases (`cmd.exe` quoting, npm.cmd) | กลาง | จำกัดสโคป: batch รับเฉพาะ argv ที่ validate ผ่าน (ปฏิเสธ `% ! "` CR/LF) แทนการพยายาม escape ทุกกรณี |
| dependency ที่ไม่เคยรันบน Windows (oidc-provider, sharp, playwright) | กลาง-ต่ำ | ทั้งหมดประกาศรองรับ Windows อย่างเป็นทางการ; ตรวจจริงในเฟส 1 วันแรก ๆ ผ่าน CI |
| ไม่มีเครื่อง Windows | กลาง | CI-first ตั้งแต่ขั้น 1; ยืม/เช่าเครื่องเฉพาะขั้นที่ 15 |

---

## 10. สิ่งที่ต้องตัดสินใจก่อนเริ่ม

1. **อนุมัติสโคป v1** ตามข้อ 3 (รวม multimodal, ไม่รวม desktop/speech/sandbox) หรือเลือก v1-lite
2. **เครื่องทดสอบ**: จะจัดหาเครื่อง Windows 11 จริงหรือเริ่มแบบ CI-only
3. **เวอร์ชันเป้าหมาย**: เสนอเป็น 0.8.0 (minor ใหม่ เพราะเพิ่มแพลตฟอร์ม)
4. จังหวะเริ่ม: แผนนี้เริ่มได้ทันที ขั้นที่ 1–2 ไม่กระทบผู้ใช้ macOS/Linux เลย
   (ทุกอย่างอยู่หลัง `process.platform === 'win32'` และ CI แยก job)

---

## ภาคผนวก: เอกสารอ้างอิง

- [WINDOWS_PLAN.md](WINDOWS_PLAN.md) — ผล audit เต็ม: 86 ประเด็นยืนยันแล้ว
  (blocker 19 / degraded 45 / cosmetic 22), ตาราง 15 ขั้นพร้อมรายชื่อไฟล์,
  ประเด็นที่ reviewer ตีตก 10 ข้อ (กันทำงานซ้ำ), แนวทางจัดการข้อที่ยังเห็นต่าง
- [COMPATIBILITY.md](COMPATIBILITY.md) — สถานะแพลตฟอร์มปัจจุบัน
- [SECURITY.md](SECURITY.md) — โมเดลความปลอดภัยที่ทุกการแก้ต้องรักษา
- ADR-029 — โครง tool surface (ไม่ผูกกับ OS)
- ผลสแกนโมดูล 0.4–0.7 (10 ก.ย. 2026): desktop +1 วัน / multimodal +3 /
  owner-control +6 / assistance +1.5 — รวม +11.5 วัน