@butlerw/vellum 0.1.0

package/src/tui/utils/__tests__/textSanitizer.test.ts

@@ -0,0 +1,266 @@
+/**
+ * Tests for textSanitizer utility
+ *
+ * @module tui/utils/__tests__/textSanitizer.test
+ */
+
+import { describe, expect, it } from "vitest";
+import { sanitize, sanitizeAnsi, sanitizeText } from "../textSanitizer.js";
+
+// =============================================================================
+// sanitizeText Tests
+// =============================================================================
+
+describe("sanitizeText", () => {
+  describe("line ending normalization", () => {
+    it("should convert CRLF to LF", () => {
+      expect(sanitizeText("Hello\r\nWorld")).toBe("Hello\nWorld");
+    });
+
+    it("should convert lone CR to LF", () => {
+      expect(sanitizeText("Hello\rWorld")).toBe("Hello\nWorld");
+    });
+
+    it("should convert mixed line endings to LF", () => {
+      expect(sanitizeText("A\r\nB\rC\nD")).toBe("A\nB\nC\nD");
+    });
+
+    it("should convert Unicode line separator (U+2028) to LF", () => {
+      expect(sanitizeText("Hello\u2028World")).toBe("Hello\nWorld");
+    });
+
+    it("should convert Unicode paragraph separator (U+2029) to LF", () => {
+      expect(sanitizeText("Hello\u2029World")).toBe("Hello\nWorld");
+    });
+  });
+
+  describe("control character removal", () => {
+    it("should remove NUL character", () => {
+      expect(sanitizeText("Hello\x00World")).toBe("HelloWorld");
+    });
+
+    it("should remove BEL character", () => {
+      expect(sanitizeText("Hello\x07World")).toBe("HelloWorld");
+    });
+
+    it("should remove backspace character", () => {
+      expect(sanitizeText("Hello\x08World")).toBe("HelloWorld");
+    });
+
+    it("should remove vertical tab", () => {
+      expect(sanitizeText("Hello\x0BWorld")).toBe("HelloWorld");
+    });
+
+    it("should remove form feed", () => {
+      expect(sanitizeText("Hello\x0CWorld")).toBe("HelloWorld");
+    });
+
+    it("should preserve escape character (for ANSI compatibility)", () => {
+      // sanitizeText preserves ESC for ANSI sequence support
+      // Use sanitize() to strip orphan ESC characters
+      expect(sanitizeText("Hello\x1BWorld")).toBe("Hello\x1BWorld");
+    });
+
+    it("should remove DEL character", () => {
+      expect(sanitizeText("Hello\x7FWorld")).toBe("HelloWorld");
+    });
+
+    it("should remove C1 control characters (0x80-0x9F)", () => {
+      expect(sanitizeText("Hello\x80\x8F\x9FWorld")).toBe("HelloWorld");
+    });
+
+    it("should preserve newline (LF)", () => {
+      expect(sanitizeText("Hello\nWorld")).toBe("Hello\nWorld");
+    });
+
+    it("should preserve tab (before conversion)", () => {
+      // Tab is preserved as control char, then converted to spaces
+      expect(sanitizeText("Hello\tWorld")).toBe("Hello  World");
+    });
+  });
+
+  describe("tab conversion", () => {
+    it("should convert tab to 2 spaces by default", () => {
+      expect(sanitizeText("A\tB")).toBe("A  B");
+    });
+
+    it("should convert tab to custom width", () => {
+      expect(sanitizeText("A\tB", { tabWidth: 4 })).toBe("A    B");
+    });
+
+    it("should convert multiple tabs", () => {
+      expect(sanitizeText("A\t\tB")).toBe("A    B");
+    });
+
+    it("should handle tab width of 0 (no conversion)", () => {
+      expect(sanitizeText("A\tB", { tabWidth: 0 })).toBe("A\tB");
+    });
+  });
+
+  describe("combined scenarios", () => {
+    it("should handle complex input", () => {
+      const input = "Hello\r\n\x00World\t!\x07";
+      expect(sanitizeText(input)).toBe("Hello\nWorld  !");
+    });
+
+    it("should handle empty string", () => {
+      expect(sanitizeText("")).toBe("");
+    });
+
+    it("should handle string with only control characters", () => {
+      // ESC is preserved for ANSI compatibility; only combined sanitize() strips orphan ESC
+      expect(sanitizeText("\x00\x07\x1B")).toBe("\x1B");
+    });
+  });
+});
+
+// =============================================================================
+// sanitizeAnsi Tests
+// =============================================================================
+
+describe("sanitizeAnsi", () => {
+  describe("safe SGR sequences (colors/styles)", () => {
+    it("should preserve basic color codes", () => {
+      expect(sanitizeAnsi("\x1b[31mRed\x1b[0m")).toBe("\x1b[31mRed\x1b[0m");
+    });
+
+    it("should preserve bright color codes", () => {
+      expect(sanitizeAnsi("\x1b[91mBright Red\x1b[0m")).toBe("\x1b[91mBright Red\x1b[0m");
+    });
+
+    it("should preserve 256-color codes", () => {
+      expect(sanitizeAnsi("\x1b[38;5;196mColor\x1b[0m")).toBe("\x1b[38;5;196mColor\x1b[0m");
+    });
+
+    it("should preserve RGB color codes", () => {
+      expect(sanitizeAnsi("\x1b[38;2;255;0;0mRGB\x1b[0m")).toBe("\x1b[38;2;255;0;0mRGB\x1b[0m");
+    });
+
+    it("should preserve text style codes", () => {
+      expect(sanitizeAnsi("\x1b[1mBold\x1b[0m")).toBe("\x1b[1mBold\x1b[0m");
+      expect(sanitizeAnsi("\x1b[3mItalic\x1b[0m")).toBe("\x1b[3mItalic\x1b[0m");
+      expect(sanitizeAnsi("\x1b[4mUnderline\x1b[0m")).toBe("\x1b[4mUnderline\x1b[0m");
+    });
+
+    it("should preserve combined style codes", () => {
+      expect(sanitizeAnsi("\x1b[1;31;4mStyled\x1b[0m")).toBe("\x1b[1;31;4mStyled\x1b[0m");
+    });
+  });
+
+  describe("dangerous CSI sequences removal", () => {
+    it("should remove cursor position (CUP)", () => {
+      expect(sanitizeAnsi("\x1b[10;20HText")).toBe("Text");
+    });
+
+    it("should remove cursor up (CUU)", () => {
+      expect(sanitizeAnsi("\x1b[5AText")).toBe("Text");
+    });
+
+    it("should remove cursor down (CUD)", () => {
+      expect(sanitizeAnsi("\x1b[5BText")).toBe("Text");
+    });
+
+    it("should remove cursor forward (CUF)", () => {
+      expect(sanitizeAnsi("\x1b[5CText")).toBe("Text");
+    });
+
+    it("should remove cursor back (CUB)", () => {
+      expect(sanitizeAnsi("\x1b[5DText")).toBe("Text");
+    });
+
+    it("should remove erase display (ED)", () => {
+      expect(sanitizeAnsi("\x1b[2JText")).toBe("Text");
+    });
+
+    it("should remove erase line (EL)", () => {
+      expect(sanitizeAnsi("\x1b[KText")).toBe("Text");
+    });
+
+    it("should remove scroll up (SU)", () => {
+      expect(sanitizeAnsi("\x1b[5SText")).toBe("Text");
+    });
+
+    it("should remove scroll down (SD)", () => {
+      expect(sanitizeAnsi("\x1b[5TText")).toBe("Text");
+    });
+
+    it("should remove save cursor position", () => {
+      expect(sanitizeAnsi("\x1b[sText\x1b[u")).toBe("Text");
+    });
+
+    it("should remove private mode sequences", () => {
+      expect(sanitizeAnsi("\x1b[?25lText\x1b[?25h")).toBe("Text");
+    });
+  });
+
+  describe("OSC sequences removal", () => {
+    it("should remove terminal title sequence (BEL terminated)", () => {
+      expect(sanitizeAnsi("\x1b]0;Title\x07Text")).toBe("Text");
+    });
+
+    it("should remove terminal title sequence (ST terminated)", () => {
+      expect(sanitizeAnsi("\x1b]0;Title\x1b\\Text")).toBe("Text");
+    });
+
+    it("should remove hyperlink sequences", () => {
+      expect(sanitizeAnsi("\x1b]8;;https://example.com\x07Link\x1b]8;;\x07")).toBe("Link");
+    });
+  });
+
+  describe("stripAllAnsi option", () => {
+    it("should strip all ANSI codes when enabled", () => {
+      const input = "\x1b[31mRed\x1b[0m \x1b[2JCleared";
+      expect(sanitizeAnsi(input, { stripAllAnsi: true })).toBe("Red Cleared");
+    });
+
+    it("should strip colors and styles when enabled", () => {
+      expect(sanitizeAnsi("\x1b[1;31;4mStyled\x1b[0m", { stripAllAnsi: true })).toBe("Styled");
+    });
+  });
+
+  describe("mixed content", () => {
+    it("should handle colors mixed with dangerous sequences", () => {
+      const input = "\x1b[2J\x1b[31mRed\x1b[0m\x1b[H";
+      expect(sanitizeAnsi(input)).toBe("\x1b[31mRed\x1b[0m");
+    });
+
+    it("should handle empty string", () => {
+      expect(sanitizeAnsi("")).toBe("");
+    });
+
+    it("should handle text without ANSI", () => {
+      expect(sanitizeAnsi("Plain text")).toBe("Plain text");
+    });
+  });
+});
+
+// =============================================================================
+// sanitize (combined) Tests
+// =============================================================================
+
+describe("sanitize (combined)", () => {
+  it("should apply both text and ANSI sanitization", () => {
+    const input = "Hello\r\nWorld\x1b[2J\x1b[31mRed\x1b[0m\t!";
+    const result = sanitize(input);
+    expect(result).toBe("Hello\nWorld\x1b[31mRed\x1b[0m  !");
+  });
+
+  it("should handle complex LLM output with ANSI codes", () => {
+    const input = "\x1b[1mTitle\x1b[0m\r\n\x1b[33mWarning\x1b[0m: Something\thappened";
+    const result = sanitize(input);
+    expect(result).toBe("\x1b[1mTitle\x1b[0m\n\x1b[33mWarning\x1b[0m: Something  happened");
+  });
+
+  it("should strip all with combined options", () => {
+    const input = "Hello\r\n\x1b[31mRed\x1b[0m\t!";
+    const result = sanitize(input, { stripAllAnsi: true, tabWidth: 4 });
+    expect(result).toBe("Hello\nRed    !");
+  });
+
+  it("should handle malicious input safely", () => {
+    // Attempt to clear screen and move cursor
+    const malicious = "\x1b[2J\x1b[H\x1b[31mTrick\x1b[0m\x1b[1000;1000H";
+    const result = sanitize(malicious);
+    expect(result).toBe("\x1b[31mTrick\x1b[0m");
+  });
+});

