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

package/docs/ROADMAP.md

@@ -1,564 +0,0 @@
-# GitSpace Roadmap
-
-> **Living Document** - Captures the vision and implementation plan for GitSpace
-
----
-
-## Vision
-
-GitSpace is a unified development environment that combines:
-- **Git worktrees** for parallel branch development
-- **VM isolation** via Lima for secure, reproducible environments
-- **Process management** via wide event observability
-- **Remote access** via E2E encrypted relay
-- **Instant hosting** via Cloudflare tunnels on `*.gitspace.sh`
-- **Code intelligence** via ast-grep + AI for structural understanding
-
----
-
-## Single Entry Point: `gssh`
-
-The `gssh` command is the universal entry point:
-
-```bash
-# Local development (default)
-gssh
-# → Starts relay daemon in background (if not running)
-# → Launches TUI
-# → Shows local workspaces
-
-# Connect to remote machine
-gssh --remote <machine-id>
-gssh --remote brads-macbook
-
-# Connect via invite token
-gssh --connect <invite-token>
-```
-
-### Startup Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         gssh (entry point)                               │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│   1. Check: Is relay daemon running?                                    │
-│      └── No → Start `gssh serve` in background                          │
-│                                                                          │
-│   2. Check: --remote flag?                                              │
-│      └── Yes → Connect TUI to remote machine                            │
-│      └── No  → Connect TUI to local machine                             │
-│                                                                          │
-│   3. Launch TUI                                                         │
-│      └── Browse workspaces                                              │
-│      └── Select workspace → ensure Lima VM running → attach session     │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Feature Roadmap
-
-### 1. Cloudflare Tunnel (Status: Partially Implemented)
-
-Instant hosting on `*.gitspace.sh` subdomains.
-
-**Implemented Commands:**
-```bash
-gssh auth login             # GitHub OAuth authentication
-gssh auth logout            # Clear credentials
-gssh auth status            # Show auth status
-gssh host reserve <name>    # Reserve myapp.gitspace.sh
-gssh host release [name]    # Release subdomain
-gssh host list              # List your subdomains
-gssh host set-primary <n>   # Set primary subdomain
-gssh host status            # Show tunnel status
-```
-
-**Not Yet Implemented:**
-- Service routing (e.g., `app.username.gitspace.sh` → `localhost:3000`)
-- Per-service access control
-- Gateway worker for auth at edge
-
-**Architecture:**
-```
-Developer Mac                    Cloudflare                    Users
-─────────────                    ──────────                    ─────
-
-gssh serve ────────────────────► Tunnel  ◄─────────────────── Browser
-     │           (cloudflared)
-     │
-     ▼
-localhost:4480 ◄─────────────── username.gitspace.sh (relay WebSocket)
-```
-
-**Implementation Files:**
-- `src/commands/auth.ts` - GitHub OAuth device flow
-- `src/commands/host.ts` - Subdomain management CLI
-- `worker/` - Cloudflare Worker API (D1 database)
-- Token stored in keychain via `src/utils/secrets.ts`
-
----
-
-### 2. Lima VMs (Status: Not Implemented)
-
-VM-per-workspace isolation using Lima. Works on all Apple Silicon (M1/M2/M3+).
-
-**Why Lima:**
-- Firecracker requires KVM (Linux-only)
-- To run Firecracker on Mac, need nested virtualization
-- Nested virt only works on M3+ with macOS 15+
-- Lima VMs work on ALL Apple Silicon
-- 5-10s boot time is acceptable for workspace-level isolation
-
-**Architecture:**
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                              MAC HOST                                    │
-│                                                                          │
-│   gssh (TUI)                                                            │
-│       │                                                                  │
-│       ▼                                                                  │
-│   gssh serve (daemon)                                                   │
-│       │                                                                  │
-│       ├── LimaManager (VM lifecycle)                                    │
-│       │       │                                                          │
-│       │       ├── Lima VM: feature-auth                                 │
-│       │       │   └── tmux-lite-server                                  │
-│       │       │   └── services (api, worker, db)                        │
-│       │       │                                                          │
-│       │       └── Lima VM: bugfix-login                                 │
-│       │           └── tmux-lite-server                                  │
-│       │           └── services                                          │
-│       │                                                                  │
-│       └── Relay connection (ONE machine identity)                       │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-**Key Design Decisions:**
-- **VM per workspace**, not per service
-- **Invisible to relay** - Mac appears as one machine with multiple workspaces
-- **Session routing** - `gssh serve` routes sessions to correct Lima VM
-- **Dockerfile → rootfs** - Define VM environment via familiar Dockerfile
-
-**Config:**
-```json
-{
-  "vm": {
-    "enabled": true,
-    "cpus": 4,
-    "memory": 4096,
-    "dockerfile": "./Dockerfile.dev"
-  }
-}
-```
-
-**Implementation:**
-- `src/core/lima/manager.ts` - VM lifecycle (start/stop/status)
-- `src/core/lima/config.ts` - Generate Lima YAML from workspace config
-- `src/core/lima/connection.ts` - Connect to tmux-lite inside VM
-- `src/session/backends/lima-session-backend.ts` - Session backend implementation
-
-**Session Lifecycle:**
-1. User selects workspace in TUI
-2. Check: Lima VM running for this workspace?
-   - No → Boot Lima VM (~5-10s)
-   - Yes → Continue
-3. Check: Session exists?
-   - No → Create session in VM's tmux-lite
-   - Yes → Attach to existing session
-4. User works in session
-5. VM stays running until idle timeout
-
----
-
-### 3. Process Runner + Wide Events (Status: Not Implemented)
-
-Service management with observability via wide events.
-
-**Concepts:**
-- **Services** - Defined in config, managed by GitSpace
-- **Wide Events** - Rich structured events (not metrics/logs/traces separately)
-- **Event Correlation** - eventId chains become single wide events
-
-**Commands:**
-```bash
-gssh run                    # Start all services
-gssh run api worker         # Start specific services
-gssh run --logs             # With log tailing
-
-gssh events                 # TUI explorer
-gssh events tail            # Live tail
-gssh events "slow requests" # AI-powered query
-gssh events --filter "http.status>=500" --group-by path
-```
-
-**Config:**
-```json
-{
-  "services": [
-    {
-      "name": "api",
-      "command": "bun run dev",
-      "readyWhen": { "port": 3000 },
-      "dependsOn": [],
-      "events": { "source": "stdout", "format": "jsonl" }
-    },
-    {
-      "name": "worker",
-      "command": "bun run worker",
-      "dependsOn": ["api"]
-    }
-  ],
-  "events": {
-    "enabled": true,
-    "store": "sqlite",
-    "flushTimeout": 5000
-  }
-}
-```
-
-**Event Format (apps emit):**
-```json
-{"eventId": "req-123", "eventKey": "http.start", "method": "GET", "path": "/users"}
-{"eventId": "req-123", "eventKey": "db.query", "table": "users", "duration_ms": 45}
-{"eventId": "req-123", "eventKey": "http.end", "status": 200, "finalEvent": true}
-```
-
-**Wide Event (after correlation):**
-```json
-{
-  "eventId": "req-123",
-  "http.method": "GET",
-  "http.path": "/users",
-  "http.status": 200,
-  "db.query_count": 1,
-  "db.total_duration_ms": 45
-}
-```
-
-**Implementation:**
-- `src/core/services/supervisor.ts` - Process manager
-- `src/core/services/dependency.ts` - Dependency resolution
-- `src/core/services/health.ts` - Ready checks
-- `src/core/events/collector.ts` - Event ingestion
-- `src/core/events/correlator.ts` - eventId → wide event
-- `src/core/events/store/` - memory, sqlite, duckdb backends
-- `src/core/events/query.ts` - Filter/group/aggregate
-- `src/commands/run.ts` - CLI
-- `src/commands/events.ts` - CLI
-
----
-
-### 4. Code Intelligence (Status: Not Implemented)
-
-ast-grep + AI for structural code understanding, inspired by Lumen.
-
-**Concept:**
-- Use **ast-grep** for structural code search (not text grep)
-- **AI generates patterns** from natural language queries
-- **Correlate with runtime** - connect slow events back to code
-- **AI synthesizes** findings into actionable insights
-
-**Commands:**
-```bash
-gssh query "how does auth work?"
-gssh query "what calls validateUser?"
-gssh query "why is checkout slow?"      # Uses runtime events + code
-gssh query --impact "change User type"  # Impact analysis
-```
-
-**Architecture:**
-```
-User: "why is checkout slow?"
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  1. Pattern Generator (AI → ast-grep rules)                         │
-│     "Find all functions with 'checkout' in name"                   │
-│     "Find all db queries in checkout flow"                         │
-└─────────────────────────────────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  2. Structural Scan (ast-grep)                                      │
-│     → 5 checkout-related functions                                  │
-│     → 12 db queries in call graph                                  │
-└─────────────────────────────────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  3. Runtime Correlation (wide events)                               │
-│     → checkout requests have p95 = 850ms                           │
-│     → db.query in OrderRepository taking 500ms                     │
-└─────────────────────────────────────────────────────────────────────┘
-    │
-    ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  4. AI Synthesis                                                    │
-│     "N+1 query in OrderRepository.findByUser() at src/repos/       │
-│      order.ts:45. Called in loop by CartService.getItems()."       │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**Implementation:**
-- `src/core/insight/index.ts` - Orchestrator
-- `src/core/insight/pattern-gen.ts` - NL → ast-grep patterns
-- `src/core/insight/scanner.ts` - Execute patterns
-- `src/core/insight/graph.ts` - Dependency/call graphs
-- `src/core/insight/ai-synth.ts` - AI synthesis
-- `src/lib/ast-grep/runner.ts` - Shell out to sg CLI
-- `src/commands/query.ts` - CLI
-
----
-
-### 5. Stack Splitting (Status: Not Implemented)
-
-AI-assisted splitting of WIP commits into clean PRs. See `docs/STACK-DESIGN.md` for full design.
-
-**Commands:**
-```bash
-gssh stack                  # Analyze and propose split
-gssh stack --base develop   # Specify base branch
-gssh stack --dry-run        # Just analyze, don't execute
-gssh stack sync             # Rebase after PR merges
-gssh stack list             # List active stacks
-```
-
----
-
-## Config Schema (Full)
-
-```json
-{
-  "name": "my-app",
-  "repository": "myorg/my-app",
-  "baseBranch": "main",
-  "createdAt": "2024-12-30T00:00:00.000Z",
-  "lastAccessed": "2024-12-30T00:00:00.000Z",
-
-  "vm": {
-    "enabled": true,
-    "cpus": 4,
-    "memory": 4096,
-    "disk": 50,
-    "dockerfile": "./Dockerfile.dev"
-  },
-
-  "services": [
-    {
-      "name": "api",
-      "command": "bun run dev",
-      "cwd": "./api",
-      "env": { "PORT": "3000" },
-      "dependsOn": ["db"],
-      "readyWhen": {
-        "port": 3000,
-        "timeout": 30000
-      },
-      "events": {
-        "source": "stdout",
-        "format": "jsonl"
-      }
-    },
-    {
-      "name": "db",
-      "command": "postgres",
-      "readyWhen": { "port": 5432 }
-    }
-  ],
-
-  "events": {
-    "enabled": true,
-    "store": "sqlite",
-    "flushTimeout": 5000,
-    "maxEvents": 100000
-  },
-
-  "host": {
-    "subdomain": "myapp",
-    "routes": [
-      { "path": "/api", "service": "api" },
-      { "path": "/", "port": 8080 }
-    ],
-    "terminal": true,
-    "access": {
-      "mode": "private",
-      "allowedKeys": []
-    }
-  },
-
-  "bundleSecretKeys": ["GITSPACE_TOKEN"]
-}
-```
-
----
-
-## CLI Reference (Current + Planned)
-
-### Implemented
-
-```bash
-# Entry point
-gssh                        # Start TUI
-gssh --relay <url>          # TUI with remote machine access
-
-# Identity
-gssh identity init          # Create machine keypair
-gssh identity show          # Show fingerprint
-
-# Access control
-gssh access add <pubkey>    # Authorize client
-gssh access list            # List authorized
-gssh access remove <key>    # Revoke access
-
-# Sharing
-gssh share create           # Create invite token
-
-# Authentication (gitspace.sh)
-gssh auth login             # GitHub OAuth
-gssh auth logout            # Clear credentials
-gssh auth status            # Show auth status
-
-# Hosting (gitspace.sh)
-gssh host reserve <name>    # Reserve subdomain
-gssh host release [name]    # Release subdomain
-gssh host list              # List subdomains
-gssh host set-primary <n>   # Set primary
-gssh host status            # Show status
-
-# Remote access
-gssh serve                  # Start daemon (foreground)
-gssh serve start            # Start daemon (background)
-gssh serve stop             # Stop daemon
-gssh connect <token>        # Connect via invite token
-gssh status                 # Show daemon status
-
-# Machine management
-gssh machine invite         # Create machine invite
-gssh machine list           # List machines (stub)
-gssh machine remove <id>    # Remove machine (stub)
-
-# Projects/workspaces
-gssh add project            # Add project from GitHub
-gssh add <name>             # Create workspace
-gssh list projects          # List projects
-gssh list workspaces        # List workspaces
-gssh remove workspace       # Remove workspace
-gssh remove project         # Remove project
-gssh directory              # Print project directory
-
-# Relay (internal)
-gssh relay start            # Start relay server
-gssh relay authorize <pubkey>  # Authorize machine
-```
-
-### Planned (Not Implemented)
-
-```bash
-# Services (requires Lima VMs)
-gssh run                    # Start all services
-gssh run <service...>       # Start specific services
-gssh stop                   # Stop all services
-gssh logs <service>         # Tail logs
-
-# Events
-gssh events                 # TUI explorer
-gssh events tail            # Live tail
-gssh events query "..."     # AI-powered query
-
-# Code intelligence
-gssh query "..."            # Ask about code + runtime
-
-# Stack splitting
-gssh stack                  # AI-assisted PR splitting
-gssh stack sync             # Sync after merges
-```
-
----
-
-## File Structure (New)
-
-```
-src/
-├── commands/
-│   ├── host.ts               # gssh host *
-│   ├── run.ts                # gssh run
-│   ├── events.ts             # gssh events
-│   └── query.ts              # gssh query
-├── core/
-│   ├── lima/
-│   │   ├── manager.ts        # VM lifecycle
-│   │   ├── config.ts         # Generate Lima YAML
-│   │   └── connection.ts     # Connect to VM
-│   ├── host/
-│   │   ├── tunnel.ts         # cloudflared integration
-│   │   └── dns.ts            # Cloudflare API
-│   ├── services/
-│   │   ├── supervisor.ts     # Process manager
-│   │   ├── dependency.ts     # Dependency resolution
-│   │   └── health.ts         # Ready checks
-│   ├── events/
-│   │   ├── collector.ts      # Event ingestion
-│   │   ├── correlator.ts     # eventId chaining
-│   │   ├── store/
-│   │   │   ├── memory.ts
-│   │   │   ├── sqlite.ts
-│   │   │   └── duckdb.ts
-│   │   └── query.ts          # Query interface
-│   └── insight/
-│       ├── index.ts          # Orchestrator
-│       ├── pattern-gen.ts    # NL → ast-grep
-│       ├── scanner.ts        # Pattern execution
-│       ├── graph.ts          # Dependency graphs
-│       └── ai-synth.ts       # AI synthesis
-├── shared/
-│   └── providers/
-│       └── LimaMachineProvider.ts
-└── lib/
-    ├── ast-grep/
-    │   ├── runner.ts         # sg CLI wrapper
-    │   └── patterns.ts       # Common patterns
-    └── events/
-        └── emitter.ts        # SDK for apps
-```
-
----
-
-## Platform Support
-
-| Platform | VM Isolation | Firecracker | Notes |
-|----------|--------------|-------------|-------|
-| Mac M1 | Lima VM | ❌ | No nested virt |
-| Mac M2 | Lima VM | ❌ | No nested virt |
-| Mac M3+ (macOS 15+) | Lima VM | ✅ (optional) | Nested virt works |
-| Linux | Firecracker | ✅ | Native KVM |
-| Cloud | Firecracker | ✅ | Via Flintlock/Nomad |
-
----
-
-## Implementation Progress
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| E2E Encrypted Remote Access | **Complete** | X3DH handshake, relay routing |
-| Web Terminal Client | **Complete** | xterm.js, React |
-| TUI Remote Access | **Complete** | `--relay` flag for TUI |
-| Cloudflare Hosting | **Partial** | Auth, subdomains; missing service routing |
-| Lima VMs | Not Started | Isolation layer for workspaces |
-| Process Runner | Not Started | Depends on Lima |
-| Event Collection | Not Started | Depends on Process Runner |
-| Code Intelligence | Not Started | ast-grep + AI |
-| Stack Splitting | Not Started | AI-assisted PR splitting |
-
-### Next Steps
-
-1. **Complete Cloudflare Hosting** - Service routing, gateway worker at edge
-2. **Lima VMs** - Workspace isolation on Mac
-3. **Process Runner** - Service management inside VMs
-
----
-
-*Last updated: 2025-01*