tty-command-window 0.1.0

data/lib/tty/command/window/input_router.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module TTY
+  class Command
+    module Window
+      # Routes keyboard input to interactive windows.
+      #
+      # While at least one interactive block is attached, the process's stdin
+      # is switched into raw mode and every keystroke is forwarded to the
+      # focused block's PTY. Ctrl-O cycles focus between interactive blocks.
+      #
+      # Note: in raw mode Ctrl-C is delivered to the focused child as a byte
+      # (0x03), not as SIGINT to the host process.
+      #
+      # Thread-ownership:
+      # * The class methods {.attach}/{.detach} are serialized by the class
+      #   mutex and provide the process-global singleton contract.
+      # * The instance methods that mutate or read +@entries+ / +@focus_index+
+      #   hold +@state_mutex+; the router thread takes the same mutex when it
+      #   forwards or cycles focus, so a concurrent add/remove cannot race
+      #   the reader (see review H7).
+      # * On emergency termination (SIGTERM/SIGHUP/at_exit) the terminal is
+      #   restored from a saved +stty -g+ snapshot; see review H4/P0-5.
+      class InputRouter
+        FOCUS_KEY = "\x0f" # Ctrl-O
+
+        # One attached interactive window: the block that owns the focus
+        # flag, the session keystrokes are written to, and the coordinator
+        # to repaint on focus changes.
+        Entry = Struct.new(:block, :session, :coordinator)
+
+        @instance = nil
+        @mutex = Mutex.new
+        @saved_termios = nil
+        @emergency_installed = false
+
+        class << self
+          attr_accessor :saved_termios
+
+          # Attach an interactive block; starts the router on first attach.
+          #
+          # @param block [Block] the view that owns the focus flag
+          # @param session [ChildSession] where keystrokes are written
+          # @param coordinator [Coordinator] repaint sink
+          def attach(block, session, coordinator)
+            return unless $stdin.tty?
+
+            @mutex.synchronize do
+              @instance ||= new
+              @instance.add(block, session, coordinator)
+            end
+          end
+
+          # Detach a block; stops the router when none remain.
+          #
+          # Holds +@mutex+ across +shutdown+ so a concurrent {.attach}
+          # cannot construct a replacement router while the old one is
+          # still joining its thread and closing its wake pipes — which
+          # would race the class-level +@saved_termios+ slot and let
+          # +emergency_restore+ wipe the new router's snapshot
+          # (follow-up review P1-5).
+          def detach(block)
+            @mutex.synchronize do
+              next unless @instance
+
+              @instance.remove(block)
+              if @instance.empty?
+                @instance.shutdown
+                @instance = nil
+              end
+            end
+          end
+
+          # Restore the terminal to whatever mode it was in before we
+          # switched it into raw. Safe to call from at_exit or a signal
+          # handler. Idempotent.
+          def emergency_restore
+            saved = @saved_termios
+            return unless saved && !saved.empty?
+
+            @saved_termios = nil
+            system("stty", saved, in: "/dev/tty", err: File::NULL, out: File::NULL)
+          rescue StandardError
+            nil
+          end
+
+          # Install the emergency-restore hooks (at_exit + SIGTERM/SIGHUP)
+          # exactly once per process.
+          def install_emergency_hooks
+            @mutex.synchronize do
+              return if @emergency_installed
+
+              @emergency_installed = true
+              at_exit { InputRouter.emergency_restore }
+              @termios_sub = ->(_sig) { InputRouter.emergency_restore }
+              TrapManager.subscribe("TERM", @termios_sub)
+              TrapManager.subscribe("HUP", @termios_sub)
+              TrapManager.subscribe("INT", @termios_sub)
+            end
+          end
+
+          # @api private for tests
+          def capture_termios
+            out = `stty -g < /dev/tty 2>/dev/null`.chomp
+            out.empty? ? nil : out
+          rescue StandardError
+            nil
+          end
+        end
+
+        def initialize
+          @entries = [] # [Entry, ...]
+          @focus_index = 0
+          @wake_read, @wake_write = IO.pipe
+          @running = false
+          @thread = nil
+          @state_mutex = Mutex.new
+        end
+
+        def add(block, session, coordinator)
+          @state_mutex.synchronize do
+            @entries << Entry.new(block, session, coordinator)
+            refocus_locked(@entries.length - 1) if @entries.length == 1
+          end
+          start unless @running
+          repaint_all
+        end
+
+        def remove(block)
+          removed = false
+          @state_mutex.synchronize do
+            index = @entries.index { |entry| entry.block.equal?(block) }
+            next unless index
+
+            @entries.delete_at(index)
+            block.focused = false
+            removed = true
+            refocus_locked(@focus_index % @entries.length) unless @entries.empty?
+          end
+          repaint_all if removed && !empty?
+        end
+
+        # @return [Boolean] true when no blocks are attached
+        def empty?
+          @state_mutex.synchronize { @entries.empty? }
+        end
+
+        # Stop the router thread, join it, close pipes. Idempotent.
+        def shutdown
+          @running = false
+          begin
+            @wake_write.write("x")
+          rescue IOError, Errno::EPIPE
+            nil
+          end
+          thread = @thread
+          thread&.join(1)
+          @thread = nil
+          [@wake_write, @wake_read].each do |io|
+            io.close
+          rescue IOError
+            nil
+          end
+          self.class.emergency_restore
+        end
+
+        private
+
+        def start
+          self.class.install_emergency_hooks
+          self.class.saved_termios ||= self.class.capture_termios
+          @running = true
+          @thread = Thread.new { run }
+          @thread.name = "tty-command-window-input"
+        end
+
+        def run
+          $stdin.raw(intr: false) do
+            while @running
+              ready = IO.select([$stdin, @wake_read])
+              next unless ready
+
+              drain_wake_pipe if ready[0].include?(@wake_read)
+              break unless @running
+
+              forward($stdin.read_nonblock(4096)) if ready[0].include?($stdin)
+            end
+          end
+        rescue IOError, Errno::EIO
+          nil
+        ensure
+          # Belt-and-braces restore: raw's block form already restores, but
+          # if the thread is killed asynchronously (Thread#kill or ensure
+          # skipped on interpreter exit) this line will not run — the
+          # emergency hooks installed via install_emergency_hooks cover
+          # that path.
+          @thread = nil
+        end
+
+        def drain_wake_pipe
+          @wake_read.read_nonblock(64)
+        rescue IO::WaitReadable, EOFError
+          nil
+        end
+
+        # Split input on the focus key: keystrokes go to the focused block,
+        # each focus-key occurrence advances focus.
+        def forward(data)
+          segments = data.split(FOCUS_KEY, -1)
+          segments.each_with_index do |segment, index|
+            write_focused(segment) unless segment.empty?
+            cycle_focus if index < segments.length - 1
+          end
+        end
+
+        def write_focused(segment)
+          entry = @state_mutex.synchronize { @entries[@focus_index] }
+          entry.session.write(segment) if entry&.block&.running?
+        end
+
+        def cycle_focus
+          moved = false
+          @state_mutex.synchronize do
+            next if @entries.length < 2
+
+            refocus_locked((@focus_index + 1) % @entries.length)
+            moved = true
+          end
+          repaint_all if moved
+        end
+
+        # Must be called with @state_mutex held.
+        def refocus_locked(index)
+          @entries.each { |entry| entry.block.focused = false }
+          @focus_index = index
+          block = @entries[@focus_index]&.block
+          block.focused = true if block
+        end
+
+        def repaint_all
+          coordinators = @state_mutex.synchronize { @entries.map(&:coordinator) }
+          coordinators.each(&:mark_dirty)
+        end
+      end
+    end
+  end
+end

