tty-command-window 0.1.0

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      # Braille spinner used in block title bars.
+      class Spinner
+        FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+        def initialize
+          @index = 0
+        end
+
+        # Advance and return the next frame.
+        #
+        # @return [String]
+        def tick
+          frame = FRAMES[@index]
+          @index = (@index + 1) % FRAMES.length
+          frame
+        end
+
+        # @return [String] the current frame without advancing
+        def frame
+          FRAMES[@index]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      # Process-global owner of the signals this gem cares about
+      # (+WINCH+, +INT+, +TERM+, +HUP+).
+      #
+      # Ruby's +Signal.trap+ is a process singleton: two coordinators
+      # installing their own trap for the same signal will silently
+      # clobber each other and lose the host application's previous
+      # handler. TrapManager mediates that by installing exactly one
+      # trap per signal (the first time anyone subscribes) and
+      # multiplexing to a subscriber list.
+      #
+      # **Ownership contract.** Once a signal has been installed by
+      # TrapManager it remains installed for the life of the process
+      # (only {.reset!}, which is test-only, uninstalls). This avoids
+      # clobbering a host-application handler that a caller installed
+      # *after* our first subscribe (follow-up review P1-6): restoring
+      # the snapshot we captured at first-install time would silently
+      # overwrite the host's newer handler.
+      #
+      # Thread-safe. Trap-safe: the trap block reads a reference to
+      # the subscriber array under MRI's GVL and iterates a local
+      # snapshot; unsubscribe swaps the array reference so an
+      # in-flight trap keeps iterating the array it saw.
+      class TrapManager
+        @mutex = Mutex.new
+        @subscribers = {} # signal (String) => [callable, ...]
+        @originals = {}   # signal (String) => Proc / String / nil returned by Signal.trap
+
+        class << self
+          # Register +callable+ as a handler for +signal+.
+          #
+          # @param signal [String, Symbol] e.g. "INT", "TERM", "WINCH"
+          # @param callable [#call] invoked as +callable.call(signal)+ in trap context
+          # @return [#call] the subscribed callable (pass back to {.unsubscribe})
+          def subscribe(signal, callable)
+            key = signal.to_s
+            @mutex.synchronize do
+              # Populate the subscriber list BEFORE installing the trap
+              # so a signal arriving between Signal.trap returning and
+              # the append cannot observe an empty list (follow-up
+              # review P1-7).
+              list = @subscribers[key] || []
+              @subscribers[key] = list + [callable]
+              install_once(key) unless @originals.key?(key)
+            end
+            callable
+          end
+
+          # Remove a previously subscribed handler.
+          #
+          # @return [void]
+          def unsubscribe(signal, callable)
+            key = signal.to_s
+            @mutex.synchronize do
+              list = @subscribers[key]
+              next if list.nil?
+
+              new_list = list.reject { |c| c.equal?(callable) }
+              # Keep the installed trap even when the subscriber list
+              # empties: uninstalling would restore the snapshot we took
+              # at first-install time and clobber a host handler
+              # installed after that snapshot (follow-up review P1-6).
+              # reset! (test-only) is the one path that uninstalls.
+              @subscribers[key] = new_list
+            end
+          end
+
+          # Uninstall every subscriber and restore original handlers.
+          # Intended for tests and emergency teardown.
+          def reset!
+            @mutex.synchronize do
+              # Materialize keys before iteration because uninstall mutates @originals.
+              @subscribers.keys.to_a.each { |key| uninstall(key) }
+              @subscribers.clear
+            end
+          end
+
+          # @api private for tests
+          def subscribed?(signal)
+            @mutex.synchronize { !(@subscribers[signal.to_s] || []).empty? }
+          end
+
+          private
+
+          def install_once(signal)
+            @originals[signal] = Signal.trap(signal) do
+              # Trap context: no mutex, no allocation-heavy work.
+              subs = @subscribers[signal] || []
+              subs.each do |sub|
+                sub.call(signal)
+              rescue StandardError
+                nil
+              end
+              orig = @originals[signal]
+              orig.call if orig.respond_to?(:call)
+            end
+          rescue ArgumentError
+            # Reserved signal (e.g. running under a debugger). Leave @originals[signal] unset;
+            # subscribers still get called from any trap someone else might install.
+            @originals[signal] = nil
+          end
+
+          def uninstall(signal)
+            original = @originals.delete(signal)
+            Signal.trap(signal, original || "DEFAULT")
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      VERSION = "0.1.0"
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      # Immutable, validated configuration for a single windowed run.
+      #
+      # Built from the raw options hash the user passed to +run_windowed+
+      # by {.build}. Runner and Block consume named accessors on this
+      # object instead of dereferencing symbol keys, so the option
+      # contract is explicit.
+      #
+      # +Struct.new(..., keyword_init: true)+ is used (rather than
+      # +Data.define+) because +Data.define+ ships in Ruby 3.2 and the
+      # gemspec's +required_ruby_version+ floor is 3.1. Instances are
+      # frozen in {.build} for immutability.
+      WindowOptions = Struct.new(
+        :lines, :title, :on_exit, :capture, :capture_max_bytes,
+        :scrollback, :output_log, :interactive,
+        keyword_init: true
+      ) do
+        # @param window_options [Hash] the raw window options subset
+        #   returned by {Window.split_options}
+        # @param cmd [TTY::Command::Cmd] used to derive a default title
+        # @return [WindowOptions]
+        def self.build(window_options, cmd)
+          lines = Integer(window_options.fetch(:lines, DEFAULT_LINES))
+          raise ArgumentError, "lines must be >= 1" if lines < 1
+
+          on_exit = validated_enum(window_options, :on_exit, ON_EXIT_MODES, :freeze)
+          capture = validated_enum(window_options, :capture, CAPTURE_MODES, :raw)
+
+          capture_max_bytes = window_options.fetch(:capture_max_bytes, DEFAULT_CAPTURE_MAX_BYTES)
+          unless capture_max_bytes.nil?
+            capture_max_bytes = Integer(capture_max_bytes)
+            raise ArgumentError, "capture_max_bytes must be >= 1 or nil" if capture_max_bytes < 1
+          end
+
+          Window.validate_on_unavailable!(window_options)
+
+          title = window_options.fetch(:title, nil)
+          title = cmd.to_command if title.nil?
+
+          new(
+            lines: lines,
+            title: title,
+            on_exit: on_exit,
+            capture: capture,
+            capture_max_bytes: capture_max_bytes,
+            scrollback: Integer(window_options.fetch(:scrollback, DEFAULT_SCROLLBACK)),
+            output_log: window_options[:output_log],
+            interactive: window_options[:interactive] == true
+          ).freeze
+        end
+
+        def self.validated_enum(window_options, key, modes, default)
+          value = window_options.fetch(key, default)
+          unless modes.include?(value)
+            raise ArgumentError, "#{key} must be one of #{modes.join(', ')}"
+          end
+
+          value
+        end
+        private_class_method :validated_enum
+
+        def interactive?
+          interactive
+        end
+
+        def capture_screen?
+          capture == :screen
+        end
+      end
+    end
+  end
+end

