shoko 0.1.0

data/lib/shoko/adapters/output/terminal/input.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require_relative 'constants/terminal_defaults'
+require_relative 'input/decoder'
+
+module Shoko
+  module Adapters::Output::Terminal
+    # TerminalInput encapsulates input reading, console modes, and size queries.
+    class TerminalInput
+      SIZE_CACHE_INTERVAL = 0.5
+      READ_CHUNK_BYTES = 4096
+
+      def initialize(input: $stdin, output: $stdout, esc_timeout: Decoder::DEFAULT_ESC_TIMEOUT,
+                     sequence_timeout: Decoder::DEFAULT_SEQUENCE_TIMEOUT)
+        @console = nil
+        @size_cache = { width: nil, height: nil, checked_at: nil }
+        @input = input
+        @output = output
+        @decoder = Decoder.new(esc_timeout: esc_timeout, sequence_timeout: sequence_timeout)
+      end
+
+      def size
+        update_size_cache if cache_expired?
+        [@size_cache[:height], @size_cache[:width]]
+      end
+
+      def setup_console
+        $stdout.sync = true
+        @console = resolve_console
+        @console.raw! if @console.respond_to?(:raw!)
+      end
+
+      def cleanup_console
+        @console.cooked! if @console.respond_to?(:cooked!)
+        @console = nil
+      end
+
+      def with_raw_console(&)
+        console = resolve_console
+        console.raw(&)
+      end
+
+      def read_key
+        with_raw_console do
+          pump_input
+          @decoder.next_token(now: monotonic_now)
+        end
+      rescue IO::WaitReadable, EOFError
+        nil
+      end
+
+      def read_key_blocking(timeout: nil)
+        deadline = timeout ? monotonic_now + timeout.to_f : nil
+        loop do
+          key = read_key
+          return key if key
+
+          now = monotonic_now
+          remaining = deadline ? (deadline - now) : nil
+          return nil if remaining && remaining <= 0
+
+          pending = @decoder.pending_timeout(now: now)
+          wait = if pending && remaining
+                   [pending, remaining].min
+                 else
+                   pending || remaining
+                 end
+
+          if wait
+            next if wait <= 0
+
+            @input.wait_readable(wait)
+          else
+            @input.wait_readable
+          end
+        end
+      end
+
+      # Mouse support
+      def enable_mouse
+        @output.print "\e[?1002h\e[?1006h"
+        @output.flush
+      end
+
+      def disable_mouse
+        @output.print "\e[?1002l\e[?1006l"
+        @output.flush
+      end
+
+      def read_input_with_mouse(timeout: nil)
+        read_key_blocking(timeout: timeout)
+      end
+
+      def setup_signal_handlers(&cleanup_callback)
+        %w[INT TERM].each do |signal|
+          trap(signal) do
+            cleanup_callback&.call
+            exit(0)
+          end
+        end
+      end
+
+      private
+
+      def cache_expired?
+        now = Time.now
+        checked = @size_cache[:checked_at]
+        checked.nil? || now - checked > SIZE_CACHE_INTERVAL
+      end
+
+      def update_size_cache
+        h, w = fetch_terminal_size
+        @size_cache = { width: w, height: h, checked_at: Time.now }
+      end
+
+      def fetch_terminal_size
+        IO.console.winsize
+      rescue StandardError
+        default_dimensions
+      end
+
+      def default_dimensions
+        [Adapters::Output::Terminal::TerminalDefaults::DEFAULT_ROWS,
+         Adapters::Output::Terminal::TerminalDefaults::DEFAULT_COLUMNS]
+      end
+
+      def resolve_console
+        return @console if @console
+
+        console = IO.console
+        if console
+          @console = console
+          return console
+        end
+
+        if @input.respond_to?(:tty?) && @input.tty? && @input.respond_to?(:raw)
+          @console = @input
+          return @input
+        end
+
+        raise Shoko::TerminalUnavailableError
+      end
+
+      def pump_input
+        loop do
+          chunk = @input.read_nonblock(READ_CHUNK_BYTES)
+          @decoder.feed(chunk)
+        end
+      rescue IO::WaitReadable, EOFError
+        nil
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      rescue StandardError
+        Time.now.to_f
+      end
+    end
+  end
+end

