rooibos 0.5.0 → 0.6.0

data/doc/contributors/documentation_stub_audit.md

@@ -0,0 +1,112 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Documentation Stub Audit
+
+Audit of learning objectives against the actual Rooibos codebase.
+
+**Legend:**
+- ⚠️ Minor issue or suggestion
+- ❌ Major issue, needs revision
+
+---
+
+## Essentials
+
+## Scaling Up
+
+## Best Practices
+
+### `forms_and_validation.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_form/` — multi-field form with validation
+- ❌ **MAJOR:** Need validation error display example in the form app
+
+---
+
+### `lists_and_tables.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_master_detail/` — list sidebar + table top-right + detail pane bottom-right (list chooses table, table chooses detail)
+
+---
+
+### `http_workflows.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_web_api/` — retry logic with exponential backoff
+- ❌ **MAJOR:** Need caching example in the HTTP app
+
+---
+
+### `streaming_data.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_websocket/` — simplified version of official third-party WebSocket gem to teach SSE/websocket patterns
+
+---
+
+### `orchestration.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_command_orchestration/` — partial failure handling and multi-step pipeline patterns
+
+---
+
+## Troubleshooting
+
+## Tutorial
+
+### `index.md`
+
+**Audit:**
+- ❌ **MAJOR:** Need `examples/app_file_browser/` — complete example that tutorial chapters will walk through building
+
+---
+
+### `04_handling_input.md`
+
+**Audit:**
+- ℹ️ **Objective 5:** References the file browser from `examples/app_file_browser/` — tutorial walks through building it
+
+---
+
+### `08_the_preview_pane.md`
+
+**Audit:**
+- ℹ️ **Objective 1:** References the file browser from `examples/app_file_browser/` — tutorial walks through building it
+
+---
+
+### `11_polish_and_refine.md`
+
+**Audit:**
+- ℹ️ **Objective 1:** Edge case handling is application logic — teach patterns, not framework features
+- ℹ️ **Objective 2:** Help overlay is application-level UI — teach implementation patterns
+
+---
+
+### `12_going_further.md`
+
+**Audit:**
+- ℹ️ All objectives are purely meta/navigational — appropriate for "Going Further" chapter
+
+---
+
+## Getting Started
+
+### `for_go_developers.md`
+
+**Audit:**
+- ℹ️ **Objective 3:** Rooibos Cmd pattern differs — uses `Command::Custom` protocol vs BubbleTea's `tea.Cmd` function (teach the difference)
+- ❌ **MAJOR:** Need `examples/app_bubbletea_counter/` — side-by-side comparison with equivalent BubbleTea code
+
+---
+
+### `ruby_primer.md`
+
+**Audit:**
+- ℹ️ All objectives are Ruby language education — appropriate for onboarding non-Rubyists

data/doc/contributors/documentation_style.md

