rooibos 0.5.0 → 0.6.1

data/lib/rooibos/welcome.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+module Rooibos
+  # Built-in welcome screen used by scaffolded applications.
+  module Welcome
+    module UI # :nodoc:
+      module Styles # :nodoc:
+        TEXT = RatatuiRuby::Style::Style.new
+        FILENAME = RatatuiRuby::Style::Style.new(fg: :green)
+        COMMAND = RatatuiRuby::Style::Style.new(fg: :red)
+        URL = RatatuiRuby::Style::Style.new(fg: :blue)
+
+        COMMAND_BUTTON = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:underlined])
+        COMMAND_BUTTON_FOCUS = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:bold, :underlined])
+        COMMAND_BUTTON_HOVER = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:reversed])
+        COMMAND_BUTTON_BOTH = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:bold, :reversed])
+
+        URL_BUTTON = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:underlined])
+        URL_BUTTON_FOCUS = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:bold, :underlined])
+        URL_BUTTON_HOVER = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:reversed])
+        URL_BUTTON_BOTH = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:bold, :reversed])
+      end
+
+      module Widgets # :nodoc:
+        WELCOME_TEXT = {
+          "Welcome to Rooibos! You will find the Ruby code " \
+            "for this application in " => Styles::TEXT,
+          "lib/saturday.rb" => Styles::FILENAME,
+          ". The tests that verify it are at " => Styles::TEXT,
+          "test/test_saturday.rb" => Styles::FILENAME,
+          ". You can run the tests with " => Styles::TEXT,
+          "bundle exec rake test" => Styles::COMMAND,
+          ". Visit " => Styles::TEXT,
+          "www.rooibos.run" => Styles::URL,
+          " to learn about Rooibos and to find other " \
+            "Rooibos developers. You can press " => Styles::TEXT,
+          "Control + C" => Styles::COMMAND,
+          " to exit at any time." => Styles::TEXT,
+        }
+
+        PARAGRAPH = RatatuiRuby::Widgets::Paragraph.new(
+          text: RatatuiRuby::Text::Line.new(
+            spans: WELCOME_TEXT.map { |text, style| RatatuiRuby::Text::Span.new(content: text, style:) }
+          ),
+          wrap: true,
+          alignment: :left
+        )
+
+        def self.website_button(focused: false, hovered: false)
+          style = if focused && hovered
+            Styles::URL_BUTTON_BOTH
+          elsif focused
+            Styles::URL_BUTTON_FOCUS
+          elsif hovered
+            Styles::URL_BUTTON_HOVER
+          else
+            Styles::URL_BUTTON
+          end
+          RatatuiRuby::Text::Span.new(content: "[Visit Website]", style:)
+        end
+
+        def self.exit_button(focused: false, hovered: false)
+          style = if focused && hovered
+            Styles::COMMAND_BUTTON_BOTH
+          elsif focused
+            Styles::COMMAND_BUTTON_FOCUS
+          elsif hovered
+            Styles::COMMAND_BUTTON_HOVER
+          else
+            Styles::COMMAND_BUTTON
+          end
+          RatatuiRuby::Text::Span.new(content: "[Exit App]", style:)
+        end
+      end
+
+      BUTTON_SLOTS = { website: 1, exit: 3 }.freeze
+      FOCUS_ORDER = [:website, :exit].freeze
+
+      BUTTON_BAR_CONSTRAINTS = [
+        RatatuiRuby::Layout::Constraint.fill(1),
+        RatatuiRuby::Layout::Constraint.length(18),
+        RatatuiRuby::Layout::Constraint.length(2),
+        RatatuiRuby::Layout::Constraint.length(14),
+        RatatuiRuby::Layout::Constraint.fill(1),
+      ].freeze
+
+      CONTENT_CONSTRAINTS = [
+        RatatuiRuby::Layout::Constraint.fill(1),
+        RatatuiRuby::Layout::Constraint.length(1),
+      ].freeze
+
+      def self.button_bar(focused:, hovered:)
+        RatatuiRuby::Layout::Layout.new(
+          direction: :horizontal,
+          constraints: BUTTON_BAR_CONSTRAINTS,
+          children: [
+            nil,
+            Widgets.website_button(focused: focused == :website, hovered: hovered == :website),
+            nil,
+            Widgets.exit_button(focused: focused == :exit, hovered: hovered == :exit),
+            nil,
+          ]
+        )
+      end
+
+      def self.content_layout(focused:, hovered:)
+        RatatuiRuby::Layout::Layout.new(
+          direction: :vertical,
+          constraints: CONTENT_CONSTRAINTS,
+          children: [Widgets::PARAGRAPH, button_bar(focused:, hovered:)]
+        )
+      end
+
+      def self.frame(focused:, hovered:)
+        RatatuiRuby::Widgets::Block.new(
+          title: "Hello, Rooibos!",
+          borders: [:all],
+          border_style: { fg: :cyan },
+          padding: [2, 2, 1, 1],
+          children: [content_layout(focused:, hovered:)]
+        )
+      end
+
+      # Value object wrapping hit-test areas for clickable buttons.
+      ButtonAreas = Data.define(:website, :exit) do
+        def contains?(name, x, y) = public_send(name)&.contains?(x, y)
+
+        def button_at(x, y)
+          return :website if website&.contains?(x, y)
+          return :exit if exit&.contains?(x, y)
+
+          nil
+        end
+
+        def for_viewport(width, height)
+          viewport = RatatuiRuby::Layout::Rect.new(x: 0, y: 0, width:, height:)
+          frame = UI.frame(focused: nil, hovered: nil)
+          inner = frame.inner(viewport)
+
+          content_rects = RatatuiRuby::Layout::Layout.split(
+            inner,
+            direction: :vertical,
+            constraints: CONTENT_CONSTRAINTS
+          )
+          button_rects = RatatuiRuby::Layout::Layout.split(
+            content_rects[1],
+            direction: :horizontal,
+            constraints: BUTTON_BAR_CONSTRAINTS
+          )
+
+          ButtonAreas.new(
+            website: button_rects[BUTTON_SLOTS[:website]],
+            exit: button_rects[BUTTON_SLOTS[:exit]]
+          )
+        end
+      end
+    end
+
+    # focused: keyboard focus (persists until Tab/Shift+Tab)
+    # hovered: mouse hover (clears on mouse-out)
+    Model = Data.define(:button_areas, :focused, :hovered) do
+      def tree = UI.frame(focused:, hovered:)
+
+      # Returns the "active" button for activation (keyboard takes precedence)
+      def active_button = focused || hovered
+    end
+
+    View = -> (model, _tui) { model.tree }
+
+    Update = -> (message, model) {
+      case message
+      in _ if message.ctrl_c?
+        Rooibos::Command.exit
+      in _ if message.resize?
+        model.with(button_areas: model.button_areas.for_viewport(message.width, message.height))
+      in _ if message.tab?
+        cycle_focus(model, :forward)
+      in _ if message.shift_back_tab?
+        cycle_focus(model, :backward)
+      in _ if message.enter? && model.active_button
+        activate_button(model.active_button, model)
+      in _ if message.mouse? && message.down? && message.button == "left"
+        handle_click(message, model)
+      in { type: :mouse }
+        handle_hover(message, model)
+      else
+        model
+      end
+    }
+
+    Init = -> {
+      viewport = RatatuiRuby.terminal_size
+      areas = UI::ButtonAreas.new(website: nil, exit: nil).for_viewport(viewport.width, viewport.height)
+      Ractor.make_shareable Model.new(button_areas: areas, focused: nil, hovered: nil)
+    }
+
+    def self.handle_click(message, model)
+      button = model.button_areas.button_at(message.x, message.y)
+      activate_button(button, model)
+    end
+
+    def self.handle_hover(message, model)
+      new_hovered = model.button_areas.button_at(message.x, message.y)
+      return model if new_hovered == model.hovered
+
+      model.with(hovered: new_hovered)
+    end
+
+    def self.cycle_focus(model, direction)
+      order = UI::FOCUS_ORDER
+      return model.with(focused: order.first) unless model.focused
+
+      current_index = order.index(model.focused)
+      return model.with(focused: order.first) unless current_index
+
+      next_index = case direction
+                  when :forward then (current_index + 1) % order.length
+                  when :backward then (current_index - 1) % order.length
+                  else 0
+      end
+      model.with(focused: order[next_index])
+    end
+
+    def self.activate_button(button, model)
+      case button
+      when :website then [model, Rooibos::Command.system("open 'https://www.rooibos.run'", :open_url)]
+      when :exit then Rooibos::Command.exit
+      else model
+      end
+    end
+  end
+end

