vibetunnel/web/spec.md

# VibeTunnel Codebase Map

A comprehensive navigation guide for the VibeTunnel web terminal system.

## Project Overview

VibeTunnel is a web-based terminal multiplexer with distributed architecture support. It provides:
- PTY-based terminal sessions via node-pty
- Real-time terminal streaming via SSE (asciinema cast files)
- Binary-optimized buffer synchronization (current viewport via WebSocket)
- Distributed HQ/remote server architecture
- Web UI with full terminal emulation
- Push notifications for terminal bell events
- Multi-method authentication (SSH keys, JWT, PAM)

## Directory Structure

```
web/
├── src/
│   ├── server/           # Node.js Express server
│   │   ├── middleware/   # Auth and other middleware
│   │   ├── pty/         # PTY management
│   │   ├── routes/      # API endpoints
│   │   ├── services/    # Core services
│   │   ├── server.ts    # Main server implementation
│   │   └── fwd.ts       # CLI forwarding tool
│   ├── client/           # Lit-based web UI
│   │   ├── assets/      # Static files (fonts, icons, html)
│   │   ├── components/  # UI components
│   │   ├── services/    # Client services
│   │   └── utils/       # Client utilities
│   ├── test/            # Test files
│   └── cli.ts           # Main entry point
├── scripts/             # Build scripts
└── public/              # Built static assets (generated)
```

## Server Architecture (`src/server/`)

### Core Components

#### Entry Points
- `cli.ts` (1-62): Main entry point, routes to server or forward mode
- `server/server.ts` (1-953): Core server implementation with Express app factory
  - CLI parsing (132-236): Extensive configuration options
  - Server modes (432-444): Normal, HQ, Remote initialization
  - WebSocket upgrade (564-677): Authentication and buffer streaming
  - Graceful shutdown (888-944): Cleanup intervals and service termination

### Authentication (`middleware/auth.ts`)
- Multi-method authentication (1-159)
  - SSH key authentication with Ed25519 support
  - Basic auth (username/password)
  - Bearer token for HQ↔Remote communication
  - JWT tokens for session persistence
- Local bypass for localhost connections (24-48, 68-87)
- Query parameter token support for EventSource

### Session Management

#### PTY Manager (`pty/pty-manager.ts`)
- Session creation (78-163): Spawns PTY processes with node-pty
- **Automatic alias resolution** (191-204): Uses `ProcessUtils.resolveCommand()`
- Terminal resize handling (63-157): Dimension synchronization
- Control pipe support using file watching on all platforms
- Bell event emission for push notifications
- Clean termination with SIGTERM→SIGKILL escalation

#### Process Utils (`pty/process-utils.ts`)
- `resolveCommand()` (242-378): Detects if command exists in PATH
  - Uses `which` (Unix) or `where` (Windows) to check existence
  - Returns appropriate shell command for aliases/builtins
  - Sources shell config files for proper alias support
- `getUserShell()` (384-484): Determines user's preferred shell
  - Checks `$SHELL` environment variable first
  - Platform-specific fallbacks (pwsh/cmd on Windows, zsh/bash on Unix)
- Interactive shell detection (220-235): Auto-adds `-i -l` flags

#### Session Manager (`pty/session-manager.ts`)
- Session persistence in `~/.vibetunnel/control/`
- Filesystem-based session discovery
- Zombie session cleanup

#### Terminal Manager (`services/terminal-manager.ts`)
- Headless xterm.js for server-side state
- Binary buffer snapshot generation
- Watches asciinema cast files and applies to terminal
- Debounced buffer change notifications

### API Routes (`routes/`)

#### Sessions (`sessions.ts`)
- `GET /api/sessions` (51-124): List all sessions
  - Returns array with `source: 'local' | 'remote'`
  - HQ mode: Aggregates from all remote servers
- `POST /api/sessions` (126-265): Create session
  - Body: `{ command, workingDir?, name?, remoteId?, spawn_terminal? }`
  - Returns: `{ sessionId: string, message?: string }`
- `GET /api/sessions/:id` (369-410): Get session info
- `DELETE /api/sessions/:id` (413-467): Kill session
- `DELETE /api/sessions/:id/cleanup` (470-518): Clean session files
- `POST /api/cleanup-exited` (521-598): Clean all exited sessions

