rooibos 0.5.0 → 0.6.0

data/lib/rooibos/command.rb

@@ -13,6 +13,7 @@ require_relative "command/wait"
 require_relative "command/batch"
 require_relative "command/all"
 require_relative "command/http"
+require_relative "command/open"
 
 module Rooibos
   # Commands represent side effects.
@@ -67,11 +68,11 @@ module Rooibos
 
     # Creates a fresh cancellation that never fires.
     #
-    # Some I/O operations cannot be cancelled mid-execution. Ruby's <tt>Net::HTTP</tt>
+    # Some I/O operations cannot be canceled 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.
+    # the origin, all commands using it become canceled.
     #
     # Use it for commands that wrap non-cancellable blocking I/O.
     #
@@ -94,6 +95,7 @@ module Rooibos
     # on <tt>Command::Cancel</tt> and signals the token.
     class Cancel < Data.define(:handle)
       include Custom
+      include Message::Predicates
 
       # Stub - Cancel is a sentinel handled by runtime before dispatch.
       def call(_out, _token)
@@ -121,55 +123,6 @@ module Rooibos
       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.
@@ -320,9 +273,9 @@ module Rooibos
     #   # Then handle it later:
     #   def update(message, model)
     #     case message
-    #     in [:got_files, {stdout:, status: 0}]
+    #     in { type: :system, envelope: :got_files, stdout:, status: 0 }
     #       [model.with(files: stdout.lines), nil]
-    #     in [:got_files, {stderr:, status:}]
+    #     in { type: :system, envelope: :got_files, stderr:, status: }
     #       [model.with(error: stderr), nil]
     #     end
     #   end
@@ -335,14 +288,14 @@ module Rooibos
     #   # Then handle incremental messages:
     #   def update(message, model)
     #     case message
-    #     in [:log, :stdout, line]
+    #     in { type: :system, envelope: :log, stream: :stdout, content: line }
     #       [model.with(lines: [*model.lines, line]), nil]
-    #     in [:log, :stderr, line]
+    #     in { type: :system, envelope: :log, stream: :stderr, content: line }
     #       [model.with(errors: [*model.errors, line]), nil]
-    #     in [:log, :complete, {status:}]
+    #     in { type: :system, envelope: :log, stream: :complete, status: }
     #       [model.with(loading: false, exit_status: status), nil]
-    #     in [:log, :error, {message:}]
-    #       [model.with(loading: false, error: message), nil]
+    #     in { type: :system, envelope: :log, stream: :error, content: msg }
+    #       [model.with(loading: false, error: msg), nil]
     #     end
     #   end
     def self.system(command, envelope, stream: false)
@@ -364,28 +317,35 @@ module Rooibos
     class Mapped < Data.define(:inner_command, :mapper)
       include Custom
 
+      DONE = Object.new.freeze
+      private_constant :DONE
+
       # Grace period delegates to inner command.
       def rooibos_cancellation_grace_period
         inner_command.respond_to?(:rooibos_cancellation_grace_period) ?
           inner_command.rooibos_cancellation_grace_period : 0.1
       end
 
-      # Executes the inner command, waits for result, and transforms it.
+      # Executes the inner command and transforms each message.
       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"
+        Concurrent::Promises.future do
+          if inner_command.respond_to?(:call)
+            inner_command.call(inner_outlet, token)
+          else
+            raise ArgumentError, "Inner command must respond to #call"
+          end
+          inner_channel.push(DONE)
         end
 
-        # Transform result and send
-        inner_message = inner_channel.pop
-        transformed = mapper.call(inner_message)
-        out.put(*transformed)
+        loop do
+          msg = inner_channel.pop
+          break if msg.equal?(DONE)
+          transformed = mapper.call(msg)
+          out.put(*transformed) if transformed
+        end
       end
     end
 
@@ -405,8 +365,14 @@ module Rooibos
     #
     #   # Parent wraps to route as [:sidebar, :got_files, {...}]
     #   parent_command = Command.map(child_command) { |child_result| [:sidebar, *child_result] }
-    def self.map(inner_command, &mapper)
-      Mapped.new(inner_command:, mapper:)
+    def self.map(inner_command, mapper = nil, &block)
+      if mapper && block
+        raise ArgumentError, "Pass either a mapper callable or a block, not both"
+      end
+      unless mapper || block
+        raise ArgumentError, "Pass a mapper callable or a block"
+      end
+      Mapped.new(inner_command:, mapper: mapper || block)
     end
 
     # Gives a callable unique identity for cancellation.
@@ -529,15 +495,32 @@ module Rooibos
       Http.new(*, **)
     end
 
