letsdo 0.1.0

data/lib/letsdo/tui/renderer.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+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
+    #
+    # Pure means: no IO, no terminal, no clock — the same inputs always
+    # produce the same string, so every rendering path (session controller,
+    # tests) feeds it identically and tests need no real TTY.
+    #
+    # Layout (bottom line is the last, no trailing newline):
+    #
+    #   letsdo · developer (@developer)            session 00:12:34
+    #   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
+    module Renderer
+      HEADER_HEIGHT = 2
+      FOOTER_HEIGHT = 1
+      DIVIDER_HEIGHT = 1
+      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 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")
+      end
+
+      # The number of body lines a terminal of the given height fits.
+      def self.body_height_for(height)
+        [height - HEADER_HEIGHT - FOOTER_HEIGHT - DIVIDER_HEIGHT, 1].max
+      end
+
+      # The index of the last line that can be the first visible one.
+      def self.max_offset(lines, body_height)
+        [lines.length - body_height, 0].max
+      end
+
+      # Clamps a view offset into the valid range.
+      def self.clamp_offset(offset, lines, body_height)
+        [[offset, max_offset(lines, body_height)].min, 0].max
+      end
+
+      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)
+      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}"]
+        if paused
+          parts << "PAUSED"
+        elsif metrics.current_task
+          parts << "task #{metrics.current_task}"
+          parts << format_duration(metrics.current_task_seconds) if metrics.current_task_seconds
+        else
+          parts << "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)
+        end
+      end
+
+      def self.divider_line(width)
+        return "" if width < 4
+
+        body = "─" * (width - 2)
+        "├#{body}┤"
+      end
+
+      def self.footer_line(width)
+        fit_line("↑/↓ PgUp/PgDn scroll · p pause · r refresh · q quit", width)
+      end
+
+      # "no open tasks, retrying in 10s" style reason for the waiting state.
+      def self.waiting_reason(left, wait_seconds)
+        formatted = wait_seconds == wait_seconds.to_i ? wait_seconds.to_i : wait_seconds
+        suffix = " (retry in #{formatted}s)"
+        if left.nil?
+          "backlog unavailable#{suffix}"
+        elsif left.zero?
+          "no open tasks#{suffix}"
+        else
+          "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
+
+      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
+
+      # 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
+        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?
+
+        require "unicode/display_width"
+        Unicode::DisplayWidth.of(text)
+      end
+    end
+  end
+end

