clawpilot 0.1.1 → 0.2.0

package/docs/PUBLISH_CHECKLIST.md

@@ -1,22 +1,31 @@
-# Publish Checklist
-
-Use this checklist before publishing a new `clawpilot` version to npm.
-
-1. Verify tests:
-   - `npm test`
-2. Verify installer behavior locally:
-   - `node bin/cli.js install --home <temp-dir>`
-3. Review package metadata:
-   - `name`
-   - `version`
-   - `bin`
-   - `license`
-4. Confirm npm auth:
-   - `npm whoami`
-5. Dry-run package contents:
-   - `npm pack --dry-run`
-6. Publish:
-   - `npm publish --access public`
-7. Validate release:
-   - `npm view clawpilot version`
-   - `npx clawpilot@latest --help`
+# Publish Checklist
+
+Use this checklist before publishing a new `clawpilot` version to npm.
+
+1. Verify tests:
+   - `npm test`
+2. Verify installer behavior locally:
+   - `node bin/cli.js install --home <temp-dir>`
+   - `node bin/cli.js install --preflight`
+3. Verify runtime dry-run behavior:
+   - `node bin/cli.js run --command morning --dry-run --timezone UTC --role-pack hana`
+   - `node bin/cli.js run --command report --dry-run --timezone UTC`
+4. Verify structured error output:
+   - `node bin/cli.js run --command morning --json-errors` (without channel should return `channel_required`)
+5. Verify troubleshooting documentation references:
+   - `docs/troubleshooting.md`
+6. Review package metadata:
+   - `name`
+   - `version`
+   - `bin`
+   - `license`
+7. Confirm npm auth:
+   - `npm whoami`
+8. Dry-run package contents:
+   - `npm pack --dry-run`
+9. Publish:
+   - `npm publish --access public`
+   - If your account has publish 2FA enabled: `npm publish --access public --otp=<6-digit-code>`
+10. Validate release:
+   - `npm view clawpilot version`
+   - `npx clawpilot@latest --help`

package/docs/plans/2026-02-13-v0.3-clawra-gap-plan.md

