@hienlh/ppm 0.1.0

package/plans/260314-2009-ppm-implementation/plan.md

@@ -0,0 +1,202 @@
+---
+status: pending
+created: 2026-03-14
+updated: 2026-03-14
+slug: ppm-implementation
+version: 3
+---
+
+# PPM Implementation Plan (v2)
+
+## Overview
+
+Build PPM (Personal Project Manager) — mobile-first web IDE running as CLI daemon.
+Tech: Bun + Hono (backend), React 19 + Vite + Tailwind + shadcn/ui (frontend).
+
+## Context
+
+- [Final Tech Stack](../reports/brainstorm-260314-1938-final-techstack.md)
+- [Tech Stack Research](../reports/research-260314-1911-ppm-tech-stack.md)
+- [Claude Code Integration Research](../reports/research-260314-1930-claude-code-integration.md)
+- [UI Style Guide](../reports/researcher-260314-2232-ui-style.md)
+- [node-pty Research](../reports/researcher-260314-2232-node-pty-bun-crash-analysis.md)
+
+## V1 Lessons (MUST follow)
+
+These were bugs/issues found during v1 browser E2E testing. V2 must build them in from the start:
+
+1. **API envelope auto-unwrap:** `api-client.get<T>()` returns `T` directly, not `{ok, data: T}`. Backend wraps in `{ok, data}`, client unwraps.
+2. **Project resolution by NAME:** All API routes accept project name (e.g. "ppm"), not filesystem path. Use `resolveProjectPath(name)` helper in every route.
+3. **Terminal: Bun native Terminal API:** Use `Bun.spawn()` with `terminal` option (full PTY). node-pty uses NAN bindings incompatible with Bun — hard crash, no fix possible. See [research](../reports/researcher-260314-2232-node-pty-bun-crash-analysis.md).
+4. **Git log: use simple-git built-in:** Don't parse `git log --format` manually. Use `simple-git`'s `.log()` method which handles parsing correctly.
+5. **Metadata on all tab openers:** Both tab-bar AND mobile-nav must pass `{ projectName }` metadata when opening git/file tabs.
+6. **Mobile sidebar = overlay drawer:** Don't use `hidden md:flex`. Use absolute positioned overlay with backdrop that slides in on hamburger click.
+
+## Team
+
+| Agent | Role | File Ownership |
+|---|---|---|
+| **Lead** (main) | Coordinator, shared types, config files | `src/types/**`, `package.json`, configs, `CLAUDE.md` |
+| **backend-dev** | Server, CLI, services | `src/cli/**`, `src/server/**`, `src/services/**`, `src/providers/**` |
+| **frontend-dev** | React UI, all components | `src/web/**`, `public/**`, `index.html` |
+| **tester** | Unit + integration tests | `tests/**`, `*.test.ts` (read-only on src) |
+
+## Phases
+
+| # | Phase | Owner | Depends | Status |
+|---|---|---|---|---|
+| 1 | [Project Skeleton + Shared Types](phase-01-project-skeleton.md) | Lead | — | pending |
+| 2 | [Backend Core (Server + CLI + Config)](phase-02-backend-core.md) | backend-dev | 1 | pending |
+| 3 | [Frontend Shell (Tab System + Layout)](phase-03-frontend-shell.md) | frontend-dev | 1 | pending |
+| 4 | [File Explorer + Editor](phase-04-file-explorer-editor.md) | backend-dev + frontend-dev | 2, 3 | pending |
+| 5 | [Web Terminal](phase-05-web-terminal.md) | backend-dev + frontend-dev | 2, 3 | pending |
+| 6 | [Git Integration](phase-06-git-integration.md) | backend-dev + frontend-dev | 4 | pending |
+| 7 | [AI Chat](phase-07-ai-chat.md) | backend-dev + frontend-dev | 2, 3 | pending |
+| 8 | [CLI Commands](phase-08-cli-commands.md) | backend-dev | 2, 6, 7 | pending |
+| 9 | [PWA + Build + Deploy](phase-09-pwa-build-deploy.md) | Lead | all | pending |
+| 10 | [Testing](phase-10-testing.md) | tester | per phase | pending |
+
+## Execution Order
+
+Backend phases run **sequentially** (single agent, 200K context limit). Frontend can parallel where independent.
+
+```
+Phase 1 (Lead)
+    ├── Phase 2 (backend-dev) ──→ Phase 4-BE ──→ Phase 5-BE ──→ Phase 6-BE ──→ Phase 7-BE ──→ Phase 8
+    ├── Phase 3 (frontend-dev) ──→ Phase 4-FE ──→ Phase 5-FE ──→ Phase 6-FE ──→ Phase 7-FE
+    │
+    Phase 9 (Lead, after all)
+    Phase 10 (tester, continuous after each phase)
+```
+
+Note: Each phase's backend + frontend can run in parallel (separate agents), but backend phases are sequential among themselves.
+
+## Project Structure
+
+```
+ppm/
+├── package.json
+├── tsconfig.json
+├── bunfig.toml
+├── vite.config.ts
+├── ppm.example.yaml
+├── .env.example
+├── LICENSE (MIT)
+├── README.md
+├── CLAUDE.md
+├── src/
+│   ├── index.ts                    # Entry point (CLI)
+│   ├── types/
+│   │   ├── config.ts               # Config types
+│   │   ├── project.ts              # Project types
+│   │   ├── git.ts                  # Git types (commit, branch, graph)
+│   │   ├── chat.ts                 # Chat/AI types (ChatEvent, AIProvider)
+│   │   ├── terminal.ts             # Terminal session types
+│   │   └── api.ts                  # API request/response types
+│   ├── cli/
+│   │   ├── index.ts                # Commander.js setup
+│   │   ├── commands/
+│   │   │   ├── init.ts
+│   │   │   ├── start.ts
+│   │   │   ├── stop.ts
+│   │   │   ├── open.ts
+│   │   │   ├── projects.ts
+│   │   │   ├── config.ts
+│   │   │   ├── git.ts
+│   │   │   └── chat.ts
+│   │   └── utils/
+│   │       └── project-resolver.ts # CWD auto-detect + -p flag
+│   ├── server/
+│   │   ├── index.ts                # Hono app + Bun.serve + WS upgrade
+│   │   ├── middleware/
+│   │   │   └── auth.ts             # Token auth middleware
+│   │   ├── routes/
+│   │   │   ├── projects.ts
+│   │   │   ├── files.ts
+│   │   │   ├── git.ts
+│   │   │   └── static.ts          # Serve embedded SPA
+│   │   ├── ws/
+│   │   │   ├── terminal.ts         # WS /ws/terminal/:id
+│   │   │   └── chat.ts             # WS /ws/chat/:id
+│   │   └── helpers/
+│   │       └── resolve-project.ts  # Shared: name → path resolver
+│   ├── services/
+│   │   ├── config.service.ts
+│   │   ├── project.service.ts
+│   │   ├── file.service.ts
+│   │   ├── git.service.ts
+│   │   ├── terminal.service.ts     # Uses Bun.spawn (NOT node-pty)
+│   │   └── chat.service.ts
+│   ├── providers/
+│   │   ├── provider.interface.ts
+│   │   ├── claude-agent-sdk.ts
+│   │   ├── cli-subprocess.ts       # Future generic CLI provider
+│   │   └── registry.ts
+│   └── web/                        # React SPA (Vite)
+│       ├── index.html
+│       ├── main.tsx
+│       ├── app.tsx
+│       ├── vite-env.d.ts
+│       ├── components/
+│       │   ├── auth/
+│       │   │   └── login-screen.tsx     # Token input screen
+│       │   ├── layout/
+│       │   │   ├── tab-bar.tsx
+│       │   │   ├── tab-content.tsx
+│       │   │   ├── sidebar.tsx          # Desktop sidebar
+│       │   │   ├── mobile-drawer.tsx    # Mobile overlay sidebar
+│       │   │   └── mobile-nav.tsx
+│       │   ├── projects/
+│       │   │   ├── project-list.tsx
+│       │   │   └── project-card.tsx
+│       │   ├── explorer/
+│       │   │   ├── file-tree.tsx
+│       │   │   └── file-actions.tsx
+│       │   ├── editor/
+│       │   │   ├── code-editor.tsx
+│       │   │   └── diff-viewer.tsx
+│       │   ├── terminal/
+│       │   │   └── terminal-tab.tsx
+│       │   ├── chat/
+│       │   │   ├── chat-tab.tsx
+│       │   │   ├── message-list.tsx
+│       │   │   ├── message-input.tsx
+│       │   │   ├── tool-approval.tsx
+│       │   │   └── session-picker.tsx
+│       │   ├── git/
+│       │   │   ├── git-graph.tsx
+│       │   │   ├── git-graph-renderer.tsx
+│       │   │   ├── git-status-panel.tsx
+│       │   │   ├── git-diff-tab.tsx
+│       │   │   └── commit-context-menu.tsx
+│       │   └── ui/                 # shadcn/ui components
+│       │       └── ...
+│       ├── stores/
+│       │   ├── tab.store.ts
+│       │   ├── project.store.ts
+│       │   └── settings.store.ts
+│       ├── hooks/
+│       │   ├── use-websocket.ts
+│       │   ├── use-terminal.ts
+│       │   └── use-chat.ts
+│       ├── lib/
+│       │   ├── api-client.ts       # Auto-unwraps {ok, data} envelope
+│       │   ├── ws-client.ts        # WebSocket client with reconnect
+│       │   └── git-graph-layout.ts
+│       └── styles/
+│           └── globals.css
+├── tests/
+│   ├── unit/
+│   │   ├── services/
+│   │   └── providers/
+│   ├── integration/
+│   │   ├── api/
+│   │   └── ws/
+│   └── setup.ts
+├── scripts/
+│   └── build.ts
+└── docs/
+    ├── project-overview-pdr.md
+    ├── code-standards.md
+    └── system-architecture.md
+```

