tui-td 0.1.0

data/lib/tui_td/driver.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "pty"
+require "io/console"
+require "json"
+
+module TUITD
+  # Drives a TUI application in a pseudo-terminal (PTY).
+  #
+  # Usage:
+  #   driver = Driver.new("my_tui_app")
+  #   driver.start
+  #   driver.wait_for_text("> ")
+  #   driver.send("Write hello\n")
+  #   state = driver.state_json  # => structured JSON for AI
+  #   driver.screenshot("out.png")
+  #   driver.close
+  #
+  class Driver
+    attr_reader :command, :state
+
+    def initialize(command, rows: 40, cols: 120, timeout: 30, chdir: nil)
+      @command = command
+      @rows = rows
+      @cols = cols
+      @timeout = timeout
+      @chdir = chdir
+      @state = nil
+      @stdin = nil
+      @stdout = nil
+      @wait_thr = nil
+      @output_buffer = +""
+    end
+
+    # Start the TUI application in a PTY
+    def start
+      env = { "TERM" => "xterm-256color", "COLUMNS" => @cols.to_s, "LINES" => @rows.to_s }
+      spawn_opts = {}
+      spawn_opts[:chdir] = @chdir if @chdir
+
+      @stdout, @stdin, @pid = PTY.spawn(env, @command, spawn_opts)
+      @stdout.winsize = [@rows, @cols]  # Set PTY window size for TUIs that check winsize
+      @wait_thr = Process.detach(@pid)
+
+      # Read until initial output stabilizes
+      wait_for_stable
+      refresh_state!
+
+      true
+    end
+
+    # Send text to the TUI
+    def send(text)
+      ensure_running!
+      @stdin&.print(text)
+      @stdin&.flush
+      true
+    end
+
+    # Send keys (escape sequences, control characters)
+    def send_keys(keys)
+      ensure_running!
+      case keys
+      when :enter then send("\r")
+      when :tab   then send("\t")
+      when :escape then send("\e")
+      when :up    then send("\e[A")
+      when :down  then send("\e[B")
+      when :left  then send("\e[D")
+      when :right then send("\e[C")
+      when :backspace then send("\u007f")
+      when :ctrl_c then send("\u0003")
+      when :ctrl_d then send("\u0004")
+      else send(keys.to_s)
+      end
+    end
+
+    # Wait until output contains the given text
+    def wait_for_text(text)
+      deadline = monotonic + @timeout
+      loop do
+        raise TimeoutError, "Timeout waiting for: #{text.inspect}" if monotonic > deadline
+        read_available!
+        break if @output_buffer.include?(text)
+        sleep 0.05
+      end
+      refresh_state!
+    end
+
+    # Wait for output to stabilize (no new data for N milliseconds)
+    def wait_for_stable(stable_ms: 300)
+      deadline = monotonic + @timeout
+      last_change = monotonic
+
+      loop do
+        raise TimeoutError, "Timeout waiting for stable output" if monotonic > deadline
+
+        if read_available!
+          last_change = monotonic
+        elsif (monotonic - last_change) * 1000 >= stable_ms
+          break
+        end
+
+        sleep 0.05
+      end
+      refresh_state!
+    end
+
+    # Wait until the process finishes
+    def wait_for_exit
+      @wait_thr&.value
+    end
+
+    # Get the terminal output (raw ANSI + text)
+    def raw_output
+      read_available!
+      @output_buffer
+    end
+
+    # Get structured terminal state as a Hash
+    def state_data
+      refresh_state! if @state.nil?
+      @state
+    end
+
+    # Get structured terminal state as JSON string
+    def state_json(pretty: false)
+      state_data
+      pretty ? JSON.pretty_generate(@state) : JSON.generate(@state)
+    end
+
+    # Capture a PNG screenshot of the current terminal state
+    def screenshot(output_path)
+      state_data
+      Screenshot.new(@state).render(output_path)
+    end
+
+    # Close the driver and clean up
+    def close
+      # Kill the process if still running
+      if @pid
+        begin
+          if Process.waitpid(@pid, Process::WNOHANG).nil?
+            Process.kill("TERM", @pid) rescue nil
+            sleep 0.05
+            Process.kill("KILL", @pid) rescue nil
+          end
+        rescue Errno::ECHILD
+          # Already reaped by Process.detach
+        end
+      end
+      @stdin&.close rescue nil
+      @stdout&.close rescue nil
+      @stdin = @stdout = @pid = nil
+    end
+
+    private
+
+    def ensure_running!
+      raise Error, "Driver not started. Call #start first." if @stdin.nil?
+      raise Error, "Process exited (status: #{@wait_thr&.value&.exitstatus})" unless @wait_thr&.alive?
+    end
+
+    def read_available!
+      return false unless @stdout
+
+      ready, = IO.select([@stdout], nil, nil, 0.01)
+      return false unless ready
+
+      data = @stdout.readpartial(4096)
+      @output_buffer << data
+      true
+    rescue EOFError
+      false
+    end
+
+    def refresh_state!
+      @state = ANSIParser.parse(@output_buffer, @rows, @cols)
+      @state[:raw] = @output_buffer.dup
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    end
+
+  class TimeoutError < Error; end
+end

