letsdo 0.4.0 → 0.5.0

data/lib/letsdo/cli/builder_metrics.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # Session recorder and metrics-file wiring for Letsdo::CLI::Builder.
+    # Kept in its own module so BuilderAssembly stays within the module-length
+    # limit.
+    module BuilderMetrics
+      # Returns the IO for the LETSDO_METRICS_FILE, or nil if unset or
+      # unwritable. Emits a warning to stderr on invalid path.
+      def metrics_io
+        path = @env['LETSDO_METRICS_FILE']
+        return nil if path.nil? || path.empty?
+
+        File.open(path, 'a', encoding: 'UTF-8')
+      rescue SystemCallError, IOError => e
+        @stderr.puts("letsdo: cannot open metrics file #{path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      def build_recorder(name)
+        Letsdo::SessionRecorder.new(name: name, handle: assignee_handle(name),
+                                    metrics_io: metrics_io)
+      end
+
+      def run_plain(name, recorder)
+        streamer = OutputStreamer.new(stdout: @stdout, stderr: @stderr)
+        agent = agent_for(name, streamer)
+        pause_gate = Control::PauseGate.new
+        reader = plain_control_reader(agent, pause_gate)
+        agent_loop(name, streamer, agent: agent, stderr: @stderr, metrics: recorder,
+                                   pause_gate: pause_gate).run
+      ensure
+        reader&.stop
+        finish_session(name, recorder)
+      end
+
+      # Plain-mode control (TASK-75): with a terminal stdin the reader maps
+      # p/q to the same actions as the TUI keys — the shared PauseGate plus
+      # the current backend (nil between runs is a no-op). Reader#start is a
+      # no-op when stdin is not a terminal (pipes, CI), so stopping stays
+      # signal-only there. The reader writes nothing, so the plain stream
+      # stays byte-identical.
+      def plain_control_reader(agent, pause_gate)
+        Control::Reader.new(input: @stdin, pause_gate: pause_gate,
+                            runner: -> { agent.backend }).tap(&:start)
+      end
+
+      # One shared stop path for plain and TUI mode (TASK-69/TASK-70): close
+      # the recorder, optionally write per-task elapsed back into the task
+      # records, then print the summary. Write-back failures are counted and
+      # reported, never raised.
+      def finish_session(name, recorder)
+        recorder.session_stop
+        not_written = task_time_comments(name, recorder)
+        @stderr.puts(recorder.summary_line)
+        @stderr.puts(comment_failure_line(not_written)) if not_written.positive?
+      end
+
+      # Opt-in (LETSDO_TASK_TIME_COMMENT=1): re-query the provider once at
+      # stop and comment the elapsed time on runs whose task is gone. Off by
+      # default — no subprocess, no task file mutation.
+      def task_time_comments(name, recorder)
+        return 0 unless @config.task_time_comment?
+
+        writeback = TaskTimeWriteback.new(command: backlog_command, cwd: @root,
+                                          env: ENV.to_h.merge(@env), stderr: @stderr)
+        writeback.call(recorder.summary.runs, final_open_tasks(name))
+      end
+
+      def final_open_tasks(name)
+        provider_for(assignee_handle(name)).call
+      end
+
+      def comment_failure_line(count)
+        "letsdo: #{count} #{count == 1 ? 'comment' : 'comments'} not written"
+      end
+    end
+  end
+end

data/lib/letsdo/cli/doctor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # `letsdo doctor` dispatch (TASK-71): builds the environment self-check
+    # from the same Letsdo::Config the rest of the CLI uses and returns its
+    # exit code. `doctor` is a reserved name -- it never launches an agent.
+    module CLIDoctor
+      private
+
+      def doctor_command
+        Doctor.new(config: Config.new(env: @env), stdout: @stdout, stdin: @stdin).run
+      end
+    end
+  end
+end

data/lib/letsdo/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'cli/init'
+require_relative 'cli/doctor'
 require_relative 'cli/builder'
 
 module Letsdo
@@ -10,6 +11,8 @@ module Letsdo
   #   letsdo                       — usage and agent list, exit code 1;
   #   letsdo --version             — version, exit code 0;
   #   letsdo --help                — usage, exit code 0;
+  #   letsdo doctor                — environment self-check, exit 0 unless a
+  #                                  check FAILs (then 1); `doctor` is reserved;
   #   letsdo <name>                — run the <name> agent in the orchestrator
   #                                    loop until SIGINT/SIGTERM;
   #   letsdo <name> (no prompt)    — same, but on the built-in default prompt;
@@ -21,6 +24,7 @@ module Letsdo
   #   letsdo <unknown option>      — "letsdo: unknown option: X" + usage, exit 1.
   class CLI
     include CLIInit
+    include CLIDoctor
 
     USAGE = 'Usage: letsdo <agent_name>'
     AGENTS_HEADER = 'Available agents:'
@@ -34,6 +38,8 @@ module Letsdo
     def initialize(env:, stdout:, stderr:, stdin: $stdin, sleeper: nil)
       @stdout = stdout
       @stderr = stderr
+      @env = env
+      @stdin = stdin
       @root = Config.new(env: env).root
       @builder = Builder.new(env: env, stdout: stdout, stderr: stderr,
                              stdin: stdin, sleeper: sleeper)
@@ -44,14 +50,22 @@ module Letsdo
       return print_version if version_flag?(arg)
       return print_help if help_flag?(arg)
       return usage_error if arg.nil?
+      return doctor_command if arg == 'doctor'
       return init_command(argv) if argv.include?('--init')
       return unknown_option(arg) if arg.start_with?('-')
 
-      @builder.run(arg)
+      run_agent(arg)
     end
 
     private
 
+    def run_agent(arg)
+      @builder.run(arg)
+    rescue Letsdo::BackendUnavailableError => e
+      @stderr.puts("letsdo: #{e.message}")
+      2
+    end
+
     def version_flag?(arg)
       ['--version', '-v'].include?(arg)
     end

data/lib/letsdo/config.rb

@@ -4,8 +4,8 @@ require 'shellwords'
 
 module Letsdo
   # The single place where every LETSDO_*/AGENT_* environment variable is
-  # read, with exactly the defaults and precedence the CLI, PiRunner and
-  # AgentLoop used to apply inline. Giving env policy one home makes it
+  # read, with exactly the defaults and precedence the CLI, the Pi backend
+  # and AgentLoop used to apply inline. Giving env policy one home makes it
   # testable in one place and gives future knobs (provider/backend
   # selection) a single spot to add a variable.
   #
@@ -14,6 +14,10 @@ module Letsdo
     DEFAULT_WAIT_SECONDS = 10.0
     DEFAULT_PI_COMMAND = 'pi'
     DEFAULT_BACKLOG_COMMAND = 'backlog'
+    DEFAULT_PROVIDER = 'backlog'
+    DEFAULT_BACKEND = 'pi'
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_CAP = 300.0
 
     def initialize(env: ENV)
       @env = env
@@ -53,7 +57,7 @@ module Letsdo
       DEFAULT_WAIT_SECONDS
     end
 
-    # The pi command used to run agents (same literal as PiRunner::COMMAND).
+    # The pi command used to run agents (same literal as Backends::Pi::COMMAND).
     def pi_command
       @env.fetch('LETSDO_PI_COMMAND', DEFAULT_PI_COMMAND)
     end
@@ -63,9 +67,67 @@ module Letsdo
       @env.fetch('LETSDO_BACKLOG_COMMAND', DEFAULT_BACKLOG_COMMAND)
     end
 
-    # Whether [letsdo] traces are enabled in PiRunner and AgentLoop.
+    # Executable search path, used by `letsdo doctor` to resolve the
+    # configured command names. It lives here so doctor code never reads
+    # ENV directly (TASK-71).
+    def path
+      @env.fetch('PATH', '')
+    end
+
+    # The task provider name. Reads LETSDO_PROVIDER with default 'backlog'.
+    # An empty value falls back to 'backlog'.
+    def provider
+      @env['LETSDO_PROVIDER'].to_s.strip.empty? ? DEFAULT_PROVIDER : @env['LETSDO_PROVIDER'].to_s.strip
+    end
+
+    # The AI backend name. Reads LETSDO_BACKEND with default 'pi'.
+    # An empty value falls back to 'pi'.
+    def backend
+      @env['LETSDO_BACKEND'].to_s.strip.empty? ? DEFAULT_BACKEND : @env['LETSDO_BACKEND'].to_s.strip
+    end
+
+    # Whether [letsdo] traces are enabled in the Pi backend and AgentLoop.
     def debug?
       @env['LETSDO_DEBUG'] == '1'
     end
+
+    # Whether per-task elapsed is written back into the task record as a
+    # backlog comment at session stop (TASK-70). Opt-in: only the literal
+    # '1' enables it, so no task file is ever modified by default.
+    def task_time_comment?
+      @env['LETSDO_TASK_TIME_COMMENT'] == '1'
+    end
+
+    # Give-up after N consecutive failed runs of the same task in a session
+    # (default 3). Any invalid value falls back to the default.
+    def max_retries
+      value = @env['LETSDO_MAX_RETRIES'].to_s.strip
+      return DEFAULT_MAX_RETRIES if value.empty?
+
+      Integer(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_MAX_RETRIES
+    end
+
+    # Base backoff seconds for the first retry; doubles per failure.
+    # Default = LETSDO_WAIT_SECONDS (the loop poll interval). An invalid
+    # value falls back to that default.
+    def retry_base
+      value = @env['LETSDO_RETRY_BASE'].to_s.strip
+      value.empty? ? wait_seconds : Float(value)
+    rescue ArgumentError, TypeError
+      wait_seconds
+    end
+
+    # Maximum backoff seconds (default 300). An invalid value falls back
+    # to the default.
+    def retry_cap
+      value = @env['LETSDO_RETRY_CAP'].to_s.strip
+      return DEFAULT_RETRY_CAP if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      DEFAULT_RETRY_CAP
+    end
   end
 end

data/lib/letsdo/control/reader.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Control
+    # The plain-mode control reader (TASK-94): when letsdo runs in plain
+    # line-stream mode (stdout not a TTY) but stdin IS a terminal, a
+    # background thread reads Enter-terminated commands and maps them to
+    # the same actions as the TUI keys (TASK-67/74 control model):
+    #
+    #   p - toggle pause: on -> Control::PauseGate#pause plus the running
+    #       backend's SIGSTOP (a no-op when nothing runs), off -> resume;
+    #   q - clean stop: Thread.main.raise(Letsdo::Stopped), the exact
+    #       teardown path of SIGINT/SIGTERM and the TUI 'q'.
+    #
+    # The reader only starts for a terminal stdin: with a pipe or
+    # /dev/null it never reads a single byte, so a user's piped stdin is
+    # left untouched and stopping stays signal-only. It writes nothing
+    # (no echo, no escape codes, no partial output) and its thread exits
+    # quietly on EOF or a read error.
+    class Reader
+      # @param input [IO] the stdin stream to read lines from
+      # @param pause_gate [Letsdo::Control::PauseGate, nil] the between-runs
+      #        gate toggled by 'p'
+      # @param runner [#call, nil] callable returning the current backend
+      #        (answers pause/resume) or nil; mirrors the TUI wiring, so a
+      #        nil between runs is simply a no-op
+      # @param on_stop [#call, nil] stop action; defaults to raising
+      #        Letsdo::Stopped into the main thread (injected in tests)
+      # @param tty [Boolean, nil] overrides the input.tty? check (tests only)
+      def initialize(input:, pause_gate: nil, runner: nil, on_stop: nil, tty: nil)
+        @input = input
+        @pause_gate = pause_gate
+        @runner = runner
+        @on_stop = on_stop
+        @tty = tty
+        @paused = false
+        @thread = nil
+      end
+
+      # Whether the reader may run: stdin must be a terminal that can be
+      # read line by line, otherwise a pipe, /dev/null or CI stdin would be
+      # read from (and stolen from the user's pipe).
+      #
+      # @return [Boolean]
+      def available?
+        @tty.nil? ? terminal_input? : @tty
+      end
+
+      # Starts the background reader thread. A non-terminal stdin starts
+      # nothing at all.
+      #
+      # @return [Thread, nil] the reader thread, or nil when not a terminal
+      def start
+        return nil unless available?
+        return @thread if @thread
+
+        @thread = build_thread
+      end
+
+      # Waits for the reader thread so tests and shutdown can join it.
+      #
+      # @param timeout [Numeric, nil] seconds to wait, nil waits forever
+      # @return [Thread, nil]
+      def join(timeout = nil)
+        @thread&.join(timeout)
+      end
+
+      # Ends the reader: kills the background thread when it is still
+      # blocked on input, so no reader outlives the run that started it.
+      # Safe to call when it was never started (non-TTY stdin).
+      #
+      # @return [void]
+      def stop
+        thread = @thread
+        return unless thread
+
+        thread.kill
+        thread.join(1)
+        @thread = nil
+      end
+
+      private
+
+      def terminal_input?
+        @input.respond_to?(:tty?) && @input.tty? && @input.respond_to?(:gets)
+      end
+
+      def build_thread
+        Thread.new { read_loop }.tap { |thread| thread.report_on_exception = false }
+      end
+
+      # Reads Enter-terminated commands until EOF or a read error; never
+      # writes and never lets an error escape the thread.
+      def read_loop
+        while (line = @input.gets)
+          handle_command(line)
+        end
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      def handle_command(line)
+        case line.strip
+        when 'p' then toggle_pause
+        when 'q' then request_stop
+        end
+      end
+
+      def toggle_pause
+        @paused = !@paused
+        action = @paused ? :pause : :resume
+        invoke(@pause_gate, action)
+        invoke(current_runner, action)
+      end
+
+      def current_runner
+        @runner.respond_to?(:call) ? @runner.call : @runner
+      end
+
+      def invoke(target, action)
+        return unless target.respond_to?(action)
+
+        target.public_send(action)
+      end
+
+      def request_stop
+        (@on_stop || -> { Thread.main.raise(Letsdo::Stopped) }).call
+      end
+    end
+  end
+end

data/lib/letsdo/control.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+require_relative 'control/reader'
+
 module Letsdo
-  # Agent-control primitives shared by the TUI and the orchestrator loop
-  # (TASK-67 control model): pausing between runs.
+  # Agent-control primitives shared by the TUI, the plain-mode reader and
+  # the orchestrator loop (TASK-67 control model): pausing between runs
+  # (PauseGate) and the stdin control reader (Reader).
   module Control
     # A thread-safe pause flag polled by Letsdo::AgentLoop between runs.
     #
-    # Mid-run suspension is handled by Letsdo::PiRunner#pause (SIGSTOP to
+    # Mid-run suspension is handled by Letsdo::Backends::Pi#pause (SIGSTOP to
     # the pi group, kernel-level freeze). Between runs there is no pi to
     # stop, so the pause lives in this gate: while #paused? is true the
     # loop must not start a new run, and it waits until #resume.

data/lib/letsdo/doctor/checks.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class Doctor
+    # The individual environment checks behind `letsdo doctor` (TASK-71).
+    # Every check returns { status:, message:, hint: } where the hint is
+    # mandatory for FAIL/WARN so the report is always actionable. Kept in its
+    # own module so Letsdo::Doctor stays within the class-length limit.
+    module DoctorChecks
+      MINIMUM_RUBY = '3.3'
+
+      private
+
+      def checks
+        [ruby_check, pi_check, backlog_check, root_check,
+         agents_md_check, agents_dir_check, tty_check]
+      end
+
+      # ruby >= 3.3 is the gemspec floor: below it letsdo still reports the
+      # problem as a WARN instead of a hard failure.
+      def ruby_check
+        return result('OK', "ruby #{RUBY_VERSION} (>= #{MINIMUM_RUBY})") if ruby_supported?
+
+        result('WARN', "ruby #{RUBY_VERSION} (< #{MINIMUM_RUBY})",
+               "upgrade Ruby to #{MINIMUM_RUBY} or newer")
+      end
+
+      def ruby_supported?
+        Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(MINIMUM_RUBY)
+      end
+
+      def pi_check
+        command_check('pi', @config.pi_command, 'LETSDO_PI_COMMAND')
+      end
+
+      def backlog_check
+        command_check('backlog', @config.backlog_command, 'LETSDO_BACKLOG_COMMAND')
+      end
+
+      def command_check(label, command, env_var)
+        return result('OK', "#{label} command found: #{command}") if command_available?(command)
+
+        result('FAIL', "#{label} command not found: #{command}",
+               "install #{label} or set #{env_var}")
+      end
+
+      # An absolute or relative command path is checked directly; a bare name
+      # is resolved against the PATH exposed by Letsdo::Config.
+      def command_available?(command)
+        return File.executable?(command) if command.include?(File::SEPARATOR)
+
+        @config.path.split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, command))
+        end
+      end
+
+      def root_check
+        return result('OK', "project root #{@config.root} has backlog/tasks/") if backlog_tasks?
+
+        result('FAIL', "project root #{@config.root} has no backlog/tasks/",
+               'run `backlog init` or set LETSDO_ROOT to a Backlog.md project')
+      end
+
+      def backlog_tasks?
+        File.directory?(File.join(@config.root, 'backlog', 'tasks'))
+      end
+
+      def agents_md_check
+        path = File.join(@config.root, 'AGENTS.md')
+        return result('OK', "AGENTS.md present at #{path}") if File.file?(path)
+
+        result('WARN', "no AGENTS.md at #{path}",
+               'add AGENTS.md with the project instructions for agents')
+      end
+
+      def agents_dir_check
+        dir = File.join(@config.root, 'agents')
+        prompts = File.directory?(dir) ? Dir.children(dir).length : 0
+        return result('OK', "agents/ present with #{prompts} prompt(s)") if prompts.positive?
+
+        result('WARN', "agents/ missing or empty at #{dir}",
+               'create an agent prompt with `letsdo <name> --init`')
+      end
+
+      # TUI engages only when stdout is a TTY (plus stdin/TERM, checked at
+      # launch); an INFO line tells the user which mode a run would pick.
+      def tty_check
+        return result('INFO', 'stdout is a TTY - TUI mode') if @stdout.tty?
+
+        result('INFO', 'stdout is not a TTY - plain mode')
+      end
+
+      def result(status, message, hint = nil)
+        { status: status, message: message, hint: hint }
+      end
+    end
+  end
+end