package/plans/260315-0356-project-scoped-api-refactor/phase-01-backend-project-router.md

@@ -0,0 +1,145 @@
+---
+phase: 1
+title: "Backend project-scoped router"
+status: completed
+effort: 2h
+---
+
+# Phase 1: Backend Project-Scoped Router
+
+## Context
+- [plan.md](./plan.md)
+- `src/server/index.ts` -- main app, route mounting, WS upgrade
+- `src/server/routes/chat.ts`, `git.ts`, `files.ts`
+- `src/server/helpers/resolve-project.ts`
+- `src/server/ws/terminal.ts`, `chat.ts`
+
+## Overview
+Create a Hono sub-router mounted at `/api/project/:projectName` with middleware that resolves the project path. Remount chat, git, files routes under it. Remove per-route `resolveProjectPath` calls.
+
+## Architecture
+
+```
+app.route("/api/project/:projectName", projectScopedRouter)
+  -> middleware: resolve projectName, set c.set("projectPath", path)
+  -> projectScopedRouter.route("/chat", chatRoutes)
+  -> projectScopedRouter.route("/git", gitRoutes)
+  -> projectScopedRouter.route("/files", fileRoutes)
+```
+
+## Related Code Files
+
+### Files to modify
+- `src/server/index.ts` -- new mount point, update WS upgrade paths
+- `src/server/routes/chat.ts` -- read projectPath from context, remove dir/projectName from query/body
+- `src/server/routes/git.ts` -- read projectPath from context, remove `:project` param from each route, remove `project` from POST bodies
+- `src/server/routes/files.ts` -- read projectPath from context, remove `:project` param from each route
+
+### Files to create
+- `src/server/routes/project-scoped.ts` -- the sub-router with middleware
+
+### Files unchanged
+- `src/server/routes/projects.ts` -- stays at `/api/projects` (global)
+- `src/server/routes/static.ts` -- unchanged
+- `src/server/middleware/auth.ts` -- unchanged
+
+## Implementation Steps
+
+### 1. Create project-scoped router (`src/server/routes/project-scoped.ts`)
+```ts
+import { Hono } from "hono";
+import { resolveProjectPath } from "../helpers/resolve-project.ts";
+import { chatRoutes } from "./chat.ts";
+import { gitRoutes } from "./git.ts";
+import { fileRoutes } from "./files.ts";
+
+type Env = { Variables: { projectPath: string; projectName: string } };
+
+export const projectScopedRouter = new Hono<Env>();
+
+// Middleware: resolve project name to path
+projectScopedRouter.use("*", async (c, next) => {
+  const name = c.req.param("projectName");
+  if (!name) return c.json({ ok: false, error: "Missing project name" }, 400);
+  const projectPath = resolveProjectPath(name);
+  c.set("projectPath", projectPath);
+  c.set("projectName", name);
+  await next();
+});
+
+projectScopedRouter.route("/chat", chatRoutes);
+projectScopedRouter.route("/git", gitRoutes);
+projectScopedRouter.route("/files", fileRoutes);
+```
+
+### 2. Update `src/server/index.ts`
+- Replace separate route mounts:
+  ```diff
+  - app.route("/api/files", fileRoutes);
+  - app.route("/api/chat", chatRoutes);
+  - app.route("/api/git", gitRoutes);
+  + app.route("/api/project/:projectName", projectScopedRouter);
+  ```
+- Keep: `app.route("/api/projects", projectRoutes)`
+- Update WS upgrade paths (see Phase 4, but do now for consistency):
+  ```diff
+  - if (url.pathname.startsWith("/ws/terminal/"))
+  + if (url.pathname.startsWith("/ws/project/"))
+  ```
+  Parse: `/ws/project/:projectName/terminal/:id` and `/ws/project/:projectName/chat/:sessionId`
+
+### 3. Refactor `src/server/routes/git.ts`
+- Remove `resolveProjectPath` import
+- GET routes: remove `/:project` param segment; read `c.get("projectPath")` from context
+  - `/status/:project` -> `/status`
+  - `/diff/:project` -> `/diff`
+  - `/diff-stat/:project` -> `/diff-stat`
+  - `/file-diff/:project` -> `/file-diff`
+  - `/graph/:project` -> `/graph`
+  - `/branches/:project` -> `/branches`
+  - `/pr-url/:project` -> `/pr-url`
+- POST routes: remove `project` from `c.req.json()` destructuring; use `c.get("projectPath")`
+  - `/stage`, `/unstage`, `/commit`, `/push`, `/pull`, `/branch/create`, `/checkout`, `/branch/delete`, `/merge`, `/cherry-pick`, `/revert`, `/tag`
+
+### 4. Refactor `src/server/routes/files.ts`
+- Remove `resolveProjectPath` import
+- All routes: remove `/:project` param; use `c.get("projectPath")`
+  - `/tree/:project` -> `/tree`
+  - `/read/:project` -> `/read`
+  - `/write/:project` -> `/write`
+  - `/create/:project` -> `/create`
+  - `/delete/:project` -> `/delete`
+  - `/compare/:project` -> `/compare`
+  - `/rename/:project` -> `/rename`
+  - `/move/:project` -> `/move`
+
+### 5. Refactor `src/server/routes/chat.ts`
+- Remove `dir` query param from sessions list; project comes from URL context
+- Remove `projectName` from POST body on session creation; use `c.get("projectName")`
+- Keep `/providers` endpoint -- move to project-scoped or keep global. Decision: keep project-scoped since providers may vary per project in future.
+- Sessions list: filter by `c.get("projectName")` instead of `dir` query
+
+### 6. Update WS handlers in `src/server/index.ts`
+- Terminal WS: `/ws/project/:projectName/terminal/:id`
+  - Parse projectName from URL, pass to ws.data
+  - Remove `?project=` query param
+- Chat WS: `/ws/project/:projectName/chat/:sessionId`
+  - Parse projectName from URL, pass to ws.data
+
+### 7. Update daemon `Bun.serve()` block (bottom of index.ts)
+- Same WS path changes as foreground server
+
+## Todo List
+- [x] Create `src/server/routes/project-scoped.ts`
+- [x] Update `src/server/index.ts` mounting
+- [x] Refactor `git.ts` routes (17 endpoints)
+- [x] Refactor `files.ts` routes (8 endpoints)
+- [x] Refactor `chat.ts` routes (4 endpoints)
+- [x] Update WS upgrade paths (foreground + daemon)
+- [x] Verify compile with `bun build`
+
+## Success Criteria
+- All routes respond at new paths
+- No `resolveProjectPath` calls in individual route files (only in middleware)
+- Git POST routes no longer require `project` in body
+- WS connections work at new paths

