ratatui_ruby-tea 0.3.1 → 0.4.0

data/lib/ratatui_ruby/tea/command/wait.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # A one-shot timer command.
+      #
+      # Applications need timed events. Notification auto-dismissal,
+      # debounced search, and animation frames all depend on delays.
+      # Building timers from scratch with threads is error-prone.
+      # Cancellation is tricky.
+      #
+      # This command waits, then sends a message. It responds to
+      # cancellation cooperatively. When cancelled, it sends
+      # <tt>Command.cancel(self)</tt> so you know the timer stopped.
+      #
+      # Use it for delayed actions, debounced inputs, or animation loops.
+      #
+      # === Example: Notification dismissal
+      #
+      #   def update(msg, model)
+      #     case msg
+      #     in :save_clicked
+      #       [model.with(notification: "Saved!"), Command.wait(3.0, :dismiss)]
+      #     in :dismiss
+      #       [model.with(notification: nil), nil]
+      #     in Command::Cancel
+      #       [model.with(notification: nil), nil]  # User navigated away
+      #     end
+      #   end
+      #
+      # === Example: Animation loop
+      #
+      #   def update(msg, model)
+      #     case msg
+      #     in :start_animation
+      #       [model.with(frame: 0), Command.tick(0.1, :animate)]
+      #     in :animate
+      #       frame = (model.frame + 1) % 10
+      #       [model.with(frame:), Command.tick(0.1, :animate)]
+      #     end
+      #   end
+      Wait = Data.define(:seconds, :envelope) do
+        include Custom
+
+        # Cooperative cancellation needs no grace period.
+        # The command responds instantly to cancellation via
+        # <tt>Concurrent::Cancellation.timeout</tt>.
+        def tea_cancellation_grace_period
+          0
+        end
+
+        # Executes the timer.
+        #
+        # Waits for <tt>seconds</tt>, then sends <tt>TimerResponse</tt>.
+        # If cancelled, sends <tt>Command.cancel(self)</tt> instead.
+        #
+        # [out] Outlet for sending messages.
+        # [token] Cancellation token from the runtime.
+        def call(out, token)
+          start_time = Time.now
+          timer_cancellation, _origin = Concurrent::Cancellation.timeout(seconds)
+          combined = token.join(timer_cancellation)
+          combined.origin.wait
+
+          if token.canceled?
+            out.put(Command.cancel(self))
+          else
+            elapsed = Time.now - start_time
+            response = Message::Timer.new(envelope:, elapsed:)
+            out.put(Ractor.make_shareable(response))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command.rb

@@ -5,9 +5,14 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-require_relative "command/cancellation_token"
+require "concurrent-edge"
 require_relative "command/custom"
 require_relative "command/outlet"
+require_relative "command/lifecycle"
+require_relative "command/wait"
+require_relative "command/batch"
+require_relative "command/all"
+require_relative "command/http"
 
 module RatatuiRuby
   module Tea
@@ -34,7 +39,14 @@ module RatatuiRuby
       # Sentinel value for application termination.
       #
       # The runtime detects this before dispatching. It breaks the loop immediately.
-      Exit = Data.define
+      class Exit < Data.define
+        include Custom
+
+        # Stub - Exit is a sentinel handled by runtime before dispatch.
+        def call(_out, _token)
+          raise "Exit command should never be dispatched"
+        end
+      end
 
       # Creates a quit command.
       #
@@ -54,6 +66,25 @@ module RatatuiRuby
         Exit.new
       end
 
+      # Creates a fresh cancellation that never fires.
+      #
+      # Some I/O operations cannot be cancelled mid-execution. Ruby's <tt>Net::HTTP</tt>
+      # blocks until completion or timeout — there is no way to interrupt it.
+      #
+      # A shared singleton would be unsafe. If any code path accidentally resolves
+      # the origin, all commands using it become cancelled.
+      #
+      # Use it for commands that wrap non-cancellable blocking I/O.
+      #
+      # === Example
+      #
+      #   token = Command.uncancellable
+      #   HttpCommand.new(url).call(outlet, token)
+      def self.uncancellable
+        cancellation, _origin = Concurrent::Cancellation.new(Concurrent::Promises.resolvable_event)
+        cancellation
+      end
+
       # Sentinel value for command cancellation.
       #
       # Long-running commands (WebSocket listeners, database pollers) run until stopped.
