gitspace 0.2.0-rc.1

package/src/lib/tmux-lite/protocol.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Tests for the tmux-lite session framed protocol
+ */
+import { describe, it, expect } from "bun:test";
+import {
+  FrameType,
+  encodeFrame,
+  encodePTY,
+  encodeControl,
+  parseFrames,
+  decodeControl,
+  type SessionCtrl,
+  type SessionEvent,
+  type SessionFrame,
+} from "./protocol";
+
+describe("protocol", () => {
+  describe("encodeFrame", () => {
+    it("encodes a PTY frame with correct header", () => {
+      const payload = Buffer.from("hello");
+      const frame = encodeFrame(FrameType.PTY, payload);
+
+      // Header: 1 byte type + 4 bytes length
+      expect(frame.length).toBe(5 + payload.length);
+      expect(frame[0]).toBe(FrameType.PTY); // type
+      expect(frame.readUInt32BE(1)).toBe(payload.length); // length
+      expect(frame.subarray(5).toString()).toBe("hello"); // payload
+    });
+
+    it("encodes a CONTROL frame with correct header", () => {
+      const payload = Buffer.from('{"type":"resize"}');
+      const frame = encodeFrame(FrameType.CONTROL, payload);
+
+      expect(frame.length).toBe(5 + payload.length);
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      expect(frame.readUInt32BE(1)).toBe(payload.length);
+      expect(frame.subarray(5).toString()).toBe('{"type":"resize"}');
+    });
+
+    it("handles empty payload", () => {
+      const frame = encodeFrame(FrameType.PTY, Buffer.alloc(0));
+
+      expect(frame.length).toBe(5);
+      expect(frame[0]).toBe(FrameType.PTY);
+      expect(frame.readUInt32BE(1)).toBe(0);
+    });
+
+    it("handles Uint8Array payload", () => {
+      const payload = new Uint8Array([1, 2, 3, 4, 5]);
+      const frame = encodeFrame(FrameType.PTY, payload);
+
+      expect(frame.length).toBe(5 + 5);
+      expect(frame.subarray(5)).toEqual(Buffer.from([1, 2, 3, 4, 5]));
+    });
+  });
+
+  describe("encodePTY", () => {
+    it("wraps data in a PTY frame", () => {
+      const data = Buffer.from("terminal output");
+      const frame = encodePTY(data);
+
+      expect(frame[0]).toBe(FrameType.PTY);
+      expect(frame.subarray(5).toString()).toBe("terminal output");
+    });
+  });
+
+  describe("encodeControl", () => {
+    it("encodes resize message", () => {
+      const msg: SessionCtrl = { type: "resize", cols: 120, rows: 40 };
+      const frame = encodeControl(msg);
+
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      const payload = frame.subarray(5).toString();
+      expect(JSON.parse(payload)).toEqual(msg);
+    });
+
+    it("encodes attach-init message", () => {
+      const msg: SessionCtrl = { type: "attach-init", cols: 80, rows: 24, clientType: "cli" };
+      const frame = encodeControl(msg);
+
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      const payload = frame.subarray(5).toString();
+      expect(JSON.parse(payload)).toEqual(msg);
+    });
+
+    it("encodes detach message", () => {
+      const msg: SessionCtrl = { type: "detach" };
+      const frame = encodeControl(msg);
+
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      const payload = frame.subarray(5).toString();
+      expect(JSON.parse(payload)).toEqual(msg);
+    });
+
+    it("encodes exited event", () => {
+      const msg: SessionEvent = { type: "exited", code: 0 };
+      const frame = encodeControl(msg);
+
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      const payload = frame.subarray(5).toString();
+      expect(JSON.parse(payload)).toEqual(msg);
+    });
+
+    it("encodes kicked event", () => {
+      const msg: SessionEvent = { type: "kicked" };
+      const frame = encodeControl(msg);
+
+      expect(frame[0]).toBe(FrameType.CONTROL);
+      const payload = frame.subarray(5).toString();
+      expect(JSON.parse(payload)).toEqual(msg);
+    });
+  });
+
+  describe("parseFrames", () => {
+    it("parses a single complete frame", () => {
+      const frame = encodePTY(Buffer.from("hello"));
+      const result = parseFrames(frame);
+
+      expect(result.frames.length).toBe(1);
+      expect(result.frames[0].type).toBe(FrameType.PTY);
+      expect(result.frames[0].payload.toString()).toBe("hello");
+      expect(result.remaining.length).toBe(0);
+    });
+
+    it("parses multiple complete frames", () => {
+      const frame1 = encodePTY(Buffer.from("first"));
+      const frame2 = encodeControl({ type: "resize", cols: 80, rows: 24 });
+      const frame3 = encodePTY(Buffer.from("third"));
+
+      const combined = Buffer.concat([frame1, frame2, frame3]);
+      const result = parseFrames(combined);
+
+      expect(result.frames.length).toBe(3);
+      expect(result.frames[0].type).toBe(FrameType.PTY);
+      expect(result.frames[0].payload.toString()).toBe("first");
+      expect(result.frames[1].type).toBe(FrameType.CONTROL);
+      expect(result.frames[2].type).toBe(FrameType.PTY);
+      expect(result.frames[2].payload.toString()).toBe("third");
+      expect(result.remaining.length).toBe(0);
+    });
+
+    it("handles incomplete frame (missing payload)", () => {
+      const frame = encodePTY(Buffer.from("hello world"));
+      // Only send header + partial payload
+      const partial = frame.subarray(0, 8);
+      const result = parseFrames(partial);
+
+      expect(result.frames.length).toBe(0);
+      expect(result.remaining.length).toBe(8);
+      expect(result.remaining).toEqual(partial);
+    });
+
+    it("handles incomplete header", () => {
+      const frame = encodePTY(Buffer.from("hello"));
+      // Only send 3 bytes (incomplete header)
+      const partial = frame.subarray(0, 3);
+      const result = parseFrames(partial);
+
+      expect(result.frames.length).toBe(0);
+      expect(result.remaining.length).toBe(3);
+    });
+
+    it("handles empty buffer", () => {
+      const result = parseFrames(Buffer.alloc(0));
+
+      expect(result.frames.length).toBe(0);
+      expect(result.remaining.length).toBe(0);
+    });
+
+    it("returns remaining bytes after complete frames", () => {
+      const frame1 = encodePTY(Buffer.from("complete"));
+      const frame2 = encodePTY(Buffer.from("incomplete"));
+      const partial2 = frame2.subarray(0, 7); // incomplete second frame
+
+      const combined = Buffer.concat([frame1, partial2]);
+      const result = parseFrames(combined);
+
+      expect(result.frames.length).toBe(1);
+      expect(result.frames[0].payload.toString()).toBe("complete");
+      expect(result.remaining.length).toBe(7);
+    });
+
+    it("rejects oversized frames", () => {
+      // Create a frame header claiming 2MB payload (over 1MB limit)
+      const header = Buffer.alloc(5);
+      header.writeUInt8(FrameType.PTY, 0);
+      header.writeUInt32BE(2 * 1024 * 1024, 1);
+
+      expect(() => parseFrames(header)).toThrow(/exceeds maximum/);
+    });
+
+    it("rejects invalid frame types", () => {
+      // Create a frame header with invalid type (0xFF)
+      const header = Buffer.alloc(10);
+      header.writeUInt8(0xFF, 0); // Invalid type
+      header.writeUInt32BE(5, 1); // 5 bytes payload
+      header.write("hello", 5);
+
+      expect(() => parseFrames(header)).toThrow(/Invalid frame type.*protocol desync/);
+    });
+  });
+
+  describe("decodeControl", () => {
+    it("decodes resize message", () => {
+      const json = JSON.stringify({ type: "resize", cols: 100, rows: 50 });
+      const msg = decodeControl(Buffer.from(json)) as SessionCtrl;
+
+      expect(msg.type).toBe("resize");
+      if (msg.type === "resize") {
+        expect(msg.cols).toBe(100);
+        expect(msg.rows).toBe(50);
+      }
+    });
+
+    it("decodes exited event", () => {
+      const json = JSON.stringify({ type: "exited", code: 1 });
+      const msg = decodeControl(Buffer.from(json)) as SessionEvent;
+
+      expect(msg.type).toBe("exited");
+      if (msg.type === "exited") {
+        expect(msg.code).toBe(1);
+      }
+    });
+
+    it("throws on invalid JSON", () => {
+      expect(() => decodeControl(Buffer.from("not json"))).toThrow();
+    });
+  });
+
+  describe("round-trip", () => {
+    it("encodes and parses PTY data correctly", () => {
+      const original = Buffer.from("Hello, terminal!\x1b[32mGreen\x1b[0m");
+      const frame = encodePTY(original);
+      const { frames } = parseFrames(frame);
+
+      expect(frames.length).toBe(1);
+      expect(frames[0].type).toBe(FrameType.PTY);
+      expect(frames[0].payload).toEqual(original);
+    });
+
+    it("encodes and parses control messages correctly", () => {
+      const original: SessionCtrl = { type: "attach-init", cols: 120, rows: 40, clientType: "web" };
+      const frame = encodeControl(original);
+      const { frames } = parseFrames(frame);
+
+      expect(frames.length).toBe(1);
+      expect(frames[0].type).toBe(FrameType.CONTROL);
+
+      const decoded = decodeControl(frames[0].payload);
+      expect(decoded).toEqual(original);
+    });
+
+    it("handles binary data with all byte values", () => {
+      // Create buffer with all possible byte values
+      const original = Buffer.alloc(256);
+      for (let i = 0; i < 256; i++) {
+        original[i] = i;
+      }
+
+      const frame = encodePTY(original);
+      const { frames } = parseFrames(frame);
+
+      expect(frames[0].payload).toEqual(original);
+    });
+
+    it("handles data that looks like old CTRL_MAGIC", () => {
+      // ESC ] 9 9 - the old magic bytes that caused collisions with OSC 99
+      const oscSequence = Buffer.from([0x1b, 0x5d, 0x39, 0x39, 0x3b, 0x74, 0x65, 0x73, 0x74, 0x07]);
+      const frame = encodePTY(oscSequence);
+      const { frames } = parseFrames(frame);
+
+      expect(frames.length).toBe(1);
+      expect(frames[0].type).toBe(FrameType.PTY);
+      expect(frames[0].payload).toEqual(oscSequence);
+    });
+  });
+
+  describe("streaming simulation", () => {
+    it("handles data arriving in chunks", () => {
+      // Simulate streaming: multiple frames arriving in arbitrary chunks
+      const frame1 = encodePTY(Buffer.from("first message"));
+      const frame2 = encodeControl({ type: "resize", cols: 80, rows: 24 });
+      const frame3 = encodePTY(Buffer.from("second message"));
+
+      const allData = Buffer.concat([frame1, frame2, frame3]);
+
+      // Simulate receiving in 7-byte chunks
+      let buffer: Buffer = Buffer.alloc(0);
+      const allFrames: SessionFrame[] = [];
+
+      for (let i = 0; i < allData.length; i += 7) {
+        const chunk = allData.subarray(i, Math.min(i + 7, allData.length));
+        buffer = Buffer.concat([buffer, chunk]);
+
+        const { frames, remaining } = parseFrames(buffer);
+        allFrames.push(...frames);
+        buffer = remaining;
+      }
+
+      expect(allFrames.length).toBe(3);
+      expect(allFrames[0].payload.toString()).toBe("first message");
+      expect(allFrames[1].type).toBe(FrameType.CONTROL);
+      expect(allFrames[2].payload.toString()).toBe("second message");
+      expect(buffer.length).toBe(0);
+    });
+  });
+});

