rooibos 0.5.0

data/lib/rooibos/runtime.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby"
+require "concurrent-edge"
+
+module Rooibos
+  # Runs the Model-View-Update event loop.
+  #
+  # Applications need a render loop. You poll events, update state, redraw. Every frame.
+  # The boilerplate is tedious and error-prone.
+  #
+  # This class handles the loop. You provide the model, view, and update. It handles the rest.
+  #
+  # Use it to build applications with predictable state.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   Rooibos.run(
+  #     model: { count: 0 }.freeze,
+  #     view: ->(model, tui) { tui.paragraph(text: model[:count].to_s) },
+  #     update: ->(message, model) { message.q? ? [model, Command.exit] : [model, nil] }
+  #   )
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class Runtime
+    # Starts the MVU event loop.
+    #
+    # Runs until the update function returns a <tt>Command.exit</tt> command.
+    #
+    # == Root Fragment with Init
+    #
+    # Pass a fragment module with <tt>Init</tt>, <tt>Update</tt>, and <tt>View</tt> constants.
+    # This allows your application to do work at startup, and your Update will be called with the result.
+    # It also allows you to create a more complex model with access to <tt>ARGV</tt> and <tt>ENV</tt>.
+    #
+    #   module MyApp
+    #     # Init is any callable, and returns an immutable Model and/or Command, according to your application's needs.
+    #     # The Model is your application's initial state, and the Command is any command to run at startup.
+    #     Init = -> () {
+    #       # To do work at startup:
+    #       return [Data.define(:count).new(count: 0), Command.http("https://api.example.com/data")]
+    #       # To start idle:
+    #       return Data.define(:count).new(count: 0)
+    #     }
+    #
+    #     # Update has access to a single Message, and your fragment's latest immutable Model.
+    #     # It returns a new Model and/or a Command, according to your application's needs.
+    #     Update = ->(message, model) {
+    #       [model, Command.exit]
+    #     }
+    #
+    #     # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
+    #     # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
+    #     View = ->(model, tui) {
+    #       tui.paragraph(text: model.count.to_s)
+    #     }
+    #   end
+    #
+    #   Rooibos.run(MyApp)
+    #
+    # == Root Fragment with auto-Init
+    #
+    # Pass a fragment module with a <tt>Model</tt> class and <tt>Update</tt> and <tt>View</tt> constants.
+    # Your application will be idle until a RatatuiRuby::Event message is sent to your Update.
+    #
+    #   module MyApp
+    #     # Model is anything that responds to <tt>new</tt>.
+    #     Model = Data.define(:count).new(count: 0)
+    #
+    #     # Update has access to a single Message, and your fragment's latest immutable Model.
+    #     # It returns a new Model and/or a Command, according to your application's needs.
+    #     Update = ->(message, model) {
+    #       [model, Command.exit]
+    #     }
+    #
+    #     # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
+    #     # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
+    #     View = ->(model, tui) {
+    #       tui.paragraph(text: model.count.to_s)
+    #     }
+    #   end
+    #
+    #   Rooibos.run(MyApp)
+    #
+    # == Explicit Parameters API
+    #
+    # A root fragment is not required. You can pass individual parameters:
+    #
+    #   Rooibos.run(
+    #     model: MyApp::Model.new(count: 0),
+    #     view: MyApp::View,
+    #     update: MyApp::Update,
+    #     command: Command.http("https://api.example.com/data")
+    #   )
+    #
+    # == Parameters
+    #
+    # [root_fragment] Module with Model, Init, Update, View constants. *Mutually exclusive with model/view/update.*
+    # [fps] Target frames per second for the application. Higher values feel more responsive, but may spike CPU usage.
+    # [model] Initial application state (immutable). *Required if fragment not provided.*
+    # [view] Callable receiving <tt>(model, tui)</tt>, returns a widget. *Required if fragment not provided.*
+    # [update] Callable receiving <tt>(message, model)</tt>, returns <tt>[new_model, command]</tt> or just <tt>new_model</tt>. *Required if fragment not provided.*
+    # [command] Optional callable to run at startup. Returns a message for update.
+    #
+    # == Raises
+    #
+    # [Rooibos::Error::Invariant] If both fragment and any of (model, view, update, command) are provided.
+    def self.run(root_fragment = nil, fps: 60, model: nil, view: nil, update: nil, command: nil)
+      @fragment = fragment_from_kwargs(root_fragment, model:, view:, update:, command:)
+      @view = @fragment::View
+      @update = @fragment::Update
+      @model, @command = init_callable.call
+      @timeout = 1 / fps
+
+      # commands do significant work, so they run off the main thread
+      validate_ractor_shareable!(@command, "command")
+      # models get passed to and from commands on other threads
+      validate_ractor_shareable!(@model, "model")
+      # views and updates run on the main thread, so they don't need to be shareable
+
+      start_runtime
+    end
+
+    # Normalizes Init callable return value to <tt>[model, command]</tt> tuple.
+    #
+    # Init callables return initial state and optional startup command. They can use
+    # DWIM (Do What I Mean) syntax: return just a model, just a command, or a full tuple.
+    #
+    # This method handles all formats. Use it when composing child fragment Inits.
+    #
+    # [result] The Init return value (model, command, or <tt>[model, command]</tt> tuple).
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Just model
+    #   model, cmd = Rooibos.normalize_init(Model.new(...))
+    #   # => [Model.new(...), nil]
+    #
+    #   # Just command
+    #   model, cmd = Rooibos.normalize_init(Command.http(...))
+    #   # => [nil, Command.http(...)]
+    #
+    #   # Tuple (already normalized)
+    #   model, cmd = Rooibos.normalize_init([Model.new(...), Command.http(...)])
+    #   # => [Model.new(...), Command.http(...)]
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.normalize_init(result)
+      normalize_update_return(result, nil)
+    end
+
+    # Sentinel value avoids accidentally quitting from application exceptions.
+    QUIT = Object.new.freeze
+
+    class << self
+      private def start_runtime
+        @message_queue = Concurrent::Promises::Channel.new
+        @pending_futures = [] #: Array[Concurrent::Promises::Future[void]]
+        @lifecycle = Command::Lifecycle.new
+
+        catch(QUIT) do
+          dispatch_command
+          RatatuiRuby.run do |tui|
+            @tui = tui
+            loop do
+              draw_view
+              handle_ratatui_event
+              handle_sync
+              send_pending_messages
+            end
+          end
+        end
+
+        # Shutdown: signal all, wait grace periods (cooperative cancellation)
+        @lifecycle.shutdown
+
+        # Process any final messages from completed commands
+        send_pending_messages(dispatch: false)
+
+        @model
+      end
+
+      private def draw_view
+        @tui.draw do |frame|
+          widget = @view.call(@model, @tui)
+          validate_view_return!(widget)
+          frame.render_widget(widget, frame.area)
+        end
+      end
+
+      # Enforces invariants
+      private def fragment_from_kwargs(root_fragment, model: nil, view: nil, update: nil, command: nil)
+        if root_fragment
+          fragment_invariant!("model") if model
+          fragment_invariant!("view") if view
+          fragment_invariant!("update") if update
+          fragment_invariant!("command") if command
+          root_fragment
+        else
+          fragment = Module.new
+          fragment.const_set(:Model, model)
+          fragment.const_set(:View, view)
+          fragment.const_set(:Update, update)
+          fragment.const_set(:Init, -> { [model, command] })
+          fragment
+        end
+      end
+
+      # Helps app developers understand invariants
+      private def fragment_invariant!(param)
+        raise Rooibos::Error::Invariant, "Cannot provide both fragment: and #{param}: parameters. Use fragment-first API (fragment:) OR explicit parameters (model:, view:, update:, command:), not both."
+      end
+
+      private def init_callable
+        if @fragment.const_defined?(:Init)
+          if @fragment::Init.respond_to?(:call)
+            if Proc === @fragment::Init or Method === @fragment::Init
+              @fragment::Init
+            else
+              @fragment::Init.method(:call)
+            end
+          else
+            raise Rooibos::Error::Invariant, "Fragment::Init must respond to :call"
+          end
+        else
+          if @fragment.const_defined?(:Model)
+            if @fragment::Model.respond_to?(:new)
+              -> { @fragment::Model.new }
+            else
+              raise Rooibos::Error::Invariant, "Fragment::Model must respond to :new; or pass Fragment::Init instead"
+            end
+          else
+            raise Rooibos::Error::Invariant, "Fragment must define a Model class or an Init callable"
+          end
+        end
+      end
+
+      private
+
+      # Validates the view returned a widget.
+      #
+      # Views return widget trees. Returning +nil+ is a bug—you forgot to
+      # return something. For an intentionally empty screen, use TUI#clear.
+      private def validate_view_return!(widget)
+        return unless widget.nil?
+
+        raise Rooibos::Error::Invariant,
+          "View returned nil. Return a widget, or use TUI#clear for an empty screen."
+      end
+
+      # Extracts [model, command] from Update return value.
+      private def normalize_update_return(result, previous_model)
+        # Case 0: Nil result - preserve previous model
+        return [previous_model, nil] if result.nil?
+
+        # Case 1: Already a [model, command] tuple
+        if result.is_a?(Array) && (result.size == 2)
+          model, command = result
+          # Verify the second element is a valid command
+          if command.nil? ||
+              (command.respond_to?(:rooibos_command?) && command.rooibos_command?)
+
+            return [model, command]
+          end
+
+          # Debug-mode heuristic: warn about suspicious command-like objects
+          if RatatuiRuby::Debug.enabled? &&
+              command.respond_to?(:call) &&
+              !command.respond_to?(:rooibos_command?) &&
+              !Ractor.shareable?(result)
+
+            warn "WARNING: Update returned [model, #{command.class}] but #{command.class} " \
+              "responds to #call without #rooibos_command?. Did you forget to include Command::Custom? " \
+              "The tuple will be treated as the model, not as [model, command]. " \
+              "To suppress this warning if the array is your model, use Ractor.make_shareable on it. " \
+              "(#{caller.first})"
+          end
+
+        end
+
+        # Case 2: Result is a Command - use previous model
+        if result.respond_to?(:rooibos_command?) && result.rooibos_command?
+          command = result #: Rooibos::Command::execution
+          return [previous_model, command]
+        end
+
+        # Case 3: Result is the new model
+        [result, nil]
+      end
+
+      # Validates an object is Ractor-shareable (deeply frozen).
+      #
+      # Models and messages must be shareable for future Ractor support.
+      # Mutable objects cause race conditions. Freeze your data.
+      #
+      # Only enforced in debug mode (and tests). Production skips this check
+      # for performance; mutable objects will still cause bugs, but silently.
+      private def validate_ractor_shareable!(object, name)
+        return unless RatatuiRuby::Debug.enabled?
+        return if Ractor.shareable?(object)
+
+        raise Rooibos::Error::Invariant,
+          "#{name.capitalize} is not Ractor-shareable. Use Ractor.make_shareable or Object#freeze."
+      end
+
+      private def handle_ratatui_event
+        message = @tui.poll_event(timeout: @timeout)
+        return if message.none?
+
+        @model, @command = normalize_update_return(@update.call(message, @model), @model)
+        validate_ractor_shareable!(@model, "model")
+        throw QUIT if Command::Exit === @command
+        dispatch_command
+      end
+
+      # This must come *after* handle_ratatui_event so Sync waits for commands
+      # dispatched by the preceding event. For example, in a test:
+      #
+      #   inject_key("a")
+      #   inject_sync
+      #
+      # We need <kbd>a</kbd> to call the Update and queue its message before
+      # processing the Sync.
+      private def handle_sync
+        if RatatuiRuby::SyntheticEvents.pending?
+          synthetic = RatatuiRuby::SyntheticEvents.pop
+          if synthetic&.sync?
+            # Wait for all pending futures to complete
+            @pending_futures.each(&:wait)
+            @pending_futures.clear
+
+            # Yield to ensure any final queue writes are visible
+            Thread.pass
+
+            # Process all pending message queue items
+            send_pending_messages
+          end
+        end
+      end
+
+      QUEUE_EMPTY = Object.new.freeze
+      private_constant :QUEUE_EMPTY
+
+      private def send_pending_messages(dispatch: true)
+        loop do
+          background_message = @message_queue.try_pop(QUEUE_EMPTY)
+          break if background_message == QUEUE_EMPTY
+
+          result = @update.call(background_message, @model)
+          @model, @command = normalize_update_return(result, @model)
+          return unless dispatch
+
+          validate_ractor_shareable!(@model, "model")
+          throw QUIT if Command::Exit === @command
+
+          dispatch_command
+        end
+      end
+
+      # Spawns a future and pushes results to the message queue.
+      # See Command.system for message formats.
+      private def dispatch_command
+        future = if @command.nil?
+          nil
+        elsif Command::Cancel === @command
+          @lifecycle.cancel(@command.handle)
+          nil
+        elsif @command.respond_to?(:rooibos_command?) && @command.rooibos_command?
+          entry = @lifecycle.run_async(@command, @message_queue)
+          entry.future
+        else
+          raise Rooibos::Error::Invariant,
+            "#{@command.inspect} is not a valid Rooibos command."
+        end
+        @pending_futures << future if future
+      end
+    end
+  end
+end

