@hienlh/ppm 0.9.0-beta.9 → 0.9.2

package/docs/extension-development-guide.md

@@ -0,0 +1,532 @@
+# PPM Extension Development Guide
+
+Build extensions that add features to PPM. Extensions are TypeScript packages that hook into PPM's UI, commands, file system, and configuration.
+
+---
+
+## Extension Basics
+
+### Structure
+
+A PPM extension is a directory with `package.json` manifest and TypeScript entry point:
+
+```
+my-extension/
+├── package.json
+├── tsconfig.json
+├── src/
+│   └── extension.ts          # Entry point with activate() & deactivate()
+├── webview/                  # Optional: webview HTML/CSS/JS
+│   └── index.html
+└── README.md
+```
+
+### Manifest (package.json)
+
+```json
+{
+  "name": "@org/ext-myfeature",
+  "version": "1.0.0",
+  "main": "src/extension.ts",
+  "engines": { "ppm": ">=0.9.0" },
+  "activationEvents": [
+    "onCommand:myext.doSomething",
+    "onView:myext.sidebar"
+  ],
+  "contributes": {
+    "commands": [
+      { "command": "myext.doSomething", "title": "My Feature: Do Something" }
+    ],
+    "views": {
+      "sidebar": [
+        { "id": "myext.sidebar", "name": "My Sidebar", "type": "tree" }
+      ]
+    },
+    "menus": {
+      "commandPalette": [
+        { "command": "myext.doSomething" }
+      ]
+    },
+    "configuration": {
+      "properties": {
+        "myext.setting": { "type": "boolean", "default": true }
+      }
+    }
+  },
+  "ppm": {
+    "displayName": "My Feature",
+    "icon": "star",
+    "webviewDir": "webview"
+  }
+}
+```
+
+**Key fields:**
+- `main` — TypeScript file with `export function activate(context, vscode) {}`
+- `engines.ppm` — minimum PPM version (not `vscode`)
+- `activationEvents` — when extension loads (commands, views, or startup)
+- `contributes` — UI elements: commands, views, menus, config
+- `ppm.displayName` — human-readable name in extension UI
+- `ppm.icon` — icon name (standard VSCode icon set)
+- `ppm.webviewDir` — directory containing webview HTML
+
+---
+
+## Activation & Lifecycle
+
+Extensions run in an isolated Bun Worker thread. The Worker receives `context` and `vscode` API:
+
+```typescript
+/** Runs when activation event fires */
+export function activate(context: ExtensionContext, vscode: VscodeApi): void {
+  console.log("Extension activated");
+  
+  // Register commands, listeners, views, etc.
+  context.subscriptions.push(
+    vscode.commands.registerCommand("myext.foo", () => {
+      // ...
+    })
+  );
+}
+
+/** Cleanup on disable/uninstall */
+export function deactivate(): void {
+  console.log("Extension deactivated");
+  // Browser/streams are auto-closed; use this for final logging
+}
+```
+
+**Important:** Push ALL disposables (commands, listeners, panels, views) to `context.subscriptions` for automatic cleanup.
+
+---
+
+## API Surface
+
+### Commands
+
+Register and execute commands:
+
+```typescript
+// Register
+const cmd = vscode.commands.registerCommand("myext.foo", (arg1, arg2) => {
+  return "result";
+});
+context.subscriptions.push(cmd);
+
+// Execute (from command palette or button click)
+// vscode.commands.executeCommand("myext.foo", arg1, arg2);
+```
+
+### Messages (Dialogs)
+
+```typescript
+// Information
+await vscode.window.showInformationMessage("Done!", "OK", "Cancel");
+
+// Warning
+await vscode.window.showWarningMessage("Are you sure?", "Yes", "No");
+
+// Error
+await vscode.window.showErrorMessage("Failed!", "Retry");
+```
+
+### Quick Pick
+
+```typescript
+const selected = await vscode.window.showQuickPick(
+  [
+    { label: "Option A", description: "First choice" },
+    { label: "Option B", description: "Second choice" }
+  ],
+  {
+    title: "Choose one",
+    placeHolder: "Start typing to filter...",
+    canPickMany: false,
+    matchOnDescription: true
+  }
+);
+```
+
+### Input Box
+
+```typescript
+const input = await vscode.window.showInputBox({
+  title: "Enter name",
+  prompt: "What is your name?",
+  placeHolder: "John Doe",
+  password: false
+});
+```
+
+### Status Bar
+
+```typescript
+const item = vscode.window.createStatusBarItem(
+  vscode.StatusBarAlignment.Right,
+  100  // priority
+);
+item.text = "⚙️ Status";
+item.tooltip = "Click for menu";
+item.command = "myext.openMenu";
+item.show();
+context.subscriptions.push(item);
+```
+
+### Tree View
+
+Sidebar tree for displaying hierarchical data:
+
+```typescript
+class MyTreeProvider {
+  getChildren(element?: NodeData): Promise<NodeData[]> {
+    if (!element) {
+      // Root items
+      return [
+        { id: "1", label: "Item 1" },
+        { id: "2", label: "Item 2" }
+      ];
+    }
+    // Children of element
+    return [];
+  }
+
+  getTreeItem(element: NodeData) {
+    return {
+      id: element.id,
+      label: element.label,
+      collapsibleState: element.children?.length ? 
+        vscode.TreeItemCollapsibleState.Collapsed : 
+        vscode.TreeItemCollapsibleState.None,
+      command: { command: "myext.selectNode", arguments: [element.id] }
+    };
+  }
+}
+
+const provider = new MyTreeProvider();
+const tree = vscode.window.createTreeView("myext.tree", {
+  treeDataProvider: provider
+});
+context.subscriptions.push(tree);
+```
+
+**viewId** must match the `contributes.views[].id` in package.json.
+
+### Webview Panel
+
+Sandboxed iframe for custom UI:
+
+```typescript
+const panel = vscode.window.createWebviewPanel(
+  "myext.panel",        // viewType (unique)
+  "My Panel",           // title (shown in tab)
+  vscode.ViewColumn.Active
+);
+
+// Set HTML (scripts auto-sandboxed, allow-scripts only)
+panel.webview.html = `
+  <!DOCTYPE html>
+  <html>
+  <body>
+    <button id="btn">Click me</button>
+    <script>
+      const vscode = acquireVsCodeApi();
+      document.getElementById("btn").onclick = () => {
+        vscode.postMessage({ type: "buttonClicked" });
+      };
+      
+      window.addEventListener("message", (e) => {
+        console.log("From extension:", e.data);
+      });
+    </script>
+  </body>
+  </html>
+`;
+
+// Receive messages from webview
+panel.webview.onDidReceiveMessage(async (msg) => {
+  if (msg.type === "buttonClicked") {
+    await vscode.window.showInformationMessage("Button clicked!");
+    await panel.webview.postMessage({ type: "response", data: "Hello from extension" });
+  }
+});
+
+context.subscriptions.push(panel.onDidDispose(() => {
+  console.log("Panel closed");
+}));
+```
+
+### Configuration
+
+```typescript
+// Read
+const config = vscode.workspace.getConfiguration("myext");
+const timeout = config.get<number>("timeout", 5000);
+
+// Update
+await config.update("timeout", 10000, vscode.ConfigurationTarget.Global);
+```
+
+### Storage (Memento)
+
+Persist data across sessions:
+
+```typescript
+// Global (user-wide)
+await context.globalState.update("key", { foo: "bar" });
+const value = context.globalState.get("key");
+
+// Workspace-scoped
+await context.workspaceState.update("project", "data");
+```
+
+### Utilities
+
+```typescript
+// URI
+const uri = vscode.Uri.file("/path/to/file");
+const webUri = panel.webview.asWebviewUri(uri);
+
+// Disposable
+const disposable = vscode.Disposable.from(
+  vscode.commands.registerCommand("a", () => {}),
+  vscode.commands.registerCommand("b", () => {})
+);
+
+// EventEmitter
+const emitter = new vscode.EventEmitter<string>();
+emitter.fire("event data");  // Notify listeners
+// const unsub = emitter.event((data) => {});
+```
+
+---
+
+## API Support Matrix
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| **Commands** | ✅ Supported | `registerCommand`, `executeCommand` |
+| **Messages** | ✅ Supported | Info, warning, error dialogs |
+| **Quick Pick** | ✅ Supported | Single/multi-select, filtering |
+| **Input Box** | ✅ Supported | Text input with validation (client-side) |
+| **Status Bar** | ✅ Supported | Left/right alignment, priority, commands |
+| **Tree View** | ✅ Supported | Hierarchical sidebar trees |
+| **Webview Panel** | ✅ Supported | Sandboxed iframe, 2-way messaging |
+| **Workspace Config** | ✅ Supported | Read/write user & workspace settings |
+| **Workspace FS** | ⚠️ Partial | Read, write, stat, readDirectory (no watch) |
+| **Storage (Memento)** | ✅ Supported | Global & workspace state, auto-persisted |
+| **Uri** | ✅ Supported | File/webview URI utilities |
+| **EventEmitter** | ✅ Supported | Custom event streams |
+| **Disposable** | ✅ Supported | Cleanup & resource management |
+| **Environment** | ✅ Supported | App name, machine ID |
+| **Languages** | ❌ Not supported | Syntax highlighting, language services |
+| **Debug** | ❌ Not supported | Debugger integration |
+| **Tasks** | ❌ Not supported | Task provider, task execution |
+| **SCM** | ❌ Not supported | Source control providers |
+| **Notebooks** | ❌ Not supported | Notebook editing |
+| **Authentication** | ❌ Not supported | Auth provider, sessions |
+| **Tests** | ❌ Not supported | Test controller |
+
+---
+
+## Webview Details
+
+### Sandbox
+
+Webviews run in a sandboxed iframe with **`allow-scripts` only** — no inline styles, event handlers, or external scripts. Use a bundler or inline `<style>` tags.
+
+### Communication
+
+**From webview to extension:**
+```typescript
+const vscode = acquireVsCodeApi();
+vscode.postMessage({ type: "action", data: "..." });
+```
+
+**From extension to webview:**
+```typescript
+panel.webview.postMessage({ type: "update", data: "..." });
+panel.webview.onDidReceiveMessage((msg) => {
+  console.log("From webview:", msg);
+});
+```
+
+### HTML Setup
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <style>
+    body { font-family: sans-serif; padding: 20px; }
+    button { padding: 8px 16px; cursor: pointer; }
+  </style>
+</head>
+<body>
+  <h1>My Webview</h1>
+  <button id="btn">Send Message</button>
+  
+  <script>
+    const vscode = acquireVsCodeApi();
+    
+    document.getElementById("btn").onclick = () => {
+      vscode.postMessage({ type: "click", time: Date.now() });
+    };
+    
+    window.addEventListener("message", (e) => {
+      const { type, data } = e.data;
+      if (type === "update") {
+        document.body.innerHTML += `<p>${data}</p>`;
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Porting from VSCode
+
+PPM uses the same API shape as VSCode. Porting is straightforward:
+
+### 1. Update imports
+
+**Before (VSCode):**
+```typescript
+import * as vscode from "vscode";
+
+export function activate(context: vscode.ExtensionContext) {
+  // ...
+}
+```
+
+**After (PPM):**
+```typescript
+import type { ExtensionContext } from "@ppm/vscode-compat";
+
+export function activate(context: ExtensionContext, vscode: any) {
+  // vscode is passed as 2nd argument
+  // ...
+}
+```
+
+Or import for type checking:
+```typescript
+import * as vscode from "@ppm/vscode-compat";
+
+export function activate(context: ExtensionContext, _vscode: typeof vscode) {
+  // ...
+}
+```
+
+### 2. Update package.json
+
+```json
+{
+  "engines": { "ppm": ">=0.9.0" }  // was vscode
+}
+```
+
+### 3. Check API support
+
+Verify unsupported features aren't used (see API Support Matrix above).
+
+### 4. Test
+
+```bash
+ppm ext dev ./path/to/extension
+```
+
+---
+
+## Example: Database Viewer
+
+See `packages/ext-database/` in the PPM repo for a complete reference extension:
+
+- **Tree view** of database connections
+- **Commands** to open query panel
+- **Webview panel** for SQL editor
+- **Status bar** icon
+- **Configuration** (maxRows, autoConnect)
+- **RPC to backend** for queries
+
+```typescript
+export function activate(context: ExtensionContext, vscode: any) {
+  // Tree view
+  const provider = new ConnectionTreeProvider();
+  const tree = vscode.window.createTreeView("ppm-db.connections", {
+    treeDataProvider: provider
+  });
+  context.subscriptions.push(tree);
+
+  // Command
+  context.subscriptions.push(
+    vscode.commands.registerCommand("ppm-db.openViewer", (connId) => {
+      const panel = vscode.window.createWebviewPanel(
+        "ppm-db.query",
+        "Query",
+        vscode.ViewColumn.Active
+      );
+      panel.webview.html = `...`;
+      panel.webview.onDidReceiveMessage(async (msg) => {
+        if (msg.type === "query") {
+          const res = await fetch(`/api/db/${connId}/query`, {
+            method: "POST",
+            body: JSON.stringify({ sql: msg.sql })
+          });
+          await panel.webview.postMessage(await res.json());
+        }
+      });
+    })
+  );
+
+  // Status bar
+  const status = vscode.window.createStatusBarItem(
+    vscode.StatusBarAlignment.Right
+  );
+  status.text = "DB";
+  status.show();
+  context.subscriptions.push(status);
+}
+```
+
+---
+
+## Best Practices
+
+1. **Cleanup**: Always push disposables to `context.subscriptions`.
+2. **Errors**: Catch and show errors via `showErrorMessage()`.
+3. **Async**: Use `await` for RPC calls; block UI during long operations.
+4. **Storage**: Use `Memento` for persistence, not file system (unless granted access).
+5. **Webview Security**: Never use `eval()`, `innerHTML` with user input, or external CDNs.
+6. **Activation**: Lazy-load expensive code via activation events, not on require.
+7. **Testing**: Use `ppm ext dev` to load locally before publishing.
+
+---
+
+## Publishing
+
+Register your extension with PPM's extension registry (coming in v0.9). For now, distribute via npm or GitHub.
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Extension doesn't activate | Check `activationEvents` in package.json matches your commands/views |
+| Command not found | Verify `contributes.commands[].command` id |
+| Tree view empty | Implement `getChildren()` and `getTreeItem()` in provider |
+| Webview blank | Check `panel.webview.html` is valid HTML; test in browser first |
+| RPC timeout | Network issue or long-running request; add retry logic |
+| Storage not persisted | Use `Memento.update()`, not local variables |
+| Unsupported API error | Check API Support Matrix; file issue if critical |
+
+---
+
+## Learn More
+
+- [VSCode Extension API](https://code.visualstudio.com/api) — reference (PPM subset)
+- `packages/ext-database/` — working example
+- `packages/vscode-compat/src/` — API implementation
+- GitHub issues — feature requests & bugs

package/docs/project-changelog.md

@@ -2,7 +2,57 @@
 
 All notable changes to PPM are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-**Current Version:** v0.8.63
+**Current Version:** v0.9.0
+
+---
+
+## [0.9.0] — 2026-04-03
+
+### Added
+- **Extension System (Phase 1-6)** — VSCode-compatible npm extensions with Bun Worker isolation, RPC protocol, @ppm/vscode-compat API shim, UI components (TreeView, WebviewPanel, StatusBar, QuickPick, InputBox), WS bridge, ext-database demo extension, Extension Manager UI, CLI support
+- **Multi-Provider AI** — ProviderInterface, CliProvider base, CursorCliProvider with NDJSON streaming, provider selector UI
+- **MCP Server Management** — REST API CRUD, SQLite storage, Settings UI, auto-import from ~/.claude.json, SDK integration
+- **ext-database extension** — Connection tree with color dots/badges/actions, table viewer webview with data grid/inline editing/pagination/SQL panel, add connection via QuickPick+InputBox flow
+
+### Technical Details
+- Extension architecture: npm packages isolated in Bun Workers, communicate via RPC, manifest-driven contribution points (commands, views, menus, configuration)
+- Multi-provider: Tier 1 (Claude Agent SDK, full agentic), Tier 2 (Cursor CLI, agentic via own tool system)
+- MCP: Servers passed to SDK as `mcpServers`, tools auto-allowed via `mcp__*` wildcard
+
+---
+
+## [0.8.77] — 2026-04-01
+
+### Added
+- **Deterministic Tab URLs + Backend Workspace Sync**
+  - Tab IDs now deterministic ({type}:{identifier}) instead of random (tab-xxxx)
+  - URL format changed: `/project/{name}/{tabType}/{identifier}` (e.g., `/project/ppm/editor/src/index.ts`)
+  - New `workspace_state` database table (schema v10) persists tab layout per project
+  - GET/PUT `/api/project/:name/workspace` endpoints for server-side persistence
+  - Frontend syncs workspace layout to server with 1.5s debounce
+  - Deep linking from URL auto-creates tabs if missing
+  - Latest-wins conflict resolution: server timestamp > client localStorage
+  - Tab ID patterns standardized: `editor:path`, `chat:provider/sessionId`, `terminal:index`, etc.
+  - Migration from random IDs to deterministic IDs on first load
+
+### Technical Details
+- **Files Created:**
+  - `src/server/routes/workspace.ts` — Workspace GET/PUT endpoints
+  - `src/web/hooks/use-workspace-sync.ts` — Server sync orchestration with debounce
+- **Files Modified:**
+  - `src/services/db.service.ts` — Added workspace_state table (schema v10), helper functions
+  - `src/web/stores/panel-utils.ts` — Deterministic tab ID derivation logic
+  - `src/web/hooks/use-url-sync.ts` — URL parsing/building with new format
+  - `src/web/stores/panel-store.ts` — Load workspace from server on project switch
+  - `src/web/stores/tab-store.ts` — Tab interface updated with metadata
+- **Breaking Changes:** URLs changed; old `/project/{name}/tab/{id}` URLs redirected or ignored (fallback to project root)
+- **Migration:** Client-side: old random tab IDs migrated to deterministic format on first load
+
+### Benefits
+- **Shareable deep links** — URLs point to specific files/chats (e.g., `/project/ppm/editor/src/index.ts`)
+- **Cross-device persistence** — Workspace layout saved on server, restored on any device
+- **URL-driven navigation** — Paste URL to recreate workspace state
+- **Conflict-free sync** — Latest timestamp wins; no manual merge dialogs
 
 ---
 

package/docs/project-roadmap.md

@@ -58,25 +58,31 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 
 **Theme:** Multi-provider AI (Claude + Cursor) + extension system. Ship a focused release, expand providers later.
 
-**Overall progress: ~53%** (2/3 features complete, merge all at 100%)
+**Overall progress: 100%** (All 3 features complete)
 
 | Feature | Priority | Status | Description |
 |---------|----------|--------|-------------|
 | **Multi-provider AI** | Critical | ✅ Done | ProviderInterface, registry, Cursor CLI, CLI provider base, UI provider/model selector, permission mode selector, system prompt customization, comprehensive tests — all on beta branch. |
 | **MCP Management** | Medium | ✅ Done | REST API (CRUD + import), SQLite storage, Settings UI, auto-import from `~/.claude.json`, validation, SDK integration. |
-| **Extension architecture** | High | 🔴 0% | Dynamic extension loading. Extensions = npm packages. First extension: extract DB viewer from core. Extension API: register routes, UI panels, sidebar tabs, skills. Config: `"extensions": ["@ppm/ext-database", "@ppm/ext-docker"]`. |
+| **Extension architecture (Phase 1-6)** | High | ✅ Done | VSCode-compatible npm extensions, Bun Worker isolation, RPC protocol, state persistence, contribution registry, CLI support, dev mode. @ppm/vscode-compat API shim (commands, window, workspace). UI components (StatusBar, TreeView, WebviewPanel, QuickPick, InputBox). WS bridge for real-time ext↔browser communication. First extension: ext-database with tree view + SQL query panel. Unit tests + extension dev guide. |
 
 **Multi-provider — v0.9 scope (reduced):**
 - Tier 1 (full agentic): Claude Agent SDK — file edit, terminal, git, full autonomy
 - Tier 2 (agentic CLI): Cursor — agentic via its own tool system
 - Provider interface is clean enough to add more providers later without refactor
 
-**Deferred to v0.9.5+:**
+**Deferred to v0.9.5+ (Multi-Provider Phase 2):**
 - Gemini CLI (Tier 2)
 - OpenAI Codex (Tier 2)
 - Tier 3 (chat-only): Any OpenAI-compatible API
 - Chinese providers (DeepSeek, Qwen) — v1.0+
 
+**Extension System — remaining for v0.10+:**
+- Settings UI auto-generation from manifest
+- Hot reload during dev (`ppm ext dev --watch`)
+- Extension template scaffold (`ppm ext create <name>`)
+- Extension marketplace (v1.0)
+
 **Extension architecture — design principles:**
 - Extensions are npm packages: `ppm ext install @ppm/ext-database`
 - Extension manifest defines: skills, UI panels, sidebar tabs, routes, settings schema