tuby 0.0.1.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5064c98e34924df24734220ff31d11a71e23fb3c932be3a44b245ef2d60571f2
+  data.tar.gz: 0e95b5507d0446e1aea9efdee95298f992982439b70c747a5687951cb9781b7b
+SHA512:
+  metadata.gz: fdde892756e75e3e3f02eaca088d0560489f164554117bad4cc515e27974edb6b5fccb6269026175d1fcd084e3fcb16e5dc7bf440f3c1764aba6999d0d97c38f
+  data.tar.gz: a50985362c41df5cceecce1860621cb323d8bd4f3c0df3441c879d72f759578989c24e8fc004be05bc4e698f55e19fdb61d89ce79fa4413ce2f4782b0acd71ac

data/README.md

@@ -0,0 +1,206 @@
+# tuby
+
+> Proof-of-concept Ruby bindings for the [ratatui](https://ratatui.rs) Rust TUI
+> library, using the `ffi` gem over a hand-written C ABI (Approach A). Not
+> published to rubygems.org — source-only install from git.
+
+**Status:** POC complete. The demo passes all eight spec §9 acceptance items,
+the test suite is green, the architecture held up under end-to-end execution.
+See [`docs/superpowers/specs/2026-04-11-tuby-design.md`](docs/superpowers/specs/2026-04-11-tuby-design.md)
+for the full design, decisions log, and scope. See
+[`docs/superpowers/plans/2026-04-11-tuby-poc.md`](docs/superpowers/plans/2026-04-11-tuby-poc.md)
+for the 18-task implementation plan that actually built it (+ the 10 plan bugs
+caught and logged during execution).
+
+## Quickstart
+
+```sh
+git clone <this-repo> tuby
+cd tuby
+bin/setup              # bundle install && cargo build --release
+bundle exec ruby demo/hello.rb
+```
+
+Press `q` or `Ctrl-C` to quit. Press `?` for the help overlay. Press `Tab` to
+cycle the outer border style. Resize the terminal and watch the layout reflow
+(the "keys pressed" list cap auto-adjusts to the available height).
+
+## What's inside
+
+- `lib/tuby/` — the Ruby gem
+  - Tier 1: `Tuby::Terminal` — 1:1 wrapper around the Rust FFI (lifecycle,
+    `begin_frame`/`end_frame`, `split`, `push_block`/`push_paragraph`/
+    `push_list`/`push_clear`, `poll_event`, `close`)
+  - Tier 2: `Tuby::Frame` + `Tuby.run` — ~80 lines of pure Ruby sugar on top
+    of Tier 1 (convenience shortcuts, centered rects, lifecycle + signal
+    handling + main-loop + `catch(:tuby_quit)` exit)
+- `ext/tuby/` — the Rust `cdylib` crate (ratatui 0.30 + crossterm 0.29),
+  17 `extern "C"` functions
+- `demo/hello.rb` — feature-rich acceptance demo exercising every Tier 1/2
+  primitive in one screen
+- `test/` — minitest suite (26 runs, 160 assertions): smoke, errors, rect/
+  event, terminal lifecycle, layout, events, thread safety
+- `docs/superpowers/` — the design spec and implementation plan that shaped
+  every decision; the plan has ~10 in-place fixes documenting bugs caught at
+  execution time
+
+## Running tests
+
+```sh
+bundle exec rake test
+```
+
+All tests use a headless ratatui `TestBackend`, so they work in CI without a
+TTY. Visual correctness of rendered output is validated by running the demo
+and walking the eight-item checklist in spec §9.
+
+## Threading
+
+- A single `Tuby::Terminal` is safe to share across Ruby threads; every FFI
+  entry point takes a Rust-side `Mutex<TerminalInner>` before touching state.
+- `Tuby::Terminal#poll_event` releases the GVL during its timeout
+  (`blocking: true` on the FFI attach), so worker threads make progress while
+  you wait for input instead of freezing the entire VM.
+- `Tuby::Terminal` is **not** shareable across Ractors.
+- If a render call raises `Tuby::PanicError`, the Rust side has caught a panic
+  and stored its message in the thread-local last-error slot. The terminal is
+  effectively dead — rescue, `close`, and construct a new one.
+
+## POC retrospective
+
+### What was painful
+
+**Plan bugs surfaced at execution time, not at write time.** The plan was
+carefully written but ten things were wrong with it across the 18 tasks, and
+each one only became visible when a subagent actually executed the code. See
+`docs/superpowers/plans/2026-04-11-tuby-poc.md` for the in-place fixes and the
+plan-fixes memory log for the sequential bug numbers. Examples: `ffi_lib` with
+an absolute path doesn't auto-append `.so` (bug 2); `Buffer::get` was
+deprecated in ratatui 0.30 between plan writing and execution (bug 8);
+`FFI::Pointer#read_string` silently returns ASCII-8BIT, breaking UTF-8 regex
+matching (bug 8 companion); crossterm normalizes Ctrl-C to `Char('c') +
+CONTROL` (code 99), not raw ETX (code 3), so the plan's synthesis branch was
+dead code (bug 9); Ruby's `ObjectSpace.define_finalizer` warns when the proc
+closes over the finalized object, which is exactly what the plan's
+boilerplate did (bug 10). None of these would have been caught by
+paper-review.
+
+**Encoding at the FFI boundary is a persistent tax.** Every byte-oriented
+buffer that crosses the boundary has to be `.force_encoding(Encoding::UTF_8)`
+on the Ruby side and UTF-8 validated on the Rust side. Both directions.
+Missing a single one is invisible until a non-ASCII character shows up and
+the whole chain stops working.
+
+**ratatui widget semantics around "clearing cells."** Block, Paragraph, and
+List widgets only paint cells they write to — they do NOT clear the interior
+of their rect. Every floating overlay leaks whatever was underneath. This
+wasn't mentioned anywhere in the plan and only showed up when the help
+overlay in the demo was drawn on top of the split_h divider. The fix was
+adding an explicit `push_clear` primitive backed by ratatui's `Clear` widget
+— small change, but a whole new variant + FFI function + Ruby wrapper +
+regression test landed after the plan was otherwise complete.
+
+### What was surprising
+
+**The architecture held.** Every decision from the spec paid off during
+execution, and nothing needed to be refactored mid-build:
+
+- `Mutex<TerminalInner>` in Task 6 made thread safety in Task 13 a one-line
+  `blocking: true` flag change instead of a cross-cutting retrofit.
+- The headless-first order (Task 6 ships `new_headless` before Task 14 ships
+  `new`) meant every render task could be tested in CI without ever needing
+  a TTY. 24 of 26 tests run headless; only the two thread-safety tests care
+  about wall-clock timing.
+- The command-buffer pattern (Task 7 scaffolds, Tasks 9–11 add one variant
+  each, Task "17-ish" adds Clear late) kept each widget addition to a tiny,
+  isolated diff. Every `push_*` function is structurally identical.
+- The `TerminalBackend` enum's `Crossterm` variant, left as a commented-out
+  placeholder in Task 6, meant Task 14 was just "fill in the blank" — no
+  invasive changes to the 12 sites that already `match`-ed on the enum.
+
+**Ruby-FFI was less painful than expected.** `attach_function` with
+`FFI.map_library_name` + absolute path is reliable on Linux. `FFI::Struct`
+layouts match `#[repr(C)]` byte-for-byte when you use an explicit `_pad`
+field for alignment. The `blocking: true` option Just Worked on the first
+try for GVL release. The main foot-gun was the `read_string` encoding
+default (see above).
+
+**Subagent-driven execution caught plan bugs one at a time.** The
+controller-subagent workflow forced each task to be self-contained: dispatch
+an implementer, run tests, dispatch a reviewer for complex tasks, fix plan
+bugs in-place, commit separately, continue. No bug survived more than one
+task before being written up. The 10 plan bugs are all numbered and
+documented in auto-memory, which means the next time someone writes a
+Ruby+Rust gem plan, they can pre-apply the lessons.
+
+**Test-assertion count ballooned from one test.** The suite has 26 runs
+(atomic tests) but 160 assertions because `test_poll_event_releases_gvl`
+alone contributes 100 `assert_same` calls in a loop and the concurrent-push
+test contributes ~800 implicit assertions through `Thread#join` under a
+timeout. The ratio is a signal that the thread-safety tests are exercising
+the FFI layer heavily even though they look small in the test file.
+
+### What's the blocker if we want to take this beyond a POC
+
+**No styling.** Every visual is monochrome. Adding colors, bold, italic,
+reverse-video, etc. means marshalling ratatui's `Style` struct across FFI.
+The struct has ~10 fields (`fg`, `bg`, `modifier` bitmask, underline color,
+underline style, etc.). The current "flat parameters" FFI pattern
+(`push_paragraph` already has 10 args) scales badly. Options: (a) `Style`
+as an `FFI::Struct` mirror, consistent with how `TubyEvent` works —
+probably the cleanest; (b) pre-register palette IDs and pass a u8 index
+per widget — faster but less flexible; (c) styled text runs (tagged string
+markup parsed on the Rust side) — most ergonomic for end users but
+complicates the `text` parameter of every widget.
+
+**Three widgets is not enough.** ratatui ships 15+ widgets: Gauge, Chart,
+Table, Tabs, Canvas, Scrollbar, Sparkline, BarChart, LineGauge, Calendar,
+…. Each is ~1 new `RenderCmd` variant + 1 new `tuby_push_*` FFI function
++ 1 new Ruby wrapper + 1 round-trip test. Mechanical but scales linearly
+— and adding stateful widgets (the `List::state` / `ListState::select`
+machinery for selection + scroll position) requires the command buffer to
+carry state, not just one-shot config, which is a bigger architectural
+change.
+
+**No mouse events.** `TubyEvent` reserves `kind=3` for mouse but no
+`encode_mouse` exists. crossterm supports it fully; this is a one-evening
+add. Until then, any mouse-driven UI is out.
+
+**Source-only install is a ceiling on adoption.** Every user has to have a
+Rust toolchain available at install time. `rake-compiler-dock` +
+pre-built `.so` per platform would fix it, but that's a build-infra
+project unto itself (Linux/macOS/Windows × x86_64/aarch64 = 6 artifacts,
+plus a CI matrix and a release workflow).
+
+**ratatui stability is not a given.** We already hit a 0.29→0.30 API drift
+mid-execution (Buffer::get deprecation). ratatui has had breaking changes
+every ~6 months in its 0.2x line. A production gem would need either a
+strict version pin (and a bump cycle every release) or a compat shim layer.
+
+### Go / no-go
+
+**Go, with caveats.** The POC proves the architecture is sound, the
+ergonomics are acceptable, the performance is adequate (160 assertions in
+<0.2s on headless, real-terminal demo feels instant), and the subagent
+workflow can execute a plan this size end-to-end with high quality. The
+ten plan bugs were all caught cheaply and fixed in place; none of them
+indicated a structural problem.
+
+**But** turning this into a v0.2 gem that people would actually use
+requires three substantial efforts before anything else:
+
+1. **Styling** (FFI::Struct-based Style marshalling) — 1–2 sessions
+2. **At least 6 more widgets** with a stateful-widget story for
+   List/Table selection — 2–3 sessions
+3. **Release infra** (rake-compiler-dock, CI matrix, pre-built artifacts)
+   — 1–2 sessions
+
+After those, the gem is viable. Before those, it's a demo. Whether to
+commit the time depends on whether there's a real user with a real Ruby
+TUI need — which is a niche audience today (most people reach for TUI
+work in Go or Rust directly). The POC was worth building; the production
+gem is conditional on finding a concrete user story.
+
+## License
+
+MIT

data/ext/tuby/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name    = "tuby_core"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name       = "tuby_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+ratatui   = "0.30"
+crossterm = "0.29"

data/ext/tuby/src/errors.rs

@@ -0,0 +1,77 @@
+use std::cell::RefCell;
+use std::ffi::{c_char, CString};
+use std::os::raw::c_int;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+
+thread_local! {
+    static LAST_ERROR: RefCell<Option<CString>> = const { RefCell::new(None) };
+}
+
+/// Store a message in the thread-local error slot. The next call to
+/// `tuby_last_error()` on this thread will return a pointer to it.
+pub fn set_last_error<S: Into<String>>(msg: S) {
+    let msg = msg.into();
+    let cstring = CString::new(msg).unwrap_or_else(|_| {
+        CString::new("tuby internal: error message contained NUL byte").unwrap()
+    });
+    LAST_ERROR.with(|slot| *slot.borrow_mut() = Some(cstring));
+}
+
+/// Wrapper used by every extern "C" function. Runs `f` inside `catch_unwind`
+/// so panics become return code -2 instead of undefined behavior across the
+/// C ABI boundary. Ordinary errors are returned as Err(String) from `f` and
+/// become return code -1.
+///
+/// Return codes:
+///   0  success
+///   -1 ordinary error (`Err(msg)` from `f`); message in last_error
+///   -2 panic caught; payload in last_error prefixed with "panic: "
+///
+/// The closure is wrapped internally in `AssertUnwindSafe`, so callers do not
+/// need to prove unwind-safety themselves. This is safe because of the
+/// architectural stance in spec §5: after a caught panic, the terminal is
+/// considered dead and the library is not expected to be reused — so the
+/// "observer of broken invariants" concern that `UnwindSafe` exists to flag
+/// is moot in practice.
+#[must_use = "catch_ffi's return code must be forwarded to the C caller to signal success/failure"]
+pub fn catch_ffi<F>(f: F) -> c_int
+where
+    F: FnOnce() -> Result<(), String>,
+{
+    match catch_unwind(AssertUnwindSafe(f)) {
+        Ok(Ok(())) => 0,
+        Ok(Err(msg)) => {
+            set_last_error(msg);
+            -1
+        }
+        Err(payload) => {
+            let msg = panic_payload_to_string(payload);
+            set_last_error(format!("panic: {msg}"));
+            -2
+        }
+    }
+}
+
+pub(crate) fn panic_payload_to_string(payload: Box<dyn std::any::Any + Send>) -> String {
+    if let Some(s) = payload.downcast_ref::<&'static str>() {
+        (*s).to_string()
+    } else if let Some(s) = payload.downcast_ref::<String>() {
+        s.clone()
+    } else {
+        "unknown panic payload".to_string()
+    }
+}
+
+/// Return a pointer to the current thread's last error message, or a pointer
+/// to an empty NUL-terminated string if none is set. The returned pointer is
+/// valid until the next call on this thread that writes to the error slot.
+#[no_mangle]
+pub extern "C" fn tuby_last_error() -> *const c_char {
+    LAST_ERROR.with(|slot| match &*slot.borrow() {
+        Some(cstring) => cstring.as_ptr(),
+        None => {
+            static EMPTY: &[u8] = b"\0";
+            EMPTY.as_ptr() as *const c_char
+        }
+    })
+}

