@hienlh/ppm 0.1.0 → 0.1.1

package/plans/260314-2009-ppm-implementation/phase-06-git-integration.md

@@ -1,244 +0,0 @@
-# Phase 6: Git Integration
-
-**Owner:** backend-dev (API) + frontend-dev (UI) — parallel
-**Priority:** High
-**Depends on:** Phase 4 (file explorer, diff viewer reuse)
-**Effort:** Large (git graph is complex)
-
-## Overview
-
-Git status panel (stage/unstage/commit/push/pull), git diff viewer, git graph visualization (SVG, ported from vscode-git-graph approach).
-
-## Backend (backend-dev)
-
-### Files
-```
-src/services/git.service.ts
-src/server/routes/git.ts
-```
-
-### Git Service
-```typescript
-import simpleGit from 'simple-git';
-
-class GitService {
-  // Status
-  async status(projectPath: string): Promise<GitStatus>
-  async diff(projectPath: string, ref1?: string, ref2?: string): Promise<string> // unified diff
-  async fileDiff(projectPath: string, filePath: string): Promise<string>
-
-  // Staging
-  async stage(projectPath: string, files: string[]): Promise<void>
-  async unstage(projectPath: string, files: string[]): Promise<void>
-
-  // Commit + Push/Pull
-  async commit(projectPath: string, message: string): Promise<string> // returns hash
-  async push(projectPath: string, remote?: string, branch?: string): Promise<void>
-  async pull(projectPath: string, remote?: string, branch?: string): Promise<void>
-
-  // Branch ops
-  async branches(projectPath: string): Promise<GitBranch[]>
-  async createBranch(projectPath: string, name: string, from?: string): Promise<void>
-  async checkout(projectPath: string, ref: string): Promise<void>
-  async deleteBranch(projectPath: string, name: string, force?: boolean): Promise<void>
-  async merge(projectPath: string, source: string): Promise<void>
-
-  // Graph data
-  async graphData(projectPath: string, maxCount?: number): Promise<GitGraphData>
-
-  // Advanced (web-only, no CLI needed)
-  async cherryPick(projectPath: string, hash: string): Promise<void>
-  async revert(projectPath: string, hash: string): Promise<void>
-  async createTag(projectPath: string, name: string, hash?: string): Promise<void>
-
-  // PR URL
-  getCreatePrUrl(projectPath: string, branch: string): string | null
-  // Parse remote URL → GitHub/GitLab PR creation URL
-}
-```
-
-### Graph Data Extraction
-
-**[V2 FIX]** Do NOT parse `git log --format` manually with newline separators. Use simple-git's built-in `.log()` which returns correctly typed `LogResult`:
-
-```typescript
-async graphData(projectPath: string, maxCount = 200): Promise<GitGraphData> {
-  const git = simpleGit(projectPath);
-
-  // Use simple-git's built-in log() — handles parsing correctly
-  const log = await git.log({
-    '--all': null,
-    maxCount,
-  });
-
-  // log.all is already typed: { hash, date, message, author_name, author_email, refs, body, diff? }[]
-  const commits: GitCommit[] = log.all.map(c => ({
-    hash: c.hash,
-    abbreviatedHash: c.hash.slice(0, 7),
-    subject: c.message,
-    body: c.body,
-    authorName: c.author_name,
-    authorEmail: c.author_email,
-    authorDate: c.date,
-    parents: [], // Need separate call or parse refs
-    refs: c.refs ? c.refs.split(', ').filter(Boolean) : [],
-  }));
-
-  // Get parent hashes via raw format (safe: one field per line)
-  const parentLog = await git.raw([
-    'log', '--all', `--max-count=${maxCount}`,
-    '--format=%H %P'  // hash + space-separated parents on ONE line
-  ]);
-  const parentMap = new Map<string, string[]>();
-  for (const line of parentLog.trim().split('\n')) {
-    const [hash, ...parents] = line.split(' ');
-    if (hash) parentMap.set(hash, parents.filter(Boolean));
-  }
-  for (const c of commits) {
-    c.parents = parentMap.get(c.hash) ?? [];
-  }
-
-  const branchSummary = await git.branch(['-a', '--no-color']);
-  const branches: GitBranch[] = Object.entries(branchSummary.branches).map(([name, info]) => ({
-    name,
-    current: info.current,
-    remote: name.startsWith('remotes/'),
-    commitHash: info.commit,
-    ahead: 0,
-    behind: 0,
-  }));
-
-  return { commits, branches };
-}
-```
-
-### Lane Allocation Algorithm
-Port from vscode-git-graph `web/graph.ts`:
-- Each branch gets a lane (column index)
-- Merge/fork lines connect lanes
-- Color = `laneIndex % colorPalette.length`
-- Return: `Map<commitHash, { lane: number, lines: Line[] }>`
-
-### API Routes
-```
-GET  /api/git/status/:project
-GET  /api/git/diff/:project?ref1=&ref2=
-GET  /api/git/file-diff/:project?file=&ref=
-GET  /api/git/graph/:project?max=500
-GET  /api/git/branches/:project
-POST /api/git/stage             { project, files }
-POST /api/git/unstage           { project, files }
-POST /api/git/commit            { project, message }
-POST /api/git/push              { project, remote?, branch? }
-POST /api/git/pull              { project, remote?, branch? }
-POST /api/git/branch/create     { project, name, from? }
-POST /api/git/checkout          { project, ref }
-POST /api/git/branch/delete     { project, name, force? }
-POST /api/git/merge             { project, source }
-POST /api/git/cherry-pick       { project, hash }
-POST /api/git/revert            { project, hash }
-POST /api/git/tag               { project, name, hash? }
-GET  /api/git/pr-url/:project?branch=  → { url }
-```
-
-## Frontend (frontend-dev)
-
-### Files
-```
-src/web/components/git/git-graph.tsx
-src/web/components/git/git-graph-renderer.tsx
-src/web/components/git/git-status-panel.tsx
-src/web/components/git/git-diff-tab.tsx
-src/web/components/git/commit-context-menu.tsx
-src/web/lib/git-graph-layout.ts
-```
-
-### Git Status Panel
-- Split into: Changes (unstaged) + Staged Changes
-- Each file: icon (M/A/D/R), filename, click → open diff
-- Buttons: Stage All, Unstage All
-- Individual file: click +/- to stage/unstage
-- Commit section: textarea input + "Commit" button
-- Push/Pull buttons with branch name display
-- Auto-refresh via WS `/ws/events` or polling
-
-### Git Graph (SVG)
-```typescript
-// git-graph-renderer.tsx
-// Receives: commits + lanes from backend API
-
-const GitGraphRenderer = ({ data }: { data: GitGraphData }) => {
-  // SVG element with:
-  // 1. Branch lines: <path> elements, curved or angular
-  // 2. Commit nodes: <circle> elements
-  // 3. Labels: branch names, tags as badges
-  // 4. Click handlers on commits → expand details
-  // 5. Context menu on commits and branches
-
-  // Virtualization: only render visible rows
-  // Each commit row height = GRID_Y (e.g., 24px)
-  // Scroll container with virtual list
-};
-```
-
-### Git Graph Context Menu (shadcn/ui ContextMenu)
-**On commit node:**
-- Checkout this commit
-- Create branch here...
-- Cherry pick
-- Revert
-- Create tag...
-- Copy commit hash
-- View diff
-
-**On branch label:**
-- Checkout
-- Merge into current branch
-- Delete branch
-- Rename branch
-- Push
-- Pull
-- Rebase onto current
-- Create Pull Request → opens browser URL
-
-### Git Diff Tab
-- Reuse `@codemirror/merge` diff viewer from Phase 4
-- Opened from: git status (click file), git graph (view diff), file explorer (compare)
-- Header: file path, ref1 vs ref2
-
-## Success Criteria
-
-**Git Status Panel:**
-- [ ] Shows two sections: "Changes" (unstaged) and "Staged Changes" with file counts
-- [ ] Each file shows status icon (M=modified, A=added, D=deleted, R=renamed) + filename
-- [ ] Click file in either section → opens diff view in new tab
-- [ ] Click "+" on unstaged file → stages it (moves to Staged section)
-- [ ] Click "−" on staged file → unstages it (moves to Changes section)
-- [ ] "Stage All" button stages all changed files
-- [ ] "Unstage All" button unstages all staged files
-- [ ] Commit section: textarea for message + "Commit" button
-- [ ] Commit with empty message → button disabled / shows warning
-- [ ] Commit with nothing staged → shows "Nothing to commit" message
-- [ ] After successful commit → status panel refreshes, staged files clear
-- [ ] Push/Pull buttons show current branch name, disabled when no remote
-
-**Git Graph:**
-- [ ] Renders commit history as SVG with colored branch lanes
-- [ ] Each commit: circle node + abbreviated hash + subject + author + relative date
-- [ ] Branch labels rendered as colored badges on corresponding commits
-- [ ] Merge commits show lines connecting from parent lanes
-- [ ] Scroll through 200+ commits without performance issues (virtualized rendering)
-- [ ] Right-click commit → context menu: Checkout, Create branch, Cherry pick, Revert, Create tag, Copy hash, View diff
-- [ ] Right-click branch label → context menu: Checkout, Merge into current, Delete, Push, Create PR
-- [ ] "Create PR" → opens correct GitHub/GitLab URL (parsed from remote) in new browser tab
-
-**Git Diff:**
-- [ ] Diff tab shows file path + refs in header
-- [ ] Side-by-side diff using `@codemirror/merge` with syntax highlighting
-- [ ] Added lines highlighted green, removed lines highlighted red
-- [ ] Opened from: git status (click file), git graph (view diff), file explorer (compare)
-
-**Mobile:**
-- [ ] Git graph scrollable horizontally and vertically with touch
-- [ ] Context menu appears on long-press (commit node or branch label)
-- [ ] Status panel: swipe file row to stage/unstage (nice-to-have, buttons work as fallback)

