ratatui_ruby-tea 0.3.0 → 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,6 +5,15 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
+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
     # Commands represent side effects.
@@ -30,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.
       #
@@ -50,23 +66,243 @@ module RatatuiRuby
         Exit.new
       end
 
-      # Command to run a shell command via Open3.
+      # 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.
+      # Stopping them requires signaling from outside the command. The runtime tracks
+      # active commands by their object identity and routes cancel requests.
+      #
+      # This type carries the handle (command object) to cancel. The runtime pattern-matches
+      # on <tt>Command::Cancel</tt> and signals the token.
+      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.
+      #
+      # The model stores the command handle (the command object itself). Returning
+      # <tt>Command.cancel(handle)</tt> signals the runtime to stop it.
       #
-      # The runtime executes the command and produces messages. In batch mode
-      # (default), a single message arrives: <tt>[tag, {stdout:, stderr:, status:}]</tt>.
+      # [handle] The command object to cancel.
       #
-      # In streaming mode, messages arrive incrementally:
+      # === Example
+      #
+      #   # Dispatch and store handle
+      #   cmd = FetchData.new(url)
+      #   [model.with(active_fetch: cmd), cmd]
+      #
+      #   # User clicks cancel
+      #   when :cancel_clicked
+      #     [model.with(active_fetch: nil), Command.cancel(model.active_fetch)]
+      def self.cancel(handle)
+        Cancel.new(handle:)
+      end
+
+      # 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.
+      #
+      # Use it to surface failures from HTTP requests, file I/O, or external processes.
+      #
+      # === Examples
+      #
+      #   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.
+      #
+      # The runtime produces this automatically when a command raises.
+      # Use this factory for testing or for commands that want to signal
+      # error completion without raising.
+      #
+      # [command] The command that failed.
+      # [exception] The exception that was raised.
+      #
+      # === Example
+      #
+      #   def update(message, model)
+      #     case message
+      #     in Command::Error(command:, exception:)
+      #       model.with(error: "#{command.class} failed: #{exception.message}")
+      #     end
+      #   end
+      def self.error(command, exception)
+        Error.new(command:, exception:)
+      end
+
+      # Runs a shell command and routes its output back as messages.
+      #
+      # Apps run external tools: linters, compilers, scripts, system utilities.
+      # The runtime dispatches the command in a thread, so the UI stays responsive.
+      # Batch mode (default) waits for completion; streaming mode shows output live.
+      # Orphaned child processes linger and waste resources, so cancellation sends
+      # <tt>SIGTERM</tt> for graceful shutdown, then <tt>SIGKILL</tt> to prevent orphans.
+      #
+      # Use it to run builds, lint files, execute scripts, or invoke any CLI tool.
+      #
+      # === Batch Mode (default)
+      #
+      # A single message arrives when the command finishes:
+      # <tt>[tag, {stdout:, stderr:, status:}]</tt>
+      #
+      # === Streaming Mode
+      #
+      # Messages arrive incrementally:
       # - <tt>[tag, :stdout, line]</tt> for each stdout line
       # - <tt>[tag, :stderr, line]</tt> for each stderr line
       # - <tt>[tag, :complete, {status:}]</tt> when the command finishes
       # - <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
+      class System < Data.define(:command, :envelope, :stream)
+        include Custom
+
         # Returns true if streaming mode is enabled.
         def stream?
           stream
         end
+
+        # Executes the shell command and sends results via outlet.
+        #
+        # In batch mode, sends a single message with all output.
+        # In streaming mode, sends incremental messages as output arrives.
+        # Respects cancellation token by sending SIGTERM (then SIGKILL) to child.
+        def call(out, token)
+          require "open3"
+
+          if stream?
+            stream_execution(out, token)
+          else
+            batch_execution(out)
+          end
+        end
+
+        private def batch_execution(out)
+          stdout, stderr, status = Open3.capture3(command)
+          message = Message::System::Batch.new(
+            envelope:,
+            stdout:,
+            stderr:,
+            status: status.exitstatus
+          )
+          out.put(Ractor.make_shareable(message))
+        end
+
+        private def stream_execution(out, token)
+          Open3.popen3(command) do |stdin, stdout, stderr, wait_thr|
+            stdin.close
+            pid = wait_thr.pid
+
+            # Track which streams are still open
+            streams = { stdout => :stdout, stderr => :stderr }
+
+            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
+
+            status = wait_thr.value.exitstatus
+            msg = Message::System::Stream.new(
+              envelope:,
+              stream: :complete,
+              content: nil,
+              status:
+            )
+            out.put(Ractor.make_shareable(msg))
+          end
+        rescue Errno::ENOENT, Errno::EACCES => e
+          msg = Message::System::Stream.new(
+            envelope:,
+            stream: :error,
+            content: e.message,
+            status: nil
+          )
+          out.put(Ractor.make_shareable(msg))
+        end
       end
 
       # Creates a shell execution command.
@@ -110,16 +346,49 @@ 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
 
-      # Command that wraps another command's result with a transformation.
+      # Wraps another command's result with a transformation.
+      #
+      # 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.
       #
-      # Fractal Architecture requires composition. Child bags produce commands.
-      # Parent bags route child results back to themselves. +Mapped+ wraps a
-      # child bag's command and transforms its result message into a parent message.
-      Mapped = Data.define(:inner_command, :mapper)
+      # This command wraps an inner command and transforms its result message.
+      # 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 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
+          inner_command.respond_to?(:tea_cancellation_grace_period) ?
+            inner_command.tea_cancellation_grace_period : 0.1
+        end
+
+        # Executes the inner command, waits for result, and transforms it.
+        def call(out, token)
+          inner_channel = Concurrent::Promises::Channel.new
+          inner_outlet = Outlet.new(inner_channel, lifecycle: out.live)
+
+          # Dispatch inner command
+          if inner_command.respond_to?(:call)
+            inner_command.call(inner_outlet, token)
+          else
+            raise ArgumentError, "Inner command must respond to #call"
+          end
+
+          # Transform result and send
+          inner_message = inner_channel.pop
+          transformed = mapper.call(inner_message)
+          out.put(*transformed)
+        end
+      end
 
       # Creates a mapped command for Fractal Architecture composition.
       #
@@ -140,6 +409,140 @@ module RatatuiRuby
       def self.map(inner_command, &mapper)
         Mapped.new(inner_command:, mapper:)
       end
+
+      # Gives a callable unique identity for cancellation.
+      #
+      # 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.
+      #
+      # === Example
+      #
+      #   # With callable
+      #   cmd = Command.custom(->(out, token) { out.put(:fetched, data) })
+      #
+      #   # With block
+      #   cmd = Command.custom(grace_period: 5.0) do |out, token|
+      #       until token.canceled?
+      #       out.put(:tick, Time.now)
+      #       sleep 1
+      #     end
+      #   end
+      def self.custom(callable = nil, grace_period: nil, &block)
+        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:
+      class Wrapped < Data.define(:callable, :grace_period)
+        include Custom
+        def tea_cancellation_grace_period
+          grace_period || super
+        end
+
+        # :nodoc:
+        def call(out, token)
+          callable.call(out, token)
+        end
+      end
+      private_constant :Wrapped
     end
   end
 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