pi-desktop-ui 1.0.1

package/README.md

@@ -0,0 +1,129 @@
+# Pi Desktop UI
+
+A native desktop GUI for [pi](https://github.com/mariozechner/pi-coding-agent) — a fully functional chat window that mirrors your terminal session with real-time streaming, markdown rendering, and workspace management.
+
+![Pi Desktop - Chat View](assets/Screenshot_1.png)
+
+![Pi Desktop - Code Diffs & Tools](assets/Screenshot_2.png)
+
+## Features
+
+- **Full bidirectional chat** — send messages from the window or the terminal, both stay in sync
+- **Real-time streaming** — assistant responses stream token-by-token with thinking indicators
+- **Markdown rendering** with syntax-highlighted code blocks
+- **Mermaid diagrams** — flowcharts, sequence diagrams, state machines, and more rendered as SVG (neutral theme, dark mode adapted via CSS)
+- **LaTeX math** — inline `$...$` and block `$$...$$` formulas rendered via KaTeX
+- **Cancel streaming** — stop button replaces send during streaming, Escape / Ctrl+C keyboard shortcuts
+- **Tool execution display** — see tool calls (bash, read, edit, write) with inline diffs for edits
+- **Sidebar navigation:**
+  - **Threads** — browse and switch between session threads
+  - **Skills & Extensions** — view installed skills and loaded extensions
+  - **Settings** — model info, token stats, cost tracking
+  - **Explorer** — browse project files
+  - **Workspaces** — navigate across all pi workspaces and their sessions
+- **Slash command palette** — access all pi commands from the window
+- **File attachments** — drag & drop or attach files to messages
+- **Custom footer & widget** in the terminal showing project, branch, model, and token stats
+
+## Installation
+
+### From Git (recommended)
+
+```bash
+pi install git:github.com/pvjagtap/pi-desktop-ui
+```
+
+### Manual
+
+Clone the repo into your pi extensions directory:
+
+```bash
+git clone https://github.com/pvjagtap/pi-desktop-ui ~/.pi/agent/extensions/pi-desktop-ui
+cd ~/.pi/agent/extensions/pi-desktop-ui
+npm install
+```
+
+Then reload pi:
+
+```
+/reload
+```
+
+## Usage
+
+### Auto-open on startup
+
+```bash
+pi --desktop
+```
+
+This launches pi and automatically opens the desktop window. You can also create a shortcut using the included `pi-desktop.cmd` (Windows) or `pi-desktop.sh` (macOS/Linux) scripts.
+
+### Open manually during a session
+
+| Method | Action |
+|--------|--------|
+| `Ctrl+Alt+N` | Keyboard shortcut |
+| `/desktop` | Slash command |
+| `/nav` | Slash command (alias) |
+
+The window opens alongside your terminal — type in either place. Messages, tool calls, and responses are synced in real-time.
+
+## Security
+
+The extension implements multiple layers of defense:
+
+- **XSS prevention** — all markdown output is sanitized through [DOMPurify](https://github.com/cure53/DOMPurify) with a strict tag/attribute allowlist
+- **Content Security Policy** — restrictive CSP blocks inline scripts from external sources, disables `connect-src`, `object-src`, and `form-action`
+- **Subresource Integrity** — CDN dependencies (marked, highlight.js, DOMPurify) are loaded with `integrity` hashes to prevent tampering
+- **Pinned dependencies** — all CDN scripts are pinned to exact versions
+- **Path traversal protection** — file explorer, thread viewer, and workspace handlers validate that paths stay within allowed directories (cwd and `~/.pi/agent/sessions/`)
+- **Attachment limits** — file uploads are capped at 25 MB with sanitized filenames
+- **Input validation** — message length caps, strict shape validation on persisted config, and traversal rejection on all user-supplied paths
+
+## Dependencies
+
+- [glimpseui](https://github.com/nickarrow/glimpseui) — native webview windows from Node.js
+- [marked](https://github.com/markedjs/marked) — markdown parsing
+- [mermaid](https://github.com/mermaid-js/mermaid) — diagram rendering (loaded via CDN)
+- [KaTeX](https://github.com/KaTeX/KaTeX) — LaTeX math rendering (loaded via CDN)
+- [DOMPurify](https://github.com/cure53/DOMPurify) — HTML sanitization (loaded via CDN)
+- [highlight.js](https://github.com/highlightjs/highlight.js) — syntax highlighting (loaded via CDN)
+- [ws](https://github.com/websockets/ws) — WebSocket support
+
+## Requirements
+
+- [pi](https://github.com/mariozechner/pi-coding-agent) coding agent
+- The [glimpse](https://github.com/nickarrow/glimpseui) skill/package must be available (provides the `glimpseui` module)
+
+## How It Works
+
+The extension hooks into pi's event system to capture the full agent lifecycle:
+
+1. **`session_start`** — initializes the custom footer and context widget
+2. **`message_start` / `message_update` / `message_end`** — streams assistant responses to the window
+3. **`tool_execution_start` / `tool_execution_end`** — displays tool calls with arguments and results
+4. **`agent_start` / `agent_end`** — shows loading states and updates token stats
+
+User messages typed in the desktop window are sent to pi via `pi.sendUserMessage()`, and the response streams back through the same event hooks.
+
+## Package Structure
+
+```
+pi-desktop-ui/
+├── assets/
+│   ├── Screenshot_1.png
+│   └── Screenshot_2.png
+├── web/
+│   ├── index.html     # Desktop window HTML shell
+│   └── app.js         # Frontend app (sidebar, chat, explorer, themes)
+├── index.ts           # Extension entry point (events, commands, window management)
+├── package.json       # Pi package manifest + dependencies
+├── pi-desktop.cmd     # Windows launcher shortcut
+├── pi-desktop.sh      # macOS/Linux launcher shortcut
+└── README.md
+```
+
+## License
+
+MIT

package/diagrams.md

@@ -0,0 +1,291 @@
+# Pi Desktop UI — Architecture Diagrams
+
+## 1. Extension Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Registered: pi loads extension
+    Registered --> SessionStart: session_start event
+    SessionStart --> FooterEnabled: enableFooter()
+    FooterEnabled --> WidgetEnabled: enableWidget()
+    WidgetEnabled --> Ready: setStatus("desktop")
+
+    state Ready {
+        [*] --> Idle
+        Idle --> WindowOpen: Ctrl+Alt+N / /desktop / /nav / --desktop flag
+        WindowOpen --> Idle: window closed
+        WindowOpen --> WindowOpen: session_start (reload/new/resume/fork)
+    }
+
+    Ready --> Shutdown: session_shutdown
+    Shutdown --> [*]: closeActiveWindow()
+```
+
+## 2. High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph Terminal["Pi Terminal - TUI"]
+        PiAgent["Pi Agent Core"]
+        Footer["Custom Footer"]
+        Widget["Context Widget"]
+        Status["Status Bar"]
+    end
+
+    subgraph Extension["index.ts Extension"]
+        EventHandlers["Event Handlers"]
+        WindowManager["Window Manager"]
+        DataCollectors["Data Collectors"]
+        Security["Security Layer"]
+        CommandReg["Command Registration"]
+        HTMLBuilder["HTML Builder"]
+    end
+
+    subgraph DesktopWindow["Glimpse Native Window"]
+        IndexHTML["web/index.html"]
+        Sidebar["Sidebar Navigation"]
+        ChatView["Chat View"]
+        ExplorerView["File Explorer"]
+        SkillsView["Skills View"]
+        SettingsView["Settings View"]
+        WorkspaceView["Workspace View"]
+        DiffOverlay["Diff Overlay"]
+        CommandPalette["Command Palette"]
+        StreamingUI["Streaming UI"]
+    end
+
+    PiAgent -->|"pi.on() events"| EventHandlers
+    EventHandlers -->|"sendToWindow()"| WindowManager
+    WindowManager -->|"glimpse.send(js)"| DesktopWindow
+    DesktopWindow -->|"glimpse.on(message)"| WindowManager
+    WindowManager -->|"handleWindowMessage()"| DataCollectors
+    DataCollectors -->|"sendToWindow()"| WindowManager
+    CommandReg -->|"registerCommand"| PiAgent
+    HTMLBuilder -->|"buildDesktopHtml()"| WindowManager
+    Extension --> Footer
+    Extension --> Widget
+    Extension --> Status
+    Security -.->|validates| DataCollectors
+```
+
+## 3. Message Streaming Flow
+
+```mermaid
+sequenceDiagram
+    participant User as User (Terminal or Window)
+    participant Pi as Pi Agent
+    participant Ext as Extension (index.ts)
+    participant Win as Desktop Window (app.js)
+
+    User->>Win: Types message + Enter
+    Win->>Ext: { type: "send-message", text }
+    Ext->>Pi: pi.sendUserMessage(text)
+
+    Pi->>Ext: agent_start event
+    Ext->>Win: { type: "agent-start" }
+    Note over Win: Show waiting indicator
+
+    Pi->>Ext: message_start (assistant)
+    Ext->>Win: { type: "message-start" }
+
+    loop Thinking (optional)
+        Pi->>Ext: message_update (thinking_start)
+        Ext->>Win: { type: "thinking-start" }
+        Pi->>Ext: message_update (thinking_delta)
+        Ext->>Win: { type: "thinking-chunk", text }
+        Pi->>Ext: message_update (thinking_end)
+        Ext->>Win: { type: "thinking-end" }
+    end
+
+    loop Text streaming
+        Pi->>Ext: message_update (text_start)
+        Ext->>Win: { type: "message-chunk-start" }
+        Pi->>Ext: message_update (text_delta)
+        Ext->>Win: { type: "message-chunk", text }
+        Pi->>Ext: message_update (text_end)
+        Ext->>Win: { type: "message-chunk-end" }
+    end
+
+    Pi->>Ext: message_end (assistant)
+    Ext->>Win: { type: "message-end", content }
+    Note over Win: Append final message
+
+    Pi->>Ext: agent_end event
+    Ext->>Win: { type: "agent-end" }
+    Ext->>Win: { type: "stats-update", stats }
+    Note over Win: Update token stats
+```
+
+## 4. Tool Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant Pi as Pi Agent
+    participant Ext as Extension
+    participant Win as Desktop Window
+
+    Pi->>Ext: tool_execution_start
+    Note over Ext: Format args display<br/>(bash→command, read→path,<br/>edit→diffs as base64)
+
+    alt Plan Mode Active & Write Tool
+        Ext->>Win: { type: "plan-mode-violation" }
+        Note over Win: Show warning toast
+    end
+
+    Ext->>Win: { type: "tool-start", toolName,<br/>toolCallId, argsDisplay,<br/>editDiffsB64, editPath }
+    Note over Win: Show spinner + tool card
+
+    Pi->>Ext: tool_execution_end
+    Ext->>Win: { type: "tool-end", toolCallId,<br/>isError, resultText }
+    Note over Win: Update card in-place<br/>(preserves details open state)
+```
+
+## 5. Window ↔ Extension Communication Protocol
+
+```mermaid
+graph LR
+    subgraph "Window → Extension Messages"
+        SM["send-message"] --> |text| A1[pi.sendUserMessage]
+        OT["open-thread"] --> |file| A2[extractThreadMessages]
+        NAV["nav"] --> |action| A3[getDirEntries]
+        ETE["explorer-tree-expand"] --> |path| A4[getDirEntries + validate]
+        EO["explorer-open"] --> |path| A5[readFile / openApp]
+        GC["get-commands"] --> A6[getAllCommands]
+        GS["get-stats"] --> A7[getTokenStats]
+        RT["refresh-threads"] --> A8[getSessionThreads]
+        RS["refresh-skills"] --> A9[getSkills + getExtensions]
+        GW["get-workspaces"] --> A10[getWorkspaces]
+        GWS["get-workspace-sessions"] --> A11[getWorkspaceSessions]
+        ST["search-threads"] --> A12[searchSessionThreads]
+        OFP["open-folder-path"] --> A13[resolve + validate path]
+        SPM["set-plan-mode"] --> A14[toggle planMode]
+        AF["attach-file"] --> A15[write to tmp]
+        CS["cancel-streaming"] --> A16[ctx.abort]
+        SHW["set-hidden-workspaces"] --> A17[saveHiddenWorkspaces]
+        CL["close"] --> A18[closeActiveWindow]
+    end
+```
+
+```mermaid
+graph LR
+    subgraph "Extension → Window Messages"
+        B1["agent-start / agent-end"]
+        B2["message-start / chunk / end"]
+        B3["thinking-start / chunk / end"]
+        B4["tool-start / tool-end"]
+        B5["stats-update"]
+        B6["thread-messages"]
+        B7["explorer-data / tree-children"]
+        B8["file-content"]
+        B9["commands-list"]
+        B10["update-threads / update-skills"]
+        B11["workspaces-list / workspace-sessions"]
+        B12["search-results"]
+        B13["workspace-opened"]
+        B14["file-attached-ack"]
+        B15["plan-mode-violation"]
+        B16["session-changed"]
+        B17["provider-request"]
+    end
+```
+
+## 6. Sidebar Navigation State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Threads: default view
+
+    Threads --> Skills: click Skills nav
+    Threads --> Settings: click Settings nav
+    Threads --> Explorer: click Explorer nav
+    Threads --> WorkspaceModal: click Open Workspace nav
+
+    Skills --> Threads: click Threads nav
+    Settings --> Threads: click Threads nav
+    Explorer --> Threads: click Explorer tree back
+    WorkspaceModal --> Threads: close modal
+
+    state Threads {
+        [*] --> CurrentSession
+        CurrentSession --> OldThread: click thread in sidebar
+        OldThread --> CurrentSession: Escape key
+        CurrentSession --> SearchResults: type in search box
+        SearchResults --> OldThread: click search result
+        SearchResults --> CurrentSession: clear search
+    }
+
+    state Explorer {
+        [*] --> FileTree
+        FileTree --> FileViewer: click file
+        FileViewer --> FileTree: Back button
+        FileTree --> FileTree: expand/collapse dirs
+    }
+
+    state WorkspaceModal {
+        [*] --> BrowseWorkspaces
+        BrowseWorkspaces --> OpenFolder: enter path
+        BrowseWorkspaces --> ExpandWorkspace: click workspace
+    }
+```
+
+## 7. Data Flow on Window Open
+
+```mermaid
+flowchart TD
+    A[openDesktopWindow called] --> B{window already open?}
+    B -->|Yes| C[Notify warning & return]
+    B -->|No| D[collectWindowData]
+
+    D --> D1[getTokenStats]
+    D --> D2[getSessionThreads]
+    D --> D3[getSkills]
+    D --> D4[getExtensions]
+    D --> D5[getWorkspaces]
+    D --> D6[extractSessionMessages]
+    D --> D7[getDirEntries cwd]
+    D --> D8[getAllCommands]
+    D --> D9[loadHiddenWorkspaces]
+
+    D1 & D2 & D3 & D4 & D5 & D6 & D7 & D8 & D9 --> E[buildDesktopHtml]
+
+    E --> E1["Read index.html template"]
+    E --> E2["Read app.js"]
+    E --> E3["JSON.stringify data → Base64"]
+    E1 & E2 & E3 --> E4["Replace __INLINE_DATA__ and __INLINE_JS__"]
+
+    E4 --> F["glimpseui.open(html, opts)"]
+    F --> G["Register event listeners:<br/>on('message') → handleWindowMessage<br/>on('closed') → cleanup<br/>on('error') → cleanup"]
+    G --> H["Set hidden thinking label<br/>setHiddenThinkingLabel()"]
+    H --> I[Window Ready — bidirectional sync active]
+```
+
+## 8. Security Model
+
+```mermaid
+flowchart TD
+    subgraph Input["User Input Validation"]
+        V1["Message length: max 100K chars"]
+        V2["Search query: 2-200 chars"]
+        V3["Attachment: max 25MB"]
+        V4["Path: no '..' traversal"]
+        V5["Filename: sanitized chars only"]
+    end
+
+    subgraph PathSec["Path Security"]
+        P1["isPathAllowed():<br/>must be under cwd or<br/>~/.pi/agent/sessions/"]
+        P2["isValidSessionFile():<br/>must end .jsonl +<br/>under sessions dir +<br/>no '..' in path"]
+        P3["Workspace dirName:<br/>reject / \\ chars"]
+        P4["open-folder-path:<br/>resolve + normalize +<br/>verify under sessions root"]
+    end
+
+    subgraph Output["Output Security"]
+        O1["DOMPurify: strict tag allowlist"]
+        O2["CSP: no connect-src,<br/>no object-src, no form-action"]
+        O3["SRI: integrity hashes on CDN"]
+        O4["escapeNonAscii():<br/>\\uXXXX encoding for<br/>Windows CP1252 safety"]
+        O5["Base64 data transfer:<br/>survives webview bridge"]
+    end
+
+    Input --> PathSec
+    PathSec --> Output
+```