@@ -62,7 +93,14 @@ module RatatuiRuby
       #
       # This type carries the handle (command object) to cancel. The runtime pattern-matches
       # on <tt>Command::Cancel</tt> and signals the token.
-      Cancel = Data.define(:handle)
+      class Cancel < Data.define(:handle)
+        include Custom
+
+        # Stub - Cancel is a sentinel handled by runtime before dispatch.
+        def call(_out, _token)
+          raise "Cancel command should never be dispatched"
+        end
+      end
 
       # Request cancellation of a running command.
       #
@@ -84,16 +122,33 @@ module RatatuiRuby
         Cancel.new(handle:)
       end
 
-      # Sentinel value for command errors.
+      # Error message from a failed command.
+      #
+      # Commands run in background threads. Exceptions bubble up silently.
+      # Your update function never sees them. Backtraces in STDERR corrupt the TUI.
+      #
+      # The runtime catches exceptions and wraps them in Error messages.
+      # Pattern match on Error in your update function. Display the error, log it, or recover.
       #
-      # Commands run in threads. Exceptions bubble up silently. The update function
-      # never sees them, and backtraces in STDERR corrupt the TUI display.
+      # Use it to surface failures from HTTP requests, file I/O, or external processes.
       #
-      # The runtime catches exceptions and pushes <tt>Error</tt> to the queue.
-      # Pattern match on it in your update function.
+      # === Examples
       #
-      # Analogous to <tt>Exit</tt> and <tt>Cancel</tt>.
-      Error = Data.define(:command, :exception)
+      #   Update = ->(message, model) {
+      #     case message
+      #     in Command::Error[command:, exception:]
+      #       # Show error toast
+      #       [model.with(error: exception.message), nil]
+      #     in Command::Error[command: Command::Http, exception:]
+      #       # Retry HTTP request
+      #       [model, command]
+      #     in Command::Error
+      #       # Log and continue
+      #       warn "Command failed: #{message.exception}"
+      #       [model, nil]
+      #     end
+      #   }
+      class Error < Data.define(:command, :exception); end
 
       # Creates an error sentinel.
       #
@@ -140,16 +195,8 @@ module RatatuiRuby
       # - <tt>[tag, :error, {message:}]</tt> if the command cannot start
       #
       # The <tt>status</tt> is the integer exit code (0 = success).
-      System = Data.define(:command, :tag, :stream) do
-        # Command identification — runtime uses this to dispatch as a command.
-        def tea_command?
-          true
-        end
-
-        # Grace period for cleanup after cancellation.
-        def tea_cancellation_grace_period
-          0.1
-        end
+      class System < Data.define(:command, :envelope, :stream)
+        include Custom
 
         # Returns true if streaming mode is enabled.
         def stream?
@@ -173,7 +220,13 @@ module RatatuiRuby
 
         private def batch_execution(out)
           stdout, stderr, status = Open3.capture3(command)
-          out.put(tag, Ractor.make_shareable({ stdout:, stderr:, status: status.exitstatus }))
+          message = Message::System::Batch.new(
+            envelope:,
+            stdout:,
+            stderr:,
+            status: status.exitstatus
+          )
+          out.put(Ractor.make_shareable(message))
         end
 
         private def stream_execution(out, token)
@@ -181,46 +234,74 @@ module RatatuiRuby
             stdin.close
             pid = wait_thr.pid
 
-            stdout_thread = Thread.new do
-              stdout.each_line { |line| out.put(tag, :stdout, line.freeze) }
-            rescue IOError
-              # Stream closed - SIGKILL the child if still alive (forcible cleanup)
-              begin
-                Process.kill("KILL", pid) if wait_thr.alive?
-              rescue Errno::ESRCH
-                # Already dead
-              end
-            end
-            stderr_thread = Thread.new do
-              stderr.each_line { |line| out.put(tag, :stderr, line.freeze) }
-            rescue IOError
-              # Stream closed
-            end
+            # Track which streams are still open
+            streams = { stdout => :stdout, stderr => :stderr }
 
-            # Cooperative cancellation: SIGTERM when token is cancelled
-            cancellation_watcher = Thread.new do
-              sleep 0.01 until token.cancelled? || !wait_thr.alive?
-              if token.cancelled? && wait_thr.alive?
+            until streams.empty?
+              # Check cancellation before blocking on IO.select
+              if token.canceled? && wait_thr.alive?
                 begin
                   Process.kill("TERM", pid)
                 rescue Errno::ESRCH
                   # Already dead
                 end
               end