package/src/tui/utils/__tests__/ui-sizing.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Tests for UI Sizing Utilities
+ */
+import { describe, expect, it } from "vitest";
+import {
+  clamp,
+  DEFAULT_TERMINAL_HEIGHT,
+  DEFAULT_TERMINAL_WIDTH,
+  getContentPadding,
+  getMaxContentWidth,
+  getTerminalHeight,
+  getTerminalSize,
+  getTerminalWidth,
+  lerp,
+  NARROW_CONTENT_RATIO,
+  NARROW_WIDTH_BREAKPOINT,
+  WIDE_CONTENT_RATIO,
+  WIDE_WIDTH_BREAKPOINT,
+} from "../ui-sizing.js";
+
+describe("ui-sizing", () => {
+  describe("lerp", () => {
+    it("returns min when t=0", () => {
+      expect(lerp(0, 100, 0)).toBe(0);
+      expect(lerp(10, 20, 0)).toBe(10);
+    });
+
+    it("returns max when t=1", () => {
+      expect(lerp(0, 100, 1)).toBe(100);
+      expect(lerp(10, 20, 1)).toBe(20);
+    });
+
+    it("interpolates correctly at t=0.5", () => {
+      expect(lerp(0, 100, 0.5)).toBe(50);
+      expect(lerp(10, 20, 0.5)).toBe(15);
+    });
+
+    it("interpolates correctly at t=0.25", () => {
+      expect(lerp(0, 100, 0.25)).toBe(25);
+      expect(lerp(10, 20, 0.25)).toBe(12.5);
+    });
+
+    it("handles negative values", () => {
+      expect(lerp(-100, 100, 0.5)).toBe(0);
+      expect(lerp(-50, -10, 0.5)).toBe(-30);
+    });
+  });
+
+  describe("clamp", () => {
+    it("returns value when within range", () => {
+      expect(clamp(50, 0, 100)).toBe(50);
+      expect(clamp(0, 0, 100)).toBe(0);
+      expect(clamp(100, 0, 100)).toBe(100);
+    });
+
+    it("clamps to min when value is below range", () => {
+      expect(clamp(-10, 0, 100)).toBe(0);
+      expect(clamp(-100, -50, 50)).toBe(-50);
+    });
+
+    it("clamps to max when value is above range", () => {
+      expect(clamp(150, 0, 100)).toBe(100);
+      expect(clamp(200, 0, 100)).toBe(100);
+    });
+
+    it("handles zero range", () => {
+      expect(clamp(50, 10, 10)).toBe(10);
+    });
+  });
+
+  describe("getTerminalWidth", () => {
+    it("returns default when stdout has no columns", () => {
+      expect(getTerminalWidth(80)).toBe(process.stdout.columns ?? 80);
+    });
+
+    it("uses custom fallback", () => {
+      // When stdout.columns is undefined, uses fallback
+      const fallback = 120;
+      const result = getTerminalWidth(fallback);
+      expect(result).toBeGreaterThan(0);
+    });
+  });
+
+  describe("getTerminalHeight", () => {
+    it("returns default when stdout has no rows", () => {
+      expect(getTerminalHeight(24)).toBe(process.stdout.rows ?? 24);
+    });
+
+    it("uses custom fallback", () => {
+      const fallback = 50;
+      const result = getTerminalHeight(fallback);
+      expect(result).toBeGreaterThan(0);
+    });
+  });
+
+  describe("getMaxContentWidth", () => {
+    it("uses narrow ratio for widths <= 80", () => {
+      expect(getMaxContentWidth(80)).toBe(Math.floor(80 * NARROW_CONTENT_RATIO));
+      expect(getMaxContentWidth(60)).toBe(Math.floor(60 * NARROW_CONTENT_RATIO));
+    });
+
+    it("uses wide ratio for widths >= 132", () => {
+      expect(getMaxContentWidth(132)).toBe(Math.floor(132 * WIDE_CONTENT_RATIO));
+      expect(getMaxContentWidth(200)).toBe(Math.floor(200 * WIDE_CONTENT_RATIO));
+    });
+
+    it("interpolates for widths between 80 and 132", () => {
+      const midWidth = 106; // Midpoint between 80 and 132
+      const result = getMaxContentWidth(midWidth);
+      // Should be between the two ratios
+      const minExpected = Math.floor(midWidth * WIDE_CONTENT_RATIO);
+      const maxExpected = Math.floor(midWidth * NARROW_CONTENT_RATIO);
+      expect(result).toBeGreaterThanOrEqual(minExpected);
+      expect(result).toBeLessThanOrEqual(maxExpected);
+    });
+
+    it("handles zero width", () => {
+      expect(getMaxContentWidth(0)).toBe(0);
+    });
+  });
+
+  describe("getContentPadding", () => {
+    it("returns left and right padding", () => {
+      const result = getContentPadding(100);
+      expect(result).toHaveProperty("left");
+      expect(result).toHaveProperty("right");
+      expect(typeof result.left).toBe("number");
+      expect(typeof result.right).toBe("number");
+    });
+
+    it("padding + content = terminal width", () => {
+      const width = 100;
+      const { left, right } = getContentPadding(width);
+      const contentWidth = getMaxContentWidth(width);
+      expect(left + right + contentWidth).toBe(width);
+    });
+
+    it("distributes padding roughly evenly", () => {
+      const { left, right } = getContentPadding(100);
+      expect(Math.abs(left - right)).toBeLessThanOrEqual(1);
+    });
+  });
+
+  describe("getTerminalSize", () => {
+    it("returns object with width and height", () => {
+      const size = getTerminalSize();
+      expect(size).toHaveProperty("width");
+      expect(size).toHaveProperty("height");
+      expect(typeof size.width).toBe("number");
+      expect(typeof size.height).toBe("number");
+    });
+  });
+
+  describe("exported constants", () => {
+    it("exports expected default values", () => {
+      expect(DEFAULT_TERMINAL_WIDTH).toBe(80);
+      expect(DEFAULT_TERMINAL_HEIGHT).toBe(24);
+      expect(NARROW_WIDTH_BREAKPOINT).toBe(80);
+      expect(WIDE_WIDTH_BREAKPOINT).toBe(132);
+    });
+
+    it("exports valid ratios", () => {
+      expect(NARROW_CONTENT_RATIO).toBeGreaterThan(0);
+      expect(NARROW_CONTENT_RATIO).toBeLessThanOrEqual(1);
+      expect(WIDE_CONTENT_RATIO).toBeGreaterThan(0);
+      expect(WIDE_CONTENT_RATIO).toBeLessThanOrEqual(1);
+    });
+  });
+});

