tui-td 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b759a458f409fc1596611c306a59a14e04be1842b6f44fff4e45eebd61f6b673
-  data.tar.gz: deb8ebbd1e4804f7874f3af677969e333cda8321fb935a287789fd166ab20a29
+  metadata.gz: be8d93991312317febcad6a713d4dd58e6e670e620211bae0adc0db0bdd21da1
+  data.tar.gz: 5618bc612addd9be3c634ebd4009800ddd6f7da9396ad5d950c8f831727398f8
 SHA512:
-  metadata.gz: ecb87f37f0af8ec853a37465aa822b4c547b389ef064579243522429c48e885b56d7fdf9d701cc7e5e08bed1adeb5d0a7a035301351531fe68806b24d15f9923
-  data.tar.gz: 53fe8549f0a04d5bf403dda60ab3016e7be26f817453693f6fda68288a926bf89bdd6a86dc858e624a5f4e7ed618d1c8adc1b1e545dedf9fdf2d0926bcfa2543
+  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

@@ -113,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

@@ -137,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
@@ -409,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TUITD
-  VERSION = "0.1.2"
+  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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Haluk Durmus