@hienlh/ppm 0.1.0

package/plans/260314-2009-ppm-implementation/phase-02-backend-core.md

@@ -0,0 +1,148 @@
+# Phase 2: Backend Core (Server + CLI + Config)
+
+**Owner:** backend-dev
+**Priority:** Critical
+**Depends on:** Phase 1
+**Effort:** Medium
+
+## Overview
+
+Hono HTTP server, WebSocket upgrade, config loading, auth middleware, static file serving. CLI `init`, `start`, `stop`, `open` commands.
+
+## Key Insights
+
+- Hono on Bun has built-in WebSocket support via `Bun.serve`
+- Config loaded from `ppm.yaml` via js-yaml, validated at startup
+- Auth = simple Bearer token header check
+- Static files = serve Vite build output from `dist/web/`
+
+## Files to Create/Modify
+
+```
+src/
+├── server/
+│   ├── index.ts              # Hono app, mount routes, WS upgrade
+│   ├── middleware/auth.ts     # Token auth
+│   ├── routes/static.ts       # Serve SPA with fallback to index.html
+│   └── routes/projects.ts     # GET /api/projects, POST /api/projects
+├── services/
+│   ├── config.service.ts      # Load/save ppm.yaml
+│   └── project.service.ts     # Project CRUD (add/remove/list)
+├── cli/
+│   ├── index.ts               # Commander.js program setup
+│   ├── commands/init.ts       # Scan .git folders, interactive setup
+│   ├── commands/start.ts      # Start Hono server (+ daemon mode)
+│   ├── commands/stop.ts       # Kill daemon by PID file
+│   ├── commands/open.ts       # Open browser to http://localhost:PORT
+│   └── utils/project-resolver.ts  # CWD detect + -p flag
+└── index.ts                   # Wire CLI → commands
+```
+
+## Implementation Steps
+
+### 1. Config Service
+```typescript
+// config.service.ts
+class ConfigService {
+  private config: PpmConfig;
+  load(path?: string): PpmConfig    // Default: ~/.ppm/config.yaml or ./ppm.yaml
+  save(): void
+  get<K extends keyof PpmConfig>(key: K): PpmConfig[K]
+  set<K extends keyof PpmConfig>(key: K, value: PpmConfig[K]): void
+}
+```
+- Search order: `--config` flag → `./ppm.yaml` → `~/.ppm/config.yaml`
+- Create default config on first run
+
+### 2. Project Service
+```typescript
+class ProjectService {
+  constructor(private config: ConfigService)
+  list(): ProjectInfo[]
+  add(path: string, name?: string): void
+  remove(nameOrPath: string): void
+  resolve(nameOrPath?: string): Project  // CWD or -p flag
+  scanForGitRepos(dir: string): string[] // Find .git folders recursively
+}
+```
+
+### 3. Hono Server
+```typescript
+// server/index.ts
+const app = new Hono()
+app.use('/api/*', authMiddleware)
+app.route('/api/projects', projectRoutes)
+// WS upgrade handled at Bun.serve level
+// Static files: serve dist/web/ with SPA fallback
+```
+
+### 4. Auth Middleware
+- Check `Authorization: Bearer <token>` header
+- Skip auth if `config.auth.enabled === false`
+- Return 401 on failure
+
+**Auth flow (minimal):**
+- Token stored in `ppm.yaml` → `auth.token` field
+- Generated on `ppm init` (random 32-char hex)
+- Browser: on first visit, if `auth.enabled === true`, show password input screen
+- User enters token → stored in localStorage → sent as Bearer header on all API calls
+- No user/password DB — single shared token from config
+- Config example:
+  ```yaml
+  auth:
+    enabled: true
+    token: "a1b2c3..."  # auto-generated, user can change
+  ```
+
+**Frontend auth screen** (`src/web/components/auth/login-screen.tsx`):
+- Full-screen centered card: "Enter Access Token" + input + submit
+- On submit: store token in localStorage, redirect to app
+- On 401 from any API call: clear localStorage, show login screen
+
+### 5. CLI Commands
+- `ppm init` — interactive: scan parent dir for .git, prompt to add, create config
+- `ppm start` — start Hono server, optionally daemonize (`-d` flag → detach process, write PID to `~/.ppm/ppm.pid`)
+- `ppm stop` — read PID file, kill process
+- `ppm open` — `open http://localhost:${port}` (macOS) / `xdg-open` (Linux)
+
+### 6. Project Resolver
+```typescript
+function resolveProject(options: { project?: string }): Project {
+  if (options.project) return projectService.resolve(options.project);
+  const cwd = process.cwd();
+  const match = projectService.list().find(p => cwd.startsWith(p.path));
+  if (match) return match;
+  throw new Error('Not in a registered project. Use -p <name>');
+}
+```
+
+### 7. Shared Project Resolver (`src/server/helpers/resolve-project.ts`)
+
+**[V2 FIX]** All API routes must resolve project by NAME first, fallback to path:
+```typescript
+export function resolveProjectPath(nameOrPath: string): string {
+  const projects = configService.get("projects");
+  const byName = projects.find(p => p.name === nameOrPath);
+  if (byName) return resolve(byName.path);
+  const abs = resolve(nameOrPath);
+  const allowed = projects.some(p => abs === p.path || abs.startsWith(p.path + "/"));
+  if (!allowed) throw new Error(`Project not found: ${nameOrPath}`);
+  return abs;
+}
+```
+Import this in every route file (files.ts, git.ts, projects.ts).
+
+## Success Criteria
+
+- [ ] `ppm init` scans current dir, creates config file with auto-generated auth token
+- [ ] `ppm start` starts HTTP server on configured port
+- [ ] `ppm start -d` runs as daemon, writes PID file; `ppm stop` reads PID and kills process
+- [ ] `GET /api/projects` with valid Bearer token returns project list as `{ ok: true, data: [...] }`
+- [ ] `GET /api/projects` without token returns 401 `{ ok: false, error: "Unauthorized" }`
+- [ ] `GET /api/projects` with `auth.enabled: false` in config returns data without token
+- [ ] `ppm open` opens `http://localhost:<port>` in default browser
+- [ ] `resolveProjectPath("ppm")` returns correct filesystem path from config
+- [ ] `resolveProjectPath("nonexistent")` throws descriptive error
+- [ ] Config service loads from `./ppm.yaml` → `~/.ppm/config.yaml` fallback chain
+- [ ] Config service creates default config if none exists
+- [ ] Static route serves `dist/web/index.html` for all non-API paths (SPA fallback)