package/src/tui/utils/bracketedPaste.ts

@@ -0,0 +1,107 @@
+/**
+ * Bracketed Paste Mode Utilities
+ *
+ * Provides functions to enable/disable bracketed paste mode in terminals.
+ * When enabled, pasted text is wrapped with escape sequences that allow
+ * applications to distinguish between typed and pasted text.
+ *
+ * @module tui/utils/bracketedPaste
+ */
+
+import { getActiveStdout } from "../buffered-stdout.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** ANSI escape sequence to enable bracketed paste mode */
+const ENABLE_BRACKETED_PASTE = "\x1b[?2004h";
+
+/** ANSI escape sequence to disable bracketed paste mode */
+const DISABLE_BRACKETED_PASTE = "\x1b[?2004l";
+
+/** Escape sequence sent by terminal at start of pasted content */
+export const PASTE_START = "\x1b[200~";
+
+/** Escape sequence sent by terminal at end of pasted content */
+export const PASTE_END = "\x1b[201~";
+
+// =============================================================================
+// Functions
+// =============================================================================
+
+/**
+ * Enable bracketed paste mode.
+ *
+ * When enabled, the terminal wraps pasted content with escape sequences:
+ * - Start: ESC [ 200 ~
+ * - End: ESC [ 201 ~
+ *
+ * This allows applications to distinguish between typed and pasted text.
+ */
+export function enableBracketedPaste(): void {
+  getActiveStdout().write(ENABLE_BRACKETED_PASTE);
+}
+
+/**
+ * Disable bracketed paste mode.
+ *
+ * Should be called when the application exits to restore terminal state.
+ */
+export function disableBracketedPaste(): void {
+  getActiveStdout().write(DISABLE_BRACKETED_PASTE);
+}
+
+/**
+ * Check if a string contains the paste start sequence.
+ */
+export function hasPasteStart(data: string): boolean {
+  return data.includes(PASTE_START);
+}
+
+/**
+ * Check if a string contains the paste end sequence.
+ */
+export function hasPasteEnd(data: string): boolean {
+  return data.includes(PASTE_END);
+}
+
+/**
+ * Extract pasted content from bracketed paste sequences.
+ *
+ * @param data - Raw input data that may contain paste sequences
+ * @returns Object containing the extracted paste content and whether extraction was complete
+ */
+export function extractPasteContent(data: string): {
+  content: string;
+  complete: boolean;
+  remaining: string;
+} {
+  const startIdx = data.indexOf(PASTE_START);
+  if (startIdx === -1) {
+    return { content: "", complete: false, remaining: data };
+  }
+
+  const contentStart = startIdx + PASTE_START.length;
+  const endIdx = data.indexOf(PASTE_END, contentStart);
+
+  if (endIdx === -1) {
+    // Paste sequence started but not ended - partial paste
+    return {
+      content: data.slice(contentStart),
+      complete: false,
+      remaining: data.slice(0, startIdx),
+    };
+  }
+
+  // Complete paste sequence found
+  const pastedContent = data.slice(contentStart, endIdx);
+  const beforePaste = data.slice(0, startIdx);
+  const afterPaste = data.slice(endIdx + PASTE_END.length);
+
+  return {
+    content: pastedContent,
+    complete: true,
+    remaining: beforePaste + afterPaste,
+  };
+}