data/lib/shoko/adapters/output/terminal/output.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'io/console'
+
+module Shoko
+  module Adapters::Output::Terminal
+    # TerminalOutput handles ANSI sequences and direct writes to an IO stream.
+    class TerminalOutput
+    attr_reader :io
+
+    def initialize(io = $stdout)
+      @io = io
+    end
+
+    # A collection of ANSI escape codes and helpers
+    module ANSI
+      RESET = "\e[0m"
+      BOLD = "\e[1m"
+      DIM = "\e[2m"
+      ITALIC = "\e[3m"
+      REVERSE = "\e[7m"
+
+      BLACK = "\e[30m"
+      RED = "\e[31m"
+      GREEN = "\e[32m"
+      YELLOW = "\e[33m"
+      BLUE = "\e[34m"
+      MAGENTA = "\e[35m"
+      CYAN = "\e[36m"
+      WHITE = "\e[37m"
+      GRAY = "\e[90m"
+      LIGHT_GREY = "\e[37;1m"
+
+      BRIGHT_RED = "\e[91m"
+      BRIGHT_GREEN = "\e[92m"
+      BRIGHT_YELLOW = "\e[93m"
+      BRIGHT_BLUE = "\e[94m"
+      BRIGHT_MAGENTA = "\e[95m"
+      BRIGHT_CYAN = "\e[96m"
+      BRIGHT_WHITE = "\e[97m"
+
+      BG_DARK = "\e[48;5;236m"
+      BG_BLACK = "\e[40m"
+      BG_BLUE = "\e[44m"
+      BG_CYAN = "\e[46m"
+      BG_GREY = "\e[48;5;240m"
+      BG_SLATE = "\e[48;5;238m"
+      BG_SOFT_GREEN = "\e[48;5;65m"
+      BG_BRIGHT_GREEN = "\e[102m"
+      BG_BRIGHT_YELLOW = "\e[103m"
+      BG_BRIGHT_WHITE = "\e[107m"
+
+      module Control
+        CLEAR = "\e[2J"
+        HOME = "\e[H"
+        HIDE_CURSOR = "\e[?25l"
+        SHOW_CURSOR = "\e[?25h"
+        SAVE_SCREEN = "\e[?1049h"
+        RESTORE_SCREEN = "\e[?1049l"
+      end
+
+      def self.move(row, col)
+        "\e[#{row};#{col}H"
+      end
+
+      def self.clear_line
+        "\e[2K"
+      end
+
+      def self.clear_below
+        "\e[J"
+      end
+    end
+
+    def print(str)
+      io.print(str)
+    end
+
+    def flush
+      io.flush
+    end
+
+    def clear
+      print(ANSI::Control::CLEAR + ANSI::Control::HOME)
+      flush
+    end
+
+    def hide_cursor
+      print(ANSI::Control::HIDE_CURSOR)
+    end
+
+    def show_cursor
+      print(ANSI::Control::SHOW_CURSOR)
+    end
+
+    def save_screen
+      print(ANSI::Control::SAVE_SCREEN)
+    end
+
+    def restore_screen
+      print(ANSI::Control::RESTORE_SCREEN)
+    end
+    end
+  end
+end