@@ -0,0 +1,275 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Documentation Style Guide
+
+This guide defines how to write Rooibos user documentation. It applies to all markdown files in `doc/` (except `doc/contributors/`, which follows its own standards).
+
+**All docs must be reviewed against this guide before merging.**
+
+---
+
+## Document Types
+
+Rooibos has three distinct document types. Each follows different patterns:
+
+| Type | Location | Pattern | Purpose |
+|------|----------|---------|---------|
+| **Tutorial** | `tutorial/` | Progressive build | Hands-on learning |
+| **Concept** | `essentials/`, `scaling_up/`, `best_practices/` | Context-Problem-Solution | Understanding why |
+| **Troubleshooting** | `troubleshooting/` | Error → Cause → Fix | Solving problems |
+
+---
+
+## Tutorial Chapters
+
+Tutorials teach through action. Readers learn by doing, then understanding.
+
+### Structure
+
+1. **Chapter title** — What you'll accomplish
+2. **Learning objectives** — What you'll know by the end (bulleted list)
+3. **Prerequisites** — What you should have completed first
+4. **Steps** — Numbered actions: "Type this → Run this → See this"
+5. **Explanation** — Why it works (after the reader has seen it work)
+6. **Summary** — What you learned
+
+### Example
+
+```markdown
+# Adding State to Your App
+
+By the end of this chapter, you will:
+- Understand what a Model is
+- Create your first `Data.define` struct
+- See how state flows through the MVU loop
+
+## Prerequisites
+
+Complete [Your First View](02_hello_world.md) before starting.
+
+## Step 1: Define Your Model
+
+Create a new file called `model.rb`:
+
+    Model = Data.define(:current_path, :entries)
+
+Run your app:
+
+    ruby app.rb
+
+You should see...
+
+## Why This Works
+
+The `Model` holds all of your application state...
+```
+
+### Guidelines
+
+- **Do first, explain after** — Show the code, let them run it, then explain
+- **Small steps** — Each step should produce a visible result
+- **No surprises** — If something can go wrong, warn them first
+- **Screenshots** — Show what success looks like
+
+---
+
+## Concept Documents
+
+Concept docs explain ideas. They answer "why" questions.
+
+### Structure: Context-Problem-Solution (Alexandrian Form)
+
+Every concept doc follows this pattern:
+
+1. **Title** — The concept name
+2. **Learning objectives** — "After reading this guide, you will know:" (Rails pattern)
+3. **Context** — Set the scene. What situation is the reader in?
+4. **Problem** — What difficulty or pain exists without this?
+5. **Solution** — How Rooibos solves it
+6. **Deep dive** — Detailed explanation with examples
+7. **See also** — Cross-references to related docs
+
+### Example
+
+```markdown
+# The Elm Architecture
+
+After reading this guide, you will know:
+- What Model-View-Update means
+- Why unidirectional data flow prevents bugs
+- How the runtime coordinates your app
+
+---
+
+## Context
+
+Applications have state. A counter has a count. A file browser has a current directory. A chat app has messages.
+
+State changes over time. Users click. Servers respond. Timers fire.
+
+## Problem
+
+Coordinating state changes is hard. Callbacks create spaghetti. Shared mutable state causes race conditions. Event emitters become untraceable.
+
+## Solution
+
+The Elm Architecture solves this with **unidirectional data flow**:
+
+1. **Model** — A single source of truth for state
+2. **Update** — A pure function that computes the next state
+3. **View** — A function that renders the model
+
+...
+```
+
+### Guidelines
+
+- **Start with why** — Don't explain what a Command is; explain why Commands exist
+- **Use diagrams** — ASCII or mermaid for data flow
+- **Show bad then good** — Contrast the painful way with the elegant way
+- **Link out to RatatuiRuby** — Don't re-document widgets; link to their guides
+
+---
+
+## Callouts
+
+Use callouts to highlight important information. Standard types:
+
+### Syntax
+
+```markdown
+> **Note**: Background context that's helpful but not critical.
+
+> **Tip**: A shortcut, best practice, or efficiency suggestion.
+
+> **Warning**: Something that could cause confusion or bugs if ignored.
+
+> **Caution**: High-risk actions that could cause data loss or crashes.
+```
+
+### When to Use
+
+| Callout | Use for |
+|---------|---------|
+| **Note** | "By the way..." — Additional context |
+| **Tip** | "Pro tip..." — Efficiency improvements |
+| **Warning** | "Watch out..." — Common mistakes |
+| **Caution** | "Danger..." — Breaking changes, data loss |
+
+---
+
+## Cross-References
+
+Every document should have **3+ cross-references** to related docs.
+
+### Related Topic Links
+
+```markdown
+See [The Elm Architecture](../essentials/the_elm_architecture.md) for background.
+
+For advanced patterns, see [Fractal Architecture](../scaling_up/fractal_architecture.md).
+
+Related: [Commands](commands.md) | [Messages](messages.md) | [The Runtime](the_runtime.md)
+```
+
+### Next/Previous Navigation
+
+Tutorial chapters and sequential docs should end with navigation links:
+
+```markdown
+---
+
+← Previous: [Handling Input](04_handling_input.md) | Next: [Organizing Your Code](06_organizing_your_code.md) →
+```
+
+### Link to RatatuiRuby
+
+Rooibos docs focus on architecture. Link to RatatuiRuby for rendering:
+
+```markdown
+For widget details, see the [RatatuiRuby List docs](https://ratatui-ruby.dev/docs).
+```
+
+---
+
+## Prose Style
+
+Based on Zinsser's *On Writing Well* and Plain Language Guidelines.
+
+### Do
+
+- **Use active voice** — "The runtime dispatches messages" not "Messages are dispatched"
+- **Use short sentences** — One idea per sentence
+- **Address the reader** — "You" not "the developer"
+- **Use imperative mood** — "Create a model" not "You should create a model"
+
+### Avoid
+
+| Avoid | Use instead |
+|-------|-------------|
+| "allows you to" | (just state what happens) |
+| "provides functionality for" | (state what it does) |
+| "in order to" | "to" |
+| "utilize" | "use" |
+| "prior to" | "before" |
+| "You must" / "You need to" | (imperative: "Do X") |
+
+### Examples
+
+**Bad:**
+> The Command module provides functionality that allows the user to perform asynchronous operations.
+
+**Good:**
+> Commands run async work. Use them to fetch data, wait for timers, or perform I/O.
+
+---
+
+## Code Examples
+
+### Format
+
+Use fenced code blocks with language identifier:
+
+    ```ruby
+    Model = Data.define(:count)
+    ```
+
+### Guidelines
+
+- **Complete and runnable** — Every example should work if copy-pasted
+- **Show output** — Include comments showing what prints or renders
+- **Progressive complexity** — Start simple, add complexity gradually
+- **Highlight changes** — When building on previous code, comment new lines
+
+---
+
+## Learning Objectives (Rails Pattern)
+
+Every concept doc starts with learning objectives:
+
+```markdown
+After reading this guide, you will know:
+
+- How to define a Model using `Data.define`
+- Why immutability matters in MVU
+- When to use nested structs vs. flat state
+```
+
+This pattern comes from Rails Guides and sets reader expectations.
+
+---
+
+## Checklist
+
+Before submitting documentation, verify:
+
+- [ ] **Type identified** — Is this a tutorial, concept, or troubleshooting doc?
+- [ ] **Pattern followed** — Does it follow the correct structure for its type?
+- [ ] **Learning objectives** — Does it start with what the reader will learn?
+- [ ] **Cross-references** — Are there 3+ links to related docs?
+- [ ] **Code examples** — Are all examples complete and runnable?
+- [ ] **Prose style** — Active voice? Short sentences? No "allows you to"?
+- [ ] **RatatuiRuby links** — Did you link out for widget/layout details?

