letsdo 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9576e7f61d65dbf1379b3e4fcce4831f3162432b9039dc2153f7952201420091
-  data.tar.gz: 679c98fd2628270bb62cf2f35c6a9d13653dd75a3ebe48aa83abc77c3aeccd97
+  metadata.gz: f15aee491b4d0954c628e52566908e6b7ea35428c347a79822f5781198ea4be9
+  data.tar.gz: 71b47328ea44b224cb250e4bb8d0e58c052ddd054cd950fa1b058c85933f6a91
 SHA512:
-  metadata.gz: 8a6744c21cd6681ac8fde456977962f8a1c8a79cfd8e8157091b0d3ba42848d29f982dd622880e7b7c03f82ec065d014d56da1b61a2f9cd954f3693fc2218f21
-  data.tar.gz: 2925952a1d86f40fc54d1e20e57c83cec89e0f07579c2a0336e2cc370b94c462516c9686c981aedc4b456120ec42fcd51859386685be342c8999ca5bcc3d53d7
+  metadata.gz: eab4462fe5a7bec0981c9b2a803a02063d1714cc049f51f5add4053f80c302b917491465dda6d90aa66a59fb668b33a5d2166ea95589d317e1958a3756564f1c
+  data.tar.gz: 5f1b243e5bce00874965683d68bebf22c2c9cec992e6f8ab1e825db3a0796781a47bf51be934b5c8c5409c7ad1cf85a83d8a872c807b8d4e5a6023c888f8ca73

data/README.md

@@ -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.2.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/lib/letsdo/agent_loop.rb

@@ -26,9 +26,14 @@ module Letsdo
       @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
@@ -52,7 +57,15 @@ module Letsdo
       @metrics = opts[:metrics]
       @pause_gate = opts[:pause_gate]
       @debug = opts[:debug].nil? ? ENV['LETSDO_DEBUG'] == '1' : opts[:debug]
-      @sleeper = opts[:sleeper] || ->(seconds) { sleep(seconds) }
+      @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
+
+    def watcher_sleeper
+      @watcher && ->(seconds) { @watcher.wait(seconds) }
     end
 
     def run_until_stopped

data/lib/letsdo/capture.rb

@@ -33,6 +33,7 @@ module Letsdo
       @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
@@ -41,7 +42,7 @@ module Letsdo
     private
 
     def spawn_child
-      opts = { out: @out_w, err: @err_w }
+      opts = { out: @out_w, err: @err_w, pgroup: true }
       opts[:chdir] = @chdir if @chdir
       Process.spawn(*@args, **opts)
     end
@@ -62,12 +63,26 @@ module Letsdo
       status
     end
 
-    # Reaps pid if the normal wait never ran (the wait was interrupted by a
-    # stop); a no-op when the child was already reaped.
-    def reattach_reaper(pid)
+    # 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
 
-      Process.detach(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
@@ -77,7 +92,7 @@ module Letsdo
       close_quietly(@err_w)
       close_quietly(@out_r)
       close_quietly(@err_r)
-      reattach_reaper(@pid)
+      terminate_and_reap(@pid) unless @reaped
     end
 
     def close_quietly(io)

data/lib/letsdo/cli/launch.rb

@@ -76,7 +76,12 @@ module Letsdo
       AgentLoop.new(name: name, handle: handle, agent: agent,
                     task_provider: -> { provider.call },
                     wait_seconds: wait_seconds, sleeper: @sleeper, stderr: opts[:stderr],
-                    metrics: opts[:metrics], pause_gate: opts[:pause_gate])
+                    metrics: opts[:metrics], pause_gate: opts[:pause_gate],
+                    watcher: backlog_watcher)
+    end
+
+    def backlog_watcher
+      Watcher.new(path: File.join(@root, 'backlog'), poll_seconds: wait_seconds)
     end
   end
 end

data/lib/letsdo/output_streamer.rb

@@ -37,10 +37,14 @@ module Letsdo
     end
 
     def finish
-      return unless @last_char && @last_char != "\n"
-
-      text_sink.write("\n")
-      text_sink.flush unless @log
+      if @last_char && @last_char != "\n"
+        text_sink.write("\n")
+        text_sink.flush unless @log
+      end
+      # Reset so the next run's finish is a no-op unless new text arrived —
+      # otherwise a tool-only run after a text run writes a spurious blank
+      # line (TASK-77).
+      @last_char = nil
     end
 
     private

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

@@ -7,11 +7,9 @@ module Letsdo
       private
 
       def input_loop
-        with_raw_input do
-          repaint
-          @last_repaint = @clock.call
-          loop { break if @stop || !poll_once }
-        end
+        repaint
+        @last_repaint = @clock.call
+        loop { break if @stop || !poll_once }
       rescue StandardError
         nil
       end

data/lib/letsdo/tui/session.rb

@@ -25,8 +25,7 @@ module Letsdo
       def run(&work)
         install_winch_handler
         @terminal.enter
