rooibos 0.5.0 → 0.6.0

data/sig/rooibos/command.rbs

@@ -135,12 +135,25 @@ module Rooibos
 
   # Mixin for user-defined custom commands.
   module Custom
+    # Interface for classes with a members method (Data.define, Struct).
+    interface _HasMembers
+      def members: () -> Array[Symbol]
+    end
+
+    # Methods excluded from deconstruct_keys introspection.
+    # Computed from Object, Data.define, Struct, and PP prototypes.
+    INFRASTRUCTURE_METHODS: Array[Symbol]
+
     # Brand predicate for command identification.
     def rooibos_command?: () -> true
 
     # Cleanup time after cancellation is requested. In seconds.
     # Default: 0.1 seconds (100 milliseconds).
     def rooibos_cancellation_grace_period: () -> Float
+
+    # Deconstructs for hash-based pattern matching.
+    # Introspects public query methods and returns a hash with :type discriminator.
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
 
   # Minimal interface for callables accepted by Lifecycle.run_sync.
@@ -179,8 +192,17 @@ module Rooibos
 
   # Messaging gateway for custom commands.
   class Outlet
+    # Internal handle for async streaming commands.
+    class AsyncHandle < Data
+      attr_reader future: Concurrent::Promises::Future[void]
+
+      def self.new: (future: Concurrent::Promises::Future[void]) -> instance
+    end
+
     @channel: Concurrent::Promises::Channel
     @live: Lifecycle
+    @pending_async: Array[AsyncHandle]
+
 
     def initialize: (Concurrent::Promises::Channel channel, lifecycle: Lifecycle) -> void
 
@@ -192,6 +214,14 @@ module Rooibos
 
     # Runs a child command synchronously, returning its result.
     def source: (_Callable command, Concurrent::Cancellation token, ?timeout: Float) -> Object?
+
+    # Spawns an async streaming command.
+    # Returns a handle for use with wait.
+    def standing: (_Callable command, Concurrent::Cancellation token) -> AsyncHandle
+
+    # Blocks until async commands complete.
+    # If no handles given, waits for all pending async commands.
+    def wait: (*AsyncHandle handles, ?token: Concurrent::Cancellation?) -> void
   end
 
   # A fire-and-forget parallel command.
@@ -261,5 +291,23 @@ module Rooibos
   # DWIM: accepts positional args, method keywords (get:, post:, etc.), or explicit keywords.
   # See Http class and documentation for all supported patterns.
   def self.http: (*(Symbol | String | nil), **(Symbol | String | Integer | Float | Hash[String, String] | ^(String, Hash[String, String]?, Integer?) -> Object | nil)) -> Http
+
+  # Opens a file or URL with the system's default application.
+  class Open < Data
+    include Custom
+
+    attr_reader path: String
+    attr_reader envelope: String
+
+    def self.new: (path: String, envelope: String) -> instance
+
+    # Builds the platform-specific open command.
+    def self.system_command: (String path, ?String platform) -> String
+
+    def call: (Outlet out, Concurrent::Cancellation token) -> void
+  end
+
+  # Creates an open command for launching files with system opener.
+  def self.open: (String path, ?String envelope) -> Open
 end
 end

data/sig/rooibos/message.rbs

@@ -8,9 +8,18 @@ module Rooibos
   module Message
   # Fallback predicate mixin.
   module Predicates
+    # Converts the message to a Symbol representation.
+    def to_sym: () -> Symbol
+
+    # Compares the message with another object.
+    def ==: (top other) -> bool
+
     # Returns false for unknown predicate methods.
     def method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
 
+    # Default deconstruct_keys for classes that don't define their own.
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+
     # Responds to all predicate methods.
     def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
   end
@@ -100,6 +109,19 @@ module Rooibos
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
 
+  # Completion sentinel from Command.batch.
+  # Signals when all children of a batch command have finished.
+  class Batch < Data
+    include Predicates
+
+    attr_reader command: Command::Batch
+
+    def self.new: (command: Command::Batch) -> instance
+
+    def batch?: () -> bool
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+  end
+
   # Response from Command.all aggregating parallel execution.
   class All
     include Predicates
@@ -117,5 +139,43 @@ module Rooibos
     def all?: () -> bool
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
+
+  # Error message from a failed command.
+  class Error < Data
+    include Predicates
+
+    attr_reader command: Command::Custom
+    attr_reader exception: Exception
+
+    def self.new: (command: Command::Custom, exception: Exception) -> instance
+
+    def error?: () -> bool
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+  end
+
+  # Cancellation notification from a canceled command.
+  class Canceled < Data
+    include Predicates
+
+    attr_reader command: untyped
+
+    def self.new: (command: untyped) -> instance
+
+    def canceled?: () -> bool
+    alias cancelled? canceled?
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+  end
+
+  # Success notification from Command.open.
+  class Open < Data
+    include Predicates
+
+    attr_reader envelope: String
+
+    def self.new: (envelope: String) -> instance
+
+    def open?: () -> bool
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+  end
 end
 end

data/sig/rooibos/shortcuts.rbs

@@ -12,5 +12,19 @@ module Rooibos
     def self.sh: (String command, Symbol | Class tag) -> Command::System
     def self.map: (Command::execution inner_command) { (Array[untyped]) -> Array[untyped] } -> Command::Mapped
   end
+
+  # Short aliases for Message types.
+  module Msg
+    Timer: singleton(Message::Timer)
+    Http: singleton(Message::HttpResponse)
+
+    module Sh
+      Batch: singleton(Message::System::Batch)
+      Stream: singleton(Message::System::Stream)
+    end
+
+    All: singleton(Message::All)
+    Batch: singleton(Message::Batch)
+  end
 end
 end

data/sig/rooibos/test_helper.rbs

@@ -5,6 +5,10 @@
 
 module Rooibos
   module TestHelper
-  def validate_rooibos_command!: (Runtime::_MaybeCommand) -> nil
-end
+    def validate_rooibos_command!: (Runtime::_MaybeCommand) -> nil
+
+    # Fails if any Command::Error is present in the messages array.
+    # Relies on Minitest's flunk method being available in the including class.
+    def assert_no_errors: (Array[untyped] messages, ?String? msg) -> void
+  end
 end

data/sig/rooibos/welcome.rbs

@@ -0,0 +1,75 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Built-in welcome screen used by scaffolded applications.
+  module Welcome
+    WEBSITE_URL: String
+
+    # Internal UI module for styles and widgets.
+    module UI
+      module Styles
+        TEXT: RatatuiRuby::Style::Style
+        FILENAME: RatatuiRuby::Style::Style
+        COMMAND: RatatuiRuby::Style::Style
+        URL: RatatuiRuby::Style::Style
+        COMMAND_BUTTON: RatatuiRuby::Style::Style
+        COMMAND_BUTTON_FOCUS: RatatuiRuby::Style::Style
+        COMMAND_BUTTON_HOVER: RatatuiRuby::Style::Style
+        COMMAND_BUTTON_BOTH: RatatuiRuby::Style::Style
+        URL_BUTTON: RatatuiRuby::Style::Style
+        URL_BUTTON_FOCUS: RatatuiRuby::Style::Style
+        URL_BUTTON_HOVER: RatatuiRuby::Style::Style
+        URL_BUTTON_BOTH: RatatuiRuby::Style::Style
+      end
+
+      module Widgets
+        WELCOME_TEXT: Hash[String, RatatuiRuby::Style::Style]
+        PARAGRAPH: RatatuiRuby::Widgets::Paragraph
+        def self.website_button: (?focused: bool, ?hovered: bool) -> RatatuiRuby::Text::Span
+        def self.exit_button: (?focused: bool, ?hovered: bool) -> RatatuiRuby::Text::Span
+      end
+
+      BUTTON_SLOTS: Hash[Symbol, Integer]
+      FOCUS_ORDER: Array[Symbol]
+      BUTTON_BAR_CONSTRAINTS: Array[RatatuiRuby::Layout::Constraint]
+      CONTENT_CONSTRAINTS: Array[RatatuiRuby::Layout::Constraint]
+
+      def self.button_bar: (focused: Symbol?, hovered: Symbol?) -> RatatuiRuby::Layout::Layout
+      def self.content_layout: (focused: Symbol?, hovered: Symbol?) -> RatatuiRuby::Layout::Layout
+      def self.frame: (focused: Symbol?, hovered: Symbol?) -> RatatuiRuby::Widgets::Block
+
+      # Value object for button hit-test areas.
+      class ButtonAreas
+        attr_reader website: RatatuiRuby::Layout::Rect?
+        attr_reader exit: RatatuiRuby::Layout::Rect?
+        def initialize: (website: RatatuiRuby::Layout::Rect?, exit: RatatuiRuby::Layout::Rect?) -> void
+        def contains?: (Symbol name, Integer x, Integer y) -> bool
+        def button_at: (Integer x, Integer y) -> Symbol?
+        def for_viewport: (Integer width, Integer height) -> ButtonAreas
+      end
+    end
+
+    # Model for Welcome screen state.
+    class Model
+      attr_reader button_areas: UI::ButtonAreas
+      attr_reader focused: Symbol?
+      attr_reader hovered: Symbol?
+      def initialize: (button_areas: UI::ButtonAreas, focused: Symbol?, hovered: Symbol?) -> void
+      def tree: () -> RatatuiRuby::Widgets::Block
+      def active_button: () -> Symbol?
+      def with: (?button_areas: UI::ButtonAreas, ?focused: Symbol?, ?hovered: Symbol?) -> Model
+    end
+
+    View: ^(Model, untyped) -> RatatuiRuby::Widgets::Block
+    Update: ^(untyped, Model) -> (Model | Command::Exit | [Model, Command::System])
+    Init: ^() -> Model
+
+    def self.handle_click: (untyped message, Model model) -> (Model | Command::Exit | [Model, Command::System])
+    def self.handle_hover: (untyped message, Model model) -> Model
+    def self.cycle_focus: (Model model, Symbol direction) -> Model
+    def self.activate_button: (Symbol? button, Model model) -> (Model | Command::Exit | [Model, Command::System])
+  end
+end

data/tasks/install.rake

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "rubygems"
+
+namespace :install do
+  desc "Force install rooibos gem globally (required for integration tests)"
+  task :force do
+    require "rooibos/version"
+
+    # Build the gem first
+    Rake::Task["build"].invoke
+
+    gem_file = "pkg/rooibos-#{Rooibos::VERSION}.gem"
+    unless File.exist?(gem_file)
+      abort "Gem not found at #{gem_file}. Run 'rake build' first."
+    end
+
+    puts "Installing rooibos #{Rooibos::VERSION} globally..."
+    system("gem", "install", gem_file, "--force", "--no-document") ||
+      abort("Failed to install gem")
+
+    puts "✓ rooibos #{Rooibos::VERSION} installed globally"
+  end
+end

data/tasks/resources/build.yml.erb

@@ -40,6 +40,8 @@ tasks:
   - test: |
       . ~/.buildenv
       cd <%= gem_name %>
+      echo "Installing rooibos gem globally for integration tests..."
+      mise x -- bundle exec rake install:force
       echo "Testing Ruby <%= ruby_version %>"
       mise x -- bundle exec rake test
   - lint: |