data/ext/tuby/src/events.rs

@@ -0,0 +1,123 @@
+use crate::errors::catch_ffi;
+use crate::terminal::{TerminalBackend, TubyTerminal};
+use crossterm::event::{self, Event as CEvent, KeyCode, KeyModifiers};
+use std::os::raw::c_int;
+use std::time::Duration;
+
+/// POD struct that Ruby pre-allocates and Rust fills in.
+/// Layout matches the Ruby-side FFI::Struct declaration in ffi_bindings.rb.
+#[repr(C)]
+pub struct TubyEvent {
+    pub kind:        u8,  // 0=none 1=key 2=resize 3=mouse(unused) 4=other
+    pub key_code:    u8,  // ASCII char OR special-key sentinel >= 128
+    pub key_mods:    u8,  // bitflags: 1=ctrl, 2=alt, 4=shift
+    pub _pad:        u8,
+    pub resize_cols: u16,
+    pub resize_rows: u16,
+}
+
+pub const K_ENTER:     u8 = 128;
+pub const K_ESC:       u8 = 129;
+pub const K_BACKSPACE: u8 = 130;
+pub const K_TAB:       u8 = 131;
+pub const K_LEFT:      u8 = 132;
+pub const K_RIGHT:     u8 = 133;
+pub const K_UP:        u8 = 134;
+pub const K_DOWN:      u8 = 135;
+pub const K_HOME:      u8 = 136;
+pub const K_END:       u8 = 137;
+pub const K_PAGEUP:    u8 = 138;
+pub const K_PAGEDOWN:  u8 = 139;
+pub const K_INSERT:    u8 = 140;
+pub const K_DELETE:    u8 = 141;
+pub const K_F1:        u8 = 150;
+pub const K_OTHER:     u8 = 200;
+
+#[no_mangle]
+pub extern "C" fn tuby_poll_event(
+    term:       *mut TubyTerminal,
+    timeout_ms: u32,
+    out:        *mut TubyEvent,
+) -> c_int {
+    catch_ffi(|| {
+        let term = unsafe { term.as_mut().ok_or_else(|| "null terminal pointer".to_string())? };
+        if out.is_null() {
+            return Err("null out pointer".to_string());
+        }
+
+        // Headless backends have no stdin — always return "no event" cleanly.
+        {
+            let state = term.inner.lock().map_err(|_| "mutex poisoned".to_string())?;
+            if matches!(state.backend, TerminalBackend::Headless(_)) {
+                write_none(out);
+                return Ok(());
+            }
+        }
+
+        let ready = event::poll(Duration::from_millis(timeout_ms as u64))
+            .map_err(|e| format!("event::poll failed: {e}"))?;
+        if !ready {
+            write_none(out);
+            return Ok(());
+        }
+
+        let ev = event::read().map_err(|e| format!("event::read failed: {e}"))?;
+        unsafe {
+            match ev {
+                CEvent::Key(k) => {
+                    let (code, flags) = encode_key(k.code, k.modifiers);
+                    (*out).kind     = 1;
+                    (*out).key_code = code;
+                    (*out).key_mods = flags;
+                }
+                CEvent::Resize(cols, rows) => {
+                    (*out).kind        = 2;
+                    (*out).resize_cols = cols;
+                    (*out).resize_rows = rows;
+                }
+                _ => {
+                    (*out).kind = 4;
+                }
+            }
+        }
+        Ok(())
+    })
+}
+
+fn write_none(out: *mut TubyEvent) {
+    unsafe {
+        (*out).kind        = 0;
+        (*out).key_code    = 0;
+        (*out).key_mods    = 0;
+        (*out)._pad        = 0;
+        (*out).resize_cols = 0;
+        (*out).resize_rows = 0;
+    }
+}
+
+fn encode_key(code: KeyCode, mods: KeyModifiers) -> (u8, u8) {
+    let c = match code {
+        KeyCode::Char(ch) if (ch as u32) < 128 => ch as u8,
+        KeyCode::Enter     => K_ENTER,
+        KeyCode::Esc       => K_ESC,
+        KeyCode::Backspace => K_BACKSPACE,
+        KeyCode::Tab       => K_TAB,
+        KeyCode::Left      => K_LEFT,
+        KeyCode::Right     => K_RIGHT,
+        KeyCode::Up        => K_UP,
+        KeyCode::Down      => K_DOWN,
+        KeyCode::Home      => K_HOME,
+        KeyCode::End       => K_END,
+        KeyCode::PageUp    => K_PAGEUP,
+        KeyCode::PageDown  => K_PAGEDOWN,
+        KeyCode::Insert    => K_INSERT,
+        KeyCode::Delete    => K_DELETE,
+        KeyCode::F(n) if (1..=12).contains(&n) => K_F1 + (n - 1),
+        _ => K_OTHER,
+    };
+    let mut flags = 0u8;
+    if mods.contains(KeyModifiers::CONTROL) { flags |= 1; }
+    if mods.contains(KeyModifiers::ALT)     { flags |= 2; }
+    if mods.contains(KeyModifiers::SHIFT)   { flags |= 4; }
+    (c, flags)
+}

