coding-tool-x 3.8.3 → 3.8.5

package/docs/superpowers/plans/2026-09-01-omp-skill-refresh-boundary.md

@@ -0,0 +1,213 @@
+# OMP Skill Refresh Boundary 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:** Make the OMP Skill panel's local scan path explicit and ensure only the manual “刷新远端” action can enqueue a remote Skill refresh.
+
+**Architecture:** Keep the existing scan/refresh API split. Rename the generic `SkillsPanel.vue` list-loading operation to `scanLocalSkills`, route every lifecycle/update callback through it, and leave `handleRefresh` as the only caller of `refreshSkills`. Preserve the existing server GET scan-only contract and lock it with an OMP-specific API test; rebuild the ignored Web bundle for deployment verification.
+
+**Tech Stack:** Vue 3 `<script setup>`, Vitest, Vue Test Utils, Express, Supertest, Vite, Node.js.
+
+---
+
+### Task 1: Lock OMP panel scan-only lifecycle
+
+**Files:**
+- Modify: `src/web/src/components/__tests__/SkillsPanelSwitch.test.js`
+- Modify: `src/web/src/components/SkillsPanel.vue:260-286,297,430,454,468-486`
+
+- [ ] **Step 1: Extend the frontend test fixture to include OMP**
+
+Add OMP to the mocked platform catalog and retain the existing `getSkills`, `refreshSkills`, and task mocks. Add a helper that mounts the real `SkillsPanel` with explicit OMP props:
+
+```js
+async function createOmpWrapper(props = {}) {
+  const { default: SkillsPanel } = await import('../SkillsPanel.vue')
+  return mount(SkillsPanel, {
+    props: { platform: 'omp', ...props },
+    global: {
+      stubs: {
+        SkillCard: { template: '<div />' },
+        SkillRepoManager: { template: '<div />' },
+        SkillCreateModal: { template: '<div />' },
+        SkillDetailDrawer: { template: '<div />' },
+        OmpSkillSettingsModal: { template: '<div />' }
+      }
+    }
+  })
+}
+```
+
+- [ ] **Step 2: Add the OMP mount and drawer-open regression assertions**
+
+Add tests that exercise both initial standalone rendering and a hidden-then-visible drawer. The assertions must distinguish a local GET scan from the remote refresh command:
+
+```js
+test.each([
+  { inDrawer: false, drawerVisible: false },
+  { inDrawer: true, drawerVisible: true }
+])('OMP panel load scans local state without remote refresh (%o)', async props => {
+  const wrapper = await createOmpWrapper(props)
+  await flushPromises()
+
+  expect(api.getSkills).toHaveBeenCalledWith('omp', {})
+  expect(api.refreshSkills).not.toHaveBeenCalled()
+  wrapper.unmount()
+})
+
+test('opening a hidden OMP drawer scans once without enqueuing refresh', async () => {
+  const wrapper = await createOmpWrapper({ inDrawer: true, drawerVisible: false })
+  await flushPromises()
+  expect(api.getSkills).not.toHaveBeenCalled()
+
+  await wrapper.setProps({ drawerVisible: true })
+  await flushPromises()
+
+  expect(api.getSkills).toHaveBeenCalledWith('omp', {})
+  expect(api.refreshSkills).not.toHaveBeenCalled()
+  wrapper.unmount()
+})
+```
+
+Run before the production rename:
+
+```bash
+npm run test:unit -- --run src/components/__tests__/SkillsPanelSwitch.test.js
+```
+
+Expected baseline: the existing source's scan-only behavior remains green; this is a regression characterization because the reported behavior is not reproducible in the checked-out source. Do not change the assertions to force a false failure.
+
+- [ ] **Step 3: Rename the generic loader to make the boundary explicit**
+
+In `src/web/src/components/SkillsPanel.vue`, rename `loadData` to `scanLocalSkills` and update every non-refresh reference:
+
+```js
+async function scanLocalSkills({ notifyError = true } = {}) {
+  // Keep the existing request-id, platform/scope checks, GET getSkills call,
+  // response validation, state assignment, and error handling unchanged.
+}
+```
+
+Update these call sites to `scanLocalSkills`:
+
+- `SkillRepoManager @updated`;
+- `SkillCreateModal @created`;
+- `SkillDetailDrawer @updated`;
+- `handleImport` completion;
+- `handleRefresh` completion after task polling;
+- `handleOmpSettingsSaved` passed callback;
+- standalone `onMounted` load;
+- `drawerVisible` watcher;
+- platform/scope/project-path watcher.
+
+Keep `handleRefresh` unchanged in responsibility: it alone calls `refreshSkills(platform, scopeOptions.value)`, polls `getSkillRefreshTask`, and calls `scanLocalSkills()` after a terminal task. No lifecycle callback may call `refreshSkills` or pass a boolean force argument.
+
+- [ ] **Step 4: Re-run the focused frontend tests**
+
+Run:
+
+```bash
+npm run test:unit -- --run src/components/__tests__/SkillsPanelSwitch.test.js
+```
+
+Expected: all tests pass; the OMP mount/open cases show `getSkills('omp', {})` and zero `refreshSkills` calls.
+
+- [ ] **Step 5: Commit the frontend boundary change**
+
+```bash
+git add src/web/src/components/SkillsPanel.vue src/web/src/components/__tests__/SkillsPanelSwitch.test.js
+git commit -m "fix: keep OMP skill panel scans local"
+```
+
+---
+
+### Task 2: Lock the server scan-only contract for OMP
+
+**Files:**
+- Modify: `tests/unit/api/skills-api.test.js:718-750`
+- Verify only: `src/server/api/skills.js:145-209`
+
+- [ ] **Step 1: Add an OMP-specific GET regression test**
+
+Within `describe('new Skill control surface')`, add a test using the existing injected service fixture:
+
+```js
+test('OMP GET ignores refresh query and never starts remote work', async () => {
+  const ompService = services.omp
+  ompService.scanSkills = vi.fn(async () => ({
+    skills: [{ name: 'omp-local', enabled: false, cached: true, managed: true }],
+    refresh: { state: 'never_fetched', taskId: null, fetchedAt: null, error: null }
+  }))
+  ompService.refreshRemoteSkills = vi.fn()
+
+  const app = buildInjectedApp({
+    controlService: { setSkillEnabled: vi.fn() },
+    refreshTasks: { enqueue: vi.fn(), get: vi.fn() }
+  })
+  const res = await request(app).get('/?platform=omp&refresh=1')
+
+  expect(res.status).toBe(200)
+  expect(ompService.scanSkills).toHaveBeenCalledWith({ scope: 'user' })
+  expect(ompService.refreshRemoteSkills).not.toHaveBeenCalled()
+})
+```
+
+- [ ] **Step 2: Run the server regression test before any server edit**
+
+Run:
+
+```bash
+npm exec -- vitest run tests/unit/api/skills-api.test.js -t "OMP GET ignores refresh query and never starts remote work"
+```
+
+Expected baseline: PASS, confirming the server boundary is already correct in the checked-out source. No server production change is required unless this test exposes a regression.
+
+- [ ] **Step 3: Commit the server contract test**
+
+```bash
+git add tests/unit/api/skills-api.test.js
+git commit -m "test: cover OMP scan-only skill listing"
+```
+
+---
+
+### Task 3: Rebuild and verify the deployed behavior
+
+**Files:**
+- Modify generated ignored output: `dist/web/` (via the existing build command; do not stage it)
+
+- [ ] **Step 1: Run focused frontend and server tests together**
+
+```bash
+npm run test:unit -- --run src/components/__tests__/SkillsPanelSwitch.test.js
+npm exec -- vitest run tests/unit/api/skills-api.test.js tests/unit/services/skill-service.test.js -t "OMP GET ignores refresh query and never starts remote work|scanSkills never performs a network refresh|scanSkills does not refresh remote OMP repositories"
+```
+
+Expected: all selected tests pass, with no `POST /skills/refresh` on panel mount/open paths.
+
+- [ ] **Step 2: Rebuild the production Web bundle**
+
+```bash
+npm run build:web
+```
+
+Expected: Vite completes successfully and the generated bundle contains the scan-only `GET /skills` request path; `refreshSkills` remains reachable only from the explicit refresh handler.
+
+- [ ] **Step 3: Run the original browser smoke scenario**
+
+Use the actual Web UI to:
+
+1. open `/cli/omp`;
+2. open the Skills drawer;
+3. record API requests during each action.
+
+Expected: panel load/open produces `GET /api/skills?platform=omp&scope=user` and no `POST /api/skills/refresh`. The existing independent `GET /api/channel-balances?source=omp` balance probe is not part of this Skill-refresh assertion.
+
+- [ ] **Step 4: Commit only tracked source/test changes and report deployment requirement**
+
+```bash
+git status --short
+git log -2 --oneline
+```
+
+Expected: only the pre-existing untracked `.omx/` and `.worktrees/` entries remain outside the two task commits. Deployment must rebuild `dist/` and restart any existing backend process; a stale process or stale packaged bundle can retain the old behavior even when source tests pass.

