cicy-desktop 2.1.237 → 2.1.239

package/docs/REST-API.md

@@ -1,276 +0,0 @@
-# REST API
-
-This document describes the current HTTP API exposed by the CiCy Desktop worker.
-
-Source of truth:
-- worker entry: `src/main.js`
-- OpenAPI/docs routes: `src/server/express-app.js`
-
-## Endpoint summary
-
-### Public endpoints
-
-These do **not** require auth:
-
-- `GET /ping` — basic health check
-- `GET /docs` — Swagger-style API UI
-- `GET /openapi.json` — generated OpenAPI spec
-
-### Authenticated RPC endpoints
-
-These **do** require auth:
-
-- `GET /rpc/tools`
-- `POST /rpc/tools/call`
-- `POST /rpc/:toolName`
-- `POST /rpc/upload/*`
-- `POST /rpc/exec/:type`
-- `GET /files`
-- `GET /api/worker`
-- `GET /api/agents`
-- `GET /api/artifacts`
-
-## Authentication
-
-Authenticated routes expect:
-
-```http
-Authorization: Bearer <token>
-```
-
-Tokens are usually stored in `~/global.json` and are the same tokens used by `cicy-rpc`.
-
-If auth fails, the worker responds with:
-
-```json
-{
-  "error": "Unauthorized"
-}
-```
-
-## Core RPC routes
-
-### `GET /rpc/tools`
-
-Returns the current tool catalog.
-
-Example:
-
-```bash
-curl http://localhost:8101/rpc/tools \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-JSON response shape:
-
-```json
-{
-  "tools": [
-    {
-      "name": "open_window",
-      "description": "...",
-      "inputSchema": {
-        "type": "object"
-      }
-    }
-  ]
-}
-```
-
-YAML is also supported by setting:
-
-```http
-Accept: application/yaml
-```
-
-### `POST /rpc/tools/call`
-
-Calls a tool by name using a generic wrapper endpoint.
-
-Example:
-
-```bash
-curl -X POST http://localhost:8101/rpc/tools/call \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "open_window",
-    "arguments": {
-      "url": "https://example.com"
-    }
-  }'
-```
-
-Request shape:
-
-```json
-{
-  "name": "tool_name",
-  "arguments": {
-    "key": "value"
-  }
-}
-```
-
-### `POST /rpc/:toolName`
-
-Calls a tool directly.
-
-Example:
-
-```bash
-curl -X POST http://localhost:8101/rpc/open_window \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://example.com",
-    "accountIdx": 0
-  }'
-```
-
-This is the simplest REST form when you already know the tool name.
-
-## Response format
-
-Successful tool responses are wrapped like this:
-
-```json
-{
-  "result": {
-    "content": [
-      {
-        "type": "text",
-        "text": "Pong"
-      }
-    ]
-  }
-}
-```
-
-Some tools return text content, some return structured JSON encoded in text, and some may return image content.
-
-If the client sends:
-
-```http
-Accept: application/yaml
-```
-
-then tool responses are returned as YAML.
-
-## JSON and YAML support
-
-Current worker behavior:
-
-- `GET /rpc/tools` supports JSON and YAML output via `Accept`
-- `POST /rpc/tools/call` accepts JSON, and also accepts YAML when `Content-Type: application/yaml`
-- `POST /rpc/:toolName` accepts JSON, and also accepts YAML when `Content-Type: application/yaml`
-- tool responses can be returned as YAML when `Accept: application/yaml`
-
-Example YAML tool call:
-
-```bash
-curl -X POST http://localhost:8101/rpc/exec_js \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/yaml" \
-  -H "Accept: application/yaml" \
-  --data-binary $'win_id: 1\ncode: document.title\n'
-```
-
-## Common examples
-
-### Health check
-
-```bash
-curl http://localhost:8101/ping
-```
-
-### Ping tool
-
-```bash
-curl -X POST http://localhost:8101/rpc/ping \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{}'
-```
-
-### Get windows
-
-```bash
-curl -X POST http://localhost:8101/rpc/get_windows \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{}'
-```
-
-### Open a window
-
-```bash
-curl -X POST http://localhost:8101/rpc/open_window \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://example.com",
-    "accountIdx": 0,
-    "reuseWindow": true
-  }'
-```
-
-### Execute JavaScript
-
-```bash
-curl -X POST http://localhost:8101/rpc/exec_js \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "win_id": 1,
-    "code": "document.title"
-  }'
-```
-
-## OpenAPI and interactive docs
-
-The worker serves generated API docs directly:
-
-- `GET /docs`
-- `GET /openapi.json`
-
-Examples:
-
-```bash
-open http://localhost:8101/docs
-curl http://localhost:8101/openapi.json
-```
-
-## Errors
-
-### 401 Unauthorized
-
-```json
-{
-  "error": "Unauthorized"
-}
-```
-
-### 400 Invalid YAML
-
-```json
-{
-  "error": "Invalid YAML: ..."
-}
-```
-
-### 500 Tool execution error
-
-```json
-{
-  "error": "..."
-}
-```
-
-If a tool raises a Zod validation error, the worker returns a `result` payload with `isError: true` instead of a generic HTTP 500.
-
-## Related docs
-
-- [Root README](../README.md)
-- [CLI split](../skills/cicy-cli/README.md)
-- [RPC CLI README](../packages/cicy-rpc/README.md)

package/docs/backend-selector-design.md

@@ -1,204 +0,0 @@
-# Backend Selector — Design
-
-Status: **draft for review**. Source of truth for `src/backends/` and the
-multi-window backend model. Adopted from the Genymotion shape: the desktop is
-a launcher / shell; the real environments (local sidecar, cloud cicy-code
-instances) live behind it as switchable backends.
-
-## Vision
-
-One installable `cicy-desktop`. After launch the user lands on a **Launcher**
-window listing every backend they can reach:
-
-- **Local** — bundled `cicy-code` daemon spawned by the sidecar (already
-  wired). Always present, always single instance.
-- **Cloud (catalog)** — instances the user owns on cicy-ai.com. Populated
-  by the cloud catalog API once it exists. (Phase 2)
-- **Manual** — arbitrary URL + token the user pasted in. Lives forever
-  in the local registry until removed.
-
-Each backend opens in its own `BrowserWindow`. Multiple windows can coexist
-targeting different backends (one local + two cloud, etc.). Closing the last
-local window keeps the sidecar running; quitting the app stops it.
-
-## Phases
-
-| Phase | Scope | Blockers |
-|-------|-------|----------|
-| **1** | Local sidecar + manual backends + multi-window + native HTML launcher | none |
-| **2** | Cloud catalog: login to cicy-ai.com, pull "my instances", auto-add to registry | cicy-ai.com catalog endpoint must exist |
-| **3** | Polish: per-window status pill, reconnect button, backend health monitor, drag-reorder | none, can be incremental |
-
-## Phase 1 — detailed design
-
-### Data model
-
-```ts
-type Backend = {
-  id: string;             // uuid; "local" reserved for the sidecar entry
-  name: string;           // user-visible label
-  kind: "local" | "manual";  // Phase 2 adds "cloud"
-  url: string;            // base URL (no token); for local = http://127.0.0.1:8008
-  token?: string;         // bearer; absent for local (sidecar reads ~/global.json itself)
-  addedAt: string;        // ISO timestamp
-  lastUsedAt?: string;
-};
-```
-
-Persistence: `<userData>/backends.json`, written atomically. Schema versioned
-in a top-level `{ "version": 1, "backends": [...] }` envelope.
-
-The `local` entry is **auto-upserted** on every startup so the user cannot
-accidentally delete it; the Manage dialog hides the delete button for `local`.
-
-### Modules
-
-```
-src/backends/
-  registry.js       # BackendRegistry — file-backed CRUD + auto-upsert local
-  window-manager.js # openWindowForBackend / closeAll / focus
-  launcher.html     # native HTML launcher (no React)
-  launcher.js       # launcher window's IPC + render logic (renderer-side)
-  ipc.js            # main-side IPC handlers backends:list / add / remove / open
-```
-
-### Sidecar lifecycle changes (small)
-
-`src/sidecar/cicy-code.js` already starts on `whenReady`. Phase 1 keeps that —
-the sidecar starts unconditionally on app launch so the local backend is
-"warm." When the catalog API ships (Phase 2) and the user wants to skip the
-local sidecar entirely, we'll add `--no-sidecar` and a per-launcher toggle.
-
-No multi-spawn risk: `sidecar.start()` already early-returns when `child` is
-non-null or when `:8008` already has a listener.
-
-### UI flows
-
-**On launch.** No START_URL set → open launcher window (loads
-`backends/launcher.html`). The launcher renders the registry list and
-provides "Open", "+ Add backend", "Manage".
-
-If a `--backend <id>` argv is present, skip the launcher and open that
-backend directly. (Lets the existing `cicy-dektop.command` Desktop launcher
-keep its "always open my default" behavior.)
-
-**Open Window.** From launcher or menu → `backends.open(id)` IPC →
-`window-manager.openWindowForBackend(backend)`:
-
-- For `local`: await `sidecar.start()`, then `createWindow({ url: <sidecar URL with token from ~/global.json> })`. URL identical to the current single-window default.
-- For `manual` / `cloud`: `createWindow({ url: \`${backend.url}/console/chrome?token=${backend.token}\` })`. Token is injected at the URL level; window has no other env coupling.
-
-Each window gets a `Window.backendId` attached (via a `WeakMap` keyed on the
-BrowserWindow). On close, the entry is removed.
-
-**Add backend.** Form fields: name, URL, token. Validates URL parses, probes
-`<url>/health` with the token, on success writes to registry + refreshes
-list. No probe → still saves (offline edit).
-
-**Manage.** Lists all non-`local` entries with delete button. Local entry
-shown read-only at the top.
-
-### IPC contract
-
-```
-backends:list      → Backend[]
-backends:add       (input: {name, url, token, kind:"manual"})  → Backend
-backends:remove    (id: string)  → boolean
-backends:open      (id: string)  → {windowId: number}
-backends:probe     ({url, token}) → {ok: bool, version?: string}
-```
-
-All registered in `src/backends/ipc.js`; exposed to the launcher renderer
-via `contextBridge` in a small preload.
-
-### Menu changes
-
-```
-File
-  New Local Window           Cmd+N
-  Open Backend Window…       Cmd+Shift+N    → launcher
-  Manage Backends…
-  ----
-  Quit
-```
-
-### Sequence: app cold start with no argv
-
-```
-electronApp.whenReady
-  ├─ ensureDesktopLauncher (existing)
-  ├─ sidecarCicyCode.start (existing)
-  ├─ server.listen 8101 (existing MCP)
-  └─ openLauncherWindow()    ← new (replaces auto-createWindow(START_URL))
-       └─ user clicks "Open" on a backend
-           → windowManager.openWindowForBackend(backend)
-               → BrowserWindow loading backend URL
-```
-
-Existing behavior preserved: if `START_URL` env / argv is set, skip launcher
-and open it directly (keeps `node bin/cicy-desktop --url …` working).
-
-## Phase 2 — cloud catalog (sketch only)
-
-Once cicy-ai.com exposes:
-
-```
-GET https://cicy-ai.com/v1/instances   (auth: Bearer <user token>)
-→ { instances: [ { id, name, url, token, region, ... } ] }
-```
-
-we add:
-
-- `src/auth/cicy-ai.js` — OAuth or token-paste flow against cicy-ai.com,
-  stores user token in `<userData>/cicy-ai-auth.json` (mode 0600).
-- `BackendRegistry.refreshFromCloud()` — pulls /v1/instances, upserts
-  entries with `kind: "cloud"`. Removes cloud entries that disappeared.
-- Launcher gains a "Sign in to cicy-ai.com" button + "Refresh" action.
-
-Cloud backends differ from manual only in:
-- They can be re-fetched and updated automatically.
-- Manage shows them read-only (server is the source of truth).
-
-## Phase 3 — polish
-
-- Window title bar shows backend name + green/red dot for health (200 on
-  `<url>/health` within 5 s).
-- "Reconnect" menu action for the active window.
-- Background poller: every 30 s probe each backend with a listening window
-  open; surface disconnects as a notification.
-- Launcher: drag to reorder, search box, group by kind.
-
-## Open questions
-
-1. **Default backend on first launch.** Open launcher window, or auto-open
-   the local backend (current behavior)? Lean toward launcher so the user
-   sees their list immediately, but a "Open local by default" preference
-   keeps the one-click path for power users.
-2. **Sidecar autostart toggle.** When the user wants to use cloud-only and
-   the local sidecar wastes resources. Adding `prefs.sidecarAutostart` is
-   trivial; defer until someone asks.
-3. **Per-backend window preferences.** Window position, zoom, devtools
-   state — currently keyed on URL by `WindowState`. Re-keying on backendId
-   would survive URL token rotation but is more code. Defer to Phase 3.
-4. **Master/Worker cluster integration.** `src/master/` + `src/cluster/`
-   currently treat the desktop as a worker registering to a master. That
-   is **orthogonal** to backend selection; both can coexist. Worth
-   re-evaluating in Phase 3 whether the cluster code is still needed at
-   all once cloud catalog covers fleet view.
-
-## Out of scope
-
-- Auto-update / version-pin per backend.
-- Backend-specific code-signing chains.
-- Cross-machine session sync.
-- Replacing the existing `src/master/` admin UI.
-
-## Next concrete steps once approved
-
-1. `src/backends/registry.js` + tests.
-2. `src/backends/ipc.js` + `window-manager.js`.
-3. `src/backends/launcher.html` + launcher renderer.
-4. Wire menu items + initial-launch behavior into `src/main.js`.
-5. Manual smoke: launch app → see launcher → open local → opens window →
-   add a fake manual backend pointing at the same local URL → open second
-   window → verify both windows render the chrome console independently.

package/docs/chrome-proxy.md

@@ -1,142 +0,0 @@
-# Worker Chrome HTTP 代理路由（/chrome）说明文档
-
-## 背景 / 目标
-
-现状：worker 的 HTTP 服务端口（例如 8101）已承载 REST/RPC（`/rpc/*`），但各 Chrome profile 的 CDP 实际监听在各自的本地 debugger port（例如 11001）。外部目前只能通过 `/rpc/chrome_*` 工具间接操作，无法通过 worker 的稳定入口直接访问 Chrome 的常用 HTTP 端点（如 `/json/version`、`/json/list`、`/json/activate/*`）或发起任意 CDP method call。
-
-目标：在不改变现有 `/rpc/:toolName` 调用方式的前提下，新增 worker 侧 HTTP 路由，让外部可以通过统一的 8101（或 worker 实际监听端口）入口，按 `accountIdx` 路由到对应 profile 的 debugger port。
-
-## 新增能力（HTTP 路由）
-
-以下路由均挂载在 worker 的 HTTP 服务下，并与 `/rpc/*` 一样受 `authMiddleware` 保护（Bearer token）。
-
-- `GET /chrome/:accountIdx/json/version`
-- `GET /chrome/:accountIdx/json/list`
-- `POST /chrome/:accountIdx/json/activate/:targetId`
-- `POST /chrome/:accountIdx/cdp/call`
-
-> 首版只做 HTTP facade（调用现有 helper），不做 websocket upgrade 透传。
-
-## 端口解析规则（accountIdx -> debuggerPort）
-
-与现有 `/rpc` 工具行为对齐，优先级如下：
-
-1. 若 `~/cicy-ai/db/chrome.json` 中存在 `account_<idx>.port`，优先使用该 port
-2. 否则回退到 `runtime-registry` 中 `registry.get(accountIdx)?.debuggerPort`
-3. 都没有则返回错误（HTTP 404）
-
-这部分被抽成共享逻辑，避免 `/rpc/chrome_*` 与 `/chrome/*` 对同一账号解析出不同端口。
-
-## 认证
-
-所有 `/chrome/*` 路由均复用既有 `authMiddleware`（与 `/rpc/*` 一致）。
-
-请求示例（token 来自 `~/global.json` 的 `api_token`，或你自己的注入方式）：
-
-```bash
-curl -H "Authorization: Bearer <token>" \
-  http://127.0.0.1:<PORT>/chrome/1/json/version
-```
-
-## API 细节与示例
-
-### 1) 获取版本信息
-
-`GET /chrome/:accountIdx/json/version`
-
-返回：Chrome 原始 `/json/version` JSON（不改写字段）。
-
-```bash
-curl -H "Authorization: Bearer <token>" \
-  http://127.0.0.1:<PORT>/chrome/1/json/version
-```
-
-### 2) 获取 targets 列表
-
-`GET /chrome/:accountIdx/json/list`
-
-返回：Chrome 原始 `/json/list` 数组。
-
-```bash
-curl -H "Authorization: Bearer <token>" \
-  http://127.0.0.1:<PORT>/chrome/1/json/list
-```
-
-### 3) 激活某个 target
-
-`POST /chrome/:accountIdx/json/activate/:targetId`
-
-返回：统一返回 JSON（避免 text/plain 不一致）：
-
-```json
-{ "ok": true, "text": "Target activated" }
-```
-
-```bash
-curl -X POST -H "Authorization: Bearer <token>" \
-  http://127.0.0.1:<PORT>/chrome/1/json/activate/<targetId>
-```
-
-### 4) 发起任意 CDP method call
-
-`POST /chrome/:accountIdx/cdp/call`
-
-Body：
-
-```json
-{ "method": "Browser.getVersion", "params": {}, "target": "optional" }
-```
-
-返回：
-
-```json
-{ "result": { ... } }
-```
-
-```bash
-curl -X POST \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{"method":"Browser.getVersion","params":{}}' \
-  http://127.0.0.1:<PORT>/chrome/1/cdp/call
-```
-
-## 错误语义（HTTP）
-
-- `accountIdx` 非整数：`400`
-  `{"error":"accountIdx must be an integer"}`
-- account 找不到 port（private config + runtime 都没有）：`404`
-  `{"error":"Missing debuggerPort for accountIdx=<n>"}`
-- 上游 debugger port 不可达、或 CDP 调用失败：`502`
-  `{"error":"<message>","debuggerPort":11001,...}`
-- `/cdp/call` 缺少 `method`：`400`
-  `{"error":"Missing method"}`
-
-## 非目标（本次不做）
-
-- 不做 websocket proxy / upgrade
-  因此也不改写 `/json/version` 和 `/json/list` 里的 `webSocketDebuggerUrl`，避免“看起来能连，实际无法 upgrade”的误导。
-- 不引入通用反向代理依赖，不做字节级 raw reverse proxy。
-
-## 代码变更点（关键文件）
-
-- 新增：`src/server/chrome-proxy-routes.js`
-  实现 `/chrome/:accountIdx/...` 路由
-- 新增：`src/chrome/debugger-port-resolver.js`
-  统一端口解析优先级（private config > runtime registry）
-- 修改：`src/main.js`
-  挂载：`app.use("/chrome", authMiddleware, createChromeProxyRoutes(...))`
-- 修改：`src/tools/chrome-tools.js`
-  让 `chrome_get_targets` / `chrome_cdp_call` 复用同一端口解析逻辑（保持行为一致）
-- 新增测试：`tests/rpc/chrome-proxy-routes.test.js`
-  覆盖成功路径与关键错误语义
-
-## 测试验证
-
-已新增并通过的单测（只跑该文件）：
-
-```bash
-npx jest tests/rpc/chrome-proxy-routes.test.js --runInBand
-```
-
-> 注：完整 `npm test` 当前在仓库内存在与本次变更无关的既有失败（例如其他 RPC suite 报 `sleep is not a function`），不属于本次引入回归。