data/lib/tty/command/window.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "tty/command"
+
+require_relative "window/version"
+require_relative "window/ansi"
+require_relative "window/emulator"
+require_relative "window/spinner"
+require_relative "window/child_session"
+require_relative "window/block"
+require_relative "window/trap_manager"
+require_relative "window/coordinator"
+require_relative "window/input_router"
+require_relative "window/window_options"
+require_relative "window/runner"
+require_relative "window/integration"
+
+module TTY
+  class Command
+    # Namespace for the windowed-run extension.
+    #
+    # Requiring this file adds {TTY::Command#run_windowed} and
+    # {TTY::Command#run_windowed!} to +TTY::Command+.
+    module Window
+      DEFAULT_LINES = 5
+      DEFAULT_SCROLLBACK = 10_000
+      DEFAULT_CAPTURE_MAX_BYTES = 10 * 1024 * 1024
+
+      # Option keys consumed by run_windowed and stripped before any
+      # delegation to plain tty-command.
+      OPTION_KEYS = %i[
+        lines title on_exit scrollback output_log interactive capture
+        capture_max_bytes output window width on_unavailable tty
+      ].freeze
+
+      ON_EXIT_MODES = %i[freeze dump_on_failure collapse].freeze
+      CAPTURE_MODES = %i[raw stripped screen].freeze
+      ON_UNAVAILABLE_MODES = %i[fallback raise].freeze
+
+      # Raised by +run_windowed+ / +run_windowed!+ when
+      # +on_unavailable: :raise+ is set and the environment cannot support
+      # windowed rendering (no TTY / PTY, on Windows, or in dry-run mode).
+      class Unavailable < StandardError; end
+
+      class << self
+        # Treat non-TTY outputs as terminals.
+        #
+        # @api private Intended for test suites that render into a StringIO.
+        #   Prefer per-call +window: true+ or the scoped
+        #   {.with_assume_tty} block form; unscoped writes leak across
+        #   examples under +config.order = :random+.
+        # @return [Boolean]
+        attr_accessor :assume_tty
+
+        # Set {.assume_tty} for the duration of the block and restore the
+        # previous value on exit — including on exception.
+        #
+        # @api private
+        # @param value [Boolean]
+        # @yieldreturn [Object] the block's return value is returned
+        def with_assume_tty(value = true) # rubocop:disable Style/OptionalBooleanParameter
+          previous = assume_tty
+          self.assume_tty = value
+          yield
+        ensure
+          self.assume_tty = previous
+        end
+
+        # @return [Boolean] true when running on Windows (no PTY support)
+        def windows?
+          !!(RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/)
+        end
+
+        # @return [Boolean] true when the PTY library is usable
+        def pty_available?
+          return @pty_available unless @pty_available.nil?
+
+          @pty_available =
+            begin
+              require "pty"
+              true
+            rescue LoadError
+              false
+            end
+        end
+
+        # Whether a windowed run can render onto the given IO.
+        #
+        # @param output [IO]
+        # @return [Boolean]
+        def renderable?(output)
+          return false if windows? || !pty_available?
+
+          assume_tty || (output.respond_to?(:tty?) && output.tty?)
+        end
+
+        # Strip ANSI escape sequences (CSI, OSC, DCS, simple escapes) from a string.
+        #
+        # @param text [String]
+        # @return [String]
+        def strip_ansi(text)
+          ANSI.strip(text)
+        end
+      end
+
+      self.assume_tty = false
+    end
+  end
+end

