letsdo 0.1.0 → 0.2.0

data/lib/letsdo/tui/renderer.rb

@@ -4,8 +4,8 @@ module Letsdo
   module Tui
     # The frame renderer: a pure function from state to text.
     #
-    #   (metrics snapshot, log lines, terminal width/height,
-    #    view offset / follow / paused) → a framed String
+    #   (metrics snapshot, log lines, terminal size, view,
+    #    wait interval) → a framed String
     #
     # Pure means: no IO, no terminal, no clock — the same inputs always
     # produce the same string, so every rendering path (session controller,
@@ -17,35 +17,37 @@ module Letsdo
     #   done 3 · left 2 · task TASK-42 · 00:03:21
     #   ├────────────────────────────────────────────────────────────┤
     #   <body_height scrollable log lines, newest at the bottom>
-    #   ↑/↓ PgUp/PgDn scroll · p pause · r refresh · q quit
+    #   ↑/↓ PgUp/PgDn scroll · p pause/resume · r refresh · q quit
     module Renderer
       HEADER_HEIGHT = 2
       FOOTER_HEIGHT = 1
       DIVIDER_HEIGHT = 1
-      ELLIPSIS = "…"
+      ELLIPSIS = '…'
 
       # Renders the full frame.
       #
       # @param metrics [Metrics::Snapshot] header metrics snapshot
       # @param lines [Array<String>] log lines, oldest first
-      # @param width [Integer] terminal width in columns
-      # @param height [Integer] terminal height in rows (>= HEADER_HEIGHT +
-      #        FOOTER_HEIGHT + DIVIDER_HEIGHT + 1)
-      # @param offset [Integer] index of the first visible log line
-      # @param follow [Boolean] whether the view sticks to the newest line
-      # @param paused [Boolean] display-freeze state (PAUSED in the header)
+      # @param size [Hash{Symbol => Integer}] :width and :height of the
+      #        terminal (rows >= HEADER_HEIGHT + FOOTER_HEIGHT +
+      #        DIVIDER_HEIGHT + 1)
+      # @param view [Hash{Symbol => Integer, Boolean}] :offset (index of
+      #        the first visible log line) and :paused (display-freeze
+      #        overlay)
       # @param wait_seconds [Numeric] retry interval shown in the waiting
       #        state
       # @return [String] the framed screen, lines joined with "\n"
-      def self.render(metrics:, lines:, width:, height:, offset:, follow:, paused:, wait_seconds: 10.0)
-        body_height = body_height_for(height)
-        frame = []
-        frame << header_line(metrics, width)
-        frame << state_line(metrics, width, paused, wait_seconds)
-        frame << divider_line(width)
-        body_lines(lines, offset, body_height, width).each { |line| frame << line }
-        frame << footer_line(width)
-        frame.join("\n")
+      def self.render(metrics:, lines:, size:, view:, wait_seconds: 10.0)
+        width = size.fetch(:width)
+        paused = view.fetch(:paused)
+        height = body_height_for(size.fetch(:height))
+        [
+          header_line(metrics, width),
+          state_line(metrics, width, paused, wait_seconds),
+          divider_line(width),
+          *body_lines(lines, view.fetch(:offset), height, width),
+          footer_line(width, paused)
+        ].join("\n")
       end
 
       # The number of body lines a terminal of the given height fits.
@@ -65,41 +67,56 @@ module Letsdo
 
       def self.header_line(metrics, width)
         title = "letsdo · #{metrics.name} (#{metrics.handle})"
-        timer = "session #{format_duration(metrics.session_seconds)}"
-        fit_line_with_right(title, timer, width)
+        timer = "session #{Text.format_duration(metrics.session_seconds)}"
+        Text.fit_line_with_right(title, timer, width)
       end
 
       # The state line: done/left plus either the running task with its
       # elapsed time, a waiting reason, or the PAUSED overlay.
       def self.state_line(metrics, width, paused, wait_seconds)
-        parts = ["done #{metrics.done}", "left #{metrics.left.nil? ? "?" : metrics.left}"]
+        parts = ["done #{metrics.done}", "left #{left_or_question(metrics.left)}"]
+        parts.concat(state_overlay(metrics, paused, wait_seconds))
+        Text.fit_line(parts.join(' · '), width)
+      end
+
+      def self.left_or_question(left)
+        left.nil? ? '?' : left
+      end
+
+      # The current-state fragment after "left N ·": task + elapsed time,
+      # a waiting reason, or the PAUSED overlay.
+      def self.state_overlay(metrics, paused, wait_seconds)
         if paused
-          parts << "PAUSED"
+          ['PAUSED']
         elsif metrics.current_task
-          parts << "task #{metrics.current_task}"
-          parts << format_duration(metrics.current_task_seconds) if metrics.current_task_seconds
+          overlay = ["task #{metrics.current_task}"]
+          overlay << Text.format_duration(metrics.current_task_seconds) if metrics.current_task_seconds
+          overlay
         else