#### Session I/O
- `POST /api/sessions/:id/input` (874-950): Send keyboard input
  - Body: `{ text: string }` OR `{ key: SpecialKey }`
- `POST /api/sessions/:id/resize` (953-1025): Resize terminal
  - Body: `{ cols: number, rows: number }`
- `POST /api/sessions/:id/reset-size` (1028-1083): Reset to native size

#### Session Output
- `GET /api/sessions/:id/stream` (723-871): SSE streaming
  - Streams asciinema v2 format with custom exit event
  - Replays existing content, then real-time streaming
- `GET /api/sessions/:id/buffer` (662-721): Binary buffer snapshot
- `GET /api/sessions/:id/text` (601-659): Plain text output
  - Optional `?styles` for markup: `[style fg="15" bold]text[/style]`

#### Activity Monitoring
- `GET /api/sessions/activity` (268-324): All sessions activity
- `GET /api/sessions/:id/activity` (327-366): Single session activity
  - Returns: `{ isActive: boolean, timestamp: string, session: SessionInfo }`

#### Remotes (`remotes.ts`) - HQ Mode Only
- `GET /api/remotes` (19-33): List registered servers
- `POST /api/remotes/register` (36-64): Register remote
- `DELETE /api/remotes/:id` (67-84): Unregister remote
- `POST /api/remotes/:id/refresh-sessions` (87-152): Refresh session list

#### Logs (`logs.ts`)
- `POST /api/logs/client` (21-53): Client log submission
- `GET /api/logs/raw` (56-74): Stream raw log file
- `GET /api/logs/info` (77-102): Log file metadata
- `DELETE /api/logs/clear` (105-119): Clear log file

### Binary Buffer Protocol

**Note**: "Buffer" refers to the current terminal viewport without scrollback - used for terminal previews.

#### Format (`terminal-manager.ts:361-555`)
```
Header (32 bytes):
- Magic: 0x5654 "VT" (2 bytes)
- Version: 0x01 (1 byte)
- Flags: reserved (1 byte)
- Dimensions: cols, rows (8 bytes)
- Cursor: X, Y, viewport (12 bytes)
- Reserved (4 bytes)

Rows: 0xFE=empty, 0xFD=content
Cells: Variable-length with type byte
```

### SSE Streaming and Asciinema Files

#### Asciinema Writer (`pty/asciinema-writer.ts`)
- Writes cast files to `~/.vibetunnel/control/[sessionId]/stream-out`
- Format:
  - Standard: `[timestamp, "o", output]` for terminal output
  - Standard: `[timestamp, "i", input]` for user input
  - Standard: `[timestamp, "r", "colsxrows"]` for resize events
  - **Custom**: `["exit", exitCode, sessionId]` when process terminates

#### SSE Streaming (`routes/sessions.ts:723-871`)
- Real-time streaming of asciinema cast files
- Replays existing content with zeroed timestamps
- Watches for new content and streams incrementally
- Heartbeat every 30 seconds

### WebSocket (`services/buffer-aggregator.ts`)
- Client connections (30-87): Authentication and subscription
- Message handling (88-127): Subscribe/unsubscribe/ping
- Binary protocol (156-209): `[0xBF][ID Length][Session ID][Buffer Data]`
- Local and remote session proxy support

### Activity Monitoring (`services/activity-monitor.ts`)
- Monitors `stream-out` file size changes (143-146)
- 100ms check interval (41-44)
- 500ms inactivity timeout (209-212)
- Persists to `activity.json` per session (220-245)
- Works for all sessions regardless of creation method

### HQ Mode Components

#### Remote Registry (`services/remote-registry.ts`)
- Health checks every 15s (150-187)
- Session ownership tracking (91-148)
- Bearer token authentication
- Automatic unhealthy remote removal

#### HQ Client (`services/hq-client.ts`)
- Registration with HQ (40-90)
- Unique ID generation with UUID v4
- Graceful unregistration on shutdown (92-113)

### Additional Services

#### Push Notifications (`services/push-notification-service.ts`)
- Web Push API integration (64-363)
- Subscription management in `~/.vibetunnel/notifications/`
- Bell event notifications (231-247)
- Automatic expired subscription cleanup

#### Bell Event Handler (`services/bell-event-handler.ts`)
- Processes terminal bell events (59-182)
- Integrates with push notifications
- Includes process context in notifications

