tty-command-window 0.1.0

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module TTY
+  class Command
+    module Window
+      # Handle to the child process spawned inside the PTY.
+      #
+      # Owns the process id and the PTY master file descriptor and
+      # exposes the operations the rest of the gem needs to perform
+      # against a live child: write user input, resize the terminal,
+      # forward a signal to its process group, reap the child, and
+      # close the master fd.
+      #
+      # **Orphan protection.** Every live session is tracked in a
+      # class-level set. A one-time +at_exit+ hook SIGKILLs the process
+      # group of any session still alive when the host process exits
+      # (follow-up review P1-8). This covers the case where the host
+      # dies before {Runner#cleanup} runs — SIGKILL to the host, an
+      # interpreter abort, or `exit!`.
+      class ChildSession
+        @live = {}.compare_by_identity
+        @live_mutex = Mutex.new
+        @at_exit_installed = false
+
+        class << self
+          # @api private
+          attr_reader :live, :live_mutex
+
+          # Register the session as live and ensure the +at_exit+ orphan
+          # sweeper is installed.
+          def track(session)
+            install_at_exit_once
+            @live_mutex.synchronize { @live[session] = true }
+          end
+
+          # Remove the session from the live-set (called on close).
+          def untrack(session)
+            @live_mutex.synchronize { @live.delete(session) }
+          end
+
+          # @api private for tests
+          def reap_orphans!
+            sessions = @live_mutex.synchronize { @live.keys.dup }
+            sessions.each(&:kill_group!)
+          end
+
+          private
+
+          def install_at_exit_once
+            return if @at_exit_installed
+
+            @at_exit_installed = true
+            at_exit { reap_orphans! }
+          end
+        end
+
+        # @param pid [Integer] child process id (session/pgroup leader)
+        # @param master [IO] PTY master fd
+        # @param rows [Integer] emulator/PTY row count (fixed for the lifetime of the session)
+        def initialize(pid:, master:, rows:)
+          @pid = pid
+          @master = master
+          @rows = rows
+          @closed = false
+          @reaped = false
+          self.class.track(self)
+        end
+
+        attr_reader :rows
+
+        # Write user keystrokes / bytes to the child.
+        def write(data)
+          @master.write(data) if @master && !@master.closed?
+        rescue Errno::EIO, IOError
+          nil
+        end
+
+        # Resize the PTY to the new column count. Rows are fixed.
+        def resize(cols)
+          @master&.winsize = [@rows, cols]
+        rescue Errno::EIO, Errno::EBADF, IOError
+          nil
+        end
+
+        # Forward a signal to the child's process group. No-op once the
+        # child has been reaped so a stale session cannot deliver to a
+        # recycled PID (belt-and-braces alongside the coordinator's
+        # unconditional @sessions.delete — see follow-up review P0-2).
+        def signal(name)
+          return if @reaped
+          return unless @pid
+
+          Process.kill(name, -@pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+
+        # Block until the child has output or +timeout+ seconds elapse.
+        #
+        # @return [IO, nil] truthy when readable, nil on timeout
+        def wait_readable(timeout)
+          @master.wait_readable(timeout)
+        end
+
+        # Read up to +length+ bytes of child output without blocking.
+        # Raises like IO#read_nonblock (IO::WaitReadable, EOFError,
+        # Errno::EIO on PTY hangup) — callers own the EOF handling.
+        def read_nonblock(length)
+          @master.read_nonblock(length)
+        end
+
+        # Non-blocking waitpid poll. Marks the session as reaped on
+        # success so subsequent {#signal} calls are inert.
+        #
+        # @return [Process::Status, nil]
+        def try_wait
+          pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+          return nil unless pid
+
+          @reaped = true
+          status
+        rescue Errno::ECHILD
+          @reaped = true
+          nil
+        end
+
+        # Blocking waitpid — used when the caller has already decided
+        # to give up polling (e.g. after SIGKILL). Marks reaped.
+        def wait_blocking
+          _, status = Process.waitpid2(@pid)
+          @reaped = true
+          status
+        rescue Errno::ECHILD
+          @reaped = true
+          nil
+        end
+
+        # Close the PTY master. Idempotent. Also removes the session
+        # from the orphan-tracking set.
+        def close
+          return if @closed
+
+          @closed = true
+          @master.close if @master && !@master.closed?
+        rescue IOError, Errno::EBADF
+          nil
+        ensure
+          self.class.untrack(self)
+        end
+
+        # Send SIGKILL to the process group. Used by the +at_exit+
+        # orphan sweeper; safe to call on a reaped session (no-op).
+        def kill_group!
+          signal("KILL")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module TTY
+  class Command
+    module Window
+      # Owns a region at the bottom of the terminal and paints the stack of
+      # active {Block}s into it from a dedicated render thread.
+      #
+      # All painted lines end with explicit "\r\n" so rendering stays correct
+      # even when the input router has put the terminal into raw mode (which
+      # disables output newline translation for the whole tty).
+      class Coordinator
+        FRAME_INTERVAL = 0.08
+        HIDE_CURSOR = "\e[?25l"
+        SHOW_CURSOR = "\e[?25h"
+
+        @registry = {}
+        @registry_mutex = Mutex.new
+
+        class << self
+          # Coordinator bound to the given output IO (one per IO).
+          #
+          # @param output [IO]
+          # @param width [Integer, nil] fixed width override
+          # @return [Coordinator]
+          def for(output, width: nil)
+            @registry_mutex.synchronize do
+              @registry[output] ||= new(output: output, width_override: width)
+            end
+          end
+
+          # Emergency cleanup for at_exit: restore the cursor everywhere.
+          def restore_all
+            @registry_mutex.synchronize do
+              @registry.each_value(&:emergency_restore)
+            end
+          end
+
+          # Trap-safe variant of {.restore_all}: iterates a snapshot of the
+          # registry without @registry_mutex, which the main thread may hold
+          # when the signal arrives (see review P0-5).
+          def emergency_restore_all
+            # .values (not each_value): iterating the live hash could raise
+            # if the main thread mutates the registry mid-trap.
+            @registry.values.each(&:emergency_restore) # rubocop:disable Style/HashEachMethods
+          rescue StandardError
+            nil
+          end
+        end
+
+        attr_reader :output, :pastel
+
+        def initialize(output:, width_override: nil)
+          @output = output
+          @width_override = width_override
+          @blocks = []
+          @sessions = {} # block => ChildSession, for signal + PTY resize
+          @painted_height = 0
+          @active = false
+          @winch = false
+          @dirty = false
+          @mutex = Mutex.new
+          @spinner = Spinner.new
+          @pastel = Pastel.new(enabled: color?)
+        end
+
+        # @return [Integer] current terminal width in columns
+        def width
+          return @width_override if @width_override
+
+          if @output.respond_to?(:winsize) && @output.respond_to?(:tty?) && @output.tty?
+            cols = @output.winsize[1]
+            return cols if cols.positive?
+          end
+          (ENV["COLUMNS"] || "80").to_i.clamp(20, 1000)
+        rescue Errno::ENOTTY, Errno::EBADF, IOError
+          80
+        end
+
+        # Add a block to the stack and start rendering if needed.
+        #
+        # @param block [Block]
+        # @param child_session [ChildSession, nil] used for signal forwarding
+        #   and PTY winsize updates; may be nil for test doubles.
+        def register(block, child_session: nil)
+          @mutex.synchronize do
+            activate unless @active
+            @blocks << block
+            @sessions[block] = child_session if child_session
+            paint
+          end
+        end
+
+        # Called by the runner when a block's command finished. Repaints and,
+        # for dump-on-failure blocks, replaces the block with its full
+        # history as permanent scrolled output. Drains the region when every
+        # block is done.
+        def finalize(block)
+          drained = false
+          @mutex.synchronize do
+            next unless @active
+
+            if block.dump_on_finalize?
+              wipe_region
+              @blocks.delete(block)
+              write_permanent(block.dump_text(@pastel))
+            end
+            # Drop the session unconditionally: the child has been reaped by
+            # Runner and its PID is no longer safe to signal. Leaving stale
+            # entries in @sessions risks INT/TERM delivery to a recycled PID
+            # (see follow-up review P0-2).
+            @sessions.delete(block)
+            paint
+            if @blocks.all?(&:done?)
+              drain
+              drained = true
+            end
+          end
+          join_render_thread if drained
+        end
+
+        # Request a repaint on the next frame (cheap, lock-free).
+        def mark_dirty
+          @dirty = true
+        end
+
+        # Trap-context WINCH notification; actual work happens on the render
+        # thread.
+        def winch!
+          @winch = true
+        end
+
+        # @return [Boolean] whether colored output is enabled
+        def color?
+          return false if ENV.key?("NO_COLOR")
+
+          Window.assume_tty || (@output.respond_to?(:tty?) && @output.tty?)
+        end
+
+        # at_exit safety net: show the cursor if we died mid-paint.
+        def emergency_restore
+          @output.write(SHOW_CURSOR) if @active && @output.respond_to?(:write) && !@output.closed?
+        rescue IOError, Errno::EBADF, Errno::EPIPE
+          nil
+        end
+
+        private
+
+        def activate
+          @active = true
+          @painted_height = 0
+          @output.write("\r#{HIDE_CURSOR}")
+          install_traps
+          Window.register_at_exit
+          @render_thread = Thread.new { render_loop }
+          @render_thread.name = "tty-command-window-render"
+        end
+
+        # Must be called while holding @mutex; the caller joins the render
+        # thread outside the lock afterwards.
+        def drain
+          @output.write("\r\n#{SHOW_CURSOR}")
+          @blocks.clear
+          @sessions.clear
+          @painted_height = 0
+          @active = false
+          restore_traps
+        end
+
+        def join_render_thread
+          thread = @render_thread
+          @render_thread = nil
+          thread&.join(1)
+        end
+
+        def render_loop
+          while @active
+            sleep(FRAME_INTERVAL)
+            @mutex.synchronize do
+              next unless @active
+
+              handle_winch if @winch
+              next unless @dirty || @blocks.any?(&:running?)
+
+              @dirty = false
+              @spinner.tick
+              paint
+            end
+          end
+        end
+
+        def handle_winch
+          @winch = false
+          wipe_region
+          new_width = width
+          @blocks.each do |block|
+            block.resize(new_width)
+            @sessions[block]&.resize(new_width)
+          end
+        end
+
+        # Paint the whole stack. Must be called while holding @mutex.
+        def paint
+          lines = render_all_lines
+          height = lines.length
+          return if height.zero? && @painted_height.zero?
+
+          ensure_capacity(height)
+          buffer = +"\r"
+          up = @painted_height - 1
+          buffer << "\e[#{up}A" if up.positive?
+          lines.each_with_index do |line, index|
+            buffer << line << "\e[0m\e[K"
+            buffer << "\r\n" if index < height - 1
+          end
+          buffer << "\e[0J" if @painted_height > height
+          @painted_height = height
+          @output.write(buffer)
+        end
+
+        def render_all_lines
+          current_width = width
+          frame = @spinner.frame
+          @blocks.flat_map do |block|
+            block.render(width: current_width, pastel: @pastel, frame: frame)
+          end
+        end
+
+        # Grow the painted region to +height+ lines by emitting newlines from
+        # the parked position (bottom line of the region, column 0).
+        def ensure_capacity(height)
+          return if height <= @painted_height
+
+          missing = height - [@painted_height, 1].max
+          @output.write("\r#{"\r\n" * missing}") if missing.positive?
+          @painted_height = height
+        end
+
+        # Erase the whole painted region, leaving the cursor at its former
+        # top line, column 0.
+        def wipe_region
+          return if @painted_height.zero?
+
+          up = @painted_height - 1
+          buffer = +"\r"
+          buffer << "\e[#{up}A" if up.positive?
+          buffer << "\e[0J"
+          @output.write(buffer)
+          @painted_height = 0
+        end
+
+        # Write permanent (scrolling) text at the current cursor position.
+        # Used for failure dumps. Cursor ends at column 0 of a fresh line.
+        def write_permanent(text)
+          body = text.split("\n", -1).join("\r\n")
+          body += "\r\n" unless body.end_with?("\r\n")
+          @output.write(body)
+        end
+
+        # --- signals -------------------------------------------------------
+        #
+        # Coordinators do not touch Signal.trap directly: the process-global
+        # TrapManager owns installation so concurrent coordinators (on
+        # distinct outputs) cannot clobber each other's handlers, and the
+        # host application's prior handler is captured exactly once and
+        # restored exactly once.
+
+        def install_traps
+          return unless @output.respond_to?(:tty?) && @output.tty?
+
+          @winch_sub = TrapManager.subscribe("WINCH", method(:on_winch_signal))
+          @int_sub = TrapManager.subscribe("INT", method(:on_process_signal))
+          @term_sub = TrapManager.subscribe("TERM", method(:on_process_signal))
+        end
+
+        def restore_traps
+          TrapManager.unsubscribe("WINCH", @winch_sub) if @winch_sub
+          TrapManager.unsubscribe("INT", @int_sub) if @int_sub
+          TrapManager.unsubscribe("TERM", @term_sub) if @term_sub
+          @winch_sub = @int_sub = @term_sub = nil
+        end
+
+        # Trap-context WINCH handler. Deferred to the render thread.
+        def on_winch_signal(_signal)
+          winch!
+        end
+
+        # Trap-context INT/TERM handler.
+        #
+        # Cannot acquire @mutex from trap context; instead we snapshot the
+        # sessions hash's values array. A concurrent register/finalize may
+        # miss the newly-added/removed session for this one signal — that
+        # is an accepted trade-off for INT/TERM forwarding.
+        def on_process_signal(signal)
+          sessions = begin
+            @sessions.values
+          rescue StandardError
+            []
+          end
+          # ChildSession#signal already rescues Errno::ESRCH / EPERM;
+          # no outer rescue needed here.
+          sessions.each { |session| session.signal(signal) }
+          # Restore the terminal before TrapManager delegates to the prior
+          # handler, which may terminate the process (review P0-5): cursor
+          # visibility for every coordinator, termios for the input router
+          # even when this session is not interactive.
+          self.class.emergency_restore_all
+          InputRouter.emergency_restore
+        end
+      end
+    end
+  end
+end