data/lib/tty-command-window.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "tty/command/window"

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: tty-command-window
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Matyas
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: tty-command
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: unicode-display_width
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: 'Extends tty-command with run_windowed: the child process runs in a PTY
+  that reports N rows, its output (including cursor-movement escape codes) is interpreted
+  by a built-in terminal emulator and rendered as a static N-line block that streams
+  in place. Supports stacked concurrent windows, interactive stdin with focus switching,
+  resize handling and failure dumps.'
+email:
+- michal.matyas@helpling.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tty-command-window.rb
+- lib/tty/command/window.rb
+- lib/tty/command/window/ansi.rb
+- lib/tty/command/window/block.rb
+- lib/tty/command/window/child_session.rb
+- lib/tty/command/window/coordinator.rb
+- lib/tty/command/window/emulator.rb
+- lib/tty/command/window/input_router.rb
+- lib/tty/command/window/integration.rb
+- lib/tty/command/window/runner.rb
+- lib/tty/command/window/spinner.rb
+- lib/tty/command/window/trap_manager.rb
+- lib/tty/command/window/version.rb
+- lib/tty/command/window/window_options.rb
+homepage: https://github.com/helpling/tty-command-window
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/helpling/tty-command-window
+  source_code_uri: https://github.com/helpling/tty-command-window
+  changelog_uri: https://github.com/helpling/tty-command-window/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Run commands with tty-command inside a live, fixed-height terminal window
+test_files: []