package/plans/260314-2009-ppm-implementation/phase-03-frontend-shell.md

@@ -0,0 +1,256 @@
+# Phase 3: Frontend Shell (Tab System + Layout)
+
+**Owner:** frontend-dev
+**Priority:** Critical
+**Depends on:** Phase 1
+**Effort:** Medium
+
+## Overview
+
+React app shell: tab bar, tab content area, sidebar, mobile navigation. This is the foundation all other UI features plug into.
+
+## Key Insights
+
+- Mobile-first: bottom tab bar on mobile, top tab bar on desktop
+- Each tab = lazy-loaded React component
+- zustand store manages tab CRUD + active tab
+- Sidebar: project list + file explorer (collapsible on mobile)
+
+## UI Design System — "Slate Dark"
+
+See full spec: [UI Style Guide](../reports/researcher-260314-2232-ui-style.md)
+
+### Color Palette
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Background | `#0f1419` | Main app bg (OLED-friendly) |
+| Surface | `#1a1f2e` | Cards, panels, modals |
+| Surface Elevated | `#252d3d` | Hover states |
+| Border | `#404854` | Dividers, input borders |
+| Text Primary | `#e5e7eb` | Body text (13.5:1 contrast) |
+| Text Secondary | `#9ca3af` | Hints, timestamps |
+| Primary Blue | `#3b82f6` | Buttons, active tabs, focus rings |
+| Success Green | `#10b981` | Commit, save |
+| Error Red | `#ef4444` | Errors, deletions |
+| Warning Orange | `#f59e0b` | Conflicts, unsaved |
+
+### Typography
+- UI font: **Geist Sans** (Vercel's dev tool font)
+- Code font: **Geist Mono** (clear `1lI` distinction, ligatures)
+- Default UI text: 14px / weight 400
+- Editor: 13px mono
+- Terminal: 12px mono
+
+### Component Rules
+- Touch targets: **44px minimum** height
+- Border radius: 8px default, 12px for cards/modals, 6px for inputs
+- **Dual theme:** Dark (default) + Light mode, togglable via settings
+- shadcn/ui with custom CSS variables for both themes
+- Icon library: **Lucide** (lightweight, works on both themes)
+- CodeMirror theme: custom from Slate Dark palette (dark) + custom light variant
+- Fonts: Google Fonts CDN (Geist Sans + Geist Mono)
+- Notifications: bottom-left toast (desktop), bottom full-width toast (mobile) — one-hand friendly
+
+### Light Theme Palette ("Slate Light")
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Background | `#ffffff` | Main app bg |
+| Surface | `#f8fafc` | Cards, panels |
+| Surface Elevated | `#f1f5f9` | Hover states |
+| Border | `#e2e8f0` | Dividers |
+| Text Primary | `#1a1f2e` | Body text |
+| Text Secondary | `#64748b` | Hints |
+| Primary Blue | `#2563eb` | Buttons, active tabs |
+| Success Green | `#059669` | Commit, save |
+| Error Red | `#dc2626` | Errors |
+| Warning Orange | `#d97706` | Conflicts |
+
+### Theme Toggle
+- Store preference in `settings.store.ts` → persisted to localStorage
+- Options: "light" | "dark" | "system" (follows OS `prefers-color-scheme`)
+- Default: "system"
+- Toggle in settings tab + quick toggle icon in top bar / mobile header
+- Tailwind `darkMode: 'class'` → toggle `<html class="dark">`
+- CodeMirror: switch between custom dark/light theme extensions
+
+### Mobile-Specific
+- Bottom nav: 64px height, max 5 tabs, icon + label
+- Active tab indicator: top border (blue)
+- Drawer sidebar: slide-in overlay with backdrop (not toggle)
+
+## Files to Create
+
+```
+src/web/
+├── index.html
+├── main.tsx                    # React entry + PWA register
+├── app.tsx                     # Layout: sidebar + tab area
+├── components/
+│   ├── layout/
+│   │   ├── tab-bar.tsx         # Scrollable tab bar
+│   │   ├── tab-content.tsx     # Renders active tab component
+│   │   ├── sidebar.tsx         # Project list + file tree
+│   │   └── mobile-nav.tsx      # Bottom nav for mobile
+│   ├── projects/
+│   │   ├── project-list.tsx    # List of registered projects
+│   │   └── project-card.tsx    # Single project card
+│   └── ui/                     # shadcn/ui (already installed)
+├── stores/
+│   ├── tab.store.ts            # Tab CRUD + active tab
+│   ├── project.store.ts        # Current project + project list
+│   └── settings.store.ts       # Theme, layout prefs
+├── hooks/
+│   └── use-websocket.ts        # Generic WS hook with reconnect
+├── lib/
+│   ├── api-client.ts           # fetch wrapper for /api/*
+│   └── ws-client.ts            # WS client class with reconnect
+└── styles/
+    └── globals.css             # Tailwind imports + custom vars
+```
+
+## Implementation Steps
+
+### 1. Tab Store (zustand)
+```typescript
+interface Tab {
+  id: string;
+  type: 'projects' | 'terminal' | 'chat' | 'editor' | 'git-graph' | 'git-status' | 'git-diff' | 'settings';
+  title: string;
+  metadata?: Record<string, any>; // e.g., filePath for editor, sessionId for chat
+  closable: boolean;
+}
+
+interface TabStore {
+  tabs: Tab[];
+  activeTabId: string | null;
+  openTab(tab: Omit<Tab, 'id'>): string;  // returns new tab id
+  closeTab(id: string): void;
+  setActiveTab(id: string): void;
+  updateTab(id: string, updates: Partial<Tab>): void;
+}
+```
+
+### 2. App Layout
+```
+Desktop:
+┌──────────┬────────────────────────────┐
+│ Sidebar  │ [Tab1] [Tab2] [Tab3] [+]   │
+│ (280px)  ├────────────────────────────┤
+│ Projects │                            │
+│ Files    │     Active Tab Content      │
+│          │                            │
+└──────────┴────────────────────────────┘
+
+Mobile:
+┌────────────────────────────────────────┐
+│ ☰  PPM - Project Name          ⚙️     │
+├────────────────────────────────────────┤
+│                                        │
+│         Active Tab Content             │
+│                                        │
+├────────────────────────────────────────┤
+│ [Projects] [Terminal] [Chat] [Git] [+] │
+└────────────────────────────────────────┘
+```
+
+### 3. Tab Content (lazy loaded)
+```typescript
+const TAB_COMPONENTS: Record<Tab['type'], React.LazyExoticComponent<any>> = {
+  'projects': lazy(() => import('./projects/project-list')),
+  'terminal': lazy(() => import('./terminal/terminal-tab')),
+  'chat': lazy(() => import('./chat/chat-tab')),
+  'editor': lazy(() => import('./editor/code-editor')),
+  'git-graph': lazy(() => import('./git/git-graph')),
+  'git-status': lazy(() => import('./git/git-status-panel')),
+  'git-diff': lazy(() => import('./git/git-diff-tab')),
+  'settings': lazy(() => import('./settings/settings-tab')),
+};
+```
+
+### 4. API Client
+```typescript
+class ApiClient {
+  constructor(private baseUrl: string, private token?: string)
+  async get<T>(path: string): Promise<T>
+  async post<T>(path: string, body?: any): Promise<T>
+  async delete(path: string): Promise<void>
+}
+```
+
+### 5. WebSocket Client
+```typescript
+class WsClient {
+  constructor(private url: string)
+  connect(): void
+  disconnect(): void
+  send(data: string | ArrayBuffer): void
+  onMessage(handler: (data: MessageEvent) => void): void
+  // Auto-reconnect with exponential backoff
+  // Heartbeat ping/pong
+}
+```
+
+### 6. Project List Tab
+- Fetch `GET /api/projects` on mount
+- Display project cards with name, path, git status indicator
+- Click project → set as active, open file explorer in sidebar
+
+### 7. Mobile Responsiveness
+- Tailwind breakpoints: `sm:`, `md:`, `lg:`
+- Tab bar: bottom on mobile (`fixed bottom-0`), top on desktop
+- Touch: swipe left/right to switch tabs (nice-to-have)
+
+### 8. Mobile Drawer Sidebar (`src/web/components/layout/mobile-drawer.tsx`)
+
+**[V2 FIX]** Do NOT use `hidden md:flex` toggle for mobile sidebar. Instead:
+- Absolute positioned overlay with backdrop (`fixed inset-0 z-50`)
+- Slide-in from left (`translate-x`) with animation
+- Click backdrop to close
+- Separate from desktop sidebar — desktop uses `hidden md:flex`, mobile uses drawer
+- Hamburger button opens drawer, not toggles sidebar visibility
+
+### 9. API Client Auto-Unwrap (`src/web/lib/api-client.ts`)
+
+**[V2 FIX]** Api-client must auto-unwrap `{ok, data}` envelope:
+```typescript
+async get<T>(path: string): Promise<T> {
+  const res = await fetch(`${this.baseUrl}${path}`, { headers });
+  const json = await res.json();
+  if (json.ok === false) throw new Error(json.error || `HTTP ${res.status}`);
+  return json.data as T;  // Return unwrapped data directly
+}
+```
+
+### 10. Auth Login Screen (`src/web/components/auth/login-screen.tsx`)
+
+- Full-screen centered card with token input field + "Unlock" button
+- On submit → store token in `localStorage('ppm-auth-token')`
+- `api-client` reads token from localStorage for all requests
+- On 401 response from any API call → clear token → redirect to login screen
+- If server has `auth.enabled: false` → skip login, app loads directly
+- Check auth status on app mount: `GET /api/auth/check` → returns `{ ok: true }` or 401
+
+### 11. Tab Metadata for Git Tabs
+
+**[V2 FIX]** Both tab-bar "+" dropdown AND mobile-nav MUST pass `{ projectName: activeProject.name }` when opening git-graph, git-status, git-diff tabs. Without this metadata, git components get `undefined` project.
+
+## Success Criteria
+
+- [ ] App loads in browser with tab bar + sidebar visible
+- [ ] Login screen shown when `auth.enabled: true` — entering correct token stores in localStorage and loads app
+- [ ] Invalid token shows error message on login screen
+- [ ] Can open new tab, close tab, switch between tabs — active tab content renders
+- [ ] Opening duplicate tab (same type + metadata) focuses existing tab instead of creating new
+- [ ] Project list fetches from API and displays project cards with name and path
+- [ ] Clicking project card sets it as active project (zustand store updates)
+- [ ] Mobile layout: bottom nav visible on small screens, top tab bar on desktop
+- [ ] Mobile drawer: hamburger opens overlay sidebar with backdrop, clicking backdrop closes it
+- [ ] Desktop sidebar: always visible at 280px width, collapsible
+- [ ] API client auto-unwraps `{ok, data}` envelope — `apiClient.get<Project[]>('/api/projects')` returns `Project[]` directly
+- [ ] API client throws error with message when `ok: false` (e.g., 401, 404)
+- [ ] WebSocket client connects, auto-reconnects with exponential backoff (1s, 2s, 4s, max 30s)
+- [ ] Git tabs opened from BOTH tab-bar AND mobile-nav include `{ projectName }` metadata
+- [ ] Theme: dark + light mode both work with proper contrast ratios
+- [ ] Theme toggle: "system" default follows OS preference, manual override persists in localStorage
+- [ ] CodeMirror editor switches theme when app theme changes
+- [ ] Notifications: toast appears bottom-left (desktop), bottom full-width (mobile)

package/plans/260314-2009-ppm-implementation/phase-04-file-explorer-editor.md

@@ -0,0 +1,120 @@
+# Phase 4: File Explorer + Code Editor
+
+**Owner:** backend-dev (API) + frontend-dev (UI) — parallel
+**Priority:** High
+**Depends on:** Phase 2, Phase 3
+**Effort:** Medium
+
+## Overview
+
+File tree API, CRUD operations, CodeMirror 6 editor tab, file compare/diff view.
+
+## Backend (backend-dev)
+
+### Files
+```
+src/services/file.service.ts
+src/server/routes/files.ts
+```
+
+### File Service
+```typescript
+class FileService {
+  getTree(projectPath: string, depth?: number): FileNode[]
+  readFile(filePath: string): { content: string; encoding: string }
+  writeFile(filePath: string, content: string): void
+  createFile(filePath: string, type: 'file' | 'directory'): void
+  deleteFile(filePath: string): void
+  renameFile(oldPath: string, newPath: string): void
+  moveFile(source: string, destination: string): void
+}
+
+interface FileNode {
+  name: string;
+  path: string;
+  type: 'file' | 'directory';
+  children?: FileNode[];
+  size?: number;
+  modified?: string;
+}
+```
+
+### API Routes
+
+**[V2 FIX]** `:project` param is project NAME (e.g. "ppm"), not path. Use `resolveProjectPath()` from `src/server/helpers/resolve-project.ts`.
+
+```
+GET    /api/files/tree/:project?depth=3     → FileNode[]
+GET    /api/files/read?path=...              → { content, encoding }
+PUT    /api/files/write                      → { path, content }
+POST   /api/files/create                     → { path, type }
+DELETE /api/files/delete                     → { path }
+POST   /api/files/rename                     → { oldPath, newPath }
+POST   /api/files/move                       → { source, destination }
+```
+
+`getTree(projectName)` accepts project name, looks it up via resolveProjectPath internally.
+
+### Security
+- Validate all paths are within registered project directories
+- Block access to `.git/`, `node_modules/`, `.env` files
+- Path traversal prevention (no `../`)
+
+## Frontend (frontend-dev)
+
+### Files
+```
+src/web/components/explorer/file-tree.tsx
+src/web/components/explorer/file-actions.tsx
+src/web/components/editor/code-editor.tsx
+src/web/components/editor/diff-viewer.tsx
+```
+
+### File Tree Component
+- Recursive tree rendering with expand/collapse
+- Icons per file type (folder, ts, js, json, md, etc.)
+- Context menu: New File, New Folder, Rename, Delete, Copy Path
+- Click file → open in editor tab
+- Select 2 files → "Compare Selected" option in context menu
+- Search/filter files (nice-to-have)
+
+### Code Editor (CodeMirror 6)
+```typescript
+// code-editor.tsx
+import CodeMirror from '@uiw/react-codemirror';
+import { oneDark } from '@codemirror/theme-one-dark';
+import { autocompletion } from '@codemirror/autocomplete';
+
+// Auto-detect language from file extension
+const getLanguageExtension = (filename: string) => {
+  const ext = filename.split('.').pop();
+  // Map ext → @codemirror/lang-* import
+};
+```
+
+- Auto-save on change (debounced 1s) via `PUT /api/files/write`
+- Unsaved indicator in tab title (dot or italic)
+- Mobile: CM6 handles touch natively
+
+### Diff Viewer
+- Uses `@codemirror/merge` for side-by-side or unified diff
+- Opened when comparing 2 files from explorer
+- Also used for git diff viewing (Phase 6)
+
+## Success Criteria
+
+- [ ] File tree loads project structure as expandable/collapsible tree with correct nesting
+- [ ] File tree excludes `.git/`, `node_modules/`, `.env` by default
+- [ ] Right-click (desktop) / long-press (mobile) opens context menu: New File, New Folder, Rename, Delete, Copy Path
+- [ ] "New File" creates file and opens it in editor tab
+- [ ] "Rename" shows inline input, saves on Enter, cancels on Esc
+- [ ] "Delete" shows confirmation dialog before deleting
+- [ ] Click file → opens CodeMirror editor in new tab with correct syntax highlighting
+- [ ] Click already-open file → focuses existing tab (no duplicate)
+- [ ] Editor: syntax highlighting works for .ts, .js, .py, .html, .css, .json, .md, .yaml
+- [ ] Editor: auto-save on change (debounced 1s) — tab title shows unsaved indicator (dot) until saved
+- [ ] Editor: save confirmed via `PUT /api/files/write` response — dot disappears
+- [ ] Select 2 files in explorer → "Compare Selected" in context menu → opens diff view
+- [ ] Diff viewer shows side-by-side or unified diff using `@codemirror/merge`
+- [ ] Path traversal blocked: accessing `../../etc/passwd` returns 403
+- [ ] Mobile: file tree scrollable with touch, context menu appears on long-press