tty-command-window 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b39102b7bfbae84d31acca3a966ca18b2553381a5dc2085a13bd98308959ba0
+  data.tar.gz: 75928be1bb72d1e7dfdd43e5e0b6678089f4c698f215fe6ec51b821cc07915cb
+SHA512:
+  metadata.gz: 3f9b8bad3b0255f783a37cfa94820df78b4a11841ca12e94331fd372ded05dfe1ea46b1d46fb974d61fe16d18a70befceff5a592f03d11acc2f07bde83f97de0
+  data.tar.gz: 957da48ba1ffcc5a4776331975ae4f12e015a82cb9be1fe32dff96c46fd9d11cb7c5797c85cd31b7333b6190ada92ae03a0ace1b97fcadc5c7e8332ef8747b49

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Renamed the `tty:` option to `window:`**. The old name was ambiguous
+  inside the `TTY::` namespace and semantically wrong (it toggles the
+  window, not "am I a TTY?"). `tty:` is kept as a deprecated alias for one
+  minor version and emits a one-time deprecation warning; it will be
+  removed in the following release.
+- `Result#err` under windowed rendering is documented (in the `#run_windowed`
+  YARD `@note` and in the README) as always `""`: the PTY merges the child's
+  stderr into `Result#out` at the OS level.
+
+### Added
+
+- `TTY::Command#run_windowed` / `#run_windowed!`: run a command inside a live,
+  fixed-height terminal window (default 5 lines) rendered as a static block.
+- Pure-Ruby VT100-subset terminal emulator (cursor movement, erase, scroll
+  regions, insert/delete lines and characters, SGR colors, alternate screen,
+  wide characters, autowrap) driving the window contents.
+- Child processes run in a PTY that reports `lines:` rows, so cursor-driven
+  programs (e.g. `docker compose`) lay themselves out for the window height.
+- Title/status bar with spinner, elapsed time and success/failure state.
+- `on_exit:` modes — `:freeze` (default), `:dump_on_failure`, `:collapse`.
+- Configurable result capture — `capture: :raw` (default), `:stripped`, `:screen`.
+- Plain-text scrollback (10k lines default, `scrollback:` option) used for
+  failure dumps and `capture: :screen`.
+- `output_log:` tees the full raw child output to a file.
+- Concurrent stacked windows from multiple threads.
+- Interactive stdin passthrough (`interactive: true`) with `Ctrl-O` focus
+  cycling between interactive windows.
+- SIGWINCH handling: terminal resizes propagate to child PTYs and the block
+  re-renders at the new width.
+- Graceful degradation to plain `tty-command` streaming when stdout is not a
+  TTY, on Windows, or when PTY support is unavailable.
+- `on_unavailable:` option — `:fallback` (default, previous behavior)
+  silently degrades to plain `run`; `:raise` raises the new
+  `TTY::Command::Window::Unavailable` error when the environment cannot
+  render a window. Lets callers who need PTY-reported rows opt out of the
+  silent-degradation default. Invalid values raise `ArgumentError`.
+- `TTY::Command::Window.with_assume_tty(value) { ... }` — scoped block form
+  of the `assume_tty` testing aid, restores the previous value on exit.
+  The `assume_tty` accessor is now marked `@api private`.
+
+## [0.1.0] - Unreleased
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Michal Matyas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# tty-command-window
+
+> [!WARNING]
+> This library has been built with Claude Code.
+
+Run shell commands with [tty-command](https://github.com/piotrmurach/tty-command),
+but show only the **last N lines** of output as a live, fixed-height block in
+your terminal — like CI log folding, but local and real-time.
+
+The trick: the child process runs in a PTY that reports **N rows**, so
+cursor-driven programs (`docker compose`, installers, progress bars) lay
+themselves out as if the terminal were N lines tall. A built-in pure-Ruby
+terminal emulator interprets every escape sequence the child emits — cursor
+movement, erase, scroll regions, colors, alternate screen — and paints the
+resulting screen into a static block that streams in place.
+
+![docker compose confined to a 5-line window](docs/demo-compose.gif)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "tty-command-window"
+```
+
+Requires Ruby >= 3.1 and a Unix-like OS for windowed rendering (see
+[Degradation](#degradation) for what happens elsewhere).
+
+## Usage
+
+```ruby
+require "tty-command-window"
+
+cmd = TTY::Command.new(printer: :null)
+
+# Everything docker compose draws stays inside 5 lines:
+cmd.run_windowed("docker compose up -d", lines: 5)
+
+# Same semantics as tty-command: raises TTY::Command::ExitError on failure,
+# run_windowed! doesn't. Returns a TTY::Command::Result.
+result = cmd.run_windowed!("make -j8", lines: 8, title: "building")
+puts result.out if result.failure?
+```
+
+`run_windowed` accepts everything `run` does (`env:`, `chdir:`, `timeout:`,
+`input:`, a streaming block, ...) plus the window options below.
+
+> **Use `printer: :null`.** `tty-command-window` renders the child's output
+> itself. If your `TTY::Command` instance uses a printer other than `:null`
+> (`:pretty`, `:progress`, `:quiet`), the printer will *also* write to the
+> terminal in parallel with the window, double-logging every line. Every
+> example in this README uses `TTY::Command.new(printer: :null)` for that
+> reason.
+
+### Options
+
+| Option            | Default        | What it does |
+| ----------------- | -------------- | ------------ |
+| `lines:`          | `5`            | Window height; also the row count the child's PTY reports. |
+| `title:`          | the command    | Title-bar text. `false` hides the title bar. |
+| `on_exit:`        | `:freeze`      | What the block does when the command ends (see below). |
+| `capture:`        | `:raw`         | What `Result#out` contains (see below). |
+| `capture_max_bytes:` | `10 MiB`    | Cap on raw bytes kept for `Result#out`; the head is dropped, the tail kept. `nil` disables. |
+| `scrollback:`     | `10_000`       | Plain-text history lines kept for dumps and `capture: :screen`. |
+| `output_log:`     | `nil`          | Tee the full raw child output to this file while rendering. |
+| `interactive:`    | `false`        | Forward your keystrokes to the child's PTY. |
+| `output:`         | printer output | IO to render on. |
+| `window:`         | auto-detect    | Force (`true`) or forbid (`false`) windowed rendering. |
+| `on_unavailable:` | `:fallback`    | `:fallback` degrades to plain `run`; `:raise` raises `TTY::Command::Window::Unavailable`. |
+| `width:`          | auto-detect    | Fixed render width. |
+
+### End-of-run behavior (`on_exit:`)
+
+- `:freeze` *(default)* — the final frame stays in the terminal and the
+  cursor moves below it. The title bar turns into `✔ title • 3.1s` (green)
+  or `✖` (red).
+- `:dump_on_failure` — like `:freeze` on success; on failure the block is
+  replaced by the full plain-text output history, so the error that scrolled
+  away is right there.
+- `:collapse` — the block shrinks to a single status line when done.
+
+![failure dump](docs/demo-failure.gif)
+
+### Result capture (`capture:`)
+
+- `:raw` *(default)* — `Result#out` is exactly what the child wrote,
+  escape codes included (tty-command semantics). `Result#err` is always
+  `""`: a PTY merges the child's stderr into the same stream at the OS
+  level, so windowed rendering cannot separate them without destroying
+  the layout fidelity that is the point of the gem. If you need stderr
+  independently, use plain `run`/`run!`.
+- `:stripped` — the raw stream with ANSI sequences removed.
+- `:screen` — the emulator's plain-text history (scrollback + final
+  screen): what a human saw, in order, without any escape codes.
+
+### Concurrent windows
+
+`run_windowed` is thread-safe; blocks from concurrent calls stack in the
+terminal, each rendering independently:
+
+```ruby
+%w[api worker assets].map do |name|
+  Thread.new { cmd.run_windowed("bin/build #{name}", lines: 3, title: name, on_exit: :collapse) }
+end.each(&:join)
+```
+
+![three concurrent windows](docs/demo-multi.gif)
+
+### Interactive commands
+
+```ruby
+cmd.run_windowed("bin/deploy", lines: 5, interactive: true)
+```
+
+With `interactive: true`, the terminal goes into raw mode and your
+keystrokes are written to the child's PTY, so `Continue? (y/N)` prompts work
+inside the window. When several interactive windows run at once, **Ctrl-O**
+cycles the keyboard focus between them — the focused window shows a `▸`
+marker and an inverse title.
+
+Because raw mode delivers Ctrl-C to the focused child as a keystroke
+(`0x03`) rather than signalling your process, the child decides what an
+interrupt means while an interactive window is open.
+
+### Resize
+
+Terminal resizes are propagated: the child PTYs get the new width (rows stay
+at `lines:`), the child re-renders — as any full-screen program does on
+SIGWINCH — and the blocks repaint.
+
+## Degradation
+
+Windowed rendering needs a real terminal and PTY support. `run_windowed`
+falls back to a plain `run` (full streamed output through your configured
+printer, no window, no PTY) when:
+
+- stdout (or the given `output:`) is not a TTY — CI, pipes, cron;
+- the OS is Windows, or Ruby's `pty` library is unavailable;
+- the command instance is in `dry_run` mode.
+
+The fallback keeps the same raise/no-raise contract, so calling code never
+needs a branch. If you *need* windowed rendering — for example, a test that
+asserts the child laid itself out at 5 rows — pass `on_unavailable: :raise`
+to opt out of degradation:
+
+```ruby
+cmd.run_windowed("bin/deploy", lines: 5, on_unavailable: :raise)
+# raises TTY::Command::Window::Unavailable when there's no PTY / TTY.
+```
+
+## Notes and limitations
+
+- **Signals**: while windows are active, `SIGINT`/`SIGTERM` are forwarded to
+  the children's process groups (previous handlers are chained and restored
+  afterwards).
+- **Cursor**: hidden while windows render, restored afterwards — also via an
+  `at_exit` hook if the process dies mid-run.
+- **`Result#out` growth**: `capture: :raw` keeps up to `capture_max_bytes:`
+  (default 10 MiB) of the raw stream in memory, dropping the oldest bytes
+  beyond that. For multi-hour firehoses prefer `capture: :screen` (bounded
+  by `scrollback:`) plus `output_log:`, or raise/disable the cap.
+- **Emulator coverage**: the common VT100/xterm repertoire (cursor
+  movement, EL/ED, IL/DL/DCH/ICH/ECH, SU/SD, DECSTBM scroll regions, SGR
+  colors incl. 256/truecolor, alternate screen, autowrap, wide characters,
+  DSR/DA reports). Exotic sequences are ignored rather than leaked to your
+  terminal.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # specs + rubocop
+ruby examples/compose_demo.rb   # see it live
+```
+
+The `examples/` directory doubles as a manual test rig; `examples/fake_compose.rb`
+simulates docker compose's cursor choreography without needing Docker.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module TTY
+  class Command
+    module Window
+      # ANSI helpers: SGR attribute tracking and escape-sequence stripping.
+      module ANSI
+        STRIP_PATTERN = Regexp.union(
+          /\e\][^\a\e]*(?:\a|\e\\)?/, # OSC ... BEL/ST
+          /\eP.*?(?:\e\\|\a)/m,       # DCS ... ST
+          %r{\e\[[\d;:?<=>!]*[ -/]*[@-~]}, # CSI sequences
+          /\e[()*+][@-~]/,            # charset designation
+          /\e[@-_]/,                  # other C1-introducing escapes
+          /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/ # stray control bytes (keep \t \n \r)
+        ).freeze
+        # Remove escape sequences and normalize CRLF, leaving printable text.
+        #
+        # @param text [String]
+        # @return [String]
+        def self.strip(text)
+          text.gsub(STRIP_PATTERN, "").gsub("\r\n", "\n").delete("\r")
+        end
+
+        # Tracks the current SGR (color/attribute) state of the emulator pen
+        # and serializes it to a compact parameter string stored per cell.
+        class SGRState
+          RESET_CODES = {
+            22 => %i[bold dim], 23 => %i[italic], 24 => %i[underline],
+            25 => %i[blink], 27 => %i[inverse], 28 => %i[hidden], 29 => %i[strike]
+          }.freeze
+
+          SET_CODES = {
+            1 => :bold, 2 => :dim, 3 => :italic, 4 => :underline,
+            5 => :blink, 7 => :inverse, 8 => :hidden, 9 => :strike
+          }.freeze
+
+          FLAG_SGR = {
+            bold: "1", dim: "2", italic: "3", underline: "4",
+            blink: "5", inverse: "7", hidden: "8", strike: "9"
+          }.freeze
+
+          def initialize
+            reset
+          end
+
+          def reset
+            @flags = {}
+            @fg = nil
+            @bg = nil
+            @serialized = nil
+          end
+
+          # Apply a list of SGR parameters (integers, with extended color
+          # sub-parameters consumed in place).
+          #
+          # @param params [Array<Integer>]
+          def apply(params)
+            params = [0] if params.empty?
+            i = 0
+            i += apply_one(params, i) while i < params.length
+            @serialized = nil
+          end
+
+          # @return [String, nil] compact SGR params ("1;38;5;196") or nil when default
+          def to_params
+            if @serialized.nil?
+              parts = @flags.keys.map { |flag| FLAG_SGR[flag] }
+              parts << @fg if @fg
+              parts << @bg if @bg
+              @serialized = parts.empty? ? false : parts.join(";").freeze
+            end
+            @serialized || nil
+          end
+
+          private
+
+          # @return [Integer] number of params consumed
+          def apply_one(params, index)
+            code = params[index] || 0
+            case code
+            when 0 then reset
+            when *SET_CODES.keys then @flags[SET_CODES[code]] = true
+            when *RESET_CODES.keys then RESET_CODES[code].each { |flag| @flags.delete(flag) }
+            when 30..37, 90..97 then @fg = code.to_s
+            when 40..47, 100..107 then @bg = code.to_s
+            when 39 then @fg = nil
+            when 49 then @bg = nil
+            when 38, 48 then return apply_extended_color(params, index)
+            end
+            1
+          end
+
+          def apply_extended_color(params, index)
+            target = params[index] == 38 ? :fg= : :bg=
+            case params[index + 1]
+            when 5
+              send(target, params[index..(index + 2)].join(";")) if params[index + 2]
+              3
+            when 2
+              send(target, params[index..(index + 4)].join(";")) if params[index + 4]
+              5
+            else
+              1
+            end
+          end
+
+          attr_writer :fg, :bg
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module TTY
+  class Command
+    module Window
+      # One live window in the terminal: an emulator plus title-bar state.
+      #
+      # Blocks are registered with a {Coordinator}, which stacks and paints
+      # them. All emulator access is synchronized through the block's mutex
+      # because the runner thread feeds data while the render thread paints.
+      class Block
+        SUCCESS_GLYPH = "✔"
+        FAILURE_GLYPH = "✖"
+        FOCUSED_MARKER = "▸ "
+        UNFOCUSED_MARKER = "▹ "
+
+        attr_reader :lines, :on_exit, :status
+        attr_accessor :focused
+
+        # @param emulator [Emulator]
+        # @param title [String, false] title text; false disables the title bar
+        # @param lines [Integer] window height (emulator rows)
+        # @param on_exit [Symbol] :freeze, :dump_on_failure or :collapse
+        # @param interactive [Boolean] eligible for stdin focus
+        def initialize(emulator:, title:, lines:, on_exit:, interactive: false)
+          @emulator = emulator
+          @title_enabled = title != false
+          @title_text = title.is_a?(String) ? title : ""
+          @lines = lines
+          @on_exit = on_exit
+          @interactive = interactive
+          @status = :running
+          @started_at = Block.clock
+          @runtime = nil
+          @focused = false
+          @mutex = Mutex.new
+        end
+
+        def self.clock
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        # Feed raw child output into the emulator.
+        def feed(data)
+          @mutex.synchronize { @emulator.feed(data) }
+        end
+
+        # Mark the block finished.
+        #
+        # @param success [Boolean]
+        # @param runtime [Float] seconds
+        def finish(success, runtime)
+          @runtime = runtime
+          @status = success ? :success : :failure
+        end
+
+        def running?
+          @status == :running
+        end
+
+        def done?
+          !running?
+        end
+
+        def success?
+          @status == :success
+        end
+
+        def failure?
+          @status == :failure
+        end
+
+        def interactive?
+          @interactive
+        end
+
+        def collapsed?
+          done? && @on_exit == :collapse
+        end
+
+        # Whether finalization should replace this block with its full history.
+        def dump_on_finalize?
+          failure? && @on_exit == :dump_on_failure
+        end
+
+        # Rendered height in terminal lines given the current state.
+        def height
+          return 1 if collapsed?
+
+          (@title_enabled ? 1 : 0) + @lines
+        end
+
+        # Render the block to an array of ANSI strings, +height+ elements.
+        #
+        # @param width [Integer] terminal width
+        # @param pastel [Pastel::Delegator]
+        # @param frame [String] current spinner frame
+        # @return [Array<String>]
+        def render(width:, pastel:, frame:)
+          @mutex.synchronize do
+            out = []
+            out << title_line(width, pastel, frame) if @title_enabled || collapsed?
+            out.concat(@emulator.render_lines) unless collapsed?
+            out
+          end
+        end
+
+        # Full plain-text history (scrollback + visible screen).
+        def full_text
+          @mutex.synchronize { @emulator.full_text }
+        end
+
+        # Plain title line plus history, used when dumping on failure.
+        def dump_text(pastel)
+          "#{status_glyph(pastel)} #{@title_text} #{pastel.dim("• #{elapsed_text}")}\n#{full_text}"
+        end
+
+        # Resize the emulator to a new terminal width. PTY resize is
+        # owned by {ChildSession}.
+        def resize(width)
+          @mutex.synchronize { @emulator.resize(cols: width) }
+        end
+
+        private
+
+        def elapsed_text
+          seconds = @runtime || (Block.clock - @started_at)
+          if seconds >= 3600
+            format("%<h>dh %<m>02dm", h: seconds / 3600, m: (seconds % 3600) / 60)
+          elsif seconds >= 60
+            format("%<m>dm %<s>02ds", m: seconds / 60, s: seconds % 60)
+          else
+            format("%<s>.1fs", s: seconds)
+          end
+        end
+
+        def status_glyph(pastel)
+          success? ? pastel.green(SUCCESS_GLYPH) : pastel.red(FAILURE_GLYPH)
+        end
+
+        def title_line(width, pastel, frame)
+          marker = running? ? pastel.cyan(frame) : status_glyph(pastel)
+          focus =
+            if interactive? && running?
+              @focused ? pastel.yellow.bold(FOCUSED_MARKER) : pastel.dim(UNFOCUSED_MARKER)
+            else
+              ""
+            end
+          suffix = pastel.dim("• #{elapsed_text}")
+          budget = width - 2 - (focus.empty? ? 0 : 2) - display_width(strip_len(suffix)) - 1
+          title = truncate_display(@title_text, budget)
+          title = pastel.inverse(title) if @focused && interactive? && running?
+          "#{marker} #{focus}#{title} #{suffix}"
+        end
+
+        def strip_len(text)
+          ANSI.strip(text)
+        end
+
+        def display_width(text)
+          Unicode::DisplayWidth.of(text)
+        end
+
+        def truncate_display(text, budget)
+          return "" if budget <= 0
+          return text if display_width(text) <= budget
+
+          out = +""
+          used = 0
+          text.each_char do |char|
+            char_width = display_width(char)
+            break if used + char_width > budget - 1
+
+            out << char
+            used += char_width
+          end
+          "#{out}…"
+        end
+      end
+    end
+  end
+end