gitspace 0.2.0-rc.2 → 0.2.0-rc.21

package/docs/UNIFIED_ARCHITECTURE.md

@@ -1,292 +0,0 @@
-# Unified TUI/Web Architecture Plan
-
-> **Implementation Status: ~90% Complete**
->
-> | Phase | Description | Status |
-> |-------|-------------|--------|
-> | 0 | Simplify access model | ✅ Complete |
-> | 1 | Web PIN encryption | ❌ Not started (optional security feature) |
-> | 2 | Shared component foundation | ✅ Complete |
-> | 3 | Extract SpacesBrowser | ✅ Complete |
-> | 4 | Port SpacesBrowser to TUI | ✅ Complete |
-> | 5 | MachineList component | ✅ Complete |
-> | 6 | TUI relay connection | ✅ Complete |
-> | 7 | TUI terminal with Ghostty | ✅ Complete |
-> | 8 | Inbox & Flows | ✅ Complete |
-> | 9 | Daemon management | ✅ Complete |
-
----
-
-## Goals
-
-1. **Feature parity** between TUI and web interfaces
-2. **Shared logic** - write business logic once, render for each platform
-3. **Remote machine support** in TUI - treat local machine as just another machine
-4. **Unified hierarchy**: Machines → Projects → Workspaces → Sessions
-
-## Current State
-
-### TUI (`src/tui/`)
-- OpenTUI (React-like API for terminal)
-- `state.ts` - reducer-based state management
-- `app.tsx` - 2200+ line monolithic component with:
-  - Project list panel
-  - Workspace tree panel (expandable sessions)
-  - Inbox system (notifications from tmux-lite)
-  - Flow states for modals (help, confirm-delete, new-project, new-workspace, etc.)
-  - Local-only operation
-
-### Web (`src/web/src/`)
-- React + Vite
-- `hooks/useRelayConnection.ts` - WebSocket to relay, machine list
-- `hooks/useTerminal.ts` - terminal session management
-- `components/MachineList.tsx` - machine selection
-- `components/SpacesBrowser.tsx` - workspace/session browser
-- Remote-only operation (no local support)
-
-## Architecture Pattern
-
-### File Structure
-```
-src/shared/components/
-├── MachineList.tsx          # Logic + hooks
-├── MachineList.web.tsx      # Web rendering
-├── MachineList.tui.tsx      # TUI rendering
-├── SpacesBrowser.tsx        # Logic + hooks
-├── SpacesBrowser.web.tsx    # Web rendering
-├── SpacesBrowser.tui.tsx    # TUI rendering
-├── Inbox.tsx                # Logic + hooks
-├── Inbox.web.tsx            # Web rendering
-├── Inbox.tui.tsx            # TUI rendering
-└── types.ts                 # Shared types
-```
-
-### Component Pattern
-
-Each component has three files:
-
-**1. Logic file (`Component.tsx`)**
-- Contains React hooks (works in both OpenTUI and React)
-- Pure TypeScript logic (no JSX rendering)
-- Exports `useComponent()` hook returning state + actions
-- Exports shared types
-
-**2. Web renderer (`Component.web.tsx`)**
-- React JSX only
-- Imports and uses the hook from logic file
-- Web-specific event handling (click, DOM events)
-
-**3. TUI renderer (`Component.tui.tsx`)**
-- OpenTUI JSX only
-- Imports and uses the hook from logic file
-- TUI-specific rendering (box, text, select elements)
-
-## Hierarchy: Machines → Projects → Workspaces → Sessions
-
-### Unified Flow
-```
-Launch → Machines → [Select Machine] → Projects → [Select Project] → Workspaces → [Expand] → Sessions → [Attach] → Terminal/Shell
-```
-
-Where "Local" is just another machine in the list.
-
-## Access Model (Simplified)
-
-Only two access levels:
-
-### 1. Full Access
-- Granted via `gssh access add <public-key>`
-- Can browse all projects, workspaces, sessions
-- Can create/attach/kill sessions
-- Can perform all operations on the machine
-- Identity is stored in machine's access list
-
-### 2. Session Invite (View-Only)
-- One-time link to view a specific session
-- Cannot browse projects/workspaces
-- Cannot interact with terminal (read-only)
-- Useful for: pair programming demos, showing progress, debugging help
-
-**Removed:** Per-project and per-workspace permission levels (read/write/manage). These add complexity without real enforceability - if someone can connect to your machine, granular permissions are hard to enforce meaningfully.
-
-### Current Code to Simplify
-
-The `AccessPermissions` type in `src/types/identity.ts` currently has:
-```typescript
-interface AccessPermissions {
-  read: boolean;
-  write: boolean;
-  manage: boolean;
-}
-```
-
-**Simplify to:**
-```typescript
-type AccessType = 'full' | 'session-invite';
-
-interface AccessEntry {
-  identityId: string;
-  signingPublicKey: string;
-  keyExchangePublicKey: string;
-  label?: string;
-  grantedAt: number;
-  accessType: AccessType;
-  // For session invites only:
-  sessionId?: string;
-  expiresAt?: number;
-}
-```
-
-**Files affected by simplification:**
-- `src/types/identity.ts` - Remove AccessPermissions, simplify to AccessType
-- `src/lib/tmux-lite/crypto/access-control.ts` - Remove permission checks
-- `src/core/access.ts` - Simplify addAccess, remove formatPermissions
-- `src/commands/access.ts` - Remove permission flags
-- `src/web/src/components/MachineList.tsx` - Remove permission badges
-- `src/web/src/hooks/useRelayConnection.ts` - Simplify MachineInfo type
-- `src/relay/server.ts` - Remove permission-based routing
-- `src/serve/client-session-manager.ts` - Remove permission checks
-
-## Key Implementation Decisions
-
-### 1. Terminal Handling (TUI)
-
-Use **ghostty-opentui** (`github.com/remorses/ghostty-opentui`) for both:
-- **Local sessions**: Connect directly to tmux-lite
-- **Remote sessions**: Connect through relay with encryption
-
-### 2. TUI Relay Connection
-
-TUI can be started with flags to connect to a relay:
-
-```bash
-# Connect to relay
-gssh --relay wss://relay.example.com
-
-# Or just start TUI locally (default)
-gssh
-```
-
-### 3. Key Storage & Encryption
-
-**TUI (Bun)**:
-- Use Bun's native keychain access
-- Store signing key and key exchange key in system keychain
-
-**Web (Browser)**:
-- Store keys in localStorage, **encrypted with user-defined PIN**
-- Use PBKDF2 to derive encryption key from PIN
-- Encrypt with AES-GCM
-
-## Implementation Phases
-
-### Phase 0: Simplify Access Model ✅
-- [x] Replace `AccessPermissions` with `AccessType` enum ('full' | 'session-invite')
-- [x] Update `AccessEntry` type in `src/types/identity.ts`
-- [x] Permission helpers in `src/serve/types.ts`: `canWrite()`, `canManage()`, `canAttachSession()`
-- [x] Update handshake to use simplified access
-- [x] Update all permission checks to just check access type
-
-### Phase 1: Web PIN Encryption ❌
-- [ ] Add PIN setup flow to web auth
-- [ ] Encrypt identity keys with PIN in localStorage
-- [ ] Add PIN unlock on app load
-- [ ] Create `src/shared/crypto/pin-encryption.ts`
-
-### Phase 2: Shared Component Foundation ✅
-- [x] Create `src/shared/` directory structure
-- [x] Define `MachineProvider` interface in `src/shared/providers/MachineProvider.ts`
-- [x] Create `LocalMachineProvider` in `src/shared/providers/LocalMachineProvider.ts`
-- [x] Create `RemoteMachineProvider` in `src/shared/providers/RemoteMachineProvider.ts`
-- [x] Create shared types in `src/shared/types.ts`
-
-### Phase 3: Extract SpacesBrowser ✅
-- [x] Extract `SpacesBrowser.tsx` logic from web component
-- [x] Create `SpacesBrowser.web.tsx` using the hook
-
-### Phase 4: Port SpacesBrowser to TUI ✅
-- [x] Create `SpacesBrowser.tui.tsx`
-- [x] Integrate into existing TUI app.tsx
-
-### Phase 5: MachineList Component ✅
-- [x] Create `MachineList.tsx` logic
-- [x] Create web and TUI renderers
-- [x] Add "Local" as first machine in TUI
-
-### Phase 6: TUI Relay Connection ✅
-- [x] Add `--relay` CLI flag
-- [x] Add relay WebSocket connection to TUI
-- [x] Create `RemoteMachineProvider` for TUI
-- [x] `useRemoteMachines` hook in `src/tui/hooks/`
-
-### Phase 7: TUI Terminal with Ghostty ✅ Complete
-- [x] Add ghostty-opentui dependency
-- [x] Integrate into Terminal component for local sessions
-- [x] Handle remote stream with ghostty
-- [x] Persistent terminal mode with proper cleanup
-
-### Phase 8: Inbox & Flows ✅
-- [x] Extract inbox logic to shared component (`Inbox.tsx`, `Inbox.web.tsx`, `Inbox.tui.tsx`)
-- [x] Create Flow component (`Flow.tsx`, `Flow.web.tsx`, `Flow.tui.tsx`)
-- [x] TUI inbox via `useInboxTUI` hook
-
-## File Structure
-
-```
-src/shared/
-├── components/
-│   ├── MachineList.tsx
-│   ├── MachineList.web.tsx
-│   ├── MachineList.tui.tsx
-│   ├── SpacesBrowser.tsx
-│   ├── SpacesBrowser.web.tsx
-│   ├── SpacesBrowser.tui.tsx
-│   ├── Inbox.tsx
-│   ├── Inbox.web.tsx
-│   ├── Inbox.tui.tsx
-│   └── types.ts
-├── providers/
-│   ├── MachineProvider.ts       # Interface
-│   ├── LocalMachineProvider.ts  # Filesystem + tmux-lite
-│   └── RemoteMachineProvider.ts # Relay + encryption
-├── crypto/
-│   └── pin-encryption.ts        # Web PIN-based key encryption
-└── hooks/
-    ├── useNavigation.ts
-    └── useMachineConnection.ts
-```
-
-## Dependencies
-
-```json
-{
-  "ghostty-opentui": "^x.x.x"   // TUI terminal rendering
-}
-```
-
-Note: Keychain access via Bun native API (no additional deps needed).
-
----
-
-## Recent Additions (2025-01)
-
-### Phase 9: Daemon Management ✅
-
-Added daemon lifecycle management for `gssh serve`:
-
-- [x] PID file management (`~/gitspace/.serve/serve.pid`)
-- [x] Unix socket status server (`~/gitspace/.serve/serve.sock`)
-- [x] `gssh serve start` - background daemon
-- [x] `gssh serve stop` - graceful shutdown
-- [x] `gssh status` - query all daemons
-- [x] Access command forwarding to running daemon
-- [x] `useDaemonStatus` hook in TUI
-
-**Files:**
-- `src/serve/daemon.ts` - Daemon lifecycle
-- `src/commands/status.ts` - Status CLI
-- `src/tui/hooks/useDaemonStatus.ts` - TUI integration
-
----
-
-*Last updated: 2025-01*