package/docs/superpowers/plans/2026-09-01-realtime-logs-panel.md

@@ -0,0 +1,125 @@
+# 实时日志面板空白修复 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:** 修复渠道管理页未渲染 `ProxyLogs` 导致实时日志区域空白的问题。
+
+**Architecture:** 保持现有日志数据流和组件边界不变，仅在 `RightPanel.vue` 显式导入其模板使用的 `ProxyLogs.vue`。使用仓库已有的静态前端组件测试模式增加回归断言，并通过前端构建和真实页面冒烟验证渲染结果。
+
+**Tech Stack:** Vue 3 `<script setup>`、Vite、Vitest、Node.js。
+
+---
+
+### Task 1: Add regression coverage for component registration
+
+**Files:**
+- Modify: `tests/unit/web/log-components.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+在现有 `describe('web log components source routing', ...)` 中追加：
+
+```js
+test('RightPanel registers the ProxyLogs component used by its template', () => {
+  const source = readProjectFile('src/web/src/components/RightPanel.vue')
+
+  expect(source).toContain("import ProxyLogs from './ProxyLogs.vue'")
+  expect(source).toContain('<ProxyLogs :source="currentChannel" />')
+})
+```
+
+- [ ] **Step 2: Run the focused test and verify it fails**
+
+Run from repository root:
+
+```bash
+npx vitest run tests/unit/web/log-components.test.js
+```
+
+Expected: the new test fails because `RightPanel.vue` currently has no `ProxyLogs` import.
+
+- [ ] **Step 3: Confirm failure is the intended regression**
+
+The failure must identify the missing import assertion, not a test parse/setup error. Do not change production code before this failure is observed.
+
+### Task 2: Register and render the existing log component
+
+**Files:**
+- Modify: `src/web/src/components/RightPanel.vue:147-152`
+
+- [ ] **Step 1: Add the minimal import**
+
+Add the import alongside the other channel panel imports:
+
+```js
+import ProxyLogs from './ProxyLogs.vue'
+```
+
+Do not change the existing template binding:
+
+```vue
+<ProxyLogs :source="currentChannel" />
+```
+
+Do not modify `ProxyLogs.vue`, WebSocket handling, Pinia state, statistics APIs, or layout CSS.
+
+- [ ] **Step 2: Run the focused regression test**
+
+```bash
+npx vitest run tests/unit/web/log-components.test.js
+```
+
+Expected: all tests in this file pass.
+
+- [ ] **Step 3: Build the frontend**
+
+```bash
+npm run build:web
+```
+
+Expected: Vite completes successfully without unresolved component warnings or build errors.
+
+### Task 3: Verify the real channel-management surface
+
+**Files:**
+- No source changes.
+
+- [ ] **Step 1: Open the running local application**
+
+Use the existing local service at `http://localhost:19999` and navigate to:
+
+```text
+http://localhost:19999/cli/omp
+```
+
+- [ ] **Step 2: Verify the rendered log panel**
+
+Confirm the right panel contains:
+
+- `实时日志`
+- the table header (`渠道`, `请求`, `回复`, platform-specific columns, `时间`)
+- either existing log rows or `暂无日志`
+- the connection status footer
+
+The `.logs-section` must contain rendered `.proxy-logs` content rather than an unresolved `<proxylogs>` custom element.
+
+- [ ] **Step 3: Verify the changed contract after build**
+
+Refresh the page and repeat the check on at least one other channel route, such as `/cli/codex` or `/cli/claude`. Existing dashboard log behavior must remain intact.
+
+### Task 4: Final review and cleanup
+
+**Files:**
+- Review only: `src/web/src/components/RightPanel.vue`, `tests/unit/web/log-components.test.js`
+
+- [ ] **Step 1: Inspect the final diff**
+
+Confirm only the intended import and regression test are present, and existing user modifications remain untouched.
+
+- [ ] **Step 2: Run the focused test once more**
+
+```bash
+npx vitest run tests/unit/web/log-components.test.js
+```
+
+Expected: PASS.

