G-Launcher/AGENTS.md

Repository rules

ห้าม hardcode ค่าที่เปลี่ยนตามสภาพแวดล้อมหรือการใช้งาน

• ห้ามใส่ path ของเครื่อง, ชื่อผู้ใช้, Desktop, ไดรฟ์ติดตั้ง (C:\...), path ของเกม/Proxy/Server/Go/Node, IP, port, URL ของ deployment หรือ endpoint ลงใน source code, logic หรือ startup scripts
• ค่า URL, endpoint, และ repository config ต้องรวมศูนย์อยู่ที่ pkg/constant/constant.go หรือ config file กลางเท่านั้น ห้ามกระจายค่าคงที่หรือซ่อน hardcode ไว้ตาม service
• การเข้าถึง filesystem ภายในเครื่องต้องใช้ filepath.Join(...) เสมอ และโฟลเดอร์ข้อมูลผู้ใช้ต้องอ้างอิงผ่าน os.UserConfigDir() (%APPDATA%) เท่านั้น ห้ามเดาพาธจากไดรฟ์หรือชื่อโฟลเดอร์
• ค่าเฉพาะเครื่องต้องอยู่ในไฟล์ local ที่ถูก ignore หรือ environment ห้าม commit ข้อมูลเฉพาะเครื่องเข้า Git
• ห้ามอ้างว่าเอา hardcode ออกหมดทั้ง repository หากตรวจหรือแก้เพียงบางส่วน ต้องระบุขอบเขตและส่วนที่ยังเหลือจริงตามความเป็นจริง

สถาปัตยกรรม System-First และลำดับการพัฒนา

• ทุกครั้งที่เพิ่มฟีเจอร์ ปรับแต่ง logic หรือแก้ schema ให้ทำที่ Go Backend (internal/, pkg/, main.go) ให้เสร็จสิ้นและรัน go vet ./... ผ่าน 100% ก่อนแตะ Frontend UI ทุกครั้ง
• เมื่อ Go Backend เปลี่ยนแปลง ต้องรัน wails3 generate bindings เพื่อซิงก์ TypeScript Bindings ลง frontend/bindings/ ก่อนเริ่มเขียนหรือแก้ไข UI ใน frontend/src/
• ห้ามแก้ Frontend UI ให้เรียก method หรือ property ที่ยังไม่มีใน Go Backend เด็ดขาด เพราะจะทำให้ Wails v3 เกิด Unhandled Exception จนหน้าต่าง Launcher ขาวสนิทหรือ crash ทันที
• ห้ามอ้างว่าแค่ build ผ่านหรือไม่มี type error แปลว่าหน้าต่าง Launcher ทำงานถูกต้อง ต้องเปิดตรวจสอบการตอบสนองจริงหรือรายงานว่ายังรอการยืนยัน

กฎของระบบอัปเดตและบิลด์ท้องถิ่น (Updater Lifecycle Contract)

• ระบบอัปเดตทั้งในสคริปต์และในแอป ต้องทำงานตามลำดับ 4 ขั้นตอนอย่างเคร่งครัด: ดาวน์โหลดลง Temp -> Build ใหม่ใน Temp -> นำมาสลับแทนที่ของเก่า -> ลบ Temp ทิ้ง 100%
• ห้าม git pull หรือรัน compiler ทับโฟลเดอร์หลักของ Launcher ขณะที่ตัว Launcher รันอยู่โดยตรง เพราะจะติด Windows Executable File Lock (Access is denied) และทำให้โฟลเดอร์ทำงานเสียหาย
• การสลับไฟล์ .exe บน Windows ต้องใช้วิธี Rename ไฟล์เดิมที่กำลังรันอยู่เป็น .old ก่อน แล้วจึงย้ายไฟล์ใหม่เข้ามาแทนที่ หากเกิดข้อผิดพลาดระหว่างย้าย ต้อง Rollback นำไฟล์ .old กลับคืนมาทันที ห้ามทิ้งไฟล์ให้อยู่ในสถานะเสียหาย
• โฟลเดอร์ชั่วคราว (temp/build_workspace หรือ os.MkdirTemp) ต้องถูกลบทิ้ง 100% ผ่านบล็อก finally หรือ defer os.RemoveAll เสมอ ห้ามทิ้งไฟล์ขยะตกค้าง