data/ext/tuby/src/lib.rs

@@ -0,0 +1,49 @@
+use std::ffi::{c_char, CString};
+use std::os::raw::c_int;
+use std::sync::OnceLock;
+
+mod errors;
+mod events;
+mod render;
+mod terminal;
+
+use crate::errors::{catch_ffi, set_last_error};
+pub use errors::tuby_last_error;
+pub use events::tuby_poll_event;
+pub use terminal::{
+    tuby_begin_frame, tuby_end_frame, tuby_headless_buffer_snapshot,
+    tuby_push_block, tuby_push_clear, tuby_push_list, tuby_push_paragraph,
+    tuby_split, tuby_string_free, tuby_terminal_free, tuby_terminal_new,
+    tuby_terminal_new_headless, tuby_terminal_size,
+};
+
+/// Returns a pointer to a NUL-terminated version string owned by the library.
+/// The returned pointer is valid for the lifetime of the process — it is backed
+/// by a `OnceLock<CString>`, so the `CString` is never dropped.
+#[no_mangle]
+pub extern "C" fn tuby_version() -> *const c_char {
+    static VERSION: OnceLock<CString> = OnceLock::new();
+    VERSION
+        .get_or_init(|| CString::new(env!("CARGO_PKG_VERSION")).unwrap())
+        .as_ptr()
+}
+
+/// Test-only helper. Populates the last-error slot with a synthetic message.
+/// - kind = -1: ordinary error via catch_ffi Err path
+/// - kind = -2: triggers a panic inside catch_ffi
+/// Any other value is a no-op returning 0.
+#[no_mangle]
+pub extern "C" fn tuby_force_error(kind: c_int) -> c_int {
+    match kind {
+        -1 => {
+            // Manually stage the error without going through catch_ffi, because
+            // the test wants to observe the thread-local *after* the call.
+            set_last_error("forced error from test helper");
+            -1
+        }
+        -2 => catch_ffi(|| {
+            panic!("forced panic from test helper");
+        }),
+        _ => 0,
+    }
+}

