rooibos 0.5.0 → 0.6.0

data/lib/rooibos/command/custom.rb

@@ -71,7 +71,7 @@ module Rooibos
       # 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.
+      # *This is NOT a lifetime limit.* Your command runs indefinitely until canceled.
       # A WebSocket open for 15 minutes is fine. This timeout only applies to the
       # cleanup phase after cancellation is requested.
       #
@@ -99,6 +99,89 @@ module Rooibos
       def rooibos_cancellation_grace_period
         0.1
       end
+
+      # Infrastructure methods to exclude from introspection.
+      # Computed once from bare prototypes.
+      INFRASTRUCTURE_METHODS = begin
+        bare_data = Data.define(:_)
+        bare_struct = Struct.new(:_)
+
+        methods = Object.public_instance_methods +
+          bare_data.public_instance_methods +
+          bare_struct.public_instance_methods
+
+        # PP methods can error when called on objects without pretty_print override
+        methods += %i[
+          pretty_print
+          pretty_print_cycle
+          pretty_print_instance_variables
+          pretty_print_inspect
+]
+
+        methods.uniq.freeze
+      end
+      private_constant :INFRASTRUCTURE_METHODS
+
+      # Deconstructs for hash-based pattern matching.
+      #
+      # Introspects public query methods (CQS: zero-arity, no side effects) and
+      # returns a hash suitable for +case+/+in+ matching. Excludes infrastructure
+      # methods from Object, Data, and Struct.
+      #
+      # Always includes +:type+ as a snake_case symbol of the class name.
+      # Anonymous classes default to +:custom+.
+      #
+      # Data.define members are automatically included since they generate
+      # public accessor methods.
+      #
+      # This is a naive but practical default. Override for:
+      # - Hot paths (introspects methods on every call)
+      # - Ghost methods via +method_missing+/+respond_to_missing?+
+      # - Methods with optional arguments (only zero-arity detected)
+      #
+      # @param keys [Array<Symbol>, nil] Limit output to specific keys for performance.
+      #   Pass +nil+ to include all keys.
+      # @return [Hash{Symbol => Object}] Deconstructed hash with +:type+ discriminator.
+      #
+      # @example Pattern matching with Data.define command
+      #   case msg
+      #   in { type: :http_response, envelope: :users, status: 200 }
+      #     # handle success
+      #   end
+      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
+
+        result = { type: type_name }
+
+        # Include Data.define/Struct members
+        if self.class.respond_to?(:members)
+          klass = self.class #: Class & _HasMembers
+          klass.members.each do |member|
+            next if keys && !keys.include?(member)
+            result[member] = public_send(member)
+          end
+        end
+
+        # Include public zero-arity query methods (excluding infrastructure)
+        # Use Kernel#public_method to avoid collision with Data.define :method member
+        get_method = Kernel.instance_method(:public_method)
+        (public_methods - INFRASTRUCTURE_METHODS).each do |method_name|
+          next if method_name.to_s.end_with?("=", "!")
+          next unless get_method.bind_call(self, method_name).arity.zero?
+          next if keys && !keys.include?(method_name)
+          result[method_name] = public_send(method_name)
+        end
+
+        result
+      end
     end
   end
 end

data/lib/rooibos/command/http.rb

@@ -18,76 +18,80 @@ module Rooibos
     Http = Data.define(:method, :url, :envelope, :headers, :body, :timeout, :parser) do
       include Custom
 
-      def self.new(*args, method: nil, url: nil, envelope: nil, headers: nil, body: nil, timeout: nil, parser: nil,
-        get: nil, post: nil, put: nil, patch: nil, delete: nil
-      )
-        # Auto-splat single hash argument
-        return new(**args.first) if args.size == 1 && args.first.is_a?(Hash)
-
-        # Auto-spread single array argument
-        return new(*args.first) if args.size == 1 && args.first.is_a?(Array)
-
-        # DWIM: parse positional args and keyword method shortcuts
-        method_keywords = { get:, post:, put:, patch:, delete: }.compact
-        method, url, envelope, body = parse_dwim_args(args, method, url, envelope, body, method_keywords)
+      class << self
+        undef_method :new
+
+        def new(*args, method: nil, url: nil, envelope: nil, headers: nil, body: nil, timeout: nil, parser: nil,
+          get: nil, post: nil, put: nil, patch: nil, delete: nil
+        )
+          # Auto-splat single hash argument
+          return new(**args.first) if args.size == 1 && args.first.is_a?(Hash)
+
+          # Auto-spread single array argument
+          return new(*args.first) if args.size == 1 && args.first.is_a?(Array)
+
+          # DWIM: parse positional args and keyword method shortcuts
+          method_keywords = { get:, post:, put:, patch:, delete: }.compact
+          method, url, envelope, body = parse_dwim_args(args, method, url, envelope, body, method_keywords)
+
+          # Ractor validation
+          if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(url)
+            raise Rooibos::Error::Invariant,
+              "URL is not Ractor-shareable: #{url.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
 