data/lib/tui_td/html_renderer.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module TUITD
+  # Renders terminal state as a self-contained HTML document.
+  # Faithfully reproduces what a TUI application shows — colors, styles,
+  # cursor position — so an LLM or human can "see" the terminal.
+  class HtmlRenderer
+    ANSI_RGB = {
+      "black"         => [0x00, 0x00, 0x00],
+      "red"           => [0xAA, 0x00, 0x00],
+      "green"         => [0x00, 0xAA, 0x00],
+      "yellow"        => [0xAA, 0x55, 0x00],
+      "blue"          => [0x00, 0x00, 0xAA],
+      "magenta"       => [0xAA, 0x00, 0xAA],
+      "cyan"          => [0x00, 0xAA, 0xAA],
+      "white"         => [0xAA, 0xAA, 0xAA],
+      "bright_black"  => [0x55, 0x55, 0x55],
+      "bright_red"    => [0xFF, 0x55, 0x55],
+      "bright_green"  => [0x55, 0xFF, 0x55],
+      "bright_yellow" => [0xFF, 0xFF, 0x55],
+      "bright_blue"   => [0x55, 0x55, 0xFF],
+      "bright_magenta"=> [0xFF, 0x55, 0xFF],
+      "bright_cyan"   => [0x55, 0xFF, 0xFF],
+      "bright_white"  => [0xFF, 0xFF, 0xFF],
+    }.freeze
+
+    CUBE = [0x00, 0x5F, 0x87, 0xAF, 0xD7, 0xFF].freeze
+
+    ANSI_INDEX = %w[
+      black red green yellow blue magenta cyan white
+      bright_black bright_red bright_green bright_yellow
+      bright_blue bright_magenta bright_cyan bright_white
+    ].freeze
+
+    DEFAULT_FG = [0xC0, 0xC0, 0xC0].freeze
+    DEFAULT_BG = [0x00, 0x00, 0x00].freeze
+
+    def initialize(state)
+      @state = state
+      @rows = _dig(state, :size, :rows) || 40
+      @cols = _dig(state, :size, :cols) || 120
+      @grid = state[:rows] || state["rows"] || []
+      @cursor = state[:cursor] || state["cursor"] || { row: 0, col: 0 }
+    end
+
+    # Return HTML string
+    def to_html
+      css = render_css
+      body = render_body
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>TUI Terminal</title>
+        <style>#{css}</style>
+        </head>
+        <body>#{body}</body>
+        </html>
+      HTML
+    end
+
+    # Write HTML to a file
+    def render(output_path)
+      File.write(output_path, to_html)
+      output_path
+    end
+
+    private
+
+    def render_css
+      <<~CSS
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+          background: #111;
+          color: #{css_color(DEFAULT_FG)};
+          font-family: "SF Mono", "Fira Code", "Cascadia Code", "JetBrains Mono", "DejaVu Sans Mono", "Menlo", "Monaco", "Courier New", monospace;
+          font-size: 14px;
+          line-height: 1.3;
+          padding: 16px;
+        }
+        .term {
+          display: inline-block;
+          background: #{css_color(DEFAULT_BG)};
+          border: 1px solid #333;
+          border-radius: 4px;
+          padding: 8px;
+        }
+        .line {
+          white-space: pre;
+          line-height: 1.3;
+          min-height: 1.3em;
+        }
+        .cursor-cell {
+          outline: 2px solid #ff0;
+          outline-offset: -1px;
+          z-index: 1;
+          position: relative;
+        }
+      CSS
+    end
+
+    def render_body
+      lines = @grid.map.with_index do |row, ri|
+        line_html = if row.nil? || row.empty?
+          '<span class="line"></span>'
+        else
+          runs = build_runs(row, ri)
+          spans = runs.map do |run|
+            render_run(run)
+          end
+          %(<span class="line">#{spans.join}</span>)
+        end
+        line_html
+      end
+
+      %(<pre class="term">\n#{lines.join("\n")}\n</pre>)
+    end
+
+    def build_runs(row, ri)
+      runs = []
+      current_run = nil
+
+      row.each_with_index do |cell, ci|
+        char = (cell[:char] || cell["char"] || " ")
+        fg = cell[:fg] || cell["fg"] || "default"
+        bg = cell[:bg] || cell["bg"] || "default"
+        bold = cell[:bold] || cell["bold"] || false
+        italic = cell[:italic] || cell["italic"] || false
+        underline = cell[:underline] || cell["underline"] || false
+
+        style_key = [fg, bg, bold, italic, underline]
+
+        if current_run && current_run[:key] == style_key
+          current_run[:chars] << char
+        else
+          current_run = {
+            key: style_key,
+            chars: [char],
+            style: cell_style(fg, bg, bold, italic, underline),
+            has_cursor: is_cursor?(ri, ci)
+          }
+          runs << current_run
+        end
+      end
+
+      runs
+    end
+
+    def cell_style(fg, bg, bold, italic, underline)
+      parts = []
+      parts << "color:#{css_color(resolve_color(fg, DEFAULT_FG))}"
+      parts << "background-color:#{css_color(resolve_color(bg, DEFAULT_BG))}" unless bg == "default"
+      parts << "font-weight:bold" if bold
+      parts << "font-style:italic" if italic
+      parts << "text-decoration:underline" if underline
+      parts.join(";")
+    end
+
+    def render_run(run)
+      chars = run[:chars].map { |c| escape_html(c) }.join
+      return chars if run[:style].empty? && !run[:has_cursor]
+
+      classes = []
+      classes << "cursor-cell" if run[:has_cursor]
+      cls = classes.empty? ? "" : %( class="#{classes.join(" ")}")
+      style = run[:style].empty? ? "" : %( style="#{run[:style]}")
+      %(<span#{cls}#{style}>#{chars}</span>)
+    end
+
+    def is_cursor?(ri, ci)
+      @cursor[:row] == ri && @cursor[:col] == ci
+    end
+
+    def resolve_color(name, fallback)
+      case name
+      when "default"
+        fallback
+      when /^#([0-9a-fA-F]{6})$/
+        [$1[0..1].to_i(16), $1[2..3].to_i(16), $1[4..5].to_i(16)]
+      when /\Acolor(\d+)\z/
+        xterm_256($1.to_i)
+      when /\Abright_(.+)\z/
+        ANSI_RGB[name] || fallback
+      else
+        ANSI_RGB[name] || fallback
+      end
+    end
+
+    def xterm_256(index)
+      if index < 16
+        name = ANSI_INDEX[index]
+        ANSI_RGB[name] || DEFAULT_FG
+      elsif index < 232
+        r = CUBE[((index - 16) / 36) % 6]
+        g = CUBE[((index - 16) / 6) % 6]
+        b = CUBE[(index - 16) % 6]
+        [r, g, b]
+      else
+        v = 8 + (index - 232) * 10
+        [v, v, v]
+      end
+    end
+
+    def css_color(rgb)
+      format("#%02x%02x%02x", *rgb)
+    end
+
+    def escape_html(char)
+      case char
+      when "&" then "&amp;"
+      when "<" then "&lt;"
+      when ">" then "&gt;"
+      when '"' then "&quot;"
+      else char
+      end
+    end
+
+    def _dig(hash, *keys)
+      keys.each do |k|
+        return nil unless hash
+        hash = hash[k] || hash[k.to_s]
+      end
+      hash
+    end
+  end
+end

data/lib/tui_td/matchers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# RSpec matchers for TUITD::State objects.
+#
+# Usage:
+#   require "tui_td/matchers"
+#
+#   state = TUITD::State.new(driver.state_data)
+#   expect(state).to have_text("Welcome")
+#   expect(state).to have_fg("cyan").at(0, 0)
+#
+module TUITD
+  module Matchers
+    RSpec::Matchers.define :have_text do |expected|
+      match do |state|
+        state.find_text(expected).any?
+      end
+
+      description { "have text #{expected.inspect}" }
+      failure_message { |state| "expected terminal to contain #{expected.inspect}" }
+      failure_message_when_negated { |state| "expected terminal NOT to contain #{expected.inspect}" }
+    end
+
+    RSpec::Matchers.define :have_fg do |expected|
+      chain(:at) { |row, col| @row, @col = row, col }
+
+      match do |state|
+        @actual = state.foreground_at(@row, @col)
+        @actual == expected
+      end
+
+      description { "have foreground #{expected.inspect} at [#{@row},#{@col}]" }
+      failure_message do |state|
+        "expected FG at [#{@row},#{@col}] to be #{expected.inspect}, but was #{@actual.inspect}"
+      end
+    end
+
+    RSpec::Matchers.define :have_bg do |expected|
+      chain(:at) { |row, col| @row, @col = row, col }
+
+      match do |state|
+        @actual = state.background_at(@row, @col)
+        @actual == expected
+      end
+
+      description { "have background #{expected.inspect} at [#{@row},#{@col}]" }
+      failure_message do |state|
+        "expected BG at [#{@row},#{@col}] to be #{expected.inspect}, but was #{@actual.inspect}"
+      end
+    end
+
+    RSpec::Matchers.define :have_style do
+      chain(:at) { |row, col| @row, @col = row, col }
+      chain(:with) { |expected| @expected = expected }
+
+      match do |state|
+        @actual = state.style_at(@row, @col)
+        @expected ||= {}
+        @expected.all? { |k, v| @actual[k] == v }
+      end
+
+      description do
+        "have style #{@expected.inspect} at [#{@row},#{@col}]"
+      end
+      failure_message do |state|
+        "expected style at [#{@row},#{@col}] to be #{@expected.inspect}, but was #{@actual.inspect}"
+      end
+    end
+  end
+end