-        start_input_thread
-        work.call
+        run_work(&work)
       rescue Letsdo::Stopped
         0
       ensure
@@ -35,6 +34,13 @@ module Letsdo
         restore_winch_handler
       end
 
+      def run_work(&work)
+        with_raw_input do
+          start_input_thread
+          work.call
+        end
+      end
+
       private
 
       def assign_identity(opts)
@@ -68,6 +74,10 @@ module Letsdo
         @input_thread = nil
       end
 
+      # Enters raw mode on the keyboard for the duration of the block. Held
+      # by the main thread (not the killable input thread) so the terminal
+      # state is restored on every quit path — a killed input thread would
+      # leave the shared tty in raw mode and break the calling shell (TASK-83).
       def with_raw_input(&block)
         if @input.stdin.tty? && @input.stdin.respond_to?(:raw)
           @input.stdin.raw(&block)

data/lib/letsdo/tui/terminal.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'tty-cursor'
-
 module Letsdo
   module Tui
     # Thin wrapper over the terminal: alternate screen, cursor handling and
@@ -36,19 +34,28 @@ module Letsdo
 
       # Enters the alternate screen and hides the cursor.
       def enter
-        write(ENTER_ALT_SCREEN + TTY::Cursor.hide)
+        write(ENTER_ALT_SCREEN + cursor.hide)
       end
 
       # Shows the cursor and leaves the alternate screen.
       def leave
-        write(TTY::Cursor.show + LEAVE_ALT_SCREEN)
+        write(cursor.show + LEAVE_ALT_SCREEN)
       end
 
       # Repaints the whole frame: cursor to the top left, then the frame.
       #
+      # Row separators are written as CRLF (\r\n), never bare LF. The TUI
+      # input thread holds stdin in io-console raw mode for the whole
+      # session, and raw mode clears OPOST on the shared tty — without it a
+      # bare \n no longer implies a carriage return, so every row after the
+      # first would start at the previous row's end column and the frame
+      # would wrap/scroll into the "blank activity pane" scramble (TASK-82).
+      # Explicit CRLF renders correctly both in raw mode and on terminals
+      # whose ONLCR already expands \n (a doubled CR is harmless).
+      #
       # @param frame [String] the rendered screen (see Letsdo::Tui::Renderer)
       def render(frame)
-        write(HOME + frame)
+        write(HOME + frame.gsub("\n", "\r\n"))
       end
 
       # The current terminal size.
@@ -61,6 +68,14 @@ module Letsdo
 
       private
 
+      # Loaded lazily (like tty-screen/tty-reader) so requiring letsdo on a
+      # clean Ruby loads no tty-* gems — only the interactive TTY path needs
+      # them (TASK-78).
+      def cursor
+        require 'tty-cursor' unless defined?(TTY::Cursor)
+        TTY::Cursor
+      end
+
       def write(text)
         @stream.write(text)
         @stream.flush