#### Authentication Service (`services/auth-service.ts`)
- SSH key authentication (144-159, 201-271)
  - Ed25519 signature verification
  - Challenge-response system
  - Checks `~/.ssh/authorized_keys`
- Password authentication (105-120)
- PAM authentication fallback (184-196)
- JWT token management (176-180)

#### Control Directory Watcher (`services/control-dir-watcher.ts`)
- Monitors external session changes (20-175)
- HQ mode integration (116-163)
- Detects new/removed sessions

### Utilities

#### Logger (`utils/logger.ts`)
- Structured logging with file and console output (1-186)
- Color-coded console with chalk
- Log levels: log, warn, error, debug
- File output to `~/.vibetunnel/log.txt`
- Debug mode via `VIBETUNNEL_DEBUG`

#### VAPID Manager (`utils/vapid-manager.ts`)
- Auto-generates VAPID keys for push notifications (20-331)
- Stores in `~/.vibetunnel/vapid/keys.json`
- Key rotation support

## Client Architecture (`src/client/`)

### Core Components

#### Entry Points
- `app-entry.ts` (1-28): Main entry, initializes Monaco and push notifications
- `test-entry.ts`: Test terminals entry
- `styles.css`: Global Tailwind styles

#### Main Application (`app.ts`)
- Lit-based SPA (15-1200+): `<vibetunnel-app>`
- URL-based routing with `?session=<id>`
- Global keyboard handlers (Cmd+O, Escape)
- View management: auth/list/session
- **Events fired**:
  - `toggle-nav`, `navigate-to-list`, `error`, `success`, `navigate`

### Component Event Architecture

```
vibetunnel-app
├── app-header (navigation, controls)
├── session-list (when view='list')
│   └── session-card (per session)
│       └── vibe-terminal-buffer (terminal preview)
├── session-view (when view='session')
│   ├── session-header
│   ├── vibe-terminal (main terminal)
│   ├── mobile-input-overlay
│   ├── ctrl-alpha-overlay
│   └── terminal-quick-keys
├── session-create-form (modal)
├── file-browser (modal)
├── unified-settings (modal)
└── auth-login (when view='auth')
```

### Terminal Components

#### Terminal (`terminal.ts`)
- Full xterm.js implementation (1-1000+)
- Virtual scrolling (537-555)
- Touch/momentum support
- URL highlighting integration
- **Events**: `terminal-ready`, `terminal-input`, `terminal-resize`, `url-clicked`

#### VibeTunnelBuffer (`vibe-terminal-buffer.ts`)
- Read-only terminal preview (25-268)
- WebSocket buffer subscription
- Auto-resizing
- **Events**: `content-changed`

#### SessionView (`session-view.ts`)
- Full-screen terminal view (29-1331)
- Manager architecture:
  - ConnectionManager: SSE streaming
  - InputManager: Keyboard/mouse
  - MobileInputManager: Mobile input
  - DirectKeyboardManager: Direct keyboard access
  - TerminalLifecycleManager: Terminal state
- **Events**: `navigate-to-list`, `error`, `warning`

### Session Management Components

#### SessionList (`session-list.ts`)
- Grid/list layout (61-700+)
- Hide/show exited sessions
- Search and filtering
- **Events**: `navigate-to-session`, `refresh`, `error`, `success`

#### SessionCard (`session-card.ts`)
- Individual session display (31-420+)
- Live terminal preview
- Activity detection
- **Events**: `session-select`, `session-killed`, `session-kill-error`

#### SessionCreateForm (`session-create-form.ts`)
- Modal dialog (27-381)
- Command input with working directory
- Native terminal spawn option
- **Events**: `session-created`, `cancel`, `error`

### UI Components

#### AppHeader (`app-header.ts`)
- Main navigation (15-280+)
- Session status display
- Theme toggle
- **Events**: `toggle-nav`, `navigate-to-list`, `toggle-create-form`

#### FileBrowser (`file-browser.ts`)
- Filesystem navigation (48-665)
- Git status display
- Monaco editor preview
- **Events**: `insert-path`, `open-in-editor`, `directory-selected`

#### LogViewer (`log-viewer.ts`)
- Real-time log display (1-432)
- SSE-style polling
- Level filtering
- Search functionality

### Services

#### BufferSubscriptionService (`buffer-subscription-service.ts`)
- WebSocket client (30-87)
- Binary protocol decoder (163-208)
- Auto-reconnection with backoff
- Per-session subscriptions

