@hienlh/ppm 0.2.20 → 0.2.21

package/docs/project-roadmap.md

@@ -1,10 +1,10 @@
 # PPM Project Roadmap & Status
 
-**Last Updated:** March 15, 2026
+**Last Updated:** March 17, 2026
 
 ## Current Version: v2.0 (In Progress)
 
-### Overall Progress: 85%
+### Overall Progress: 90%
 
 Multi-project, project-scoped API refactor with improved UX.
 
@@ -49,13 +49,21 @@ Multi-project, project-scoped API refactor with improved UX.
 - URL sync for project/tab/file state
 - Tab metadata persistence in localStorage
 
+**Latest Work (260317):**
+- Project Switcher Bar: 52px left sidebar with project avatars, drag-to-reorder
+- Project color customization (12-color palette or custom hex)
+- Mobile ProjectBottomSheet for project selection
+- Keep-alive workspace switching (hide/show instead of unmount, preserves xterm DOM)
+- Sidebar tab system: Explorer / Git / History tabs (removed projects/git-status tab types)
+- Smart project initials with collision detection (1-char, 2-char, or index fallback)
+
 ---
 
 ### Phase 4: File Explorer & Editor ✅ Complete
 - FileTree component with directory expansion
-- CodeMirror 6 integration with syntax highlighting
+- Monaco Editor integration with syntax highlighting
 - File read/write operations
-- Diff viewer (Diff2HTML)
+- Monaco diff viewer for git diffs
 
 **Status:** Done
 
@@ -64,6 +72,11 @@ Multi-project, project-scoped API refactor with improved UX.
 - File viewer for images/PDFs/markdown
 - Better error messages
 
+**Latest Work (260317):**
+- Migrated CodeMirror → Monaco Editor (@monaco-editor/react) for better syntax highlighting and diff viewer
+- Alt+Z keyboard shortcut for word wrap toggle in editor and diff viewer
+- Improved code completion and IntelliSense
+
 ---
 
 ### Phase 5: Web Terminal ✅ Complete
@@ -206,6 +219,11 @@ Multi-project, project-scoped API refactor with improved UX.
 - [x] File attachments in chat
 - [x] Mobile responsive improvements
 - [x] URL sync for bookmarking/sharing
+- [x] Project Switcher Bar (52px sidebar, avatars, colors, reordering) (260317)
+- [x] Keep-alive workspace switching (preserve xterm DOM) (260317)
+- [x] Sidebar tab system (Explorer/Git/History) (260317)
+- [x] Monaco Editor migration (CodeMirror → Monaco) (260317)
+- [x] Project color customization (12-color palette + custom hex) (260317)
 - [ ] Complete test coverage (60% complete)
 - [ ] Documentation (in progress)
 - [ ] Security audit (planned)

package/docs/system-architecture.md

@@ -65,12 +65,17 @@
 
 **Responsibilities:**
 - Render UI for file explorer, editor, terminal, chat
+- Project switching with visual indicators (avatars, colors, keep-alive workspaces)
 - Capture user input (text, file uploads, terminal commands)
 - Display streaming responses, terminal output
 - Handle authentication (token in localStorage)
 
 **Key Files:**
 - `src/web/app.tsx` — Root React component
+- `src/web/components/layout/project-bar.tsx` — Narrow left sidebar with project avatars (52px width)
+- `src/web/components/layout/project-bottom-sheet.tsx` — Mobile project switcher (bottom sheet)
+- `src/web/components/layout/sidebar.tsx` — Main sidebar with Explorer/Git/History tabs
+- `src/web/components/chat/chat-history-panel.tsx` — History tab content (chat sessions)
 - `src/web/components/` — UI components
 - `src/cli/commands/` — CLI command handlers
 
@@ -100,6 +105,8 @@ PUT    /api/settings/ai         → Update AI provider settings
 POST   /api/projects            → Create project
 GET    /api/projects            → List projects
 DELETE /api/projects/:name      → Delete project
+PATCH  /api/projects/reorder    → Reorder projects by name order
+PATCH  /api/projects/:name/color → Set project color (hex string)
 GET    /api/project/:name/chat/sessions           → List sessions
 POST   /api/project/:name/chat/sessions           → Create session
 GET    /api/project/:name/chat/sessions/:id/messages → Get history
