ratatui_ruby-tea 0.3.0 → 0.3.1

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

@@ -0,0 +1,135 @@
+# 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
+      # Cooperative cancellation mechanism for long-running commands.
+      #
+      # Long-running commands block the event loop. Commands that poll, stream, or wait
+      # indefinitely prevent clean shutdown. Killing threads mid-operation corrupts state.
+      #
+      # This class signals cancellation requests. Commands check +cancelled?+ periodically
+      # and stop gracefully. The runtime calls +cancel!+ when shutdown begins.
+      #
+      # Use it to implement WebSocket handlers, database pollers, or any command that loops.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class PollerCommand
+      #     include Tea::Command::Custom
+      #
+      #     def call(out, token)
+      #       until token.cancelled?
+      #         data = fetch_batch
+      #         out.put(:batch, data)
+      #         sleep 5
+      #       end
+      #       out.put(:poller_stopped)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      class CancellationToken
+        # Number of times +cancel!+ has been called. :nodoc:
+        #
+        # Exposed for testing thread-safety. Not part of the public API.
+        attr_reader :cancel_count
+
+        # Creates a new cancellation token in the non-cancelled state.
+        def initialize
+          @cancel_count = 0
+          @mutex = Mutex.new
+        end
+
+        # Signals cancellation. Thread-safe.
+        #
+        # Call this to request the command stop. The command checks +cancelled?+
+        # and stops at the next safe point.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   token = CancellationToken.new
+        #   token.cancel!
+        #   token.cancelled?  # => true
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def cancel!
+          @mutex.synchronize do
+            current = @cancel_count
+            sleep 0 # Force context switch (enables thread-safety testing)
+            @cancel_count = current + 1
+          end
+        end
+
+        # Checks if cancellation was requested. Thread-safe.
+        #
+        # Commands call this periodically in their main loop. When it returns
+        # <tt>true</tt>, the command should clean up and exit.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   until token.cancelled?
+        #     do_work
+        #     sleep 1
+        #   end
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def cancelled?
+          @cancel_count > 0
+        end
+
+        # Null object for commands that ignore cancellation.
+        #
+        # Some commands complete quickly and do not check for cancellation.
+        # Pass this when the command signature requires a token but the
+        # command does not use it.
+        #
+        # Ractor-shareable. Calling <tt>cancel!</tt> does nothing.
+        class NoneToken < Data.define(:cancelled?)
+          # Does nothing. Ignores cancellation requests.
+          #
+          # === Example
+          #
+          #--
+          # SPDX-SnippetBegin
+          # SPDX-FileCopyrightText: 2026 Kerrick Long
+          # SPDX-License-Identifier: MIT-0
+          #++
+          #   CancellationToken::NONE.cancel!  # => nil (no effect)
+          #--
+          # SPDX-SnippetEnd
+          #++
+          def cancel!
+            nil
+          end
+        end
+
+        # Singleton null token. Always returns <tt>cancelled? == false</tt>.
+        NONE = NoneToken.new(cancelled?: false)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# 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
+      # Mixin for user-defined custom commands.
+      #
+      # Custom commands extend Tea with side effects: WebSockets, gRPC, database polls,
+      # background tasks. The runtime dispatches them in threads and routes results
+      # back as messages.
+      #
+      # Include this module to identify your class as a command. The runtime uses
+      # +tea_command?+ to distinguish commands from plain models. Override
+      # +tea_cancellation_grace_period+ if your cleanup takes longer than 100 milliseconds.
+      #
+      # Use it to build real-time features, long-polling connections, or background workers.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class WebSocketCommand
+      #     include RatatuiRuby::Tea::Command::Custom
+      #
+      #     def initialize(url)
+      #       @url = url
+      #     end
+      #
+      #     def call(out, token)
+      #       ws = WebSocket::Client.new(@url)
+      #       ws.on_message { |msg| out.put(:ws_message, msg) }
+      #       ws.connect
+      #
+      #       until token.cancelled?
+      #         ws.ping
+      #         sleep 1
+      #       end
+      #
+      #       ws.close
+      #     end
+      #
+      #     # WebSocket close handshake needs extra time
+      #     def tea_cancellation_grace_period
+      #       5.0
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      module Custom
+        # Brand predicate for command identification.
+        #
+        # The runtime calls this to distinguish commands from plain models.
+        # Returns <tt>true</tt> unconditionally.
+        #
+        # You do not need to override this method.
+        def tea_command?
+          true
+        end
+
+        # Cleanup time after cancellation is requested. In seconds.
+        #
+        # When the runtime cancels your command (app exit, navigation, explicit cancel),
+        # it calls <tt>token.cancel!</tt> and waits this long for your command to stop.
+        # If your command does not exit within this window, it is force-killed.
+        #
+        # *This is NOT a lifetime limit.* Your command runs indefinitely until cancelled.
+        # A WebSocket open for 15 minutes is fine. This timeout only applies to the
+        # cleanup phase after cancellation is requested.
+        #
+        # Override this method to specify how long your cleanup takes:
+        #
+        # - <tt>0.5</tt> — Quick HTTP abort, no cleanup needed
+        # - <tt>2.0</tt> — Default, suitable for most commands
+        # - <tt>5.0</tt> — WebSocket close handshake with remote server
+        # - <tt>Float::INFINITY</tt> — Never force-kill (database transactions)
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   # Database transactions should never be interrupted mid-write
+        #   def tea_cancellation_grace_period
+        #     Float::INFINITY
+        #   end
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def tea_cancellation_grace_period
+          0.1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby"
+
+module RatatuiRuby
+  module Tea
+    module Command
+      # Messaging gateway for custom commands.
+      #
+      # Custom commands run in background threads. They produce results that the
+      # main loop consumes.
+      #
+      # Managing queues and message formats manually is tedious. It scatters queue
+      # logic across your codebase and makes mistakes easy.
+      #
+      # This class wraps the queue with a clean API. Call +put+ to send tagged
+      # messages. Debug mode validates Ractor-shareability.
+      #
+      # Use it to send results from HTTP requests, WebSocket streams, or database polls.
+      #
+      # === Example (One-Shot)
+      #
+      # Commands run in their own thread. Blocking calls work fine:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class FetchUserCommand
+      #     include Tea::Command::Custom
+      #
+      #     def initialize(user_id)
+      #       @user_id = user_id
+      #     end
+      #
+      #     def call(out, _token)
+      #       response = Net::HTTP.get(URI("https://api.example.com/users/#{@user_id}"))
+      #       user = JSON.parse(response)
+      #       out.put(:user_fetched, Ractor.make_shareable(user: user))
+      #     rescue => e
+      #       out.put(:user_fetch_failed, error: e.message.freeze)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      #
+      # === Example (Long-Running)
+      #
+      # Commands that loop check the cancellation token:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class PollerCommand
+      #     include Tea::Command::Custom
+      #
+      #     def call(out, token)
+      #       until token.cancelled?
+      #         data = fetch_batch
+      #         out.put(:batch, Ractor.make_shareable(data))
+      #         sleep 5
+      #       end
+      #       out.put(:poller_stopped)
+      #     end
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      class Outlet
+        # Creates an outlet for the given queue.
+        #
+        # The runtime provides the queue. Custom commands receive the outlet as
+        # their first argument.
+        #
+        # [queue] A <tt>Thread::Queue</tt> or compatible object.
+        def initialize(queue)
+          @queue = queue
+        end
+
+        # Sends a tagged message to the runtime.
+        #
+        # Builds an array <tt>[tag, *payload]</tt> and pushes it to the queue.
+        # The update function pattern-matches on the tag.
+        #
+        # Debug mode validates Ractor-shareability. It raises <tt>Error::Invariant</tt>
+        # if the message is not shareable. Production skips this check.
+        #
+        # [tag] Symbol identifying the message type.
+        # [payload] Additional arguments. Freeze them or use <tt>Ractor.make_shareable</tt>.
+        #
+        # === Example
+        #
+        #--
+        # SPDX-SnippetBegin
+        # SPDX-FileCopyrightText: 2026 Kerrick Long
+        # SPDX-License-Identifier: MIT-0
+        #++
+        #   out.put(:user_fetched, user: Ractor.make_shareable(user))
+        #   out.put(:error, message: "Connection failed".freeze)
+        #   out.put(:progress, percent: 42)  # Integers are always shareable
+        #--
+        # SPDX-SnippetEnd
+        #++
+        def put(tag, *payload)
+          message = [tag, *payload].freeze
+
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(message)
+            raise RatatuiRuby::Error::Invariant,
+              "Message is not Ractor-shareable: #{message.inspect}\n" \
+                "Use Ractor.make_shareable or Object#freeze."
+          end
+
+          @queue << message
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/tea/command.rb