data/lib/letsdo/doctor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'doctor/checks'
+
+module Letsdo
+  # `letsdo doctor`: one line per environment check with a status tag and an
+  # actionable hint for every FAIL/WARN (TASK-71). Exits 0 when nothing
+  # FAILs and 1 otherwise, so it can gate scripts.
+  #
+  # Every input comes from Letsdo::Config (env policy) plus the injected
+  # streams, so the command is fully testable without touching process ENV.
+  class Doctor
+    include DoctorChecks
+
+    def initialize(config:, stdout:, stdin: $stdin)
+      @config = config
+      @stdout = stdout
+      @stdin = stdin
+    end
+
+    # Prints the report and returns the process exit code: 1 when at least
+    # one check FAILed, 0 otherwise.
+    def run
+      results = checks
+      results.each { |check| print_result(check) }
+      results.any? { |check| check[:status] == 'FAIL' } ? 1 : 0
+    end
+
+    private
+
+    def print_result(check)
+      line = "[#{tag(check[:status])}] #{check[:message]}"
+      line += " - #{check[:hint]}" if check[:hint]
+      @stdout.puts(line)
+    end
+
+    # All tags render six characters wide, so the columns line up.
+    def tag(status)
+      status == 'OK' ? ' OK ' : status
+    end
+  end
+end