+
+              # Wait up to 0.05s for any stream to have data
+              ready = IO.select(streams.keys, nil, nil, 0.05)
+              next unless ready
+
+              ready[0].each do |io|
+                stream_type = streams[io]
+                begin
+                  line = io.read_nonblock(8192, exception: false)
+                  case line
+                  when :wait_readable
+                    next
+                  when nil, ""
+                    # EOF - stream closed
+                    streams.delete(io)
+                  else
+                    # Split into lines and send each
+                    line.each_line do |l|
+                      msg = Message::System::Stream.new(
+                        envelope:,
+                        stream: stream_type,
+                        content: l.freeze,
+                        status: nil
+                      )
+                      out.put(Ractor.make_shareable(msg))
+                    end
+                  end
+                rescue EOFError
+                  streams.delete(io)
+                rescue IOError
+                  # Stream forcibly closed
+                  streams.delete(io)
+                end
+              end
             end
 
+            # Wait for process to finish
             wait_thr.join
 
-            # Child exited; clean up threads
-            stdout_thread.kill
-            stderr_thread.kill
-            cancellation_watcher.kill
-
             status = wait_thr.value.exitstatus
-            out.put(tag, :complete, Ractor.make_shareable({ status: }))
+            msg = Message::System::Stream.new(
+              envelope:,
+              stream: :complete,
+              content: nil,
+              status:
+            )
+            out.put(Ractor.make_shareable(msg))
           end
         rescue Errno::ENOENT, Errno::EACCES => e
-          out.put(tag, :error, Ractor.make_shareable({ message: e.message }))
+          msg = Message::System::Stream.new(
+            envelope:,
+            stream: :error,
+            content: e.message,
+            status: nil
+          )
+          out.put(Ractor.make_shareable(msg))
         end
       end
 
@@ -265,25 +346,24 @@ module RatatuiRuby
       #       [model.with(loading: false, error: message), nil]
       #     end
       #   end
-      def self.system(command, tag, stream: false)
-        System.new(command:, tag:, stream:)
+      def self.system(command, envelope, stream: false)
+        System.new(command:, envelope:, stream:)
       end
 
       # Wraps another command's result with a transformation.
       #
-      # Fractal Architecture requires composition. Child bags produce commands
-      # with their own tags. Parent bags need those results routed back with
+      # Fractal Architecture requires composition. Child fragments produce commands
+      # with their own tags. Parent fragments need those results routed back with
       # a parent prefix. Without transformation, update functions become
       # monolithic "God Reducers" that know about every child's internals.
       #
       # This command wraps an inner command and transforms its result message.
-      # The parent bag delegates to the child, then intercepts the result and
+      # The parent fragment delegates to the child, then intercepts the result and
       # adds its routing prefix. Clean separation. No coupling.
       #
-      # Use it to compose child bags that return their own commands.
-      Mapped = Data.define(:inner_command, :mapper) do
-        # Command identification for runtime dispatch.
-        def tea_command? = true
+      # Use it to compose child fragments that return their own commands.
+      class Mapped < Data.define(:inner_command, :mapper)
+        include Custom
 
         # Grace period delegates to inner command.
         def tea_cancellation_grace_period
@@ -293,8 +373,8 @@ module RatatuiRuby
 
         # Executes the inner command, waits for result, and transforms it.
         def call(out, token)
-          inner_queue = Queue.new
-          inner_outlet = Outlet.new(inner_queue)
+          inner_channel = Concurrent::Promises::Channel.new
+          inner_outlet = Outlet.new(inner_channel, lifecycle: out.live)
 
           # Dispatch inner command
           if inner_command.respond_to?(:call)
@@ -304,7 +384,7 @@ module RatatuiRuby
           end
 
           # Transform result and send
-          inner_message = inner_queue.pop
+          inner_message = inner_channel.pop
           transformed = mapper.call(inner_message)
           out.put(*transformed)
         end
@@ -335,6 +415,10 @@ module RatatuiRuby
       # Reusable procs and lambdas share identity. Dispatch them twice, and
       # +Command.cancel+ would cancel both. Wrap them to get distinct handles.
       #
