@hienlh/ppm 0.1.0

package/plans/260314-2009-ppm-implementation/phase-08-cli-commands.md

@@ -0,0 +1,143 @@
+# Phase 8: CLI Commands
+
+**Owner:** backend-dev
+**Priority:** Medium
+**Depends on:** Phase 2, Phase 6, Phase 7
+**Effort:** Medium
+
+## Overview
+
+Implement remaining CLI commands that call Service Layer directly. All commands share project resolution logic (CWD auto-detect + `-p` flag).
+
+## Files
+```
+src/cli/commands/projects.ts
+src/cli/commands/config.ts
+src/cli/commands/git.ts
+src/cli/commands/chat.ts
+```
+
+## Commands
+
+### ppm projects
+```bash
+ppm projects list                     # Table: name, path, branch, status
+ppm projects add <path> [--name <n>]  # Add project to config
+ppm projects remove <name-or-path>    # Remove from config
+```
+
+### ppm config
+```bash
+ppm config get <key>                  # e.g., ppm config get port
+ppm config set <key> <value>          # e.g., ppm config set port 9090
+```
+
+### ppm git
+All git commands accept `-p <project>` flag. Default: CWD auto-detect.
+
+```bash
+ppm git status [-p proj]              # Show status (like git status --short)
+ppm git log [-p proj] [-n 20]         # Show recent commits
+ppm git diff [-p proj] [ref1] [ref2]  # Show diff
+ppm git stage [-p proj] <files...>    # Stage files (or "." for all)
+ppm git unstage [-p proj] <files...>  # Unstage files
+ppm git commit [-p proj] -m "msg"     # Commit staged changes
+ppm git push [-p proj]                # Push to remote
+ppm git pull [-p proj]                # Pull from remote
+ppm git branch create [-p proj] <name> [--from <ref>]
+ppm git branch checkout [-p proj] <name>
+ppm git branch delete [-p proj] <name> [--force]
+ppm git branch merge [-p proj] <source>
+```
+
+### ppm chat
+```bash
+ppm chat list [-p proj]                            # List sessions (table: id, provider, title, date)
+ppm chat create [-p proj] [--provider claude]      # Create session, print session ID
+ppm chat send [-p proj] <session-id> "message"     # Send message, stream response to stdout
+ppm chat resume [-p proj] <session-id>             # Interactive mode (stdin/stdout)
+ppm chat delete [-p proj] <session-id>             # Delete session
+```
+
+`ppm chat send` streams response to stdout as it arrives. Useful for AI-to-AI orchestration:
+```bash
+# AI agent sends a task to PPM chat
+RESPONSE=$(ppm chat send -p myapp abc123 "Fix the bug in auth.ts")
+```
+
+`ppm chat resume` enters interactive mode:
+```
+You: Fix the auth bug
+Claude: I'll read the file...
+[Tool: Read auth.ts] Allow? (y/n): y
+Claude: Found the issue...
+You:
+```
+
+## Implementation Pattern
+
+All commands follow same pattern:
+```typescript
+// commands/git.ts
+import { Command } from 'commander';
+
+export function registerGitCommands(program: Command) {
+  const git = program.command('git').description('Git operations');
+
+  git.command('status')
+    .option('-p, --project <name>', 'Project name')
+    .action(async (options) => {
+      const project = resolveProject(options);
+      const gitService = new GitService();
+      const status = await gitService.status(project.path);
+      // Pretty print to terminal
+      printGitStatus(status);
+    });
+
+  // ... more subcommands
+}
+```
+
+## Output Formatting
+
+- Use colors (via `chalk` or Bun built-in ANSI) for terminal output
+- Tables for list commands (projects list, chat list)
+- Git status: colored M/A/D indicators like git
+- Streaming output for chat send
+
+## Success Criteria
+
+**Project Resolution:**
+- [ ] `-p myproject` flag resolves project by name
+- [ ] No `-p` flag + CWD inside registered project → auto-detects
+- [ ] No `-p` flag + CWD not in any project → clear error: "Not in a registered project. Use -p <name>"
+
+**ppm projects:**
+- [ ] `ppm projects list` → formatted table with columns: Name, Path, Branch, Status
+- [ ] `ppm projects add /path/to/repo --name myrepo` → adds project, confirms with message
+- [ ] `ppm projects add` with duplicate name → error message
+- [ ] `ppm projects remove myrepo` → removes, confirms with message
+
+**ppm config:**
+- [ ] `ppm config get port` → prints current port value
+- [ ] `ppm config set port 9090` → updates config file, confirms
+- [ ] `ppm config get nonexistent` → error message
+
+**ppm git:**
+- [ ] `ppm git status` → colored output matching git status --short format (M=yellow, A=green, D=red)
+- [ ] `ppm git log -n 5` → shows last 5 commits with hash, message, author, date
+- [ ] `ppm git stage .` → stages all files, prints count
+- [ ] `ppm git commit -m "test"` → creates commit, prints hash
+- [ ] `ppm git commit` with nothing staged → "Nothing to commit" error
+- [ ] `ppm git push` → pushes to remote, prints result
+- [ ] `ppm git branch create feature-x` → creates branch, confirms
+- [ ] `ppm git branch checkout feature-x` → switches branch, confirms
+- [ ] `ppm git branch delete feature-x` → deletes branch, confirms
+
+**ppm chat:**
+- [ ] `ppm chat list` → table with columns: ID, Provider, Title, Date
+- [ ] `ppm chat create` → creates session, prints session ID
+- [ ] `ppm chat send <id> "fix the bug"` → streams response to stdout in real-time
+- [ ] `ppm chat resume <id>` → interactive mode with `You:` / `Claude:` prompts
+- [ ] Tool approval in interactive mode: `[Tool: Bash] Allow? (y/n):` prompt
+- [ ] `ppm chat delete <id>` → deletes session, confirms