@@ -255,6 +262,58 @@ HTTP/1.1 200 OK
 
 ---
 
+## Project Workspace Management
+
+### Keep-Alive Pattern (v2.0+)
+When switching projects, workspaces are preserved instead of destroyed:
+1. **Workspace Mount State**: Each project's UI (tabs, terminal xterm DOM, file selections) remains mounted in the DOM
+2. **Visibility Toggle**: CSS `display: none/block` hides/shows workspaces instead of React unmounting
+3. **Terminal DOM Persistence**: xterm.js terminal instances retain their DOM structure across switches (prevents re-render flicker)
+4. **Cache Efficiency**: Zustand stores persist open tabs, selections, and scroll positions per project
+
+**Benefits:**
+- Instant project switching (no DOM reconstruction)
+- Terminal history preserved across switches
+- Smooth UX without flashing/re-rendering
+- Reduced network requests (cached UI state)
+
+### Project Color & Ordering (v2.0+)
+**Storage**: Colors stored as optional `color` field in `Project` interface (hex string or undefined)
+
+**Endpoints:**
+- `PATCH /api/projects/:name/color` — Update project color
+- `PATCH /api/projects/reorder` — Reorder projects array in config
+
+**UI Components:**
+- `ProjectBar` (52px sidebar) — Shows project avatars with color backgrounds, context menu for reorder/rename/delete/color-picker
+- `ProjectBottomSheet` (mobile) — Bottom sheet switcher with scrollable project list
+- `ProjectAvatar` utility — Generates smart initials with collision resolution (prefer 1-char, fallback to 2-char or index)
+- `PROJECT_PALETTE` — 12-color palette for default colors when not customized
+
+---
+
+## Code Editor Migration (v2.0+)
+
+**Migration**: CodeMirror 6 → Monaco Editor (@monaco-editor/react)
+
+**Reasons:**
+- Better syntax highlighting for complex languages
+- Superior IntelliSense and code completion
+- Performance improvements on large files
+- More polished diff viewer experience
+
+**Components Updated:**
+- `src/web/components/editor/code-editor.tsx` — Monaco Editor with language detection
+- `src/web/components/editor/diff-viewer.tsx` — Monaco diff viewer for git diffs
+
+**Features:**
+- Alt+Z toggle for word wrap
+- Automatic language detection from file extension
+- Theme sync with app dark/light mode
+- Responsive layout with proper scrolling
+
+---
+
 ## Authentication Flow
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "module": "src/index.ts",
   "type": "module",
@@ -8,8 +8,8 @@
     "ppm": "src/index.ts"
   },
   "scripts": {
-    "dev": "bun run --hot src/index.ts start & bun run vite --config vite.config.ts & wait",
-    "dev:server": "bun run --hot src/index.ts start -f",
+    "dev": "bun run --hot src/index.ts start -c ~/.ppm/config.dev.yaml & bun run vite --config vite.config.ts & wait",
+    "dev:server": "bun run --hot src/index.ts start -c ~/.ppm/config.dev.yaml",
     "dev:web": "bun run vite --config vite.config.ts",
     "build:web": "bun run vite build --config vite.config.ts",
     "build": "bun run build:web && bun build src/index.ts --compile --outfile dist/ppm",
@@ -27,6 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "@types/web-push": "^3.6.4",
     "@vitejs/plugin-react": "^6.0.1",
+    "esbuild": "^0.27.4",
     "tailwindcss": "^4.2.1",
     "vite": "^8.0.0",
     "vite-plugin-pwa": "^1.2.0"
@@ -36,23 +37,13 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.76",
-    "@codemirror/autocomplete": "^6.20.1",
-    "@codemirror/lang-css": "^6.3.1",
-    "@codemirror/lang-html": "^6.4.11",
-    "@codemirror/lang-javascript": "^6.2.5",
-    "@codemirror/lang-json": "^6.0.2",
-    "@codemirror/lang-markdown": "^6.5.0",
-    "@codemirror/lang-python": "^6.2.1",
-    "@codemirror/merge": "^6.12.1",
-    "@codemirror/theme-one-dark": "^6.1.3",
     "@inquirer/prompts": "^8.3.0",
-    "@uiw/react-codemirror": "^4.25.8",
+    "@monaco-editor/react": "^4.7.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "codemirror": "^6.0.2",
     "commander": "^14.0.3",
     "diff2html": "^3.4.56",
     "hono": "^4.12.8",
@@ -68,6 +59,7 @@
     "simple-git": "^3.33.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
+    "vite-plugin-monaco-editor": "^1.1.0",
     "web-push": "^3.6.7",
     "zustand": "^5.0.11"
   }