package/src/tui/utils/cursor-manager.ts

@@ -0,0 +1,131 @@
+/**
+ * Centralized Cursor Management
+ *
+ * Singleton to prevent race conditions from multiple components
+ * trying to show/hide the cursor simultaneously.
+ *
+ * @module tui/utils/cursor-manager
+ */
+
+import { getActiveStdout } from "../buffered-stdout.js";
+
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+
+/**
+ * Cursor manager implementation
+ */
+class CursorManagerImpl {
+  private _hidden = false;
+  private _locked = false;
+
+  /** Get the active stdout stream (uses BufferedStdout when available) */
+  private get _stdout(): NodeJS.WriteStream {
+    return getActiveStdout();
+  }
+
+  /**
+   * Hide the cursor (idempotent).
+   * Does nothing if cursor is already hidden or locked.
+   */
+  hide(): void {
+    if (!this._hidden && !this._locked) {
+      try {
+        this._stdout.write(HIDE_CURSOR);
+        this._hidden = true;
+      } catch {
+        // Ignore write errors (e.g., closed stdout)
+      }
+    }
+  }
+
+  /**
+   * Show the cursor (idempotent).
+   * Does nothing if cursor is already visible or locked.
+   */
+  show(): void {
+    if (this._hidden && !this._locked) {
+      try {
+        this._stdout.write(SHOW_CURSOR);
+        this._hidden = false;
+      } catch {
+        // Ignore write errors (e.g., closed stdout)
+      }
+    }
+  }
+
+  /**
+   * Lock cursor in hidden state (for TUI mode).
+   * While locked, show() has no effect.
+   */
+  lock(): void {
+    this._locked = true;
+    this.forceHide();
+  }
+
+  /**
+   * Unlock cursor control.
+   * After unlocking, show() and hide() work normally.
+   */
+  unlock(): void {
+    this._locked = false;
+  }
+
+  /**
+   * Force hide cursor (bypasses lock, for cleanup).
+   * Use only for critical cleanup scenarios.
+   */
+  forceHide(): void {
+    try {
+      this._stdout.write(HIDE_CURSOR);
+      this._hidden = true;
+    } catch {
+      // Ignore write errors
+    }
+  }
+
+  /**
+   * Force show cursor (bypasses lock, for cleanup on exit).
+   * Use only for exit/cleanup scenarios.
+   */
+  forceShow(): void {
+    try {
+      this._stdout.write(SHOW_CURSOR);
+      this._hidden = false;
+    } catch {
+      // Ignore write errors
+    }
+  }
+
+  /**
+   * Whether the cursor is currently hidden.
+   */
+  get isHidden(): boolean {
+    return this._hidden;
+  }
+
+  /**
+   * Whether cursor control is locked.
+   */
+  get isLocked(): boolean {
+    return this._locked;
+  }
+}
+
+/**
+ * Global cursor manager singleton.
+ * Use this instead of directly writing cursor escape codes.
+ *
+ * @example
+ * ```ts
+ * // Lock cursor hidden for TUI session
+ * CursorManager.lock();
+ *
+ * // On exit, restore cursor
+ * CursorManager.unlock();
+ * CursorManager.show();
+ * ```
+ */
+export const CursorManager = new CursorManagerImpl();
+
+export type { CursorManagerImpl };