@@ -0,0 +1,199 @@
+# Clawpilot v0.3 Plan (Clawra Gap Fill)
+
+Date: 2026-02-13  
+Owner: RyanSparkc / clawpilot  
+Status: Draft (local only)
+
+## 1) Goal
+
+在不複製「女友版」定位的前提下，補齊 clawra 的關鍵可用性能力，讓 clawpilot 達到：
+
+- 第一次安裝就能成功跑通
+- 發送失敗可被快速定位與修復
+- 有清楚的升級路徑與 demo 體驗
+- 維持「虛構韓系美感，不綁定真人身份」策略
+
+## 2) Scope (This Round)
+
+優先納入以下 7 項（依優先順序）：
+
+1. 安裝前檢查（OpenClaw / Gateway / 設定完整性）
+2. 引導式安裝流程（step-by-step）
+3. 重裝 / 升級處理（update/skip/reinstall）
+4. 送訊可靠性（錯誤分類 + 修復指引）
+5. 一鍵範例腳本（safe/send 雙軌 first success demo）
+6. 配置集中管理（delivery/channel/role-pack/runtime defaults）
+7. Troubleshooting 擴充（常見錯誤清單）
+
+## 3) Out of Scope (v0.3)
+
+- 真實人物身份綁定與肖像生成
+- 自動上傳多平台圖片（Discord/WhatsApp/Telegram 同時送圖）
+- 需要外部付費 API 的完整圖生產線（先保留接口，不強綁）
+
+## 4) Milestones
+
+## M1: Installer Reliability Foundation
+
+Target:
+- 安裝流程先做「前置檢查 + 引導」
+
+Tasks:
+- 新增 `preflight` 檢查模組，至少包含：
+  - `openclaw` CLI 是否可執行與版本資訊
+  - `openclaw` home / `skills` / `workspace` 目錄可寫入
+  - 既有 `openclaw.json` 可解析性
+  - `delivery.mode=openclaw-gateway` 時的必要欄位（如 channel / token 來源）
+- 在 `install` 內加入互動式步驟（timezone、delivery channel、role pack）
+- `--yes` 模式保留非互動安裝，缺值時給明確錯誤碼與修復指令
+
+Likely files:
+- `src/install.js`
+- `bin/cli.js`
+- `src/runtime/openclaw-gateway.js`
+
+Acceptance:
+- 缺失條件能在安裝前阻擋並提示修復方式
+- `npx -y clawpilot@latest install --yes ...` 在 CI/自動化可穩定執行
+- preflight 輸出含 machine-readable summary（供測試斷言）
+
+## M2: Upgrade/Reinstall + Config Centralization
+
+Target:
+- 已安裝狀態下，提供明確更新路徑，避免覆寫驚喜
+
+Tasks:
+- 偵測既有安裝，提供 `update / skip / reinstall` 分支（CLI 與 `--yes` 都可用）
+- 將 `delivery/channel/role-pack/runtime defaults` 集中到單一 config entry
+- 導入版本化配置遷移：
+  - 新增 `configSchemaVersion`
+  - 建立 `vN -> vN+1` migration table（可重複執行且結果一致）
+  - 保留未知欄位與使用者覆寫值
+
+Likely files:
+- `src/install.js`
+- `src/runtime/index.js`
+- `skill/manifest.json`
+
+Acceptance:
+- 重新安裝不會重複注入內容
+- 版本升級時保留使用者舊設定
+- migration 對同一份 config 執行兩次結果相同（idempotent）
+
+## M3: Delivery Error Taxonomy + Troubleshooting
+
+Target:
+- 送訊失敗時，能回傳可行動的錯誤資訊
+
+Tasks:
+- 建立錯誤分類：
+  - `gateway_missing`
+  - `gateway_unreachable`
+  - `auth_invalid`
+  - `channel_not_found`
+  - `permission_denied`
+  - `network_timeout`
+  - `invalid_payload`
+  - `rate_limited`
+  - `unknown`
+- 建立 stderr/status -> error code 映射規則（Regex + fallback）
+- CLI 失敗輸出標準化（`code + reason + one-line fix + docs link`）
+- `--json-errors` 輸出機制（給自動化與監控）
+- 新增 troubleshooting 文件與 FAQ
+
+Likely files:
+- `src/runtime/openclaw-gateway.js`
+- `src/runtime/index.js`
+- `README.md`
+- `docs/troubleshooting.md`（新檔，必要時由 `PUBLISH_CHECKLIST` 連結）
+
+Acceptance:
+- 常見失敗可在 1 次輸出內看懂原因與下一步
+- 測試覆蓋每個錯誤分類與映射分支
+
+## M4: One-Command Demo Path
+
+Target:
+- 新手可快速達成 first success，且避免誤發送
+
+Tasks:
+- 提供雙軌 demo script（PowerShell + Bash）：
+  - `demo-safe`: 安裝 + morning dry-run（不實送）
+  - `demo-send`: 實送流程，需 `--confirm` 或互動確認
+- README 加入 copy-paste 範例
+- demo 過程若缺設定，直接導向 M1 的引導式補齊流程
+
+Likely files:
+- `scripts/demo-safe.ps1`
+- `scripts/demo-safe.sh`
+- `scripts/demo-send.ps1`
+- `scripts/demo-send.sh`
+- `README.md`
+
+Acceptance:
+- 新使用者依 README 5 分鐘內可完成首次成功 dry-run
+- 有明確確認機制後可完成首次成功實送
+
+## 5) Optional Extension (Behind Feature Flag)
+
+主題：Image capability 接口化（不綁真人）
+
+- 僅新增 provider interface，不內建真人 prompt
+- 預設 persona 為 fictional K-style descriptors
+- 先支援 `--image-dry-run` 生成 prompt payload，不直接走付費 API
+
+## 6) Test Plan
+
+以 coverage matrix 為主，不以「測試數量」作為唯一指標。
+
+- Installer
+  - preflight fail/success matrix（CLI 缺失、無權限、壞 config、完整通過）
+  - `--yes` 缺值錯誤碼與訊息
+- Migration
+  - `update / skip / reinstall` 分支
+  - `configSchemaVersion` 遷移與 idempotency
+  - 舊設定保留（含未知欄位）
+- Runtime Delivery
+  - gateway error taxonomy mapping（所有錯誤碼）
+  - `--json-errors` 輸出格式穩定性
+- Demo/Docs
+  - script smoke checks（safe/send）
+  - README 指令與 `--help` 一致
+
+## 7) Release Plan
+
+- `v0.2.x` 維護：只收 bugfix
+- `v0.3.0-beta.1`：M1 + M2
+- `v0.3.0-beta.2`：M3 + M4
+- `v0.3.0`：穩定版發布
+
+Go/No-Go Gates（GA 前）：
+- 首次安裝成功率（fresh env）達既定門檻（建議 >= 90%）
+- Top 錯誤類型可被正確分類並給出修復指引（建議 >= 95%）
+- 回歸測試全綠，且無 P0/P1 已知問題
+
+Rollback 機制：
+- 若 beta 發現高嚴重度回歸，立即凍結新功能
+- 以 patch release 回復上一穩定行為並補 migration 修復腳本
+
+## 8) Risks and Mitigation
+
+- Risk: OpenClaw/Gateway 版本差異造成安裝邏輯不一致  
+  Mitigation: preflight 顯示偵測版本並提供最小版本提示
+
+- Risk: 互動流程讓自動化部署變慢  
+  Mitigation: `--yes` 保留完整無互動模式，並保證可機器可讀錯誤輸出
+
+- Risk: 錯誤訊息仍偏技術、使用者看不懂  
+  Mitigation: 錯誤輸出固定「原因 + 一行修復命令 + 文件連結」
+
+- Risk: config migration 破壞既有用戶設定  
+  Mitigation: migration idempotency test + unknown fields preservation + rollback plan
+
+## 9) Definition of Done
+
+- M1-M3 全數完成（必要項）
+- M4 完成，或以 issue 明確延期並提供替代 demo-safe 體驗
+- 測試全綠（含新增 matrix 測試）
+- README 與 CLI 行為一致
+- `npx clawpilot@latest install` 新手流程可跑通