data/lib/tty/command/window/integration.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      # Adds {#run_windowed} and {#run_windowed!} to +TTY::Command+.
+      module Integration
+        # Run a command inside a live, fixed-height terminal window and raise
+        # +TTY::Command::ExitError+ on failure (mirrors +TTY::Command#run+).
+        #
+        # The child runs in a PTY reporting +lines:+ rows, so cursor-driven
+        # programs lay themselves out for the window height. Output is
+        # interpreted by a terminal emulator and painted as a static block.
+        #
+        # When stdout is not a TTY (or on Windows, or without PTY support)
+        # the call degrades to a plain +run+ with full streamed output —
+        # unless +on_unavailable: :raise+ is set, in which case
+        # {TTY::Command::Window::Unavailable} is raised instead.
+        #
+        # @note Under windowed rendering the child runs in a PTY, so its
+        #   stderr is merged into +Result#out+ at the OS level;
+        #   +Result#err+ is always +""+ (compare the plain +run+, where
+        #   stderr is a separate stream). If you must inspect stderr
+        #   independently, use +run+ / +run!+ or set +on_unavailable:
+        #   :raise+ and handle both branches.
+        #
+        # @example
+        #   cmd = TTY::Command.new(printer: :null)
+        #   cmd.run_windowed("docker compose up -d", lines: 5)
+        #
+        # @param args [Array] command, arguments and options as for +#run+,
+        #   plus the window options below
+        # @option args [Integer] :lines window height (default 5)
+        # @option args [String, false] :title title bar text; false hides it
+        # @option args [Symbol] :on_exit :freeze (default), :dump_on_failure
+        #   or :collapse
+        # @option args [Integer] :scrollback plain-text history limit
+        #   (default 10_000 lines)
+        # @option args [String] :output_log tee raw child output to this file
+        # @option args [Boolean] :interactive forward keystrokes to the child
+        #   (Ctrl-O cycles focus between interactive windows)
+        # @option args [Symbol] :capture what Result#out contains — :raw
+        #   (default), :stripped or :screen
+        # @option args [Integer, nil] :capture_max_bytes cap on the raw
+        #   bytes retained for +Result#out+ (default 10 MiB); when the
+        #   child produces more, the head is dropped and only the trailing
+        #   +capture_max_bytes+ are kept. +nil+ disables the cap.
+        #   Ignored for +capture: :screen+, which retains no raw stream.
+        # @option args [IO] :output render target (default: printer output)
+        # @option args [Boolean] :window force (+true+) or forbid (+false+)
+        #   windowed rendering, overriding TTY / PTY / Windows detection
+        # @option args [Symbol] :on_unavailable :fallback (default) silently
+        #   degrades to plain +run+ when the environment cannot render a
+        #   window; :raise raises {TTY::Command::Window::Unavailable}
+        # @option args [Integer] :width fixed render width override
+        #
+        # @yield [chunk, nil] streamed raw output, like +#run+
+        # @return [TTY::Command::Result]
+        def run_windowed(*args, &)
+          execute_windowed(args, raise_on_error: true, &)
+        end
+
+        # Same as {#run_windowed} but never raises on non-zero exit.
+        #
+        # @return [TTY::Command::Result]
+        def run_windowed!(*args, &)
+          execute_windowed(args, raise_on_error: false, &)
+        end
+
+        private
+
+        def execute_windowed(args, raise_on_error:, &block)
+          window_options, plain_args = Window.split_options(args)
+          Window.apply_tty_alias!(window_options)
+          Window.validate_on_unavailable!(window_options)
+          output = window_options[:output] || printer.output
+
+          unless windowed_renderable?(window_options, output)
+            if window_options.fetch(:on_unavailable, :fallback) == :raise
+              raise Window::Unavailable,
+                    "windowed rendering unavailable " \
+                    "(no TTY / PTY, on Windows, or dry-run)"
+            end
+            return raise_on_error ? run(*plain_args, &block) : run!(*plain_args, &block)
+          end
+
+          cmd = build_cmd(plain_args)
+          options = Window.normalize_options(window_options, cmd)
+          coordinator = Coordinator.for(output, width: window_options[:width])
+          result = Runner.new(cmd, options, coordinator, &block).run!
+
+          raise ExitError.new(cmd.to_command, result) if raise_on_error && result.failure?
+
+          result
+        end
+
+        # BOUNDARY: this call relies on +TTY::Command#command+, which is
+        # marked +@api private+ upstream. Reimplementing tty-command's
+        # argument parsing would couple us to more internals than we save,
+        # so we accept the dependency — but funnel it through this single
+        # named seam so an upstream shape change lands here, and nowhere
+        # else.
+        def build_cmd(plain_args)
+          command(*plain_args)
+        end
+
+        def windowed_renderable?(window_options, output)
+          return false if dry_run?
+
+          case window_options[:window]
+          when true then !Window.windows? && Window.pty_available?
+          when false then false
+          else Window.renderable?(output)
+          end
+        end
+      end
+
+      class << self
+        # Extract window-specific keys from a trailing options hash.
+        #
+        # @param args [Array] raw run_windowed arguments
+        # @return [Array(Hash, Array)] window options and cleaned args
+        def split_options(args)
+          return [{}, args] unless args.last.respond_to?(:to_hash)
+
+          options = args.last.to_hash
+          window_options = options.slice(*OPTION_KEYS)
+          remaining = options.except(*OPTION_KEYS)
+          plain_args = args[0..-2]
+          plain_args << remaining unless remaining.empty?
+          [window_options, plain_args]
+        end
+
+        # Translate the legacy +tty:+ key into +window:+ with a one-time
+        # deprecation warning. Preserves compatibility with pre-rename
+        # callers for one minor version.
+        #
+        # @api private
+        # @param window_options [Hash] mutated in place
+        def apply_tty_alias!(window_options)
+          return unless window_options.key?(:tty)
+
+          value = window_options.delete(:tty)
+          return if window_options.key?(:window)
+
+          warn_tty_deprecation
+          window_options[:window] = value
+        end
+
+        # Fail fast on typos / unsupported values for +on_unavailable:+
+        # (see follow-up review P0-4).
+        #
+        # @api private
+        def validate_on_unavailable!(window_options)
+          return unless window_options.key?(:on_unavailable)
+
+          mode = window_options[:on_unavailable]
+          return if ON_UNAVAILABLE_MODES.include?(mode)
+
+          raise ArgumentError,
+                "on_unavailable must be one of #{ON_UNAVAILABLE_MODES.join(', ')}"
+        end
+
+        # Validate and default the window options.
+        #
+        # @param window_options [Hash]
+        # @param cmd [TTY::Command::Cmd]
+        # @return [WindowOptions]
+        def normalize_options(window_options, cmd)
+          WindowOptions.build(window_options, cmd)
+        end
+
+        # Install the at_exit cursor-restore hook once.
+        def register_at_exit
+          return if @at_exit_registered
+
+          @at_exit_registered = true
+          at_exit { Coordinator.restore_all }
+        end
+
+        private
+
+        def warn_tty_deprecation
+          @tty_deprecation_warned ||= false
+          return if @tty_deprecation_warned
+
+          @tty_deprecation_warned = true
+          warn "[tty-command-window] `tty:` is deprecated; use `window:` instead."
+        end
+      end
+    end
+
+    include Window::Integration
+  end
+end