package/experiments/pty-benchmark.ts

@@ -1,148 +0,0 @@
-/**
- * PTY over Unix Socket Benchmark
- * Tests latency and throughput of piping PTY data over Unix domain sockets
- */
-
-import { unlinkSync } from "fs";
-
-const SOCKET_PATH = "/tmp/spaces-pty-bench.sock";
-
-// Clean up any existing socket
-try { unlinkSync(SOCKET_PATH); } catch {}
-
-// ============== SERVER ==============
-let serverTerminal: Bun.Terminal | null = null;
-let serverProc: Bun.Subprocess | null = null;
-
-const server = Bun.listen({
-  unix: SOCKET_PATH,
-  socket: {
-    open(socket) {
-      console.log("[server] Client connected");
-    },
-    data(socket, data) {
-      const msg = data.toString();
-
-      if (msg.startsWith("{")) {
-        const cmd = JSON.parse(msg);
-
-        if (cmd.type === "run") {
-          serverTerminal = new Bun.Terminal({
-            cols: 120,
-            rows: 40,
-            data(term, output) {
-              socket.write(output);
-            }
-          });
-
-          serverProc = Bun.spawn(cmd.args, {
-            terminal: serverTerminal,
-            cwd: process.cwd(),
-          });
-
-          serverProc.exited.then(code => {
-            socket.write(`\n__EXIT__${code}__`);
-          });
-        } else if (cmd.type === "resize") {
-          serverTerminal?.resize(cmd.cols, cmd.rows);
-        }
-      } else {
-        serverTerminal?.write(data);
-      }
-    },
-    close(socket) {
-      serverProc?.kill();
-      serverTerminal?.close();
-    },
-    error(socket, error) {
-      console.error("[server] Error:", error);
-    }
-  }
-});
-
-console.log(`[server] Listening on ${SOCKET_PATH}`);
-
-// ============== CLIENT ==============
-await Bun.sleep(50);
-
-let bytesReceived = 0;
-let messagesReceived = 0;
-let startTime = 0;
-let firstByteTime = 0;
-let testResolve: () => void;
-
-const client = await Bun.connect({
-  unix: SOCKET_PATH,
-  socket: {
-    open(socket) {
-      console.log("[client] Connected via Unix socket\n");
-    },
-    data(socket, data) {
-      messagesReceived++;
-      bytesReceived += data.byteLength;
-
-      if (firstByteTime === 0) {
-        firstByteTime = performance.now();
-      }
-
-      const str = data.toString();
-      if (str.includes("__EXIT__")) {
-        const elapsed = performance.now() - startTime;
-        const throughput = (bytesReceived / 1024 / 1024) / (elapsed / 1000);
-        const latency = firstByteTime - startTime;
-
-        console.log(`\n--- Results ---`);
-        console.log(`Bytes: ${(bytesReceived / 1024).toFixed(2)} KB`);
-        console.log(`Chunks: ${messagesReceived}`);
-        console.log(`Time: ${elapsed.toFixed(2)} ms`);
-        console.log(`Throughput: ${throughput.toFixed(2)} MB/s`);
-        console.log(`First byte: ${latency.toFixed(3)} ms`);
-        testResolve?.();
-      }
-    },
-    error(socket, error) {
-      console.error("[client] Error:", error);
-    }
-  }
-});
-
-async function runTest(name: string, args: string[], waitMs = 2000) {
-  console.log(`=== ${name} ===`);
-  bytesReceived = 0;
-  messagesReceived = 0;
-  firstByteTime = 0;
-
-  const done = new Promise<void>(r => { testResolve = r; });
-  startTime = performance.now();
-  client.write(JSON.stringify({ type: "run", args }));
-
-  await Promise.race([done, Bun.sleep(waitMs)]);
-}
-
-await runTest("Latency: echo", ["echo", "hello"], 500);
-await runTest("Throughput: seq 50k", ["seq", "1", "50000"], 3000);
-await runTest("Realistic: ls -laR", ["ls", "-laR", "/usr/bin"], 5000);
-
-// Interactive test
-console.log("\n=== Interactive: bash session ===");
-bytesReceived = 0;
-messagesReceived = 0;
-firstByteTime = 0;
-startTime = performance.now();
-
-client.write(JSON.stringify({ type: "run", args: ["bash"] }));
-await Bun.sleep(100);
-
-for (const cmd of ["echo test", "ls", "pwd", "exit"]) {
-  await Bun.sleep(30);
-  client.write(cmd + "\n");
-}
-
-await Bun.sleep(300);
-console.log(`Interactive: ${(bytesReceived/1024).toFixed(2)} KB in ${(performance.now()-startTime).toFixed(0)} ms`);
-
-server.stop();
-client.end();
-try { unlinkSync(SOCKET_PATH); } catch {}
-console.log("\n✓ Done");
-process.exit(0);