data/lib/letsdo/duration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Shared rendering of a duration in seconds as "4m 12s" / "12s" / "0s".
+  #
+  # The stop summary (TASK-69) and the opt-in per-task elapsed write-back
+  # (TASK-70) both use this one formatter, so the number a session reports
+  # and the number written into the task record can never drift apart.
+  module Duration
+    module_function
+
+    # @param seconds [Numeric] duration in seconds (negative values clamp to 0)
+    # @return [String] human-readable duration, e.g. "4m 12s"
+    def format(seconds)
+      total = [seconds.to_f, 0.0].max.round
+      minutes, secs = total.divmod(60)
+      return '0s' if minutes.zero? && secs.zero?
+      return "#{secs}s" if minutes.zero?
+
+      "#{minutes}m #{secs}s"
+    end
+  end
+end

data/lib/letsdo/errors.rb

@@ -9,4 +9,11 @@ module Letsdo
   # cleanly. Not a StandardError — nothing rescues it accidentally.
   class Stopped < StandardError
   end
+
+  # Raised when the AI backend process cannot be started (missing or
+  # non-executable binary). This is a configuration error, not a loop
+  # problem: the CLI catches it, prints a clear message and exits 2 instead
+  # of dying with a Ruby backtrace.
+  class BackendUnavailableError < Error
+  end
 end