#### PushNotificationService (`push-notification-service.ts`)
- Service worker registration
- Push subscription management
- Notification action handling

#### AuthClient (`auth-client.ts`)
- Token management
- Authentication state
- API header generation

### Utils

#### CastConverter (`cast-converter.ts`)
- Asciinema v2 parser (31-82)
- SSE stream handler (294-427)
- Custom exit event support

#### TerminalRenderer (`terminal-renderer.ts`)
- Binary buffer decoder (279-424)
- HTML generation from buffer
- Style mapping

#### URLHighlighter (`url-highlighter.ts`)
- Multi-line URL detection
- Protocol validation
- Click event handling

## Forward Tool (`src/server/fwd.ts`)

### Purpose
CLI tool for spawning PTY sessions using VibeTunnel infrastructure.

### Usage
```bash
npx tsx src/fwd.ts [--session-id <id>] <command> [args...]

# Examples
npx tsx src/fwd.ts claude --resume
npx tsx src/fwd.ts --session-id abc123 bash -l
```

### Key Features
- Interactive terminal forwarding (43-195)
- Automatic shell alias support via ProcessUtils
- Session ID pre-generation support
- Graceful cleanup on exit
- Colorful output with chalk

### Integration Points
- Uses central PTY Manager (78-82)
- Control pipe handling delegated to PTY Manager
- Terminal resize synchronization (148-163)
- Raw mode for proper input capture (166-172)

## Build System

### Main Build (`scripts/build.js`)
- Asset copying (7-121)
- CSS compilation with Tailwind
- Client bundling with esbuild
- Server TypeScript compilation
- Native executable creation

### Native Binary (`scripts/build-native.js`)
- Node.js SEA integration (1-537)
- node-pty patching for compatibility (82-218)
- Outputs:
  - `native/vibetunnel`: Main executable
  - `native/pty.node`: Terminal emulation
  - `native/spawn-helper`: Process spawning (macOS)
  - `native/authenticate_pam.node`: PAM auth

## Key Files Quick Reference

### Server Core
- `src/cli.ts`: Main entry point
- `src/server/server.ts`: Server implementation
- `src/server/middleware/auth.ts`: Authentication
- `src/server/routes/sessions.ts`: Session API
- `src/server/pty/pty-manager.ts`: PTY management
- `src/server/services/terminal-manager.ts`: Terminal state
- `src/server/services/activity-monitor.ts`: Activity tracking
- `src/server/fwd.ts`: CLI forwarding tool

### Client Core
- `src/client/app-entry.ts`: Entry point
- `src/client/app.ts`: Main SPA
- `src/client/components/terminal.ts`: Terminal renderer
- `src/client/components/session-view.ts`: Session viewer
- `src/client/services/buffer-subscription-service.ts`: WebSocket
- `src/client/utils/cast-converter.ts`: Asciinema parser

### Configuration
- Environment: `PORT`, `VIBETUNNEL_USERNAME`, `VIBETUNNEL_PASSWORD`, `VIBETUNNEL_DEBUG`
- CLI: `--port`, `--username`, `--password`, `--hq`, `--hq-url`, `--name`
- Debug logging: Set `VIBETUNNEL_DEBUG=1` or `true`

### Protocols
- REST API: Session CRUD, terminal I/O
- SSE: Real-time asciinema streaming
- WebSocket: Binary buffer updates
- Control pipes: External session control

### Session Data Storage
Each session has a directory in `~/.vibetunnel/control/[sessionId]/`:
- `session.json`: Session metadata
- `stream-out`: Asciinema cast file
- `stdin`: Input pipe
- `control`: Control pipe
- `activity.json`: Activity status

## Development Notes

### Recent Improvements
- Push notification support for terminal bells
- Multi-method authentication (SSH keys, JWT, PAM)
- Unified logging infrastructure with style guide
- Activity monitoring for all sessions
- Control directory watcher for external sessions
- Improved TypeScript types (no "as any")
- Colorful CLI output with chalk
- Auto-generation of security keys (VAPID)

### Testing
- Unit tests: `pnpm test`
- E2E tests: `pnpm run test:e2e`
- Vitest configuration with coverage

### Key Dependencies
- node-pty: Cross-platform PTY
- @xterm/headless: Terminal emulation
- Lit: Web components
- Express: HTTP server
- web-push: Push notifications
- TailwindCSS: Styling