@@ -5,6 +5,10 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
+require_relative "command/cancellation_token"
+require_relative "command/custom"
+require_relative "command/outlet"
+
 module RatatuiRuby
   module Tea
     # Commands represent side effects.
@@ -50,12 +54,86 @@ module RatatuiRuby
         Exit.new
       end
 
-      # Command to run a shell command via Open3.
+      # 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.
+      Cancel = Data.define(:handle)
+
+      # 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.
+      #
+      # [handle] The command object to cancel.
+      #
+      # === 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
+
+      # Sentinel value for command errors.
+      #
+      # Commands run in threads. Exceptions bubble up silently. The update function
+      # never sees them, and backtraces in STDERR corrupt the TUI display.
+      #
+      # The runtime catches exceptions and pushes <tt>Error</tt> to the queue.
+      # Pattern match on it in your update function.
+      #
+      # Analogous to <tt>Exit</tt> and <tt>Cancel</tt>.
+      Error = Data.define(:command, :exception)
+
+      # 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)
       #
-      # The runtime executes the command and produces messages. In batch mode
-      # (default), a single message arrives: <tt>[tag, {stdout:, stderr:, status:}]</tt>.
+      # A single message arrives when the command finishes:
+      # <tt>[tag, {stdout:, stderr:, status:}]</tt>
       #
