@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0048-device-level-host-project-registry.md

@@ -0,0 +1,253 @@
+# S0048 — Device-level Host And Project Registry
+
+## Goal
+
+把当前“一次 daemon serve 只服务一个启动 cwd”的实现升级为 Device-level Host：
+
+- 一个 Device 只有一个逻辑 Host。
+- Host 持久管理本机多个 Project。
+- `projectId` 取代 `projectSlug` 成为稳定身份。
+- Session 必须归属 Project。
+- Runtime 创建必须根据 Session 的 Project 解析 canonical `workDir`。
+
+这是 GUI、WebUI 添加项目、SSH 远程设备和纯 HTTP API 的共同地基。
+
+## Why Now
+
+当前 M5 WebUI 通过 Session JSONL 聚合 `projectSlug`，只能展示 daemon 启动时的单一工作目录。这个模型无法支持：
+
+- 在同一个 Device 上添加多个工作目录。
+- GUI 像 Codex App 一样管理本地和远程 Project。
+- WebUI 从侧边栏浏览目录并添加 Project。
+- API 客户端先注册 Project，再创建 Session。
+
+在继续堆 UI 前必须先把 Host 的领域模型改正确。
+
+## Scope
+
+### 1. Protocol
+
+新增：
+
+```typescript
+type ProjectId = string & { readonly __brand: "ProjectId" };
+
+interface HostProject {
+  projectId: ProjectId;
+  displayName: string;
+  workDir: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface DirectoryListing {
+  path: string;
+  parentPath?: string;
+  entries: Array<{
+    name: string;
+    path: string;
+    kind: "directory";
+  }>;
+}
+```
+
+修改：
+
+- `SessionMeta.projectId` 必填。
+- `SessionSummary.projectId` 必填。
+- `connected` handshake 只报告 Device identity，不报告单 Project identity。
+- `list_sessions` filter 改为 `{ projectId?: ProjectId; limit?: number }`。
+- `list_projects` 从 Registry 返回 `HostProject[]`。
+- 新增 `list_directories`、`register_project`、`remove_project`。
+- bump `protocolVersion`。
+
+删除：
+
+- `projectSlug`
+- `workDirHint`
+- 任何把 daemon startup cwd 当连接身份的字段
+
+### 2. Project Registry
+
+新增 Host-owned persistence：
+
+```text
+~/.scorel/projects.json
+```
+
+规则：
+
+- Registry 是 Project 的权威索引。
+- `registerProject(workDir)` 先 realpath/canonicalize，再校验 directory 存在。
+- 同一 canonical path 重复注册返回已有 Project，保持幂等。
+- `projectId` 由 Host 生成，不能由 client 路径 slug 计算。
+- `displayName` 默认取目录 basename，后续可扩展 rename。
+- `removeProject(projectId)` 只允许移除没有 Session 的 Registry 项，不删除 session JSONL 或工作区文件。仍有 Session 时返回明确冲突错误。
+
+### 3. Device-level Host
+
+将 `EmbeddedDaemon` 的核心能力升级为 `ScorelHost`。允许在实现过程中保留内部类名作为短期机械步骤，但公开概念、API 和测试必须使用 Host 语义。
+
+Host options 不再接收单一 `workDir`。改为：
+
+```typescript
+interface ScorelHostOptions {
+  deviceId: DeviceId;
+  sessionsDir: string;
+  projectsPath: string;
+  createRuntime(project: HostProject, sessionId: SessionId): Promise<ScorelRuntime>;
+}
+```
+
+Host 根据 `SessionMeta.projectId` 查询 Registry，再把 Project 交给 runtime factory。
+
+### 4. CLI Entry
+
+- `scorel chat --cwd <path>`：创建 embedded Host，注册 cwd，创建或恢复该 Project 下的 Session。
+- `scorel daemon serve`：启动 Device-level WS Host，不把 `--cwd` 当身份。
+- `scorel up --cwd <path>`：可把 cwd 作为启动后的首个注册 Project，作为便捷入口。
+- 新增最小 CLI 管理面：
+
+```text
+scorel project list
+scorel project add <path>
+scorel project remove <projectId>
+```
+
+CLI 管理命令连接已有 WS Host；若实现选择不在 S0048 暴露命令，也必须至少提供等价 integration helper 供 S0049 和测试调用。
+
+### 5. Directory Browsing
+
+Host 暴露 `listDirectories(path?)`：
+
+- path 省略时从用户 home 开始。
+- 返回 canonical current path、可选 parent path、直接子目录。
+- 只返回 directory。
+- 稳定排序。
+- 当前开发阶段不做 workspace root restriction、ACL 或 permission prompt。
+- filesystem error 映射为明确 wire error。
+
+### 6. Session Persistence
+
+新的 Session header 必须写入 `meta.projectId`。旧 `projectSlug` header 不迁移。
+
+实现切换时允许清理开发机上的旧产物：
+
+```text
+~/.scorel/sessions/*
+~/.scorel/attach-cache/*
+```
+
+Registry 文件使用新的 `~/.scorel/projects.json`。不继续写 `~/.scorel/project-index.json`。
+
+### 7. Attach Cache
+
+远程 attach scope 改为：
+
+```text
+deviceId + projectId + sessionId
+```
+
+删除旧 slug-based cache key 和 fallback。
+
+### 8. Diagnostics
+
+日志增加：
+
+- `project_registered`
+- `project_removed`
+- `project_resolved`
+- `directory_listed`
+
+日志可记录 `projectId` 和 canonical path，不得记录 token、API key 或 SSH secret。
+
+## Explicitly Not In Scope
+
+- WebUI Add Project UI，见 S0049。
+- GUI desktop app。
+- SSH 安装、SSH proxy 和远端 supervisor。
+- HTTP API adapter。
+- ACL、角色、scope、sandbox 和 permission approval。
+- Project rename。
+- 每个 Project 一个 worker process。
+- 旧状态迁移或协议兼容。
+
+## Destructive Refactor Rules
+
+Scorel 当前 pre-1.0。本 spec 直接删除旧模型：
+
+- 不保留 `projectSlug` alias。
+- 不做 `projectSlug -> projectId` dual write。
+- 不读取旧 `project-index.json`。
+- 不读取旧 WebUI local storage shape。
+- 不保留旧 client/server protocol negotiation。
+
+旧 Client 连接新 Host 时应因 `protocolVersion` 不匹配明确失败。
+
+## Required Tests
+
+### Protocol
+
+- `SessionMeta.projectId` 和新增 request/response schema round-trip。
+- 不再导出 `projectSlug` 或 `workDirHint`。
+
+### Registry
+
+- 注册 canonical path 幂等。
+- 不存在路径和非目录路径失败。
+- Registry 重启后可恢复。
+- remove 对仍有 Session 的 Project 返回冲突错误；成功 remove 不删除 workspace 文件。
+
+### Host
+
+- 同一 Host 注册两个临时仓库。
+- 分别在两个 Project 创建 Session。
+- 两个 Runtime 的 cwd 正确隔离。
+- `listSessions({ projectId })` 只返回对应 Session。
+- Host 重启后 Registry 和 Session 归属仍正确。
+
+### Directory Browser
+
+- home 默认起点。
+- parent path。
+- 只返回子目录并稳定排序。
+- filesystem error 映射。
+
+### Client
+
+- daemon-only handshake 后可 list/register/remove Project。
+- session-bound 操作仍要求绑定 Session。
+- attach cache scope 使用 `deviceId + projectId + sessionId`。
+
+### CLI And Real Smoke
+
+- `scorel chat --cwd <repo-a>` 能使用真实 provider 完成一轮。
+- 同一 `scorel daemon serve` 注册 `<repo-a>` 和 `<repo-b>`。
+- 对两个 Project 分别创建 Session，真实 provider 回答中可观测 cwd 不串线。
+- `scorel attach --remote` 可恢复其中一个 Session。
+
+不要使用 fake/mock provider 代替真实产品 smoke。
+
+## Likely Files
+
+```text
+packages/protocol/src/ids.ts
+packages/protocol/src/events.ts
+packages/protocol/src/wire.ts
+packages/daemon/src/index.ts
+packages/daemon/src/projects/registry.ts
+packages/daemon/src/ws-server.ts
+packages/client/src/index.ts
+apps/cli/src/index.ts
+apps/cli/src/daemon-cli.ts
+apps/cli/src/up-cli.ts
+```
+
+## Done When
+
+- 一个 WS Host 能管理至少两个 Project。
+- Project 来自持久 Registry，不再来自 Session 聚合。
+- Session 和 Runtime 都按 `projectId` 解析 cwd。
+- `projectSlug` 和 `workDirHint` 从当前代码、协议和非历史文档中删除。
+- 自动测试、typecheck 和真实双 Project smoke 通过。
+- 完成后 commit：`S0048: feat: add device-level host project registry`