data/lib/letsdo/tui/session.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Tui
+    # The TUI controller: owns the terminal lifecycle, the background input
+    # thread and the repaint loop around an orchestrator run.
+    #
+    # Threading model (the orchestrator loop stays on the calling thread,
+    # exactly as in plain mode — Letsdo::PiRunner's signal design keeps
+    # working unchanged):
+    #   main thread    — the injected block (Letsdo::AgentLoop#run with its
+    #                    own signal traps): provider queries, agent runs,
+    #                    streamer writes into the log, metrics events;
+    #   input thread   — the SOLE repainter: polls keys (tty-reader),
+    #                    drains the log snapshot, tracks the metrics
+    #                    snapshot and repaints on keys, data, 1s timer
+    #                    ticks and SIGWINCH. Never touches the loop.
+    #
+    # Interactive actions (footer lists them):
+    #   ↑ / ↓ / PgUp / PgDn / Home / End — scroll; the view auto-follows
+    #     the newest line while at the bottom (tail -f semantics);
+    #   p — pause/resume: display freeze (PAUSED in the header, the log
+    #     keeps buffering, the view stays); keys still repaint;
+    #   r — immediate backlog re-query for the 'left' metric;
+    #   q / Ctrl-C — quit: exactly the signal-stop unwinding — Letsdo::Stopped
+    #     raised into the main thread terminates the pi child (PiRunner
+    #     rescue), stops the loop (AgentLoop rescue) and restores the
+    #     terminal from the ensure block; exit code 0.
+    #
+    # Signals: SIGWINCH sets a flag → the input thread re-queries the size
+    # and repaints (no corruption). SIGINT/SIGTERM keep working through the
+    # loop's own traps (main thread).
+    class Session
+      # 1s session-timer repaint interval.
+      REPAINT_INTERVAL = 1.0
+      # Poll sleep when the display is frozen or nothing happened (avoids a
+      # busy loop while still repainting at the timer interval).
+      IDLE_SLEEP = 0.01
+      # How long teardown waits for the input thread to finish its poll.
+      INPUT_JOIN_TIMEOUT = 2.0
+
+      # @param name [String] agent name (header identity)
+      # @param handle [String] assignee handle (header identity)
+      # @param log [LogBuffer] the combined log the streamer writes into
+      # @param metrics [Metrics] the header metrics facade
+      # @param terminal [Terminal] the terminal wrapper
+      # @param input [Input] the key reader
+      # @param refresh [Proc, nil] callable → open task count (Integer) or
+      #        nil (backlog unreadable); 'r' uses it for an immediate
+      #        re-query
+      # @param wait_seconds [Numeric] retry interval for the waiting state
+      # @param clock [Proc] monotonic clock for tick timing (injectable)
+      def initialize(name:, handle:, log:, metrics:, terminal:, input:,
+                     refresh: nil, wait_seconds: 10.0, clock: nil)
+        @name = name
+        @handle = handle
+        @log = log
+        @metrics = metrics
+        @terminal = terminal
+        @input = input
+        @refresh = refresh
+        @wait_seconds = wait_seconds
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @offset = 0
+        @follow = true
+        @paused = false
+        @stop = false
+        @winch = false
+        @body_height = 1
+        @seen_version = 0
+        @input_thread = nil
+      end
+
+      # Runs the TUI around the given orchestrator work.
+      #
+      # The block runs on the calling thread. On quit (q/Ctrl-C) or a stop
+      # signal Letsdo::Stopped unwinds it; the terminal is restored from
+      # the ensure block on every exit path.
+      #
+      # @yield the orchestrator run (e.g. Letsdo::AgentLoop#run)
+      # @return [Integer] the block's result, or 0 when stopped
+      def run(&work)
+        install_winch_handler
+        @terminal.enter
+        start_input_thread
+        result = work.call
+        result
+      rescue Letsdo::Stopped
+        0
+      ensure
+        stop_input_thread
+        leave_terminal
+        restore_winch_handler
+      end
+
+      private
+
+      # The input thread body: the only place that writes to the terminal.
+      def input_loop
+        with_raw_input do
+          repaint
+          @last_repaint = @clock.call
+          loop do
+            break if @stop
+
+            key = @input.next_key
+            handled = key ? handle_key(key) : false
+            winch = take_winch
+            handled = true if winch
+            now = @clock.call
+            tick = now - @last_repaint >= REPAINT_INTERVAL
+            new_data = @log.version != @seen_version
+            if handled || (!@paused && (tick || new_data))
+              repaint
+              @last_repaint = @clock.call
+            else
+              sleep(IDLE_SLEEP)
+            end
+          end
+        end
+      rescue StandardError
+        # The input thread must never die loudly into the middle of the
+        # screen, and a quiet exit still leaves the loop running (teardown
+        # joins it). Terminal state is restored by the ensure blocks.
+        nil
+      end
+
+      def handle_key(key)
+        case key
+        when :up, :page_up
+          @offset -= key == :page_up ? page_step : 1
+          @follow = false
+          true
+        when :down, :page_down
+          @offset += key == :page_down ? page_step : 1
+          true # repaint decides re-sticking at the bottom
+        when :home
+          @offset = 0
+          @follow = false
+          true
+        when :end
+          @follow = true
+          true
+        when :p
+          @paused = !@paused
+          true
+        when :r
+          refresh
+          true
+        when :q, :ctrl_c
+          quit
+          false # leaving the session; no repaint needed
+        else
+          false
+        end
+      end
+
+      # Immediate backlog re-query: the provider is re-run on this thread
+      # (a subprocess call, thread-safe) and the count reaches the header
+      # snapshot.
+      def refresh
+        return unless @refresh
+
+        @metrics.provider_result(@refresh.call)
+      end
+
+      # Quit = the same unwinding as a stop signal: Letsdo::Stopped raised
+      # into the main thread (inside the orchestrator work) terminates the
+      # pi child and stops the loop; the ensure block restores the
+      # terminal. No-op after teardown already started.
+      def quit
+        return if @stop
+
+        Thread.main.raise(Letsdo::Stopped)
+      end
+
+      # Repaints the whole frame from the current state.
+      def repaint
+        lines, version = @log.lines
+        @seen_version = version
+        height, width = @terminal.size
+        @body_height = Renderer.body_height_for(height)
+        max_offset = Renderer.max_offset(lines, @body_height)
+        if @paused
+          @offset = [[@offset, max_offset].min, 0].max
+        elsif @follow
+          @offset = max_offset
+        else
+          @offset = [[@offset, max_offset].min, 0].max
+          @follow = true if @offset == max_offset
+        end
+        frame = Renderer.render(
+          metrics: @metrics.snapshot, lines: lines, width: width, height: height,
+          offset: @offset, follow: @follow, paused: @paused,
+          wait_seconds: @wait_seconds
+        )
+        @terminal.render(frame)
+      end
+
+      # Page height for PgUp/PgDn.
+      def page_step
+        @body_height.positive? ? @body_height : 1
+      end
+
+      def take_winch
+        flag = @winch
+        @winch = false
+        flag
+      end
+
+      # Raw keyboard mode for the whole input session (the tty-reader
+      # per-read raw wraps would leave the terminal echoing between polls);
+      # no-op for non-tty inputs (tests use a pipe).
+      def with_raw_input(&block)
+        if @input.stdin.tty? && @input.stdin.respond_to?(:raw)
+          @input.stdin.raw(&block)
+        else
+          block.call
+        end
+      end
+
+      def install_winch_handler
+        Signal.trap("SIGWINCH") { @winch = true }
+      rescue ArgumentError
+        nil # no SIGWINCH on this platform — no resize repaints
+      end
+
+      def restore_winch_handler
+        Signal.trap("SIGWINCH", "DEFAULT")
+      rescue ArgumentError
+        nil
+      end
+
+      def start_input_thread
+        @input_thread = Thread.new { input_loop }
+        @input_thread.report_on_exception = false
+        @input_thread
+      end
+
+      def stop_input_thread
+        @stop = true
+        thread = @input_thread
+        return unless thread
+
+        thread.join(INPUT_JOIN_TIMEOUT) || thread.kill
+      end
+
+      def leave_terminal
+        @terminal.leave
+      end
+    end
+  end
+end