data/doc/contributors/e2e_pty.md

@@ -0,0 +1,168 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# End-to-End PTY Testing for TUI Applications
+
+This document explains how to write end-to-end tests for Rooibos TUI applications
+using Ruby's PTY module. These tests verify that `rooibos new` generated apps
+can be launched via `rooibos run` and respond correctly to user input.
+
+## Background
+
+Testing TUI applications is challenging because:
+
+1. **TUI apps require a real terminal** - They use raw mode, escape sequences,
+   and read from the controlling terminal (`/dev/tty`), not just stdin.
+2. **Crossterm reads from the controlling terminal** - Via `isatty()` check on
+   stdin, falling back to `/dev/tty` if stdin isn't a tty.
+3. **Bundler context matters** - Tests running via `bundle exec` inherit that
+   Bundler context, which can interfere with the generated app's own dependencies.
+
+## Key Learnings
+
+### 1. Use `PTY.spawn` for Proper Terminal Emulation
+
+`PTY.spawn` properly establishes a controlling terminal for the child process by:
+- Calling `setsid()` to create a new session
+- Setting the PTY as the controlling terminal via `TIOCSCTTY`
+- Connecting the child's stdin/stdout/stderr to the PTY
+
+```ruby
+require "pty"
+
+# Ruby's PTY.spawn returns [r, w, pid] where:
+# - r = readable IO (receives child's stdout/stderr)
+# - w = writable IO (sends to child's stdin)
+# These are the host's view of the PTY - what the child writes, we read from r;
+# what we write to w, the child reads from stdin.
+pty_out, pty_in, pid = PTY.spawn("rooibos", "run", chdir: app_dir)
+```
+
+### 2. Escape the Parent's Bundler Context
+
+When tests run via `bundle exec`, child processes inherit that Bundler context.
+For generated apps to use their own `Gemfile`, wrap spawning in:
+
+```ruby
+Bundler.with_unbundled_env do
+  pty_out, pty_in, pid = PTY.spawn("rooibos", "run", chdir: app_dir)
+  # ... all PTY interaction must happen inside this block
+end
+```
+
+### 3. Drain the PTY Output Buffer
+
+**Critical**: TUI apps write escape sequences and screen content to stdout.
+If you don't read from the PTY, the buffer fills up and the app blocks waiting
+to write, never reading your input.
+
+Use a background thread to continuously drain output:
+
+```ruby
+reader = Thread.new do
+  loop do
+    pty_out.read_nonblock(4096)
+  rescue IO::WaitReadable
+    pty_out.wait_readable(0.1)
+  rescue EOFError, Errno::EIO
+    break
+  end
+end
+
+# ... send input, wait for exit ...
+
+reader.kill rescue nil
+```
+
+### 5. Set the PTY Window Size
+
+**Critical**: Ruby's `PTY.spawn` creates terminals with 0×0 dimensions by default.
+TUI apps that query terminal size will get zero and may crash (e.g., negative width
+calculations). Set standard 80×24 dimensions after spawning:
+
+```ruby
+require "io/console"
+
+pty_out, pty_in, pid = PTY.spawn("rooibos", "run", chdir: app_dir)
+pty_out.winsize = [24, 80]  # rows, columns
+```
+
+### 6. Send Key Events as Raw Bytes
+
+Ctrl+C is sent as the ETX byte (0x03), not as a signal:
+
+```ruby
+pty_in.sync = true       # Disable buffering
+pty_in.write("\x03")     # ETX = Ctrl+C
+pty_in.flush
+```
+
+Crossterm parses bytes 0x01-0x1A as Ctrl+A through Ctrl+Z:
+
+<!-- SPDX-SnippetBegin -->
+<!-- SPDX-License-Identifier: MIT -->
+<!-- SPDX-SnippetCopyrightText: 2019 Timon -->
+```rust
+// From crossterm/src/event/sys/unix/parse.rs
+c @ b'\x01'..=b'\x1A' => KeyEvent::new(
+    KeyCode::Char((c - 0x1 + b'a') as char),
+    KeyModifiers::CONTROL,
+)
+```
+<!-- SPDX-SnippetEnd -->
+
+### 5. Require Global Gem Installation
+
+Generated apps expect `rooibos` to be installed as a gem. For tests:
+
+```ruby
+def require_global_rooibos!
+  require "rooibos/version"
+  installed = Gem::Specification.find_all_by_name("rooibos", Rooibos::VERSION)
+  if installed.empty?
+    flunk "Rooibos #{Rooibos::VERSION} not installed globally. Run: rake install:force"
+  end
+end
+```
+
+Run `rake install:force` before tests (CI does this automatically).
+
+## Complete Example
+
+See [test/cli/test_new_integration.rb](../../test/cli/test_new_integration.rb),
+specifically the `test_new_app_runs_and_exits_on_ctrl_c` method.
+
+## Common Pitfalls
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| App can't load its own gem | Wrong Bundler context | Use `Bundler.with_unbundled_env` |
+| Test hangs forever | PTY buffer full | Add background reader thread |
+| `LoadError: cannot load such file` | Gem not installed globally | Run `rake install:force` |
+| Ctrl+C doesn't work | Sending SIGINT instead of byte | Write `"\x03"` to PTY |
+| `bundle exec rooibos run` fails | Inherits parent's Bundler | Use global `rooibos` command |
+
+## References
+
+- `ruby/ext/pty/pty.c` - How PTY.spawn sets up the controlling terminal
+- `crossterm/src/event/sys/unix/parse.rs` - How key events are parsed from raw bytes
+- `crossterm/src/terminal/sys/file_descriptor.rs` - How crossterm decides where to read input from
+
+## Want a Helper API?
+
+This pattern isn't currently exposed in `Rooibos::TestHelper` because most
+testing needs are met by `with_test_terminal`. However, reach out if you need
+PTY-based E2E testing regularly, and you would use a helper like the following.
+
+```ruby
+Rooibos::TestHelper.with_pty("rooibos", "run") do |pty_in, pty_out, pid|
+  # ...
+end
+```
+
+If you'd use this, please email the
+[~kerrick/ratatui_ruby-discuss](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)
+mailing list to request it as a feature.