package/plans/260314-2009-ppm-implementation/phase-07-ai-chat.md

@@ -1,242 +0,0 @@
-# Phase 7: AI Chat
-
-**Owner:** backend-dev (provider + WS) + frontend-dev (chat UI) — parallel
-**Priority:** High
-**Depends on:** Phase 2, Phase 3
-**Effort:** Large
-
-## Overview
-
-AI chat with Claude Agent SDK as first provider. Generic AIProvider interface for multi-provider support. Chat UI with streaming, tool approvals, session management.
-
-## Backend (backend-dev)
-
-### Files
-```
-src/providers/provider.interface.ts    # Already in types, implement here
-src/providers/claude-agent-sdk.ts
-src/providers/cli-subprocess.ts        # Stub for future
-src/providers/registry.ts
-src/services/chat.service.ts
-src/server/ws/chat.ts
-```
-
-### Claude Agent SDK Provider
-```typescript
-import { query, listSessions, getSessionMessages } from '@anthropic-ai/claude-agent-sdk';
-
-class ClaudeAgentSdkProvider implements AIProvider {
-  id = 'claude';
-  name = 'Claude Code';
-
-  async createSession(config: SessionConfig): Promise<Session> {
-    // Start a new query() — capture session_id from init message
-    // Return session handle
-  }
-
-  async resumeSession(sessionId: string): Promise<Session> {
-    // Use { resume: sessionId } option
-  }
-
-  async *sendMessage(sessionId: string, message: string): AsyncIterable<ChatEvent> {
-    const options = sessionId
-      ? { resume: sessionId, allowedTools: [...] }
-      : { allowedTools: [...] };
-
-    for await (const msg of query({ prompt: message, options })) {
-      // Map SDK messages → ChatEvent types
-      if (msg.type === 'assistant') {
-        for (const block of msg.content) {
-          if (block.type === 'text') yield { type: 'text', content: block.text };
-          if (block.type === 'tool_use') yield { type: 'tool_use', tool: block.name, input: block.input };
-        }
-      }
-      if (msg.type === 'result') {
-        yield { type: 'done', sessionId: msg.session_id };
-      }
-    }
-  }
-
-  async listSessions(): Promise<SessionInfo[]> {
-    return await listSessions();
-  }
-
-  async deleteSession(sessionId: string): Promise<void> {
-    // Delete session file from ~/.claude/projects/...
-  }
-}
-```
-
-### Tool Approval Flow
-```typescript
-// In claude-agent-sdk.ts
-// canUseTool callback → forward to frontend via WS
-
-const options = {
-  canUseTool: async (toolName: string, input: any) => {
-    // Send approval request to frontend via WS
-    const response = await this.requestApproval(sessionId, toolName, input);
-    if (response.approved) {
-      return { behavior: 'allow', updatedInput: input };
-    }
-    return { behavior: 'deny', message: response.reason || 'User denied' };
-  }
-};
-```
-
-### Provider Registry
-```typescript
-class ProviderRegistry {
-  private providers: Map<string, AIProvider> = new Map();
-
-  register(provider: AIProvider): void
-  get(id: string): AIProvider | undefined
-  list(): AIProviderInfo[]
-  getDefault(): AIProvider
-}
-```
-
-### Chat Service
-```typescript
-class ChatService {
-  constructor(private registry: ProviderRegistry)
-
-  async createSession(providerId: string, config: SessionConfig): Promise<Session>
-  async resumeSession(providerId: string, sessionId: string): Promise<Session>
-  async listSessions(providerId?: string): Promise<SessionInfo[]>
-  async deleteSession(providerId: string, sessionId: string): Promise<void>
-  sendMessage(providerId: string, sessionId: string, message: string): AsyncIterable<ChatEvent>
-}
-```
-
-### WebSocket Handler
-```
-WS /ws/chat/:sessionId
-```
-
-Protocol (JSON messages):
-```typescript
-// Client → Server
-{ type: 'message', content: string }
-{ type: 'approval_response', requestId: string, approved: boolean, reason?: string }
-
-// Server → Client
-{ type: 'text', content: string }
-{ type: 'tool_use', tool: string, input: any }
-{ type: 'tool_result', output: string }
-{ type: 'approval_request', requestId: string, tool: string, input: any }
-{ type: 'done', sessionId: string }
-{ type: 'error', message: string }
-```
-
-## Frontend (frontend-dev)
-
-### Files
-```
-src/web/components/chat/chat-tab.tsx
-src/web/components/chat/message-list.tsx
-src/web/components/chat/message-input.tsx
-src/web/components/chat/tool-approval.tsx
-src/web/components/chat/session-picker.tsx
-src/web/hooks/use-chat.ts
-```
-
-### Chat Tab Layout
-```
-┌─────────────────────────────────┐
-│ Claude Code  ▼  [Session: abc]  │  ← provider picker + session info
-├─────────────────────────────────┤
-│                                 │
-│  User: Fix the bug in auth.ts   │
-│                                 │
-│  Claude: I'll read the file...  │
-│  📄 Read auth.ts                │
-│  ✅ Tool result: (content)      │
-│                                 │
-│  ⚠️ Bash: rm -rf /tmp/test     │
-│  [Allow] [Deny]                 │  ← tool approval dialog
-│                                 │
-├─────────────────────────────────┤
-│ 📎  Type a message...    [Send] │  ← input with file attach
-└─────────────────────────────────┘
-```
-
-### Message Types Rendering
-- **User message:** Right-aligned bubble (or left with avatar)
-- **Assistant text:** Markdown rendered (code blocks with syntax highlight)
-- **Tool use:** Collapsible card showing tool name + input
-- **Tool result:** Collapsible card showing output (truncated)
-- **Approval request:** Highlighted card with Allow/Deny buttons + tool details
-- **Error:** Red alert banner
-
-### Session Picker
-- Dropdown or modal listing all sessions
-- Each session: provider icon, title (first message truncated), timestamp
-- Actions: Resume, Delete, Fork (nice-to-have)
-- "New Chat" button → create fresh session
-
-### useChat Hook
-```typescript
-const useChat = (sessionId?: string) => {
-  const ws = useWebSocket(`/ws/chat/${sessionId}`);
-  const [messages, setMessages] = useState<ChatMessage[]>([]);
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [pendingApproval, setPendingApproval] = useState<ApprovalRequest | null>(null);
-
-  const sendMessage = (content: string) => {
-    ws.send(JSON.stringify({ type: 'message', content }));
-  };
-
-  const respondToApproval = (requestId: string, approved: boolean) => {
-    ws.send(JSON.stringify({ type: 'approval_response', requestId, approved }));
-  };
-
-  return { messages, isStreaming, pendingApproval, sendMessage, respondToApproval };
-};
-```
-
-### Mobile Considerations
-- Chat input: sticky bottom, auto-resize textarea
-- Long messages: scrollable code blocks
-- Tool approval: full-width card, large touch targets for Allow/Deny
-- Keyboard: input should push content up, not cover it
-
-## Chat History & Reconnect
-
-### REST API for Message History
-- `GET /api/chat/sessions` → list all sessions (id, provider, title, createdAt)
-- `GET /api/chat/sessions/:id/messages` → full message history for a session
-- On WS reconnect: client loads history via REST, then subscribes to live stream
-- This avoids WS replay complexity — REST is simpler and more reliable
-
-### Reconnect Flow
-```
-Client disconnects
-  → WS closes
-  → Client: exponential backoff reconnect
-  → Client reconnects to same sessionId
-  → Client: GET /api/chat/sessions/:id/messages → render history
-  → Server: resume streaming from where it left off (if AI still generating)
-```
-
-### Session Persistence
-- Claude Agent SDK sessions persist automatically (stored in ~/.claude/)
-- PPM stores session metadata in `~/.ppm/chat-sessions.json`: id, provider, title, projectName, createdAt
-- Session list fetched from PPM metadata file (fast), not from SDK (slow)
-
-## Success Criteria
-
-- [ ] Can create new chat session → WS connects, session appears in session list
-- [ ] Sending message streams AI response text in real-time (character by character)
-- [ ] Tool use blocks render with tool name + collapsible input JSON
-- [ ] Tool result blocks render with collapsible output
-- [ ] Tool approval dialog: shows tool name + input, Allow/Deny buttons work, response sent via WS
-- [ ] After Allow → tool executes and result streams back; after Deny → AI acknowledges denial
-- [ ] Can resume existing session: select from picker → loads history via REST → WS reconnects
-- [ ] Session list shows all sessions with provider icon, truncated title, timestamp
-- [ ] "New Chat" button creates fresh session with current project context
-- [ ] Multiple chat tabs work simultaneously (each with own WS connection)
-- [ ] WS disconnect → reconnect → message history loaded from REST API
-- [ ] Works on mobile: sticky bottom input, keyboard pushes content up, large Allow/Deny buttons
-- [ ] Markdown rendering in AI messages: code blocks with syntax highlighting, lists, headers
-- [ ] Error messages from AI/server shown as red alert banner (not silent failure)

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

@@ -1,143 +0,0 @@
-# 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