package/experiments/pty-latency.ts

@@ -1,100 +0,0 @@
-/**
- * Pure latency test - measure keystroke round-trip time
- */
-import { unlinkSync } from "fs";
-
-const SOCKET_PATH = "/tmp/spaces-latency.sock";
-try { unlinkSync(SOCKET_PATH); } catch {}
-
-let terminal: Bun.Terminal;
-let clientSocket: any;
-
-const server = Bun.listen({
-  unix: SOCKET_PATH,
-  socket: {
-    open(socket) {
-      clientSocket = socket;
-      terminal = new Bun.Terminal({
-        cols: 80,
-        rows: 24,
-        data(term, output) {
-          socket.write(output);
-        }
-      });
-
-      // Spawn cat - echoes input immediately
-      Bun.spawn(["cat"], { terminal });
-    },
-    data(socket, data) {
-      terminal.write(data);
-    },
-  }
-});
-
-await Bun.sleep(50);
-
-const latencies: number[] = [];
-let pendingResolve: ((t: number) => void) | null = null;
-let sendTime = 0;
-
-const client = await Bun.connect({
-  unix: SOCKET_PATH,
-  socket: {
-    data(socket, data) {
-      if (pendingResolve) {
-        const latency = performance.now() - sendTime;
-        pendingResolve(latency);
-        pendingResolve = null;
-      }
-    },
-  }
-});
-
-async function measureRoundTrip(): Promise<number> {
-  return new Promise(resolve => {
-    pendingResolve = resolve;
-    sendTime = performance.now();
-    client.write("x");
-  });
-}
-
-// Warmup
-for (let i = 0; i < 10; i++) {
-  await measureRoundTrip();
-}
-
-// Measure
-console.log("Measuring 1000 keystroke round-trips over Unix socket...\n");
-
-for (let i = 0; i < 1000; i++) {
-  const lat = await measureRoundTrip();
-  latencies.push(lat);
-}
-
-latencies.sort((a, b) => a - b);
-
-const avg = latencies.reduce((a, b) => a + b) / latencies.length;
-const p50 = latencies[Math.floor(latencies.length * 0.5)];
-const p95 = latencies[Math.floor(latencies.length * 0.95)];
-const p99 = latencies[Math.floor(latencies.length * 0.99)];
-const min = latencies[0];
-const max = latencies[latencies.length - 1];
-
-console.log("=== Keystroke Round-Trip Latency ===");
-console.log(`Min:    ${min.toFixed(3)} ms`);
-console.log(`Avg:    ${avg.toFixed(3)} ms`);
-console.log(`P50:    ${p50.toFixed(3)} ms`);
-console.log(`P95:    ${p95.toFixed(3)} ms`);
-console.log(`P99:    ${p99.toFixed(3)} ms`);
-console.log(`Max:    ${max.toFixed(3)} ms`);
-
-// Compare to typical human perception
-console.log("\n=== Context ===");
-console.log(`Human perception threshold: ~13ms`);
-console.log(`60 FPS frame time: 16.67ms`);
-console.log(`Typical SSH local: 1-5ms`);
-console.log(`Typical SSH remote: 20-100ms`);
-
-server.stop();
-client.end();
-try { unlinkSync(SOCKET_PATH); } catch {}