-          parts << "waiting: #{waiting_reason(metrics.left, wait_seconds)}"
+          ["waiting: #{waiting_reason(metrics.left, wait_seconds)}"]
         end
-        fit_line(parts.join(" · "), width)
       end
 
       def self.body_lines(lines, offset, body_height, width)
         Array.new(body_height) do |index|
           line = lines[offset + index]
-          line.nil? ? (" " * width) : fit_line(line, width)
+          line.nil? ? (' ' * width) : Text.fit_line(line, width)
         end
       end
 
       def self.divider_line(width)
-        return "" if width < 4
+        return '' if width < 4
 
-        body = "─" * (width - 2)
+        body = '─' * (width - 2)
         "├#{body}┤"
       end
 
-      def self.footer_line(width)
-        fit_line("↑/↓ PgUp/PgDn scroll · p pause · r refresh · q quit", width)
+      # The key-help footer. The 'p' hint mirrors the toggle state:
+      # 'p pause' when the run is active, 'p resume' when it is suspended
+      # (the display is frozen, PAUSED in the header).
+      def self.footer_line(width, paused)
+        hint = paused ? 'p resume' : 'p pause'
+        Text.fit_line("↑/↓ PgUp/PgDn scroll · #{hint} · r refresh · q quit", width)
       end
 
       # "no open tasks, retrying in 10s" style reason for the waiting state.
@@ -111,63 +128,69 @@ module Letsdo
         elsif left.zero?
           "no open tasks#{suffix}"
         else
-          "next task"
+          'next task'
         end
       end
 
-      # HH:MM:SS (hours can exceed two digits for long sessions).
-      def self.format_duration(seconds)
-        total = [seconds.to_i, 0].max
-        hours, remainder = total.divmod(3600)
-        minutes, secs = remainder.divmod(60)
-        format("%02d:%02d:%02d", hours, minutes, secs)
-      end
+      # Text fitting helpers — kept separate so the frame logic stays short.
+      module Text
+        # HH:MM:SS (hours can exceed two digits for long sessions).
+        def self.format_duration(seconds)
+          total = [seconds.to_i, 0].max
+          hours, remainder = total.divmod(3600)
+          minutes, secs = remainder.divmod(60)
+          format('%<hours>02d:%<minutes>02d:%<secs>02d', hours: hours, minutes: minutes, secs: secs)
+        end
 
-      def self.fit_line_with_right(left, right, width)
-        gap = [width - display_width(left) - display_width(right), 0].max
-        fit_line("#{left}#{" " * gap}#{right}", width)
-      end
+        def self.fit_line_with_right(left, right, width)
+          gap = [width - display_width(left) - display_width(right), 0].max
+          fit_line("#{left}#{' ' * gap}#{right}", width)
+        end
 
-      # Fits a line to the width: display-width truncation with an
-      # ellipsis, then whitespace padding so the whole line is rewritten
-      # (a narrow terminal resize leaves no stale content).
-      def self.fit_line(line, width)
-        fitted = fit(line, width)
-        pad = width - display_width(fitted)
-        pad.positive? ? fitted + (" " * pad) : fitted
-      end
+        # Fits a line to the width: display-width truncation with an
+        # ellipsis, then whitespace padding so the whole line is rewritten
+        # (a narrow terminal resize leaves no stale content).
+        def self.fit_line(line, width)
+          fitted = fit(line, width)
+          pad = width - display_width(fitted)
+          pad.positive? ? fitted + (' ' * pad) : fitted
+        end
 
-      # Cuts the line on a character boundary by display width, adding an
-      # ellipsis when anything was cut. Lines within the width are kept
-      # verbatim.
-      def self.fit(line, width)
-        text_width = display_width(line)
-        return line if width >= text_width
-        return "" if width <= 1
-
-        out = +""
-        acc = 0
-        limit = width - display_width(ELLIPSIS)
-        line.each_char do |char|
-          char_width = display_width(char)
-          break if acc + char_width > limit
-
-          out << char
-          acc += char_width
+        # Cuts the line on a character boundary by display width, adding an
+        # ellipsis when anything was cut. Lines within the width are kept
+        # verbatim.
+        def self.fit(line, width)
+          text_width = display_width(line)
+          return line if width >= text_width
+          return '' if width <= 1
+
+          "#{truncate(line, width - display_width(ELLIPSIS))}#{ELLIPSIS}"
         end
-        out << ELLIPSIS
-        out
-      end
 
-      # Display width of a string (Unicode-aware: ✓/⚙/…/CJK are counted
-      # correctly). Requires "unicode/display_width" lazily so the plain
-      # (non-TTY) path needs no extra gems.
-      def self.display_width(text)
-        return 0 if text.nil? || text.empty?
+        # Characters of the line that fit into the width budget.
+        def self.truncate(line, budget)
+          out = +''
+          acc = 0
+          line.each_char do |char|
+            char_width = display_width(char)
+            break if acc + char_width > budget
+
+            out << char
+            acc += char_width
+          end
+          out
+        end
+
+        # Display width of a string (Unicode-aware: ✓/⚙/…/CJK are counted
+        # correctly). Requires "unicode/display_width" lazily so the plain
+        # (non-TTY) path needs no extra gems.
+        def self.display_width(text)
+          return 0 if text.nil? || text.empty?
 