ความปลอดภัยของข้อมูลและการแก้ไขไฟล์ตัวเกม (Data Safety & Atomic Operations)

• ไฟล์ตัวเกมและไฟล์เซฟเป็นข้อมูลที่มีขนาดใหญ่และเสียหายง่าย ก่อนจะ patch, แก้ไข หรือเขียนทับไฟล์ใดๆ (เช่น .dll, .exe, ExcelData) ต้องคัดลอกไฟล์เดิมไว้เป็นนามสกุล .backup เสมอ
• หากการ patch, verify hash, หรือ download เกิดข้อผิดพลาด ต้องทำ Atomic Rollback กู้คืนไฟล์ .backup กลับมาทันที ห้ามทิ้งไฟล์เกมในสภาพเสียหาย
• การบันทึกไฟล์คอนฟิก (เช่น game-selection.json) ห้ามใช้ os.WriteFile ธรรมดา เพราะไฟดับหรือ crash จะทำให้ไฟล์กลายเป็น 0 ไบต์ ต้องเขียนลง .tmp พร้อม file.Sync() แล้วสลับด้วย Windows API MoveFileEx (MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) เท่านั้น

การจัดการเครื่องมือและ Zero-Dependency

• ห้ามสมมติว่าเครื่องผู้ใช้มี Git, Go, Node.js หรือ 7-Zip อยู่ใน PATH สคริปต์ bootstrap ต้องมีระบบดาวน์โหลด portable runtime อัตโนมัติลงใน tools/
• ฝั่ง Launcher ต้องแตก binary tools (7za.exe, hpatchz.exe, zift.exe) ออกจาก embed assets ลง bin/ อัตโนมัติเมื่อเริ่มโปรแกรม
• สคริปต์ PowerShell ทั้งหมดที่มีอักขระสองไบต์หรือภาษาไทย ต้องบันทึกเป็น UTF-8 with BOM ([System.Text.Encoding]::UTF8) เสมอ เพื่อป้องกัน Windows PowerShell 5.1 ตีความไบต์ผิด
• คำสั่ง Git ในสคริปต์และในโค้ด ต้องกำหนด GIT_TERMINAL_PROMPT=0 เสมอ เพื่อป้องกันโปรเซสค้างจากการรอ interactive credentials prompt

การอนุรักษ์ Naming และการ Refactor

• ห้ามใช้วิธี Find-and-Replace ชื่อโปรเจกต์เดิม (เช่น sunbringer, firefly) สุ่มสี่สุ่มห้าทั่วทั้งโปรเจกต์ เพราะจะทำให้ internal protocol, protobuf serialization, หรือ build manifest พัง
• ให้แยก User-Facing Branding (เช่น ชื่อหน้าต่าง, Title, Tooltip) ออกจาก System/Package Identifier ภายในให้ชัดเจน เปลี่ยนเฉพาะส่วนที่จำเป็นเมื่อระบบ core นิ่งแล้วเท่านั้น

Git Workflow และความสะอาดของ Repository

• ทำงานและ Commit บน branch Dev เท่านั้น ห้ามแตะต้องหรือ push เข้า main โดยตรง
• ก่อน Commit ทุกครั้ง: Go ต้องผ่าน go vet ./... 100% และ Frontend ต้องผ่าน npm run build 100%
• รักษาความสะอาดของ .gitignore ห้าม commit ไฟล์ _references/, dist/, node_modules/, bin/, temp/, tools/, server/, หรือ *.old เข้า Git

การฟื้นตัวของ AI หลัง Compact บริบท

• เมื่อ AI เริ่มเซสชันใหม่หรือฟื้นตัวหลังจากการทำ Compact บริบท ให้เปิดอ่านไฟล์ในโฟลเดอร์ Doc/ (โดยเฉพาะ Doc/G-LAUNCHER-HANDOFF.md) ทันทีเพื่อคืนบริบทและทำความเข้าใจสถานะจริงก่อนเริ่มงานเสมอ