@warnyin/agents 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -23,6 +23,11 @@
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-06-11
+
+### Added
+- **Global install mode — ติดตั้งครั้งเดียวใช้ได้ทุกโปรเจกต์ (opt-in)** (feature `global-install`) — `npx @warnyin/agents --global` ติดตั้ง adapter → `~/.claude/{commands/warnyin,agents,skills}` + playbook → `~/.warnyin/{workflow,template}` **ครั้งเดียว** → `/warnyin:*` ใช้ได้ทุกโปรเจกต์ (Claude Code โหลด user-level `~/.claude/`). **Hybrid:** workspace (`docs/`) ยัง per-project; โปรเจกต์ที่มี `./.warnyin/` local → ใช้ local ก่อน (override → คง reproducibility); **per-project ยังเป็น default**. **mode resolution** `resolveMode()` (pure-fn): flag `--global`/`--project`; ไม่ระบุ+TTY → prompt; **non-TTY → project (CI-safe ไม่ค้าง)**; `--global --project` → error. **ปลอดภัยต่อ homedir:** first-install `overwrite:false` (ไม่ทับไฟล์ user ใน `~/.claude/{agents,skills}`), `installGlobalNote()` เขียน `~/.claude/CLAUDE.md` แบบ **append-with-marker** (ไม่แตะ personal global memory), homedir guard (falsy/root → error), echo target paths. **resolve playbook local-first → global** ผ่าน convention canonical ใน `CLAUDE.md`/`AGENTS.md`/`CLAUDE.global.md` (ไม่ duplicate ลงทุก adapter). `/warnyin:init` รับ workspace bootstrap (scaffold + seed `docs/`, อ่าน template local→global). **backward compatible** (project mode = default ไม่เปลี่ยน; `--global` opt-in). **limitation:** Codex/Antigravity global root doc รอบนี้ยังไม่รองรับ (per-project ใช้ได้เต็ม). zero-dep + cross-platform (`os.homedir()`, HOME/USERPROFILE); payload ติดมากับ `--update` รอบถัดไป
+
 ## [0.12.0] - 2026-06-11
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warnyin/agents",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Warnyin Standard Workflow installer — 5-stage ways of work (Discovery/DESIGN/BUILD/VERIFY/SHIP) สำหรับทุกโปรเจกต์",
   "type": "module",
   "license": "MIT",

package/src/.warnyin/installer/templates/CLAUDE.global.md

@@ -0,0 +1,5 @@
+<!-- warnyin:global-note -->
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)

package/src/.warnyin/installer/templates/CLAUDE.md

@@ -28,3 +28,7 @@ Claude Code อ่าน `.claude/` + ไฟล์นี้, ส่วน Codex/
 
 ## อัปเดต workflow
 `npx @warnyin/agents --update` — เขียนทับเฉพาะ playbook กลาง (`.warnyin/workflow/`, `.claude/commands/warnyin/`, template `.warnyin/template/stages/[topic]/`) ไม่แตะ `docs/` และงานจริงใน `docs/stages/`
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)

package/src/.warnyin/workflow/init.md

@@ -31,6 +31,16 @@
 
 ## 3. ลำดับขั้นการทำงาน (process)
 
+0. **Workspace bootstrap (ทำก่อนวิเคราะห์โปรเจกต์ — idempotent):**
+   - **หา template:** ตรวจ `./.warnyin/template/` ก่อน (local) — ไม่มีหรือไม่มี `./.warnyin/` → fallback `~/.warnyin/template/` (global install); ใช้ path ที่พบเป็น `<template>`
+   - **สร้าง scaffold (ถ้ายังไม่มี):**
+     - `docs/stages/context.md` — ไม่มีให้สร้างไฟล์เปล่า; มีอยู่แล้ว → ข้าม
+     - `docs/stages/achieved/.gitkeep` — ไม่มีให้สร้างไฟล์เปล่า (สร้าง dir `docs/stages/achieved/` ด้วยถ้าจำเป็น); มีอยู่แล้ว → ข้าม
+   - **seed `docs/` จาก `<template>/docs/**` (ถ้า template มี):**
+     - วน entry ใน `<template>/docs/` — **ข้าม entry ที่ชื่อขึ้นต้นด้วย `[`** (placeholder เช่น `[component]/`, `[topic]/` — seedDocs-skip invariant)
+     - entry ที่เหลือ: ปลายทาง `docs/<entry>` — **ไม่ทับไฟล์ที่มีอยู่แล้ว** (copy เฉพาะที่ยังไม่มี)
+   - **ทั้งหมดนี้เป็น agent-driven** — agent ตรวจ/สร้างไฟล์เปล่าเอง; ไม่ต้องรัน script
+
 1. **สแกนภาพรวม:** โครงสร้าง repo, package manifest, ภาษา/framework, แบ่งเป็น **component** อะไรบ้าง (เช่น api-service, admin-console)
 2. **วิเคราะห์ลึกต่อ component (ขนานได้, read-only):** โครงสร้างโฟลเดอร์/โมดูล, pattern/convention ที่ใช้จริงในโค้ด, วิธี build/test ที่มีอยู่
 3. **วิเคราะห์ infra:** docker/compose, env, service ที่ต้องรันสำหรับ local dev
