npm - @hienlh/ppm - Versions diffs - 0.1.0 → 0.1.1 - Mend

@hienlh/ppm 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

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

@@ -1,256 +0,0 @@
-# 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 DELETED Viewed

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

package/plans/260314-2009-ppm-implementation/phase-05-web-terminal.md DELETED Viewed

@@ -1,174 +0,0 @@
-# Phase 5: Web Terminal
-**Owner:** backend-dev (PTY + WS) + frontend-dev (xterm.js) — parallel
-**Priority:** High
-**Depends on:** Phase 2, Phase 3
-**Effort:** Medium
-## Overview
-Web-based terminal: xterm.js in browser ↔ WebSocket ↔ Bun.spawn() native Terminal API on server. Multiple terminal sessions.
-## Backend (backend-dev)
-### Files
-```
-src/services/terminal.service.ts
-src/server/ws/terminal.ts
-```
-### Terminal Service
-**[V2 FIX]** Use `Bun.spawn()` with **native Terminal API** (NOT node-pty).
-**Why:** node-pty uses NAN (pre-2015 C++ bindings), Bun only supports NAPI. This is a hard incompatibility — segfault crashes entire process, no try-catch possible. See [research report](../reports/researcher-260314-2232-node-pty-bun-crash-analysis.md).
-**Chosen approach:** `Bun.spawn()` with `terminal` option — built-in, zero dependencies, full PTY support (colors, cursor, resize).
-```typescript
-class TerminalService {
-  private sessions: Map<string, TerminalSession> = new Map();
-  private outputBuffers: Map<string, string> = new Map(); // Last 10KB per session
-  create(projectPath: string, shell?: string): string {
-    const id = crypto.randomUUID();
-    const proc = Bun.spawn([shell || process.env.SHELL || 'bash'], {
-      cwd: projectPath,
-      terminal: {
-        cols: 80,
-        rows: 24,
-        data: (terminal, chunk) => {
-          // Buffer last 10KB for reconnect
-          this.appendBuffer(id, chunk.toString());
-          // Emit to connected WS clients via event bus
-        },
-      },
-    });
-    this.sessions.set(id, { id, proc, projectPath, createdAt: new Date() });
-    return id;
-  }
-  write(id: string, data: string): void {
-    this.sessions.get(id)?.proc.terminal?.write(data);
-  }
-  resize(id: string, cols: number, rows: number): void {
-    this.sessions.get(id)?.proc.terminal?.resize(cols, rows);
-  }
-  kill(id: string): void {
-    const session = this.sessions.get(id);
-    if (session) {
-      session.proc.terminal?.close();
-      session.proc.kill();
-      this.sessions.delete(id);
-      this.outputBuffers.delete(id);
-    }
-  }
-  getBuffer(id: string): string {
-    return this.outputBuffers.get(id) ?? '';
-  }
-  list(): TerminalSessionInfo[] { /* ... */ }
-  get(id: string): TerminalSession | undefined { /* ... */ }
-}
-```
-**Limitation:** POSIX only (macOS/Linux). Acceptable for dev environment — Windows users use WSL.
-### WebSocket Handler
-```
-WS /ws/terminal/:id
-```
-Protocol (binary frames):
-- Client → Server: keystrokes (text)
-- Server → Client: terminal output (text)
-- Client → Server: `\x01RESIZE:cols,rows` (control message)
-- Server detects client disconnect → keep PTY alive for reconnect (30s timeout)
-### Flow
-```
-Browser (xterm.js) → WS connect /ws/terminal/:id
-  If session exists → attach to existing PTY
-  If not → create new PTY via TerminalService
-  xterm.js keystroke → WS → pty.write()
-  pty.onData() → WS → xterm.js render
-  xterm.js resize → WS control msg → pty.resize()
-```
-## Frontend (frontend-dev)
-### Files
-```
-src/web/components/terminal/terminal-tab.tsx
-src/web/hooks/use-terminal.ts
-```
-### Terminal Tab Component
-```typescript
-import { Terminal } from '@xterm/xterm';
-import { FitAddon } from '@xterm/addon-fit';
-import { WebLinksAddon } from '@xterm/addon-web-links';
-// useTerminal hook manages WS connection + xterm instance
-const useTerminal = (sessionId: string) => {
-  // Create Terminal instance
-  // Attach FitAddon for auto-resize
-  // Connect WebSocket
-  // Wire: ws.onmessage → term.write()
-  // Wire: term.onData → ws.send()
-  // Wire: ResizeObserver → ws.send(resize control msg)
-};
-```
-### Features
-- Auto-fit to container size
-- Clickable URLs (WebLinksAddon)
-- Copy/paste (mobile: long press select, paste button)
-- Reconnect on WS drop (re-attach to same PTY)
-- "New Terminal" button → opens new tab with new session
-- Terminal font: monospace, configurable size
-### Mobile Considerations
-- xterm.js works on mobile but keyboard can obscure terminal
-- Use `visualViewport` API to adjust terminal height when keyboard opens
-- Bottom toolbar with common keys: Tab, Ctrl, Esc, arrows
-## State Persistence & Reconnect
-### Output Buffer
-- Server keeps a circular buffer (last 10KB) of terminal output per session
-- On WS reconnect → server sends buffered output before live stream
-- Client clears xterm and replays buffer for seamless experience
-### Session Persistence
-- Terminal sessions survive server restart: save session metadata (id, projectPath, shell, cwd) to `~/.ppm/sessions.json`
-- On server start → attempt to restore sessions from file (re-spawn shell in last known cwd)
-- Sessions that fail to restore → mark as "dead", remove from list
-- Idle session timeout: configurable, default 1 hour — kill PTY + remove from sessions
-### WS Reconnect Flow
-```
-Client disconnects (network drop, tab switch on mobile)
-  → WS closes
-  → Client: exponential backoff reconnect (1s, 2s, 4s... max 30s)
-  → Server: PTY stays alive, output buffers
-  → Client reconnects: sends { type: 'attach', sessionId: 'xxx' }
-  → Server: sends buffered output, then pipes live
-```
-## Success Criteria
-- [ ] Opening terminal tab spawns real shell (bash/zsh) with correct CWD
-- [ ] Keystrokes sent from browser appear in shell; shell output renders in xterm.js
-- [ ] Terminal auto-resizes when browser window/container resizes — sends RESIZE control message
-- [ ] Multiple terminal tabs work simultaneously (each with own PTY session)
-- [ ] WS disconnect → reconnect → terminal shows buffered output + continues working
-- [ ] Works on mobile: keyboard opens without covering terminal, bottom toolbar has Tab/Ctrl/Esc/arrows
-- [ ] `visualViewport` API adjusts terminal height when mobile keyboard opens
-- [ ] Terminal session persists if server stays running (navigate away + come back = same session)
-- [ ] Idle sessions killed after configured timeout (default 1h)
-- [ ] Clickable URLs in terminal output (WebLinksAddon)