data/lib/rooibos.rb

@@ -11,6 +11,7 @@ require_relative "rooibos/message"
 require_relative "rooibos/command"
 require_relative "rooibos/runtime"
 require_relative "rooibos/router"
+require_relative "rooibos/welcome"
 
 # The Elm Architecture for Ruby.
 #
@@ -103,17 +104,17 @@ module Rooibos
   #   # Verbose:
   #   case message
   #   in [:stats, *rest]
-  #     new_child, cmd = StatsPanel::UPDATE.call(rest, model.stats)
+  #     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)
+  #   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..]
+    rest = message[1]
     new_child, command = child_update.call(rest, child_model)
     wrapped = command ? route(command, prefix) : nil
     [new_child, wrapped]

data/mise.toml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 [tools]
-ruby = "4.0.0"
+ruby = "4.0.1"
 rust = "1.91.1"
 python = "3.12"
 pre-commit = "latest"

data/rbs_collection.lock.yaml

@@ -66,11 +66,11 @@ gems:
   source:
     type: stdlib
 - name: prism
-  version: 1.7.0
+  version: 1.8.0
   source:
     type: rubygems
 - name: ratatui_ruby
-  version: 0.10.2
+  version: 1.1.0
   source:
     type: rubygems
 - name: ratatui_ruby-devtools

data/sig/concurrent.rbs

@@ -31,6 +31,7 @@ module Concurrent
       def rejected?: () -> bool
       def wait: (?Numeric? timeout) -> self
       def value: () -> T?