data/lib/letsdo/tui/terminal.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "tty-cursor"
+
+module Letsdo
+  module Tui
+    # Thin wrapper over the terminal: alternate screen, cursor handling and
+    # frame rendering, all through an injected stream (StringIO in tests).
+    #
+    # The alternate screen is entered/exited with the raw ANSI sequences
+    # (tty-cursor has no alt-screen helper); cursor hide/show and the home
+    # position come from TTY::Cursor. The frame render is a single write:
+    # cursor-to-top + the framed text. Resizes are handled by re-querying
+    # the size provider before each render.
+    class Terminal
+      # Alternate screen buffer on (keeps the caller's terminal content).
+      ENTER_ALT_SCREEN = "\e[?1049h"
+      # Alternate screen buffer off.
+      LEAVE_ALT_SCREEN = "\e[?1049l"
+      # Cursor-to-home-column-1-row-1 (cell 1,1 per tty-cursor convention).
+      HOME = "\e[1;1H"
+
+      # @param stream [IO] the terminal output stream
+      # @param size_provider [Proc] callable → [height, width]; defaults to
+      #        TTY::Screen.size; injected in tests for deterministic size
+      def initialize(stream:, size_provider: nil)
+        require "tty-screen" unless defined?(TTY::Screen)
+
+        @stream = stream
+        @size_provider = size_provider ||
+                         -> { size = TTY::Screen.size; [size[0] || 24, size[1] || 80] }
+      end
+
+      # Enters the alternate screen and hides the cursor.
+      def enter
+        write(ENTER_ALT_SCREEN + TTY::Cursor.hide)
+      end
+
+      # Shows the cursor and leaves the alternate screen.
+      def leave
+        write(TTY::Cursor.show + LEAVE_ALT_SCREEN)
+      end
+
+      # Repaints the whole frame: cursor to the top left, then the frame.
+      #
+      # @param frame [String] the rendered screen (see Letsdo::Tui::Renderer)
+      def render(frame)
+        write(HOME + frame)
+      end
+
+      # The current terminal size.
+      #
+      # @return [Array(Integer, Integer)] height and width in rows/columns
+      def size
+        dims = @size_provider.call
+        [dims[0] || 24, dims[1] || 80]
+      end
+
+      private
+
+      def write(text)
+        @stream.write(text)
+        @stream.flush
+      end
+    end
+  end
+end

