tui-td 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45c5b163ff48383823bccd9c0b9efe73f5a37b009c2e0968fb2619dea4c87d51
-  data.tar.gz: '01885208a25d500718f786fb66bc2b0753b2b0ff720cf6ed39c9380c9f1d13bf'
+  metadata.gz: b759a458f409fc1596611c306a59a14e04be1842b6f44fff4e45eebd61f6b673
+  data.tar.gz: deb8ebbd1e4804f7874f3af677969e333cda8321fb935a287789fd166ab20a29
 SHA512:
-  metadata.gz: d4887b9af284ee25b16236b8e4a0aad6eadbb1c8583d14119630250749d3d9fce45a138321f50eb2b59e7de0ea107b34d33461da62113d6b1a76e4f8d789b698
-  data.tar.gz: c435e9556f67254b627c2b7ff21199489b9991bd37e06eb5f1e609a4b99414917a6d731776434a0c42af53e7d362103caf203020200feb79328e310077e53903
+  metadata.gz: ecb87f37f0af8ec853a37465aa822b4c547b389ef064579243522429c48e885b56d7fdf9d701cc7e5e08bed1adeb5d0a7a035301351531fe68806b24d15f9923
+  data.tar.gz: 53fe8549f0a04d5bf403dda60ab3016e7be26f817453693f6fda68288a926bf89bdd6a86dc858e624a5f4e7ed618d1c8adc1b1e545dedf9fdf2d0926bcfa2543

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
 
@@ -43,8 +48,7 @@ brew install ruby
 ### 2. Install tui-td
 
 ```bash
-curl -sL https://github.com/vurte/tui-td/releases/download/v0.1.0/tui-td-0.1.0.gem -o tui-td.gem
-gem install tui-td.gem && rm tui-td.gem
+gem install tui-td
 ```
 
 ### 3. Test

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"
@@ -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
 

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.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tui-td
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Haluk Durmus
@@ -107,9 +107,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.50'
-description: tui-td is a Ruby framework for testing terminal UIs. It drives TUIs in
-  a PTY, captures ANSI state (colors, layout, cursor), and outputs structured data
-  that AI models can understand. Supports screenshot rendering for vision model consumption.
+description: tui-td drives terminal applications in a PTY, captures ANSI state as
+  structured data, and provides PNG screenshots and HTML renders. Includes an MCP
+  server for AI-driven testing, a JSON test runner, and RSpec matchers.
 email:
 - haluk_durmus@yahoo.de
 executables:
@@ -155,5 +155,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: AI-friendly TUI (Terminal User Interface) testing framework
+summary: TUI testing framework — language-agnostic via JSON tests and MCP
 test_files: []