package/src/providers/claude-agent-sdk.ts

@@ -56,8 +56,8 @@ interface PendingApproval {
  * Uses canUseTool callback for tool approvals and AskUserQuestion.
  */
 export class ClaudeAgentSdkProvider implements AIProvider {
-  id = "claude-sdk";
-  name = "Claude Agent SDK";
+  id = "claude";
+  name = "Claude";
 
   private activeSessions = new Map<string, Session>();
   private messageCount = new Map<string, number>();

package/src/providers/registry.ts

@@ -1,6 +1,7 @@
 import type { AIProvider } from "./provider.interface.ts";
 import { MockProvider } from "./mock-provider.ts";
 import { ClaudeAgentSdkProvider } from "./claude-agent-sdk.ts";
+import { configService } from "../services/config.service.ts";
 
 export interface ProviderInfo {
   id: string;
@@ -9,13 +10,9 @@ export interface ProviderInfo {
 
 class ProviderRegistry {
   private providers = new Map<string, AIProvider>();
-  private defaultId: string | null = null;
 
   register(provider: AIProvider): void {
     this.providers.set(provider.id, provider);
-    if (!this.defaultId) {
-      this.defaultId = provider.id;
-    }
   }
 
   get(id: string): AIProvider | undefined {
@@ -29,15 +26,19 @@ class ProviderRegistry {
     }));
   }
 
+  /** Get the default provider based on config's default_provider */
   getDefault(): AIProvider {
-    if (!this.defaultId) throw new Error("No providers registered");
-    const provider = this.providers.get(this.defaultId);
-    if (!provider) throw new Error("Default provider not found");
-    return provider;
+    const defaultId = configService.get("ai").default_provider;
+    const provider = this.providers.get(defaultId);
+    if (provider) return provider;
+    // Fallback to "claude" if config value doesn't match any registered provider
+    const fallback = this.providers.get("claude");
+    if (fallback) return fallback;
+    throw new Error(`Default provider "${defaultId}" not found in registry`);
   }
 }
 
-/** Singleton registry — first registered = default */
+/** Singleton registry */
 export const providerRegistry = new ProviderRegistry();
-providerRegistry.register(new ClaudeAgentSdkProvider()); // default — real streaming, multi-turn
-providerRegistry.register(new MockProvider());            // testing only
+providerRegistry.register(new ClaudeAgentSdkProvider());
+providerRegistry.register(new MockProvider()); // testing only

package/src/server/routes/projects.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { projectService } from "../../services/project.service.ts";
+import { configService } from "../../services/config.service.ts";
 import { searchGitDirs } from "../../services/git-dirs.service.ts";
 import { ok, err } from "../../types/api.ts";
 
@@ -45,6 +46,48 @@ projectRoutes.get("/suggest-dirs", (c) => {
   }
 });
 
+/** PATCH /api/projects/reorder — reorder projects array */
+projectRoutes.patch("/reorder", async (c) => {
+  try {
+    const body = await c.req.json<{ order: string[] }>();
+    if (!Array.isArray(body.order)) {
+      return c.json(err("Missing required field: order (string[])"), 400);
+    }
+    const projects = configService.get("projects");
+    const orderMap = new Map(body.order.map((name, i) => [name, i]));
+    const reordered = [...projects].sort((a, b) => {
+      const ai = orderMap.get(a.name) ?? Infinity;
+      const bi = orderMap.get(b.name) ?? Infinity;
+      return ai - bi;
+    });
+    configService.set("projects", reordered);
+    configService.save();
+    return c.json(ok({ reordered: reordered.length }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+/** PATCH /api/projects/:name/color — set project color */
+projectRoutes.patch("/:name/color", async (c) => {
+  try {
+    const name = c.req.param("name");
+    const body = await c.req.json<{ color: string | null }>();
+    const projects = configService.get("projects");
+    const idx = projects.findIndex((p) => p.name === name);
+    if (idx === -1) return c.json(err(`Project not found: ${name}`), 404);
+    const updated = { ...projects[idx]! };
+    if (body.color) updated.color = body.color;
+    else delete updated.color;
+    projects[idx] = updated;
+    configService.set("projects", projects);
+    configService.save();
+    return c.json(ok(updated));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
 /** PATCH /api/projects/:name — update a project's name/path */
 projectRoutes.patch("/:name", async (c) => {
   try {

package/src/server/routes/settings.ts

@@ -3,20 +3,51 @@ import { configService } from "../../services/config.service.ts";
 import {
   validateAIProviderConfig,
   validateDefaultProvider,
+  VALID_PROVIDERS,
   type AIProviderConfig,
+  type ThemeConfig,
 } from "../../types/config.ts";
 import { ok, err } from "../../types/api.ts";
 
 export const settingsRoutes = new Hono();
 
+/** Strip api_key_env from all providers in an AI config object */
+function stripSensitiveFields(ai: { providers: Record<string, unknown> }) {
+  const clone = structuredClone(ai);
+  for (const provider of Object.values(clone.providers)) {
+    delete (provider as Record<string, unknown>).api_key_env;
+  }
+  return clone;
+}
+
+// ── Theme ─────────────────────────────────────────────────────────────
+
+/** GET /settings/theme */
+settingsRoutes.get("/theme", (c) => {
+  return c.json(ok({ theme: configService.get("theme") ?? "system" }));
+});
+
+/** PUT /settings/theme */
+settingsRoutes.put("/theme", async (c) => {
+  try {
+    const { theme } = await c.req.json<{ theme: ThemeConfig }>();
+    if (!["light", "dark", "system"].includes(theme)) {
+      return c.json(err("theme must be light, dark, or system"), 400);
+    }
+    configService.set("theme", theme);
+    configService.save();
+    return c.json(ok({ theme }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 400);
+  }
+});
+
+// ── AI ────────────────────────────────────────────────────────────────
+
 /** GET /settings/ai — return current AI config (strips api_key_env) */
 settingsRoutes.get("/ai", (c) => {
-  const ai = structuredClone(configService.get("ai"));
-  // Strip sensitive env var names from response
-  for (const provider of Object.values(ai.providers)) {
-    delete (provider as unknown as Record<string, unknown>).api_key_env;
-  }
-  return c.json(ok(ai));
+  const ai = configService.get("ai");
+  return c.json(ok(stripSensitiveFields(ai)));
 });
 
 /** PUT /settings/ai — update AI provider settings, writes to yaml */
@@ -54,8 +85,11 @@ settingsRoutes.put("/ai", async (c) => {
       }
     }
 
-    // Validate default_provider references existing provider
+    // Validate default_provider is in allowed list and references existing provider
     if (body.default_provider) {
+      if (!VALID_PROVIDERS.includes(body.default_provider as any)) {
+        return c.json(err(`default_provider must be one of: ${VALID_PROVIDERS.join(", ")}`), 400);
+      }
       const dpErr = validateDefaultProvider(updated.default_provider, updated.providers);
       if (dpErr) return c.json(err(dpErr), 400);
     }
@@ -63,7 +97,7 @@ settingsRoutes.put("/ai", async (c) => {
     configService.set("ai", updated);
     configService.save();
 
-    return c.json(ok(updated));
+    return c.json(ok(stripSensitiveFields(updated)));
   } catch (e) {
     return c.json(err((e as Error).message), 400);
   }

package/src/server/ws/chat.ts

@@ -159,7 +159,7 @@ export const chatWebSocket = {
   open(ws: ChatWsSocket) {
     const { sessionId, projectName } = ws.data;
     const session = chatService.getSession(sessionId);
-    const providerId = session?.providerId ?? "claude-sdk";
+    const providerId = session?.providerId ?? providerRegistry.getDefault().id;
 
     let projectPath: string | undefined;
     if (projectName) {
@@ -238,7 +238,7 @@ export const chatWebSocket = {
     }
 
     const entry = activeSessions.get(sessionId);
-    const providerId = entry?.providerId ?? "mock";
+    const providerId = entry?.providerId ?? providerRegistry.getDefault().id;
 
     if (parsed.type === "message") {
       // Resume session in provider first

package/src/services/config.service.ts

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import yaml from "js-yaml";
 import type { PpmConfig } from "../types/config.ts";
-import { DEFAULT_CONFIG } from "../types/config.ts";
+import { DEFAULT_CONFIG, sanitizeConfig } from "../types/config.ts";
 
 const PPM_DIR = resolve(homedir(), ".ppm");
 const GLOBAL_CONFIG_PATH = resolve(PPM_DIR, "config.yaml");
@@ -34,6 +34,10 @@ class ConfigService {
             this.config.auth.token = randomBytes(16).toString("hex");
             this.save();
           }
+          // Fix invalid config values and persist corrections
+          if (sanitizeConfig(this.config)) {
+            this.save();
+          }
           return this.config;
         }
       }

package/src/services/project.service.ts

@@ -13,6 +13,7 @@ class ProjectService {
     return projects.map((p) => ({
       name: p.name,
       path: p.path,
+      ...(p.color ? { color: p.color } : {}),
     }));
   }
 

package/src/types/config.ts

@@ -4,10 +4,13 @@ export interface PushConfig {
   vapid_subject: string;
 }
 
+export type ThemeConfig = "light" | "dark" | "system";
+
 export interface PpmConfig {
   device_name: string;
   port: number;
   host: string;
+  theme: ThemeConfig;
   auth: AuthConfig;
   projects: ProjectConfig[];
   ai: AIConfig;
@@ -22,6 +25,7 @@ export interface AuthConfig {
 export interface ProjectConfig {
   path: string;
   name: string;
+  color?: string;
 }
 
 export interface AIConfig {
@@ -44,6 +48,7 @@ export const DEFAULT_CONFIG: PpmConfig = {
   device_name: "",
   port: 8080,
   host: "0.0.0.0",
+  theme: "system",
   auth: { enabled: true, token: "" },
   projects: [],
   ai: {
@@ -63,6 +68,9 @@ export const DEFAULT_CONFIG: PpmConfig = {
 const VALID_TYPES = ["agent-sdk", "mock"] as const;
 const VALID_EFFORTS = ["low", "medium", "high", "max"] as const;
 const VALID_MODELS = ["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"] as const;
+/** Only these values are allowed for default_provider in config */
+export const VALID_PROVIDERS = ["claude"] as const;
+const VALID_THEMES: ThemeConfig[] = ["light", "dark", "system"];
 
 /** Validate AI provider config fields. Returns array of error messages (empty = valid). */
 export function validateAIProviderConfig(config: Partial<AIProviderConfig>): string[] {
@@ -95,3 +103,32 @@ export function validateDefaultProvider(defaultProvider: string, providers: Reco
   }
   return null;
 }
+
+/**
+ * Sanitize a loaded config — fix invalid values to defaults.
+ * Returns true if any field was corrected (caller should save).
+ */
+export function sanitizeConfig(config: PpmConfig): boolean {
+  let dirty = false;
+
+  // Fix invalid theme
+  if (!VALID_THEMES.includes(config.theme)) {
+    config.theme = DEFAULT_CONFIG.theme;
+    dirty = true;
+  }
+
+  // Fix invalid default_provider — must be in VALID_PROVIDERS
+  if (!VALID_PROVIDERS.includes(config.ai.default_provider as any)) {
+    config.ai.default_provider = DEFAULT_CONFIG.ai.default_provider;
+    dirty = true;
+  }
+
+  // Ensure the default provider has a config entry
+  if (!config.ai.providers[config.ai.default_provider]) {
+    config.ai.providers[config.ai.default_provider] =
+      structuredClone(DEFAULT_CONFIG.ai.providers[DEFAULT_CONFIG.ai.default_provider]!);
+    dirty = true;
+  }
+
+  return dirty;
+}

package/src/types/project.ts

@@ -1,6 +1,7 @@
 export interface Project {
   name: string;
   path: string;
+  color?: string;
 }
 
 export interface ProjectInfo extends Project {