@@ -44,7 +54,7 @@
 5. **เสนอ summary → user ยืนยันครั้งเดียว**
 6. **เขียนไฟล์จริงลง `docs/` ให้ครบตาราง §4 (ขั้นบังคับ ห้ามข้าม)** — ทำตามกลไก 6.1–6.4 นี้:
 
-   **6.1 ไฟล์ root** — copy template แล้วเติม:
+   **6.1 ไฟล์ root** — copy template แล้วเติม (ขั้นนี้ = เติมเนื้อหาหลังวิเคราะห์ เสริมขั้น 0 ที่สร้าง scaffold/seed ไว้แล้ว):
    ```
    mkdir -p docs
    cp .warnyin/template/docs/project.md         docs/project.md
@@ -52,6 +62,7 @@
    cp .warnyin/template/docs/rule.md            docs/rule.md
    cp .warnyin/template/docs/troubleshooting.md docs/troubleshooting.md
    ```
+   - ใช้ `.warnyin/template/` (local) — per-project install มีให้เสมอ; global mode ขั้น 0 seed ให้แล้ว (template อ่าน local→global ตามขั้น 0)
    - ไฟล์ไหนมีอยู่แล้วใน `docs/` → **ห้าม `cp` ทับ** ให้เปิดอ่านแล้ว Edit เติมแทน
    - `project.md` → เติมจากผลสัมภาษณ์ user (ข้อ 4) · `infra.md` → เติมจาก config จริง (ข้อ 3) · `rule.md`/`troubleshooting.md` → วางโครงหัวข้อ ใส่ `<!-- ยังว่าง รอเติม -->` ในส่วนที่ยังไม่มีข้อมูล
 

package/src/AGENTS.md

@@ -46,3 +46,9 @@ Discovery (optional) ──▶ DESIGN ──▶ BUILD ──▶ VERIFY ──▶
 ทำตาม `.warnyin/workflow/stages/discovery.md` — เริ่มอ่าน `docs/project.md`, ตี scope กว้าง→แคบ,
 ถามทีละข้อพร้อมเสนอคำตอบที่แนะนำ, คำถามที่ตอบได้ด้วยโค้ดให้ไปอ่านโค้ดเอง,
 เขียน output ลง `docs/stages/<slug>/discovery.md` และ `research.md`
+
+## การ resolve playbook (local-first → global)
+- path `.warnyin/workflow/...` / `.warnyin/template/...`: หาในโปรเจกต์ `./.warnyin/` ก่อน ไม่มี → `~/.warnyin/` (global install)
+- ถ้ายังไม่มี `docs/stages/` (global mode โปรเจกต์ใหม่) → รัน `/warnyin:init` ก่อน (สร้าง workspace)
+
+> หมายเหตุ: global root doc ของ Codex/Antigravity ไม่รองรับรอบนี้ — convention นี้มีผลเฉพาะ per-project path

package/src/bin/cli.mjs