package/docs/superpowers/plans/2026-09-02-config-driven-platform-boundary.md

@@ -0,0 +1,86 @@
+# 配置化平台边界实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** 删除平台专属 API 和项目配置适配器目录，把平台业务收敛到 Driver，把跨平台核心工具收敛到 `src/shared`。
+
+**Architecture:** 保留一个通用 platform API route factory，使用 manifest 的 aliases、capabilities 和 route definitions 生成旧 URL；Driver 提供平台操作和校验。`src/server` 只保留 HTTP 注册、请求响应转换、通用服务与基础设施；`src/platforms/drivers/<platform>` 不创建 shared 子目录。
+
+**Tech Stack:** Node.js 22、CommonJS、Express、Vitest、现有 Registry/Runtime/manifest loader。
+
+---
+
+### Task 1: 搬迁共享项目配置核心
+
+**Files:**
+- Create: `src/shared/project-config.js`
+- Modify: `src/server/services/project-config-service.js`
+- Modify: `src/server/services/mcp-service.js`
+- Modify: `src/server/services/config-templates-service.js`
+- Modify: `src/server/services/config-sync-manager.js`
+- Modify: `src/server/services/skill-service.js`
+- Modify: `src/server/services/skill-projection-service.js`
+- Modify: `src/server/api/mcp.js`
+- Create/modify: `src/platforms/drivers/{claude,codex,gemini,opencode,omp}/project-config.js`
+- Delete: `src/server/services/project-config-adapters/`
+- Test: affected project-config and MCP tests
+
+- [ ] 将 `project-config-adapters/shared.js` 的通用路径安全、JSON/TOML 原子读写、MCP patch、secret 脱敏函数搬到 `src/shared/project-config.js`，只修正相对 import。
+- [ ] 将五个平台 adapter 搬到对应 Driver 的 `project-config.js`，导出相同 `createAdapter`，平台格式仅由 Driver 自身实现。
+- [ ] 修改 `ProjectConfigService`，从 Runtime/manifest 获取 `projectConfig` Driver，不再维护 `FACTORIES` 和旧目录路径。
+- [ ] 将通用服务和 API 的 shared import 统一改为 `src/shared/project-config`。
+- [ ] 删除旧 `project-config-adapters` 目录。
+- [ ] 运行 `npx vitest run tests/unit/services/project-config-service.test.js tests/unit/services/mcp-service.test.js tests/unit/api/project-config.test.js --no-file-parallelism --maxWorkers=1`。
+
+### Task 2: 建立配置化平台 API 路由描述
+
+**Files:**
+- Create: `src/server/api/platform-api-config.js`
+- Modify: `src/platforms/manifest-schema.js`
+- Modify: `src/platforms/manifests/*.json`
+- Modify: `src/platforms/drivers/legacy.js`
+- Modify: `src/server/api/platform-route-factory.js`
+- Test: platform registry and route factory tests
+
+- [ ] 为 manifest 增加可选 `api` 描述，包含平台旧 URL alias 和 capability route operation；schema 严格校验 path、method、capability、operation。
+- [ ] 把各平台共同的 projects、sessions、channels、proxy、statistics 路由整理成一份配置，不复制五份 Express route 文件。
+- [ ] 在 route factory 中统一解析 platform、project、session、channel 参数，调用 Runtime Driver，并统一映射 `ok/unsupported/invalid/failed`。
+- [ ] 将仅平台不同的参数名、安装检测、默认值和校验作为 Driver operation 或 manifest data，不在路由 factory 中写平台分支。
+- [ ] 为旧 `/api/channels`、`/api/codex/...`、`/api/gemini/...`、`/api/opencode/...`、`/api/omp/...` 注册 aliases。
+- [ ] 添加未知平台、unsupported capability、Driver error 和旧 URL 等价响应测试。
+
+### Task 3: 将平台 API 业务下沉到 Driver
+
+**Files:**
+- Create: `src/platforms/drivers/{claude,codex,gemini,opencode,omp}/api-operations.js`
+- Modify: corresponding channel/proxy/session/statistics/config Driver files
+- Modify: `src/server/index.js`
+- Delete: platform-specific files under `src/server/api/`
+- Modify: API tests to exercise generic router and old aliases
+
+- [ ] 从平台 API 文件提取 provider 校验、CLI 安装检测、默认模型、speed-test、native config、session operation 和 platform DTO 到对应 `api-operations.js` 或现有 capability Driver。
+- [ ] 保持旧请求参数和响应格式，由 operation adapter 生成兼容 DTO；通用路由只负责调用和输出。
+- [ ] 让每个平台 Driver 暴露相同 operation names，不支持的 operation 返回结构化 `unsupported`。
+- [ ] 用一个通用 router 替换 server index 中的平台 API require/mount 列表。
+- [ ] 删除 `codex-channels.js`、`gemini-channels.js`、`opencode-channels.js`、`omp-channels.js`、各平台 proxy/projects/sessions/statistics API 文件及不再需要的单独路由目录。
+- [ ] 保留真正通用的 `platform-route-factory.js`、validation、response 和 websocket 基础设施。
+
+### Task 4: 清理引用和迁移测试
+
+**Files:**
+- Modify: all production imports of deleted API/config adapter paths
+- Modify: tests under `tests/unit/api`, `tests/unit/services`, `tests/unit/platforms`
+- Delete: tests that only assert deleted platform route modules
+
+- [ ] 全局搜索并消除 `src/server/api/<platform>-*.js` 和 `src/server/services/project-config-adapters` 的生产及测试引用。
+- [ ] 将 require.cache mock seam 改为 generic router 或 Driver operation seam。
+- [ ] 删除仅覆盖重复路由实现的测试，保留每个平台的行为 contract test。
+- [ ] 检查 `src/platforms/drivers` 不存在 `shared` 子目录。
+
+### Task 5: 完整验证与提交
+
+- [ ] 运行所有 API、Driver、项目配置和 CLI 相关测试。
+- [ ] 运行完整 `npx vitest run tests/unit --no-file-parallelism --maxWorkers=1 --testTimeout=30000`。
+- [ ] 运行所有平台 capability Driver 加载冒烟和 `git diff --check`。
+- [ ] 检查工作树无测试生成数据库差异。
+- [ ] 提交：`refactor: make platform APIs configuration-driven`。