+      # The callable must be Ractor-shareable (cannot capture mutable state).
+      # Create resources like database connections inside the callable, not in
+      # the closure. See the Custom Commands guide for details.
+      #
       # [callable] Proc, lambda, or any object responding to +call(out, token)+.
       #            If omitted, the block is used.
       # [grace_period] Cleanup time override. Default: 2.0 seconds.
@@ -346,20 +430,117 @@ module RatatuiRuby
       #
       #   # With block
       #   cmd = Command.custom(grace_period: 5.0) do |out, token|
-      #     until token.cancelled?
+      #       until token.canceled?
       #       out.put(:tick, Time.now)
       #       sleep 1
       #     end
       #   end
       def self.custom(callable = nil, grace_period: nil, &block)
-        Wrapped.new(callable: callable || block, grace_period:)
+        c = callable || block
+
+        # Debug mode: validate that callable can be made shareable (fail fast)
+        if RatatuiRuby::Debug.enabled?
+          begin
+            c = Ractor.make_shareable(c)
+          rescue Ractor::IsolationError
+            raise RatatuiRuby::Error::Invariant,
+              "Command.custom requires a Ractor-shareable callable. " \
+                "#{c.class} is not shareable. Use Ractor.make_shareable or define at top-level."
+          end
+        end
+        # Production mode: skip validation (Ractors not yet used, avoid overhead)
+
+        Wrapped.new(callable: c, grace_period:)
+      end
+
+      # Creates a one-shot timer command.
+      #
+      # Waits for +seconds+ then sends +TimerResponse+ to the update function.
+      # Use for delayed actions like notification dismissal or debounced search.
+      #
+      # [seconds] Duration to wait (Float or Integer).
+      # [envelope] Symbol to tag the result message.
+      def self.wait(seconds, envelope)
+        Wait.new(seconds:, envelope:)
+      end
+
+      # Creates a recurring timer command.
+      #
+      # Identical to +wait+, but semantically used for animation frames where
+      # the update function re-dispatches to continue the animation loop.
+      #
+      # [interval] Duration between ticks (Float or Integer).
+      # [tag] Symbol to tag the result message.
+      singleton_class.alias_method :tick, :wait
+
+      # Creates a parallel batch command.
+      #
+      # Applications fetch data from multiple sources. Dashboard panels load
+      # users, stats, and notifications. Waiting sequentially is slow.
+      # Managing threads and error handling manually is error-prone.
+      #
+      # This command runs children in parallel. Each child sends its own messages
+      # independently. The batch completes when all children finish or when
+      # cancellation fires.
+      #
+      # Use it for parallel fetches, concurrent refreshes, or any work that
+      # does not need coordinated results.
+      #
+      # [commands] One or more commands to run in parallel. Pass multiple
+      #   arguments or a single array.
+      #
+      # === Example
+      #
+      #   # Variadic syntax
+      #   Command.batch(
+      #     Command.http(:get, "/users", :users),
+      #     Command.http(:get, "/stats", :stats),
+      #   )
+      #
+      #   # Array syntax
+      #   Command.batch([cmd1, cmd2, cmd3])
+      def self.batch(*)
+        Batch.new(*)
+      end
+
+      # Creates an aggregating parallel command.
+      #
+      # Applications load dashboards that combine user, settings, and stats.
+      # Fire-and-forget loses correlation. This command waits for all children
+      # and returns their results together in a single message.
+      #
+      # [commands] One or more commands to run in parallel. Pass multiple
+      #   arguments or a single array.
+      #
+      # === Example
+      #
+      #   # Variadic syntax
+      #   Command.all(
+      #     Command.http(:get, "/users", :_),
+      #     Command.http(:get, "/stats", :_),
+      #   )
+      #   # Produces: [:all, [user_result, stats_result]]
+      def self.all(envelope, *)
+        All.new(envelope, *)
+      end
+
+      # Creates an HTTP request command.
+      # Supports DWIM arity - see Http.new for patterns.
+      def self.http(*, **)
+        Http.new(*, **)
       end
 
       # :nodoc:
-      Wrapped = Data.define(:callable, :grace_period) do
+      class Wrapped < Data.define(:callable, :grace_period)
         include Custom
-        def tea_cancellation_grace_period = grace_period || super
-        def call(out, token) = callable.call(out, token)
+        def tea_cancellation_grace_period
+          grace_period || super
+        end
+
+        # :nodoc:
+        def call(out, token)
+          callable.call(out, token)
+        end
       end
       private_constant :Wrapped
     end