@@ -1,28 +1,50 @@
 #!/usr/bin/env node
 /**
  * warnyin-agents installer
- * ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน (cwd)
+ * ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน (cwd) หรือแบบ global (~/)
  *
- *   npx @warnyin/agents             ติดตั้ง (ข้ามไฟล์ที่มีอยู่แล้ว)
+ *   npx @warnyin/agents             ติดตั้งลงโปรเจกต์ (ข้ามไฟล์ที่มีอยู่แล้ว)
+ *   npx @warnyin/agents --global    ติดตั้งแบบ global (~/) ใช้ได้ทุกโปรเจกต์
+ *   npx @warnyin/agents --project   ติดตั้งลงโปรเจกต์ (บังคับ — ไม่ถาม)
  *   npx @warnyin/agents --update    อัปเดต playbook กลาง (เขียนทับเฉพาะไฟล์ core)
  *   npx @warnyin/agents --dry-run   แสดงว่าจะทำอะไร โดยไม่เขียนไฟล์จริง
  *   (ทางสำรองไม่ผ่าน npm: npx github:warnyin/warnyin-agents)
  */
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
 
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const target = process.cwd()
+const cwd = process.cwd()
 const args = new Set(process.argv.slice(2))
 const UPDATE = args.has('--update')
 const DRY = args.has('--dry-run')
 
