Refresh settings page in realtime

docs/superpowers/plans/2026-04-07-settings-page-realtime.md

@@ -0,0 +1,99 @@
+# Settings Page Realtime Refresh Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 `/me/settings` 在用户设置变更后自动刷新。
+
+**Architecture:** 复用现有 `boss-events -> /api/v1/events -> RealtimeRefresh` SSE 链路，新增一个语义明确的 `settings.updated` 事件。`updateUserSettings` 写入文件状态后发布事件，设置页只监听这个事件。
+
+**Tech Stack:** Next.js App Router, TypeScript, Node test runner, SSE
+
+---
+
+### Task 1: 写红灯测试
+
+**Files:**
+- Create: `tests/settings-page-realtime-refresh.test.ts`
+- Create: `tests/settings-state-events.test.ts`
+
+- [ ] **Step 1: 写设置页接线测试**
+
+```ts
+assert.match(source, /<RealtimeRefresh/, "expected settings page to render RealtimeRefresh");
+assert.match(source, /events=\{\["settings\.updated"\]\}/, "expected settings page to refresh on settings.updated");
+```
+
+- [ ] **Step 2: 跑页面测试确认失败**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts`
+Expected: FAIL，因为设置页还没有接 `RealtimeRefresh`。
+
+- [ ] **Step 3: 写设置事件测试**
+
+```ts
+await updateUserSettings({ liveUpdates: false });
+assert.equal(events.at(-1)?.event, "settings.updated");
+```
+
+- [ ] **Step 4: 跑事件测试确认失败**
+
+Run: `npx tsx --test tests/settings-state-events.test.ts`
+Expected: FAIL，因为 `updateUserSettings` 还没有发布 `settings.updated`。
+
+### Task 2: 补实现
+
+**Files:**
+- Modify: `src/lib/boss-events.ts`
+- Modify: `src/lib/boss-data.ts`
+- Modify: `src/app/me/settings/page.tsx`
+
+- [ ] **Step 1: 扩展 `BossEventName`**
+
+```ts
+  | "settings.updated"
+```
+
+- [ ] **Step 2: 修改 `updateUserSettings` 发布事件**
+
+```ts
+publishBossEvent("settings.updated");
+```
+
+- [ ] **Step 3: 给设置页接入刷新**
+
+```tsx
+<RealtimeRefresh events={["settings.updated"]} />
+```
+
+- [ ] **Step 4: 跑本轮测试确认转绿**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts`
+Expected: PASS
+
+### Task 3: 验证与提交
+
+**Files:**
+- Test: `tests/settings-page-realtime-refresh.test.ts`
+- Test: `tests/settings-state-events.test.ts`
+
+- [ ] **Step 1: 跑相关 realtime 测试**
+
+Run: `npx tsx --test tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts tests/config-pages-realtime-refresh.test.ts tests/config-state-events.test.ts tests/realtime-refresh-utils.test.ts tests/project-scoped-realtime-refresh.test.ts tests/status-pages-realtime-refresh.test.ts`
+Expected: PASS
+
+- [ ] **Step 2: 跑 lint**
+
+Run: `npm run lint`
+Expected: exit code 0
+
+- [ ] **Step 3: 跑 build**
+
+Run: `npm run build`
+Expected: exit code 0
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add docs/superpowers/specs/2026-04-07-settings-page-realtime-design.md docs/superpowers/plans/2026-04-07-settings-page-realtime.md tests/settings-page-realtime-refresh.test.ts tests/settings-state-events.test.ts src/lib/boss-events.ts src/lib/boss-data.ts src/app/me/settings/page.tsx
+git commit -m "Refresh settings page in realtime"
+```

docs/superpowers/specs/2026-04-07-settings-page-realtime-design.md

@@ -0,0 +1,21 @@
+# 设置页实时刷新 Design
+
+## 目标
+
+让 Web 设置页 `/me/settings` 在用户设置被其他窗口或设备修改后自动刷新。
+
+## 范围
+
+本轮只处理设置页：
+
+- 新增 `settings.updated` SSE 事件
+- `updateUserSettings` 写入成功后发布 `settings.updated`
+- `/me/settings` 页面通过 `RealtimeRefresh` 监听 `settings.updated`
+
+不处理 `devices/add`、`me/security` 和根重定向页；这些页面没有同等价值的实时刷新需求。
+
+## 验证
+
+- 页面接线测试确认设置页渲染 `RealtimeRefresh` 并监听 `settings.updated`
+- 状态事件测试确认 `updateUserSettings` 会发布 `settings.updated`
+- 跑相关 realtime 测试、`npm run lint`、`npm run build`