tui-td 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0be0079e98bf668b7fb089333a443ac31e36e1726254d129461e0f580ba1af9b
-  data.tar.gz: 25b660c725c5dd79e7eada430d71a6f8711bd6c5b763bbc1069bc7fc740322e7
+  metadata.gz: be8d93991312317febcad6a713d4dd58e6e670e620211bae0adc0db0bdd21da1
+  data.tar.gz: 5618bc612addd9be3c634ebd4009800ddd6f7da9396ad5d950c8f831727398f8
 SHA512:
-  metadata.gz: 44ab226b002b10eec8d8bc1b8f6ffb84c92a1c5ad2a6cb491d08f7cd647acec4bd024e63806b8a3f16f524c36b8a608f11b7749fedf352e75a7ed26d81803694
-  data.tar.gz: 4ad17e1e563b1d7c8c34d098b249eb9b05fb8da335c570409dff236048a91039852f595b2a08c87e5780d6ad5b24148b9f6b999d34c2a437d1617c800a164f4b
+  metadata.gz: ea0199d84e4f2a038141178e6b0adc539c1547184d99b13ee270e971e7076e37d079f315b6d6fde4b880231a032f8463677ebc359e93ad5084974ca0bc6ad30d
+  data.tar.gz: 99e5a3c8d7bdf39ec903a7b44fb9a7d2e9c792cc405ec25b409ed8eca6f504b830b75cdf24a29271612931b79b4719f547580f61ab6f5f67aa829e74ab95bd10

data/CHANGELOG.md

@@ -1,9 +1,37 @@
 # CHANGELOG
 
-## 0.1.0 (initial)
+## 0.1.3
 
-- PTY-basierter TUI-Driver
-- ANSI-Parser (SGR Farben, Cursor, Erase, 256/Truecolor)
-- Strukturierter State als JSON
-- CLI: run, drive, capture
-- Screenshot-Funktion (ANSI → PNG via terminal-screenshot)
+- UTF-8 multi-byte character support in ANSI parser (`_utf8_char_at`)
+- `--help` is now a complete CLI reference: Examples section, interactive drive commands
+- `tui-td help test` — JSON test step reference with CLI and Ruby code workflow
+- `tui-td help rspec` — RSpec matchers reference with Driver/State setup workflow
+- `--version` flag
+
+## 0.1.2
+
+- Background reader thread — continuous PTY reads prevent buffer overflow
+- Thread-safe output buffer with Mutex protection
+- DSR (Device Status Report) support — respond to `\e[6n` cursor position requests
+- Replace `IO.select`/`readpartial` with `read_nonblock`
+
+## 0.1.1
+
+- Add `--chdir` / `-C` CLI flag for running commands in a specific directory
+- Default `capture` output to text instead of full JSON grid
+- Use `permute!` for CLI option parsing so global flags work after the command
+- Fix: skip ISO 2022 charset sequences (`ESC(B`) instead of leaking `(B` into output
+- Add `raw` field to state JSON (original ANSI with all escape sequences preserved)
+- Publish to rubygems.org
+
+## 0.1.0
+
+- PTY-based TUI driver with `start`, `send`, `send_keys`, `wait_for_text`, `wait_for_stable`
+- ANSI parser: SGR colors (16, 256, TrueColor), cursor movement, erase, scroll
+- Structured state output: `{size, cursor, rows, raw}`
+- CLI: `capture`, `run`, `drive`, `test`, `serve`
+- Pure Ruby PNG screenshots via `chunky_png` with embedded Spleen 8×16 font
+- HTML renderer with run-length encoding
+- JSON test runner with 12 step types
+- RSpec matchers: `have_text`, `have_fg`, `have_bg`, `have_style`
+- MCP server (JSON-RPC over stdio) for AI-driven TUI testing

data/README.md

@@ -1,13 +1,18 @@
 # TUI Test Drive
 