data/lib/shoko/adapters/output/terminal/terminal.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require_relative 'constants/terminal_defaults'
+require_relative 'output'
+require_relative 'buffer'
+require_relative 'input'
+
+module Shoko
+  module Adapters::Output::Terminal
+    # Facade that preserves the historical Terminal API
+    # while delegating to composable, testable components:
+    # - TerminalOutput
+    # - TerminalBuffer
+    # - TerminalInput
+    class Terminal
+      # Keep ANSI nested under Terminal for compatibility
+      ANSI = TerminalOutput::ANSI
+
+      # Defines constants for special keyboard keys to abstract away different
+      # terminal escape codes.
+      module Keys
+        UP = ["\e[A", "\eOA", 'k'].freeze
+        DOWN = ["\e[B", "\eOB", 'j'].freeze
+        ENTER = ["\r", "\n"].freeze
+        ESCAPE = ["\e", "\x1B", 'q'].freeze
+      end
+
+      @output = TerminalOutput.new($stdout)
+      @buffer_manager = TerminalBuffer.new(@output)
+      @input = TerminalInput.new
+      @buffer = @buffer_manager.buffer
+
+      class << self
+        # Expose a print wrapper for backward-compatible expectations in tests
+        def print(str)
+          @output.print(str)
+        end
+
+        def size
+          @input.size
+        end
+
+        def clear
+          print [ANSI::Control::CLEAR, ANSI::Control::HOME].join
+          clear_buffer_cache
+          $stdout.flush
+        end
+
+        def move(row, col)
+          # Historically this only queued the move; keep parity
+          @buffer << ANSI.move(row, col)
+        end
+
+        def write(row, col, text)
+          @buffer_manager.write(row, col, text)
+        end
+
+        def write_differential(row, col, text)
+          @buffer_manager.write_differential(row, col, text)
+        end
+
+        def clear_buffer_cache
+          @buffer_manager.clear_buffer_cache
+        end
+
+        def batch_write(&)
+          @buffer_manager.batch_write(&)
+        end
+
+        def start_frame(width: nil, height: nil)
+          if width && height
+            w = width.to_i
+            h = height.to_i
+          else
+            h, w = size
+          end
+
+          @buffer_manager.start_frame(width: w, height: h)
+          @buffer = @buffer_manager.buffer
+        end
+
+        def end_frame
+          @buffer_manager.end_frame
+        end
+
+        # Queue raw control sequences (e.g., Kitty graphics) for the current frame.
+        # These are emitted before any row diffs.
+        def raw(text)
+          @buffer_manager.raw(text)
+        end
+
+        def setup
+          @input.setup_console
+          print ANSI::Control::SAVE_SCREEN
+          print ANSI::Control::HIDE_CURSOR
+          print ANSI::BG_DARK
+          clear
+          @input.setup_signal_handlers { cleanup }
+        end
+
+        def cleanup
+          print([
+            ANSI::Control::CLEAR,
+            ANSI::Control::HOME,
+            ANSI::Control::SHOW_CURSOR,
+            ANSI::Control::RESTORE_SCREEN,
+            ANSI::RESET,
+          ].join)
+          @output.flush
+          @input.cleanup_console
+        end
+
+        def read_key
+          @input.read_key
+        end
+
+        def read_key_blocking(timeout: nil)
+          @input.read_key_blocking(timeout: timeout)
+        end
+
+        def enable_mouse
+          @input.enable_mouse
+        end
+
+        def disable_mouse
+          @input.disable_mouse
+        end
+
+        def read_input_with_mouse(timeout: nil)
+          @input.read_input_with_mouse(timeout: timeout)
+        end
+
+        def setup_signal_handlers(&cleanup_callback)
+          @input.setup_signal_handlers(&cleanup_callback)
+        end
+
+        def buffer
+          @buffer
+        end
+
+        def buffer_manager
+          @buffer_manager
+        end
+
+        def output
+          @output
+        end
+
+        def input
+          @input
+        end
+
+        def reset!
+          @output = TerminalOutput.new($stdout)
+          @buffer_manager = TerminalBuffer.new(@output)
+          @input = TerminalInput.new
+          @buffer = @buffer_manager.buffer
+        end
+      end
+    end
+  end
+end
+
+module Shoko
+  Terminal = Adapters::Output::Terminal::Terminal
+end