-        # Ractor validation
-        if RatatuiRuby::Debug.enabled? && !Ractor.shareable?(url)
-          raise Rooibos::Error::Invariant,
-            "URL is not Ractor-shareable: #{url.inspect}\n" \
-              "Use a frozen string or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && headers && !Ractor.shareable?(headers)
+            raise Rooibos::Error::Invariant,
+              "Headers are not Ractor-shareable: #{headers.inspect}\n" \
+                "Use Ractor.make_shareable or freeze the hash and its contents."
+          end
 
-        if RatatuiRuby::Debug.enabled? && headers && !Ractor.shareable?(headers)
-          raise Rooibos::Error::Invariant,
-            "Headers are not Ractor-shareable: #{headers.inspect}\n" \
-              "Use Ractor.make_shareable or freeze the hash and its contents."
-        end
+          if RatatuiRuby::Debug.enabled? && body && !Ractor.shareable?(body)
+            raise Rooibos::Error::Invariant,
+              "Body is not Ractor-shareable: #{body.inspect}\n" \
+                "Use a frozen string or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && body && !Ractor.shareable?(body)
-          raise Rooibos::Error::Invariant,
-            "Body is not Ractor-shareable: #{body.inspect}\n" \
-              "Use a frozen string or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && envelope && !Ractor.shareable?(envelope)
+            raise Rooibos::Error::Invariant,
+              "Envelope is not Ractor-shareable: #{envelope.inspect}\n" \
+                "Use a frozen string, symbol, or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && envelope && !Ractor.shareable?(envelope)
-          raise Rooibos::Error::Invariant,
-            "Envelope is not Ractor-shareable: #{envelope.inspect}\n" \
-              "Use a frozen string, symbol, or Ractor.make_shareable."
-        end
+          if RatatuiRuby::Debug.enabled? && timeout && !Ractor.shareable?(timeout)
+            raise Rooibos::Error::Invariant,
+              "Timeout is not Ractor-shareable: #{timeout.inspect}\n" \
+                "Use a number or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && timeout && !Ractor.shareable?(timeout)
-          raise Rooibos::Error::Invariant,
-            "Timeout is not Ractor-shareable: #{timeout.inspect}\n" \
-              "Use a number or Ractor.make_shareable."
-        end
+          # Parser validation
+          if parser && !parser.respond_to?(:call)
+            raise ArgumentError, "parser: must respond to :call"
+          end
 
-        # Parser validation
-        if parser && !parser.respond_to?(:call)
-          raise ArgumentError, "parser: must respond to :call"
-        end
+          if RatatuiRuby::Debug.enabled? && parser && !Ractor.shareable?(parser)
+            raise Rooibos::Error::Invariant,
+              "Parser is not Ractor-shareable: #{parser.inspect}\n" \
+                "Use a frozen Method object or Ractor.make_shareable."
+          end
 
-        if RatatuiRuby::Debug.enabled? && parser && !Ractor.shareable?(parser)
-          raise Rooibos::Error::Invariant,
-            "Parser is not Ractor-shareable: #{parser.inspect}\n" \
-              "Use a frozen Method object or Ractor.make_shareable."
-        end
+          # Method validation
+          unless %i[get post put patch delete].include?(method)
+            raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+          end
 
-        # Method validation
-        unless %i[get post put patch delete].include?(method)
-          raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+          instance = allocate
+          instance.__send__(:initialize, method:, url:, envelope:, headers:, body:, timeout: timeout || 10, parser:)
+          instance
         end
-
-        instance = allocate
-        instance.__send__(:initialize, method:, url:, envelope:, headers:, body:, timeout: timeout || 10, parser:)
-        instance
       end
 
       # Net::HTTP is blocking; no cooperative cancellation possible.
       # Grace period = 0 means runtime can force-kill immediately.
       def rooibos_cancellation_grace_period = 0
 
-      def self.parse_dwim_args(args, method_kw, url_kw, envelope_kw, body_kw, method_keywords)
+      def self.parse_dwim_args(args, method_kw, url_kw, envelope_kw, body_kw, method_keywords) # :nodoc:
         # Handle keyword method shortcuts: get: 'url'
         if method_keywords.any?
           method_key, url = method_keywords.first

data/lib/rooibos/command/lifecycle.rb

@@ -19,8 +19,7 @@ module Rooibos
     #
     # The framework creates one instance at startup. All outlets share it.
     class Lifecycle