package/plans/260314-2009-ppm-implementation/phase-09-pwa-build-deploy.md

@@ -0,0 +1,209 @@
+# Phase 9: PWA + Build + Deploy
+
+**Owner:** Lead
+**Priority:** Medium
+**Depends on:** All previous phases
+**Effort:** Medium
+
+## Overview
+
+PWA configuration, production build pipeline, single binary compilation, CI/CD for cross-platform releases.
+
+## PWA Setup
+
+### vite-plugin-pwa Config
+```typescript
+// vite.config.ts
+import { VitePWA } from 'vite-plugin-pwa';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    VitePWA({
+      registerType: 'autoUpdate',
+      manifest: {
+        name: 'PPM - Personal Project Manager',
+        short_name: 'PPM',
+        description: 'Mobile-first web IDE for managing code projects',
+        theme_color: '#0f172a',
+        background_color: '#0f172a',
+        display: 'standalone',
+        orientation: 'any',
+        icons: [
+          { src: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+          { src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+        ],
+      },
+      workbox: {
+        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
+        // Cache UI shell for offline. API calls always need network.
+        runtimeCaching: [
+          {
+            urlPattern: /^https?:\/\/.*\/api\//,
+            handler: 'NetworkOnly', // API = always online
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+### PWA Features
+- Install prompt on mobile
+- Offline: UI shell loads, shows "No connection" for API features
+- App icon + splash screen
+
+## Build Pipeline
+
+### scripts/build.ts
+```typescript
+import { $ } from 'bun';
+
+// 1. Build frontend (Vite)
+await $`bun run vite build --outDir dist/web`;
+
+// 2. Compile backend + embedded frontend into single binary
+await $`bun build src/index.ts --compile --outfile dist/ppm`;
+
+// For cross-platform:
+// bun build src/index.ts --compile --target=bun-linux-x64 --outfile dist/ppm-linux-x64
+// bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile dist/ppm-darwin-arm64
+```
+
+### Static File Embedding
+```typescript
+// server/routes/static.ts
+// In dev: proxy to Vite dev server
+// In prod: serve from embedded dist/web/ directory
+
+if (process.env.NODE_ENV === 'production') {
+  // Serve built files
+  app.use('/*', serveStatic({ root: './dist/web' }));
+  // SPA fallback
+  app.get('*', (c) => c.html(readFileSync('./dist/web/index.html', 'utf-8')));
+} else {
+  // Proxy to Vite dev server
+  // Or just run Vite separately
+}
+```
+
+### Package.json Scripts
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"bun run --hot src/index.ts start\" \"bun run vite\"",
+    "build": "bun run scripts/build.ts",
+    "build:linux": "bun build src/index.ts --compile --target=bun-linux-x64 --outfile dist/ppm-linux-x64",
+    "build:mac-arm": "bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile dist/ppm-darwin-arm64",
+    "build:mac-x64": "bun build src/index.ts --compile --target=bun-darwin-x64 --outfile dist/ppm-darwin-x64"
+  }
+}
+```
+
+## CI/CD (GitHub Actions)
+
+### .github/workflows/release.yml
+```yaml
+name: Release
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: bun-linux-x64
+            artifact: ppm-linux-x64
+          - os: macos-latest
+            target: bun-darwin-arm64
+            artifact: ppm-darwin-arm64
+          - os: macos-13
+            target: bun-darwin-x64
+            artifact: ppm-darwin-x64
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run vite build --outDir dist/web
+      - run: bun build src/index.ts --compile --target=${{ matrix.target }} --outfile dist/${{ matrix.artifact }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/${{ matrix.artifact }}
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            ppm-linux-x64/ppm-linux-x64
+            ppm-darwin-arm64/ppm-darwin-arm64
+            ppm-darwin-x64/ppm-darwin-x64
+```
+
+### Dockerfile (fallback)
+```dockerfile
+FROM oven/bun:1.2-alpine
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --production
+COPY dist/ ./dist/
+COPY src/ ./src/
+EXPOSE 8080
+CMD ["bun", "run", "src/index.ts", "start"]
+```
+
+## Deployment Docs
+
+### Local
+```bash
+# Install
+curl -fsSL https://github.com/user/ppm/releases/latest/download/ppm-$(uname -s | tr A-Z a-z)-$(uname -m) -o /usr/local/bin/ppm
+chmod +x /usr/local/bin/ppm
+
+# Setup
+ppm init
+ppm start
+```
+
+### VPS
+```bash
+scp ppm-linux-x64 user@vps:/usr/local/bin/ppm
+scp ppm.yaml user@vps:/etc/ppm/config.yaml
+ssh user@vps "ppm start -c /etc/ppm/config.yaml -d"
+```
+
+## Static File Embedding (NEEDS INVESTIGATION)
+
+**Known issue:** `bun build --compile` bundles JS but does NOT auto-embed static files (HTML, CSS, images).
+
+**Options to investigate:**
+1. Use `Bun.file()` with `import.meta.dir` to reference files relative to binary
+2. Use `import with { type: "file" }` syntax to embed at build time
+3. Inline frontend assets into a JS module at build time (custom build step)
+4. Ship `dist/web/` alongside binary (not single-file, but simpler)
+
+**TODO:** Test each approach before Phase 9 implementation. Research `bun build --compile` static file embedding in Bun docs.
+
+## Success Criteria
+
+- [ ] PWA installable on mobile: "Add to Home Screen" prompt appears
+- [ ] PWA offline: UI shell loads without network, shows "No connection" for API features
+- [ ] `bun run build` completes without errors, produces binary + web assets
+- [ ] Built binary starts server and serves frontend at `http://localhost:<port>/`
+- [ ] Frontend served by binary is fully functional (not blank page)
+- [ ] API routes work through built binary (not just dev mode)
+- [ ] Cross-platform binaries compile in CI (linux-x64, darwin-arm64, darwin-x64)
+- [ ] GitHub Release created with binaries on tag push (v* tags)
+- [ ] Docker image builds and runs: `docker run -p 8080:8080 ppm` serves app
+- [ ] Fresh install flow works: download binary → `ppm init` → `ppm start` → browser opens → app works
+- [ ] App icon shows correctly on mobile homescreen