data/ext/tuby/src/render.rs

@@ -0,0 +1,80 @@
+use ratatui::{
+    layout::Rect as RRect,
+    widgets::{Block, BorderType, Borders, Clear, List, ListItem, Paragraph},
+    Frame,
+};
+
+#[derive(Debug)]
+pub enum RenderCmd {
+    Block {
+        rect:   RRect,
+        border: u8,
+        title:  Option<String>,
+    },
+    Paragraph {
+        rect:   RRect,
+        text:   String,
+        border: u8,
+        title:  Option<String>,
+    },
+    List {
+        rect:   RRect,
+        items:  Vec<String>,
+        border: u8,
+        title:  Option<String>,
+    },
+    /// Fill the given rect with blank cells. Use before drawing a floating
+    /// overlay so background content (border lines from underlying panels,
+    /// previous-frame ghosts) doesn't bleed through — ratatui's Paragraph/
+    /// Block widgets do NOT clear cells they don't explicitly write to.
+    Clear {
+        rect: RRect,
+    },
+}
+
+pub fn replay(cmds: &[RenderCmd], frame: &mut Frame) {
+    for cmd in cmds {
+        match cmd {
+            RenderCmd::Block { rect, border, title } => {
+                let b = build_block(*border, title.as_deref());
+                frame.render_widget(b, *rect);
+            }
+            RenderCmd::Paragraph { rect, text, border, title } => {
+                let mut p = Paragraph::new(text.as_str());
+                if *border != 0 || title.is_some() {
+                    p = p.block(build_block(*border, title.as_deref()));
+                }
+                frame.render_widget(p, *rect);
+            }
+            RenderCmd::List { rect, items, border, title } => {
+                let list_items: Vec<ListItem> = items
+                    .iter()
+                    .map(|s| ListItem::new(s.as_str()))
+                    .collect();
+                let mut list = List::new(list_items);
+                if *border != 0 || title.is_some() {
+                    list = list.block(build_block(*border, title.as_deref()));
+                }
+                frame.render_widget(list, *rect);
+            }
+            RenderCmd::Clear { rect } => {
+                frame.render_widget(Clear, *rect);
+            }
+        }
+    }
+}
+
+fn build_block(border: u8, title: Option<&str>) -> Block<'_> {
+    let mut b = Block::default();
+    if border != 0 {
+        b = b.borders(Borders::ALL).border_type(match border {
+            2 => BorderType::Rounded,
+            3 => BorderType::Double,
+            _ => BorderType::Plain,
+        });
+    }
+    if let Some(t) = title {
+        b = b.title(t);
+    }
+    b
+}