-    # :nodoc:
-    class Wrapped < Data.define(:callable, :grace_period)
+    # Opens a file or URL with the system's default application.
+    # Cross-platform: uses +open+ on macOS, +xdg-open+ on Linux, +start+ on Windows.
+    #
+    # On success (exit 0), sends +Message::Open+.
+    # On failure (non-zero), sends +Message::Error+.
+    #
+    # === Example
+    #
+    #   case message
+    #   in { type: :open, envelope: path }
+    #     model.with(status: "Opened #{path}")
+    #   in { type: :error, envelope: path }
+    #     model.with(error: "Could not open #{path}")
+    #   end
+    #
+    def self.open(path, envelope = path)
+      Open.new(path:, envelope:)
+    end
+
+    class Wrapped < Data.define(:callable, :grace_period) # :nodoc:
       include Custom
       def rooibos_cancellation_grace_period
         grace_period || super
       end
 
-      # :nodoc:
-      def call(out, token)
+      def call(out, token) # :nodoc:
         callable.call(out, token)
       end
     end

data/lib/rooibos/message/batch.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Completion sentinel from Command.batch.
+    #
+    # Batch commands stream child messages live. When all children finish,
+    # this message signals completion. Use it to trigger follow-up actions
+    # or UI updates after parallel work completes.
+    #
+    # === Example
+    #
+    #   case msg
+    #   in Message::Batch
+    #     out.put(:all_done)
+    #   in [:progress, pct]
+    #     model.with(progress: pct)
+    #   end
+    #
+    Batch = Data.define(:command) do
+      include Predicates
+
+      # Returns <tt>true</tt> for batch completion messages.
+      def batch?
+        true
+      end
+
+      # Deconstructs for pattern matching.
+      def deconstruct_keys(_keys)
+        { type: :batch, command: }
+      end
+    end
+  end
+end

data/lib/rooibos/message/canceled.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Cancellation notification from a canceled command.
+    #
+    # Long-running commands respond to cancellation cooperatively. When the
+    # runtime signals cancellation, the command finishes current work and sends
+    # this message.
+    #
+    # Pattern match on Canceled in your update function to clean up state,
+    # stop animations, or acknowledge the cancellation.
+    #
+    # Use it to handle timer cancellations, aborted HTTP requests, or
+    # stopped background processes.
+    #
+    # === Example
+    #
+    #   Update = ->(message, model) {
+    #     case message
+    #     in { type: :canceled, command: }
+    #       # Timer was canceled, clear the notification
+    #       model.with(notification: nil)
+    #     in Message::Canceled
+    #       # Generic cancellation handling
+    #       model
+    #     end
+    #   }
+    Canceled = Data.define(:command) do
+      include Predicates
+
+      # Returns <tt>true</tt> for cancellation messages.
+      def canceled?
+        true
+      end
+      alias_method :cancelled?, :canceled?
+
+      # Deconstructs for pattern matching.
+      #
+      # Returns a hash with <tt>type</tt> and <tt>command</tt>.
+      def deconstruct_keys(_keys)
+        { type: :canceled, command: }
+      end
+    end
+  end
+end

data/lib/rooibos/message/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # 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 { type: :error, command:, exception: }
+    #       # Show error toast
+    #       model.with(error: exception.message)
+    #     in Message::Error
+    #       # Store for later inspection
+    #       model.with(last_error: message.exception)
+    #     end
+    #   }
+    Error = Data.define(:command, :exception) do
+      include Predicates
+
+      # Returns <tt>true</tt> for error messages.
+      def error?
+        true
+      end
+
+      # Deconstructs for pattern matching.
+      #
+      # Returns a hash with <tt>type</tt>, <tt>command</tt>, and <tt>exception</tt>.
+      def deconstruct_keys(_keys)
+        { type: :error, command:, exception: }
+      end
+    end
+  end
+end

data/lib/rooibos/message/open.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Signals that a file or URL was successfully opened.
+    #
+    # This message arrives after +Command.open+ completes with exit status 0.
+    # Non-zero exits produce +Message::Error+ instead.
+    #
+    # === Pattern Matching
+    #
+    #   case message
+    #   in { type: :open, envelope: path }
+    #     model.with(status: "Opened #{path}")
+    #   end
+    #
+    class Open < Data.define(:envelope)
+      include Predicates
+
+      def deconstruct_keys(_keys)
+        { type: :open, envelope: }
+      end
+    end
+  end
+end

data/lib/rooibos/message.rb

@@ -8,21 +8,97 @@
 module Rooibos
   # Messages sent from commands to update functions.
   #
-  # All built-in response types live here. Each includes the +Predicates+
+  # All built-in response types live here. Each includes the <tt>Predicates</tt>
   # mixin for safe predicate calls.
   module Message
+    # Matches built-in framework message types for case/when dispatch.
+    #
+    # Returns <tt>true</tt> only for classes under <tt>Rooibos::Message::</tt>.
+    # Rejects key events and user-defined message classes.
+    #
+    # === Example
+    #
+    #   case message
+    #   when Rooibos::Message
+    #     handle_command_response(message)
+    #   when RatatuiRuby::Event::Key
+    #     handle_key(message)
+    #   end
+    def self.===(other)
+      other.class.name&.start_with?("Rooibos::Message::")
+    end
+
     # Fallback predicate mixin.
     #
