tty-command-window 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b39102b7bfbae84d31acca3a966ca18b2553381a5dc2085a13bd98308959ba0
-  data.tar.gz: 75928be1bb72d1e7dfdd43e5e0b6678089f4c698f215fe6ec51b821cc07915cb
+  metadata.gz: e113fbc7a82f69f888cf1b28b007f526077c813bddbdc5d81be332f47f8b95d5
+  data.tar.gz: 529b3ea936fdcfe996fa199bdf4314fad0833d1d1ab4154afb788a1073c78358
 SHA512:
-  metadata.gz: 3f9b8bad3b0255f783a37cfa94820df78b4a11841ca12e94331fd372ded05dfe1ea46b1d46fb974d61fe16d18a70befceff5a592f03d11acc2f07bde83f97de0
-  data.tar.gz: 957da48ba1ffcc5a4776331975ae4f12e015a82cb9be1fe32dff96c46fd9d11cb7c5797c85cd31b7333b6190ada92ae03a0ace1b97fcadc5c7e8332ef8747b49
+  metadata.gz: 84e815c903062e5e30b68f998b1fcfd31d722a21738323bf867062015958bf09c3cf20da729ed60dd255e04e630eb482cf030b970e47d16350fbec5db8dde387
+  data.tar.gz: 68ddebea7c5e5a164fa9db3b445dae0d3c3728301c9c340388519575704de769356027f4a1f9e5c810ef46181407c06a66612d43bdd6b357cd44c49f475bdb7d

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Step windows: `TTY::Command::Window::Step.open(title:, lines:, ...)` opens a
+  caller-managed window whose lifecycle spans multiple commands. Run commands
+  into it with `cmd.run_windowed("...", window: step)` (or the `step.run` /
+  `step.run!` sugar), append plain lines with `step.log`, rename the title bar
+  with `step.retitle`, and close it with `step.finish(success:)`. The title
+  bar doubles as a progress line. A block form finishes automatically.
+- `on_exit: :collapse_or_dump` — on success the window is replaced by its
+  one-line `✔ title • elapsed` summary as permanent scrolled output; on
+  failure the output history is dumped. Sequential steps leave a compact
+  checklist behind. This is the default mode for step windows.
+- `dump_lines:` — caps how many history lines a failure dump prints; the
+  head is replaced by a truncation marker. Default: unlimited.
+- When windowed rendering is unavailable (no TTY, Windows, no PTY),
+  `Step.open` returns a `PlainStep` with the same interface: a start marker
+  and `✔`/`✖` summary line as plain text, with command output streamed in
+  full between them — calling code needs no branch, and CI logs get a
+  readable checklist.
+
+## [0.1.0] - 2026-08-12
+
 ### Changed
 
 - **Renamed the `tty:` option to `window:`**. The old name was ambiguous
@@ -49,6 +71,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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/README.md

@@ -107,6 +107,45 @@ end.each(&:join)
 
 ![three concurrent windows](docs/demo-multi.gif)
 
