letsdo 0.4.0 → 0.6.1

data/lib/letsdo/cli/builder_assembly.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Letsdo
+  class CLI
+    # Provider and backend registries used by Letsdo::CLI::Builder: name ->
+    # factory maps, injectable via the constructor for tests. Kept separate so
+    # the assembly module stays within the module-length limit.
+    module BuilderRegistries
+      # Provider registry: maps LETSDO_PROVIDER names to factories that build
+      # a provider from handle, command, cwd, and env.  Inject a custom
+      # registry via the constructor for tests.
+      PROVIDERS = {
+        'backlog' => lambda do |handle:, command:, cwd:, env:|
+          Providers::Backlog.new(handle: handle, command: command, cwd: cwd, env: env)
+        end
+      }.freeze
+
+      # Backend registry: maps LETSDO_BACKEND names to factory builders that
+      # take the Letsdo::Config and return a backend_factory (callable with
+      # prompt:, streamer:, model:). The pi entry captures the pi command and
+      # flags from Config (LETSDO_PI_COMMAND / LETSDO_PI_FLAGS with the
+      # AGENT_PI_FLAGS fallback), keeping pi vocabulary out of the business
+      # layer.  Inject a custom registry via the constructor for tests.
+      BACKENDS = {
+        'pi' => lambda do |config:|
+          command = config.pi_command
+          flags = config.pi_flags
+          lambda { |prompt:, streamer:, model: nil|
+            Letsdo::Backends::Pi.new(prompt: prompt, streamer: streamer,
+                                     flags: flags, command: command,
+                                     model: model, config: config)
+          }
+        end
+      }.freeze
+    end
+
+    # Registry-driven component wiring for Letsdo::CLI::Builder: the run
+    # entry point, agent/provider/loop assembly and the plain-mode run path.
+    # Extracted into its own module so Builder stays within the class-length
+    # limit (same reason as the BuilderTui split).
+    module BuilderAssembly
+      include BuilderRegistries
+
+      def initialize(env:, stdout:, stderr:, **rest)
+        @env = env
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = rest[:stdin] || $stdin
+        @sleeper = rest[:sleeper]
+        @config = Config.new(env: env)
+        @root = @config.root
+        @provider_registry = rest[:provider_registry] || PROVIDERS
+        @backend_registry = rest[:backend_registry] || BACKENDS
+      end
+
+      # Runs <name> in plain or TUI mode; returns the process exit code.
+      def run(name)
+        return 1 unless resolve_provider!
+        return 1 unless resolve_backend!
+
+        store = PromptStore.new(root: @root)
+        announce_default_prompt(name, store) if store.read(name).nil?
+        recorder = build_recorder(name)
+        tui? ? run_tui(name, recorder) : run_plain(name, recorder)
+      end
+
+      private
+
+      def agent_for(name, streamer)
+        Agent.new(name: name, root: @root, handle: assignee_handle(name),
+                  backend_factory: @selected_backend_factory,
+                  streamer: streamer)
+      end
+
+      # Resolves LETSDO_BACKEND through the backend registry once per run,
+      # so both wiring paths (plain and TUI) build the Agent's
+      # backend_factory through the same registry entry.  An unknown backend
+      # name fails fast instead of silently falling back.
+      def resolve_backend!
+        builder = @backend_registry[@config.backend]
+        if builder
+          @selected_backend_factory = builder.call(config: @config)
+          return true
+        end
+
+        @stderr.puts("letsdo: unknown AI backend: #{@config.backend}")
+        false
+      end
+
+      def resolve_provider!
+        @selected_provider_factory = @provider_registry[@config.provider]
+        return true if @selected_provider_factory
+
+        @stderr.puts("letsdo: unknown task provider: #{@config.provider}")
+        false
+      end
+
+      def provider_for(handle)
+        @selected_provider_factory.call(
+          handle: handle,
+          command: backlog_command,
+          cwd: @root,
+          env: ENV.to_h.merge(@env)
+        )
+      end
+
+      def agent_loop(name, streamer, **opts)
+        handle = opts[:handle] || assignee_handle(name)
+        agent = opts[:agent] || agent_for(name, streamer)
+        provider = opts[:provider] || provider_for(handle)
+        # The provider object itself (not a wrapping lambda) reaches the loop
+        # so the once-per-run assignee mismatch hint can read its
+        # #assignee_variants (TASK-96).
+        AgentLoop.new(name: name, handle: handle, agent: agent,
+                      task_provider: provider,
+                      wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
+                      metrics: opts[:metrics], pause_gate: opts[:pause_gate],
+                      watcher: backlog_watcher, **retry_options)
+      end
+
+      def retry_options
+        { retry_base: @config.retry_base, retry_cap: @config.retry_cap, max_retries: @config.max_retries }
+      end
+
+      def backlog_watcher
+        Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
+      end
+
+      # One-time fallback notification (before the first loop message): names
+      # the exact path checked and the placement hint. The agent still starts
+      # — Letsdo::Agent falls back to the built-in default prompt itself.
+      def announce_default_prompt(name, store)
+        @stderr.puts("letsdo: no prompt for #{name} at #{store.agent_path(name)}")
+        @stderr.puts("letsdo: using the built-in default prompt (create a prompt file with 'letsdo #{name} --init')")
+      end
+
+      def tui?
+        @stdout.tty? && @stdin.tty? && @env['TERM'].to_s != 'dumb'
+      end
+
+      def assignee_handle(name)
+        @config.assignee_handle(name)
+      end
+
+      def backlog_command
+        @config.backlog_command
+      end
+
+      def wait_seconds
+        @config.wait_seconds
+      end
+    end
+  end
+end

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
@@ -34,11 +38,22 @@ module Letsdo
       Shellwords.split(value)
     end
 
-    # The agent's backlog assignee handle. Default: @<name> (handle = name);
-    # a blank override also falls back to the derived handle.
+    # The agent's backlog assignee name. Default: the bare agent name —
+    # the tracker stores bare names ('developer'); the '@' prefix is
+    # prompt-only notation (TASK-96). AGENT_ASSIGNEE_HANDLE overrides for
+    # legacy setups (used verbatim; a @-prefixed value still matches after
+    # normalization in the provider, but `letsdo doctor` warns about it);
+    # a blank override also falls back to the derived bare name.
     def assignee_handle(name)
-      handle = @env['AGENT_ASSIGNEE_HANDLE']
-      handle && !handle.strip.empty? ? handle : "@#{name}"
+      assignee_handle_override || name.to_s
+    end
+
+    # Raw AGENT_ASSIGNEE_HANDLE (nil when unset or blank) — `letsdo
+    # doctor` uses it to warn about a legacy @-prefixed override instead
+    # of it silently missing every bare-named task.
+    def assignee_handle_override
+      value = @env['AGENT_ASSIGNEE_HANDLE']
+      value && !value.strip.empty? ? value : nil
     end
 
     # Retry interval when no tasks are open. LETSDO_WAIT_SECONDS wins, then
@@ -53,7 +68,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 +78,75 @@ 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
+
+    # Environment for CLI child processes spawned outside the builder
+    # (the doctor's handle-less provider): the process environment
+    # overlaid with the injected env, so shebang PATH resolution and test
+    # scenario variables both keep working (TASK-96).
+    def child_env
+      ENV.to_h.merge(@env)
+    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.