letsdo 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a847d927396a19813b8b643486bddabe1f9264f9ba38c6618110e24cc67b55d
-  data.tar.gz: 6d8ad205231a4e833694d7471efffe40dfd8a1f5bea89c45fdf1babb099fbdfa
+  metadata.gz: f15aee491b4d0954c628e52566908e6b7ea35428c347a79822f5781198ea4be9
+  data.tar.gz: 71b47328ea44b224cb250e4bb8d0e58c052ddd054cd950fa1b058c85933f6a91
 SHA512:
-  metadata.gz: 39ba23f90a1c8c4add2bce03e9443071a7cb57dd0458c64e7be96ec0c803ff098cea7fbd0d4a9d37eb94050aa470e142f7820643d6738be759176424e2387b98
-  data.tar.gz: 6bc4f0e7f03e01963bfb44d305e0ca76082727643a061eb042a58f71f49fce415a4616a4e6374c7461575ec28458f66c51fa864abc81048751367cf2ba4549a8
+  metadata.gz: eab4462fe5a7bec0981c9b2a803a02063d1714cc049f51f5add4053f80c302b917491465dda6d90aa66a59fb668b33a5d2166ea95589d317e1958a3756564f1c
+  data.tar.gz: 5f1b243e5bce00874965683d68bebf22c2c9cec992e6f8ab1e825db3a0796781a47bf51be934b5c8c5409c7ad1cf85a83d8a872c807b8d4e5a6023c888f8ca73

data/README.md

@@ -70,9 +70,9 @@ generation, any repeatable task flow you can express as assignee + prompt.
   and stops instantly on `Ctrl+C`.
 - **Streaming output** — agent text streams to stdout as it is generated;
   service and tool lines go to stderr with a shared `HH:MM:SS` prefix:
-  tool start (`⚙ name: args`), completion with duration
-  (`✓/✖ name: … (3s)`), indented results (trimmed with a summary note
-  when large), and error results marked (`✖ Error: ...`).
+  tool start (`⚙ name: args`) and completion with duration
+  (`✓/✖ name: done/error (3s)`). Tool result bodies are not printed, so
+  the stream stays readable while the agent works.
 - **`--version` / `--help`** — `Letsdo::VERSION` and usage, exit 0.
 - **Available as a library** — `require "letsdo"` exposes the
   `Letsdo` module (`Letsdo::VERSION`, `Letsdo::PromptStore`, `Letsdo::Agent`,
@@ -99,9 +99,16 @@ The gem is built from the repository:
 git clone git@github.com:sergio-fry/letsdo.git
 cd letsdo
 gem build letsdo.gemspec
-gem install letsdo-0.1.0.gem
+gem install letsdo-0.3.0.gem
 ```
 
+> **Ruby 4.0.x note.** Some Ruby 4.0.x builds ship default gems out of sync —
+> rdoc 8.0.0 declares `rbs >= 4.0.0` while rbs 3.x is bundled — so the
+> post-install RDoc hook can raise `Gem::ConflictError` even though the gem
+> files are already installed. Install without documentation to skip the
+> hook (`gem install letsdo-0.3.0.gem --no-document`), or install a matching
+> rbs first (`gem install rbs -v '>= 4.0.0'`).
+
 or run it straight from the checkout without installing:
 
 ```sh

data/bin/letsdo

@@ -4,18 +4,26 @@
 #
 # letsdo — a local agent worker for Backlog.md/markdown tasks.
 #
-# A thin wrapper over Letsdo::CLI: runs an agent by name (prompt from
-# agents/<name>.md in the project root) as an orchestrator loop — all open
-# tasks assigned to the agent are done one after another (one agent run =
-# one task), then the loop waits for new ones until stopped with
-# SIGINT/SIGTERM (clean exit, code 0).
+# A thin wrapper over Letsdo::CLI: runs an agent by name as an orchestrator
+# loop — all open tasks assigned to the agent are done one after another
+# (one agent run = one task), then the loop waits for new ones until stopped
+# with SIGINT/SIGTERM (clean exit, code 0). The agent's prompt comes from
+# agents/<name>.md in the project root; when that file is missing the agent
+# still starts on the built-in default prompt (Letsdo::DefaultPrompt) and a
+# one-time notification is printed on stderr naming the looked-up path and
+# the 'letsdo <name> --init' hint. --init creates agents/<name>.md with the
+# starter default prompt (letsdo itself never runs the agent in that case,
+# so the prompt can be customized before the first run).
 #
 # Usage:
-#   ./bin/letsdo <name>    # run the <name> agent in the loop (exit 0 on stop)
-#   ./bin/letsdo --version # version, exit 0
-#   ./bin/letsdo --help    # help, exit 0
-#   ./bin/letsdo           # usage and agent list, exit 1
-#   ./bin/letsdo --badopt  # "unknown option" + usage, exit 1
+#   ./bin/letsdo <name>       # run the <name> agent in the loop (exit 0 on stop)
+#   ./bin/letsdo <name> --init # create agents/<name>.md with the starter
+#                               #   default prompt, never run the agent (exit 0)
+#   ./bin/letsdo --init <name>  # same, flag-first form
+#   ./bin/letsdo --version    # version, exit 0
+#   ./bin/letsdo --help       # help, exit 0
+#   ./bin/letsdo              # usage and agent list, exit 1
+#   ./bin/letsdo --badopt     # "unknown option" + usage, exit 1
 #
 # Environment:
 #   LETSDO_ROOT             project root with agents/ (default — current folder)
@@ -28,6 +36,6 @@
 # A new agent = a new agents/<name>.md file, no code changes needed.
 #
 
-require_relative "../lib/letsdo"
+require_relative '../lib/letsdo'
 
-exit Letsdo::CLI.run(ARGV)
+exit Letsdo::CLI.run(ARGV)

data/lib/letsdo/agent.rb

@@ -2,7 +2,10 @@
 
 module Letsdo
   # A single agent run: reads the prompt from agents/<name>.md by agent name
-  # and runs pi with that prompt. Returns the pi exit code.
+  # (falling back to the built-in default prompt when the file is missing)
+  # and runs pi with that prompt. Returns the pi exit code. There are no
+  # unknown agents — every name runs, with the file prompt when present and
+  # with Letsdo::DefaultPrompt::TEXT otherwise.
   #
   # This is the logic of one bin/agent run: a prompt store + an output
   # streamer + a pi runner. The orchestrator (a loop while tasks exist)
@@ -29,9 +32,8 @@ module Letsdo
     # Runs the agent once.
     #
     # @return [Integer] pi exit code
-    # @raise [UnknownAgentError] if the agent is not in agents/
     def run
-      prompt = prompt_store.read(@name)
+      prompt = prompt_store.read(@name) || Letsdo::DefaultPrompt::TEXT
       @runner = PiRunner.new(prompt: prompt, flags: @flags, streamer: @streamer, command: @command)
       @runner.run
     end
@@ -42,4 +44,4 @@ module Letsdo
       @prompt_store ||= PromptStore.new(root: @root)
     end
   end
-end
+end

data/lib/letsdo/agent_loop/tasks.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Provider reporting and per-task run wrapping for AgentLoop.
+  module AgentLoopTasks
+    private
+
+    def wrapped_provider
+      lambda do
+        tasks = @task_provider.call
+        @metrics&.provider_result(tasks&.length)
+        report_provider(tasks)
+        tasks
+      end
+    end
+
+    def report_provider(tasks)
+      if tasks.nil?
+        debug('provider: backlog unavailable')
+        @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
+      elsif tasks.empty?
+        debug('provider: no open tasks')
+        @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
+      else
+        debug("provider: #{tasks.length} open task(s)")
+        @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
+      end
+    end
+
+    def wrapped_run
+      lambda do |task|
+        wait_while_paused
+        run_one_task(task)
+      end
+    end
+
+    def run_one_task(task)
+      label = task_label(task)
+      @metrics&.run_started(label)
+      @stderr.puts("letsdo: running #{@name} for #{label}")
+      debug("running agent for task #{label}")
+      code = @run_one.call(task)
+      debug("agent run exit #{code}")
+      @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
+    ensure
+      @metrics&.run_finished
+    end
+
+    def task_label(task)
+      id = task.respond_to?(:[]) ? task['id'] : nil
+      return id.to_s unless id.nil? || id.to_s.empty?
+
+      task.to_s
+    end
+
+    def wait_while_paused
+      return unless @pause_gate
+
+      @sleeper.call(AgentLoop::PAUSE_POLL_SECONDS) while @pause_gate.paused?
+    end
+  end
+end

data/lib/letsdo/agent_loop.rb

@@ -1,170 +1,98 @@
 # frozen_string_literal: true
 
+require_relative 'agent_loop/tasks'
+
 module Letsdo
-  # The orchestrator loop wired to the real environment for `letsdo <name>`:
-  #
-  #   Letsdo::Loop        — while the provider gives open tasks, runs the
-  #                         agent (one run = one task); no tasks (or the
-  #                         backlog is unreadable) — waits and checks again;
-  #   task provider       — open tasks assigned to the agent's handle
-  #                         (Letsdo::BacklogTasks by default);
-  #   agent run           — one Letsdo::Agent run per open task;
-  #   signals             — SIGINT/SIGTERM stop the loop: a running pi child
-  #                         is terminated and the process exits with 0.
-  #
-  # Waiting is interruptible: stop signals are delivered as
-  # Letsdo::Stopped raised from the trap, so the loop unwinds right away
-  # instead of waiting out the retry interval (see #on_signal).
-  #
-  # Service output goes to stderr: started, running <name> for <task>, no
-  # open tasks / backlog unavailable with the retry interval, non-zero agent
-  # exit codes, stopped.
+  # The orchestrator loop wired to the real environment for `letsdo <name>`.
   class AgentLoop
+    include AgentLoopTasks
+
     STOP = :letsdo_stop
+    PAUSE_POLL_SECONDS = 0.05
 
-    # @param name [String] agent name (for messages)
-    # @param handle [String] assignee handle of the agent (e.g. "@developer")
-    # @param agent [Letsdo::Agent, nil] agent to run once per task (its
-    #        current runner is terminated on stop); ignored when run_one is
-    #        given
-    # @param run_one [Proc, nil] callable(task) → agent exit code; by default
-    #        the injected agent's #run
-    # @param task_provider [Proc] callable → Array of open tasks (empty = no
-    #        tasks) or nil (backlog unreadable — pause)
-    # @param wait_seconds [Float] retry interval when there are no tasks
-    # @param sleeper [Proc, nil] callable(Float) → waiting; injectable for
-    #        deterministic stops in tests (throw Letsdo::AgentLoop::STOP)
-    # @param stderr [IO] service output stream
-    # @param metrics [Object, nil] optional header-metrics facade
-    #        (Letsdo::Tui::Metrics in TUI mode): receives provider_result
-    #        on every provider call and run_started/run_finished around
-    #        each agent run; nil in plain mode, so plain behavior is
-    #        byte-identical
-    # @param debug [Boolean, nil] trace [letsdo] lines to stderr; nil = LETSDO_DEBUG
-    def initialize(name:, handle:, agent: nil, run_one: nil, task_provider:,
-                   wait_seconds: 10.0, sleeper: nil, stderr: $stderr, metrics: nil, debug: nil)
+    def initialize(name:, handle:, task_provider:, **opts)
       @name = name
       @handle = handle
-      @agent = agent
-      @run_one = run_one || ->(_task) { @agent.run }
       @task_provider = task_provider
-      @wait_seconds = wait_seconds
-      @stderr = stderr
-      @metrics = metrics
-      @debug = debug.nil? ? ENV["LETSDO_DEBUG"] == "1" : debug
-      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      assign_opts(opts)
     end
 
-    # Runs the loop until stopped (SIGINT/SIGTERM).
-    # Runs the loop until stopped (SIGINT/SIGTERM).
-    #
-    # Stopping is done by raising Letsdo::Stopped from the signal handler:
-    # the raise interrupts whatever the main thread is doing (reading pi
-    # output, waiting for new tasks, running the backlog CLI) and unwinds
-    # the loop. The handler itself only sends SIGTERM to a running pi group
-    # (no waits or IO — safe from a trap) and raises.
-    #
-    # @return [Integer] exit code — always 0 when stopped cleanly
     def run
       @loop = build_loop
       install_signal_handlers
       debug("loop start (agent=#{@name}, handle=#{@handle}, wait=#{@wait_seconds}s)")
-      begin
-        catch(STOP) { @loop.run }
-      rescue Letsdo::Stopped
-        debug("stopped by signal")
-      end
-      debug("loop stopped")
-      @stderr.puts("letsdo: stopped")
+      run_until_stopped
+      debug('loop stopped')
+      @stderr.puts('letsdo: stopped')
       0
     ensure
+      close_watcher
       restore_signal_handlers
     end
 
+    def close_watcher
+      @watcher&.close
+    end
+
     def debug(message)
       warn("[letsdo] loop: #{message}") if @debug
     end
 
-    # Signal handler: sends SIGTERM to a running pi group and raises
-    # Letsdo::Stopped to interrupt the main thread. Nothing else — no IO,
-    # no sleeps (a trap writing to a busy stream deadlocks; the pi is
-    # reaped by Letsdo::PiRunner#run after the unwind).
     def on_signal(_signum)
-      runner = @agent&.runner
-      runner&.terminate_now
+      @agent&.runner&.terminate_now
       raise Letsdo::Stopped
     end
 
     private
 
-    def build_loop
-      @loop = Letsdo::Loop.new(
-        task_provider: wrapped_provider,
-        run_task: wrapped_run,
-        wait_seconds: @wait_seconds,
-        sleeper: @sleeper
-      )
+    def assign_opts(opts)
+      @agent = opts[:agent]
+      @run_one = opts[:run_one] || ->(_task) { @agent.run }
+      @wait_seconds = opts.fetch(:wait_seconds, 10.0)
+      @stderr = opts.fetch(:stderr, $stderr)
+      assign_control_opts(opts)
     end
 
-    # Messages on stderr: open task count before the batch and the wait
-    # reason (no tasks vs unreadable backlog) before every wait.
-    def wrapped_provider
-      lambda do
-        tasks = @task_provider.call
-        @metrics&.provider_result(tasks.nil? ? nil : tasks.length)
-        if tasks.nil?
-          debug("provider: backlog unavailable")
-          @stderr.puts("letsdo: backlog unavailable, retrying in #{@wait_seconds}s")
-        elsif tasks.empty?
-          debug("provider: no open tasks")
-          @stderr.puts("letsdo: no open tasks for #{@name}, retrying in #{@wait_seconds}s")
-        else
-          debug("provider: #{tasks.length} open task(s)")
-          @stderr.puts("letsdo: #{@name} has #{tasks.length} open task(s)")
-        end
-        tasks
-      end
+    def assign_control_opts(opts)
+      @metrics = opts[:metrics]
+      @pause_gate = opts[:pause_gate]
+      @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
+      @watcher = opts[:watcher] || (Watcher.new(path: opts[:watch_path]) if opts[:watch_path])
+      # Precedence is deliberate: an explicitly injected sleeper always wins
+      # over the watcher idle path — tests inject a stop/control sleeper that
+      # must never be bypassed by a configured watcher (TASK-84).
+      @sleeper = opts[:sleeper] || watcher_sleeper || ->(seconds) { sleep(seconds) }
     end
 
-    # One agent run per task; a non-zero exit code is noted but the loop
-    # continues. Metrics events bracket the run so the TUI can count done
-    # tasks and show the running one with its elapsed time.
-    def wrapped_run
-      lambda do |task|
-        @metrics&.run_started(task_label(task))
-        @stderr.puts("letsdo: running #{@name} for #{task_label(task)}")
-        debug("running agent for task #{task_label(task)}")
-        code = @run_one.call(task)
-        debug("agent run exit #{code}")
-        @stderr.puts("letsdo: #{@name} exited with code #{code}") if code != 0
-      ensure
-        @metrics&.run_finished
-      end
+    def watcher_sleeper
+      @watcher && ->(seconds) { @watcher.wait(seconds) }
     end
 
-    # A human-readable label of a task for messages: the id field when
-    # present, the object as-is otherwise.
-    def task_label(task)
-      id = task.respond_to?(:[]) ? task["id"] : nil
-      return id.to_s unless id.nil? || id.to_s.empty?
-
-      task.to_s
+    def run_until_stopped
+      catch(STOP) { @loop.run }
+    rescue Letsdo::Stopped
+      debug('stopped by signal')
     end
 
-    # The default waiting blocks only for the retry interval: a stop signal
-    # interrupts it as Letsdo::Stopped raised from the trap.
-    def interruptible_sleeper
-      ->(seconds) { sleep(seconds) }
+    def build_loop
+      Letsdo::Loop.new(
+        task_provider: wrapped_provider,
+        run_task: wrapped_run,
+        wait_seconds: @wait_seconds,
+        sleeper: @sleeper
+      )
     end
 
     def install_signal_handlers
-      Signal.trap("SIGINT", method(:on_signal))
-      Signal.trap("SIGTERM", method(:on_signal))
+      Signal.trap('SIGINT', method(:on_signal))
+      Signal.trap('SIGTERM', method(:on_signal))
+      Signal.trap('SIGHUP', method(:on_signal))
     end
 
     def restore_signal_handlers
-      Signal.trap("SIGINT", "DEFAULT")
-      Signal.trap("SIGTERM", "DEFAULT")
+      Signal.trap('SIGINT', 'DEFAULT')
+      Signal.trap('SIGTERM', 'DEFAULT')
+      Signal.trap('SIGHUP', 'DEFAULT')
     end
   end
-end
+end

data/lib/letsdo/backlog_tasks.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
-require "open3"
-require "shellwords"
+require 'json'
+require 'shellwords'
 
 module Letsdo
   # Task provider for Letsdo::Loop backed by the real backlog CLI:
@@ -23,7 +22,7 @@ module Letsdo
     # @param env [Hash, nil] environment for the CLI child (nil = inherit
     #        the process environment; injected in tests to control the
     #        fake backlog scenarios)
-    def initialize(handle:, command: "backlog", cwd: nil, env: nil)
+    def initialize(handle:, command: 'backlog', cwd: nil, env: nil)
       @handle = handle
       @command = command
       @cwd = cwd
@@ -35,10 +34,10 @@ module Letsdo
     # @return [Array<Hash>, nil] open tasks; nil when the backlog is unreadable
     def call
       args = @env ? [@env, *command_line] : command_line
-      out, _err, status = Open3.capture3(*args, chdir: @cwd)
+      out, _err, status = Letsdo::Capture.new(*args, chdir: @cwd).run
       return nil unless status.success?
 
-      tasks = JSON.parse(out)["tasks"]
+      tasks = JSON.parse(out)['tasks']
       tasks.is_a?(Array) ? tasks : nil
     rescue Errno::ENOENT, JSON::ParserError, TypeError
       nil
@@ -50,11 +49,11 @@ module Letsdo
     def command_line
       [
         *Shellwords.split(@command),
-        "task", "list",
-        "--assignee", @handle,
-        "--exclude-status", "Done",
-        "--json"
+        'task', 'list',
+        '--assignee', @handle,
+        '--exclude-status', 'Done',
+        '--json'
       ]
     end
   end
-end
+end

data/lib/letsdo/capture.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # Captures a child command's stdout and stderr (like Open3.capture3)
+  # while tolerating an asynchronous Letsdo::Stopped that lands mid-call —
+  # a TUI quit or a signal raised into the main thread. Open3's capture3
+  # is not interruption-safe: its ensure closes the pipes while its reader
+  # threads are still blocked in IO#read, and each reader then dies with
+  # "stream closed in another thread" and prints a report_on_exception dump.
+  #
+  # Here the reader threads report no exception and rescue that benign
+  # IOError, and the child is reaped even when the wait is interrupted, so
+  # a stop can never leave dumps or zombies. Other reader errors still
+  # re-raise through Thread#value, keeping real failures visible.
+  class Capture
+    # @param args [Array] command arguments for Process.spawn (an optional
+    #        leading environment hash is preserved)
+    # @param chdir [String, nil] working directory for the child (nil =
+    #        inherit the current one)
+    def initialize(*args, chdir: nil)
+      @args = args
+      @chdir = chdir
+      @out_r, @out_w = IO.pipe
+      @err_r, @err_w = IO.pipe
+    end
+
+    # Runs the command.
+    #
+    # @return [Array(String, String, Process::Status)] stdout, stderr, status
+    def run
+      @pid = spawn_child
+      @out_w.close
+      @err_w.close
+      readers = [quiet_reader(@out_r), quiet_reader(@err_r)]
+      status = wait_and_reap(@pid)
+      @reaped = true
+      [readers[0].value, readers[1].value, status]
+    ensure
+      cleanup
+    end
+
+    private
+
+    def spawn_child
+      opts = { out: @out_w, err: @err_w, pgroup: true }
+      opts[:chdir] = @chdir if @chdir
+      Process.spawn(*@args, **opts)
+    end
+
+    # A stdout/stderr reader thread that stays silent when its pipe is
+    # closed while still reading (the stop path) and returns nil instead.
+    def quiet_reader(pipe)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        pipe.read
+      rescue IOError
+        nil
+      end
+    end
+
+    def wait_and_reap(pid)
+      _, status = Process.wait2(pid)
+      status
+    end
+
+    # Kills the child's process group and reaps it when the normal wait was
+    # interrupted (a stop raised into the main thread). Killing the whole
+    # group also terminates any grandchildren that inherited the child's
+    # stdout/stderr pipes, so none of them is left holding the pipes open
+    # (TASK-84). A no-op when the child was already reaped normally.
+    def terminate_and_reap(pid)
+      return unless pid
+
+      kill_group(pid)
+      reap(pid)
+    end
+
+    def kill_group(pid)
+      Process.kill('TERM', -pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    def reap(pid)
+      Process.wait2(pid)
+    rescue Errno::ECHILD
+      nil
+    end
+
+    def cleanup
+      close_quietly(@out_w)
+      close_quietly(@err_w)
+      close_quietly(@out_r)
+      close_quietly(@err_r)
+      terminate_and_reap(@pid) unless @reaped
+    end
+
+    def close_quietly(io)
+      io.close unless io.nil? || io.closed?
+    rescue IOError
+      nil
+    end
+  end
+end

data/lib/letsdo/cli/init.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Letsdo
+  # The --init scaffold command (TASK-44): `letsdo <name> --init` and
+  # `letsdo --init <name>` create agents/<name>.md with the starter default
+  # prompt (Letsdo::DefaultPrompt::TEXT) so the agent can be customized
+  # later. The agent itself is never started. PromptStore#create_agent
+  # already guarantees no overwrite and nothing outside agents/ — this
+  # module only maps the results to messages and exit codes.
+  module CLIInit
+    private
+
+    # Creates agents/<name>.md. Success prints "created <path>" (stdout),
+    # exit 0; an unsafe name or an already existing file prints the error
+    # on stderr, exit 1; a missing name falls back to usage, exit 1.
+    def init_command(argv)
+      name = argv[0] == '--init' ? argv[1] : argv[0]
+      return usage_error if name.nil?
+      return init_error("invalid agent name: #{name}") if PromptStore.unsafe_name?(name)
+
+      store = PromptStore.new(root: @root)
+      return init_error("agents/#{name}.md already exists") unless store.create_agent(name, Letsdo::DefaultPrompt::TEXT)
+
+      @stdout.puts("created #{store.agent_path(name)}")
+      0
+    end
+
+    def init_error(message)
+      @stderr.puts("letsdo: #{message}")
+      1
+    end
+  end
+end