data/doc/contributors/specs/earliest_tutorial_steps_per_story.md

@@ -0,0 +1,70 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+> [!NOTE]
+> This is not *where* each story should go, but
+> *when* the pre-requisites for each story are met.
+
+## FINAL MAPPING RESULTS
+
+### Project Setup
+  - Story -4: Project Setup
+
+### Hello World
+  - Story -3: Hello World + Quit
+
+### Adding State
+  - Story -2: Static File List
+  - Story -1: Arrow Key Navigation
+  - Story 0: Real Files <!-- FAKE DATA STOPS HERE; ALL DATA FETCHING UNTIL COMMANDS IS VIA RUBY STDLIB SYNCHRONOUS CALLS IN UPDATE -->
+  - Story 1: Walking Skeleton - View Current Directory
+  - Story 2: Basic Navigation - Move Through List
+  - Story 3: Enter Directories
+
+### Organizing Your Code
+  - Story 4: Three-Pane Layout
+  - Story 5: File Metadata Display
+  - Story 6: Text File Preview
+  - Story 7: Directory Tree Expansion
+  - Story 8: Pane Focus Switching
+  - Story 9: Sort Files
+  - Story 10: Filter Files by Name
+  - Story 11: Toggle Hidden Files
+  - Story 12: Create New Directory
+  - Story 13: Rename Files and Directories
+
+### Your First Command
+  - Story 14: Delete Files and Directories
+  - Story 15: Copy Files and Directories
+  - Story 16: Move Files and Directories
+  - Story 17: Open in External Editor
+  - Story 18: Help Overlay
+  - Story 19: Error Handling and Messages
+  - Story 20: Mouse Support
+  - Story 21: Terminal Resize Handling
+  - Story 22: Loading States for Large Directories
+  - Story 23: Visual Polish and Theming
+  - Story 24: Performance Optimization
+
+### The Preview Pane
+  (No stories)
+
+### Loading States
+  (No stories)
+
+### Testing Your App
+  - Story 25: Comprehensive Test Coverage
+  - Story 26: Configurable Color Schemes
+  - Story 27: Configuration Management
+
+### Polish and Refine
+  (No stories)
+
+### Going Further
+  (No stories)
+
+### Tutorial: Build a File Browser
+  (No stories)