package/docs/spec/ship/S0049-webui-add-project-directory-browser.md

@@ -0,0 +1,217 @@
+# S0049 — WebUI Add Project And Directory Browser
+
+## Goal
+
+让 WebUI 侧边栏出现正式的“添加项目”入口。用户选择 Device，浏览该 Device 的目录，注册工作空间，并立即在 Device -> Project -> Session 树中看到新 Project。
+
+S0049 继续保持 Device-first：
+
+- WebUI 添加的是 Device，不是 Project subscription。
+- Project 只是 owning Host 上 canonical 工作目录的稳定抽象。
+- 连接 Device 后，WebUI 展示该 Host Registry 中的全部 Project。
+- 展开 Project 时才按 `projectId` 查询 Session。
+- 点击 Session 时才加载 JSONL，并按需创建 Runtime。
+
+## Dependency
+
+必须先完成 [`S0048`](S0048-device-level-host-project-registry.md)。
+
+S0048 已完成以下基础迁移，S0049 不重复实现：
+
+- WebUI Project 身份已经从 `projectSlug` 切到 `projectId`。
+- Project route 已经使用 `[projectId]`。
+- attach cache scope 已经使用 `deviceId + projectId + sessionId`。
+- `syncProjects(deviceId)` 已经使用 Registry 返回值。
+- `syncSessions(deviceId, projectId)` 已经发送 `projectId` filter，并按 Device + Project 去重。
+- New Session 已经传递 `meta.projectId`。
+
+## Product Model
+
+```text
+Device
+  -> listProjects() 展示 Host Registry 中全部 Project
+    -> 展开 Project 时 listSessions({ projectId })
+      -> 点击 Session 时 loadSession(sessionId)
+        -> Host 按 projectId 解析 canonical workDir
+          -> 按需创建 Runtime
+```
+
+Project Registry 是 Host 已知工作目录的权威集合。UI 不再增加一套 visible Project、pin、disable 或 archive 状态。
+
+Session JSONL 是 Project 下的持久历史。UI 不增加 Session delete、archive 或额外状态文件。
+
+## Product Flow
+
+```text
+点击侧边栏“添加项目”
+  -> 选择 Device
+  -> 浏览该 Device 文件夹
+  -> 选择当前工作目录
+  -> register_project
+  -> Host canonicalize 路径并幂等返回 Project
+  -> WebUI 重新调用 list_projects
+  -> 展示该 Device 的完整 Project Registry
+  -> 自动展开并选中新 Project
+  -> 可直接新增 Session
+```
+
+本地 Device 和远程 Device 使用同一套 Host API。WebUI 不直接读取浏览器所在机器的文件系统，也不自行解释远端路径。
+
+## Scope
+
+### 1. Sidebar Add Project
+
+在 sidebar 的 Device / Project 区域增加正式“添加项目”入口：
+
+- 没有 Device 时，引导用户先添加 Device。
+- 有一个 Device 时，直接进入该 Device 的目录浏览。
+- 有多个 Device 时，先选择 Device。
+- 注册成功后重新同步该 Device 的完整 Project 列表。
+- 自动展开并选中新 Project。
+- 注册失败时显示明确错误，不静默吞掉。
+
+### 2. Directory Browser Dialog
+
+新增 modal/dialog：
+
+- 显示当前 Device。
+- 显示 Host 返回的 canonical current path。
+- 支持进入直接子目录。
+- 支持返回 Host 返回的 parent path。
+- 支持选择当前目录作为 Project。
+- loading、empty、filesystem error 都有明确状态。
+- 浏览器不得自行拼接、规范化或反向解析路径。
+- 目录导航只使用 Host 返回的 `path` 和 `parentPath`。
+
+### 3. Registry Refresh
+
+注册成功后：
+
+1. 调用 `client.registerProject(workDir)`。
+2. 调用现有 `syncProjects({ client, store, deviceId })`。
+3. 使用返回 Project 的 `projectId` 展开并跳转：
+
+```text
+/devices/:deviceId/projects/:projectId
+```
+
+`registerProject()` 对同一 canonical path 必须幂等。重复添加同一路径时复用已有 `projectId`，不能制造重复 Project。
+
+### 4. Session Lazy Loading
+
+保持现有懒加载边界，不引入额外 Session 生命周期：
+
+- `syncProjects()` 不加载 Session。
+- 展开或进入 Project 时调用 `listSessions({ projectId })`。
+- 点击 Session 时调用 `loadSession(sessionId)`。
+- Session JSONL 不删除、不归档。
+- Host 不为 Registry 中每个 Project 常驻创建 Runtime。
+
+### 5. Existing Device Behavior
+
+连接已有 Device 后，WebUI 继续调用 `listProjects()` 并展示 Host Registry 全集。
+
+- 不保存客户端侧 visible Project 子集。
+- 不实现 Project pin / unpin。
+- 不区分本地 Device 与远端 Device 的 Project 展示规则。
+- 添加 Project 始终通过目标 Device 的 Host 目录浏览完成。
+
+## Explicitly Not In Scope
+
+- GUI desktop app。
+- SSH 配置导入、安装远端 Scorel、SSH proxy。
+- 账号密码、权限分级、ACL。
+- Project rename、pin、recent list、disable、archive。
+- 普通 WebUI 的 Project remove 操作。
+- Session delete、archive、unarchive 或额外 `session-state.json`。
+- IDE-style file explorer。
+- HTTP API。
+- 为每个 Registry Project 常驻 Runtime。
+- S0048 已完成的 `projectId` route、cache 和 store 迁移。
+
+`remove_project` 若继续存在，只是底层 Host 管理 API。S0049 普通 WebUI 不调用它，也不扩展它。
+
+## Required Tests
+
+### Add Project Dialog
+
+- 无 Device 时显示添加 Device 引导。
+- 单 Device 时直接浏览该 Device。
+- 多 Device 时先选择 Device。
+- 初始目录加载状态。
+- 目录列表 empty 状态。
+- filesystem error 状态。
+- child navigation 使用 Host 返回的 child `path`。
+- parent navigation 使用 Host 返回的 `parentPath`。
+- 选择当前目录后调用 `registerProject(workDir)`。
+- 重复注册同一目录时接受 Host 返回的已有 Project。
+- 注册失败时保持 dialog 打开并显示错误。
+
+### Sidebar Integration
+
+- sidebar 存在“添加项目”入口。
+- 注册成功后调用 `syncProjects(deviceId)`，而不是仅向浏览器 store 手工 append。
+- 同步后展示 Device Registry 全集。
+- 注册成功后自动展开并跳转到 `projectId` route。
+- 普通 UI 不调用 `removeProject()`。
+
+### Lazy Loading Regression
+
+- `syncProjects(deviceId)` 不调用 `listSessions()`。
+- 展开或进入 Project 时调用 `listSessions({ projectId })`。
+- 点击 Session 时调用 `loadSession(sessionId)`。
+- 不新增 Session archive / delete 状态。
+
+### Existing S0048 Regression
+
+- Project route 继续使用 `projectId`。
+- New Session 继续携带 `meta.projectId`。
+- attach cache scope 继续使用 `deviceId + projectId + sessionId`。
+- browser store 不读取旧 slug snapshot。
+
+### Real Manual Smoke
+
+1. `scorel up` 启动真实 Host 和 WebUI。
+2. 在 WebUI 添加 Device。
+3. 在侧边栏点击“添加项目”。
+4. 通过目标 Device 的目录浏览注册两个不同真实临时仓库。
+5. 确认 Device 下展示 Host Registry 的两个 Project。
+6. 分别展开两个 Project，确认按 Project 懒加载 Session。
+7. 分别创建 Session。
+8. 通过真实 provider 在两个 Session 发送 prompt，确认 Runtime cwd 不串线。
+9. 刷新页面，确认 Device -> Project -> Session 树恢复。
+10. CLI attach 其中一个 Session，确认 WebUI 可见同一事件流。
+
+不要使用 fake/mock provider 代替真实产品 smoke。
+
+## Likely Files
+
+```text
+apps/webui/components/shell/sidebar.tsx
+apps/webui/components/shell/sidebar.test.tsx
+apps/webui/components/projects/add-project-dialog.tsx
+apps/webui/components/projects/add-project-dialog.test.tsx
+apps/webui/lib/connection/pool.ts
+apps/webui/lib/connection/use-connection.ts
+apps/webui/lib/sync/projects.ts
+apps/webui/lib/sync/projects.test.ts
+apps/webui/README.md
+```
+
+## Risks And Boundaries
+
+- 目录浏览发生在目标 Device Host，不是浏览器所在机器。
+- 浏览器不得假设 POSIX 路径，也不得自行拼接路径。
+- Registry Project 数量增长时，`listProjects()` 仍是 Device 级全集；客户端侧筛选不是 S0049 的优化方向。
+- Session 列表必须保持按 Project 懒加载，避免 Device 连接时扫描并加载全部 Session。
+- 普通 UI 不暴露底层 `remove_project`，避免把工作目录管理误解为 Session 删除。
+
+## Done When
+
+- WebUI 侧边栏可通过 Host 目录浏览注册 Project。
+- 添加 Device 后展示该 Host Registry 的全部 Project。
+- 重复注册同一路径不会产生重复 Project。
+- Session 继续按 Project 懒加载，Runtime 继续按 Session 按需创建。
+- 普通 WebUI 不提供 Project remove、Project disable 或 Session archive。
+- 自动测试和真实双 Project WebUI smoke 通过。
+- 完成后 commit：`S0049: feat: add webui project directory browser`