data/lib/tty/command/window/runner.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module TTY
+  class Command
+    module Window
+      # Spawns the child inside a PTY sized to the window, pumps its output
+      # into the block's emulator (and optional log/stream targets), enforces
+      # timeouts and builds the final +TTY::Command::Result+.
+      class Runner
+        READ_CHUNK = 64 * 1024
+        SELECT_INTERVAL = 0.25
+
+        # Post-pump reap budget. If the master closes but the child does
+        # not exit promptly (e.g. it double-forked or closed its stdio and
+        # kept running), we escalate to SIGKILL after this many seconds
+        # rather than blocking the caller forever.
+        REAP_DEADLINE = 2.0
+
+        # @param cmd [TTY::Command::Cmd]
+        # @param options [WindowOptions] validated window options
+        # @param coordinator [Coordinator]
+        # @param stream_block [Proc, nil] yields (chunk, nil) like tty-command
+        def initialize(cmd, options, coordinator, &stream_block)
+          @cmd = cmd
+          @options = options
+          @coordinator = coordinator
+          @stream_block = stream_block
+        end
+
+        # @return [TTY::Command::Result]
+        def run!
+          require "pty"
+          rows = @options.lines
+          width = @coordinator.width
+
+          emulator = Emulator.new(
+            rows: rows, cols: width,
+            scrollback_limit: @options.scrollback,
+            responder: ->(reply) { @session&.write(reply) }
+          )
+          @block = Block.new(
+            emulator: emulator,
+            title: @options.title,
+            lines: rows,
+            on_exit: @options.on_exit,
+            interactive: @options.interactive?
+          )
+          @emulator = emulator
+
+          @session = spawn_child(rows, width)
+          started = clock
+          # Only retain raw bytes when a capture mode actually consumes them.
+          # For capture: :screen the emulator grid holds the final state; the
+          # raw stream is dead weight and would grow unbounded on long runs
+          # (see review/performance.md H5 / P0-1).
+          @needs_raw = !@options.capture_screen?
+          @raw = @needs_raw ? (+"").force_encoding(Encoding::BINARY) : nil
+          @log = @options.output_log && File.open(@options.output_log, "wb")
+
+          @coordinator.register(@block, child_session: @session)
+          InputRouter.attach(@block, @session, @coordinator) if @options.interactive?
+
+          write_initial_input
+          timed_out = timed_out_pumping?
+          status = reap(timed_out)
+          runtime = clock - started
+
+          finish(status, runtime, timed_out)
+          raise TTY::Command::TimeoutExceeded if timed_out
+
+          build_result(status, runtime)
+        ensure
+          cleanup
+        end
+
+        private
+
+        def clock
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        # @return [ChildSession]
+        def spawn_child(rows, cols)
+          master, slave = PTY.open
+          master.winsize = [rows, cols]
+          env = { "TERM" => ENV["TERM"] || "xterm-256color" }
+          pid = Process.spawn(env, @cmd.to_command,
+                              in: slave, out: slave, err: slave, pgroup: true)
+          slave.close
+          ChildSession.new(pid: pid, master: master, rows: rows)
+        end
+
+        def write_initial_input
+          input = @cmd.options[:input]
+          @session.write(input) if input
+        end
+
+        # Pump child output until EOF or timeout.
+        #
+        # @return [Boolean] true when the timeout was exceeded
+        def timed_out_pumping?
+          timeout = @cmd.options[:timeout]
+          @pump_deadline = timeout && (clock + timeout)
+          deadline = @pump_deadline
+
+          loop do
+            return true if deadline && clock >= deadline
+
+            wait = deadline ? [deadline - clock, SELECT_INTERVAL].min : SELECT_INTERVAL
+            ready = @session.wait_readable([wait, 0].max)
+
+            if ready
+              break unless read_chunk
+            elsif child_exited?
+              drain_remaining
+              break
+            end
+          end
+          false
+        end
+
+        # @return [Boolean] false on EOF
+        def read_chunk
+          data = @session.read_nonblock(READ_CHUNK)
+          handle_data(data)
+          true
+        rescue IO::WaitReadable
+          true
+        rescue Errno::EIO, EOFError
+          false
+        end
+
+        def handle_data(data)
+          if @needs_raw
+            @raw << data
+            cap = @options.capture_max_bytes
+            # Truncate from the head — the tail of the log is what callers
+            # inspect after a failure (review P0-2).
+            @raw = @raw.byteslice(-cap, cap) if cap && @raw.bytesize > cap
+          end
+          @log&.write(data)
+          @block.feed(data)
+          @coordinator.mark_dirty
+          @stream_block&.call(data.dup, nil)
+        end
+
+        def child_exited?
+          status = @session.try_wait
+          if status
+            @reaped_status = status
+            true
+          else
+            false
+          end
+        end
+
+        def drain_remaining
+          loop do
+            break unless @session.wait_readable(0.05)
+            break unless read_chunk
+          end
+        end
+
+        # Passes the pump deadline through when the caller set +timeout:+
+        # (review P0-3): after EOF the child keeps its remaining budget
+        # before SIGKILL escalation, and after a timeout the escalation is
+        # immediate instead of granting a bonus REAP_DEADLINE.
+        def reap(timed_out)
+          if timed_out
+            @session.signal(@cmd.options[:signal] || "SIGKILL")
+            wait_status(deadline: @pump_deadline) || @reaped_status
+          else
+            @reaped_status || wait_status(deadline: @pump_deadline)
+          end
+        end
+
+        # Bounded, non-blocking reap. Polls waitpid2 with WNOHANG until
+        # either the child exits or the deadline elapses, at which point
+        # we SIGKILL and reap once more. Prevents indefinite hangs when
+        # a child closes its stdio but keeps running (see review H3).
+        def wait_status(deadline: nil)
+          deadline ||= clock + REAP_DEADLINE
+          loop do
+            status = @session.try_wait
+            return status if status
+
+            if clock >= deadline
+              @session.signal("SIGKILL")
+              return @session.wait_blocking
+            end
+            sleep 0.05
+          end
+        end
+
+        def finish(status, runtime, timed_out)
+          success = !timed_out && !status.nil? && status.success?
+          @block.finish(success, runtime)
+          InputRouter.detach(@block) if @options.interactive?
+          @coordinator.finalize(@block)
+        end
+
+        def exit_code(status)
+          return 1 if status.nil?
+
+          status.exitstatus || (status.termsig ? 128 + status.termsig : 1)
+        end
+
+        def build_result(status, runtime)
+          TTY::Command::Result.new(exit_code(status), captured_output, "", runtime)
+        end
+
+        def captured_output
+          case @options.capture
+          when :stripped then ANSI.strip(utf8(@raw))
+          when :screen then @block.full_text
+          else utf8(@raw)
+          end
+        end
+
+        def utf8(data)
+          return "" if data.nil?
+
+          text = data.dup.force_encoding(Encoding::UTF_8)
+          text.valid_encoding? ? text : text.scrub("\u{FFFD}")
+        end
+
+        # Ensure the child is dead and the block finalized even when the
+        # pump raised (Interrupt, timeout, IO errors).
+        def cleanup
+          if @block&.running?
+            @session&.signal("SIGKILL")
+            wait_status
+            @block.finish(false, 0.0)
+            InputRouter.detach(@block) if @options.interactive?
+            @coordinator.finalize(@block)
+          end
+          @session&.close
+          @log&.close
+        end
+      end
+    end
+  end
+end