-      # :nodoc: Internal representation of a tracked async command.
-      Entry = Data.define(:future, :origin)
+      Entry = Data.define(:future, :origin) # :nodoc: Internal representation of a tracked async command.
 
       # Creates a lifecycle manager.
       #
@@ -40,7 +39,7 @@ module Rooibos
       # [token]   Parent's cancellation token.
       # [timeout] Max wait seconds for the result.
       #
-      # Returns the child's message, or <tt>nil</tt> if cancelled or timed out.
+      # Returns the child's message, or <tt>nil</tt> if canceled or timed out.
       # Raises if the child raised.
       def run_sync(command, token, timeout:)
         return nil if token.canceled?
@@ -76,7 +75,7 @@ module Rooibos
       #
       # Spawns a future that executes the command. Tracks the command in the
       # active map for cancellation support. Errors are pushed to the channel
-      # as <tt>Command::Error</tt> messages.
+      # as <tt>Message::Error</tt> messages.
       #
       # [command] Callable with <tt>call(out, token)</tt>.
       # [channel] Channel to push results and errors to.
@@ -89,7 +88,7 @@ module Rooibos
         future = Concurrent::Promises.future do
           command.call(outlet, cancellation)
         rescue => e
-          channel.push Command::Error.new(command:, exception: e)
+          channel.push Message::Error.new(command:, exception: e)
         end
 
         entry = Entry.new(future:, origin:)
@@ -114,6 +113,7 @@ module Rooibos
         entry.future.wait(grace.finite? ? grace : nil)
 
         @active.delete(command)
+        entry # Return so caller can remove from pending_futures
       end
 
       # Cancels all active commands and waits for them to complete.

data/lib/rooibos/command/open.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "shellwords"
+
+module Rooibos
+  module Command
+    # Opens a file or URL with the system's default application.
+    #
+    # Terminal applications often need to hand off to external programs.
+    # Opening a PDF, launching a URL, or viewing an image requires
+    # platform-specific commands.
+    #
+    # This command detects the platform and runs the appropriate opener:
+    # +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
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in :view_clicked
+    #       [model, Command.open(model.selected_file)]
+    #     in { type: :open, envelope: path }
+    #       model.with(status: "Opened #{path}")
+    #     in { type: :error, envelope: path }
+    #       model.with(error: "Could not open #{path}")
+    #     end
+    #   end
+    #
+    class Open < Data.define(:path, :envelope)
+      include Custom
+
+      # System commands are generally fast; no grace period needed.
+      def rooibos_cancellation_grace_period = 0
+
+      # Executes the open command and sends the result message.
+      def call(out, token)
+        return if token.canceled?
+
+        require "open3"
+        cmd = self.class.__send__(:system_command, path)
+        _stdout, stderr, status = Open3.capture3(cmd)
+
+        message = if status.exitstatus == 0
+          Message::Open.new(envelope:)
+        else
+          error_msg = stderr.empty? ? "Failed to open: #{path}" : stderr.strip
+          Message::Error.new(
+            command: envelope,
+            exception: RuntimeError.new(error_msg.freeze).freeze
+          )
+        end
+
+        out.put(Ractor.make_shareable(message))
+      rescue => e
+        out.put(Ractor.make_shareable(Message::Error.new(
+          command: envelope,
+          exception: RuntimeError.new(e.message.freeze).freeze
+        )))
+      end
+
+      # Builds the platform-specific open command.
+      def self.system_command(path, platform = RUBY_PLATFORM) # :nodoc:
+        escaped = path.shellescape
+        case platform
+        when /darwin/
+          "open #{escaped}"
+        when /linux/
+          "xdg-open #{escaped}"
+        when /mingw|mswin|cygwin/
+          "start #{path}"
+        else
+          "xdg-open #{escaped}"
+        end
+      end
+      private_class_method :system_command
+    end
+  end
+end

data/lib/rooibos/command/outlet.rb

@@ -85,10 +85,15 @@ module Rooibos
       def initialize(message_queue, lifecycle:)
         @message_queue = message_queue
         @live = lifecycle
+        @pending_async = [] #: Array[AsyncHandle]
       end
 
-      # :nodoc: Internal infrastructure for nested command lifecycle sharing.
-      attr_reader :live
+      # Internal handle for async streaming commands.
+      AsyncHandle = Data.define(:future) # :nodoc:
+      private_constant :AsyncHandle
+
+      # Internal infrastructure for nested command lifecycle sharing.
+      attr_reader :live # :nodoc:
 
       # Sends a message to the runtime.
       #
@@ -131,7 +136,7 @@ module Rooibos
       # [token]   The parent's cancellation token, passed through to the child.
       # [timeout] Max seconds to wait for the child's result (default: 30.0).
       #