data/lib/letsdo/tui.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The interactive TUI (TASK-42): a full-screen interface for letsdo <name>
+# when stdout and stdin are terminals (TERM != "dumb"). In TUI mode the
+# streamer and the loop driver feed a log buffer + metrics facade; the
+# session renders a header (name + handle, done-in-session counter, session
+# timer, tasks remaining, current-task elapsed, waiting/PAUSED states), a
+# scrollable combined log and a key-help footer, and repaints from a
+# background input thread. Non-TTY output stays the plain line-stream.
+#
+# Components:
+#   Letsdo::Tui::LogBuffer  - thread-safe combined log (streamer target)
+#   Letsdo::Tui::Metrics    - header metrics facade (loop driver events)
+#   Letsdo::Tui::Renderer   - pure function: state → framed String
+#   Letsdo::Tui::Terminal   - alt screen, cursor, frame rendering
+#   Letsdo::Tui::Input      - tty-reader key decoding (injectable)
+#   Letsdo::Tui::Session    - controller: terminal lifecycle + input thread
+
+require_relative "tui/log_buffer"
+require_relative "tui/metrics"
+require_relative "tui/renderer"
+require_relative "tui/terminal"
+require_relative "tui/input"
+require_relative "tui/session"

data/lib/letsdo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Letsdo
+  VERSION = "0.1.0"
+end

data/lib/letsdo.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# The Letsdo package — a local agent worker for Backlog.md/markdown tasks.
+#
+# OOP structure:
+#   Letsdo::Errors           - error hierarchy (UnknownAgentError and others)
+#   Letsdo::PromptStore      - access to agents/*.md prompts
+#   Letsdo::OutputStreamer   - where and how agent text and service lines are printed
+#   Letsdo::PiRunner         - running pi --mode json and parsing the event stream
+#   Letsdo::Agent            - a single agent run: prompt from agents/ + pi
+#   Letsdo::BacklogTasks     - open tasks from the backlog CLI (the task provider)
+#   Letsdo::Loop             - generic orchestrator: tasks → runs → waiting
+#   Letsdo::AgentLoop        - letsdo wiring: provider + agent + signals + messages
+#   Letsdo::Tui              - the interactive TUI (LogBuffer, Metrics,
+#                              Renderer, Terminal, Input, Session)
+#   Letsdo::CLI              - command-line arguments, usage, exit code
+#
+# Entry point — bin/letsdo (a thin wrapper over Letsdo::CLI).
+
+require_relative "letsdo/version"
+require_relative "letsdo/errors"
+require_relative "letsdo/prompt_store"
+require_relative "letsdo/output_streamer"
+require_relative "letsdo/pi_runner"
+require_relative "letsdo/agent"
+require_relative "letsdo/backlog_tasks"
+require_relative "letsdo/loop"
+require_relative "letsdo/agent_loop"
+require_relative "letsdo/tui"
+require_relative "letsdo/cli"

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: letsdo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergei O. Udalov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  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-cursor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: tty-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: unicode-display_width
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'letsdo — a local agent worker for Backlog.md/markdown tasks. OOP structure:
+  Letsdo::PromptStore (agents/), Letsdo::OutputStreamer and Letsdo::PiRunner (pi --mode
+  json), Letsdo::Agent (one run), Letsdo::Loop (orchestrator loop), Letsdo::CLI. Minitest
+  tests. Will later be split into a separate repository.'
+email:
+- udalov.x@mail.ru
+executables:
+- letsdo
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/letsdo
+- lib/letsdo.rb
+- lib/letsdo/agent.rb
+- lib/letsdo/agent_loop.rb
+- lib/letsdo/backlog_tasks.rb
+- lib/letsdo/cli.rb
+- lib/letsdo/errors.rb
+- lib/letsdo/loop.rb
+- lib/letsdo/output_streamer.rb
+- lib/letsdo/pi_runner.rb
+- lib/letsdo/prompt_store.rb
+- lib/letsdo/tui.rb
+- lib/letsdo/tui/input.rb
+- lib/letsdo/tui/log_buffer.rb
+- lib/letsdo/tui/metrics.rb
+- lib/letsdo/tui/renderer.rb
+- lib/letsdo/tui/session.rb
+- lib/letsdo/tui/terminal.rb
+- lib/letsdo/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: A local agent worker for Backlog.md/markdown tasks
+test_files: []