data/lib/ratatui_ruby/tea/message/all.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Message
+      # Response from Command.all aggregating parallel execution.
+      #
+      # Running multiple commands in parallel needs aggregated results. Without
+      # structured responses, handling mixed success/failure requires manual
+      # array parsing.
+      #
+      # This response collects all child results and provides predicates for
+      # success checking. Include Predicates for safe predicate calls.
+      #
+      # Use it to handle <tt>Command.all</tt> completions.
+      #
+      # === Example
+      #
+      #   case msg
+      #   in { type: :all, envelope: :parallel, results: }
+      #     model.with(outputs: results)
+      #   end
+      #
+      All = Data.define(:envelope, :results, :nested) do
+        include Predicates
+
+        # Returns <tt>true</tt> for all responses.
+        def all?
+          true
+        end
+
+        # Deconstructs for pattern matching.
+        #
+        # Returns a hash with <tt>:type</tt>, <tt>:envelope</tt>, <tt>:results</tt>,
+        # and <tt>:nested</tt>.
+        def deconstruct_keys(_keys)
+          { type: :all, envelope:, results:, nested: }
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/message/http_response.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Message
+      # Response from an HTTP command.
+      #
+      # HTTP requests return status codes, bodies, and headers. Errors may occur.
+      # Without structured responses, handling success vs. error requires manual
+      # checks on raw data.
+      #
+      # This response includes predicates for common checks and deconstructs for
+      # pattern matching. Include Predicates for safe predicate calls on any message.
+      #
+      # Use it to handle +Command.http+ completions.
+      #
+      # === Example
+      #
+      #   case msg
+      #   in { type: :http, envelope: :users, status:, body: }
+      #     model.with(users: JSON.parse(body))
+      #   in { type: :http, envelope: :users, error: }
+      #     model.with(error:)
+      #   end
+      #
+      HttpResponse = Data.define(:envelope, :status, :body, :headers, :error) do
+        include Predicates
+
+        # Returns +true+ for HTTP responses.
+        def http?
+          true
+        end
+
+        # Returns +true+ if status is 2xx.
+        def success?
+          status&.between?(200, 299)
+        end
+
+        # Returns +true+ if an error occurred.
+        def error?
+          !!error
+        end
+
+        # Deconstructs for pattern matching.
+        #
+        # Returns a hash with <tt>:type</tt>, <tt>:envelope</tt>, and either
+        # <tt>:error</tt> or <tt>:status</tt>, <tt>:body</tt>, <tt>:headers</tt>.
+        def deconstruct_keys(_keys)
+          if error
+            { type: :http, envelope:, error: }
+          else
+            { type: :http, envelope:, status:, body:, headers: }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/message/system/batch.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module Message
+      # System command response types.
+      #
+      # Contains message types for system command results.
+      module System
+        # Response from a system command (batch mode).
+        #
+        # Shell commands capture output and status. Without structured responses,
+        # handling success vs error requires manual parsing of arrays.
+        #
+        # This response includes predicates for common checks and deconstructs for
+        # pattern matching. Include Predicates for safe predicate calls.
+        #
+        # Use it to handle <tt>Command.system</tt> completions (batch mode).
+        #
+        # === Example
+        #
+        #   case msg
+        #   in { type: :system, envelope: :build, status: 0, stdout: }
+        #     model.with(output: stdout)
+        #   in { type: :system, envelope: :build, status: }
+        #     model.with(error: "Build failed with exit #{status}")
+        #   end
+        #
+        Batch = Data.define(:envelope, :stdout, :stderr, :status) do
+          include Predicates
+
+          # Returns <tt>true</tt> for system responses.
+          def system?
+            true
+          end
+
+          # Returns <tt>true</tt> if status is 0.
+          def success?
+            status == 0
+          end
+
+          # Returns <tt>true</tt> if status is non-zero.
+          def error?
+            status != 0
+          end
+
+          # Deconstructs for pattern matching.
+          #
+          # Returns a hash with <tt>:type</tt>, <tt>:envelope</tt>, <tt>:stdout</tt>,
+          # <tt>:stderr</tt>, and <tt>:status</tt>.
+          def deconstruct_keys(_keys)
+            { type: :system, envelope:, stdout:, stderr:, status: }
+          end
+        end
+      end
+    end
+  end
+end