-      # Returns the message from the child, or +nil+ if cancelled/timed out.
+      # Returns the message from the child, or +nil+ if canceled/timed out.
       # Raises if the child command raised an exception.
       #
       # === Example
@@ -152,6 +157,103 @@ module Rooibos
       def source(command, token, timeout: 30.0)
         @live.run_sync(command, token, timeout:)
       end
+
+      # Spawns an async streaming command.
+      #
+      # Multiple data sources often need to stream in parallel. Dashboards,
+      # real-time feeds, and multi-provider aggregations all face this pattern.
+      # Waiting for one source before starting the next creates latency.
+      #
+      # This method spawns a child command that runs asynchronously. Messages
+      # from the child stream directly to your update function as they arrive.
+      # The child gets a full Outlet, so it can nest +source+ or +standing+ calls.
+      #
+      # Use +wait+ to block until the child completes, or fire-and-forget for
+      # long-running streams.
+      #
+      # [command] A callable with <tt>call(out, token)</tt>.
+      # [token]   The parent's cancellation token.
+      #
+      # Returns a handle for use with +wait+.
+      #
+      # === Example
+      #
+      # A dashboard that opens two SSE streams for live updates. Each stream
+      # emits chunks as they arrive — no waiting for the other.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   def call(out, token)
+      #     # Authenticate first (sync)
+      #     auth = out.source(Authenticate.new, token)
+      #     return if auth.nil?
+      #
+      #     # Open two SSE streams in parallel — chunks arrive live
+      #     # Streams remain outstanding until token is canceled
+      #     out.standing(StreamNotifications.new(auth), token)
+      #     out.standing(StreamPrices.new(auth), token)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def standing(command, token)
+        child_outlet = Outlet.new(@message_queue, lifecycle: @live)
+        future = Concurrent::Promises.future do
+          command.call(child_outlet, token)
+        rescue => e
+          @message_queue.push Message::Error.new(command:, exception: e)
+        end
+        handle = AsyncHandle.new(future:)
+        @pending_async << handle
+        handle
+      end
+
+      # Blocks until async commands complete.
+      #
+      # After spawning children with +standing+, the parent command normally
+      # returns immediately. Use +wait+ to block until children finish, then
+      # emit a completion signal.
+      #
+      # This is how custom commands achieve the same end-of-streams dispatch
+      # that +Command.batch+ gets automatically with +Message::Batch+.
+      #
+      # [handles] Zero or more handles from +standing+. If empty, waits for all.
+      #
+      # === Example
+      #
+      # A custom command that streams from two sources and signals when done.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   def call(out, token)
+      #     h1 = out.standing(StreamPrices.new, token)
+      #     h2 = out.standing(StreamNews.new, token)
+      #     out.wait(h1, h2)
+      #     out.put(:streams_closed)  # Your custom completion signal
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def wait(*handles, token: nil)
+        handles = @pending_async || [] if handles.empty?
+        return if handles.empty?
+
+        futures = handles.map(&:future)
+        all_done = Concurrent::Promises.zip_futures(*futures)
+
+        if token
+          # Race completion against cancellation
+          Concurrent::Promises.any_event(all_done, token.origin).wait
+        else
+          all_done.wait
+        end
+      end
     end
   end
 end

data/lib/rooibos/command/wait.rb

@@ -15,8 +15,8 @@ module Rooibos
     # 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.
+    # cancellation cooperatively. When canceled, it sends
+    # <tt>Message::Canceled</tt> so you know the timer stopped.
     #
     # Use it for delayed actions, debounced inputs, or animation loops.
     #
@@ -28,7 +28,7 @@ module Rooibos
     #       [model.with(notification: "Saved!"), Command.wait(3.0, :dismiss)]
     #     in :dismiss
     #       [model.with(notification: nil), nil]
-    #     in Command::Cancel
+    #     in Message::Canceled
     #       [model.with(notification: nil), nil]  # User navigated away
     #     end
     #   end
@@ -57,7 +57,7 @@ module Rooibos
       # Executes the timer.
       #
       # Waits for <tt>seconds</tt>, then sends <tt>TimerResponse</tt>.
-      # If cancelled, sends <tt>Command.cancel(self)</tt> instead.
+      # If canceled, sends <tt>Message::Canceled</tt> instead.
       #
       # [out] Outlet for sending messages.
       # [token] Cancellation token from the runtime.
@@ -68,7 +68,7 @@ module Rooibos
         combined.origin.wait
 
         if token.canceled?
-          out.put(Command.cancel(self))
+          out.put(Message::Canceled.new(command: self))
         else
           elapsed = Time.now - start_time
           response = Message::Timer.new(envelope:, elapsed:)