jettypod 4.4.118 → 4.4.121

package/TAURI-MIGRATION-PLAN.md

@@ -0,0 +1,840 @@
+# JettyPod Stack Migration: Electron/Next.js → Tauri/Vite/Rust
+
+## Executive Summary
+
+Migrate JettyPod from Electron + Next.js + Node.js to Tauri + Vite + React + Rust. The goal is dramatically lower resource usage (RAM, disk, startup time), cross-platform readiness (especially Windows), and a faster CLI — while preserving all current functionality.
+
+**Current stack:** Electron 32 / Next.js 16 / React 19 / Node.js CLI / SQLite (two drivers) / Cloudflare Worker
+**Target stack:** Tauri 2 / Vite / React 19 / Rust CLI + core / SQLite (rusqlite) / Cloudflare Worker (unchanged)
+
+**Estimated total effort:** 5-6 months calendar, ~500-600 hours active development
+
+---
+
+## Current Architecture Snapshot
+
+### What exists today
+
+| Layer | Technology | Size |
+|-------|-----------|------|
+| Desktop shell | Electron 32 (Chromium + Node.js) | 5 files, 3,849 lines |
+| Frontend | Next.js 16 + React 19 + Tailwind 4 | 50 components, 40 pages/routes |
+| CLI | Node.js (jettypod.js + lib/) | 3,473 + 2,639 lines + 106 modules |
+| Data | SQLite via sqlite3 (async) + better-sqlite3 (sync) | 30 migrations, WAL mode |
+| Update server | Cloudflare Worker + D1 + R2 + KV | 1,085 lines |
+| Tests | Jest + Cucumber.js | 56 unit, 238 BDD features |
+| Auth | Google OAuth + Email OTP → JWT → local file | jettypod:// protocol handler |
+| Real-time | WebSocket server on port 47808 | Polls SQLite mtime every 500ms |
+
+### Key IPC surface (what Tauri must replace)
+
+The Electron main process exposes **52 IPC channels** across these domains:
+
+- **Database/Kanban** (18 channels): CRUD for work items, sessions, decisions, env vars
+- **Claude subprocess** (3 channels): spawn, write stdin, kill process tree
+- **Dev server** (4 channels): spawn/kill/status/list for app preview servers
+- **Project management** (5 channels): dialog pickers, recent projects
+- **Claude Code CLI** (5 channels): install, update, auth check, login
+- **Subscription/billing** (4 channels): Stripe checkout, activation, portal
+- **Auth** (7 channels): Google OAuth, token save/get/logout, status checks
+- **Shell** (1 channel): open external URLs
+- **Settings** (3 channels): project name, env vars
+- **Process lifecycle** (2 channels): app version, dev mode detection
+
+### System-level dependencies in Electron
+
+These are the things that make migration non-trivial:
+
+1. **Custom protocol handler** (jettypod://) — OAuth callback routing
+2. **Child process management** — Claude CLI + dev servers with process tree kill
+3. **Auto-updater** — electron-updater with JWT-authenticated manifest endpoint
+4. **File system access** — auth.json, subscription.json, config.json, SQLite databases
+5. **Shell integration** — PATH symlink creation via osascript sudo
+6. **WebSocket server** — embedded in main process for real-time DB change notifications
+7. **Native module rebuilds** — better-sqlite3 rebuilt for Electron's Node version
+8. **Skills sync** — copies bundled skills to ~/.claude/skills/ on launch
+9. **Menu bar** — native macOS menu with keyboard shortcuts
+
+---
+
+## Target Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Tauri Shell                        │
+│  ┌──────────────┐  ┌─────────────────────────────┐  │
+│  │  Rust Backend │  │   Webview (OS native)       │  │
+│  │              │  │  ┌───────────────────────┐  │  │
+│  │  jettypod-   │  │  │  Vite + React 19      │  │  │
+│  │  core crate  │◄─┤  │  (existing components) │  │  │
+│  │              │  │  │  IPC via @tauri-apps/  │  │  │
+│  │  - SQLite    │  │  │  api invoke()          │  │  │
+│  │  - Git ops   │  │  └───────────────────────┘  │  │
+│  │  - Auth      │  │                             │  │
+│  │  - Sessions  │  └─────────────────────────────┘  │
+│  │  - WS server │                                    │
+│  └──────┬───────┘                                    │
+│         │                                            │
+└─────────┼────────────────────────────────────────────┘
+          │ shared crate
+┌─────────┴───────┐
+│  jettypod-cli   │
+│  (Rust binary)  │
+│  same core lib  │
+└─────────────────┘
+```
+
+### Rust workspace layout
+
+```
+jettypod-rs/
+  Cargo.toml              # workspace root
+  crates/
+    jettypod-core/        # shared library
+      src/
+        lib.rs
+        db/               # SQLite schema, migrations, queries
+        git/              # worktree, branch, merge operations
+        auth/             # JWT decode, auth.json read/write
+        work/             # work item CRUD, status transitions
+        sessions/         # Claude session management
+        config/           # project config, env vars
+    jettypod-cli/         # CLI binary
+      src/
+        main.rs           # clap argument parsing
+        commands/         # work, backlog, init, etc.
+    jettypod-tauri/       # Tauri app
+      src/
+        main.rs           # Tauri setup, window management
+        commands/         # IPC command handlers
+        protocol.rs       # jettypod:// deep link handler
+        updater.rs        # auto-update configuration
+        processes.rs      # Claude CLI + dev server subprocess management
+        websocket.rs      # real-time DB change notifications
+      tauri.conf.json
+  frontend/               # Vite + React (moved from apps/dashboard/)
+    src/
+      components/         # existing 50 components (migrated)
+      pages/              # existing routes
+      lib/                # utilities
+      ipc.ts              # Tauri invoke() wrapper (replaces window.electronAPI)
+    vite.config.ts
+    index.html
+```
+
+---
+
+## Migration Phases
+
+### Phase 0: Proof of Concept (1 week)
+
+**Goal:** Derisk the three hardest problems before committing to the full migration. Build a throwaway Tauri app that validates the critical paths.
+
+**Duration:** 1 week
+
+This phase exists because the biggest risks — auth deep links, subprocess management, and IPC reliability — are all Tauri-specific unknowns. Spending 1 week now saves potentially months of rework later.
+
+#### What to build
+
+A minimal Tauri 2 app (no real UI) that proves:
+
+1. **Auth flow end-to-end**
+   - Register `jettypod-test://` as a custom protocol
+   - Test cold start: app not running → browser opens `jettypod-test://auth/callback?token=xyz` → app launches → receives URL
+   - Test warm start: app running → browser opens URL → app receives it
+   - Verify URL parsing (hostname vs pathname gotcha)
+   - Test single-instance behavior (what happens on double-click login?)
+   - Implement a launch queue that buffers protocol events arriving before handlers initialize
+
+2. **Subprocess management**
+   - Spawn a long-running child process (simulate Claude CLI)
+   - Stream its stdout/stderr to the webview via Tauri events
+   - Kill the process and ALL its children reliably
+   - Test: spawn a process that itself spawns children → kill parent → verify children are dead
+   - On macOS: use process groups (`setsid` + `killpg`)
+   - Document what the Windows equivalent will need (`CREATE_NEW_PROCESS_GROUP` + `taskkill /T /F`)
+
+3. **One complex IPC round-trip**
+   - Open a real `.jettypod/work.db` with rusqlite
+   - Implement `get_kanban_data` command that queries and returns structured data
+   - Call it from the webview, verify serialization/deserialization
+   - Measure latency vs the Electron equivalent
+   - Test error propagation (what happens when the DB is locked? corrupt? missing?)
+
+#### Acceptance criteria
+
+- [ ] Deep link works on cold start (app not running)
+- [ ] Deep link works on warm start (app already running)
+- [ ] Double-activation doesn't create zombie windows
+- [ ] Protocol URL parsed correctly (hostname=auth, path=/callback)
+- [ ] Child process stdout/stderr streams to webview
+- [ ] Process tree kill works (parent + all children)
+- [ ] SQLite query returns correct data through Tauri IPC
+- [ ] IPC error handling works (locked DB, missing file)
+
+#### Go/no-go decision
+
+If any of these three areas has a fundamental blocker in Tauri 2, we learn it now at 1 week cost instead of at month 3. If all three work, proceed with confidence.
+
+---
+
+### Phase 1: Tauri Shell with Node.js Backend (3-4 weeks)
+
+**Goal:** Replace Electron with Tauri while keeping the existing Node.js backend as a sidecar process. This derisks the desktop shell migration without requiring Rust business logic yet.
+
+**Duration:** 3-4 weeks
+
+**Why this order:** The original plan had "Rust CLI first, then Tauri shell." That's backwards. The desktop shell is where all the risk lives (auth, subprocesses, auto-update, IPC). Port the shell first with a proven backend, then swap the backend to Rust when the shell is stable. This way you're never debugging Tauri quirks AND Rust bugs simultaneously.
+
+#### Architecture (transitional)
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Tauri Shell                        │
+│  ┌──────────────┐  ┌─────────────────────────────┐  │
+│  │ Thin Rust    │  │   Webview (OS native)       │  │
+│  │ layer        │  │  ┌───────────────────────┐  │  │
+│  │              │  │  │  Existing React/Next   │  │  │
+│  │ - Deep links │◄─┤  │  frontend (unchanged)  │  │  │
+│  │ - Menus      │  │  │                        │  │  │
+│  │ - Updater    │  │  └───────────────────────┘  │  │
+│  │ - Process    │  │                             │  │
+│  │   mgmt       │  └─────────────────────────────┘  │
+│  └──────┬───────┘                                    │
+│         │ spawns                                     │
+│  ┌──────┴──────────┐                                 │
+│  │ Node.js sidecar │  (existing ipc-handlers.js)     │
+│  │ - SQLite        │                                 │
+│  │ - Git ops       │                                 │
+│  │ - WebSocket     │                                 │
+│  └─────────────────┘                                 │
+└─────────────────────────────────────────────────────┘
+```
+
+The Rust layer handles only Tauri-specific concerns (window, menus, deep links, updater, process management). All business logic stays in Node.js as a sidecar process, communicating via local HTTP or stdin/stdout JSON-RPC.
+
+#### What to port to Rust
+
+Only the Electron-specific parts:
+- Window creation and management
+- Native menu bar
+- Deep link handler (`jettypod://`) with launch queue from Phase 0
+- Auto-updater (tauri-plugin-updater)
+- File dialogs (tauri-plugin-dialog)
+- Shell open (tauri-plugin-shell)
+- Single-instance enforcement
+- Process management for Claude CLI + dev servers (with platform-specific kill from Phase 0)
+
+#### What stays in Node.js (for now)
+
+- All 18 database IPC handlers → Node.js sidecar
+- Claude session management
+- WebSocket server (port 47808)
+- Work tracking logic
+- Git operations
+- Skills sync
+- Auth file I/O (auth.json, subscription.json)
+
+#### IPC bridge approach
+
+Two options for Tauri ↔ Node.js sidecar communication:
+
+**Option A: Tauri sidecar + JSON-RPC over stdin/stdout**
+- Tauri spawns Node.js script as managed sidecar
+- Frontend calls Tauri command → Rust forwards to Node.js via stdin → response via stdout
+- Pro: clean lifecycle management, Tauri restarts sidecar if it crashes
+- Con: serialization overhead, adds latency
+
+**Option B: Node.js HTTP server on localhost**
+- Node.js runs existing logic as local HTTP server (already has API routes)
+- Frontend calls Node.js directly via fetch() for data, Tauri commands for native features
+- Pro: minimal changes to existing code, can reuse Next.js API routes directly
+- Con: port management, CORS, two communication channels
+
+**Recommendation:** Option B. The frontend already has API routes that do the exact same thing as the IPC handlers. In this transitional phase, just have the frontend hit localhost for data and Tauri for native features. This minimizes changes.
+
+#### Frontend changes
+
+Minimal in this phase:
+- Replace `window.electronAPI` calls for native features (dialog, shell, auth protocol) → Tauri `invoke()`
+- Data fetching calls stay as-is (hitting Next.js API routes on localhost)
+- Add Tauri event listeners for deep link callbacks, updater status
+
+#### Process management: platform-specific implementation
+
+```rust
+// processes.rs
+
+#[cfg(unix)]
+pub fn kill_process_tree(pid: u32) -> Result<()> {
+    // Send SIGTERM to the process group
+    unsafe { libc::killpg(pid as i32, libc::SIGTERM) };
+    // Wait, then SIGKILL if still alive
+    std::thread::sleep(Duration::from_secs(2));
+    unsafe { libc::killpg(pid as i32, libc::SIGKILL) };
+    Ok(())
+}
+
+#[cfg(windows)]
+pub fn kill_process_tree(pid: u32) -> Result<()> {
+    // taskkill /T terminates process tree, /F forces
+    Command::new("taskkill")
+        .args(["/PID", &pid.to_string(), "/T", "/F"])
+        .output()?;
+    Ok(())
+}
+```
+
+**Critical:** When spawning Claude CLI and dev servers, always create a new process group:
+- Unix: `pre_exec(|| { libc::setsid(); Ok(()) })`
+- Windows: `CREATE_NEW_PROCESS_GROUP` flag via `.creation_flags()`
+
+#### Acceptance criteria
+
+- [ ] App launches with Tauri shell + Node.js sidecar
+- [ ] All pages render (Next.js served from localhost)
+- [ ] Google OAuth flow completes end-to-end
+- [ ] Deep link works: cold start AND warm start
+- [ ] Claude subprocess spawns, streams, killable (including children)
+- [ ] Dev server spawns, streams, killable
+- [ ] Auto-updater checks for updates (new Tauri endpoint)
+- [ ] File dialogs work
+- [ ] Native menu bar with keyboard shortcuts
+- [ ] WebSocket real-time updates work (via Node.js sidecar)
+- [ ] Memory < 200MB idle (Node.js sidecar adds some overhead vs final state)
+- [ ] Code signing + notarization work on macOS
+- [ ] Single-instance enforcement works
+
+---
+
+### Phase 2: Rust Core + CLI (6-8 weeks)
+
+**Goal:** Port all Node.js business logic to a Rust jettypod-core crate. Replace the Node.js sidecar in Tauri and ship a standalone Rust CLI.
+
+**Duration:** 6-8 weeks (realistic for learning Rust while building)
+
+**Prerequisite:** Phase 1 complete (Tauri shell is stable and proven)
+
+Now that the desktop shell works and all the scary Tauri integration points are validated, this phase is "just" porting business logic to Rust. It's a lot of code, but the risk is low — if any piece of the Rust port isn't ready, the Node.js sidecar keeps working.
+
+#### What to port
+
+| Module | Current (Node.js) | Target (Rust) | Complexity | Hours |
+|--------|-------------------|---------------|------------|-------|
+| lib/database.js | sqlite3 async callbacks | rusqlite sync | Medium | 20h |
+| lib/schema.js + lib/migrations/ | 30 migration files | rusqlite + refinery | Medium | 15h |
+| lib/work-tracking/index.js | 2,639 lines CRUD | jettypod-core::work | High | 50h |
+| lib/work-commands/ | Git worktree mgmt | jettypod-core::git via shell | Medium | 25h |
+| lib/config.js | JSON config r/w | serde_json | Low | 5h |
+| jettypod.js | 3,473 lines routing | clap + command modules | High | 40h |
+| WebSocket broadcast | ws, mtime polling | tokio-tungstenite | Low | 10h |
+| Auth file I/O | auth.json r/w | serde + fs | Low | 5h |
+| Session management | SQLite + JSON | jettypod-core::sessions | Medium | 20h |
+| Skills sync | fs.copy | fs::copy | Low | 5h |
+
+**Estimated: ~200 hours** (includes Rust learning overhead — fighting the borrow checker, rewriting things that don't compile, etc.)
+
+#### Key Rust crates
+
+| Crate | Purpose | Replaces |
+|-------|---------|----------|
+| rusqlite | SQLite with bundled libsqlite3 | sqlite3 + better-sqlite3 |
+| clap | CLI argument parsing | manual switch/case |
+| serde + serde_json | JSON serialization | JSON.parse/stringify |
+| jsonwebtoken | JWT decode | manual base64 decode |
+| tokio | Async runtime (WS, subprocesses) | Node.js event loop |
+| tokio-tungstenite | WebSocket server | ws |
+| colored | Terminal colors | chalk |
+| anyhow / thiserror | Error handling | throw/catch |
+| refinery | SQLite migrations | manual _meta versioning |
+
+#### Migration strategy within this phase
+
+Port module by module, swapping each Tauri command from "forward to Node.js sidecar" to "call jettypod-core directly." This allows incremental validation:
+
+1. **Week 1-2:** Database layer + schema + migrations. Verify against real work.db files.
+2. **Week 2-4:** Work tracking CRUD. This is the largest piece. Port function by function, test each one.
+3. **Week 4-5:** Git operations (shell out to git), config, auth file I/O.
+4. **Week 5-6:** Session management, WebSocket server, skills sync.
+5. **Week 6-7:** CLI binary (clap routing, wire up all commands).
+6. **Week 7-8:** Integration testing, edge cases, polish.
+
+At each step, the Tauri app can use the Rust implementation for ported modules and the Node.js sidecar for the rest. Once all modules are ported, kill the sidecar.
+
+#### Decision: git2 vs shelling out
+
+**Decision:** Shell out to git via std::process::Command. Worktrees are central to JettyPod and git2's worktree support is incomplete. Every user already has git installed.
+
+#### SQLite concurrent access during transition
+
+During this phase, the Rust code (rusqlite) and Node.js sidecar (better-sqlite3) may both access the same work.db. This is dangerous because:
+
+- Different bundled SQLite versions can have WAL format incompatibilities
+- Concurrent writers with different busy timeout behaviors can corrupt data
+
+**Mitigation:** Module-by-module cutover means we never have both drivers writing to the same tables simultaneously. When a module is ported to Rust, its Node.js equivalent is disabled. The sidecar's responsibility shrinks with each ported module until it's removed entirely.
+
+#### Testing strategy
+
+- **Rust unit tests:** `cargo test` for every module in jettypod-core. Test against snapshot copies of real work.db files.
+- **CLI integration tests:** Run new Rust CLI against existing .jettypod projects. Compare output with Node.js CLI.
+- **IPC integration:** For each ported Tauri command, verify frontend behavior is unchanged.
+- **Regression suite:** Run existing Jest + Cucumber tests against the Node.js sidecar throughout to catch breakage.
+
+#### Acceptance criteria
+
+- [ ] All jettypod work subcommands work identically in Rust CLI
+- [ ] jettypod backlog output matches Node.js version
+- [ ] Existing .jettypod/work.db databases read/write correctly
+- [ ] All 30 migrations apply cleanly on existing databases
+- [ ] All 52 IPC channels respond correctly via Rust (no more Node.js sidecar)
+- [ ] WebSocket broadcasts trigger dashboard refreshes
+- [ ] CLI cold start < 10ms (vs current ~200ms)
+- [ ] Existing git hooks continue to work
+- [ ] Node.js sidecar fully removed
+- [ ] `cargo test` passes with >90% coverage on jettypod-core
+
+---
+
+### Phase 3: Drop Next.js for Vite (3-4 weeks)
+
+**Goal:** Remove Next.js entirely. Frontend becomes a static Vite + React SPA loaded by Tauri's webview.
+
+**Duration:** 3-4 weeks (not 1-2 — data fetching patterns, state hydration, and edge cases add up)
+
+**Prerequisite:** Phase 2 complete (Node.js sidecar removed, all data via Tauri IPC)
+
+#### Why
+
+Next.js currently provides:
+- File-based routing → replaceable with react-router
+- API routes → no longer needed (all data via Tauri IPC since Phase 2)
+- SSR → unused in a desktop app
+- ~15MB bundle size overhead
+- Webpack build pipeline → caused the Tailwind v4 class stripping bug
+
+#### What's harder than it looks
+
+- **Data fetching patterns change completely.** Next.js server components, `getServerSideProps`, and API route calls all become Tauri `invoke()` calls. This isn't just a find-and-replace — the timing and error handling are different.
+- **State hydration disappears.** Next.js hydrates server-rendered HTML. A Vite SPA renders from scratch. Components that assumed server-rendered initial state will flash or break.
+- **Loading states.** Next.js handled loading between page transitions. With react-router, you need explicit loading UI or Suspense boundaries.
+- **Build-time optimizations gone.** Next.js was doing code splitting, image optimization, and chunk prioritization. Vite does some of this but differently.
+
+#### Replacement map
+
+| Next.js | Replacement |
+|---------|-------------|
+| app/ routing | react-router-dom v7 |
+| next/link | Link from react-router |
+| next/router | useNavigate() / useParams() |
+| next/image | img tag |
+| API routes (22 files) | Delete — all data via Tauri IPC |
+| next.config.js | vite.config.ts |
+| @tailwindcss/postcss | @tailwindcss/vite |
+| getServerSideProps | useEffect + invoke() |
+| Server components | Client components with loading states |
+
+#### Routes
+
+```typescript
+export const router = createBrowserRouter([
+  { path: '/', element: <Dashboard /> },
+  { path: '/work/:id', element: <WorkItemDetail /> },
+  { path: '/decision/:id', element: <DecisionDetail /> },
+  { path: '/tests', element: <Tests /> },
+  { path: '/settings', element: <Settings /> },
+  { path: '/prototypes', element: <Prototypes /> },
+  { path: '/welcome', element: <Welcome /> },
+  { path: '/login', element: <Login /> },
+  { path: '/signup', element: <Signup /> },
+  { path: '/subscribe', element: <Subscribe /> },
+  { path: '/install-claude', element: <InstallClaude /> },
+  { path: '/connect-claude', element: <ConnectClaude /> },
+  { path: '/design-system', element: <DesignSystem /> },
+]);
+```
+
+#### Testing
+
+- Component-level tests need updating (no more Next.js test utilities)
+- E2E test framework: move to Playwright or WebdriverIO with Tauri driver
+- Visual regression: screenshot comparison before/after for each page
+
+#### Acceptance criteria
+
+- [ ] All 14 pages render correctly
+- [ ] Navigation works (history, back/forward)
+- [ ] No Next.js imports remain
+- [ ] No loading state regressions (pages don't flash empty)
+- [ ] Vite HMR < 100ms
+- [ ] Production build < 10 seconds
+- [ ] Tailwind v4 custom classes work (no more stripping)
+- [ ] Bundle < 2MB
+- [ ] E2E test suite passes
+
+---
+
+### Phase 4: SQLite Formalization (1 week, overlaps Phase 2)
+
+**Goal:** Single SQLite driver (rusqlite), typed schema, clean migrations.
+
+**Duration:** 1 week (happens naturally as part of Phase 2's database porting)
+
+#### Problems solved
+
+1. Two drivers (sqlite3 async + better-sqlite3 sync) → single rusqlite
+2. String literal queries → typed Rust structs with compile-time checking
+3. Fragile manual _meta versioning → refinery crate with embedded migrations
+4. Inconsistent WAL/busy-timeout config → single connection setup
+
+No schema changes. Same tables, same data.
+
+#### Acceptance criteria
+
+- [ ] Existing work.db files work with rusqlite
+- [ ] All 30 migrations apply cleanly
+- [ ] CLI and Tauri both access DB without corruption
+- [ ] WAL mode enforced on every connection
+- [ ] Busy timeout set consistently (5000ms)
+- [ ] Foreign keys enforced
+
+---
+
+### Phase 5: Update Server + Release Pipeline (2-3 weeks)
+
+**Goal:** Cloudflare Worker serves Tauri update manifests. CI builds for macOS (arm64 + x64) and Linux. Dual update channels during transition.
+
+**Duration:** 2-3 weeks
+
+#### New update server route
+
+```typescript
+router.get('/updates/tauri/:target/:arch/:current_version', async (req) => {
+  const latest = await getLatestVersion(mapPlatform(target, arch));
+  if (semver.lte(latest.version, current_version)) return new Response('', { status: 204 });
+  return Response.json({ version, url, signature, notes, pub_date });
+});
+```
+
+Keep existing Electron update routes. Track requests by user-agent for deprecation metrics.
+
+#### Ed25519 signing
+
+```bash
+# One-time key generation
+tauri signer generate -w ~/.tauri/jettypod.key
+# Public key → tauri.conf.json
+# Private key → TAURI_SIGNING_PRIVATE_KEY in CI secrets
+```
+
+#### CI (GitHub Actions)
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-13
+            target: x86_64-apple-darwin
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: pnpm install --frozen-lockfile
+        working-directory: frontend
+      - uses: tauri-apps/tauri-action@v0
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_SIGNING_IDENTITY: "ERIK JOSEPH,BARYN SPANGENBERG (45W2KB54VS)"
+```
+
+Note: Windows is Phase 6. Not in this CI matrix yet.
+
+#### Artifacts
+
+- macOS: .dmg + .app.tar.gz + .sig
+- Linux: .AppImage + .tar.gz + .sig
+
+#### Transition period (run for 6+ months)
+
+- Electron users keep getting Electron updates
+- Tauri users get Tauri updates
+- Version telemetry tracks user count per platform
+- After 90%+ on Tauri: ship final Electron update that shows "please download new version"
+
+#### Acceptance criteria
+
+- [ ] Tauri update endpoint returns correct JSON per platform
+- [ ] Ed25519 signatures verify
+- [ ] Auto-update end-to-end works
+- [ ] macOS signed + notarized
+- [ ] Linux AppImage works on Ubuntu 22.04+
+- [ ] Download page serves Tauri artifacts
+- [ ] Electron update channel still works in parallel
+- [ ] Version telemetry tracks platform distribution
+
+---
+
+### Phase 6: Windows (separate project, ~6 months after macOS stable)
+
+**Goal:** Ship Windows desktop app using the same Tauri codebase.
+
+**Duration:** 4-6 weeks of focused work, but don't start until macOS + Linux are stable for 3+ months.
+
+**Why this is its own phase and not "1-2 months later":**
+
+Windows is not "the same code on a different OS." It's a different world:
+
+- **Protocol handlers** require Windows Registry entries. Tauri's deep-link plugin handles this, but testing the install/uninstall/upgrade cycle for registry entries is its own project.
+- **Process management** has no process groups. `taskkill /T /F` is the workaround but behaves differently from Unix `killpg`. Claude CLI spawning subprocesses on Windows needs dedicated testing.
+- **File paths** — backslashes, UNC paths, `%APPDATA%` vs `~/Library/Application Support/`. Every hardcoded path assumption needs auditing.
+- **Code signing** — completely different from macOS. You need an EV certificate (expensive, hardware token required for some CAs) or Azure Trusted Signing.
+- **Auto-updater permissions** — Windows UAC prompts during update. NSIS installer behavior. Silent update vs interactive.
+- **WebView2** — pre-installed on Windows 10/11 but the bootstrapper install flow needs testing on older/enterprise machines.
+
+#### What to do
+
+1. Add Windows to CI matrix (windows-latest, x86_64-pc-windows-msvc)
+2. Audit all file path handling for Windows compatibility
+3. Test deep link registration/deregistration across install/update/uninstall
+4. Test process tree kill for Claude CLI + dev servers on Windows
+5. Obtain Windows code signing certificate
+6. Test auto-update flow including UAC
+7. Beta test with real Windows users before GA
+
+#### Acceptance criteria
+
+- [ ] Windows NSIS installer works
+- [ ] Deep links work on Windows
+- [ ] Process tree kill works on Windows
+- [ ] Auto-update works (including UAC)
+- [ ] Code signed with valid certificate
+- [ ] WebView2 bootstrapper installs if missing
+- [ ] All file paths use platform-appropriate separators
+
+---
+
+## Risk Register
+
+### Critical
+
+| # | Risk | Likelihood | Impact | Mitigation |
+|---|------|-----------|--------|------------|
+| 1 | **Auth deep link race condition** — protocol URL arrives before Tauri handlers initialize on cold start | High | High | Phase 0 proves this works. Implement launch queue that buffers early events. Test cold/warm start explicitly. |
+| 2 | **Rust learning curve blows timeline** — async, borrow checker, lifetimes | High | High | Phase 1 uses minimal Rust (thin shell). Learning happens gradually during Phase 2 with a working fallback (Node.js sidecar). |
+| 3 | **Auto-update regression** — users stuck on old version permanently | Medium | Critical | Dual update channels for 6+ months. Version telemetry. Never deprecate Electron channel until >90% migrated. |
+| 4 | **Process tree kill fails silently** — zombie Claude/dev-server processes | High | Medium | Phase 0 validates. Platform-specific implementations with process group isolation. Add monitoring that detects orphaned processes. |
+
+### Moderate
+
+| # | Risk | Likelihood | Impact | Mitigation |
+|---|------|-----------|--------|------------|
+| 5 | **SQLite version mismatch during transition** — rusqlite and better-sqlite3 bundle different SQLite versions, causing WAL incompatibilities | Medium | High | Module-by-module cutover: never have both drivers writing same tables. Verify SQLite versions match or test WAL compatibility explicitly. |
+| 6 | **Next.js removal harder than expected** — data fetching, hydration, loading states all change | High | Medium | Budget 3-4 weeks not 1-2. Port page by page, test each one. Don't rush this. |
+| 7 | **Feature freeze during Phase 1** — desktop shell in flux | Medium | High | Phase 1 uses Node.js sidecar, so most features still work. Only native-feature changes are frozen. |
+| 8 | **Two apps in the wild for extended period** — support burden, bug duplication | Medium | Medium | Accept this. Plan for 6+ months of dual support. Final Electron version redirects to download page. |
+| 9 | **E2E test gap** — Electron spectron tests don't apply, new framework needed | High | Medium | Add to Phase 3. Choose Playwright or WebdriverIO with Tauri driver early. |
+
+---
+
+## Decision Log
+
+### D1: Git operations
+**Decision:** Shell out to git CLI. git2 has incomplete worktree support.
+
+### D2: Async runtime
+**Decision:** Hybrid. rusqlite sync for DB. std::process::Command sync for git. Tokio (bundled by Tauri) for WebSocket + subprocess streaming.
+
+### D3: Package manager
+**Decision:** Switch to pnpm. Faster installs, stricter hoisting. Rebuilding pipeline anyway.
+
+### D4: Transition strategy
+**Decision:** Gradual with extended overlap. Tauri as new download. Electron updates for 6+ months. Final Electron version redirects users after >90% migrated.
+
+### D5: Windows timeline
+**Decision:** Separate phase (Phase 6). Ship macOS + Linux first. Windows 6+ months after macOS Tauri is stable. Protocol handlers, process management, and code signing are fundamentally different.
+
+### D6: Phase ordering
+**Decision:** Tauri shell first (with Node.js sidecar), then Rust core. Derisks the desktop shell before investing in Rust business logic. If Tauri has a deal-breaker, we find out in week 2 instead of month 3.
+
+### D7: Sidecar communication (Phase 1)
+**Decision:** Node.js runs as localhost HTTP server (reuses existing Next.js API routes). Frontend calls localhost for data, Tauri invoke() for native features. Minimal changes to existing code.
+
+---
+
+## Auth Flow in Tauri (Critical Path)
+
+```
+User          Browser         Update Server       macOS           Tauri App
+ │               │                │                 │                │
+ │ click login   │                │                 │                │
+ │──────────────►│ GET /auth/google                 │                │
+ │               │───────────────►│                 │                │
+ │               │  302 → Google  │                 │                │
+ │               │◄───────────────│                 │                │
+ │  consent      │                │                 │                │
+ │──────────────►│  callback      │                 │                │
+ │               │───────────────►│ exchange + JWT  │                │
+ │               │  redirect to   │                 │                │
+ │               │  jettypod://auth/callback?token= │                │
+ │               │◄───────────────│                 │                │
+ │               │  open jettypod://...             │                │
+ │               │─────────────────────────────────►│                │
+ │               │                │                 │ deep_link event│
+ │               │                │                 │───────────────►│
+ │               │                │                 │                │
+ │               │                │        ┌────────┤  IF COLD START:│
+ │               │                │        │ launch │  buffer in     │
+ │               │                │        │ queue  │  launch queue, │
+ │               │                │        │        │  process after │
+ │               │                │        └────────┤  init complete │
+ │               │                │                 │                │
+ │               │                │                 │  parse URL     │
+ │               │                │                 │  hostname=auth │
+ │               │                │                 │  path=/callback│
+ │               │                │                 │  save auth.json│
+ │  dashboard    │                │                 │  emit navigate │
+ │◄─────────────────────────────────────────────────────────────────│
+```
+
+**Gotcha:** new URL('jettypod://auth/callback?token=xyz') parses hostname as 'auth', pathname as '/callback'. NOT pathname '/auth/callback'. Parse carefully.
+
+**Launch queue implementation:**
+
+```rust
+use std::sync::Mutex;
+use once_cell::sync::Lazy;
+
+static LAUNCH_QUEUE: Lazy<Mutex<Vec<String>>> = Lazy::new(|| Mutex::new(Vec::new()));
+static APP_READY: Lazy<Mutex<bool>> = Lazy::new(|| Mutex::new(false));
+
+pub fn queue_or_handle_url(url: String, app: Option<&AppHandle>) {
+    let ready = APP_READY.lock().unwrap();
+    if *ready {
+        if let Some(app) = app {
+            handle_deep_link(app, &url);
+        }
+    } else {
+        LAUNCH_QUEUE.lock().unwrap().push(url);
+    }
+}
+
+pub fn flush_launch_queue(app: &AppHandle) {
+    *APP_READY.lock().unwrap() = true;
+    let urls: Vec<String> = LAUNCH_QUEUE.lock().unwrap().drain(..).collect();
+    for url in urls {
+        handle_deep_link(app, &url);
+    }
+}
+```
+
+---
+
+## Timeline
+
+```
+Week:  1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18  19  20
+       ├P0─┤
+            ├────Phase 1: Tauri Shell + Node.js Sidecar────┤
+                                        ├──────────Phase 2: Rust Core + CLI──────────────────┤
+                                        ├P4┤                ├──Phase 3: Vite──────┤
+                                                            ├───Phase 5: Pipeline────┤
+
+                                                                          ... 6 months gap ...
+
+                                                                          ├──Phase 6: Windows──┤
+```
+
+| Phase | Calendar | Hours | Blocks |
+|-------|----------|-------|--------|
+| 0: POC | 1 wk | ~30h | Everything (go/no-go) |
+| 1: Tauri shell | 3-4 wks | ~100h | Phase 3 |
+| 2: Rust core + CLI | 6-8 wks | ~200h | Phase 3 (sidecar removal) |
+| 3: Drop Next.js | 3-4 wks | ~80h | — |
+| 4: SQLite | 1 wk | ~20h | — (overlaps Phase 2) |
+| 5: Pipeline | 2-3 wks | ~50h | Shipping |
+| 6: Windows | 4-6 wks | ~100h | — (months later) |
+
+**Phases 0-5 total: ~480 hours, 16-20 weeks calendar (~4-5 months)**
+**Including Phase 6: ~580 hours, shipping Windows ~10-12 months from start**
+
+---
+
+## Rollback Strategy
+
+| Phase | Rollback |
+|-------|----------|
+| 0: POC | It's throwaway code. Delete it. |
+| 1: Tauri shell | Users stay on Electron. Tauri is a separate download. |
+| 2: Rust core | Keep Node.js sidecar running. Swap failed Rust modules back to Node.js. |
+| 3: Drop Next.js | Git revert. |
+| 4: SQLite | Schema unchanged. Keep old drivers. |
+| 5: Pipeline | Electron pipeline still works in parallel. |
+| 6: Windows | Don't ship it. macOS + Linux are unaffected. |
+
+**Full abort at any phase:** Electron + Node.js CLI continue working. No data migration occurred (schema unchanged throughout). Delete jettypod-rs/. Only cost is time.
+
+The key advantage of the revised phase ordering: Phase 1's Node.js sidecar means you always have a working fallback. You're never in a state where both the desktop shell AND the business logic are half-ported.
+
+---
+
+## Testing Strategy
+
+### Phase 0
+- Manual testing of POC scenarios (auth, subprocess, IPC)
+- Automated test for deep link cold/warm start
+
+### Phase 1
+- Existing Jest + Cucumber tests continue running against Node.js sidecar
+- Manual testing of native features (menus, dialogs, deep links)
+- Subprocess kill verification script (spawn → kill → check children)
+
+### Phase 2
+- `cargo test` for every jettypod-core module
+- Snapshot testing: compare Rust CLI output against Node.js CLI for every command
+- Integration tests: run Rust CLI against real .jettypod projects
+- Regression: keep running Jest/Cucumber against Node.js until fully ported
+
+### Phase 3
+- Component tests updated for Vite (remove Next.js test utilities)
+- E2E framework: Playwright with Tauri WebDriver
+- Visual regression: screenshot comparison for each page before/after
+- Loading state audit: verify no pages flash empty
+
+### Phase 5
+- Update server integration tests (mock Tauri client checks for updates)
+- Signing verification tests
+- CI smoke tests on each platform
+
+### Phase 6
+- Windows-specific test suite:
+  - Protocol handler registration/deregistration
+  - Process tree kill
+  - UAC behavior during update
+  - File path handling (backslash, UNC, long paths)
+
+---
+
+## Post-Migration Wins
+
+1. **Windows desktop app** — Tauri cross-compiles (Phase 6).
+2. **Linux desktop app** — AppImage, same pipeline.
+3. **Sub-second startup** — No Chromium cold start.
+4. **~50MB install** — vs ~250MB Electron.
+5. **~80-120MB RAM idle** — vs ~400-600MB Electron.
+6. **< 10ms CLI** — vs ~200ms Node.js.
+7. **Single SQLite driver** — no dual-driver bugs.
+8. **Vite HMR < 100ms** — vs 1-3s Next.js webpack.
+9. **Tailwind v4 works** — Vite plugin, no PostCSS stripping.
+10. **Shared core library** — CLI + desktop identical business logic.