+/**
+ * ★ pure function — เลือก mode จาก flag/TTY/answer (ไม่มี side-effect, export ให้ unit test)
+ * @param {{globalFlag?:boolean, projectFlag?:boolean, isTTY?:boolean, answer?:string}} o
+ * @returns {'project'|'global'}
+ */
+export function resolveMode({ globalFlag, projectFlag, isTTY, answer } = {}) {
+  if (globalFlag && projectFlag) {
+    throw new Error('--global กับ --project ใช้พร้อมกันไม่ได้ (เลือกอย่างใดอย่างหนึ่ง)')
+  }
+  if (globalFlag) return 'global'
+  if (projectFlag) return 'project'
+  if (!isTTY) return 'project' // CI-safe default — npx/pipe ไม่ค้างรอ input
+  const a = (answer ?? '').trim().toLowerCase()
+  return a === '2' || a === 'global' ? 'global' : 'project'
+}
+
 if (args.has('--help') || args.has('-h')) {
-  console.log(`warnyin-agents — ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน
+  console.log(`warnyin-agents — ติดตั้ง Warnyin Standard Workflow ลงโปรเจกต์ปัจจุบัน หรือแบบ global
 
 ใช้งาน:
-  npx @warnyin/agents             ติดตั้ง (ข้ามไฟล์ที่มีอยู่แล้ว ไม่เขียนทับ)
+  npx @warnyin/agents             ติดตั้งลงโปรเจกต์ (ถ้า TTY จะถามก่อน; ข้ามไฟล์ที่มีอยู่แล้ว)
+  npx @warnyin/agents --global    ติดตั้งแบบ global ลง ~/ (~/.warnyin + ~/.claude) ใช้ได้ทุกโปรเจกต์
+  npx @warnyin/agents --project   ติดตั้งลงโปรเจกต์ (บังคับ ไม่ถาม)
   npx @warnyin/agents --update    อัปเดต playbook กลางเป็นเวอร์ชันล่าสุด
                                   (เขียนทับเฉพาะ .warnyin/workflow/, .claude/commands/warnyin/,
                                    template .warnyin/template/stages/[topic] — ไม่แตะ docs/ และงานจริง)
@@ -33,15 +55,15 @@ if (args.has('--help') || args.has('-h')) {
 }
 
 // guard กัน self-install — เก็บไว้แบบ defensive (zero-cost)
-// หลังย้าย source เข้า src/ → pkgRoot = src/ (sibling ของ bin/) จึงแทบไม่มีทาง === target (repo root / temp sandbox)
+// หลังย้าย source เข้า src/ → pkgRoot = src/ (sibling ของ bin/) จึงแทบไม่มีทาง === cwd (repo root / temp sandbox)
 // → guard นี้เป็น no-op โดยตั้งใจในเคสปกติ/sandbox; ยังคงดักได้เฉพาะ edge case ที่ install ลงโฟลเดอร์ที่เป็น src/ เอง
-if (path.resolve(pkgRoot) === path.resolve(target)) {
+if (path.resolve(pkgRoot) === path.resolve(cwd)) {
   console.error('✖ กำลังรันอยู่ใน repo ของ warnyin-agents เอง — ให้ cd ไปที่โปรเจกต์ปลายทางก่อน')
   process.exit(1)
 }
 
 // โครงเก่า (≤0.2.x): workflow/ + warnyin-stages/ ที่ root — เตือนให้ย้ายเอง ไม่แตะงานจริงของ user
-const legacyV2 = ['workflow', 'warnyin-stages'].filter((d) => fs.existsSync(path.join(target, d)))
+const legacyV2 = ['workflow', 'warnyin-stages'].filter((d) => fs.existsSync(path.join(cwd, d)))
 if (legacyV2.length) {
   console.warn(`⚠ พบโครงเลย์เอาต์เก่า (≤0.2.x): ${legacyV2.join(', ')}
 เวอร์ชันนี้ย้าย core ไปใต้ .warnyin/ และงานจริงไป docs/stages/ — แนะนำย้ายด้วยตัวเองก่อน:
@@ -52,7 +74,7 @@ if (legacyV2.length) {
 
 // โครงเก่า (0.3–0.5.x): ทุกอย่างอยู่ใต้ warnyin/ ที่ root — เวอร์ชันนี้แยกเป็น .warnyin/ (core) + docs/stages (งานจริง)
 const legacyV5 = ['workflow', 'template', 'installer', 'stages'].filter((d) =>
-  fs.existsSync(path.join(target, 'warnyin', d)),
+  fs.existsSync(path.join(cwd, 'warnyin', d)),
 )
 if (legacyV5.length) {
   console.warn(`⚠ พบโครงเลย์เอาต์เก่า (0.3–0.5.x): warnyin/{${legacyV5.join(', ')}}
@@ -79,6 +101,9 @@ const SCAFFOLD_FILES = [
 
 const stats = { created: 0, updated: 0, skipped: 0 }
 
+// target = ปลายทางที่จะเขียนไฟล์ — ตั้งหลัง resolve mode (project=cwd | global=homedir)
+let target = cwd
+
 function copyTree(relDir, { overwrite }) {
   const srcDir = path.join(pkgRoot, relDir)
   if (!fs.existsSync(srcDir)) return
@@ -173,21 +198,113 @@ function installRootDoc(name, srcPath) {
   console.log(`  ± ${name} (ต่อท้าย section Warnyin Standard Workflow)`)
 }
 
-console.log(`Warnyin Standard Workflow → ${target}${DRY ? '  (dry-run)' : ''}\n`)
+const GLOBAL_NOTE_MARKER = '<!-- warnyin:global-note -->'
 
-for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
-ensureScaffold()
-seedDocs()
-installRootDoc('CLAUDE.md', path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.md'))
-installRootDoc('AGENTS.md', path.join(pkgRoot, 'AGENTS.md'))
+/**
+ * เขียน resolution note ลง ~/.claude/CLAUDE.md แบบ note-only append-with-marker (global mode)
+ * — ห้ามเขียนทับทั้งไฟล์ (personal global memory ของ user); append เฉพาะถ้ายังไม่มี marker (idempotent)
+ * — defensive skip ถ้า template ไม่มี (worktree T1 เดี่ยวก่อน merge T2) — pattern เดียวกับ copyTree/seedDocs
+ */
+function installGlobalNote() {
+  const src = path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.global.md')
+  const destRel = path.join('.claude', 'CLAUDE.md')
+  const dest = path.join(target, destRel)
+  if (!fs.existsSync(src)) {
+    console.log(`  · ข้าม ${destRel} (ยังไม่มี template CLAUDE.global.md)`)
+    return
+  }
+  const note = fs.readFileSync(src, 'utf8')
+  if (!fs.existsSync(dest)) {
+    if (!DRY) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true })
+      fs.writeFileSync(dest, note)
+    }
+    stats.created++
+    console.log(`  + ${destRel}`)
+    return
+  }
+  const existing = fs.readFileSync(dest, 'utf8')
+  if (existing.includes(GLOBAL_NOTE_MARKER)) {
+    stats.skipped++
+    return
+  }
+  const section = (existing.endsWith('\n') ? '\n' : '\n\n') + note
+  if (!DRY) fs.appendFileSync(dest, section)
+  stats.updated++
+  console.log(`  ± ${destRel} (ต่อท้าย warnyin global note)`)
+}
+
+/** เลือก mode + ติดตั้งตาม mode (target=cwd|homedir). ห่อ async เฉพาะ path TTY (readline) */
+async function main() {
+  const globalFlag = args.has('--global')
+  const projectFlag = args.has('--project')
+  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+  let mode
+  try {
+    if (!globalFlag && !projectFlag && isTTY) {
+      // ถาม เฉพาะ path TTY — non-TTY/flag ไม่แตะ readline (ไม่ค้าง/ไม่ช้าลง)
+      const rl = createInterface({ input: process.stdin, output: process.stdout })
+      let answer
+      try {
+        answer = await rl.question('ติดตั้งแบบไหน? [1] โปรเจกต์นี้ (default) [2] global (~/) : ')
+      } finally {
+        rl.close()
+      }
+      mode = resolveMode({ globalFlag, projectFlag, isTTY, answer })
+    } else {
+      mode = resolveMode({ globalFlag, projectFlag, isTTY })
+    }
+  } catch (e) {
+    console.error(`✖ ${e.message}`)
+    process.exit(1)
+  }
+
+  if (mode === 'global') {
+    const home = os.homedir()
+    // homedir guard — falsy หรือ filesystem root (CI/container ไม่มี passwd) → error แทนเขียนลง root
+    if (!home || path.resolve(home) === path.parse(path.resolve(home)).root) {
+      console.error('✖ หา home directory ไม่ได้ (หรือเป็น filesystem root) — ใช้ --project แทน')
+      process.exit(1)
+    }
+    target = home
+    console.log(`Warnyin Standard Workflow → global ${target}${DRY ? '  (dry-run)' : ''}`)
+    console.log(`  จะเขียนนอกโปรเจกต์ที่: ${path.join(target, '.warnyin')}, ${path.join(target, '.claude', 'commands', 'warnyin')}, ${path.join(target, '.claude', 'CLAUDE.md')}\n`)
+    // first-install overwrite:false (skip ของเดิมใน ~/.claude/{agents,skills}) — ทับเฉพาะ --global --update
+    for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
+    // ข้าม scaffold/seedDocs (ยกให้ /warnyin:init) + ข้าม AGENTS.md global (DQ3 limitation)
+    installGlobalNote()
+  } else {
+    target = cwd
+    console.log(`Warnyin Standard Workflow → ${target}${DRY ? '  (dry-run)' : ''}\n`)
+    for (const dir of CORE) copyTree(dir, { overwrite: UPDATE })
+    ensureScaffold()
+    seedDocs()
+    installRootDoc('CLAUDE.md', path.join(pkgRoot, '.warnyin', 'installer', 'templates', 'CLAUDE.md'))
+    installRootDoc('AGENTS.md', path.join(pkgRoot, 'AGENTS.md'))
+  }
+
+  console.log(`\nสรุป: สร้างใหม่ ${stats.created} · อัปเดต ${stats.updated} · ข้าม (มีอยู่แล้ว) ${stats.skipped}`)
 
-console.log(`\nสรุป: สร้างใหม่ ${stats.created} · อัปเดต ${stats.updated} · ข้าม (มีอยู่แล้ว) ${stats.skipped}`)
+  if (!UPDATE) {
+    if (mode === 'global') {
+      console.log(`
+ติดตั้ง global แล้ว — /warnyin:* ใช้ได้ทุกโปรเจกต์ (จาก ~/.claude/commands/)
+  เปิดโปรเจกต์ใด ๆ ใน Claude Code → รัน  /warnyin:init  เพื่อสร้าง workspace (docs/) ของโปรเจกต์นั้น
 
-if (!UPDATE) {
-  console.log(`
+อัปเดต playbook ภายหลัง:  npx @warnyin/agents --global --update`)
+    } else {
+      console.log(`
 ขั้นถัดไป:
   1. เปิด Claude Code ในโปรเจกต์นี้ แล้วรัน  /warnyin:init  — ให้ agent วิเคราะห์โปรเจกต์ + เติม docs/
   2. เริ่มงานแรก:  /warnyin:discovery <topic>  หรือ  /warnyin:design <slug> <change>
 
 อัปเดต playbook ภายหลัง:  npx @warnyin/agents --update`)
+    }
+  }
+}
+
+// main-guard: รันเฉพาะตอน execute ตรง ๆ (ไม่ trigger ตอน import เพื่อ unit-test resolveMode)
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main()
 }