@juspay/shooter 1.0.0

package/src/lib/modules/server/terminal/session-watcher.ts

@@ -0,0 +1,320 @@
+import { watch as chokidarWatch, type FSWatcher } from 'chokidar';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { ConversationMessage, MessagePart } from '../sessions/types';
+
+import { parseJsonlText } from '../sessions/jsonl-parser';
+
+/**
+ * Callback invoked when new JSONL entries are parsed from a watched file.
+ */
+type OnNewEntries = (entries: ConversationMessage[]) => void;
+
+interface WatchedFile {
+  callbacks: Set<OnNewEntries>;
+  filePath: string;
+  offset: number;
+  watcher: FSWatcher;
+}
+
+// Path to Claude Code's project session data
+const CLAUDE_PROJECTS_DIR = path.join(process.env.HOME || '', '.claude', 'projects');
+
+/**
+ * SessionWatcher provides incremental, file-change-driven reading of
+ * Claude Code JSONL session files. It uses chokidar to detect writes
+ * and reads only the bytes appended since the last read, parsing them
+ * into structured ConversationMessage entries.
+ */
+class SessionWatcher {
+  // Track assistant turns that span multiple JSONL lines, keyed by filePath
+  private assistantTurnsPerFile = new Map<
+    string,
+    Map<string, { parts: MessagePart[]; timestamp: string }>
+  >();
+  // Buffer for incomplete trailing lines (no terminating newline yet)
+  private lineBufferPerFile = new Map<string, string>();
+  // Track message index per file for generating fallback IDs
+  private messageIndexPerFile = new Map<string, number>();
+  private watchedFiles = new Map<string, WatchedFile>();
+
+  /**
+   * Read all entries from a JSONL file from the beginning.
+   * Used for catch-up replay when a new client connects mid-session.
+   */
+  getHistory(filePath: string): ConversationMessage[] {
+    if (!fs.existsSync(filePath)) {
+      return [];
+    }
+
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const assistantTurns = new Map<string, { parts: MessagePart[]; timestamp: string }>();
+      const messages = parseJsonlText(raw, assistantTurns, 0);
+
+      // Flush any remaining incomplete assistant turns
+      for (const [msgId, turn] of assistantTurns) {
+        if (turn.parts.length > 0) {
+          messages.push({
+            id: msgId,
+            parts: turn.parts,
+            role: 'assistant',
+            timestamp: turn.timestamp,
+          });
+        }
+      }
+
+      return messages;
+    } catch (error) {
+      console.error(`[session-watcher] Failed to read history for ${filePath}:`, error);
+      return [];
+    }
+  }
+
+  /**
+   * Get raw JSONL entries from a session file (unparsed objects).
+   */
+  getRawEntries(filePath: string): Record<string, unknown>[] {
+    if (!fs.existsSync(filePath)) {
+      return [];
+    }
+
+    try {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const entries: Record<string, unknown>[] = [];
+      for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) {continue;}
+        try {
+          entries.push(JSON.parse(trimmed));
+        } catch {
+          // skip malformed lines
+        }
+      }
+      return entries;
+    } catch (error) {
+      console.error(`[session-watcher] Failed to read raw entries for ${filePath}:`, error);
+      return [];
+    }
+  }
+
+  /**
+   * Stop watching a specific file and clean up resources.
+   */
+  stop(filePath: string): void {
+    const watched = this.watchedFiles.get(filePath);
+    if (!watched) {
+      return;
+    }
+
+    watched.watcher.close();
+    this.watchedFiles.delete(filePath);
+    this.assistantTurnsPerFile.delete(filePath);
+    this.messageIndexPerFile.delete(filePath);
+    this.lineBufferPerFile.delete(filePath);
+
+    console.log(`[session-watcher] Stopped watching: ${filePath}`);
+  }
+
+  /**
+   * Stop watching all files and clean up all resources.
+   */
+  stopAll(): void {
+    for (const [filePath] of this.watchedFiles) {
+      this.stop(filePath);
+    }
+  }
+
+  /**
+   * Subscribe to new JSONL entries for a file. If the file is not yet
+   * being watched, starts watching it. Returns an unsubscribe function
+   * that removes the callback (and stops the watcher when no subscribers
+   * remain). Matches the multi-subscriber pattern used by OpenCodeWatcher.
+   */
+  subscribe(filePath: string, onNewEntries: OnNewEntries): () => void {
+    const existing = this.watchedFiles.get(filePath);
+    if (existing) {
+      // Already watching — just add the new callback.
+      existing.callbacks.add(onNewEntries);
+      console.log(
+        `[session-watcher] Added subscriber to: ${filePath} (total=${existing.callbacks.size})`
+      );
+      return () => {
+        existing.callbacks.delete(onNewEntries);
+        console.log(
+          `[session-watcher] Removed subscriber from: ${filePath} (remaining=${existing.callbacks.size})`
+        );
+        if (existing.callbacks.size === 0) {
+          this.stop(filePath);
+        }
+      };
+    }
+
+    // Initialize tracking state for this file
+    const initialOffset = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    this.assistantTurnsPerFile.set(filePath, new Map());
+    this.messageIndexPerFile.set(filePath, 0);
+    this.lineBufferPerFile.set(filePath, '');
+
+    const watcher = chokidarWatch(filePath, {
+      // Debounce rapid successive writes
+      awaitWriteFinish: {
+        pollInterval: 100,
+        stabilityThreshold: 200,
+      },
+      // Don't emit 'add' event on initial scan — we handle catch-up via getHistory
+      ignoreInitial: true,
+      // Use polling as a fallback for network filesystems
+      usePolling: false,
+    });
+
+    const watched: WatchedFile = {
+      callbacks: new Set([onNewEntries]),
+      filePath,
+      offset: initialOffset,
+      watcher,
+    };
+
+    watcher.on('change', () => {
+      this.readNewEntries(watched);
+    });
+
+    // Handle file creation if it doesn't exist yet (PTY Manager may
+    // start watching before the AI process creates the file)
+    watcher.on('add', () => {
+      this.readNewEntries(watched);
+    });
+
+    watcher.on('error', (error) => {
+      console.error(`[session-watcher] Error watching ${filePath}:`, error);
+    });
+
+    this.watchedFiles.set(filePath, watched);
+    console.log(`[session-watcher] Watching: ${filePath} (offset: ${initialOffset})`);
+
+    return () => {
+      watched.callbacks.delete(onNewEntries);
+      console.log(
+        `[session-watcher] Removed subscriber from: ${filePath} (remaining=${watched.callbacks.size})`
+      );
+      if (watched.callbacks.size === 0) {
+        this.stop(filePath);
+      }
+    };
+  }
+
+  /**
+   * Start watching a JSONL file for new entries (legacy API).
+   * Delegates to subscribe() internally. Callers that need to
+   * unsubscribe should use subscribe() directly instead.
+   */
+  watch(filePath: string, onNewEntries: OnNewEntries): void {
+    this.subscribe(filePath, onNewEntries);
+  }
+
+  /**
+   * Read bytes appended since last offset, parse new JSONL lines,
+   * and invoke the callback with any new messages.
+   */
+  private readNewEntries(watched: WatchedFile): void {
+    const { filePath } = watched;
+
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      return;
+    }
+
+    const currentSize = stat.size;
+    if (currentSize <= watched.offset) {
+      // File truncated or unchanged — reset offset if truncated
+      if (currentSize < watched.offset) {
+        console.warn(`[session-watcher] File truncated, resetting offset: ${filePath}`);
+        watched.offset = 0;
+        this.assistantTurnsPerFile.set(filePath, new Map());
+        this.messageIndexPerFile.set(filePath, 0);
+        this.lineBufferPerFile.set(filePath, '');
+      }
+      return;
+    }
+
+    // Read only the new bytes
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const bytesToRead = currentSize - watched.offset;
+      const buffer = Buffer.alloc(bytesToRead);
+      fs.readSync(fd, buffer, 0, bytesToRead, watched.offset);
+      watched.offset = currentSize;
+
+      const chunk = buffer.toString('utf-8');
+      // Prepend any buffered incomplete line from previous read
+      const previousBuffer = this.lineBufferPerFile.get(filePath) || '';
+      const combined = previousBuffer + chunk;
+
+      // Split on newlines. If the chunk does not end with a newline,
+      // the last segment is an incomplete line — buffer it for next time.
+      const segments = combined.split('\n');
+      if (!combined.endsWith('\n')) {
+        this.lineBufferPerFile.set(filePath, segments.pop() || '');
+      } else {
+        this.lineBufferPerFile.set(filePath, '');
+        // Remove trailing empty segment from the final newline
+        if (segments.length > 0 && segments[segments.length - 1] === '') {
+          segments.pop();
+        }
+      }
+
+      const completeLines = segments.filter((line) => line.trim());
+      if (completeLines.length === 0) {
+        return;
+      }
+
+      // Parse the new lines using the file's accumulated assistant turn state
+      const assistantTurns = this.assistantTurnsPerFile.get(filePath) || new Map();
+      const startIndex = this.messageIndexPerFile.get(filePath) || 0;
+      const newText = completeLines.join('\n');
+      const newMessages = parseJsonlText(newText, assistantTurns, startIndex);
+
+      // Update the message index counter
+      this.messageIndexPerFile.set(filePath, startIndex + completeLines.length);
+
+      if (newMessages.length > 0) {
+        for (const cb of watched.callbacks) {
+          try {
+            cb(newMessages);
+          } catch (cbError) {
+            console.error('[session-watcher] Callback error:', cbError);
+          }
+        }
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+}
+
+/**
+ * Compute the JSONL file path for a Claude Code session.
+ * ~/.claude/projects/{encoded-cwd}/{sessionId}.jsonl
+ */
+export function sessionFilePath(cwd: string, sessionId: string): string {
+  const encoded = encodeCwd(cwd);
+  return path.join(CLAUDE_PROJECTS_DIR, encoded, `${sessionId}.jsonl`);
+}
+
+/**
+ * Encode a working directory path the way Claude Code does:
+ * replace `/` with `-` so `/Users/me/project` becomes `-Users-me-project`.
+ */
+function encodeCwd(cwd: string): string {
+  return cwd.replace(/\//g, '-');
+}
+
+// Use globalThis to ensure a single shared instance across module loaders.
+const SW_GLOBAL_KEY = '__shooter_session_watcher';
+export const sessionWatcher: SessionWatcher =
+	((globalThis as Record<string, unknown>)[SW_GLOBAL_KEY] as SessionWatcher) ||
+	new SessionWatcher();
+(globalThis as Record<string, unknown>)[SW_GLOBAL_KEY] = sessionWatcher;

package/src/lib/modules/server/terminal/terminal-store.ts

@@ -0,0 +1,198 @@
+/**
+ * Terminal Store — SQLite persistence for terminal metadata.
+ *
+ * Persists TerminalRecord rows so PtyManager can recover running terminals
+ * after a server restart. Uses better-sqlite3 with WAL journal mode.
+ *
+ * Database location: ~/.shooter/shooter.db
+ */
+
+import type { TerminalRecord } from '$generated/types';
+
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// ── Constants ────────────────────────────────────────────────────────
+
+const DB_DIR = path.join(process.env.HOME || '', '.shooter');
+const DB_PATH = path.join(DB_DIR, 'shooter.db');
+
+// ── Snake/Camel Conversion ───────────────────────────────────────────
+
+/** Column order used by INSERT. */
+const COLUMNS = [
+	'id',
+	'command',
+	'args',
+	'cwd',
+	'cols',
+	'rows',
+	'pid',
+	'holder_pid',
+	'socket_path',
+	'session_file',
+	'opencode_session_id',
+	'status',
+	'exit_code',
+	'created_at',
+	'exited_at'
+] as const;
+
+/** Map a snake_case DB row to a camelCase TerminalRecord. */
+function rowToRecord(row: Record<string, unknown>): TerminalRecord {
+	return {
+		args: row.args as string,
+		cols: row.cols as number,
+		command: row.command as string,
+		createdAt: row.created_at as string,
+		cwd: row.cwd as string,
+		exitCode: (row.exit_code as number) ?? null,
+		exitedAt: (row.exited_at as string) ?? null,
+		holderPid: (row.holder_pid as number) ?? null,
+		id: row.id as string,
+		opencodeSessionId: (row.opencode_session_id as string) ?? null,
+		pid: (row.pid as number) ?? null,
+		rows: row.rows as number,
+		sessionFile: (row.session_file as string) ?? null,
+		socketPath: (row.socket_path as string) ?? null,
+		status: row.status as TerminalRecord['status']
+	};
+}
+
+/** Map camelCase field name to snake_case column name. */
+const CAMEL_TO_SNAKE: Record<string, string> = {
+	createdAt: 'created_at',
+	exitCode: 'exit_code',
+	exitedAt: 'exited_at',
+	holderPid: 'holder_pid',
+	opencodeSessionId: 'opencode_session_id',
+	sessionFile: 'session_file',
+	socketPath: 'socket_path'
+};
+
+export class TerminalStore {
+	private db: Database.Database;
+
+	constructor() {
+		fs.mkdirSync(DB_DIR, { recursive: true });
+
+		this.db = new Database(DB_PATH);
+		this.db.pragma('journal_mode = WAL');
+
+		this.db.exec(`
+			CREATE TABLE IF NOT EXISTS terminals (
+				id                    TEXT PRIMARY KEY,
+				command               TEXT NOT NULL,
+				args                  TEXT NOT NULL DEFAULT '[]',
+				cwd                   TEXT NOT NULL,
+				cols                  INTEGER NOT NULL DEFAULT 80,
+				rows                  INTEGER NOT NULL DEFAULT 24,
+				pid                   INTEGER,
+				holder_pid            INTEGER,
+				socket_path           TEXT,
+				session_file          TEXT,
+				opencode_session_id   TEXT,
+				status                TEXT NOT NULL DEFAULT 'running',
+				exit_code             INTEGER,
+				created_at            TEXT NOT NULL,
+				exited_at             TEXT
+			)
+		`);
+	}
+
+	deleteOlderThan(ms: number): number {
+		const cutoff = new Date(Date.now() - ms).toISOString();
+		const result = this.db
+			.prepare(
+				"DELETE FROM terminals WHERE status IN ('exited', 'orphaned') AND COALESCE(exited_at, created_at) < ?"
+			)
+			.run(cutoff);
+		return result.changes;
+	}
+
+	get(id: string): null | TerminalRecord {
+		const row = this.db
+			.prepare('SELECT * FROM terminals WHERE id = ?')
+			.get(id) as Record<string, unknown> | undefined;
+		return row ? rowToRecord(row) : null;
+	}
+
+	insert(terminal: TerminalRecord): void {
+		const placeholders = COLUMNS.map(() => '?').join(', ');
+		const stmt = this.db.prepare(
+			`INSERT INTO terminals (${COLUMNS.join(', ')}) VALUES (${placeholders})`
+		);
+		stmt.run(
+			terminal.id,
+			terminal.command,
+			terminal.args,
+			terminal.cwd,
+			terminal.cols,
+			terminal.rows,
+			terminal.pid,
+			terminal.holderPid,
+			terminal.socketPath,
+			terminal.sessionFile,
+			terminal.opencodeSessionId,
+			terminal.status,
+			terminal.exitCode,
+			terminal.createdAt,
+			terminal.exitedAt
+		);
+	}
+
+	listAll(): TerminalRecord[] {
+		const rows = this.db
+			.prepare('SELECT * FROM terminals ORDER BY created_at DESC')
+			.all() as Record<string, unknown>[];
+		return rows.map(rowToRecord);
+	}
+
+	listRunning(): TerminalRecord[] {
+		const rows = this.db
+			.prepare("SELECT * FROM terminals WHERE status = 'running' ORDER BY created_at DESC")
+			.all() as Record<string, unknown>[];
+		return rows.map(rowToRecord);
+	}
+
+	markExited(id: string, exitCode: null | number): void {
+		this.db
+			.prepare(
+				"UPDATE terminals SET status = 'exited', exit_code = ?, exited_at = ? WHERE id = ?"
+			)
+			.run(exitCode, new Date().toISOString(), id);
+	}
+
+	markOrphaned(id: string): void {
+		this.db
+			.prepare("UPDATE terminals SET status = 'orphaned' WHERE id = ?")
+			.run(id);
+	}
+
+	update(id: string, fields: Partial<TerminalRecord>): void {
+		const entries = Object.entries(fields).filter(([key]) => key !== 'id');
+		if (entries.length === 0) {return;}
+
+		const sets = entries.map(([key]) => `${toSnake(key)} = ?`).join(', ');
+		const values = entries.map(([, val]) => val ?? null);
+
+		this.db.prepare(`UPDATE terminals SET ${sets} WHERE id = ?`).run(...values, id);
+	}
+}
+
+// ── TerminalStore Class ──────────────────────────────────────────────
+
+function toSnake(key: string): string {
+	return CAMEL_TO_SNAKE[key] || key;
+}
+
+// ── Singleton ────────────────────────────────────────────────────────
+// Use globalThis to ensure a single shared instance across module
+// loaders (same pattern as pty-manager, session-watcher, opencode-watcher).
+
+const TS_GLOBAL_KEY = '__shooter_terminal_store';
+export const terminalStore: TerminalStore =
+	((globalThis as Record<string, unknown>)[TS_GLOBAL_KEY] as TerminalStore) ||
+	new TerminalStore();
+(globalThis as Record<string, unknown>)[TS_GLOBAL_KEY] = terminalStore;

package/src/lib/modules/server/ws/events-handler.ts

@@ -0,0 +1,73 @@
+// WebSocket events handler — broadcast-only global event bus.
+// Manages the /ws/events channel: tracks connected clients and broadcasts
+// ShooterEvents to all listeners. No client-to-server messages are expected.
+
+import type { WebSocket } from 'ws';
+
+// ── Event types ─────────────────────────────────────────────────────
+
+export type ShooterEvent =
+  | { code: null | number; terminalId: string; type: 'terminal-exited'; }
+  | { command: string; terminalId: string; type: 'terminal-created'; }
+  | { decision: 'allow' | 'deny'; requestId: string; type: 'permission-resolved'; }
+  | { input: Record<string, unknown>; requestId: string; tool: string; type: 'permission-requested'; }
+  | { project: string; sessionId: string; source: 'claude-code' | 'opencode'; type: 'session-started'; }
+  | { sessionId: string; summary: string; type: 'session-ended'; };
+
+// ── Connection tracking ─────────────────────────────────────────────
+
+/** All clients subscribed to the global events channel. */
+const EVENTS_KEY = '__shooter_ws_events_clients';
+const eventsClients: Set<WebSocket> =
+  ((globalThis as Record<string, unknown>)[EVENTS_KEY] as Set<WebSocket>) || new Set<WebSocket>();
+(globalThis as Record<string, unknown>)[EVENTS_KEY] = eventsClients;
+
+// ── Handlers ────────────────────────────────────────────────────────
+
+/**
+ * Broadcast a ShooterEvent to every connected events client.
+ * Silently skips clients that are not in the OPEN ready state.
+ */
+export function broadcastEvent(event: ShooterEvent): void {
+  const data = JSON.stringify({
+    ...event,
+    timestamp: new Date().toISOString(),
+  });
+
+  for (const ws of eventsClients) {
+    // WebSocket.OPEN === 1
+    if (ws.readyState === 1) {
+      ws.send(data);
+    }
+  }
+}
+
+/**
+ * Returns the number of clients currently connected to the events channel.
+ * Used by the notifier to decide between WebSocket broadcast vs APNs push.
+ */
+export function getEventsClientCount(): number {
+  return eventsClients.size;
+}
+
+/**
+ * Handle a new WebSocket connection on /ws/events.
+ * Adds the client to the events set, sends a welcome message,
+ * and registers cleanup on close.
+ */
+export function handleEventsConnection(ws: WebSocket): void {
+  eventsClients.add(ws);
+
+  ws.send(
+    JSON.stringify({
+      channel: 'events',
+      clients: eventsClients.size,
+      timestamp: new Date().toISOString(),
+      type: 'welcome',
+    })
+  );
+
+  ws.on('close', () => {
+    eventsClients.delete(ws);
+  });
+}

package/src/lib/modules/server/ws/keepalive.ts

@@ -0,0 +1,108 @@
+// WebSocket keepalive module.
+// Sends protocol-level ping frames every 30 seconds to all tracked connections.
+// If a client does not respond with a pong within 10 seconds, the connection is
+// terminated and cleaned up.
+//
+// Cloudflare Tunnel closes idle WebSocket connections after ~100 seconds,
+// so 30-second pings keep connections alive through the tunnel.
+
+import type { WebSocket } from 'ws';
+
+import { getAllConnections } from './server.js';
+
+// ── Configuration ────────────────────────────────────────────────────
+
+const PING_INTERVAL_MS = 30_000;
+const PONG_TIMEOUT_MS = 10_000;
+
+// ── Internal state ───────────────────────────────────────────────────
+
+let pingInterval: null | ReturnType<typeof setInterval> = null;
+
+/**
+ * Track which connections have an outstanding pong we are waiting for.
+ * Maps a WebSocket to its pong-timeout timer.
+ */
+const pendingPongs = new Map<WebSocket, ReturnType<typeof setTimeout>>();
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Start the keepalive ping loop.
+ * Safe to call multiple times — subsequent calls are no-ops until `stopKeepalive()`.
+ */
+export function startKeepalive(): void {
+	if (pingInterval) {
+		return;
+	}
+
+	pingInterval = setInterval(() => {
+		const connections = getAllConnections();
+
+		for (const ws of connections) {
+			if (ws.readyState !== 1) {
+				// Not OPEN — skip (will be cleaned up by close handler)
+				continue;
+			}
+
+			// If there is already a pending pong timer for this connection,
+			// the previous ping was never answered. This should not happen
+			// under normal operation because the timeout fires in 10s and
+			// the interval is 30s, but guard against it anyway.
+			if (pendingPongs.has(ws)) {
+				continue;
+			}
+
+			// Set up a timer that fires if no pong arrives within the timeout.
+			const timeout = setTimeout(() => {
+				cleanup();
+				// No pong received — consider the connection dead.
+				ws.terminate();
+			}, PONG_TIMEOUT_MS);
+
+			pendingPongs.set(ws, timeout);
+
+			// Shared cleanup: clear the timer and remove both listeners
+			// so that close listeners do not accumulate across ping cycles.
+			function cleanup() {
+				ws.removeListener('pong', onPong);
+				ws.removeListener('close', onClose);
+				const timer = pendingPongs.get(ws);
+				if (timer) {
+					clearTimeout(timer);
+				}
+				pendingPongs.delete(ws);
+			}
+
+			const onPong = () => {
+				cleanup();
+			};
+
+			const onClose = () => {
+				cleanup();
+			};
+
+			ws.once('pong', onPong);
+			ws.once('close', onClose);
+
+			// Send the protocol-level ping frame.
+			ws.ping();
+		}
+	}, PING_INTERVAL_MS);
+}
+
+/**
+ * Stop the keepalive ping loop and clear all pending pong timers.
+ */
+export function stopKeepalive(): void {
+	if (pingInterval) {
+		clearInterval(pingInterval);
+		pingInterval = null;
+	}
+
+	// Clear any outstanding pong timers.
+	for (const [, timer] of pendingPongs) {
+		clearTimeout(timer);
+	}
+	pendingPongs.clear();
+}