package/src/lib/tmux-lite/protocol.ts

@@ -0,0 +1,266 @@
+/**
+ * tmux-lite protocol
+ */
+
+/** Protocol version - increment when making breaking changes */
+export const PROTOCOL_VERSION = 1;
+
+/** Package version - should match package.json */
+export const PACKAGE_VERSION = "1.0.0";
+
+const DEFAULT_ROUTER_SOCKET = "/tmp/tmux-lite.sock";
+const DEFAULT_PID_FILE = "/tmp/tmux-lite.pid";
+const DEFAULT_SESSION_DIR = "/tmp";
+
+export function getRouterSocket(): string {
+  return process.env.TMUX_LITE_SOCKET || DEFAULT_ROUTER_SOCKET;
+}
+
+export function getPidFile(): string {
+  return process.env.TMUX_LITE_PID_FILE || DEFAULT_PID_FILE;
+}
+
+/**
+ * Pattern for valid session IDs - alphanumeric, hyphens, underscores only
+ * Security: Prevents path traversal attacks via session IDs
+ */
+const VALID_SESSION_ID_PATTERN = /^[a-zA-Z0-9\-_]+$/;
+
+/**
+ * Validate a session ID to prevent path traversal
+ */
+export function isValidSessionId(id: string): boolean {
+  if (!id || id.length === 0 || id.length > 256) {
+    return false;
+  }
+  return VALID_SESSION_ID_PATTERN.test(id);
+}
+
+export function getSessionSocketPath(id: string): string {
+  // Security: Validate session ID to prevent path traversal
+  if (!isValidSessionId(id)) {
+    throw new Error(`Invalid session ID: ${id}`);
+  }
+  const dir = process.env.TMUX_LITE_SESSION_DIR || DEFAULT_SESSION_DIR;
+  const normalizedDir = dir.endsWith("/") ? dir.slice(0, -1) : dir;
+  return `${normalizedDir}/tmux-lite-${id}.sock`;
+}
+
+const ROUTER_FRAME_HEADER_BYTES = 4;
+
+export function encodeRouterMessage(msg: Command | Response): Buffer {
+  const json = JSON.stringify(msg);
+  const len = Buffer.byteLength(json);
+  const buf = Buffer.alloc(ROUTER_FRAME_HEADER_BYTES + len);
+  buf.writeUInt32BE(len, 0);
+  buf.write(json, ROUTER_FRAME_HEADER_BYTES);
+  return buf;
+}
+
+export function decodeRouterMessages(buffer: Buffer): {
+  messages: Array<Command | Response>;
+  remaining: Buffer;
+} {
+  const messages: Array<Command | Response> = [];
+  let offset = 0;
+
+  while (offset + ROUTER_FRAME_HEADER_BYTES <= buffer.length) {
+    const len = buffer.readUInt32BE(offset);
+    const frameEnd = offset + ROUTER_FRAME_HEADER_BYTES + len;
+    if (frameEnd > buffer.length) {
+      break;
+    }
+    const json = buffer.subarray(offset + ROUTER_FRAME_HEADER_BYTES, frameEnd).toString();
+    messages.push(JSON.parse(json));
+    offset = frameEnd;
+  }
+
+  return {
+    messages,
+    remaining: buffer.subarray(offset),
+  };
+}
+
+// Router commands
+export type Command =
+  | { type: "list" }
+  | { type: "new"; name?: string; cwd: string }
+  | { type: "attach"; id: string; force?: boolean }
+  | { type: "kill"; id: string }
+  | { type: "kill-server" }
+  | { type: "inbox" }
+  | { type: "inbox-clear"; id?: string }  // Clear one or all
+  | { type: "inbox-read"; id: string }    // Mark as read
+  | { type: "version" }                   // Get server version info
+  | { type: "status" };                   // Get server status (version + stats)
+
+export type Response =
+  | { type: "sessions"; sessions: Session[] }
+  | { type: "session"; session: Session }
+  | { type: "already-attached"; session: Session }
+  | { type: "ok" }
+  | { type: "error"; message: string }
+  | { type: "inbox"; items: InboxItem[] }
+  | { type: "version"; version: string; protocol: number }
+  | { type: "status"; version: string; protocol: number; pid: number; uptime: number; sessions: number; attached: number };
+
+export interface Session {
+  id: string;
+  name: string;
+  socketPath: string;
+  pid: number;
+  attached: boolean;
+  cwd: string;
+  createdAt: number;
+  exitCode?: number;  // undefined = running, number = exited
+  processTitle?: string;  // Title set by running process (e.g., vim, npm run dev)
+}
+
+// Inbox item - things that need attention
+export interface InboxItem {
+  id: string;
+  sessionId: string;
+  sessionName: string;
+  type: 'bell' | 'exit' | 'title' | 'idle';
+  timestamp: number;
+  exitCode?: number;
+  context: string;  // The actual message/output
+  processTitle?: string;  // What process was running (e.g., "claude", "npm run dev")
+  read: boolean;
+}
+
+// ============================================================================
+// Session Framed Protocol
+// ============================================================================
+//
+// All session socket communication uses length-prefixed framing:
+//   [type:1 byte][len:4 bytes BE][payload:len bytes]
+//
+// Frame types:
+//   0x00 = PTY data (raw bytes, passthrough)
+//   0x01 = CONTROL message (JSON)
+//
+// This replaces the old CTRL_MAGIC scanning approach which had collision
+// issues with OSC 99 (Kitty notifications).
+
+/** Frame types for the session protocol */
+export const FrameType = {
+  PTY: 0x00,      // Raw PTY data
+  CONTROL: 0x01,  // JSON control message
+} as const;
+
+export type FrameTypeValue = (typeof FrameType)[keyof typeof FrameType];
+
+/** Session control messages (client → server) */
+export type SessionCtrl =
+  | { type: "attach-init"; cols: number; rows: number; clientType?: "cli" | "web" }
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "detach" };
+
+/** Session events (server → client) */
+export type SessionEvent =
+  | { type: "attach-ready"; cols: number; rows: number }
+  | { type: "attached" }
+  | { type: "exited"; code: number }
+  | { type: "kicked" };
+
+/** A decoded frame from the session socket */
+export interface SessionFrame {
+  type: FrameTypeValue;
+  payload: Buffer;
+}
+
+/** Result of parsing frames from a buffer */
+export interface FrameParseResult {
+  frames: SessionFrame[];
+  remaining: Buffer;
+}
+
+// Frame header: 1 byte type + 4 bytes length
+const FRAME_HEADER_LEN = 5;
+
+// Maximum frame size (1MB) - security limit to prevent DoS
+// Matches relay protocol limit for consistency across all transport paths
+export const MAX_FRAME_SIZE = 1024 * 1024;
+
+// Valid frame types for sanity checking (helps detect protocol desync)
+const VALID_FRAME_TYPES = new Set([FrameType.PTY, FrameType.CONTROL]);
+
+/**
+ * Encode data into a frame
+ * @param type - FrameType.PTY or FrameType.CONTROL
+ * @param payload - Raw bytes to send
+ */
+export function encodeFrame(type: FrameTypeValue, payload: Buffer | Uint8Array): Buffer {
+  const payloadBuf = Buffer.from(payload);
+  const buf = Buffer.alloc(FRAME_HEADER_LEN + payloadBuf.length);
+  buf.writeUInt8(type, 0);
+  buf.writeUInt32BE(payloadBuf.length, 1);
+  payloadBuf.copy(buf, FRAME_HEADER_LEN);
+  return buf;
+}
+
+/**
+ * Encode raw PTY data into a frame
+ */
+export function encodePTY(data: Buffer | Uint8Array): Buffer {
+  return encodeFrame(FrameType.PTY, data);
+}
+
+/**
+ * Encode a control message (SessionCtrl or SessionEvent) into a frame
+ */
+export function encodeControl(msg: SessionCtrl | SessionEvent): Buffer {
+  const json = JSON.stringify(msg);
+  return encodeFrame(FrameType.CONTROL, Buffer.from(json));
+}
+
+/**
+ * Parse frames from a buffer (handles partial frames)
+ *
+ * @param buffer - Buffer containing one or more frames
+ * @returns Parsed frames and any remaining bytes (incomplete frame)
+ */
+export function parseFrames(buffer: Buffer): FrameParseResult {
+  const frames: SessionFrame[] = [];
+  let offset = 0;
+
+  while (offset + FRAME_HEADER_LEN <= buffer.length) {
+    const type = buffer.readUInt8(offset) as FrameTypeValue;
+    const length = buffer.readUInt32BE(offset + 1);
+
+    // Security: Validate frame type (helps detect protocol desync)
+    if (!VALID_FRAME_TYPES.has(type)) {
+      throw new Error(`Invalid frame type 0x${type.toString(16).padStart(2, '0')} at offset ${offset} (possible protocol desync)`);
+    }
+
+    // Security: Reject oversized frames
+    if (length > MAX_FRAME_SIZE) {
+      throw new Error(`Frame size ${length} exceeds maximum ${MAX_FRAME_SIZE} (type=0x${type.toString(16).padStart(2, '0')}, offset=${offset})`);
+    }
+
+    const frameEnd = offset + FRAME_HEADER_LEN + length;
+    if (frameEnd > buffer.length) {
+      // Incomplete frame, need more data
+      break;
+    }
+
+    // Copy payload data - subarray references become invalid when Bun reuses socket buffers
+    const payload = Buffer.from(buffer.subarray(offset + FRAME_HEADER_LEN, frameEnd));
+    frames.push({ type, payload });
+    offset = frameEnd;
+  }
+
+  return {
+    frames,
+    // Copy remaining bytes - subarray references become invalid when Bun reuses socket buffers
+    remaining: Buffer.from(buffer.subarray(offset)),
+  };
+}
+
+/**
+ * Decode a control message from a frame payload
+ */
+export function decodeControl(payload: Buffer): SessionCtrl | SessionEvent {
+  return JSON.parse(payload.toString());
+}