package/plans/260315-0356-project-scoped-api-refactor/phase-02-frontend-api-migration.md

@@ -0,0 +1,107 @@
+---
+phase: 2
+title: "Frontend API client + calls migration"
+status: pending
+effort: 2h
+depends_on: [1]
+---
+
+# Phase 2: Frontend API Client + Calls Migration
+
+## Context
+- [plan.md](./plan.md)
+- [phase-01](./phase-01-backend-project-router.md)
+- `src/web/lib/api-client.ts`
+- All frontend components calling `/api/...`
+
+## Overview
+Add project-scoped URL helper to ApiClient. Update all frontend API calls to use `/api/project/:projectName/...` pattern. Remove `project` from POST bodies for git operations.
+
+## Key Insight
+Most components already have access to `projectName` via `useProjectStore` or props. The migration is mechanical: prefix every API path with `/api/project/${projectName}`.
+
+## Related Code Files
+
+### Files to modify
+- `src/web/lib/api-client.ts` -- add `projectUrl()` helper
+- `src/web/components/chat/chat-tab.tsx` -- session creation URL
+- `src/web/components/chat/session-picker.tsx` -- session list/delete URLs
+- `src/web/hooks/use-chat.ts` -- message history URL
+- `src/web/components/git/git-graph.tsx` -- all git API calls (~12 calls)
+- `src/web/components/git/git-status-panel.tsx` -- status, stage, unstage, commit, push, pull
+- `src/web/stores/file-store.ts` -- file tree URL
+- `src/web/components/editor/code-editor.tsx` -- read/write URLs
+- `src/web/components/explorer/file-actions.tsx` -- create/rename/delete URLs
+- `src/web/components/editor/diff-viewer.tsx` -- compare/diff URLs
+
+## Implementation Steps
+
+### 1. Add helper to `api-client.ts`
+```ts
+/** Build project-scoped API path prefix */
+export function projectUrl(projectName: string): string {
+  return `/api/project/${encodeURIComponent(projectName)}`;
+}
+```
+
+### 2. Update git-graph.tsx
+Before:
+```ts
+`/api/git/graph/${encodeURIComponent(projectName)}?max=200`
+gitAction("/api/git/checkout", { project: projectName, ref });
+```
+After:
+```ts
+`${projectUrl(projectName)}/git/graph?max=200`
+gitAction(`${projectUrl(projectName)}/git/checkout`, { ref });
+```
+- Remove `project` field from all `gitAction` call bodies
+- Update all GET URLs: `/api/git/status/:project` -> `${projectUrl(name)}/git/status`
+
+### 3. Update git-status-panel.tsx
+Same pattern:
+- GET `/api/git/status/${name}` -> `${projectUrl(name)}/git/status`
+- POST bodies: remove `project: projectName` field from stage/unstage/commit/push/pull
+
+### 4. Update file-related components
+- `file-store.ts`: `/api/files/tree/${name}` -> `${projectUrl(name)}/files/tree`
+- `code-editor.tsx`: `/api/files/read/${name}?path=` -> `${projectUrl(name)}/files/read?path=`
+- `file-actions.tsx`: same pattern for create/rename/delete
+- `diff-viewer.tsx`: same pattern for compare/file-diff/diff
+
+### 5. Update chat components
+- `chat-tab.tsx`: `/api/chat/sessions` -> `${projectUrl(name)}/chat/sessions`
+  - Remove `projectName` from POST body
+- `session-picker.tsx`: same prefix, remove `?dir=` query
+- `use-chat.ts`: `/api/chat/sessions/:id/messages` -> `${projectUrl(name)}/chat/sessions/:id/messages`
+  - Need to pass projectName into `useChat` hook (add param)
+
+### 6. Update use-chat.ts signature
+```ts
+export function useChat(
+  sessionId: string | null,
+  providerId: string,
+  projectName: string,  // NEW
+): UseChatReturn
+```
+- History fetch: `${projectUrl(projectName)}/chat/sessions/${sessionId}/messages?providerId=${providerId}`
+- WS URL change handled in Phase 4
+
+## Todo List
+- [ ] Add `projectUrl()` to api-client.ts
+- [ ] Update git-graph.tsx (~15 call sites)
+- [ ] Update git-status-panel.tsx (~6 call sites)
+- [ ] Update file-store.ts (1 call)
+- [ ] Update code-editor.tsx (2 calls)
+- [ ] Update file-actions.tsx (3 calls)
+- [ ] Update diff-viewer.tsx (4 calls)
+- [ ] Update chat-tab.tsx (1 call)
+- [ ] Update session-picker.tsx (2 calls)
+- [ ] Update use-chat.ts (1 call + signature)
+- [ ] Verify compile
+
+## Success Criteria
+- All API calls use `/api/project/:projectName/...` prefix
+- No `project` field in git POST bodies
+- No `dir` query param in chat session list
+- TypeScript compiles clean

package/plans/260315-0356-project-scoped-api-refactor/phase-03-per-project-tabs.md

@@ -0,0 +1,100 @@
+---
+phase: 3
+title: "Per-project tab storage"
+status: pending
+effort: 1.5h
+depends_on: []
+---
+
+# Phase 3: Per-Project Tab Storage
+
+## Context
+- [plan.md](./plan.md)
+- `src/web/stores/tab-store.ts` -- current global tab store
+- `src/web/stores/project-store.ts` -- project selection
+- `src/web/app.tsx` -- default tab opening logic
+
+## Overview
+Make tabs project-scoped: each project gets its own tab set persisted under `ppm-tabs-{projectName}`. When user switches project, the tab bar swaps to that project's tabs.
+
+## Key Design Decision
+**Approach: Dynamic storage key** -- Zustand `persist` middleware does not natively support dynamic keys. Two options:
+
+**Option A (chosen): Manual localStorage swap.** On project change, serialize current tabs to `ppm-tabs-{oldProject}`, load from `ppm-tabs-{newProject}`, hydrate store. Simple, no lib changes.
+
+**Option B (rejected): Multiple store instances.** One store per project. Over-engineered for this use case.
+
+## Related Code Files
+
+### Files to modify
+- `src/web/stores/tab-store.ts` -- add project-aware persist, swap logic
+- `src/web/app.tsx` -- pass project context on default tab, react to project switch
+
+## Implementation Steps
+
+### 1. Refactor tab-store.ts
+
+Remove Zustand `persist` middleware. Replace with manual localStorage read/write:
+
+```ts
+const STORAGE_PREFIX = "ppm-tabs-";
+
+function storageKey(projectName: string): string {
+  return `${STORAGE_PREFIX}${projectName}`;
+}
+
+function loadTabs(projectName: string): { tabs: Tab[]; activeTabId: string | null } {
+  try {
+    const raw = localStorage.getItem(storageKey(projectName));
+    if (raw) return JSON.parse(raw);
+  } catch { /* ignore */ }
+  return { tabs: [], activeTabId: null };
+}
+
+function saveTabs(projectName: string, state: { tabs: Tab[]; activeTabId: string | null }) {
+  localStorage.setItem(storageKey(projectName), JSON.stringify(state));
+}
+```
+
+Add to store:
+```ts
+interface TabStore {
+  // existing...
+  currentProject: string | null;
+  switchProject: (projectName: string) => void;
+}
+```
+
+`switchProject(newProject)`:
+1. If `currentProject` exists, save current tabs to localStorage under old key
+2. Load tabs from new key
+3. Set `currentProject = newProject`, hydrate tabs
+4. If no tabs loaded, open default "Projects" tab
+
+### 2. Auto-save on tab mutations
+After every `openTab`, `closeTab`, `setActiveTab`, `updateTab` -- call `saveTabs(currentProject, { tabs, activeTabId })`. Use Zustand `subscribe` to batch this.
+
+### 3. Update app.tsx
+- On project change (when `activeProject` changes), call `useTabStore.getState().switchProject(activeProject.name)`
+- Remove the "open default tab if none" effect -- let `switchProject` handle defaults
+
+### 4. Clean up old storage
+- Remove old `ppm-tabs` key migration: not needed on v2-fresh-start branch
+
+### 5. Fix nextId collision
+Current `nextId` is a module-level counter. On project switch, tabs from different projects may have overlapping IDs. Fix: derive nextId from loaded tabs on every switch.
+
+## Todo List
+- [ ] Remove `persist` middleware from tab-store
+- [ ] Add manual localStorage read/write functions
+- [ ] Add `currentProject` and `switchProject` to store
+- [ ] Add `subscribe` auto-save
+- [ ] Update `app.tsx` to call `switchProject` on project change
+- [ ] Fix nextId derivation on hydration
+- [ ] Test: switch project -> tabs change, switch back -> original tabs restored
+
+## Success Criteria
+- Each project has independent tab state in localStorage
+- Switching project instantly swaps visible tabs
+- Closing all tabs in project A does not affect project B
+- Default "Projects" tab opens if project has no saved tabs

package/plans/260315-0356-project-scoped-api-refactor/phase-04-websocket-migration.md

@@ -0,0 +1,66 @@
+---
+phase: 4
+title: "WebSocket URL migration"
+status: pending
+effort: 0.5h
+depends_on: [1]
+---
+
+# Phase 4: WebSocket URL Migration
+
+## Context
+- [plan.md](./plan.md)
+- [phase-01](./phase-01-backend-project-router.md) -- backend WS path changes
+- `src/web/hooks/use-terminal.ts` -- terminal WS connection
+- `src/web/hooks/use-chat.ts` -- chat WS connection (via use-websocket)
+
+## Overview
+Update frontend WS URLs to match new `/ws/project/:projectName/...` paths.
+
+## Related Code Files
+
+### Files to modify
+- `src/web/hooks/use-terminal.ts` -- WS URL construction
+- `src/web/hooks/use-chat.ts` -- WS URL passed to `useWebSocket`
+
+## Implementation Steps
+
+### 1. Update use-terminal.ts
+Before:
+```ts
+const url = `${protocol}//${host}/ws/terminal/${sid}${projectParam ? `?project=${encodeURIComponent(projectParam)}` : ""}`;
+```
+After:
+```ts
+const url = `${protocol}//${host}/ws/project/${encodeURIComponent(options.projectName!)}/terminal/${sid}`;
+```
+- Remove `?project=` query param -- project is in path
+- `projectName` is now required (not optional) in `UseTerminalOptions`
+
+### 2. Update use-chat.ts
+Before:
+```ts
+url: sessionId ? `/ws/chat/${sessionId}` : "",
+```
+After:
+```ts
+url: sessionId && projectName ? `/ws/project/${encodeURIComponent(projectName)}/chat/${sessionId}` : "",
+```
+- `projectName` param was added in Phase 2
+
+### 3. Ensure backend parses new WS paths
+Already handled in Phase 1, step 6. Verify:
+- `/ws/project/:projectName/terminal/:id` extracts both projectName and id
+- `/ws/project/:projectName/chat/:sessionId` extracts both
+
+## Todo List
+- [ ] Update `use-terminal.ts` WS URL
+- [ ] Make `projectName` required in `UseTerminalOptions`
+- [ ] Update `use-chat.ts` WS URL
+- [ ] Verify both WS connections work end-to-end
+
+## Success Criteria
+- Terminal WS connects at `/ws/project/:projectName/terminal/:id`
+- Chat WS connects at `/ws/project/:projectName/chat/:sessionId`
+- No query params for project identification
+- Both foreground and daemon server blocks handle new paths