dexter/BTerminal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
BTerminal/docs/phases.md

9.3 KiB
Raw Blame History

BTerminal v2 — Implementation Phases

See task_plan.md for architecture decisions, error handling, and testing strategy.

Phase 1: Project Scaffolding [status: complete] — MVP

  • Create feature branch v2-mission-control
  • Initialize Tauri 2.x project with Svelte 5 frontend
  • Project structure (see below)
  • Basic Tauri window with Catppuccin Mocha CSS variables
  • Verify Tauri builds and launches on target system
  • 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 (SVG)
        Markdown/
          MarkdownPane.svelte  # Live markdown file viewer
        Sidebar/
          SessionList.svelte   # Session browser
        StatusBar/
          StatusBar.svelte     # Global status bar (pane counts, cost)
        Notifications/
          ToastContainer.svelte # Toast notification display
        Settings/
          SettingsDialog.svelte # Settings modal dialog
      stores/
        sessions.svelte.ts   # Session state ($state runes)
        agents.svelte.ts     # Active agent tracking
        layout.svelte.ts     # Pane layout state
        notifications.svelte.ts # Toast notification state
      adapters/
        sdk-messages.ts      # SDK message abstraction layer
        pty-bridge.ts        # PTY IPC wrapper
        settings-bridge.ts   # Settings IPC wrapper
      utils/
        agent-tree.ts        # Agent tree builder (hierarchy from messages)
      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  |                         |
+--------+-------------------------+
  • CSS Grid layout with sidebar + main area + optional right panel
  • Responsive breakpoints (ultrawide / standard / narrow)
  • Pane resize via drag handles (deferred — current presets sufficient for MVP)
  • Layout presets: 1-col, 2-col, 3-col, 2x2, master+stack
  • Save/restore layout to SQLite (Phase 4)
  • Keyboard: Ctrl+1-4 focus pane, Ctrl+N new terminal

Terminal

  • xterm.js with Canvas addon (explicit — no WebGL dependency)
  • Catppuccin Mocha theme for xterm.js
  • PTY spawn from Rust (portable-pty), stream to frontend via Tauri events
  • Terminal resize -> PTY resize (100ms debounce)
  • Copy/paste (Ctrl+Shift+C/V) — deferred
  • SSH session: spawn ssh command in PTY (via shell args)
  • Local shell: spawn user's $SHELL
  • 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

  • Node.js sidecar: spawns claude CLI with --output-format stream-json (not Agent SDK query() — avoids npm dep + version churn)
  • Sidecar communication: Rust spawns Node.js, stdio NDJSON
  • Sidecar lifecycle: auto-start on app launch, shutdown on exit
  • Sidecar lifecycle: detect crash, offer restart in UI (agent_restart command + restart button)
  • Tauri commands: agent_query, agent_stop, agent_ready, agent_restart

Frontend

  • SDK message adapter: parses stream-json into 9 typed AgentMessage types (abstraction layer)
  • Agent bridge: Tauri IPC adapter (invoke + event listeners)
  • Agent dispatcher: singleton routing sidecar events to store, crash detection
  • Agent store: session state, message history, cost tracking (Svelte 5 $state)
  • Agent pane: renders structured messages
    • Text -> plain text (markdown rendering deferred)
    • Tool calls -> collapsible cards (tool name + input)
    • Tool results -> collapsible cards
    • Thinking -> collapsible details
    • Init -> model badge
    • Cost -> USD/tokens/turns/duration summary
    • Errors -> highlighted error card
    • Subagent spawn -> tree node + optional new pane (Phase 5)
  • Agent status indicator (starting/running/done/error)
  • Start/stop agent from UI (prompt form + stop button)
  • Auto-scroll with scroll-lock on user scroll-up
  • Session resume (SDK resume: sessionId)
  • Keyboard: Ctrl+Shift+N new agent
  • 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

  • SQLite persistence for sessions (rusqlite with bundled feature)
  • Session types: terminal, agent, markdown (SSH via terminal args)
  • Session CRUD: save, delete, update_title, touch (last_used_at)
  • Session groups/folders (deferred — not needed for MVP)
  • Remember last layout on restart (preset + pane_ids in layout_state table)
  • Auto-restore panes on app startup (restoreFromDb in layout store)

Markdown Viewer

  • File watcher (notify crate v6) -> Tauri events -> frontend
  • Markdown rendering (marked.js)
  • Syntax highlighting (Shiki) — deferred, adds significant bundle size
  • Open from sidebar (file picker button "M")
  • Catppuccin-themed markdown styles (h1-h3, code, pre, tables, blockquotes)
  • 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: partial] — Post-MVP

  • Agent tree visualization (SVG, compact horizontal layout) — AgentTree.svelte + agent-tree.ts utility
  • Click tree node -> focus agent pane (onNodeClick prop exists, not wired)
  • Aggregate cost per subtree (subtreeCost util exists, not displayed in UI)
  • Global status bar (terminal/agent counts, active agents pulse, token/cost totals) — StatusBar.svelte
  • Notification system (toast: success/error/warning/info, auto-dismiss 4s, max 5) — notifications.svelte.ts + ToastContainer.svelte
  • Agent dispatcher toast integration (agent complete, error, sidecar crash notifications)
  • Global keyboard shortcuts — Ctrl+W close focused pane, Ctrl+, open settings
  • Settings dialog (default shell, cwd, max panes) — SettingsDialog.svelte + settings-bridge.ts
  • Settings backend — settings table in SQLite (session.rs), Tauri commands settings_get/set/list (lib.rs)
  • ctx integration (port from v1)

Phase 6: Packaging + Distribution [status: complete] — Post-MVP

  • install-v2.sh — build-from-source installer with dependency checks (Node.js 20+, Rust 1.77+, system libs)
    • Checks: WebKit2GTK, GTK3, GLib, libayatana-appindicator, librsvg, openssl, build-essential, pkg-config, curl, wget, FUSE
    • Prompts to install missing packages via apt
    • Builds with npx tauri build, installs binary as bterminal-v2 in ~/.local/bin/
    • Creates desktop entry and installs SVG icon
  • Tauri bundle configuration — targets: ["deb", "appimage"], category: DeveloperTool
    • .deb depends: libwebkit2gtk-4.1-0, libgtk-3-0, libayatana-appindicator3-1
    • AppImage: bundleMediaFramework disabled
  • Icons regenerated from bterminal.svg — RGBA PNGs (32x32, 128x128, 128x128@2x, 512x512, .ico)
  • GitHub Actions release workflow (.github/workflows/release.yml)
    • Triggered on v* tags, Ubuntu 22.04 runner
    • Caches Rust and npm dependencies
    • Builds .deb + AppImage, uploads as GitHub Release artifacts
  • Build verified: .deb (4.3 MB), AppImage (103 MB)
  • Auto-update mechanism (Tauri updater) — deferred, needs signing key + update server

System Requirements

  • Node.js 20+ (for Agent SDK sidecar)
  • Rust 1.77+ (for building from source)
  • WebKit2GTK 4.1+ (Tauri runtime)
  • Linux x86_64 (primary target)