package/docs/plans/2026-02-13-v0.3-implementation.md

@@ -0,0 +1,434 @@
+# Clawpilot v0.3 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 以最小風險完成 v0.3 gap 補齊，讓安裝、升級與送訊錯誤處理可預期且可觀測。  
+**Architecture:** 先補 installer preflight 與 config migration 基礎，再加上 gateway 錯誤分類與 CLI 統一錯誤輸出，最後補 demo 與文件。所有功能以 TDD 驅動，先寫失敗測試，再補最小實作。  
+**Tech Stack:** Node.js 18+, CommonJS, `node:test`, `node:assert/strict`, PowerShell/Bash scripts.
+
+---
+
+### Task 1: Preflight 檢查模組
+
+**Files:**
+- Create: `src/preflight.js`
+- Test: `test/preflight.test.cjs`
+- Modify: `src/install.js`
+
+**Step 1: Write the failing test**
+
+```js
+test('preflight returns gateway_missing when openclaw command is unavailable', () => {
+  const summary = runPreflight({
+    openClawHome: 'C:/tmp/.openclaw',
+    commandRunner: () => ({ status: 1, stderr: 'not found' }),
+    fsOps: fakeFsWithWritableDirs()
+  });
+  assert.equal(summary.ok, false);
+  assert.equal(summary.issues[0].code, 'gateway_missing');
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/preflight.test.cjs`  
+Expected: FAIL with `runPreflight is not a function` (or module not found).
+
+**Step 3: Write minimal implementation**
+
+```js
+function runPreflight({ openClawHome, commandRunner, fsOps }) {
+  const issues = [];
+  const cmd = commandRunner('openclaw', ['--version']);
+  if (cmd.status !== 0) issues.push({ code: 'gateway_missing', reason: 'openclaw unavailable' });
+  return { ok: issues.length === 0, issues };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/preflight.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/preflight.js test/preflight.test.cjs src/install.js
+git commit -m "feat: add installer preflight foundation"
+```
+
+### Task 2: 安裝流程接 preflight + `--yes` 明確錯誤
+
+**Files:**
+- Modify: `bin/cli.js`
+- Modify: `src/install.js`
+- Test: `test/cli-install-options.test.cjs`
+
+**Step 1: Write the failing test**
+
+```js
+test('install --yes fails with machine-readable code when preflight fails', () => {
+  const result = runCli(['install', '--yes'], { CLAWPILOT_TEST_FORCE_PREFLIGHT_FAIL: '1' });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /code: gateway_missing/i);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/cli-install-options.test.cjs`  
+Expected: FAIL because `code: gateway_missing` is not printed.
+
+**Step 3: Write minimal implementation**
+
+```js
+if (options.yes && !preflight.ok) {
+  throw new Error(`code: ${preflight.issues[0].code} fix: npm i -g openclaw`);
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/cli-install-options.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add bin/cli.js src/install.js test/cli-install-options.test.cjs
+git commit -m "feat: block install on preflight failure in --yes mode"
+```
+
+### Task 3: 版本化配置遷移 (`configSchemaVersion`)
+
+**Files:**
+- Create: `src/config/migrations.js`
+- Test: `test/config-migrations.test.cjs`
+- Modify: `src/install.js`
+
+**Step 1: Write the failing test**
+
+```js
+test('migrateConfig upgrades v1 to v2 and preserves unknown fields', () => {
+  const next = migrateConfig({ configSchemaVersion: 1, xCustom: true, skills: {} });
+  assert.equal(next.configSchemaVersion, 2);
+  assert.equal(next.xCustom, true);
+});
+
+test('migrateConfig is idempotent', () => {
+  const first = migrateConfig({ configSchemaVersion: 1, skills: {} });
+  const second = migrateConfig(first);
+  assert.deepEqual(second, first);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/config-migrations.test.cjs`  
+Expected: FAIL with `migrateConfig is not a function`.
+
+**Step 3: Write minimal implementation**
+
+```js
+function migrateConfig(input) {
+  const current = { ...input };
+  const from = current.configSchemaVersion || 1;
+  if (from < 2) current.configSchemaVersion = 2;
+  return current;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/config-migrations.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/config/migrations.js src/install.js test/config-migrations.test.cjs
+git commit -m "feat: add versioned config migration pipeline"
+```
+
+### Task 4: `update / skip / reinstall` 分支
+
+**Files:**
+- Modify: `bin/cli.js`
+- Modify: `src/install.js`
+- Test: `test/install-existing-behavior.test.cjs`
+
+**Step 1: Write the failing test**
+
+```js
+test('existing installation with --on-existing skip exits successfully without overwrite', async () => {
+  const result = await installSkill({ openClawHome: tmpHome, packageRoot: tmpPkg, onExisting: 'skip' });
+  assert.equal(result.action, 'skip');
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/install-existing-behavior.test.cjs`  
+Expected: FAIL because `onExisting` is unsupported.
+
+**Step 3: Write minimal implementation**
+
+```js
+if (fs.existsSync(skillDir)) {
+  if (onExisting === 'skip') return { action: 'skip', skillDir, configPath, workspaceSoulPath, identityPath };
+  if (onExisting === 'update') { /* no rm, only merge config+templates */ }
+  if (onExisting === 'reinstall') fs.rmSync(skillDir, { recursive: true, force: true });
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/install-existing-behavior.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add bin/cli.js src/install.js test/install-existing-behavior.test.cjs
+git commit -m "feat: support update skip reinstall install paths"
+```
+
+### Task 5: Gateway 錯誤分類與映射
+
+**Files:**
+- Modify: `src/runtime/openclaw-gateway.js`
+- Test: `test/openclaw-gateway.test.cjs`
+
+**Step 1: Write the failing test**
+
+```js
+test('maps ENOENT to gateway_missing', () => {
+  const err = classifyGatewayError({ status: 1, stderr: 'ENOENT openclaw' });
+  assert.equal(err.code, 'gateway_missing');
+});
+
+test('maps timeout text to network_timeout', () => {
+  const err = classifyGatewayError({ status: 1, stderr: 'ETIMEDOUT connect' });
+  assert.equal(err.code, 'network_timeout');
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/openclaw-gateway.test.cjs`  
+Expected: FAIL with `classifyGatewayError is not a function`.
+
+**Step 3: Write minimal implementation**
+
+```js
+function classifyGatewayError(result) {
+  const text = `${result.stderr || ''} ${result.stdout || ''}`;
+  if (/ENOENT|not found/i.test(text)) return { code: 'gateway_missing' };
+  if (/timed?out|ETIMEDOUT/i.test(text)) return { code: 'network_timeout' };
+  return { code: 'unknown' };
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/openclaw-gateway.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/runtime/openclaw-gateway.js test/openclaw-gateway.test.cjs
+git commit -m "feat: add gateway error taxonomy mapping"
+```
+
+### Task 6: CLI 統一錯誤輸出與 `--json-errors`
+
+**Files:**
+- Modify: `bin/cli.js`
+- Modify: `src/runtime/index.js`
+- Test: `test/cli-run-command.test.cjs`
+- Create: `test/cli-errors.test.cjs`
+
+**Step 1: Write the failing test**
+
+```js
+test('run outputs json error when --json-errors is enabled', () => {
+  const result = runCli(['run', '--command', 'morning', '--json-errors']);
+  const payload = JSON.parse(result.stderr);
+  assert.equal(payload.code, 'channel_required');
+  assert.match(payload.fix, /--channel/);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/cli-errors.test.cjs`  
+Expected: FAIL because CLI does not emit JSON errors.
+
+**Step 3: Write minimal implementation**
+
+```js
+catch (error) {
+  const normalized = normalizeCliError(error);
+  if (options.jsonErrors) process.stderr.write(`${JSON.stringify(normalized)}\n`);
+  else console.error(`${normalized.code}: ${normalized.reason}\nFix: ${normalized.fix}`);
+  process.exitCode = 1;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/cli-errors.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add bin/cli.js src/runtime/index.js test/cli-errors.test.cjs test/cli-run-command.test.cjs
+git commit -m "feat: standardize cli error output with json mode"
+```
+
+### Task 7: Troubleshooting 文件與 README 對齊
+
+**Files:**
+- Create: `docs/troubleshooting.md`
+- Modify: `README.md`
+- Modify: `docs/PUBLISH_CHECKLIST.md`
+- Test: `test/docs-smoke.test.cjs`
+
+**Step 1: Write the failing test**
+
+```js
+test('README references troubleshooting doc and json-errors flag', () => {
+  const readme = fs.readFileSync(path.join(__dirname, '..', 'README.md'), 'utf8');
+  assert.match(readme, /docs\/troubleshooting\.md/);
+  assert.match(readme, /--json-errors/);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/docs-smoke.test.cjs`  
+Expected: FAIL because references are missing.
+
+**Step 3: Write minimal implementation**
+
+```md
+## Troubleshooting
+- See `docs/troubleshooting.md`
+- Use `clawpilot run ... --json-errors` for machine-readable diagnostics
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/docs-smoke.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add README.md docs/troubleshooting.md docs/PUBLISH_CHECKLIST.md test/docs-smoke.test.cjs
+git commit -m "docs: add runtime troubleshooting and json error guidance"
+```
+
+### Task 8: Demo 腳本（safe/send）與 smoke 測試
+
+**Files:**
+- Create: `scripts/demo-safe.ps1`
+- Create: `scripts/demo-safe.sh`
+- Create: `scripts/demo-send.ps1`
+- Create: `scripts/demo-send.sh`
+- Create: `test/demo-scripts-smoke.test.cjs`
+- Modify: `README.md`
+
+**Step 1: Write the failing test**
+
+```js
+test('demo-safe scripts include --dry-run and never send media', () => {
+  const ps1 = fs.readFileSync(path.join(repo, 'scripts', 'demo-safe.ps1'), 'utf8');
+  assert.match(ps1, /--dry-run/);
+  assert.doesNotMatch(ps1, /openclaw message send/);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --test test/demo-scripts-smoke.test.cjs`  
+Expected: FAIL because scripts do not exist.
+
+**Step 3: Write minimal implementation**
+
+```bash
+# demo-safe.sh
+node bin/cli.js install --yes --timezone UTC
+node bin/cli.js run --command morning --dry-run --timezone UTC
+```
+
+```powershell
+# demo-send.ps1
+param([string]$Channel,[switch]$Confirm)
+if (-not $Confirm) { throw "Pass -Confirm to send" }
+node bin/cli.js run --command morning --channel $Channel --timezone UTC
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --test test/demo-scripts-smoke.test.cjs`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add scripts/demo-safe.ps1 scripts/demo-safe.sh scripts/demo-send.ps1 scripts/demo-send.sh test/demo-scripts-smoke.test.cjs README.md
+git commit -m "feat: add safe and confirmed send demo scripts"
+```
+
+### Task 9: 全量驗證與發布前檢查
+
+**Files:**
+- Modify: `package.json` (if adding script aliases)
+- Modify: `docs/plans/2026-02-13-v0.3-clawra-gap-plan.md` (status updates)
+
+**Step 1: Run full test suite**
+
+Run: `npm test`  
+Expected: PASS all tests.
+
+**Step 2: Smoke CLI behavior**
+
+Run: `node bin/cli.js --help`  
+Expected: Includes `--json-errors`, `--on-existing`, demo docs references.
+
+**Step 3: Validate README command examples**
+
+Run: `node --test test/docs-smoke.test.cjs`  
+Expected: PASS.
+
+**Step 4: Tag release readiness note**
+
+```md
+- v0.3.0-beta.1 gate: PASS (M1/M2)
+- v0.3.0-beta.2 gate: PASS (M3/M4)
+```
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-02-13-v0.3-clawra-gap-plan.md README.md package.json
+git commit -m "chore: prepare v0.3 release gates and validation notes"
+```
+
+## Execution Order
+
+1. Task 1 -> Task 2 (installer preflight path)
+2. Task 3 -> Task 4 (migration + existing install behavior)
+3. Task 5 -> Task 6 (runtime error taxonomy + CLI output)
+4. Task 7 -> Task 8 (docs + demo paths)
+5. Task 9 (final verification and release gate notes)
+
+## Non-Negotiable Checks
+
+- 每個 Task 先跑失敗測試，再寫最小實作，再回測。
+- 每次 commit 僅包含單一任務主題。
+- 不可跳過 `npm test` 與 docs smoke 測試。
+- 任何新增錯誤碼都必須在 `docs/troubleshooting.md` 出現。