+### Step windows
+
+A step is a window you open yourself, feed several commands (and plain log
+lines), and close when the logical unit of work is done — the shape of a
+step in a CLI progress checklist:
+
+```ruby
+step = TTY::Command::Window::Step.open(title: "starting containers", lines: 8)
+cmd = TTY::Command.new(printer: :null)
+
+cmd.run_windowed("docker compose pull", window: step)
+step.log "images pulled, starting"
+result = cmd.run_windowed!("docker compose up -d", window: step)
+
+step.finish(success: result.success?)
+```
+
+The title bar doubles as the progress line: spinner while open, then
+`✔ starting containers • 12.3s`. Steps default to `on_exit: :collapse_or_dump`:
+on success the window is replaced by that one-line summary as permanent
+output (sequential steps leave a compact checklist behind); on failure the
+full output history is dumped — cap it with `dump_lines: 200`. `step.run` /
+`step.run!` are sugar for `run_windowed(..., window: step)`, and a block form
+finishes the step automatically:
+
+```ruby
+TTY::Command::Window::Step.open(title: "deps") do |step|
+  step.run(cmd, "bundle install")
+  step.run(cmd, "yarn install")
+end
+```
+
+Geometry and end-of-run behavior (`lines:`, `title:`, `on_exit:`,
+`scrollback:`, `dump_lines:`) are fixed at `Step.open` time; per-run calls
+accept only `capture:`, `capture_max_bytes:` and `output_log:`. Without a
+TTY, `Step.open` returns a `PlainStep` with the same interface — plain
+start/summary marker lines with full streamed output between them, so the
+same code produces a readable CI log.
+
 ### Interactive commands
 
 ```ruby

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

@@ -22,15 +22,19 @@ module TTY
         # @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 on_exit [Symbol] :freeze, :dump_on_failure, :collapse or
+        #   :collapse_or_dump
         # @param interactive [Boolean] eligible for stdin focus
-        def initialize(emulator:, title:, lines:, on_exit:, interactive: false)
+        # @param dump_lines [Integer, nil] cap on history lines printed when
+        #   dumping on failure; nil dumps everything
+        def initialize(emulator:, title:, lines:, on_exit:, interactive: false, dump_lines: nil)
           @emulator = emulator
           @title_enabled = title != false
           @title_text = title.is_a?(String) ? title : ""
           @lines = lines
           @on_exit = on_exit
           @interactive = interactive
+          @dump_lines = dump_lines
           @status = :running
           @started_at = Block.clock
           @runtime = nil
@@ -77,12 +81,21 @@ module TTY
         end
 
         def collapsed?
-          done? && @on_exit == :collapse
+          done? && (@on_exit == :collapse || (@on_exit == :collapse_or_dump && success?))
         end
 
         # Whether finalization should replace this block with its full history.
         def dump_on_finalize?
-          failure? && @on_exit == :dump_on_failure
+          failure? && %i[dump_on_failure collapse_or_dump].include?(@on_exit)
+        end
+
+        # Whether finalization should replace this block with its one-line
+        # summary as permanent scrolled output. Distinct from {#collapsed?}
+        # (which keeps the line inside the live region) so that sequential
+        # step windows leave a scrolling checklist behind instead of an
+        # ever-growing region.
+        def retire_on_finalize?
+          success? && @on_exit == :collapse_or_dump
         end
 
         # Rendered height in terminal lines given the current state.
@@ -112,9 +125,27 @@ module TTY
           @mutex.synchronize { @emulator.full_text }
         end
 
+        # Replace the title-bar text.
+        def retitle(title)
+          @mutex.synchronize { @title_text = title.to_s }
+        end
+
         # Plain title line plus history, used when dumping on failure.
+        # Honors the +dump_lines+ cap: only the trailing lines are kept,
+        # with a truncation marker in their place.
         def dump_text(pastel)
-          "#{status_glyph(pastel)} #{@title_text} #{pastel.dim("• #{elapsed_text}")}\n#{full_text}"
+          summary = "#{status_glyph(pastel)} #{@title_text} #{pastel.dim("• #{elapsed_text}")}"
+          "#{summary}\n#{capped_history(pastel)}"
+        end
+
+        # The one-line summary written as permanent output when a
+        # :collapse_or_dump block finishes successfully.
+        #
+        # @param width [Integer] terminal width
+        # @param pastel [Pastel::Delegator]
+        # @return [String]
+        def summary_line(width:, pastel:)
+          @mutex.synchronize { title_line(width, pastel, "") }
         end
 
         # Resize the emulator to a new terminal width. PTY resize is
@@ -125,15 +156,21 @@ module TTY
 
         private
 
+        def capped_history(pastel)
+          text = full_text
+          return text unless @dump_lines
+
+          lines = text.split("\n", -1)
+          return text if lines.length <= @dump_lines
+
+          marker = pastel.dim(
+            "… earlier output truncated (showing last #{@dump_lines} of #{lines.length} lines)"
+          )
+          ([marker] + lines.last(@dump_lines)).join("\n")
+        end
+
         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
+          Window.format_elapsed(@runtime || (Block.clock - @started_at))
         end
 
         def status_glyph(pastel)

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

@@ -106,6 +106,10 @@ module TTY
               wipe_region
               @blocks.delete(block)
               write_permanent(block.dump_text(@pastel))
+            elsif block.retire_on_finalize?
+              wipe_region
+              @blocks.delete(block)
+              write_permanent(block.summary_line(width: width, pastel: @pastel))
             end
             # Drop the session unconditionally: the child has been reaped by
             # Runner and its PID is no longer safe to signal. Leaving stale
@@ -121,6 +125,23 @@ module TTY
           join_render_thread if drained
         end
 
+        # Attach a child session to an already-registered block so signal
+        # forwarding and PTY resize reach it. Used by step windows, whose
+        # blocks outlive any single command.
+        #
+        # @param block [Block]
+        # @param session [ChildSession]
+        def attach_session(block, session)
+          @mutex.synchronize { @sessions[block] = session }
+        end
+
+        # Detach the session attached via {#attach_session}.
+        #
+        # @param block [Block]
+        def detach_session(block)
+          @mutex.synchronize { @sessions.delete(block) }
+        end
+
         # Request a repaint on the next frame (cheap, lock-free).
         def mark_dirty
           @dirty = true
@@ -159,9 +180,12 @@ module TTY
         end
 
         # Must be called while holding @mutex; the caller joins the render
-        # thread outside the lock afterwards.
+        # thread outside the lock afterwards. When every block was retired
+        # or dumped the region is already empty and the cursor sits at
+        # column 0 of a fresh line — adding a newline there would leave a
+        # blank line between sequential step windows.
         def drain
-          @output.write("\r\n#{SHOW_CURSOR}")
+          @output.write("#{"\r\n" if @painted_height.positive?}#{SHOW_CURSOR}")
           @blocks.clear
           @sessions.clear
           @painted_height = 0

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

@@ -67,12 +67,23 @@ module TTY
           execute_windowed(args, raise_on_error: false, &)
         end
 
+        # Option keys that may accompany +window: <step>+; everything else
+        # is fixed at Step.open time.
+        STEP_RUN_KEYS = %i[window capture capture_max_bytes output_log].freeze
+
         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)
+
+          target = window_options[:window]
+          if target.is_a?(Step) || target.is_a?(PlainStep)
+            return execute_in_step(target, window_options, plain_args,
+                                   raise_on_error: raise_on_error, &block)
+          end
+
           output = window_options[:output] || printer.output
 
           unless windowed_renderable?(window_options, output)
@@ -94,6 +105,39 @@ module TTY
           result
         end
 
+        # Run a command inside an existing step window. The step's block is
+        # reused (the step stays open afterwards); only per-run options are
+        # accepted here — geometry and end-of-run behavior were fixed when
+        # the step was opened.
+        def execute_in_step(step, window_options, plain_args, raise_on_error:, &block)
+          invalid = window_options.keys - STEP_RUN_KEYS
+          if invalid.any?
+            raise ArgumentError,
+                  "options not allowed with window: <step>: #{invalid.join(', ')} " \
+                  "(set them when opening the step)"
+          end
+          raise ArgumentError, "cannot run a command in a finished step" unless step.active?
+
+          if step.is_a?(PlainStep) || dry_run?
+            tee = lambda do |chunk, err|
+              step.write_output(chunk) if chunk && step.is_a?(PlainStep)
+              block&.call(chunk, err)
+            end
+            return raise_on_error ? run(*plain_args, &tee) : run!(*plain_args, &tee)
+          end
+
+          cmd = build_cmd(plain_args)
+          options = Window.normalize_options(
+            window_options.except(:window).merge(lines: step.lines, title: false),
+            cmd
+          )
+          result = Runner.new(cmd, options, step.coordinator, step: step, &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,

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

@@ -21,11 +21,15 @@ module TTY
         # @param cmd [TTY::Command::Cmd]
         # @param options [WindowOptions] validated window options
         # @param coordinator [Coordinator]
+        # @param step [Step, nil] when given, the command renders into the
+        #   step's existing block instead of a block of its own; the step
+        #   stays open after the command finishes
         # @param stream_block [Proc, nil] yields (chunk, nil) like tty-command
-        def initialize(cmd, options, coordinator, &stream_block)
+        def initialize(cmd, options, coordinator, step: nil, &stream_block)
           @cmd = cmd
           @options = options
           @coordinator = coordinator
+          @step = step
           @stream_block = stream_block
         end
 
@@ -35,19 +39,24 @@ module TTY
           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
+          if @step
+            @block = @step.block
+          else
+            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?,
+              dump_lines: @options.dump_lines
+            )
+            @emulator = emulator
+          end
 
           @session = spawn_child(rows, width)
           started = clock
@@ -59,8 +68,12 @@ module TTY
           @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?
+          if @step
+            @step.adopt_session(@session)
+          else
+            @coordinator.register(@block, child_session: @session)
+            InputRouter.attach(@block, @session, @coordinator) if @options.interactive?
+          end
 
           write_initial_input
           timed_out = timed_out_pumping?
@@ -194,7 +207,15 @@ module TTY
           end
         end
 
+        # For step runs the block belongs to the step: it stays running and
+        # is finished later by Step#finish; only the session is released.
         def finish(status, runtime, timed_out)
+          if @step
+            @finished = true
+            @step.release_session
+            return
+          end
+
           success = !timed_out && !status.nil? && status.success?
           @block.finish(success, runtime)
           InputRouter.detach(@block) if @options.interactive?
@@ -227,9 +248,17 @@ module TTY
         end
 
         # Ensure the child is dead and the block finalized even when the
-        # pump raised (Interrupt, timeout, IO errors).
+        # pump raised (Interrupt, timeout, IO errors). For step runs the
+        # block is never finalized here — the step owns it — but the child
+        # must still die and the session detach from the step.
         def cleanup
-          if @block&.running?
+          if @step
+            unless @finished
+              @session&.signal("SIGKILL")
+              wait_status if @session
+              @step.release_session
+            end
+          elsif @block&.running?
             @session&.signal("SIGKILL")
             wait_status
             @block.finish(false, 0.0)

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

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module TTY
+  class Command
+    module Window
+      # A caller-managed window whose lifecycle spans multiple commands.
+      #
+      # Where {Integration#run_windowed} opens a window for exactly one
+      # command, a step is opened explicitly, fed any number of commands
+      # (via +cmd.run_windowed(..., window: step)+ or {#run} / {#run!}),
+      # interleaved with plain {#log} lines, and closed with {#finish}.
+      # The title bar doubles as a progress line: spinner while open,
+      # +✔/✖ title • elapsed+ once finished.
+      #
+      # @example A build step with two commands and a note
+      #   step = TTY::Command::Window::Step.open(title: "building", lines: 8)
+      #   cmd = TTY::Command.new(printer: :null)
+      #   cmd.run_windowed("make deps", window: step)
+      #   step.log "deps done, compiling"
+      #   result = cmd.run_windowed!("make -j8", window: step)
+      #   step.finish(success: result.success?)
+      #
+      # When the environment cannot render windows (no TTY, Windows, no
+      # PTY), {.open} returns a {PlainStep} with the same interface: start
+      # and summary lines are printed as plain text and commands stream
+      # their full output, so calling code never needs a branch.
+      class Step
+        attr_reader :lines
+
+        # Open a step window (or a {PlainStep} fallback).
+        #
+        # @param title [String] title-bar text
+        # @param lines [Integer] window height (also the PTY row count
+        #   commands see)
+        # @param output [IO] render target
+        # @param width [Integer, nil] fixed render width override
+        # @param on_exit [Symbol] :collapse_or_dump (default), :freeze,
+        #   :dump_on_failure or :collapse
+        # @param scrollback [Integer] plain-text history limit
+        # @param dump_lines [Integer, nil] cap on history lines printed by a
+        #   failure dump; nil dumps everything
+        # @param window [Boolean, nil] force (+true+) or forbid (+false+)
+        #   windowed rendering, overriding TTY / PTY detection
+        #
+        # @yield [step] optional block form; the step is finished with
+        #   +success: true+ on normal return and +success: false+ when the
+        #   block raises (the exception propagates)
+        # @return [Step, PlainStep] the block form returns the block's value
+        def self.open(title:, lines: DEFAULT_LINES, output: $stdout, width: nil,
+                      on_exit: :collapse_or_dump, scrollback: DEFAULT_SCROLLBACK,
+                      dump_lines: nil, window: nil)
+          validate!(lines, on_exit, dump_lines)
+
+          step =
+            if renderable?(window, output)
+              new(title: title, lines: lines, output: output, width: width,
+                  on_exit: on_exit, scrollback: scrollback, dump_lines: dump_lines)
+            else
+              PlainStep.new(title: title, output: output)
+            end
+          return step unless block_given?
+
+          begin
+            result = yield step
+            step.finish(success: true)
+            result
+          rescue Exception # rubocop:disable Lint/RescueException
+            step.finish(success: false)
+            raise
+          end
+        end
+
+        def self.renderable?(window, output)
+          case window
+          when true then !Window.windows? && Window.pty_available?
+          when false then false
+          else Window.renderable?(output)
+          end
+        end
+        private_class_method :renderable?
+
+        def self.validate!(lines, on_exit, dump_lines)
+          raise ArgumentError, "lines must be >= 1" if Integer(lines) < 1
+          unless ON_EXIT_MODES.include?(on_exit)
+            raise ArgumentError, "on_exit must be one of #{ON_EXIT_MODES.join(', ')}"
+          end
+          return unless dump_lines && Integer(dump_lines) < 1
+
+          raise ArgumentError,
+                "dump_lines must be >= 1 or nil"
+        end
+        private_class_method :validate!
+
+        # @api private Use {.open}.
+        def initialize(title:, lines:, output:, width:, on_exit:, scrollback:, dump_lines:)
+          @lines = lines
+          @coordinator = Coordinator.for(output, width: width)
+          @session = nil
+          @session_mutex = Mutex.new
+          @emulator = Emulator.new(
+            rows: lines, cols: @coordinator.width,
+            scrollback_limit: scrollback,
+            responder: ->(reply) { write_to_child(reply) }
+          )
+          @block = Block.new(
+            emulator: @emulator, title: title, lines: lines,
+            on_exit: on_exit, dump_lines: dump_lines
+          )
+          @active = true
+          @started_at = Block.clock
+          @coordinator.register(@block)
+        end
+
+        # @return [Boolean] false once {#finish} has run
+        def active?
+          @active
+        end
+
+        # Append plain text lines to the window, as if the child had
+        # printed them. Embedded ANSI colors are interpreted normally.
+        #
+        # @param text [String]
+        # @return [self]
+        def log(text)
+          return self unless @active
+
+          body = +""
+          # Start on a fresh line when a child left the cursor mid-line.
+          body << "\r\n" if @emulator.cursor_col.positive?
+          body << text.to_s.gsub("\n", "\r\n")
+          body << "\r\n" unless body.end_with?("\r\n")
+          @block.feed(body)
+          @coordinator.mark_dirty
+          self
+        end
+
+        # Replace the title-bar text.
+        #
+        # @param title [String]
+        # @return [self]
+        def retitle(title)
+          @block.retitle(title)
+          @coordinator.mark_dirty
+          self
+        end
+
+        # Run a command inside this step's window; raises
+        # +TTY::Command::ExitError+ on failure like +#run+.
+        #
+        # Sugar for +cmd.run_windowed(*args, window: self)+.
+        #
+        # @param cmd [TTY::Command]
+        # @return [TTY::Command::Result]
+        def run(cmd, *args, &)
+          cmd.run_windowed(*args_with_window(args), &)
+        end
+
+        # Same as {#run} but never raises on non-zero exit.
+        #
+        # @return [TTY::Command::Result]
+        def run!(cmd, *args, &)
+          cmd.run_windowed!(*args_with_window(args), &)
+        end
+
+        # Close the step: the title bar shows ✔/✖ and the window ends
+        # according to its +on_exit+ mode (for the default
+        # :collapse_or_dump — success leaves a one-line summary in the
+        # scrollback, failure dumps the output history).
+        #
+        # @param success [Boolean]
+        # @return [self]
+        def finish(success: true)
+          return self unless @active
+
+          @active = false
+          @block.finish(success ? true : false, Block.clock - @started_at)
+          @coordinator.finalize(@block)
+          self
+        end
+
+        # @api private Runner protocol: the block backing this step.
+        attr_reader :block
+
+        # @api private Runner protocol: the coordinator rendering this step.
+        attr_reader :coordinator
+
+        # @api private Runner protocol: a command's child session started.
+        def adopt_session(session)
+          @session_mutex.synchronize { @session = session }
+          @coordinator.attach_session(@block, session)
+        end
+
+        # @api private Runner protocol: the child session ended.
+        def release_session
+          @session_mutex.synchronize { @session = nil }
+          @coordinator.detach_session(@block)
+          @coordinator.mark_dirty
+        end
+
+        private
+
+        def write_to_child(reply)
+          session = @session_mutex.synchronize { @session }
+          session&.write(reply)
+        end
+
+        def args_with_window(args)
+          if args.last.respond_to?(:to_hash)
+            args[0..-2] + [args.last.to_hash.merge(window: self)]
+          else
+            args + [{ window: self }]
+          end
+        end
+      end
+
+      # Fallback step for environments without windowed rendering: the
+      # same interface as {Step}, rendered as plain scrolling text.
+      # Commands stream their full output between a start marker and a
+      # ✔/✖ summary line.
+      class PlainStep
+        attr_reader :output
+
+        def initialize(title:, output:)
+          @title = title.to_s
+          @output = output
+          @active = true
+          @at_line_start = true
+          @started_at = Block.clock
+          @pastel = Pastel.new(enabled: color?)
+          @output.puts("#{@pastel.dim('──')} #{@title}")
+        end
+
+        # @return [Boolean] false once {#finish} has run
+        def active?
+          @active
+        end
+
+        # @param text [String]
+        # @return [self]
+        def log(text)
+          @output.write("\n") unless @at_line_start
+          @at_line_start = true
+          @output.puts(text)
+          self
+        end
+
+        # @param title [String]
+        # @return [self]
+        def retitle(title)
+          @title = title.to_s
+          self
+        end
+
+        # (see Step#run)
+        def run(cmd, *args, &)
+          cmd.run_windowed(*args_with_window(args), &)
+        end
+
+        # (see Step#run!)
+        def run!(cmd, *args, &)
+          cmd.run_windowed!(*args_with_window(args), &)
+        end
+
+        # Print the ✔/✖ summary line.
+        #
+        # @param success [Boolean]
+        # @return [self]
+        def finish(success: true)
+          return self unless @active
+
+          @active = false
+          @output.write("\n") unless @at_line_start
+          glyph = success ? @pastel.green(Block::SUCCESS_GLYPH) : @pastel.red(Block::FAILURE_GLYPH)
+          elapsed = Window.format_elapsed(Block.clock - @started_at)
+          @output.puts("#{glyph} #{@title} #{@pastel.dim("• #{elapsed}")}")
+          self
+        end
+
+        # @api private Integration protocol: stream a command output chunk.
+        def write_output(chunk)
+          @at_line_start = chunk.end_with?("\n") unless chunk.empty?
+          @output.write(chunk)
+        end
+
+        private
+
+        def color?
+          return false if ENV.key?("NO_COLOR")
+
+          Window.assume_tty || (@output.respond_to?(:tty?) && @output.tty?)
+        end
+
+        def args_with_window(args)
+          if args.last.respond_to?(:to_hash)
+            args[0..-2] + [args.last.to_hash.merge(window: self)]
+          else
+            args + [{ window: self }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module TTY
   class Command
     module Window
-      VERSION = "0.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

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

@@ -16,7 +16,7 @@ module TTY
       # frozen in {.build} for immutability.
       WindowOptions = Struct.new(
         :lines, :title, :on_exit, :capture, :capture_max_bytes,
-        :scrollback, :output_log, :interactive,
+        :scrollback, :output_log, :interactive, :dump_lines,
         keyword_init: true
       ) do
         # @param window_options [Hash] the raw window options subset
@@ -36,6 +36,12 @@ module TTY
             raise ArgumentError, "capture_max_bytes must be >= 1 or nil" if capture_max_bytes < 1
           end
 
+          dump_lines = window_options.fetch(:dump_lines, nil)
+          unless dump_lines.nil?
+            dump_lines = Integer(dump_lines)
+            raise ArgumentError, "dump_lines must be >= 1 or nil" if dump_lines < 1
+          end
+
           Window.validate_on_unavailable!(window_options)
 
           title = window_options.fetch(:title, nil)
@@ -49,7 +55,8 @@ module TTY
             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
+            interactive: window_options[:interactive] == true,
+            dump_lines: dump_lines
           ).freeze
         end
 

data/lib/tty/command/window.rb

@@ -14,6 +14,7 @@ require_relative "window/coordinator"
 require_relative "window/input_router"
 require_relative "window/window_options"
 require_relative "window/runner"
+require_relative "window/step"
 require_relative "window/integration"
 
 module TTY
@@ -31,10 +32,10 @@ module TTY
       # 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
+        capture_max_bytes output window width on_unavailable tty dump_lines
       ].freeze
 
-      ON_EXIT_MODES = %i[freeze dump_on_failure collapse].freeze
+      ON_EXIT_MODES = %i[freeze dump_on_failure collapse collapse_or_dump].freeze
       CAPTURE_MODES = %i[raw stripped screen].freeze
       ON_UNAVAILABLE_MODES = %i[fallback raise].freeze
 
@@ -102,6 +103,21 @@ module TTY
         def strip_ansi(text)
           ANSI.strip(text)
         end
+
+        # Human-readable elapsed time, as shown in title bars and step
+        # summaries.
+        #
+        # @param seconds [Float]
+        # @return [String]
+        def format_elapsed(seconds)
+          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
       end
 
       self.assume_tty = false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tty-command-window
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michal Matyas
@@ -64,7 +64,7 @@ description: 'Extends tty-command with run_windowed: the child process runs in a
   in place. Supports stacked concurrent windows, interactive stdin with focus switching,
   resize handling and failure dumps.'
 email:
-- michal.matyas@helpling.com
+- github@higher.lv
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -83,16 +83,17 @@ files:
 - lib/tty/command/window/integration.rb
 - lib/tty/command/window/runner.rb
 - lib/tty/command/window/spinner.rb
+- lib/tty/command/window/step.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
+homepage: https://github.com/d4rky-pl/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
+  homepage_uri: https://github.com/d4rky-pl/tty-command-window
+  source_code_uri: https://github.com/d4rky-pl/tty-command-window
+  changelog_uri: https://github.com/d4rky-pl/tty-command-window/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []