rooibos 0.5.0 → 0.6.1

data/lib/rooibos/command/open.rb

@@ -0,0 +1,93 @@
+# 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:
+    # <tt>open</tt> on macOS, <tt>xdg-open</tt> on Linux, <tt>start</tt> on Windows.
+    #
+    # On success (exit 0), sends <tt>Message::Open</tt>.
+    # On failure (non-zero), sends <tt>Message::Error</tt>.
+    #
+    # Prefer the <tt>Command.open</tt> factory method for convenience.
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   Command.open(model.selected_file)
+    #   Command.open("https://rooibos.run")
+    #
+    #   # Using the class directly
+    #   Open.new(path: model.selected_file, envelope: model.selected_file)
+    #
+    #   # Pattern-match on the response
+    #   def update(msg, model)
+    #     case msg
+    #     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,11 +15,14 @@ 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.
     #
+    # Prefer the <tt>Command.wait</tt> or <tt>Command.tick</tt> factory
+    # methods for convenience. Both are aliases for the same behavior.
+    #
     # === Example: Notification dismissal
     #
     #   def update(msg, model)
@@ -28,7 +31,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
@@ -44,7 +47,7 @@ module Rooibos
     #       [model.with(frame:), Command.tick(0.1, :animate)]
     #     end
     #   end
-    Wait = Data.define(:seconds, :envelope) do
+    class Wait < Data.define(:seconds, :envelope)
       include Custom
 
       # Cooperative cancellation needs no grace period.
@@ -57,7 +60,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 +71,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:)

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.
@@ -35,9 +36,21 @@ module Rooibos
   #   # No side effect
   #   [model, nil]
   module Command
-    # Sentinel value for application termination.
+    # Terminates the application.
     #
-    # The runtime detects this before dispatching. It breaks the loop immediately.
+    # Users press a key or click a button to quit. The update function returns
+    # a command, and the runtime executes it. Termination is special: the
+    # runtime detects this sentinel before dispatching and breaks the loop.
+    #
+    # Prefer the <tt>Command.exit</tt> factory method for convenience.
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   [model, Command.exit]
+    #
+    #   # Using the class directly
+    #   [model, Exit.new]
     class Exit < Data.define
       include Custom
 
@@ -67,11 +80,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.
     #
@@ -84,16 +97,28 @@ module Rooibos
       cancellation
     end
 
-    # Sentinel value for command cancellation.
+    # Cancels a running command.
+    #
+    # 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.
     #
-    # 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.
+    # Prefer the <tt>Command.cancel</tt> factory method for convenience.
     #
-    # This type carries the handle (command object) to cancel. The runtime pattern-matches
-    # on <tt>Command::Cancel</tt> and signals the token.
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   [model, Command.cancel(model.active_fetch)]
+    #
+    #   # Using the class directly
+    #   [model, Cancel.new(handle: model.active_fetch)]
     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 +146,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.
@@ -180,20 +156,29 @@ module Rooibos
     #
     # Use it to run builds, lint files, execute scripts, or invoke any CLI tool.
     #
+    # Prefer the <tt>Command.system</tt> factory method for convenience.
+    #
     # === Batch Mode (default)
     #
     # A single message arrives when the command finishes:
-    # <tt>[tag, {stdout:, stderr:, status:}]</tt>
+    # <tt>Message::System::Batch</tt> with <tt>stdout</tt>, <tt>stderr</tt>, <tt>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
+    # <tt>Message::System::Stream</tt> messages arrive incrementally:
+    # <tt>stream: :stdout</tt>:: for each stdout chunk
+    # <tt>stream: :stderr</tt>:: for each stderr chunk
+    # <tt>stream: :complete</tt>:: when the command finishes
+    # <tt>stream: :error</tt>:: if the command cannot start
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   Command.system("ls -la", :got_files)
+    #   Command.system("tail -f log.txt", :log, stream: true)
     #
-    # The <tt>status</tt> is the integer exit code (0 = success).
+    #   # Using the class directly
+    #   System.new(command: "ls -la", envelope: :got_files, stream: false)
     class System < Data.define(:command, :envelope, :stream)
       include Custom
 
@@ -320,9 +305,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 +320,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)
@@ -361,31 +346,48 @@ module Rooibos
     # adds its routing prefix. Clean separation. No coupling.
     #
     # Use it to compose child fragments that return their own commands.
+    #
+    # Prefer the <tt>Command.map</tt> factory method for convenience.
+    #
+    # === Example
+    #
+    #   # Using the factory method (recommended)
+    #   Command.map(child_command) { |msg| [:sidebar, msg] }
+    #
+    #   # Using the class directly
+    #   Mapped.new(inner_command: child_command, mapper: ->(msg) { [:sidebar, msg] })
     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 +407,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 +537,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