-      # In streaming mode, messages arrive incrementally:
+      # === 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
@@ -63,10 +141,87 @@ module RatatuiRuby
       #
       # 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
+
         # 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)
+          out.put(tag, Ractor.make_shareable({ stdout:, stderr:, status: status.exitstatus }))
+        end
+
+        private def stream_execution(out, token)
+          Open3.popen3(command) do |stdin, stdout, stderr, wait_thr|
+            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
+
+            # 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?
+                begin
+                  Process.kill("TERM", pid)
+                rescue Errno::ESRCH
+                  # Already dead
+                end
+              end
+            end
+
+            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: }))
+          end
+        rescue Errno::ENOENT, Errno::EACCES => e
+          out.put(tag, :error, Ractor.make_shareable({ message: e.message }))
+        end
       end
 
       # Creates a shell execution command.
@@ -114,12 +269,46 @@ module RatatuiRuby
         System.new(command:, tag:, 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 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)
+      # Fractal Architecture requires composition. Child bags produce commands
+      # with their own tags. Parent bags 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
+      # 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
+
+        # 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_queue = Queue.new
+          inner_outlet = Outlet.new(inner_queue)
+
+          # 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_queue.pop
+          transformed = mapper.call(inner_message)
+          out.put(*transformed)
+        end
+      end
 
       # Creates a mapped command for Fractal Architecture composition.
       #
@@ -140,6 +329,39 @@ 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.
+      #
+      # [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.cancelled?
+      #       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:)
+      end
+
+      # :nodoc:
+      Wrapped = Data.define(:callable, :grace_period) do
+        include Custom
+        def tea_cancellation_grace_period = grace_period || super
+        def call(out, token) = callable.call(out, token)
+      end
+      private_constant :Wrapped
     end
   end
 end