data/lib/letsdo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letsdo
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/letsdo/watcher.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'fiddle/import'
+
+module Letsdo
+  # OS file-change watcher for the backlog folder.
+  #
+  # On Linux it subscribes to inotify (via Fiddle, no external gem) and wakes
+  # as soon as a backlog entry changes; everywhere else it degrades to the
+  # same periodic polling a plain sleeper would do. Either way the wait is
+  # interruptible — a signal trap raising Letsdo::Stopped breaks the
+  # underlying IO.select — and an internal self-pipe lets #wake interrupt a
+  # blocked #wait from another thread.
+  class Watcher
+    # inotify event masks we subscribe to (Linux <sys/inotify.h>).
+    IN_ACCESS       = 0x00000001
+    IN_MODIFY       = 0x00000002
+    IN_ATTRIB       = 0x00000004
+    IN_CLOSE_WRITE  = 0x00000008
+    IN_CLOSE_NOWRITE = 0x00000010
+    IN_OPEN         = 0x00000020
+    IN_MOVED_FROM   = 0x00000040
+    IN_MOVED_TO     = 0x00000080
+    IN_CREATE       = 0x00000100
+    IN_DELETE       = 0x00000200
+    IN_DELETE_SELF  = 0x00000400
+    IN_MOVE_SELF    = 0x00000800
+
+    RELEVANT_MASK = IN_CREATE | IN_MODIFY | IN_CLOSE_WRITE | IN_DELETE |
+                    IN_MOVED_FROM | IN_MOVED_TO | IN_DELETE_SELF | IN_MOVE_SELF
+
+    EXCLUDED_DIR = '.locks'
+
+    # @param path [String] the watched folder (its direct entries)
+    # @param poll_seconds [Float] fallback poll interval / select timeout
+    def initialize(path:, poll_seconds: 10.0)
+      @poll_seconds = poll_seconds
+      @wake_r, @wake_w = IO.pipe
+      @backend = build_backend(path)
+    end
+
+    # Blocks until a relevant backlog change, an explicit #wake, or the poll
+    # timeout. Irrelevant events (e.g. .locks churn) keep the wait going for
+    # the remainder of the timeout.
+    #
+    # @return [Symbol] :change, :wake, or :timeout
+    def wait(timeout = @poll_seconds)
+      deadline = monotonic + timeout
+      loop do
+        result = wait_once(deadline)
+        return result if result
+      end
+    end
+
+    # Interrupts a blocked #wait from another thread.
+    def wake
+      @wake_w.write_nonblock('.')
+    rescue IO::WaitWritable, Errno::EPIPE
+      nil
+    end
+
+    def close
+      @backend&.close
+      close_io(@wake_w)
+      close_io(@wake_r)
+    end
+
+    private
+
+    def wait_once(deadline)
+      remaining = deadline - monotonic
+      return :timeout if remaining <= 0
+
+      ready = IO.select(read_fds, nil, nil, remaining)
+      return :timeout if ready.nil?
+      return :wake if wake_ready?(ready)
+
+      @backend.relevant_event? ? :change : nil
+    end
+
+    def read_fds
+      fds = [@wake_r]
+      fds << @backend.io if @backend
+      fds
+    end
+
+    def wake_ready?(ready)
+      return false unless ready.first.include?(@wake_r)
+
+      drain_wake
+      true
+    end
+
+    def drain_wake
+      @wake_r.read_nonblock(4096)
+    rescue IO::WaitReadable, EOFError
+      nil
+    end
+
+    def build_backend(path)
+      InotifyBackend.new(path, RELEVANT_MASK)
+    rescue InotifyBackend::Unavailable, Fiddle::DLError
+      nil
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def close_io(io)
+      io.close unless io.nil? || io.closed?
+    rescue IOError
+      nil
+    end
+
+    # Linux inotify backend. Construction raises InotifyBackend::Unavailable
+    # when inotify is missing or the watch cannot be set up, so the watcher
+    # falls back to polling through its self-pipe timeout.
+    class InotifyBackend
+      # libc inotify bindings via Fiddle (no external gem).
+      module Lib
+        extend Fiddle::Importer
+        dlload Fiddle.dlopen(nil)
+        extern 'int inotify_init1(int)'
+        extern 'int inotify_add_watch(int, const char*, uint32_t)'
+      end
+
+      # Signals that inotify is unavailable and the watcher should fall back.
+      class Unavailable < StandardError; end
+
+      IN_CLOEXEC = 0x00080000
+      EVENT_HEADER_SIZE = 16
+
+      attr_reader :io
+
+      def initialize(path, mask)
+        fd = Lib.inotify_init1(IN_CLOEXEC)
+        guard(fd)
+        @io = IO.new(fd, 'r', autoclose: true)
+        guard(Lib.inotify_add_watch(fd, path, mask))
+      rescue Unavailable, Fiddle::DLError
+        @io&.close
+        raise Unavailable
+      end
+
+      # Drains pending events and reports whether any relevant (non-.locks)
+      # entry changed.
+      def relevant_event?
+        buffer = @io.read_nonblock(8192)
+        parse_relevant(buffer)
+      rescue IO::WaitReadable, EOFError
+        false
+      end
+
+      def close
+        @io&.close
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def guard(value)
+        raise Unavailable if value.negative?
+      end
+
+      def parse_relevant(buffer)
+        offset = 0
+        relevant = false
+        while offset + EVENT_HEADER_SIZE <= buffer.bytesize
+          _wd, mask, _cookie, len = buffer.byteslice(offset, EVENT_HEADER_SIZE).unpack('L4')
+          name = buffer.byteslice(offset + EVENT_HEADER_SIZE, len).to_s.sub(/\0.*/m, '')
+          relevant ||= relevant_mask?(mask) && !excluded?(name)
+          offset += EVENT_HEADER_SIZE + len
+        end
+        relevant
+      end
+
+      def relevant_mask?(mask)
+        (mask & Watcher::RELEVANT_MASK) != 0
+      end
+
+      def excluded?(name)
+        name == Watcher::EXCLUDED_DIR || name.start_with?("#{Watcher::EXCLUDED_DIR}/")
+      end
+    end
+  end
+end

data/lib/letsdo.rb

@@ -30,6 +30,7 @@ require_relative 'letsdo/agent'
 require_relative 'letsdo/capture'
 require_relative 'letsdo/backlog_tasks'
 require_relative 'letsdo/loop'
+require_relative 'letsdo/watcher'
 require_relative 'letsdo/agent_loop'
 require_relative 'letsdo/control'
 require_relative 'letsdo/tui'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letsdo
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sergei O. Udalov
@@ -122,6 +122,7 @@ files:
 - lib/letsdo/tui/session/view.rb
 - lib/letsdo/tui/terminal.rb
 - lib/letsdo/version.rb
+- lib/letsdo/watcher.rb
 homepage: https://github.com/sergio-fry/letsdo
 licenses:
 - MIT