data/lib/shoko/adapters/output/terminal/terminal_sanitizer.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters
+    module Output
+      module Terminal
+        # Sanitizes untrusted text before it is rendered in a terminal.
+        #
+        # Removes ANSI/VT control sequences (OSC/DCS/CSI/etc.) and drops C0/C1 control
+        # characters to prevent terminal escape injection and layout corruption.
+        module TerminalSanitizer
+      module_function
+
+      # Pre-sanitizer for XML/XHTML sources before feeding them to an XML parser.
+      #
+      # Some EPUBs (and malicious inputs) include numeric character references to
+      # disallowed control characters (e.g. `` / ``), which can cause
+      # REXML to raise parse errors. To keep parsing resilient, this method:
+      # - Decodes *numeric* references for C0/C1/DEL into real codepoints so the
+      #   control-sequence scanner can remove the entire escape sequence.
+      # - Drops numeric references to codepoints that are invalid in XML 1.0.
+      #
+      # It intentionally does not decode non-control references (e.g. `<`)
+      # because doing so can change document structure before parsing.
+      def sanitize_xml_source(text, preserve_newlines: true, preserve_tabs: true)
+        return '' if text.nil?
+
+        str = coerce_utf8(String(text))
+        return '' if str.empty?
+
+        pre = decode_control_numeric_references(str)
+        sanitize(pre, preserve_newlines: preserve_newlines, preserve_tabs: preserve_tabs)
+      rescue StandardError
+        sanitize(text.to_s, preserve_newlines: preserve_newlines, preserve_tabs: preserve_tabs)
+      end
+
+      # @param text [String,nil]
+      # @param preserve_newlines [Boolean] keep `\n` (and normalize `\r` to `\n`)
+      # @param preserve_tabs [Boolean] keep `\t`
+      # @return [String] UTF-8 string safe for terminal rendering
+      def sanitize(text, preserve_newlines: false, preserve_tabs: false)
+        return '' if text.nil?
+
+        str = String(text)
+        return '' if str.empty?
+
+        str = coerce_utf8(str)
+        cps = str.codepoints
+        return '' if cps.empty?
+
+        out = +''
+        out.force_encoding(Encoding::UTF_8)
+
+        i = 0
+        while i < cps.length
+          cp = cps[i]
+
+          case cp
+          when 0x1B # ESC
+            i = skip_esc_sequence(cps, i + 1)
+            next
+          when 0x9B # CSI (8-bit)
+            i = skip_csi_sequence(cps, i + 1)
+            next
+          when 0x9D # OSC (8-bit)
+            i = skip_osc_sequence(cps, i + 1, c1_variant: true)
+            next
+          when 0x90, 0x98, 0x9E, 0x9F # DCS, SOS, PM, APC (8-bit)
+            i = skip_string_sequence(cps, i + 1, c1_variant: true)
+            next
+          end
+
+          if cp == 0x0A # \n
+            out << (preserve_newlines ? "\n" : ' ')
+            i += 1
+            next
+          end
+
+          if cp == 0x0D # \r
+            out << (preserve_newlines ? "\n" : ' ')
+            i += 1
+            next
+          end
+
+          if cp == 0x09 # \t
+            out << (preserve_tabs ? "\t" : ' ')
+            i += 1
+            next
+          end
+
+          if control_codepoint?(cp)
+            i += 1
+            next
+          end
+
+          out << cp
+          i += 1
+        end
+
+        out
+      rescue StandardError
+        String(text).encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+      end
+
+      # Input filter for single-character text entry (search fields, editors).
+      # Prevents inserting C0/C1 control characters and DEL.
+      def printable_char?(key)
+        return false unless key.is_a?(String)
+        return false unless key.length == 1
+
+        cp = key.ord
+        return false if cp < 0x20
+        return false if cp == 0x7F
+        return false if cp.between?(0x80, 0x9F)
+
+        true
+      rescue StandardError
+        false
+      end
+
+      def coerce_utf8(str)
+        return str if str.encoding == Encoding::UTF_8 && str.valid_encoding?
+
+        str.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+      rescue StandardError
+        str.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+      end
+      private_class_method :coerce_utf8
+
+      def control_codepoint?(codepoint)
+        return true if codepoint < 0x20
+        return true if codepoint == 0x7F
+        return true if codepoint.between?(0x80, 0x9F)
+
+        false
+      end
+      private_class_method :control_codepoint?
+
+      def skip_esc_sequence(codepoints, index)
+        return codepoints.length if index >= codepoints.length
+
+        lead = codepoints[index]
+        case lead
+        when 0x5B # '[' CSI
+          skip_csi_sequence(codepoints, index + 1)
+        when 0x5D # ']' OSC
+          skip_osc_sequence(codepoints, index + 1, c1_variant: false)
+        when 0x50, 0x58, 0x5E, 0x5F # 'P' DCS, 'X' SOS, '^' PM, '_' APC
+          skip_string_sequence(codepoints, index + 1, c1_variant: false)
+        else
+          # 2-byte escape sequence (ESC + final byte)
+          index + 1
+        end
+      end
+      private_class_method :skip_esc_sequence
+
+      def skip_csi_sequence(codepoints, index)
+        while index < codepoints.length
+          cp = codepoints[index]
+          index += 1
+          # Final byte is 0x40..0x7E
+          break if cp.between?(0x40, 0x7E)
+        end
+        index
+      end
+      private_class_method :skip_csi_sequence
+
+      def skip_osc_sequence(codepoints, index, c1_variant:)
+        while index < codepoints.length
+          cp = codepoints[index]
+
+          return index + 1 if cp == 0x07 # BEL
+
+          return index + 2 if !c1_variant && cp == 0x1B && codepoints[index + 1] == 0x5C # ESC \
+
+          return index + 1 if c1_variant && cp == 0x9C # ST (8-bit)
+
+          # Allow ESC \ as terminator even for 8-bit variants (robustness).
+          return index + 2 if cp == 0x1B && codepoints[index + 1] == 0x5C
+
+          index += 1
+        end
+        index
+      end
+      private_class_method :skip_osc_sequence
+
+      def skip_string_sequence(codepoints, index, c1_variant:)
+        while index < codepoints.length
+          cp = codepoints[index]
+
+          return index + 1 if c1_variant && cp == 0x9C # ST
+
+          return index + 2 if cp == 0x1B && codepoints[index + 1] == 0x5C # ESC \
+
+          index += 1
+        end
+        index
+      end
+      private_class_method :skip_string_sequence
+
+      def decode_control_numeric_references(str)
+        # Hex numeric references
+        out = str.gsub(/&#x([0-9A-Fa-f]+);/) do |match|
+          cp = Regexp.last_match(1).to_i(16)
+          replacement_for_xml_numeric_ref(cp, match)
+        end
+
+        # Decimal numeric references
+        out.gsub(/&#(\d+);/) do |match|
+          cp = Regexp.last_match(1).to_i
+          replacement_for_xml_numeric_ref(cp, match)
+        end
+      end
+      private_class_method :decode_control_numeric_references
+
+      def replacement_for_xml_numeric_ref(codepoint, original)
+        return '' unless codepoint.is_a?(Integer)
+
+        # Decode control characters so the escape-sequence scanner can remove the
+        # full sequence (e.g. ESC + '[' + ... + 'm').
+        return [codepoint].pack('U') if codepoint < 0x20 || codepoint == 0x7F || codepoint.between?(0x80, 0x9F)
+
+        # Drop codepoints that are not valid in XML 1.0.
+        xml_allowed_codepoint?(codepoint) ? original : ''
+      rescue StandardError
+        ''
+      end
+      private_class_method :replacement_for_xml_numeric_ref
+
+      def xml_allowed_codepoint?(codepoint)
+        return true if [0x09, 0x0A, 0x0D].include?(codepoint)
+        return true if codepoint.between?(0x20, 0xD7FF)
+        return true if codepoint.between?(0xE000, 0xFFFD)
+        return true if codepoint.between?(0x10000, 0x10FFFF)
+
+        false
+      end
+      private_class_method :xml_allowed_codepoint?
+        end
+      end
+    end
+  end
+end