+*Like Playwright or Puppeteer, but built specifically for Terminal UIs and optimized for AI Coding Agents.*
+
 Testing framework for Terminal User Interfaces (TUIs) with MCP support.
 
+A Ruby library, but language-agnostic through its JSON test format and MCP server — use it from Python, JavaScript, Go, or any other programming language on Linux and macOS.
+
 **tui-td** lets you:
 1. Start a TUI application in a virtual terminal (PTY)
 2. See the output — as structured JSON, plain text, PNG screenshots, or HTML renders
 3. Send input — keystrokes, text, control sequences
 4. Analyze output — find text, check colors, detect cursor position
 5. Loop — adjust and retest without manual intervention
+6. Integrate — works with any language via JSON test files or MCP
 
 ## Installation
 
@@ -108,9 +113,12 @@ Global options:
   --json                Output state as compact JSON (includes raw ANSI)
   --pretty              Output state as pretty JSON
   --text                Output state as plain text table (default)
-  -h, --help            Show help
+  -h, --help            Show complete reference (commands, options, examples, interactive commands)
 ```
 
+`tui-td --help` serves as the full CLI reference. `tui-td help test` shows all JSON test
+step types and `tui-td help rspec` shows all RSpec matchers — no need to consult the docs.
+
 ## Ruby API
 
 ### Driver — Start, send, capture

data/lib/tui_td/ansi_parser.rb

@@ -92,6 +92,7 @@ module TUITD
       attrs = { fg: "default", bg: "default", bold: false, italic: false, underline: false }
       saved_cursor = nil
       scroll_region = nil
+      pending_dsr = false
 
       # Strip everything before the last full clear (if any)
       # to avoid accumulated garbage
@@ -102,10 +103,11 @@ module TUITD
         if processed[i] == "\e" && processed[i + 1] == "["
           # Find end of CSI sequence
           j = i + 2
-          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fm]/)
+          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fmnR]/)
           seq = processed[i..j]
 
-          _apply_csi(seq, cursor, attrs, grid, rows, cols)
+          dsr = _apply_csi(seq, cursor, attrs, grid, rows, cols)
+          pending_dsr ||= dsr
 
           i = j + 1
         elsif processed[i] == "\n" || processed[i] == "\r\n"
@@ -135,16 +137,16 @@ module TUITD
           else
             i += 1
           end
-        elsif processed[i] =~ /[[:print:]]/
-          # Printable character
+        elsif (char, char_len = _utf8_char_at(processed, i))
+          # Printable character (including multi-byte UTF-8)
           if cursor[:row] < rows && cursor[:col] < cols
             cell = grid[cursor[:row]][cursor[:col]]
-            cell[:char] = processed[i]
+            cell[:char] = char
             cell.merge!(attrs)
             cursor[:col] += 1
             cursor[:col] = cols - 1 if cursor[:col] >= cols
           end
-          i += 1
+          i += char_len
         else
           i += 1
         end
@@ -164,6 +166,7 @@ module TUITD
         size: { rows: rows, cols: cols },
         cursor: cursor,
         rows: grid,
+        pending_dsr: pending_dsr,
       }
     end
 
@@ -211,7 +214,7 @@ module TUITD
     def self._apply_csi(seq, cursor, attrs, grid, rows, cols)
       # Strip leading escape char if present
       cleaned = seq.sub(/^\e/, "")
-      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhm])$/)
+      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhmnR])$/)
       return unless match
 
       params = match[1].split(";").map(&:to_i)
@@ -267,6 +270,11 @@ module TUITD
           next unless cursor[:row] < rows && cursor[:col] + i < cols
           grid[cursor[:row]][cursor[:col] + i][:char] = " "
         end
+      when "n" # DSR — Device Status Report request
+        # \e[6n = request cursor position → caller must respond with \e[row;colR
+        return params[0] == 6
+      when "R" # DSR response (from terminal side) or CPR — ignore
+        nil
       end
     end
 
@@ -401,5 +409,38 @@ module TUITD
         nil
       end
     end
+
+    # Extract a single UTF-8 character at position i in a binary string.
+    # Returns [char_string, byte_length] or nil if the byte is not printable/valid.
+    def self._utf8_char_at(str, i)
+      byte = str.getbyte(i)
+      return nil unless byte
+
+      if byte < 0x80
+        # Single-byte ASCII
+        return nil unless byte >= 0x20  # only printable, skip control chars
+        return [byte.chr, 1]
+      end
+
+      # Multi-byte UTF-8
+      len = if byte & 0xE0 == 0xC0
+              2
+      elsif byte & 0xF0 == 0xE0
+              3
+      elsif byte & 0xF8 == 0xF0
+              4
+      else
+              return nil  # continuation byte or invalid — let main loop advance
+      end
+      return nil if i + len > str.bytesize
+
+      bytes = str.byteslice(i, len)
+      char = bytes.dup.force_encoding("UTF-8")
+      return nil unless char.valid_encoding?
+
+      [char, len]
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/tui_td/cli.rb

@@ -18,12 +18,29 @@ module TUITD
         opts.banner = "Usage: tui-td <command> [options]"
         opts.separator ""
         opts.separator "Commands:"
-        opts.separator "  serve             Start MCP server (JSON-RPC over stdio)"
-        opts.separator "  run <command>      Run a TUI app and show live output"
-        opts.separator "  drive <command>    Drive a TUI with structured state output"
+        opts.separator "  serve              Start MCP server (JSON-RPC over stdio)"
         opts.separator "  capture <command>  Run once, capture and display state"
-        opts.separator "  test <file>        Run JSON test file"
-        opts.separator "  help               Show this help"
+        opts.separator "  drive <command>    Drive a TUI interactively"
+        opts.separator "  run <command>      Run a TUI app and show live output"
+        opts.separator "  test <file.json>   Run JSON test file"
+        opts.separator "  help [topic]       Show this help, or help test / help rspec"
+        opts.separator ""
+        opts.separator "Examples:"
+        opts.separator "  tui-td capture \"ls -la\""
+        opts.separator "  tui-td --screenshot out.png capture \"htop\" --timeout 5"
+        opts.separator "  tui-td --html out.html capture \"glow README.md\""
+        opts.separator "  tui-td -C /my/project capture \"make test\""
+        opts.separator "  tui-td drive \"vim file.txt\" --rows 24 --cols 80"
+        opts.separator "  tui-td test examples/echo_test.json"
+        opts.separator "  tui-td serve"
+        opts.separator ""
+        opts.separator "Interactive commands (drive mode):"
+        opts.separator "  state              Show terminal state as pretty JSON"
+        opts.separator "  raw                Show raw ANSI output"
+        opts.separator "  key <name>         Send keystroke (enter, tab, escape, up, down, left, right,"
+        opts.separator "                     backspace, ctrl_c, ctrl_d)"
+        opts.separator "  <text>             Send text to the TUI"
+        opts.separator "  exit               Quit drive mode"
         opts.separator ""
         opts.separator "Global options:"
 
@@ -54,6 +71,10 @@ module TUITD
         opts.on("--text", "Output state as plain text table") do |_|
           global_opts[:format] = :text
         end
+        opts.on("--version", "Show version") do
+          puts "tui-td #{TUITD::VERSION}"
+          exit 0
+        end
         opts.on("-h", "--help", "Show help") do
           puts opts
           exit 0
@@ -74,9 +95,20 @@ module TUITD
         cmd_capture(command_opts, global_opts)
       when "test"
         cmd_test(command_opts, global_opts)
-      when nil, "help"
-        puts OptionParser.new { |o| o.banner = "Usage: tui-td <command> [options]" }
-        exit 0
+      when "help"
+        topic = argv.shift
+        case topic
+        when "test"
+          _help_test
+        when "rspec"
+          _help_rspec
+        when nil
+          _help_main
+        else
+          abort "Unknown help topic: #{topic.inspect}\nTry: tui-td help test, tui-td help rspec"
+        end
+      when nil
+        _help_main
       else
         abort "Unknown command: #{command.inspect}\nUse tui-td --help for usage"
       end
@@ -228,5 +260,130 @@ module TUITD
         puts line.empty? ? "~" : line
       end
     end
+
+    def _help_main
+      puts OptionParser.new { |o| o.banner = "Usage: tui-td <command> [options]" }
+      puts
+      puts "For more: tui-td help test   (JSON test step types)"
+      puts "          tui-td help rspec  (RSpec matchers)"
+      exit 0
+    end
+
+    def _help_test
+      puts <<~HELP
+        JSON Test Format
+        ================
+
+        Run from CLI:
+
+          tui-td test examples/echo_test.json
+
+        Or from Ruby code:
+
+          require "tui_td/test_runner"
+          runner = TUITD::TestRunner.new(name: "my test", steps: [...])
+          result = runner.run  # => { passed: true, results: [...] }
+
+        A test is a Hash or JSON string: {"name": "...", "steps": [...]}
+
+        Top-level keys: name, steps, rows (default 40), cols (default 120),
+                        timeout (default 30), chdir
+
+        Each step is an object with a single action key:
+
+          {"start": "<command>"}
+              Start a TUI process in a PTY.
+
+          {"send": "<text>"}
+              Send text to the TUI. Use "\\n" for Enter.
+
+          {"send_key": "<name>"}
+              Send a keystroke. Names: enter, tab, escape, up, down,
+              left, right, backspace, ctrl_c, ctrl_d.
+
+          {"wait_for_text": "<substring>"}
+              Wait until the given text appears in the output.
+
+          {"wait_for_stable": true}
+              Wait until the output stops changing (default 300ms quiet).
+
+          {"assert_text": "<substring>"}
+              Fail if the text is not found in the current state.
+
+          {"assert_fg": [row, col], "is": "<color>"}
+              Assert foreground color at cell. Colors: "default",
+              named ANSI (red, green, blue, cyan, ...), "bright_*",
+              "color<N>" (256-color), "#rrggbb" (TrueColor).
+
+          {"assert_bg": [row, col], "is": "<color>"}
+              Assert background color at cell. Same color format.
+
+          {"assert_style": [row, col], "bold": true, "italic": false, ...}
+              Assert style attributes at cell. Checks only the keys provided.
+
+          {"screenshot": "<path>"}
+              Save a PNG screenshot. Path defaults to /tmp/tui_td_<ts>.png.
+
+          {"html": "<path>"}
+              Save an HTML render. Path defaults to /tmp/tui_td_<ts>.html.
+
+          {"close": true}
+              Close the driver session.
+
+        Example test file: examples/echo_test.json
+      HELP
+      exit 0
+    end
+
+    def _help_rspec
+      puts <<~HELP
+        RSpec Matchers
+        ==============
+
+        Matchers work on TUITD::State objects, not raw output.
+        Get a State from the Driver:
+
+          require "tui_td"
+          require "tui_td/matchers"
+
+          driver = TUITD::Driver.new("my_tui", rows: 24, cols: 80)
+          driver.start
+          state = TUITD::State.new(driver.state_data)
+
+          expect(state).to have_text("Hello")
+          expect(state).to have_fg("red").at(0, 5)
+
+          driver.close
+
+        Or build a State manually for unit tests:
+
+          state = TUITD::State.new(
+            size: { rows: 5, cols: 20 },
+            cursor: { row: 0, col: 0 },
+            rows: [[{ char: "H", fg: "default", bg: "default",
+                      bold: false, italic: false, underline: false }]]
+          )
+
+        Matchers
+        --------
+
+        have_text(expected)
+            Passes if expected text appears anywhere in the terminal state.
+            Usage: expect(state).to have_text("Hello")
+
+        have_fg(expected).at(row, col)
+            Assert foreground color at [row, col] matches expected.
+            Usage: expect(state).to have_fg("red").at(0, 5)
+
+        have_bg(expected).at(row, col)
+            Assert background color at [row, col] matches expected.
+            Usage: expect(state).to have_bg("default").at(0, 0)
+
+        have_style.at(row, col).with(bold: true, italic: false, ...)
+            Assert style attributes at [row, col] match the given hash.
+            Usage: expect(state).to have_style.at(0, 0).with(bold: true)
+      HELP
+      exit 0
+    end
   end
 end

data/lib/tui_td/driver.rb

@@ -30,6 +30,9 @@ module TUITD
       @stdout = nil
       @wait_thr = nil
       @output_buffer = +""
+      @output_mutex = Mutex.new
+      @reader_thread = nil
+      @reader_running = false
     end
 
     # Start the TUI application in a PTY
@@ -46,6 +49,8 @@ module TUITD
       wait_for_stable
       refresh_state!
 
+      _start_reader_thread
+
       true
     end
 
@@ -81,7 +86,8 @@ module TUITD
       loop do
         raise TimeoutError, "Timeout waiting for: #{text.inspect}" if monotonic > deadline
         read_available!
-        break if @output_buffer.include?(text)
+        found = @output_mutex.synchronize { @output_buffer.include?(text) }
+        break if found
         sleep 0.05
       end
       refresh_state!
@@ -114,7 +120,7 @@ module TUITD
     # Get the terminal output (raw ANSI + text)
     def raw_output
       read_available!
-      @output_buffer
+      @output_mutex.synchronize { @output_buffer.dup }
     end
 
     # Get structured terminal state as a Hash
@@ -137,6 +143,8 @@ module TUITD
 
     # Close the driver and clean up
     def close
+      _stop_reader_thread
+
       # Kill the process if still running
       if @pid
         begin
@@ -156,6 +164,30 @@ module TUITD
 
     private
 
+    def _start_reader_thread
+      @reader_running = true
+      @reader_thread = Thread.new do
+        loop do
+          break unless @reader_running
+          begin
+            read_available!
+          rescue IOError, Errno::EIO
+            break
+          end
+          sleep 0.05
+        end
+      end
+    end
+
+    def _stop_reader_thread
+      @reader_running = false
+      if @reader_thread
+        @reader_thread.join(1)
+        @reader_thread.kill rescue nil
+        @reader_thread = nil
+      end
+    end
+
     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?
@@ -164,19 +196,35 @@ module TUITD
     def read_available!
       return false unless @stdout
 
-      ready, = IO.select([@stdout], nil, nil, 0.01)
-      return false unless ready
+      data = @stdout.read_nonblock(4096)
+
+      @output_mutex.synchronize { @output_buffer << data }
+
+      respond_to_dsr if data.include?("\e[6n")
 
-      data = @stdout.readpartial(4096)
-      @output_buffer << data
       true
-    rescue EOFError
+    rescue IO::WaitReadable, EOFError
       false
     end
 
+    def respond_to_dsr
+      @output_mutex.synchronize do
+        @state = ANSIParser.parse(@output_buffer, @rows, @cols)
+        @state[:raw] = @output_buffer.dup
+        @output_buffer.gsub!("\e[6n", "")
+
+        cursor = @state[:cursor]
+        response = "\e[#{cursor[:row] + 1};#{cursor[:col] + 1}R"
+        @stdin&.print(response)
+        @stdin&.flush
+      end
+    end
+
     def refresh_state!
-      @state = ANSIParser.parse(@output_buffer, @rows, @cols)
-      @state[:raw] = @output_buffer.dup
+      @output_mutex.synchronize do
+        @state = ANSIParser.parse(@output_buffer, @rows, @cols)
+        @state[:raw] = @output_buffer.dup
+      end
     end
 
     def monotonic

data/lib/tui_td/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TUITD
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Haluk Durmus
@@ -155,5 +155,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: TUI (Terminal User Interface) testing framework with MCP support
+summary: TUI testing framework — language-agnostic via JSON tests and MCP
 test_files: []