data/lib/letsdo/metrics/fanout.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Letsdo
+  module Metrics
+    # A small fan-out facade that forwards the loop-driver events to a
+    # list of observers.  Used in TUI mode so the session recorder and
+    # the header metrics facade both receive the same callbacks from
+    # Letsdo::AgentLoop.
+    #
+    # Each observer must respond to provider_result, run_started and
+    # run_finished (the same interface Tui::Metrics and SessionRecorder
+    # implement).  The exit code is forwarded to every observer so the
+    # session recorder can classify outcomes; Tui::Metrics ignores it.
+    class Fanout
+      # @param observers [Array<Object>] each must implement the three
+      #        callback methods (provider_result, run_started, run_finished)
+      def initialize(*observers)
+        @observers = observers
+      end
+
+      # Forwards the provider open-task count to every observer.
+      #
+      # @param count [Integer, nil] number of open tasks; nil = the
+      #        backlog state is unreadable
+      # @return [void]
+      def provider_result(count)
+        @observers.each { |observer| observer.provider_result(count) }
+      end
+
+      # Forwards a run-started event (task label) to every observer.
+      #
+      # @param task [String] task label
+      # @return [void]
+      def run_started(task)
+        @observers.each { |observer| observer.run_started(task) }
+      end
+
+      # Forwards a run-finished event (exit code) to every observer.
+      #
+      # @param exit_code [Integer, nil] the run exit code
+      # @return [void]
+      def run_finished(exit_code = nil)
+        @observers.each { |observer| observer.run_finished(exit_code) }
+      end
+    end
+  end
+end