cd1271adf0
- phases.md: Phase 3 polish + Phase 4 items checked off as complete - progress.md: Phase 4 session details added - task_plan.md: status updated to "MVP COMPLETE" - README.md: v2 status updated to "MVP complete (Phase 4 done)" - TODO.md: Phase 3/4 moved to Completed, new post-MVP items added - CHANGELOG.md: Phase 4 entries added under [Unreleased] - .claude/CLAUDE.md: workflow status and constraints updated
192 lines
7.5 KiB
Markdown
192 lines
7.5 KiB
Markdown
# BTerminal v2 — Implementation Phases
|
|
|
|
See [task_plan.md](task_plan.md) for architecture decisions, error handling, and testing strategy.
|
|
|
|
---
|
|
|
|
## Phase 1: Project Scaffolding [status: complete] — MVP
|
|
|
|
- [x] Create feature branch `v2-mission-control`
|
|
- [x] Initialize Tauri 2.x project with Svelte 5 frontend
|
|
- [x] Project structure (see below)
|
|
- [x] Basic Tauri window with Catppuccin Mocha CSS variables
|
|
- [x] Verify Tauri builds and launches on target system
|
|
- [x] Set up dev scripts (dev, build, lint)
|
|
|
|
### File Structure
|
|
```
|
|
bterminal-v2/
|
|
src-tauri/
|
|
src/
|
|
main.rs # Tauri app entry
|
|
pty.rs # PTY management (portable-pty, not plugin)
|
|
sidecar.rs # Node.js sidecar lifecycle (spawn, restart, health)
|
|
watcher.rs # File watcher for markdown viewer
|
|
session.rs # Session persistence (SQLite via rusqlite)
|
|
Cargo.toml
|
|
src/
|
|
App.svelte # Root layout
|
|
lib/
|
|
components/
|
|
Layout/
|
|
TilingGrid.svelte # Dynamic tiling manager
|
|
PaneContainer.svelte # Individual pane wrapper
|
|
PaneHeader.svelte # Pane title bar with controls
|
|
Terminal/
|
|
TerminalPane.svelte # xterm.js terminal pane
|
|
Agent/
|
|
AgentPane.svelte # SDK agent structured output
|
|
AgentTree.svelte # Subagent tree visualization
|
|
ToolCallCard.svelte # Individual tool call display
|
|
Markdown/
|
|
MarkdownPane.svelte # Live markdown file viewer
|
|
Sidebar/
|
|
SessionList.svelte # Session browser
|
|
stores/
|
|
sessions.svelte.ts # Session state ($state runes)
|
|
agents.svelte.ts # Active agent tracking
|
|
layout.svelte.ts # Pane layout state
|
|
adapters/
|
|
sdk-messages.ts # SDK message abstraction layer
|
|
pty-bridge.ts # PTY IPC wrapper
|
|
styles/
|
|
catppuccin.css # Theme CSS variables
|
|
app.css
|
|
sidecar/
|
|
agent-runner.ts # Node.js sidecar entry point
|
|
package.json # Agent SDK dependency
|
|
esbuild.config.ts # Bundle to single file
|
|
package.json
|
|
svelte.config.js
|
|
vite.config.ts
|
|
tauri.conf.json
|
|
```
|
|
|
|
**Key change from v1:** Using portable-pty directly from Rust instead of tauri-plugin-pty (38-star community plugin). portable-pty is well-maintained (used by WezTerm). More work upfront, more reliable long-term.
|
|
|
|
---
|
|
|
|
## Phase 2: Terminal Pane + Layout [status: complete] — MVP
|
|
|
|
### Layout (responsive)
|
|
|
|
**32:9 (5120px) — full density:**
|
|
```
|
|
+--------+------------------------------------+--------+
|
|
|Sidebar | 2-4 panes, CSS Grid, resizable | Right |
|
|
| 260px | | 380px |
|
|
+--------+------------------------------------+--------+
|
|
```
|
|
|
|
**16:9 (1920px) — degraded but functional:**
|
|
```
|
|
+--------+-------------------------+
|
|
|Sidebar | 1-2 panes | (right panel collapses to overlay)
|
|
| 240px | |
|
|
+--------+-------------------------+
|
|
```
|
|
|
|
- [x] CSS Grid layout with sidebar + main area + optional right panel
|
|
- [x] Responsive breakpoints (ultrawide / standard / narrow)
|
|
- [ ] Pane resize via drag handles (deferred — current presets sufficient for MVP)
|
|
- [x] Layout presets: 1-col, 2-col, 3-col, 2x2, master+stack
|
|
- [ ] Save/restore layout to SQLite (Phase 4)
|
|
- [x] Keyboard: Ctrl+1-4 focus pane, Ctrl+N new terminal
|
|
|
|
### Terminal
|
|
- [x] xterm.js with Canvas addon (explicit — no WebGL dependency)
|
|
- [x] Catppuccin Mocha theme for xterm.js
|
|
- [x] PTY spawn from Rust (portable-pty), stream to frontend via Tauri events
|
|
- [x] Terminal resize -> PTY resize (100ms debounce)
|
|
- [ ] Copy/paste (Ctrl+Shift+C/V) — deferred
|
|
- [x] SSH session: spawn `ssh` command in PTY (via shell args)
|
|
- [x] Local shell: spawn user's $SHELL
|
|
- [x] Claude Code CLI: spawn `claude` in PTY (via shell args)
|
|
|
|
**Milestone: After Phase 2, we have a working multi-pane terminal.** Usable as a daily driver even without agent features.
|
|
|
|
---
|
|
|
|
## Phase 3: Agent SDK Integration [status: complete] — MVP
|
|
|
|
### Backend
|
|
- [x] Node.js sidecar: spawns `claude` CLI with `--output-format stream-json` (not Agent SDK query() — avoids npm dep + version churn)
|
|
- [x] Sidecar communication: Rust spawns Node.js, stdio NDJSON
|
|
- [x] Sidecar lifecycle: auto-start on app launch, shutdown on exit
|
|
- [x] Sidecar lifecycle: detect crash, offer restart in UI (agent_restart command + restart button)
|
|
- [x] Tauri commands: agent_query, agent_stop, agent_ready, agent_restart
|
|
|
|
### Frontend
|
|
- [x] SDK message adapter: parses stream-json into 9 typed AgentMessage types (abstraction layer)
|
|
- [x] Agent bridge: Tauri IPC adapter (invoke + event listeners)
|
|
- [x] Agent dispatcher: singleton routing sidecar events to store, crash detection
|
|
- [x] Agent store: session state, message history, cost tracking (Svelte 5 $state)
|
|
- [x] Agent pane: renders structured messages
|
|
- [x] Text -> plain text (markdown rendering deferred)
|
|
- [x] Tool calls -> collapsible cards (tool name + input)
|
|
- [x] Tool results -> collapsible cards
|
|
- [x] Thinking -> collapsible details
|
|
- [x] Init -> model badge
|
|
- [x] Cost -> USD/tokens/turns/duration summary
|
|
- [x] Errors -> highlighted error card
|
|
- [ ] Subagent spawn -> tree node + optional new pane (Phase 5)
|
|
- [x] Agent status indicator (starting/running/done/error)
|
|
- [x] Start/stop agent from UI (prompt form + stop button)
|
|
- [x] Auto-scroll with scroll-lock on user scroll-up
|
|
- [ ] Session resume (SDK `resume: sessionId`)
|
|
- [x] Keyboard: Ctrl+Shift+N new agent
|
|
- [x] Sidebar: agent session button
|
|
|
|
**Milestone: After Phase 3, we have the core differentiator.** SDK agents run in structured panes alongside raw terminals.
|
|
|
|
---
|
|
|
|
## Phase 4: Session Management + Markdown Viewer [status: complete] — MVP
|
|
|
|
### Sessions
|
|
- [x] SQLite persistence for sessions (rusqlite with bundled feature)
|
|
- [x] Session types: terminal, agent, markdown (SSH via terminal args)
|
|
- [x] Session CRUD: save, delete, update_title, touch (last_used_at)
|
|
- [ ] Session groups/folders (deferred — not needed for MVP)
|
|
- [x] Remember last layout on restart (preset + pane_ids in layout_state table)
|
|
- [x] Auto-restore panes on app startup (restoreFromDb in layout store)
|
|
|
|
### Markdown Viewer
|
|
- [x] File watcher (notify crate v6) -> Tauri events -> frontend
|
|
- [x] Markdown rendering (marked.js)
|
|
- [ ] Syntax highlighting (Shiki) — deferred, adds significant bundle size
|
|
- [x] Open from sidebar (file picker button "M")
|
|
- [x] Catppuccin-themed markdown styles (h1-h3, code, pre, tables, blockquotes)
|
|
- [x] Live reload on file change
|
|
|
|
**Milestone: After Phase 4 = MVP ship.** Full session management, structured agent panes, terminal panes, markdown viewer.
|
|
|
|
---
|
|
|
|
## Phase 5: Agent Tree + Polish [status: not_started] — Post-MVP
|
|
|
|
- [ ] Agent tree visualization (SVG, compact horizontal layout)
|
|
- [ ] Click tree node -> focus agent pane
|
|
- [ ] Aggregate cost per subtree
|
|
- [ ] Global status bar (total cost, active agents, uptime)
|
|
- [ ] Notification system (agent done, error)
|
|
- [ ] Global keyboard shortcuts
|
|
- [ ] Settings dialog
|
|
- [ ] ctx integration (port from v1)
|
|
|
|
---
|
|
|
|
## Phase 6: Packaging + Distribution [status: not_started] — Post-MVP
|
|
|
|
- [ ] install.sh v2 (check Node.js, install Tauri runtime deps)
|
|
- [ ] AppImage build (single file, works everywhere)
|
|
- [ ] .deb package (Debian/Ubuntu)
|
|
- [ ] GitHub Actions CI for building releases
|
|
- [ ] Auto-update mechanism (Tauri updater)
|
|
- [ ] Migrate bterminal.svg icon
|
|
- [ ] README update
|
|
|
|
### System Requirements
|
|
- Node.js 20+ (for Agent SDK sidecar)
|
|
- WebKit2GTK 4.1+ (Tauri runtime)
|
|
- Linux x86_64 (primary target)
|