data/lib/rooibos/shortcuts.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "command"
+
+module Rooibos
+  # Convenient short aliases for Rooibos APIs.
+  #
+  # The library uses intention-revealing names that match Ruby built-ins:
+  # +Command+, +System+, +Exit+. These are great for readability.
+  #
+  # This module provides the short aliases common in TEA-style code:
+  #
+  # === Example
+  #
+  #   require "rooibos/shortcuts"
+  #   include Rooibos::Shortcuts
+  #
+  #   # Now use short names freely:
+  #   Cmd.exit               # → Command.exit
+  #   Cmd.sh("ls", :files)   # → Command.system("ls", :files)
+  #   Cmd.map(child) { ... } # → Command.map(child) { ... }
+  module Shortcuts
+    # Short alias for +Command+.
+    module Cmd
+      # Creates an exit command.
+      # Alias for +Command.exit+.
+      def self.exit
+        Command.exit
+      end
+
+      # Creates a shell execution command.
+      # Short alias for +Command.system+.
+      def self.sh(command, envelope)
+        Command.system(command, envelope)
+      end
+
+      # Creates a mapped command.
+      # Short alias for +Command.map+.
+      def self.map(inner_command, &mapper)
+        Command.map(inner_command, &mapper)
+      end
+    end
+  end
+end