-    # Returns +false+ for any unknown predicate method (ending in +?+).
-    # Include in custom message types for safe predicate calls.
+    # Update functions receive many message types. Checking unknown predicates
+    # crashes with NoMethodError. Verifying every predicate clutters the code.
+    #
+    # This mixin returns <tt>false</tt> for unknown predicates. It also adds
+    # symbol comparison via <tt>to_sym</tt> and <tt>==</tt>.
+    #
+    # Include in custom message types for safe predicate calls and symbol matching.
     module Predicates
-      # Returns +false+ for unknown predicate methods.
+      # Converts the message to a Symbol.
+      #
+      # Returns the <tt>:type</tt> value from <tt>deconstruct_keys</tt> prefixed
+      # with <tt>message_</tt>. The prefix avoids collision with RatatuiRuby
+      # event symbols like <tt>:resize</tt> or <tt>:mouse</tt>.
+      #
+      # === Example
+      #
+      #   timer = Message::Timer.new(envelope: :tick, elapsed: 0.016)
+      #   timer.to_sym # => :message_timer
+      def to_sym
+        :"message_#{deconstruct_keys(nil)[:type]}"
+      end
+
+      # Compares the message with another object.
+      #
+      # Symbols compare against <tt>to_sym</tt>. Other objects use default equality.
+      #
+      # === Example
+      #
+      #   if message == :message_timer
+      #     handle_tick(message)
+      #   end
+      def ==(other)
+        case other
+        when Symbol then to_sym == other
+        else super
+        end
+      end
+
+      # Returns <tt>false</tt> for unknown predicate methods.
       def method_missing(name, *args, **kwargs, &block)
         return false if name.to_s.end_with?("?") && args.empty? && kwargs.empty?
 
         super
       end
 
+      # Fallback pattern matching for classes without explicit deconstruct_keys.
+      #
+      # Derives <tt>:type</tt> from the class name in snake_case. Anonymous
+      # classes default to <tt>:custom</tt>.
+      #
+      # === Example
+      #
+      #   class MyCustomMessage
+      #     include Rooibos::Message::Predicates
+      #   end
+      #
+      #   msg = MyCustomMessage.new
+      #   msg.deconstruct_keys(nil) # => { type: :my_custom_message }
+      #   msg.to_sym                # => :message_my_custom_message
+      def deconstruct_keys(_keys)
+        class_name = self.class.name&.split("::")&.last
+        type_name = if class_name
+          class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+        else
+          :custom
+        end
+        { type: type_name }
+      end
+
       # Responds to all predicate methods.
       def respond_to_missing?(name, *)
         name.to_s.end_with?("?")
@@ -32,7 +108,11 @@ module Rooibos
 end
 
 require_relative "message/timer"
+require_relative "message/open"
 require_relative "message/http_response"
 require_relative "message/system/batch"
 require_relative "message/system/stream"
 require_relative "message/all"
+require_relative "message/batch"
+require_relative "message/error"
+require_relative "message/canceled"

data/lib/rooibos/router.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 #--
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
@@ -13,10 +13,10 @@ module Rooibos
   # Writing this routing logic by hand is tedious and error-prone.
   #
   # Include this module to declare routes and keymaps. Call +from_router+ to
-  # generate an UPDATE lambda that handles routing automatically.
+  # generate an Update lambda that handles routing automatically.
   #
-  # A *fragment* is a module containing <tt>Model</tt>, <tt>INITIAL</tt>,
-  # <tt>UPDATE</tt>, and <tt>VIEW</tt> constants. Fragments compose: parent fragments
+  # A *fragment* is a module containing <tt>Model</tt>, <tt>Init</tt>,
+  # <tt>Update</tt>, and <tt>View</tt> constants. Fragments compose: parent fragments
   # delegate to child fragments.
   #
   # === Example
@@ -33,9 +33,9 @@ module Rooibos
   #     end
   #
   #     Model = Data.define(:stats, :network)
-  #     INITIAL = Model.new(stats: StatsPanel::INITIAL, network: NetworkPanel::INITIAL)
-  #     VIEW = ->(model, tui) { ... }
-  #     UPDATE = from_router
+  #     Init = -> { Model.new(stats: StatsPanel::Init.(), network: NetworkPanel::Init.()) }
+  #     View = ->(model, tui) { ... }
+  #     Update = from_router
   #   end
   module Router
     # Configuration for key handlers.
@@ -59,8 +59,7 @@ module Rooibos
       end
     end
 
-    # :nodoc:
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.extend(ClassMethods)
     end
 
@@ -254,8 +253,7 @@ module Rooibos
       # Returns the registered handlers hash.
       attr_reader :handlers
 
-      # :nodoc:
-      def initialize
+      def initialize # :nodoc:
         @handlers = {}
         @guard_stack = []
       end
@@ -369,8 +367,7 @@ module Rooibos
       # Returns the registered click handler.
       attr_reader :click_handler
 
-      # :nodoc:
-      def initialize
+      def initialize # :nodoc:
         @scroll_handlers = {}
         @click_handler = nil
       end