rooibos 0.5.0 → 0.6.1

data/doc/contributors/WIP/v0.4.0_todo.md

@@ -1,468 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# v0.4.0 Remaining TODOs
-
-Outstanding items before releasing v0.4.0. Each section is self-contained with enough detail to implement independently.
-
----
-
-## 1. ~~Rename `tag` → `envelope` in Command.system and Command.all~~ ✅ DONE
-
----
-
-## 2. ~~Command.all Must Emit Message::All Instead of Raw Arrays~~ ✅ DONE
-
----
-
-# v0.4.1 Remaining TODOs
-
-Outstanding items before releasing v0.4.1. Each section is self-contained with enough detail to implement independently.
-
----
-
-## 3. Add Default `deconstruct_keys` to Command::Custom
-
-### Problem
-Design doc (lines 786-797) specifies that custom commands should have a default `deconstruct_keys` for hash-based pattern matching. Currently missing from `lib/rooibos/command/custom.rb`.
-
-### Implementation
-
-Add to `lib/rooibos/command/custom.rb` in the `Custom` module:
-
-```ruby
-# Methods inherited from common ancestor classes that are infrastructure,
-# not domain-specific query methods. 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
-
-  # Include OpenStruct only if already loaded (don't require it ourselves)
-  if defined?(OpenStruct)
-    methods += OpenStruct.new(_: nil).public_instance_methods
-  end
-
-  methods.uniq.freeze
-end
-private_constant :INFRASTRUCTURE_METHODS
-
-# Deconstructs for pattern matching.
-#
-# Introspects the object and builds a hash from all public query methods
-# (following CQS: methods with no side effects that return values).
-# Excludes infrastructure methods from Object, Data, and Struct to focus
-# on domain-specific fields.
-#
-# Always includes :type as a snake_case symbol of the class name.
-# 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)
-#
-# === Example
-#
-#   # For a Data.define(:envelope, :status, :body) command:
-#   case msg
-#   in { type: :http_response, envelope: :users, status: 200 }
-#     # handle success
-#   end
-def deconstruct_keys(keys)
-  # Snake-case class name as type discriminator
-  type_name = self.class.name.split("::").last
-    .gsub(/([a-z])([A-Z])/, '\1_\2')
-    .downcase
-    .to_sym
-
-  # Find public query methods: zero arity, not infrastructure, not commands/setters
-  query_methods = (public_methods - INFRASTRUCTURE_METHODS)
-    .select { |m| method(m).arity.zero? }
-    .reject { |m| m.to_s.end_with?("=", "!") }
-
-  # Build hash: filter by requested keys if provided
-  result = { type: type_name }
-  query_methods.each do |m|
-    result[m] = public_send(m) if keys.nil? || keys.include?(m)
-  end
-  result
-end
-```
-
-This provides a smart default that:
-- Computes infrastructure methods once from bare `Data.define`, `Struct`, and `OpenStruct` prototypes
-- Catches `members`, `with`, `to_h`, `deconstruct`, `deconstruct_keys`, etc. automatically
-- No hardcoded method lists — if Ruby adds new methods to these classes, they're excluded
-- Includes all Data.define members automatically (they generate accessor methods)
-- Excludes commands (methods ending in `!`) and setters (ending in `=`)
-- Respects the `keys` argument for performance (only calls methods for requested keys)
-
-### Limitations
-
-This is a **naive but practical** default:
-
-1. **Performance**: Introspects methods on every call. For hot paths, app devs should override with a static implementation.
-2. **Metaprogramming**: Ghost methods via `method_missing`/`respond_to_missing?` don't appear in `public_methods`. RBS introspection could help but is overkill for a default.
-3. **Custom accessors**: Only zero-arity methods are included. Methods with optional args won't be detected.
-
-**App devs who need more control should override `deconstruct_keys` directly.**
-
----
-
-## 4. Update Doc Comments to Show Hash Pattern Matching
-
-### Problem
-Doc comments in `lib/rooibos/command.rb` show array-based pattern matching (old style) instead of hash-based (new style per Appendix A).
-
-### Files to Update
-
-**lib/rooibos/command.rb** — Lines 326-350 (Command.system examples):
-
-```ruby
-# Current (wrong):
-#   in [:got_files, {stdout:, status: 0}]
-#     [model.with(files: stdout.lines), nil]
-#   in [:log, :stdout, line]
-#     [model.with(lines: [*model.lines, line]), nil]
-
-# Correct:
-#   in { type: :system, envelope: :got_files, stdout:, status: 0 }
-#     [model.with(files: stdout.lines), nil]
-#   in { type: :system, envelope: :log, stream: :stdout, content: line }
-#     [model.with(lines: [*model.lines, line]), nil]
-```
-
-Also update:
-- `lib/rooibos.rb` lines 106, 112: Change `::UPDATE` → `::Update` in examples
-- `lib/rooibos/router.rb` lines 19-20, 37: Change `INITIAL`, `UPDATE`, `VIEW` → `Init`, `Update`, `View` in docstrings
-
----
-
-## 5. Update widget_command_system Example
-
-### Problem
-`examples/widget_command_system/app.rb` uses outdated conventions:
-- Screaming-case constants: `INITIAL`, `VIEW`, `UPDATE`
-- Old `Rooibos.run` API: `Rooibos.run(model:, view:, update:)`
-
-### Implementation
-
-1. Rename constants (lines 28, 34, 100):
-   - `INITIAL` → `Init` (make it a lambda: `Init = -> { Model.new(...) }`)
-   - `VIEW` → `View`
-   - `UPDATE` → `Update`
-
-2. Change `Rooibos.run` call (line 128):
-   ```ruby
-   # Current:
-   Rooibos.run(model: INITIAL, view: VIEW, update: UPDATE)
-   
-   # Correct (Fragment-first API):
-   Rooibos.run(WidgetCommandSystem)
-   ```
-
-3. Update pattern matching in `Update` lambda (lines 103-106) to use hash-based format:
-   ```ruby
-   # Current:
-   in [:got_output, { stdout:, status: 0 }]
-   
-   # Correct:
-   in { type: :system, envelope: :got_output, stdout:, status: 0 }
-   ```
-
-4. Fix variable shadowing bugs on lines 117, 121: `command` vs `cmd`
-
----
-
-## 6. Rooibos.delegate Array Wrapping (Lower Priority)
-
-### Problem
-Line 853 of design doc states: "Rooibos's delegate helper should probably not wrap in arrays."
-
-Currently `Rooibos.delegate` (lib/rooibos.rb:116) passes `rest = message[1..]` as an array to child update. The design suggests passing unwrapped messages.
-
-### Consideration
-This may be intentional for consistency. Review whether child updates expect array or unwrapped messages before changing. If changing:
-
-```ruby
-# Current:
-rest = message[1..]
-new_child, command = child_update.call(rest, child_model)
-
-# Potentially:
-rest = message[1]  # Single value, not array
-new_child, command = child_update.call(rest, child_model)
-```
-
-**Note:** This change may break existing code. Audit all `Rooibos.delegate` callers first.
-
----
-
-## 7. Missing Tests (Technical Debt)
-
-### Phase 3: Mixed Command Types Test
-Add test demonstrating `Command.batch` or `Command.all` with heterogeneous child commands:
-
-```ruby
-def test_batch_with_mixed_command_types
-  cmd = Command.batch(
-    Command.http(:get, "/api/users", :users),
-    Command.wait(0.1, :timer),
-    Command.system("echo hello", :shell)
-  )
-  # Verify all three types execute and return properly
-end
-```
-
-### Phase 5: Sync→Parallel→Sync Flow Test
-Add test demonstrating `Outlet#source` orchestration:
-
-```ruby
-def test_source_sync_parallel_sync_flow
-  # Custom command that:
-  # 1. source(single_command) - sync
-  # 2. source(Command.all([...]) - parallel
-  # 3. source(single_command) - sync again
-  # Verify correct sequencing and result handling
-end
-```
-
----
-
-## 8. Update test_widget_command_system.rb
-
-### Problem
-Uses `::UPDATE` and `::INITIAL` screaming-case (lines 14, 17, 28, 31).
-
-### Implementation
-After updating the example (TODO #5), update the tests to use `::Update` and `::Init`.
-
----
-
-## Verification
-
-After implementing all items, run:
-
-```bash
-bundle exec rake test
-```
-
-All tests should pass. The following patterns should work in update functions:
-
-```ruby
-case msg
-in { type: :http, envelope: :users, status: 200, body: }
-  # HTTP success
-in { type: :system, envelope: :files, stdout:, status: 0 }
-  # System batch success
-in { type: :timer, envelope: :dismiss, elapsed: }
-  # Timer completed
-in { type: :all, envelope: :dashboard, results: }
-  # Aggregated parallel results
-end
-```
-
----
-
-## 9. Add `out.source_nonblock` for Parallel Streaming Commands
-
-### Context
-
-Custom commands can orchestrate work using `out.source(cmd, token)` for sequential steps and `Command.all` for parallel-but-wait-for-all patterns. However, there's no way to run multiple streaming commands in parallel where each emits messages live as they arrive.
-
-### Problem
-
-Consider a dashboard that:
-1. Authenticates
-2. Fetches initial data
-3. Opens two Server-Sent Events (SSE) streams for live updates
-4. Post-processes each stream's chunks differently
-5. Emits processed chunks to the update function as they arrive
-
-With current primitives:
-- `out.source` blocks — can only read one stream at a time
-- `Command.all` waits for ALL to complete — no live streaming
-- `Command.batch` only works from `update`, not inside custom commands
-- Raw `Thread.new` causes silent hangs if threads crash (documented in `doc/concepts/async_work.md`)
-
-Developers are stuck.
-
-### Solution
-
-Add `out.source_nonblock` to spawn async child commands that stream messages live:
-
-```ruby
-# API:
-handle = out.source_nonblock(command, token)              # messages pass directly to runtime
-handle = out.source_nonblock(command, token, processor)   # messages go through processor first
-out.last(handle1, handle2, ...)                           # block until all handles complete
-```
-
-### Usage Example
-
-```ruby
-class LoadDashboard < Data.define(:user_id, :tag)
-  include Rooibos::Command::Custom
-
-  def call(out, token)
-    # Sequential: authenticate first
-    auth = out.source(Authenticate.new(user_id:, tag: :_), token)
-    return if auth.nil? || token.canceled?
-
-    # Sequential: fetch initial data
-    dashboard = out.source(
-      Command.all(:_, [FetchProfile.new(...), FetchNotifications.new(...)]),
-      token
-    )
-    return if dashboard.nil? || token.canceled?
-    out.put(tag, dashboard.results)
-
-    # Parallel streaming: two SSE connections
-    # 5a: Pass messages directly to update function (no processing)
-    h1 = out.source_nonblock(StreamNotifications.new(auth[:token]), token)
-
-    # 5b: Post-process messages before they reach update function
-    h2 = out.source_nonblock(
-      StreamDashboardDeltas.new(dashboard.results[:profile][:id], auth[:token]),
-      token,
-      DeltaPostProcessor.new(user_id)  # Ractor-shareable callable
-    )
-
-    # 5c: Block until both streams complete (or are cancelled)
-    out.last(h1, h2)
-  end
-end
-
-# The processor is a Ractor-shareable callable:
-DeltaPostProcessor = Data.define(:user_id) do
-  def call(chunk, out)
-    processed = transform(chunk)
-    out.put(:delta, { user_id:, data: processed })
-  end
-
-  def transform(chunk)
-    # post-processing logic
-  end
-end
-```
-
-### Implementation
-
-#### 1. Add `AsyncHandle` class
-
-In `lib/rooibos/command/outlet.rb`:
-
-```ruby
-AsyncHandle = Data.define(:future, :channel) do
-  def done?
-    future.resolved?
-  end
-end
-```
-
-#### 2. Add `source_nonblock` to `Outlet`
-
-```ruby
-def source_nonblock(command, token, processor = nil)
-  channel = Concurrent::Promises::Channel.new
-
-  # Create outlet that writes to channel instead of parent queue
-  child_outlet = if processor
-    ProcessorOutlet.new(channel, processor, @message_queue)
-  else
-    ChannelOutlet.new(channel, @message_queue)
-  end
-
-  # Spawn child command
-  future = Concurrent::Promises.future do
-    command.call(child_outlet, token)
-    channel.push(:done)
-  rescue => e
-    @message_queue.push Command::Error.new(command:, exception: e)
-    channel.push(:done)
-  end
-
-  (@pending_async ||= []) << AsyncHandle.new(future:, channel:)
-  AsyncHandle.new(future:, channel:)
-end
-```
-
-#### 3. Add outlet variants
-
-```ruby
-# Passes messages directly to runtime queue
-ChannelOutlet = Data.define(:channel, :message_queue) do
-  def put(*args)
-    message = (args.size == 1) ? args.first : args.freeze
-    message_queue.push(message)
-  end
-end
-
-# Invokes processor, which calls out.put on a Ractor-safe outlet
-ProcessorOutlet = Data.define(:channel, :processor, :message_queue) do
-  def put(*args)
-    message = (args.size == 1) ? args.first : args.freeze
-    # Processor receives message and a simple outlet for its output
-    output_outlet = ChannelOutlet.new(channel, message_queue)
-    processor.call(message, output_outlet)
-  rescue => e
-    message_queue.push Command::Error.new(command: processor, exception: e)
-  end
-end
-```
-
-#### 4. Add `last` method
-
-```ruby
-def last(*handles)
-  handles = @pending_async if handles.empty?
-  handles.each do |handle|
-    handle.future.wait
-  end
-  @pending_async&.clear
-end
-```
-
-### Ractor Safety
-
-- **Child command**: runs in Ractor/future, must be shareable (existing requirement)
-- **Processor**: must be Ractor-shareable (e.g., `Data.define` with shareable members)
-- **Messages**: must be shareable (existing requirement)
-- **The block IS NOT USED**: callbacks are shareable callables, not closures
-
-The processor runs in the child's context (Ractor/future). It receives a Ractor-safe outlet that pushes to a channel. The runtime reads the channel and delivers messages — no closure crosses the Ractor boundary.
-
-### Tests
-
-Add to `test/test_outlet.rb`:
-
-```ruby
-def test_source_nonblock_streams_messages_live
-  # Custom command that:
-  # 1. source(single_command) - sync
-  # 2. source_nonblock(streaming_cmd1), source_nonblock(streaming_cmd2)
-  # 3. last(h1, h2)
-  # Verify messages arrive interleaved as streams produce them
-end
-
-def test_source_nonblock_with_processor_transforms_messages
-  # Verify processor.call is invoked for each message
-  # Verify transformed output reaches update function
-end
-
-def test_source_nonblock_crash_produces_command_error
-  # Verify child crash doesn't hang — becomes Command::Error
-end
-
-def test_source_nonblock_processor_crash_produces_command_error
-  # Verify processor crash doesn't hang — becomes Command::Error
-end
-```
-

data/doc/contributors/kit-no-outlet.md

@@ -1,238 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Why Kit Doesn't Need Outlet
-
-> **Context**: The `unified-draft.md` specifies `Rooibos::Command::Outlet` for message passing from custom commands to the Rooibos runtime. This document explains why Kit (the component-based runtime) does not need this abstraction.
-
----
-
-## The Core Insight: Immediate-Mode Rendering
-
-RatatuiRuby's Engine is **immediate-mode**:
-
-> "Each frame, your code describes the entire UI from scratch. The Engine draws it and immediately forgets it, holding no application state between renders."
-
-This means Kit walks the entire component tree and calls `render` **every frame**. Components don't need to notify anyone of state changes—the next frame automatically sees updated state.
-
----
-
-## Rooibos vs Kit: Different Problems
-
-| Concern | Rooibos | Kit |
-|---------|-----|-----|
-| **State model** | Immutable (Ractor-safe) | Mutable (encapsulated) |
-| **State location** | Single Model in runtime | Distributed in components |
-| **Async results** | Message → Queue → Update | Callback → mutate state |
-| **Render trigger** | After update function | **Every frame** |
-| **Re-render notification** | Implicit (update always renders) | **Not needed** (always renders) |
-
----
-
-## WebSocket Example: Rooibos vs Kit
-
-### Rooibos: Outlet Required
-
-```ruby
-
-class WebSocketCommand
-  include Rooibos::Command::Custom
-
-  def call(out, token)
-    ws = WebSocket::Client.new(@url)
-    ws.on_message { |msg| out.put(:ws, :message, data: msg) }
-    ws.connect
-
-    until token.cancelled?
-      sleep 1
-    end
-
-    ws.close
-  end
-end
-
-def update(msg, model)
-  case msg
-  in [:ws, :message, data:]
-    model.with(messages: model.messages + [data])
-  end
-end
-```
-
-Rooibos needs Outlet because:
-1. Command runs in a separate thread
-2. Model is immutable—can't mutate from callback
-3. Runtime must receive messages to call `update`
-
-### Kit: Direct Mutation
-
-```ruby
-class WebSocketTab
-  include Kit::Component
-
-  def initialize(url:)
-    @url = url
-    @messages = []
-  end
-
-  def mount
-    @ws = WebSocket::Client.new(@url)
-    @ws.on_message { |msg| @messages << msg }
-    @ws.connect_async
-  end
-
-  def unmount
-    @ws&.close
-  end
-
-  def render(frame, area)
-    frame.render_widget(tui.list(items: @messages.last(10)), area)
-  end
-end
-```
-
-Kit doesn't need Outlet because:
-1. Component owns the WebSocket directly
-2. State is mutable—callbacks mutate `@messages`
-3. Next frame's `render` sees updated state automatically
-
----
-
-## Why Each Rooibos Concept Is Unnecessary in Kit
-
-### Outlet (Message Gateway)
-
-**Rooibos**: Routes messages from command thread → runtime queue → update function.
-
-**Kit**: Not needed. Callbacks mutate component state directly. Immediate-mode rendering sees changes next frame.
-
-### CancellationToken
-
-**Rooibos**: Runtime signals command to stop cooperatively, since commands run in spawned threads tracked by the runtime.
-
-**Kit**: Not needed. Components have `unmount` lifecycle hook. Component stops its own resources:
-
-```ruby
-def unmount
-  @ws&.close
-  @polling_thread&.kill
-end
-```
-
-### Ractor Safety
-
-**Rooibos**: Messages cross thread boundaries and must be Ractor-shareable for future Ruby 4.0 compatibility.
-
-**Kit**: Not needed. Components are mutable by design. State stays within the component. No Ractor isolation required.
-
-### Thread Tracking
-
-**Rooibos**: Runtime tracks spawned command threads to ensure clean shutdown.
-
-**Kit**: Not needed. Each component tracks its own resources. Tree traversal during shutdown calls `unmount` on each component.
-
----
-
-## What Kit DOES Need
-
-### 1. Lifecycle Hooks
-
-```ruby
-module Kit::Component
-  def mount
-    # Called when component enters tree
-  end
-
-  def unmount
-    # Called when component leaves tree
-  end
-end
-```
-
-These replace Rooibos's command spawning and cancellation.
-
-### 2. Thread Safety for Complex Mutations
-
-For simple mutations (array append, boolean toggle), Ruby's GIL is sufficient.
-
-For complex mutations:
-
-```ruby
-def mount
-  @mutex = Mutex.new
-  @ws = WebSocket::Client.new(@url)
-  @ws.on_message do |msg|
-    @mutex.synchronize { @messages << msg }
-  end
-end
-
-def render(frame, area)
-  messages = @mutex.synchronize { @messages.dup }
-  # render with messages
-end
-```
-
-### 3. Error Handling
-
-Components should rescue and surface errors:
-
-```ruby
-def mount
-  @ws = WebSocket::Client.new(@url)
-  @ws.on_error { |e| @error = e.message }
-rescue => e
-  @error = e.message
-end
-```
-
----
-
-## Comparison Table
-
-| Abstraction | Rooibos | Kit | Why Different |
-|-------------|-----|-----|---------------|
-| **Outlet** | ✓ Required | ✗ Not needed | Kit mutates directly |
-| **CancellationToken** | ✓ Required | ✗ Not needed | Kit has `unmount` |
-| **Ractor safety** | ✓ Required | ✗ Not needed | Kit is mutable |
-| **Thread tracking** | ✓ Runtime tracks | ✗ Not needed | Components self-manage |
-| **Lifecycle hooks** | ✗ Not applicable | ✓ Required | Kit needs mount/unmount |
-| **Mutex** | ✗ Uses Outlet | ⚠ If complex | Kit needs manual locking |
-
----
-
-## Architectural Summary
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                          ENGINE                                  │
-│               (Immediate-mode, renders every frame)              │
-├─────────────────────────────┬───────────────────────────────────┤
-│         ROOIBOS             │              KIT                   │
-│                             │                                    │
-│  Immutable Model            │  Mutable Components                │
-│  Commands spawn threads     │  Components own resources          │
-│  Outlet sends messages      │  Callbacks mutate state            │
-│  Runtime tracks threads     │  unmount cleans up                 │
-│  Ractor-safe required       │  GIL + Mutex sufficient            │
-│                             │                                    │
-│  NEEDS OUTLET               │  DOESN'T NEED OUTLET               │
-└─────────────────────────────┴───────────────────────────────────┘
-```
-
----
-
-## Conclusion
-
-**Outlet is Rooibos-specific.** It solves the problem of getting async results into an immutable, unidirectional data flow.
-
-Kit's paradigm—mutable components with immediate-mode rendering—makes Outlet unnecessary:
-
-1. **Callbacks mutate state** → No message routing needed
-2. **Render every frame** → No change notification needed
-3. **`unmount` hook** → No external cancellation needed
-4. **Components own resources** → No runtime tracking needed
-
-The Outlet stays in `Rooibos::Command::Outlet`. Kit needs no equivalent.