-        require "unicode/display_width"
-        Unicode::DisplayWidth.of(text)
+          require 'unicode/display_width'
+          Unicode::DisplayWidth.of(text)
+        end
       end
     end
   end
-end
+end

data/lib/letsdo/tui/session/keys.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # Keyboard actions for the TUI session input thread.
+    module SessionKeys
+      private
+
+      KEY_METHODS = {
+        up: :scroll_up,
+        page_up: :scroll_page_up,
+        down: :scroll_down,
+        page_down: :scroll_page_down,
+        home: :go_home,
+        end: :go_end,
+        p: :pause_key,
+        r: :refresh_key,
+        q: :quit_key,
+        ctrl_c: :quit_key
+      }.freeze
+
+      def handle_key(key)
+        send(KEY_METHODS.fetch(key, :ignore_key))
+      end
+
+      def scroll_up
+        @offset -= 1
+        @follow = false
+        true
+      end
+
+      def scroll_page_up
+        @offset -= page_step
+        @follow = false
+        true
+      end
+
+      def scroll_down
+        @offset += 1
+        true
+      end
+
+      def scroll_page_down
+        @offset += page_step
+        true
+      end
+
+      def go_home
+        @offset = 0
+        @follow = false
+        true
+      end
+
+      def go_end
+        @follow = true
+        true
+      end
+
+      def pause_key
+        toggle_pause
+        true
+      end
+
+      def refresh_key
+        refresh
+        true
+      end
+
+      def quit_key
+        quit
+        false
+      end
+
+      def ignore_key
+        false
+      end
+
+      def refresh
+        return unless @refresh
+
+        @metrics.provider_result(@refresh.call)
+      end
+
+      def toggle_pause
+        @paused = !@paused
+        send(@paused ? :engage_pause : :engage_resume)
+      end
+
+      def engage_pause
+        invoke_gate(:pause)
+        invoke_runner(:pause)
+      end
+
+      def engage_resume
+        invoke_gate(:resume)
+        invoke_runner(:resume)
+      end
+
+      def invoke_gate(action)
+        gate = @pause_gate
+        return unless gate
+
+        gate.public_send(action)
+      end
+
+      def invoke_runner(action)
+        runner = @runner.call if @runner
+        return unless runner
+
+        runner.public_send(action)
+      end
+
+      def quit
+        return if @stop
+
+        @stop = true
+        Thread.main.raise(Letsdo::Stopped)
+      end
+    end
+  end
+end

data/lib/letsdo/tui/session/view.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # Frame painting and view-offset tracking for the TUI session.
+    module SessionView
+      private
+
+      def input_loop
+        with_raw_input do
+          repaint
+          @last_repaint = @clock.call
+          loop { break if @stop || !poll_once }
+        end
+      rescue StandardError
+        nil
+      end
+
+      def poll_once
+        handled = process_input
+        if handled || (!@paused && (tick? || new_data?))
+          repaint
+          @last_repaint = @clock.call
+        else
+          sleep(Session::IDLE_SLEEP)
+        end
+        true
+      end
+
+      def process_input
+        key = @input.next_key
+        handled = key ? handle_key(key) : false
+        take_winch ? true : handled
+      end
+
+      def tick?
+        @clock.call - @last_repaint >= Session::REPAINT_INTERVAL
+      end
+
+      def new_data?
+        @log.version != @seen_version
+      end
+
+      def take_winch
+        flag = @winch
+        @winch = false
+        flag
+      end
+
+      def repaint
+        lines, version = @log.lines
+        @seen_version = version
+        height, width = @terminal.size
+        @body_height = Renderer.body_height_for(height)
+        update_offset(lines)
+        @terminal.render(frame_for(lines, width, height))
+      end
+
+      def update_offset(lines)
+        max_offset = Renderer.max_offset(lines, @body_height)
+        if @paused
+          @offset = clamp_offset(max_offset)
+        elsif @follow
+          @offset = max_offset
+        else
+          @offset = clamp_offset(max_offset)
+          @follow = true if @offset == max_offset
+        end
+      end
+
+      def clamp_offset(max_offset)
+        [[@offset, max_offset].min, 0].max
+      end
+
+      def frame_for(lines, width, height)
+        Renderer.render(
+          metrics: @metrics.snapshot, lines: lines,
+          size: { width: width, height: height },
+          view: { offset: @offset, paused: @paused },
+          wait_seconds: @wait_seconds
+        )
+      end
+
+      def page_step
+        @body_height.positive? ? @body_height : 1
+      end
+    end
+  end
+end