package/plans/260314-2009-ppm-implementation/phase-10-testing.md

@@ -0,0 +1,311 @@
+# Phase 10: Testing
+
+**Owner:** tester
+**Priority:** High
+**Depends on:** Runs continuously after each phase completes
+**Effort:** Large
+
+## Overview
+
+Comprehensive unit + integration tests for both backend services AND frontend logic. E2E smoke tests for full flow.
+
+## Test Framework
+
+- **Runner:** `bun test` (built-in, Jest-compatible)
+- **HTTP testing:** Hono test client (`app.request()`)
+- **WS testing:** Native WebSocket client in Bun
+- **Frontend logic testing:** `bun test` for store/lib/hook logic (no DOM needed for pure logic)
+
+## Test Structure
+```
+tests/
+├── setup.ts                      # Global setup (test config, temp dirs)
+├── unit/
+│   ├── services/
+│   │   ├── config.service.test.ts
+│   │   ├── project.service.test.ts
+│   │   ├── file.service.test.ts
+│   │   ├── git.service.test.ts
+│   │   ├── terminal.service.test.ts
+│   │   └── chat.service.test.ts
+│   ├── providers/
+│   │   ├── claude-agent-sdk.test.ts
+│   │   └── registry.test.ts
+│   ├── cli/
+│   │   └── project-resolver.test.ts
+│   ├── server/
+│   │   ├── resolve-project.test.ts
+│   │   └── auth-middleware.test.ts
+│   └── web/
+│       ├── stores/
+│       │   ├── tab.store.test.ts
+│       │   ├── project.store.test.ts
+│       │   └── settings.store.test.ts
+│       ├── lib/
+│       │   ├── api-client.test.ts
+│       │   ├── ws-client.test.ts
+│       │   └── git-graph-layout.test.ts
+│       └── hooks/
+│           └── use-websocket.test.ts
+├── integration/
+│   ├── api/
+│   │   ├── auth.test.ts
+│   │   ├── projects.test.ts
+│   │   ├── files.test.ts
+│   │   └── git.test.ts
+│   └── ws/
+│       ├── terminal.test.ts
+│       └── chat.test.ts
+└── e2e/
+    └── smoke.test.ts             # Full flow: init → start → use → stop
+```
+
+## Test Strategy Per Phase
+
+### Phase 2 Tests (Backend Core)
+
+**Config Service:**
+- [ ] Loads config from `./ppm.yaml` when present
+- [ ] Falls back to `~/.ppm/config.yaml` when no local config
+- [ ] Creates default config with generated auth token on first run
+- [ ] `get('port')` returns configured port
+- [ ] `set('port', 9090)` persists change to file
+- [ ] Invalid YAML file → throws descriptive error
+
+**Project Service:**
+- [ ] `add("/path/to/repo", "myrepo")` adds project to config
+- [ ] `add` with duplicate name → throws error
+- [ ] `remove("myrepo")` removes project from config
+- [ ] `list()` returns all registered projects
+- [ ] `resolve("myrepo")` returns project by name
+- [ ] `resolve` from CWD → auto-detects project when CWD is inside registered project path
+- [ ] `resolve("nonexistent")` → throws "Project not found" error
+- [ ] `scanForGitRepos(dir)` finds `.git` directories recursively
+
+**Auth Middleware:**
+- [ ] Valid Bearer token → passes, sets context
+- [ ] Missing Authorization header → 401 `{ ok: false, error: "Unauthorized" }`
+- [ ] Invalid token → 401
+- [ ] `auth.enabled: false` in config → all requests pass without token
+- [ ] Token from config matches what's checked
+
+**Server:**
+- [ ] Server starts on configured port
+- [ ] `GET /api/health` returns 200
+- [ ] SPA fallback: `GET /nonexistent` returns `index.html` (not 404)
+- [ ] API 404: `GET /api/nonexistent` returns 404 JSON
+
+**Resolve Project Helper:**
+- [ ] `resolveProjectPath("ppm")` → returns path from config
+- [ ] `resolveProjectPath("/absolute/path")` → validates path is within registered project
+- [ ] `resolveProjectPath("../escape")` → throws (path traversal)
+
+### Phase 3 Tests (Frontend Logic)
+
+**Tab Store:**
+- [ ] `openTab({type: 'terminal', title: 'Terminal'})` adds tab and returns id
+- [ ] `openTab` with duplicate type+metadata → returns existing tab id (no duplicate)
+- [ ] `closeTab(id)` removes tab from list
+- [ ] `closeTab` on last tab → activeTabId becomes null
+- [ ] `setActiveTab(id)` updates activeTabId
+- [ ] `updateTab(id, {title: 'new'})` updates tab properties
+- [ ] Closing active tab → activates previous tab (not first, not null)
+
+**API Client:**
+- [ ] `get<T>('/api/projects')` unwraps `{ok: true, data: [...]}` → returns `[...]`
+- [ ] Server returns `{ok: false, error: "Not found"}` → throws Error with "Not found" message
+- [ ] Server returns HTTP 500 → throws Error
+- [ ] Bearer token header sent on every request when token is set
+- [ ] No Authorization header when token is null/undefined
+
+**WS Client:**
+- [ ] Connects to WebSocket URL
+- [ ] Auto-reconnects on close with exponential backoff (1s, 2s, 4s)
+- [ ] Max reconnect delay caps at 30s
+- [ ] `send()` queues messages if not connected, sends on reconnect
+- [ ] `onMessage` callback fires for incoming messages
+- [ ] `disconnect()` stops reconnect attempts
+
+**Git Graph Layout:**
+- [ ] Single branch → all commits in lane 0
+- [ ] Two branches → merge commit connects lanes correctly
+- [ ] Lane reuse: closed branch lane gets reused by next branch
+- [ ] Empty commits list → returns empty layout
+
+### Phase 4 Tests (File Explorer)
+
+**File Service:**
+- [ ] `getTree(projectPath)` returns nested FileNode structure
+- [ ] `getTree` excludes `.git/`, `node_modules/`
+- [ ] `readFile(path)` returns content as string
+- [ ] `readFile` for binary file → returns base64 with encoding flag
+- [ ] `writeFile(path, content)` creates/updates file
+- [ ] `createFile(path, 'file')` creates empty file
+- [ ] `createFile(path, 'directory')` creates directory
+- [ ] `deleteFile(path)` removes file
+- [ ] `renameFile(old, new)` renames file
+- [ ] Path traversal: `readFile("../../etc/passwd")` → throws error
+- [ ] Access `.git/config` → throws error
+- [ ] Access `.env` → throws error
+
+**File API Integration:**
+- [ ] `GET /api/files/tree/myproject` returns file tree (project resolved by name)
+- [ ] `GET /api/files/read?path=src/index.ts` returns file content
+- [ ] `PUT /api/files/write` with `{path, content}` writes file
+- [ ] `DELETE /api/files/delete` with `{path}` removes file
+- [ ] Invalid project name → 404
+- [ ] Path outside project → 403
+
+### Phase 5 Tests (Terminal)
+
+**Terminal Service:**
+- [ ] `create({projectPath})` spawns shell process and returns session
+- [ ] `get(id)` returns existing session
+- [ ] `get(nonexistent)` returns undefined
+- [ ] `write(id, "ls\n")` sends input to PTY
+- [ ] `onData(id, handler)` receives shell output
+- [ ] `kill(id)` terminates process and removes session
+- [ ] `list()` returns all active sessions
+- [ ] Output buffer: last 10KB of output stored per session
+
+**Terminal WS Integration:**
+- [ ] Connect to `/ws/terminal/:id` → creates new PTY if not exists
+- [ ] Send keystroke via WS → appears in PTY
+- [ ] PTY output → arrives via WS message
+- [ ] Send resize control message → PTY resizes (if supported)
+- [ ] Disconnect WS → PTY stays alive for 30s
+- [ ] Reconnect within 30s → receives buffered output
+- [ ] Reconnect after timeout → session dead, returns error
+- [ ] Multiple WS clients to same session → both receive output
+
+### Phase 6 Tests (Git)
+
+**Git Service (using real temp repos):**
+- [ ] `status(path)` → returns modified/staged/untracked files
+- [ ] `stage(path, ["file.txt"])` → file appears in staged list
+- [ ] `unstage(path, ["file.txt"])` → file moves back to unstaged
+- [ ] `commit(path, "msg")` → creates commit, returns hash
+- [ ] `commit` with nothing staged → throws error
+- [ ] `branches(path)` → returns branch list with current marked
+- [ ] `createBranch(path, "feature")` → branch exists
+- [ ] `checkout(path, "feature")` → current branch changes
+- [ ] `deleteBranch(path, "feature")` → branch removed
+- [ ] `deleteBranch` on current branch → throws error
+- [ ] `graphData(path)` → returns commits with parents, refs, branch info
+- [ ] `graphData` uses simple-git `.log()` (not manual parse) → no garbled data on multi-line commit messages
+- [ ] `diff(path)` → returns unified diff string
+- [ ] `fileDiff(path, "file.txt")` → returns diff for specific file
+- [ ] `getCreatePrUrl(path, "feature")` → returns GitHub PR URL from remote
+
+**Git API Integration:**
+- [ ] `GET /api/git/status/myproject` → status JSON (project resolved by name)
+- [ ] `POST /api/git/commit` with `{project: "myproject", message: "test"}` → creates commit
+- [ ] `GET /api/git/graph/myproject?max=50` → returns graph data with ≤50 commits
+- [ ] All git routes resolve project by NAME, not path
+
+### Phase 7 Tests (AI Chat)
+
+**Provider Registry:**
+- [ ] `register(provider)` adds provider
+- [ ] `get("claude")` returns Claude provider
+- [ ] `get("nonexistent")` returns undefined
+- [ ] `list()` returns all provider infos
+- [ ] `getDefault()` returns first registered provider
+
+**Chat Service (mock provider):**
+- [ ] `createSession("mock", config)` → returns session with id
+- [ ] `sendMessage("mock", sessionId, "hello")` → yields ChatEvent stream
+- [ ] `listSessions()` → returns session list
+- [ ] `deleteSession("mock", sessionId)` → session removed from list
+
+**Chat WS Integration:**
+- [ ] Connect to `/ws/chat/:sessionId` → WS opens
+- [ ] Send `{type: "message", content: "hello"}` → receives streamed response events
+- [ ] Receive `{type: "approval_request"}` → send `{type: "approval_response", approved: true}` → tool executes
+- [ ] Approval denied → AI receives denial message
+- [ ] `{type: "done"}` received at end of response
+- [ ] Error in provider → `{type: "error", message: "..."}` sent via WS
+
+**Chat REST API:**
+- [ ] `GET /api/chat/sessions` → list of all sessions
+- [ ] `GET /api/chat/sessions/:id/messages` → message history for session
+- [ ] Reconnect flow: disconnect WS → GET messages via REST → reconnect WS → no messages lost
+
+### Phase 8 Tests (CLI)
+
+**Project Resolver:**
+- [ ] `-p myproject` flag → resolves to correct project
+- [ ] No flag, CWD inside project → auto-detects
+- [ ] No flag, CWD not in any project → throws descriptive error
+
+**CLI Commands (capture stdout):**
+- [ ] `ppm projects list` → outputs table with project names and paths
+- [ ] `ppm projects add /tmp/repo --name test` → adds project
+- [ ] `ppm git status -p myproject` → outputs colored status
+- [ ] `ppm git commit -p myproject -m "test"` → commits and prints hash
+- [ ] `ppm chat list -p myproject` → outputs session table
+
+### Phase 9 Tests (Build)
+- [ ] `bun run build` completes without errors
+- [ ] Built binary serves frontend at `http://localhost:<port>/`
+- [ ] Built binary serves API at `/api/*`
+- [ ] PWA manifest accessible at expected path
+
+## Test Utilities
+
+```typescript
+// tests/setup.ts
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+
+// Create temp git repo for testing
+export function createTestRepo(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'ppm-test-'));
+  execSync('git init', { cwd: dir });
+  execSync('git commit --allow-empty -m "init"', { cwd: dir });
+  return dir;
+}
+
+// Create test config
+export function createTestConfig(overrides?: Partial<PpmConfig>): PpmConfig {
+  return { port: 0, host: '127.0.0.1', auth: { enabled: false }, projects: [], ...overrides };
+}
+
+// Create test Hono app with test config
+export function createTestApp(config?: Partial<PpmConfig>): Hono {
+  // Wire up routes with test config, return app instance
+}
+
+// Wait for WS message matching predicate
+export async function waitForWsMessage(ws: WebSocket, predicate: (msg: any) => boolean, timeout = 5000): Promise<any> {
+  // Returns first message matching predicate, throws on timeout
+}
+```
+
+## Mock Strategy
+
+- **Git operations:** Use real temp git repos (no mocking git)
+- **AI Provider:** Mock provider implementing AIProvider interface (no real API calls)
+- **File system:** Use temp directories (real FS, no mocking)
+- **WebSocket:** Use real WS connections to test server
+- **Auth:** Test with both `auth.enabled: true` (with token) and `auth.enabled: false`
+
+## Coverage Target
+
+- Services: 80%+
+- API routes: 80%+
+- CLI commands: 70%+
+- Frontend stores/lib/hooks: 80%+
+- Frontend components: Manual testing (visual verification)
+
+## Success Criteria
+
+- [ ] `bun test` runs all tests (unit + integration)
+- [ ] No tests use fake data/mocks that mask real behavior
+- [ ] Git tests use real temp repos with real git operations
+- [ ] API tests use real HTTP requests via Hono test client
+- [ ] WS tests verify full protocol correctness (connect, send, receive, reconnect)
+- [ ] Frontend store tests verify state transitions and edge cases
+- [ ] API client tests verify envelope unwrapping and error handling
+- [ ] All tests pass before merge — failing tests block PR
+- [ ] Test output includes file/line for failures (easy to locate)