gitspace 0.2.0-rc.2 → 0.2.0-rc.21

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

@@ -1,307 +0,0 @@
-/**
- * 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

@@ -1,266 +0,0 @@
-/**
- * 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());
-}