data/lib/rooibos/test_helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby/test_helper"
+
+module Rooibos
+  # Test helpers for Rooibos command validation.
+  #
+  # This module extends RatatuiRuby::TestHelper with Rooibos-specific assertions
+  # for verifying custom commands implement the proper protocol.
+  module TestHelper
+    # Validates a command implements the Rooibos command protocol.
+    #
+    # Custom commands run in background threads. They dispatch work and send messages.
+    # Forgetting to include \<tt>Command::Custom\</tt> breaks dispatch. The runtime
+    # treats \<tt>[model, bad_command]\</tt> as a model, not a tuple. Tests fail with
+    # confusing Ractor shareability errors.
+    #
+    # This method checks the protocol. Call it in tests to catch mistakes early.
+    #
+    # [command] The command object to validate.
+    #
+    # === Example
+    #
+    #   def test_websocket_command_protocol
+    #     cmd = WebSocketCommand.new("wss://example.com")
+    #     validate_rooibos_command!(cmd)
+    #   end
+    def validate_rooibos_command!(command)
+      unless command.respond_to?(:rooibos_command?)
+        raise Rooibos::Error::Invariant,
+          "#{command.class} does not respond to #rooibos_command?. " \
+            "Include Command::Custom or implement the rooibos_command? predicate."
+      end
+
+      unless command.respond_to?(:call)
+        raise Rooibos::Error::Invariant,
+          "#{command.class} does not respond to #call. " \
+            "Implement call(out, token) to execute the command."
+      end
+
+      unless command.respond_to?(:rooibos_cancellation_grace_period)
+        raise Rooibos::Error::Invariant,
+          "#{command.class} does not respond to #rooibos_cancellation_grace_period. " \
+            "Include Command::Custom or implement this method."
+      end
+    end
+  end
+end
+
+# Attach Rooibos test helpers to RatatuiRuby::TestHelper
+RatatuiRuby::TestHelper.include(Rooibos::TestHelper)

data/lib/rooibos/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # The version of this gem.
+  # See https://semver.org/spec/v2.0.0.html
+  VERSION = "0.5.0"
+end

data/lib/rooibos.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "rooibos/version"
+require_relative "rooibos/error"
+require_relative "rooibos/message"
+require_relative "rooibos/command"
+require_relative "rooibos/runtime"
+require_relative "rooibos/router"
+
+# The Elm Architecture for Ruby.
+#
+# Building TUI applications means managing state, events, and rendering. Mixing them leads to
+# spaghetti code. Bugs hide in the tangles.
+#
+# This module implements The Elm Architecture (TEA). It separates your application into three
+# pure functions: model, view, and update. The runtime handles the rest.
+#
+# Use it to build applications with predictable, testable state management.
+module Rooibos
+  # Starts the MVU event loop.
+  #
+  # Convenience delegator to Runtime.run. See Runtime for full documentation.
+  def self.run(root_fragment = nil, **)
+    Runtime.run(root_fragment, **)
+  end
+
+  # Normalizes Init callable return value to <tt>[model, command]</tt> tuple.
+  #
+  # Init callables use DWIM syntax. They can return just a model, just a command,
+  # or a full <tt>[model, command]</tt> tuple.
+  #
+  # This method handles all formats. Use it when composing child fragment Inits
+  # in fractal architecture.
+  #
+  # [result] The Init return value.
+  #
+  # === Examples
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # Parent fragment composes children
+  #   Init = ->(theme:) do
+  #     stats_model, stats_cmd = Rooibos.normalize_init(StatsPanel::Init.(theme: theme))
+  #     network_model, network_cmd = Rooibos.normalize_init(NetworkPanel::Init.(theme: theme))
+  #
+  #     model = Model.new(stats: stats_model, network: network_model)
+  #     command = Command.batch(stats_cmd, network_cmd)
+  #     [model, command]
+  #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
+  def self.normalize_init(result)
+    Runtime.normalize_init(result)
+  end
+
+  # Wraps a command with a routing prefix.
+  #
+  # Parent fragments trigger child fragment commands. The results need routing back
+  # to the correct child fragment. Manually wrapping every command is tedious.
+  #
+  # This method prefixes command results automatically. Use it to route
+  # child fragment command results in Fractal Architecture.
+  #
+  # [command] The child fragment command to wrap.
+  # [prefix] Symbol prepended to results (e.g., <tt>:stats</tt>).
+  #
+  # === Example
+  #
+  #   # Verbose:
+  #   Command.map(child_fragment.fetch_command) { |r| [:stats, *r] }
+  #
+  #   # Concise:
+  #   Rooibos.route(child_fragment.fetch_command, :stats)
+  def self.route(command, prefix)
+    Command.map(command) { |result| [prefix, *result] }
+  end
+
+  # Delegates a prefixed message to a child fragment's UPDATE.
+  #
+  # Parent fragment UPDATE functions route messages to child fragments. Each route
+  # requires pattern matching, calling the child, and rewrapping any returned
+  # command. The boilerplate adds up fast.
+  #
+  # This method handles the dispatch. It checks the prefix, calls the child,
+  # and wraps any command. Returns <tt>nil</tt> if the prefix does not match.
+  #
+  # [message] Incoming message (e.g., <tt>[:stats, :system_info, {...}]</tt>).
+  # [prefix] Expected prefix symbol (e.g., <tt>:stats</tt>).
+  # [child_update] The child's UPDATE callable.
+  # [child_model] The child's current model.
+  #
+  # === Example
+  #
+  #   # Verbose:
+  #   case message
+  #   in [:stats, *rest]
+  #     new_child, cmd = StatsPanel::UPDATE.call(rest, model.stats)
+  #     mapped = cmd ? Command.map(cmd) { |r| [:stats, *r] } : nil
+  #     [new_child, mapped]
+  #   end
+  #
+  #   # Concise:
+  #   Rooibos.delegate(message, :stats, StatsPanel::UPDATE, model.stats)
+  def self.delegate(message, prefix, child_update, child_model)
+    return nil unless message.is_a?(Array) && message.first == prefix
+
+    rest = message[1..]
+    new_child, command = child_update.call(rest, child_model)
+    wrapped = command ? route(command, prefix) : nil
+    [new_child, wrapped]
+  end
+end

data/mise.toml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+[tools]
+ruby = "4.0.0"
+rust = "1.91.1"
+python = "3.12"
+pre-commit = "latest"