gitspace 0.2.0-rc.20 → 0.2.0-rc.21

package/docs/UNIFIED_ARCHITECTURE.md

@@ -1,138 +0,0 @@
-# Unified Architecture
-
-This document describes the canonical shared architecture for CLI/TUI/Web state and session handling.
-
-## Status
-
-Implementation is now centered on a shared session engine and backend adapters.
-
-- Completed:
-  - Shared component logic/renderer split (`*.tsx`, `*.web.tsx`, `*.tui.tsx`)
-  - Shared workspace/project lifecycle orchestration (`core/workspace-lifecycle.ts`, `core/project-lifecycle.ts`)
-  - Shared relay machine-directory client (`src/relay-client/machine-directory-client.ts`)
-  - Shared relay machine-directory hook (`src/relay-client/useMachineDirectory.ts`) used by web+tui wrappers
-  - Shared session engine foundation (`src/session/*`)
-  - Shared remote/local backend adapters (`src/session/backends/*`)
-  - Shared remote session hook (`src/session/useRemoteSessionClient.ts`) used by web+tui wrappers
-  - Web remote terminal flow migrated to shared session backend
-  - TUI remote machine screen migrated to shared remote backend + remote terminal transport
-  - TUI local projects/workspaces/sessions/inbox state now sourced from shared local backend via `useLocalSession`
-  - TUI local terminal attach/detach/PTY lifecycle is now backend-driven via `LocalSessionBackend`
-  - TUI project/workspace panels now consume shared local backend state directly (legacy sync bridge removed)
-  - Legacy TUI-only state/adapter modules removed (`tui/state.ts`, `tui/adapters.ts`, `tui/hooks/useInboxTUI.ts`)
-  - Shared project catalog service (`core/project-catalog.ts`) used by CLI list + local backend + remote session handler
-
-## Goals
-
-1. Shared core behavior across platforms.
-2. Platform differences isolated to renderer/input/transport adapters.
-3. Remote and local machines represented through the same backend contract.
-
-## Canonical Model
-
-### 1) Session Engine (Shared)
-
-`src/session/`
-
-- `types.ts`: canonical backend/session state
-- `events.ts`: normalized backend event contract
-- `reducer.ts`: deterministic state transitions
-- `backend-manager.ts`: backend registration + event routing
-- `useSessionEngine.ts`: React hook API for platform UIs
-- `useRemoteSessionClient.ts`: shared remote terminal/session orchestration hook used by platform wrappers
-
-Key state shape:
-
-- Backends keyed by descriptor (`local`, `remote:<relay>:<machine>`)
-- Per-backend status, projects, workspaces, sessions, inbox, notification config, attach/script runtime state
-- Active backend selection for UI focus
-
-### 2) Backend Contract (Shared)
-
-`src/session/backend.ts`
-
-All local/remote machine operations are expressed through `SessionBackend`:
-
-- connect/disconnect
-- list projects/workspaces/sessions
-- attach/detach/kill/delete
-- inbox read/clear/fetch
-- notification config get/update
-- PTY write/resize (optional)
-- event subscription
-
-### 3) Backend Implementations
-
-#### Remote backend
-
-`src/session/backends/remote-session-backend.ts`
-
-- Owns relay handshake lifecycle (X3DH adapters)
-- Owns encrypted frame encode/decode adapters
-- Speaks canonical remote-session protocol (`list_*`, `attach_session`, inbox/config/script-output, etc.)
-- Emits normalized backend events
-
-#### Local backend
-
-`src/session/backends/local-session-backend.ts`
-
-- Wraps local tmux/config/workspace lifecycle operations
-- Maps local operations to the same backend event model as remote
-
-## Platform Integration
-
-### Web
-
-- Relay directory: `src/hooks/useRelayConnection.web.ts`
-- Terminal/session: `src/hooks/useTerminal.web.ts`
-
-`useRelayConnection` and `useTerminal` are now thin adapters over shared relay/session hooks.
-
-### TUI
-
-- Relay directory: `src/hooks/useRemoteMachines.tui.ts`
-- Remote terminal/session: `src/hooks/useRemoteTerminal.tui.ts`
-- Remote attached renderer: `src/components/SessionTerminal.tui.tsx`
-- Remote machine screen: `src/components/RemoteMachineScreen.tui.tsx`
-
-Current TUI state split:
-
-- Remote machine path uses shared remote backend.
-- Local machine path uses shared local backend for projects/workspaces/sessions/inbox and terminal attach lifecycle.
-- Project/workspace panel rendering reads backend state directly; local reducer now tracks only UI view/focus/loading/error state.
-
-### CLI
-
-- Project listing now shares project catalog logic through `src/core/project-catalog.ts`.
-- Remote connect now uses shared remote backend adapters (`RemoteSessionBackend` + node adapters), matching TUI/Web session protocol flow.
-
-## Data Flow
-
-1. Platform creates backend(s) with descriptor + transport/crypto/handshake adapters.
-2. Backend registers with `useSessionEngine`.
-3. UI calls engine actions (`listWorkspaces`, `attachSession`, `requestInbox`, etc.).
-4. Backend emits canonical events.
-5. Engine reducer updates state.
-6. Renderer consumes normalized state.
-
-## Testing
-
-Added/updated tests around the shared architecture:
-
-- `src/session/__tests__/reducer.test.ts`
-- `src/session/__tests__/backend-manager.test.ts`
-- `src/session/__tests__/remote-session-backend.test.ts`
-- `src/session/__tests__/local-session-backend.test.ts`
-- `src/hooks/__tests__/useLocalSession.tui.test.ts`
-- `src/tui/__tests__/local-terminal-sync.test.ts`
-
-## Final Migration Target
-
-When migration is complete:
-
-- TUI and Web both run entirely on shared session engine state.
-- Local and remote use the same backend contract.
-- Platform-specific code is limited to:
-  - renderers (`*.web.tsx`, `*.tui.tsx`)
-  - UI input handling
-  - transport/crypto adapter wiring.

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 {}

package/experiments/router/client.ts

@@ -1,199 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Client - connects to router, attaches to session
- *
- * Usage: bun client.ts [project] [workspace]
- */
-
-import { select } from "@inquirer/prompts";
-import {
-  ROUTER_SOCKET,
-  type RouterCommand,
-  type RouterResponse,
-  type SessionInfo,
-  type AttachMode,
-  encodeControl,
-  isControl,
-  decodeControl,
-  type SessionEvent,
-} from "./protocol";
-
-const [project = "test", workspace = "default"] = process.argv.slice(2);
-
-// Connect to router
-async function routerCommand(cmd: RouterCommand): Promise<RouterResponse> {
-  return new Promise(async (resolve, reject) => {
-    const socket = await Bun.connect({
-      unix: ROUTER_SOCKET,
-      socket: {
-        data(socket, data) {
-          resolve(JSON.parse(data.toString()));
-          socket.end();
-        },
-        error(socket, error) {
-          reject(error);
-        },
-        connectError(socket, error) {
-          reject(new Error("Router not running. Start with: bun router.ts"));
-        }
-      }
-    });
-
-    socket.write(JSON.stringify(cmd));
-  });
-}
-
-// Get or create session
-console.log(`Connecting to ${project}/${workspace}...`);
-
-let session: SessionInfo;
-
-try {
-  let response = await routerCommand({
-    type: "create",
-    project,
-    workspace,
-    cwd: process.cwd()
-  });
-
-  // Handle already-attached case
-  if (response.type === "already-attached") {
-    console.log(`\nSession "${project}/${workspace}" is already attached.\n`);
-
-    const choice = await select({
-      message: "What would you like to do?",
-      choices: [
-        { value: "take-over", name: "Take over (disconnect other client)" },
-        { value: "new", name: "Create new session for this workspace" },
-        { value: "cancel", name: "Cancel" },
-      ]
-    }) as AttachMode;
-
-    if (choice === "cancel") {
-      console.log("Cancelled.");
-      process.exit(0);
-    }
-
-    if (choice === "take-over") {
-      // Attach with take-over mode
-      response = await routerCommand({
-        type: "attach",
-        sessionId: response.session.id,
-        mode: "take-over"
-      });
-    } else if (choice === "new") {
-      // Force create new session (kill old one first, then create)
-      await routerCommand({ type: "kill", sessionId: response.session.id });
-      response = await routerCommand({
-        type: "create",
-        project,
-        workspace,
-        cwd: process.cwd()
-      });
-    }
-  }
-
-  if (response.type === "error") {
-    console.error("Error:", response.message);
-    process.exit(1);
-  }
-
-  if (response.type !== "created") {
-    console.error("Unexpected response:", response);
-    process.exit(1);
-  }
-
-  session = response.session;
-} catch (e: any) {
-  console.error(e.message);
-  process.exit(1);
-}
-
-console.log(`Attached to session ${session.id}`);
-console.log("Press Ctrl+D to detach\n");
-
-// Connect to session
-const sessionSocket = await Bun.connect({
-  unix: session.socketPath,
-  socket: {
-    data(socket, data) {
-      const buf = Buffer.from(data);
-
-      if (isControl(buf)) {
-        const event = decodeControl(buf) as SessionEvent;
-
-        switch (event.type) {
-          case "attached":
-            // Replay scrollback
-            if (event.scrollback) {
-              const scrollback = Buffer.from(event.scrollback, "base64");
-              process.stdout.write(scrollback);
-            }
-            break;
-
-          case "exited":
-            process.stdin.setRawMode(false);
-            console.log(`\nSession exited with code ${event.code}`);
-            process.exit(event.code);
-            break;
-
-          case "kicked":
-            process.stdin.setRawMode(false);
-            console.log("\n\nAnother client took over this session.");
-            process.exit(0);
-            break;
-
-          case "pong":
-            break;
-        }
-      } else {
-        // PTY output - write to terminal
-        process.stdout.write(buf);
-      }
-    },
-
-    close() {
-      process.stdin.setRawMode(false);
-      console.log("\nDisconnected from session");
-      process.exit(0);
-    },
-
-    error(socket, error) {
-      process.stdin.setRawMode(false);
-      console.error("\nSession error:", error.message);
-      process.exit(1);
-    }
-  }
-});
-
-// Send initial resize
-sessionSocket.write(encodeControl({
-  type: "resize",
-  cols: process.stdout.columns || 80,
-  rows: process.stdout.rows || 24
-}));
-
-// Handle terminal resize
-process.stdout.on("resize", () => {
-  sessionSocket.write(encodeControl({
-    type: "resize",
-    cols: process.stdout.columns,
-    rows: process.stdout.rows
-  }));
-});
-
-// Forward stdin to session
-process.stdin.setRawMode(true);
-process.stdin.resume();
-
-for await (const chunk of process.stdin) {
-  // Check for Ctrl+D (detach)
-  if (chunk[0] === 4) {
-    sessionSocket.write(encodeControl({ type: "detach" }));
-    process.stdin.setRawMode(false);
-    console.log("\nDetached (session still running)");
-    process.exit(0);
-  }
-
-  sessionSocket.write(chunk);
-}

package/experiments/router/protocol.ts

@@ -1,74 +0,0 @@
-/**
- * Shared protocol between router, sessions, and clients
- */
-
-export const ROUTER_SOCKET = "/tmp/spaces-router.sock";
-export const SESSION_SOCKET_PREFIX = "/tmp/spaces-session-";
-
-// Router commands (JSON over socket)
-export type RouterCommand =
-  | { type: "list" }
-  | { type: "create"; project: string; workspace: string; cwd: string }
-  | { type: "attach"; sessionId: string; mode?: AttachMode }
-  | { type: "kill"; sessionId: string }
-  | { type: "kick"; sessionId: string };  // Disconnect current client
-
-export type RouterResponse =
-  | { type: "sessions"; sessions: SessionInfo[] }
-  | { type: "created"; session: SessionInfo }
-  | { type: "already-attached"; session: SessionInfo }  // Session exists but has a client
-  | { type: "error"; message: string }
-  | { type: "ok" };
-
-export interface SessionInfo {
-  id: string;
-  project: string;
-  workspace: string;
-  socketPath: string;
-  pid: number;
-  attached: boolean;  // true if a client is connected
-  createdAt: number;
-}
-
-// When attaching to an already-attached session
-export type AttachMode =
-  | "take-over"   // Disconnect existing client, you take over
-  | "new"         // Create a new session for the same workspace
-  | "cancel";     // Abort
-
-// Session protocol (binary + JSON control)
-// Control messages start with 0x00, data is raw bytes
-export const CONTROL_PREFIX = 0x00;
-
-export type SessionControl =
-  | { type: "resize"; cols: number; rows: number }
-  | { type: "detach" }
-  | { type: "ping" };
-
-export type SessionEvent =
-  | { type: "attached"; scrollback: string }
-  | { type: "exited"; code: number }
-  | { type: "kicked" }  // Another client took over
-  | { type: "pong" };
-
-// Helper to encode control message
-export function encodeControl(msg: SessionControl | SessionEvent): Buffer {
-  const json = JSON.stringify(msg);
-  const buf = Buffer.alloc(1 + 4 + json.length);
-  buf[0] = CONTROL_PREFIX;
-  buf.writeUInt32BE(json.length, 1);
-  buf.write(json, 5);
-  return buf;
-}
-
-// Helper to check if data is control message
-export function isControl(data: Buffer): boolean {
-  return data[0] === CONTROL_PREFIX;
-}
-
-// Helper to decode control message
-export function decodeControl(data: Buffer): SessionControl | SessionEvent {
-  const len = data.readUInt32BE(1);
-  const json = data.subarray(5, 5 + len).toString();
-  return JSON.parse(json);
-}