+      def value!: () -> T
       def reason: () -> Exception?
     end
 
@@ -39,6 +40,9 @@ module Concurrent
 
     # Races multiple futures/events, returning when any resolves.
     def self.any_event: (*Future[untyped] | ResolvableEvent) -> ResolvableEvent
+
+    # Joins multiple futures, resolving when all complete.
+    def self.zip_futures: (*Future[untyped]) -> Future[Array[untyped]]
   end
 
   # Single-element blocking container for synchronization.

data/sig/gem.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Local shim for Gem::Version#segments not in stdlib RBS.
+# TODO: Remove when upstream RBS adds this method.
+
+module Gem
+  class Version
+    # Returns version segments as an array of integers and strings.
+    def segments: () -> Array[Integer | String]
+  end
+end
+
+# Local shim for RatatuiRuby.terminal_size alias not in upstream RBS.
+# The Ruby gem has: alias terminal_size get_terminal_size
+module RatatuiRuby
+  def self.terminal_size: () -> RatatuiRuby::Layout::Rect
+end

data/sig/rooibos/cli.rbs

@@ -0,0 +1,42 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module CLI
+    COMMANDS: Hash[String, singleton(Commands::New) | singleton(Commands::Run)]
+
+    def self.call: (Array[String]) -> void
+    def self.usage: () -> String
+
+    module Commands
+      module New
+        # Options hash from parse_options.
+        type options = Hash[Symbol, bool | String]
+
+        BUNDLE_GEM_DEFAULTS: Array[String]
+
+        def self.call: (Array[String]) -> void
+        def self.usage: () -> String
+        def self.parse_options: (Array[String]) -> options
+        def self.create_app: (String, Array[String], options) -> void
+        def self.build_bundle_gem_args: (Array[String]) -> Array[String]
+        def self.git_enabled?: (Array[String]) -> bool
+        def self.make_initial_commit: (Pathname) -> void
+        def self.to_module_name: (String) -> String
+        def self.fix_gemspec_placeholders: (String) -> String
+        def self.exe_template: (String, String) -> String
+        def self.app_template: (String, String) -> String
+        def self.test_template: (String, String) -> String
+      end
+
+      module Run
+        def self.call: (Array[String]) -> void
+        def self.usage: () -> String
+        def self.run_app: () -> void
+        def self.find_project_root: () -> Pathname?
+      end
+    end
+  end
+end

data/sig/rooibos/command.rbs

@@ -18,6 +18,10 @@ module Rooibos
     # Grace period for cooperative cancellation (seconds).
     # Runtime waits this long before force-killing the thread.
     def rooibos_cancellation_grace_period: () -> Float
+
+    # Runtime type checking (from Kernel).
+    # Required for DWIM nested detection in All.new.
+    def is_a?: (Module | Class module_or_class) -> bool
   end
 
   # Sentinel value for application termination.
@@ -114,9 +118,9 @@ module Rooibos
     include Custom
 
     attr_reader seconds: Float
-    attr_reader tag: Symbol
+    attr_reader envelope: Symbol
 
-    def self.new: (seconds: Float, tag: Symbol) -> instance
+    def self.new: (seconds: Float, envelope: Symbol) -> instance
 
     # Execute the timer with cooperative cancellation.
     def call: (Outlet out, Concurrent::Cancellation token) -> void
@@ -135,12 +139,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 +196,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
 
@@ -188,10 +214,18 @@ module Rooibos
     attr_reader live: Lifecycle
 
     # Sends a message to the runtime.
-    def put: (*Object args) -> void
+    def put: (*message args) -> void
 
     # 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.
@@ -212,17 +246,17 @@ module Rooibos
   class All
     include Custom
 
-    attr_reader tag: Symbol
-    attr_reader commands: Array[Custom]
+    attr_reader envelope: Symbol
+    attr_reader commands: Array[_Command]
     attr_reader nested: bool
 
-    def self.new: (Symbol tag, *Custom | Array[Custom]) -> instance
+    def self.new: (Symbol envelope, *_Command | Array[_Command]) -> instance
 
     def call: (Outlet outlet, Concurrent::Cancellation token) -> void
   end
 
   # Creates an aggregating parallel command.
-  def self.all: (Symbol tag, *Custom | Array[Custom]) -> All
+  def self.all: (Symbol envelope, *_Command | Array[_Command]) -> All
 
   # HTTP response shapes for pattern matching
   type http_success_shape = { type: :http, envelope: Symbol, status: Integer, body: String, headers: Hash[String, String] }
@@ -261,5 +295,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

@@ -4,13 +4,26 @@
 #++
 
 module Rooibos
+  # Any value passed through Outlet#put to the runtime.
+  # Commands may produce any type; Predicates mixin is optional.
+  type message = Object
+
   # Messages sent from commands to update functions.
   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,22 +113,73 @@ 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
 
     attr_reader envelope: Symbol
-    attr_reader results: Array[untyped]
+    attr_reader results: Array[message]
     attr_reader nested: bool
 
     def initialize: (
       envelope: Symbol,
-      results: Array[untyped],
+      results: Array[message],
       nested: bool
     ) -> void
 
     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