Skip to content
Back to search

r3bl-open-core

TUI framework and developer productivity apps in Rust πŸ¦€

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/r3bl-org/r3bl-open-core with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/r3bl-org/r3bl-open-core'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/r3bl-org--r3bl-open-core/badge.svg)](/listings/r3bl-org--r3bl-open-core)

HTML

<a href="/listings/r3bl-org--r3bl-open-core"><img src="/api/listings/r3bl-org--r3bl-open-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Automated Setup (Recommended)

Use the bootstrap script to automatically install all required tools:

# Clone the repository
git clone https://github.com/r3bl-org/r3bl-open-core.git
cd r3bl-open-core

# Run the bootstrap script
./bootstrap.sh

The [`bootstrap.sh`] script handles **OS-level setup** with a clean main function structure and will:

- **Cross-Platform Support**: Works on **macOS** (Homebrew) and **Linux** including Ubuntu (apt), Fedora (dnf), Arch (pacman), openSUSE (zypper), and Alpine (apk) - **Core Rust Installation**: Install Rust toolchain (`rustup`) and ensure `cargo` is in `PATH` - **Development Shell**: Install `Fish` shell and `fzf` for interactive development - **File Watching**: Install file watchers (`inotifywait` on Linux, `fswatch` on macOS) - **Development Utilities**: Install `htop`, `screen`, `tmux` for system monitoring - **Node.js Ecosystem**: Install [`Node.js`] and `npm` (for Markdown formatting via Prettier and local documentation serving) - **AI (LLM) Integration (Optional)**: If you choose to use an AI coding agent, the repo supports `Antigravity CLI` (`agy`), or any tool of your choice - **Rust Development Tools Setup**: Call `fish run.fish install-cargo-tools` for all Rust-specific `cargo` tooling

**Architecture**: Uses clear function separation with `main()` orchestrator and dedicated functions for each concern (`install_rustup`, `install_clang`, `install_shell_tools`, etc.)

Manual Setup

If you prefer manual installation or are on Windows:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install `fish`, `fzf`, `nodejs`, and `npm` (via package manager)
# Ubuntu/Debian: sudo apt install fish fzf nodejs npm
# macOS: brew install fish fzf node
# Or run `./bootstrap.sh` for automatic detection

# Install Rust development tools (after OS dependencies)
fish run.fish install-cargo-tools

**Note**: The manual approach requires you to install OS-level dependencies yourself. The `install-cargo-tools` command focuses specifically on **Rust development tools**:

**From crates.io (via cargo-binstall with fallback to cargo install):**

- **`cargo-binstall`**: Fast binary installer (installed first as foundation) - **Core Development Tools**: `bacon`, `flamegraph`, `inferno` - **Workspace Management**: `cargo-workspaces`, `cargo-cache`, `cargo-update` - **Code Quality & Link Checking**: `cargo-deny`, `cargo-unmaintained`, `cargo-expand`, `cargo-readme`, `lychee` - **Language Server Components**: `rust-analyzer` component, `rust-src`

**From local source (via `cargo install --path`):**

- **cmdr**: `edi`, `giti`, `rc`, `env-source` binaries (calls `run.fish install-cmdr`) - **build-infra**: `cargo-rustdoc-fmt` (calls `run.fish install-build-infra`) - **rust-analyzer-mcp-server**: `rust-analyzer-mcp-server` MCP binary (calls `run.fish install-rust-analyzer-mcp-server`)

**Features:**

- **Smart Installation**: Uses `cargo-binstall` for speed with fallback to `cargo install --locked` - **Local Source Rebuild**: Always rebuilds `cmdr`, `build-infra`, and `rust-analyzer-mcp-server` from source with current toolchain - **Shared Utilities**: Leverages utility functions from `script_lib.fish` for consistency

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,928 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # r3bl-open-core
  2. <!--
  3. <img
  4. src="https://raw.githubusercontent.com/r3bl-org/r3bl-open-core/main/r3bl-term.svg?raw=true"
  5. height="256px">
  6. -->
  7. <!-- R3BL TUI library & suite of apps focused on developer productivity -->
  8. <!-- prettier-ignore-start -->
  9. ```text
  10. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•— β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
  11. β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•”β•β•β•β•β•
  12. β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘
  13. β–ˆβ–ˆβ•”β•β•β–ˆβ–ˆβ•—β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β–ˆβ–ˆβ•‘
  14. β–ˆβ–ˆβ•‘ β–ˆβ–ˆβ•‘β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•”β•β•šβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ•—
  15. β•šβ•β• β•šβ•β• β•šβ•β•β•β•β•β• β•šβ•β•β•β•β•β•
  16. ```
  17. <!-- prettier-ignore-end -->
  18. <p align="left">
  19. <a href="https://crates.io/crates/r3bl_tui"><img src="https://img.shields.io/badge/crates.io-2.7M%2B%20downloads-orange?logo=rust&style=flat-square" alt="Crates.io Total Downloads"></a>
  20. </p>
  21. ## Modernizing the Terminal: Taking Inspiration From Web and Desktop Apps
  22. Despite the massive rise of AI/LLM coding agents & execution harnesses and cloud VM
  23. administration over SSH, terminal UI innovation has largely stagnated since the 1970s.
  24. Most CLI tools still rely on blocking single-threaded I/O, [`curses`]-era APIs, and
  25. fragile platform hacks - or rely on the heavy, fragile workaround of layering web stacks
  26. like [`Node.js`], [`React`], and [`ink`] onto the console. This introduces unreasonable
  27. memory bloat, high latency, broken keyboard shortcuts, and unpredictable instability that
  28. breaks down during long-horizon agentic workflows and sub-process orchestration.
  29. **ROC (`r3bl-open-core`) moves the terminal forward (with love & respect) into 2026 and
  30. beyond. ❀️**
  31. R3BL brings modern web and desktop app design patterns to the terminal, turning it into a
  32. place of focused productivity to build delightful, ergonomic, and rich text user interface
  33. (TUI) experiences.
  34. Representing years of systems programming, performance optimization, and production-grade
  35. infrastructure design in Rust, R3BL re-imagines the terminal for the modern era - making
  36. rich, reactive TUI applications accessible over SSH to any terminal emulator across Linux,
  37. macOS, Windows, and Unix/BSDs (such as FreeBSD).
  38. R3BL TUI is fundamentally different from [`vim`], [`neovim`], and [`ratatui`] through its
  39. immediate mode reactive UI, clean separation between rendering and state mutation, and
  40. purely async architecture - it never blocks the main thread, and natively embraces
  41. multithreaded execution and multi-process orchestration.
  42. ### Primary Use Cases
  43. ROC is designed to power four primary use cases:
  44. - πŸ€– **AI/LLM Coding Agents & Execution Harnesses**: Building fast, interactive terminal
  45. interfaces and execution harnesses for AI/LLM coding agents in pure Rust. While popular
  46. agent tools are written in [`Node.js`] and [`ink`] (see [origin story]), Node-based
  47. runtimes struggle with runaway memory consumption, fragile sub-process control, and
  48. unstable PTY session management when orchestrating heavy, long-running tools in
  49. sandboxed environments (containers, microVMs, systemd-nspawn machines, etc.).
  50. Furthermore, Node-based runtimes struggle with terminal input decoding, frequently
  51. dropping modifier keys, mangling keyboard chords, and introducing sluggish ESC key
  52. disambiguation lag. ROC provides a rock-solid, pure Rust foundation engineered for
  53. native PTY orchestration, zero-latency ANSI input decoding, deterministic process
  54. lifecycles, flicker-free diff rendering, and minimal resource overhead.
  55. - ☁️ **DevOps & Cloud Workflows**: Administering modern cloud infrastructure shouldn't
  56. feel like using stone-age tools to build a satellite. Juggling remote VMs, containers,
  57. and multi-process server environments through bare terminal sessions is slow and
  58. error-prone. ROC transforms terminal workflows into a rich, responsive workspace with
  59. in-memory virtual terminal emulation, virtual tabs, 2D horizontal panning across wide
  60. logs, and double-buffered diff rendering that stays lag-free even over high-latency SSH
  61. connections.
  62. - πŸ“ **Interactive Document & Markdown Workflows**: Rich interactive editing, syntax
  63. highlighting, and real-time code block execution directly inside Markdown documents in
  64. the terminal, bridging documentation directly with live operations.
  65. - πŸ› οΈ **Developer Productivity Infrastructure**: High-efficiency developer tooling and
  66. composable terminal infrastructure to enhance knowledge capture, eliminate friction, and
  67. streamline everyday command-line workflows.
  68. The framework supports the full spectrum from CLI to inline dialogs to full-screen TUI and
  69. terminal multiplexing experiences with deep systems integration.
  70. ### ROC Workspace Architecture: Core Engine, Productivity Apps & Build Tools
  71. With over 2.7M downloads across crates.io, ROC (`r3bl-open-core`) provides
  72. production-grade systems infrastructure across five specialized crates:
  73. | Crate | Purpose |
  74. | :------------------------------------ | :---------------------------------------------------------------------------- |
  75. | **[`r3bl_tui`]** | Core foundational async TUI engine, reactive runtime & PTY primitives |
  76. | **[`r3bl-cmdr`]** | Suite of productivity apps (`giti`, `edi`, `env-source`) |
  77. | **[`r3bl-build-infra`]** | Developer infrastructure & build tools (`cargo-rustdoc-fmt`, `spawny`) |
  78. | **[`r3bl-rust-analyzer-mcp-server`]** | High-performance std-thread rust-analyzer MCP server for coding agents & IDEs |
  79. | **[`r3bl_analytics_schema`]** | Shared schema for privacy-first analytics & upgrade checks |
  80. ### Built-from-Scratch Primitives: The Four Pillars of `r3bl_tui`
  81. At the heart of ROC is **`r3bl_tui`**, which provides four foundational interaction
  82. primitives designed from the ground up in pure Rust:
  83. 1. πŸ“Ÿ **CLI & REPLs (`readline_async`)**: Unlike GNU [`readline`] which is single-threaded
  84. and blocking, our implementation is fully async, interruptable, and non-blocking,
  85. allowing background spinners and tasks to print concurrently without pausing line
  86. editing or blocking your main thread.
  87. 2. πŸ“‘ **Inline / Partial TUI (`choose`)**: Single-shot interactive multi-select dialogs
  88. that enter raw mode and render inline in terminal scrollback without taking over the
  89. screen or disrupting the back buffer (similar to `fzf` in spirit).
  90. 3. πŸ–₯️ **Full-Screen TUI**: Complete raw mode with alternate screen support, fully async
  91. and panic-safe terminal restoration. Build [React] and [Elm] inspired apps with
  92. [unidirectional data flow], [responsive] [flexbox] layouts, [declarative] [CSS-like]
  93. styling, reactive state architecture, reusable modal dialogs with asynchronous
  94. autocomplete, and a full-featured Markdown editor component with custom parser, custom
  95. syntax highlighter, and fast zero-copy gap buffer.
  96. 4. πŸ”€ **Terminal Multiplexing & PTY**: In-memory virtual terminals, virtual terminal tabs,
  97. deterministic process orchestration, and multiplexing primitives (build your own
  98. [`tmux`] or sandboxed AI/LLM coding agent execution harness) featuring 2D horizontal
  99. viewport panning and decoupled throughput.
  100. **Power via Composition**: Designed to be [loosely coupled and strongly coherent], you can
  101. pick and choose only what you need or compose them seamlessly within a single application.
  102. Transition smoothly from a non-blocking `readline_async` prompt into an inline `choose`
  103. menu, launch a full-screen TUI for complex tasks, or orchestrate background PTY
  104. subprocesses, all sharing application state without process restarts.
  105. ### Automated Headless Testing & Benchmarking
  106. The entire framework across all 4 pillars is testable across Linux, macOS, and Windows.
  107. Powered by our own PTY pillar, real production code runs headlessly in an isolated virtual
  108. terminal environment, enabling end-to-end testing of interactive apps without requiring
  109. human interaction:
  110. - **PTY Automated Interactive Testing**: Enables end-to-end testing of interactive apps
  111. via headless PTY subprocess orchestration with the `generate_pty_test!` macro. Automate
  112. key sequences, window resizing, and screen output verification in completely isolated
  113. child processes without someone having to sit and manually type at a keyboard.
  114. - **Visual UI Snapshot Testing**: Everything renders to an offscreen buffer (`OfsBuf`),
  115. providing built-in visual snapshot testing. Easily diff and assert the actual rendered
  116. terminal screen state headlessly generated in a real PTY environment.
  117. - **Sans-IO In-Memory Terminal**: Pure functional VT-100 parser verifying virtual terminal
  118. screen buffers directly in RAM with zero OS syscalls.
  119. - **Decoupled I/O Devices**: `InputDevice` and `OutputDevice` abstract terminal I/O away
  120. from physical `stdin` and `stdout`, allowing input events and output streams to be
  121. driven and inspected directly in tests without taking over your terminal.
  122. - **Empirical Benchmarking & Flamegraph Profiling**: Continuous performance measurement
  123. via Rust's built-in benchmarking suites and automated flamegraph profiling against
  124. established baselines rather than guesswork.
  125. ### Engineered for Performance, Correctness & Reliability
  126. - πŸ“ **Zero-Cost Type-Proof Architecture & Mathematical Correctness**: Rather than relying
  127. on ambiguous primitive integers (`usize`, `u16`) and runtime assertions, formal type
  128. theory and trait hierarchies [make illegal states unrepresentable]:
  129. - **The Newtype Pattern for Domain Separation & Coordinate Safety**: Replaces raw
  130. primitive integers with zero-cost newtypes (`CRow`, `VPRow`, `CHeight`), eliminating
  131. primitive obsession and transposition bugs with zero runtime memory or performance
  132. overhead:
  133. - **0-Index vs 1-Index Separation**: Strongly types the distinction between
  134. 0-based buffer positions (`IndexOps`: `VPRow`, `VPCol`, `CRow`, `CCol`), 1-based
  135. terminal coordinates (`TermRow`, `TermCol`), and 1-based lengths (`LengthOps`:
  136. `VPHeight`, `VPWidth`, `CHeight`, `CWidth`).
  137. - **Safe Bidirectional Conversions**: Pairing traits provide explicit conversions
  138. between 0-based and 1-based domains (`to_zero_based()`, `from_zero_based()`,
  139. `convert_to_length()`).
  140. - **Algebraic Identities & CSI Zero Protection**: Enforces algebraic laws
  141. (`Index + Length = Index`, `Index - Index = Length`) to eliminate dangerous
  142. manual arithmetic on raw integers, preventing off-by-one errors (`<` vs `<=`),
  143. negative underflow, and CSI zero-index terminal crashes (`TermRowDelta`,
  144. `TermColDelta`).
  145. - **Empirically Proven Zero-Cost Layout**: Newtypes share the identical memory
  146. layout, size, and ABI of raw primitives (passed in CPU registers with zero heap
  147. allocation or indirection) and are completely erased during LLVM compilation;
  148. Criterion benchmarks confirm execution differences remain strictly within the
  149. +/- 2% noise margin ([FUNARCH 2026][FUNARCH 2026 paper]).
  150. - **Dual-Domain Coordinate Trait Hierarchy**: Strict trait boundaries isolate 64-bit
  151. memory coordinates (`StorageCoordinate`, `usize`: `CPos`) from 16-bit visual
  152. coordinates (`ScreenCoordinate`, `u16`: `VPPos`), requiring explicit camera viewport
  153. transformations.
  154. - **Explicit Narrowing/Widening Traits & Zero Raw `as` Casts**: Replaces dangerous,
  155. silent primitive `as` casting across the codebase with explicit, type-safe traits
  156. (`WideningCastTo` for lossless promotions and `NarrowingCastTo` for checked/clamped
  157. reductions), preventing accidental truncations and sign-loss bugs.
  158. - **Eliminating Boolean Blindness with Witness Enums**: Grounded in ACM research
  159. ([FUNARCH 2023][FUNARCH 2023 paper] and [Parse, don't validate]), boundary and
  160. bounds checks never return uninformative `bool` flags. Instead, they return
  161. structured witness enums (`ArrayOverflowResult`, `RangeBoundsResult`), forcing
  162. callers to exhaustively handle all boundary states at compile time.
  163. - πŸ¦„ **First-Class Unicode & Complex Emoji Engine (`GCString`)**: Most terminal emulators
  164. and TUI libraries break when handling "jumbo emojis", zero-width joiners (ZWJ), skin
  165. tone modifiers, and wide characters (display width > 1), causing visual tearing,
  166. misaligned borders, and string-slicing panics. ROC solves this from the ground up via
  167. `GCStringOwned`:
  168. - **Three Distinct Coordinate Spaces**: Strictly decouples memory position
  169. (`ByteIndex`, UTF-8 offset), logical editing position (`SegIndex`, user-perceived
  170. grapheme clusters), and visual column position (`VPCol`, actual terminal display
  171. width).
  172. - **Complex Emoji & Modifier Support**: Correctly measures and renders multi-codepoint
  173. sequences (e.g., `πŸ‘¨πŸΎβ€πŸ€β€πŸ‘¨πŸΏ` spans 5 codepoints and 7 code units, but resolves to 1 logical
  174. grapheme segment and 2 visual columns).
  175. - **Panic-Proof Slicing & Boundary Safety**: Guarantees cursor navigation, backspace,
  176. and substring slicing never split UTF-8 codepoints or mid-grapheme clusters,
  177. eliminating runtime slicing panics across editors, line inputs, and diff rendering.
  178. - πŸ”’ **Supply-Chain Integrity & Owning Our BOM**: In an era of software supply-chain
  179. attacks, maintainer burnout, and abandonware, our explicit architectural goal is to
  180. **own our Bill of Materials (BOM)**. Critical primitives (including our custom
  181. `direct_to_ansi` terminal I/O backend, VT-100/ANSI parser, zero-copy gap buffer, and
  182. Markdown parser) are engineered in-house in pure Rust. We strictly limit external
  183. dependencies to actively funded, strongly supported, and battle-tested industry
  184. foundations (such as `tokio`, `mio`, and `mimalloc`), safeguarding production
  185. applications against transitive bloat, sudden deprecations, and upstream
  186. vulnerabilities.
  187. - 🌍 **Multi-Backend Architecture (Linux, macOS, Windows, Unix/BSDs)**: Native,
  188. first-class support across platforms using the best backend for each OS:
  189. - **Linux**: Our custom high-performance, Linux-native `direct_to_ansi` engine
  190. (talking directly to the terminal device via `mio`/epoll for minimal latency and
  191. maximum throughput, without the use of `crossterm`).
  192. - **macOS, Windows & Unix/BSDs**: Currently powered by `crossterm`. We plan to expand
  193. `direct_to_ansi` in the future to replace `crossterm` across all platforms.
  194. - πŸš€ **SIMD Contiguous Memory Layout (`Flat2DArray`)**: Single contiguous 1D allocation
  195. indexed as 2D, delivering 2.3x rendering speedups, SIMD chunk batching, and eliminating
  196. pointer indirection ([implementation deep
  197. dive][High-Performance Flat 2D Arrays in Rust (SIMD, L1 Cache)] and [memory latency
  198. theory][Rust, Memory performance & latency]).
  199. - πŸ§‘β€πŸ€β€πŸ§‘ **Double-Buffered SSH-Optimized Diff Rendering**: Double-buffered compositor computes
  200. minimal cell-level diffs between frames, painting only what changed for smooth,
  201. flicker-free performance over high-latency SSH connections, with multi-layer Z-order
  202. compositing for modal overlays and popups.
  203. - πŸ”€ **Terminal Multiplexing & PTY Architecture (`PTYMux`)**: Decouples physical display
  204. constraints from subprocess execution via virtual terminals and process orchestration:
  205. - **2D Viewport Panning in PTY Sessions (Horizontal Scrolling without Wrapping)**:
  206. Traditional terminal emulators (like `xterm`, `Alacritty`, `Kitty`) lack horizontal
  207. panning for standard CLI tools (like `cat`, `grep`, `git log`, `dmesg`), forcibly
  208. hard-wrapping wide lines across rows and mangling tabular data, JSON, or stack
  209. traces into unreadable spaghetti. When running any CLI program inside a ROC PTY
  210. session (a concrete manifestation of which is [`pty_mux_example`], powered by
  211. [`GrowableBuffer`] and [`PTYMux`]), ROC decouples the physical viewport from the
  212. virtual terminal canvas width (e.g., 1,000+ columns). The child process writes into
  213. this wide virtual canvas without line wrapping, allowing users to smoothly pan
  214. horizontally (`Shift + Mouse Wheel` or trackpad gestures) across the output without
  215. layout destruction.
  216. - **Decoupled Throughput vs. Terminal Bottlenecks (Faster Than Bare `xterm`)**: In
  217. traditional terminal emulators (like `xterm`), running a command that dumps
  218. megabytes of text (e.g., `cat large.log`) blocks the process on `stdout` I/O while
  219. the terminal synchronously parses escape codes, recalculates line wrapping, and
  220. rasterizes every glyph. Counter-intuitively, running that same command inside a ROC
  221. PTY session (such as [`pty_mux_example`]) running _inside_ `xterm` is often
  222. significantly **faster than running the command directly in bare `xterm`**. ROC's
  223. headless VT-100 parser (`OfsBufVT100`) acts as an in-memory shock absorber,
  224. ingesting raw subprocess output at memory bus speeds, while double-buffered diff
  225. rendering paints only the visible viewport to the host terminal at controlled
  226. display intervals. Subprocesses drain `stdout` without stalling on terminal drawing
  227. or network I/O backpressure.
  228. - πŸ•ŠοΈ **Terminfo Liberation**: Completely frees your applications from legacy `terminfo` /
  229. `termcap` databases and [`ncurses`] baggage by querying modern ANSI protocols directly
  230. at runtime.
  231. - πŸ“œ **`CSS`-Like Styling & Declarative Layouts**: Responsive [flexbox] layouts and
  232. [declarative] [CSS-like] styling inspired by [React] and [Elm].
  233. - 🎨 **Intelligent Color Degradation**: Automatically detects terminal capabilities and
  234. gracefully degrades colors: **24-bit Truecolor -> 256 colors -> 16 ANSI colors ->
  235. Monochrome** (black & white). Gracefully handles environments lacking truecolor support
  236. (such as pre-macOS 26 Tahoe `Terminal.app`, Linux virtual consoles, or headless CI
  237. runners), complete with dynamic lolcat rainbow color-wheel palettes that automatically
  238. adapt to terminal color capability.
  239. - ⌨️ **Modern Terminal Input & Keyboard Protocol Architecture**: Combines Linux-native
  240. kernel TTY polling via `direct_to_ansi` with an IO-free Sans-IO protocol state machine
  241. for robust, zero-latency input handling across local terminals and SSH:
  242. - **Linux-Native `direct_to_ansi` Driver**: Bypasses `crossterm` and `libc` FFI
  243. wrappers on Linux by talking directly to `/dev/tty` via `mio`/`epoll(7)`,
  244. eliminating thread-blocking reads and CPU-spinning loops.
  245. - **Disambiguating Modifier Chords & Key Collisions**: Reliably decodes chords and
  246. combinations that traditional terminal runtimes mangle or drop - such as
  247. [`Shift+Enter`], `Ctrl+Enter`, `Ctrl+Tab`, `Ctrl+Number/Punctuation`, `Ctrl+I` vs
  248. `Tab`, and `Alt+[` collisions.
  249. - **Kitty Keyboard Protocol (`CSI u`) Progressive Enhancement**: Negotiates advanced
  250. keyboard protocols with modern terminals ([Kitty keyboard protocol]), enabling full
  251. modifier reporting, key-release events, and unambiguous key sequences with graceful
  252. legacy fallback.
  253. - **Zero-Latency ESC Disambiguation (`MaybeMore`)**: Replaces brittle 50-100ms timeout
  254. heuristics with an internal state machine (`KernelDrained`, `KernelMayHaveMore`),
  255. achieving 0ms zero-latency ESC handling while correctly reassembling multi-packet
  256. escape sequences across SSH.
  257. - **OSC Terminal Query Absorption & SGR Mouse Reporting**: Frames and absorbs
  258. background terminal responses (such as OSC 10/11 color queries and OSC 52 clipboard)
  259. on `stdin` to prevent terminal text leakage, while supporting full SGR mouse
  260. tracking (clicks, drags, scroll wheel).
  261. - 🧩 **Composable "Applet" Architecture & Shared State**: Enables multiple integrated TUI
  262. experiences ("applets") to run within the same process and terminal window. Supports
  263. shared application state across sub-apps alongside local view state, allowing seamless
  264. transitions and routing between Full-Screen TUI views and inline Partial-TUI dialogs
  265. without process restarts or lost context.
  266. ## Welcome to the monorepo and workspace
  267. All the crates in the `r3bl-open-core` [monorepo] provide lots of useful functionality to
  268. help you build TUI (text user interface) apps, along with general niceties & ergonomics
  269. that all Rustaceans πŸ¦€ can enjoy πŸŽ‰.
  270. Any top-level folder in this repository that contains a `Cargo.toml` file is a Rust
  271. project, also known as a [crate]. These crates are likely published to [crates.io].
  272. Together, they form a [Rust workspace].
  273. Here's the [changelog] for this monorepo containing a Rust workspace. The changelog is a
  274. great place to start to get familiar with what has changed recently in each of the crates
  275. in this Rust workspace.
  276. ## This workspace contains crates for building TUI, CLI, TTY apps
  277. The [`r3bl_tui`] crate is the main crate that contains the core functionality for building
  278. TUI apps. It allows you to build apps that range from "full" TUI to "partial" TUI, and
  279. everything in the middle.
  280. Here are some videos that you can watch to get a better understanding of TTY programming.
  281. - [Build with Naz: TTY playlist]
  282. - [Build with Naz: async readline]
  283. This crate provides five entry points for building interactive terminal applications. Each
  284. internalizes terminal availability and size checks, and returns a `TuiAvailability<T>`
  285. enum:
  286. | Entry Point | Purpose | Best For |
  287. | :---------------------------------- | :--------------------- | :--------------------------------------------------------------------- |
  288. | `TerminalWindow::main_event_loop()` | Full TUI framework | Complex, multi-component apps with layouts, dialogs, and custom logic. |
  289. | `ReadlineAsyncContext::try_new()` | Async Readline | CLI-style line input, REPLs, and background logging. |
  290. | `choose()` | Interactive Selection | Prompting user to select one or more items from a list. |
  291. | `PTYMuxBuilder::build()` | Terminal Multiplexer | Wrapping existing CLI tools (like `htop`, `bash`) in a multi-pane TUI. |
  292. | `Spinner::try_start()` | Indeterminate Progress | Long-running tasks needing visual feedback (standalone or embedded). |
  293. ### Full TUI (async, raw mode, full screen) for immersive TUI apps
  294. [`tui`] gives you "raw mode", "alternate screen" and "full screen" support, while being
  295. totally async. It provides a full-featured framework with:
  296. - **`App` trait**: Unidirectional data flow architecture.
  297. - **`FlexBox`**: Responsive layout engine.
  298. - **Component System**: Reusable UI elements (editors, dialogs, etc.).
  299. An example of this is the "Full TUI" app `edi` in the [`r3bl-cmdr`] crate. You can install
  300. & run this with the following command:
  301. ```bash
  302. cargo install r3bl-cmdr
  303. edi
  304. ```
  305. ### Partial TUI (async, partial raw mode, async readline) for choice based user interaction
  306. [`choose`] allows you to build less interactive apps that ask a user to make choices from
  307. a list of options and then use a decision tree to perform actions.
  308. An example of this is this "Partial TUI" app `giti` in the [`r3bl-cmdr`] crate. You can
  309. install & run this with the following command:
  310. ```bash
  311. cargo install r3bl-cmdr
  312. giti
  313. ```
  314. ### Partial TUI (async, partial raw mode, async readline) for async REPL
  315. [`readline_async`] gives you the ability to easily ask for user input in a line editor.
  316. You can customize the prompt, and other behaviors, like input history.
  317. Using this, you can build your own async shell programs using "async readline & `stdout`".
  318. Use advanced features like showing indeterminate progress spinners, and even write to
  319. `stdout` in an async manner, without clobbering the prompt / async readline, or the
  320. spinner. When the spinner is active, it pauses output to `stdout`, and resumes it when the
  321. spinner is stopped.
  322. An example of this is this "Partial TUI" app `giti` in the [`r3bl-cmdr`] crate. You can
  323. install & run this with the following command:
  324. ```bash
  325. cargo install r3bl-cmdr
  326. giti
  327. ```
  328. Here are other examples of this:
  329. 1. [`tcp-api-server`]: An interactive async REPL client demonstrating `readline_async`
  330. with concurrent background tasks and progress spinners.
  331. 2. [`tui/examples`]: Standalone examples in this workspace demonstrating async readline
  332. (`readline_async.rs`), spinners (`spinner.rs`), shell (`shell_async.rs`), and PTY
  333. orchestration.
  334. ### Terminal multiplexer
  335. [`PTYMux::run()`] lets you build a terminal multiplexer similar to `tmux`. It manages
  336. multiple child processes (each in its own PTY) with per-process virtual terminal buffers
  337. and instant switching. See the [`pty_mux_example`] for a working example that wraps
  338. `bash`, `htop`, and other CLI tools.
  339. ## Power via composition
  340. You can mix and match "Full TUI" with "Partial TUI" to build for whatever use case you
  341. need. `r3bl_tui` allows you to create application state that can be moved between various
  342. "applets", where each "applet" can be "Full TUI" or "Partial TUI".
  343. ### Main library crate
  344. There is just one main library crate in this workspace: [`r3bl_tui`].
  345. To add `r3bl_tui` to your own Rust project:
  346. **Option 1: crates.io (stable release)**
  347. Use this if you prefer stable, versioned releases:
  348. ```bash
  349. cargo add r3bl_tui
  350. ```
  351. Or in your `Cargo.toml`:
  352. ```toml
  353. [dependencies]
  354. r3bl_tui = "0.7.8"
  355. ```
  356. **Option 2: GitHub main branch (bleeding edge)**
  357. Bug fixes and patches land on `main` immediately before being published to crates.io. If
  358. you need the latest fixes or rapid iteration:
  359. ```bash
  360. cargo add r3bl_tui --git https://github.com/r3bl-org/r3bl-open-core.git --branch main
  361. ```
  362. Or in your `Cargo.toml`:
  363. ```toml
  364. [dependencies]
  365. r3bl_tui = { git = "https://github.com/r3bl-org/r3bl-open-core.git", branch = "main" }
  366. ```
  367. ### Main binary crate
  368. There is just one main binary crate that contains user facing apps that are built using
  369. the library crates: [`r3bl-cmdr`]. This crate contains these apps:
  370. - `giti`: Interactive git workflows made easy.
  371. - `edi`: Beautiful Markdown editor with advanced rendering and editing features.
  372. - `env-source`: Fast cross-platform environment loader evaluating scripts across POSIX sh,
  373. Fish, PowerShell, and cmd.exe.
  374. You can install & run this with the following command:
  375. ```bash
  376. cargo install r3bl-cmdr
  377. # Interactive git workflows made easy.
  378. giti --version
  379. # Beautiful Markdown editor with advanced rendering and editing features.
  380. edi --version
  381. # Fast cross-platform environment loader.
  382. env-source --version
  383. ```
  384. ### Build infrastructure and developer tooling crate
  385. The [`r3bl-build-infra`] crate provides developer productivity tools:
  386. - `cargo-rustdoc-fmt`: Formats markdown tables and converts inline links to
  387. reference-style links in rustdoc comments.
  388. You can install this binary with:
  389. ```bash
  390. cargo install r3bl-build-infra
  391. # Or from local source within this workspace:
  392. fish run.fish install-build-infra
  393. ```
  394. ## Project Task Organization
  395. This project uses a task management system for organizing day-to-day development work
  396. using detailed task files with implementation plans in the `./task/` directory.
  397. ### Task Management Files
  398. - **[`./task/`]** - Directory containing detailed task management files:
  399. - **Active tasks**: `task_*.md` files in root of `./task/` - Complex tasks currently
  400. in progress
  401. - **`pending/`**: Tasks queued for later work
  402. - **`done/`**: Completed task files moved from root after all steps are marked
  403. `[COMPLETE]`
  404. - **`archive/`**: Abandoned tasks retained for historical reference
  405. - **`AGENTS.md`**: Rules and format specifications for creating and maintaining task
  406. files
  407. ### Task File Format
  408. Detailed task files follow a structured format defined in [`./task/AGENTS.md`]:
  409. **Structure:**
  410. ```markdown
  411. # Task Overview
  412. High-level description, architecture, context, and the "why"
  413. # Implementation Plan
  414. ## Step 0: Do Something [STATUS]
  415. Detailed instructions for this step
  416. ### Step 0.0: Do Subtask [STATUS]
  417. Details about subtask
  418. ### Step 0.1: Do Another Subtask [STATUS]
  419. Details about another subtask
  420. ## Step 1: Do Something Else [STATUS]
  421. More detailed steps...
  422. ```
  423. **Hierarchical organization:**
  424. - Steps are numbered (Step 0, Step 1, Step 2, etc.)
  425. - Substeps use decimal notation (Step 0.0, Step 0.1, etc.)
  426. - Table of contents automatically generated and maintained using `doctoc`
  427. - Formatting standardized with `prettier`
  428. **Status markers:**
  429. - `[COMPLETE]` - Step finished and verified
  430. - `[WORK_IN_PROGRESS]` - Currently working on this step
  431. - `[BLOCKED]` - Cannot proceed (waiting for dependency)
  432. - `[DEFERRED]` - Postponed to later
  433. ### Task Workflow Commands
  434. The `/r3bl-task` slash command (defined in [`AGENTS.md: task-tracking-system`]) manages
  435. the task lifecycle:
  436. **Create a new task:**
  437. ```bash
  438. /r3bl-task create my_feature_name
  439. ```
  440. - Creates `./task/task_my_feature_name.md` from your detailed plan
  441. - Use after you have a comprehensive plan in your todo list
  442. - Initializes structure with steps and status markers
  443. **Update an existing task:**
  444. ```bash
  445. /r3bl-task update my_feature_name
  446. ```
  447. - Updates progress markers in `./task/task_my_feature_name.md`
  448. - Moves completed task files to `./task/done/` when all steps are `[COMPLETE]`
  449. **Resume working on a task:**
  450. ```bash
  451. /r3bl-task load my_feature_name
  452. ```
  453. - Loads `./task/task_my_feature_name.md` for continued work
  454. - Resumes from the last step marked `[WORK_IN_PROGRESS]`
  455. - If none found, asks which incomplete step to start with
  456. ### Workflow Connection
  457. The task organization workflow connects strategic planning with tactical execution:
  458. - **Strategic Planning** (`docs/` folder): Feature roadmaps, architectural decisions,
  459. design documents
  460. - **Planning to Active Work**: Complex features are documented in `docs/` first.
  461. - **Tactical Execution**:
  462. 1. Complex tasks get detailed planning β†’ `/r3bl-task create` β†’ `./task/task_*.md`
  463. 2. Work progresses through hierarchical steps with `/r3bl-task update` marking
  464. progress
  465. 3. Completion β†’ Task moved to `./task/done/` via `/r3bl-task update`
  466. This approach (docs β†’ ./task/) ensures strategic planning, tactical planning, and detailed
  467. execution are well-organized and connected.
  468. ### Development Tools Integration
  469. R3BL provides IDE extensions to enhance your development workflow:
  470. **For VSCode Users**
  471. R3BL provides custom VSCode extensions including Task Spaces (organize editor tabs by
  472. context), theme, and enhanced syntax highlighting. See the [R3BL VSCode Extensions]
  473. section below for installation and detailed feature descriptions.
  474. **Workflow Integration:**
  475. The R3BL Task Spaces extension helps you organize editor tabs by context (e.g., one space
  476. for features, one for docs, one for debugging) while the `./task/` files track your
  477. implementation progress.
  478. ## Documentation and Planning
  479. We invest heavily in documentation quality because it is the right thing to do. Also,
  480. [research shows] it is the single most important factor developers consider when
  481. evaluating open source projects. In the Rust ecosystem specifically, documentation is the
  482. #1 crate evaluation criterion ([RFC 1824]), and 91% of practitioners depend on
  483. documentation for adoption decisions ([2024 study]). Every public API has rustdoc comments
  484. with usage examples, and doc tests verify that every example compiles and runs.
  485. Our documentation standards are not aspirational - they are [machine-enforced].
  486. Conventions for voice, structure, links, and formatting are codified as an AI (LLM) skill
  487. that runs during development, not a style guide that sits in a wiki collecting dust. We
  488. also operationalize inclusivity at the documentation level: our [Pedagogical Links for
  489. Inclusivity] rule requires linking domain-specific terms to external references so no
  490. reader is excluded by assumed knowledge - a concrete, measurable practice rather than a
  491. vague aspiration.
  492. The [`docs/`] folder contains comprehensive documentation for this project, including:
  493. ### Documentation Philosophy
  494. - [`why-good-docs-matter.md`] - Research evidence for why we invest heavily in
  495. documentation quality
  496. ### Release and Contribution Guides
  497. - [`release-guide.md`] - Step-by-step guide for releasing new versions
  498. - [`CONTRIBUTING.md`] - Contribution guidelines including branch naming, commit message
  499. standards, local checks, and PR procedures
  500. ### Technical Design Documents
  501. - Parser strategy analysis and design decisions
  502. - Performance optimization guides (`docs/task_tui_perf_optimize.md`)
  503. - Architecture documentation for various components
  504. - Feature-specific planning and design documents
  505. The `docs/` folder serves as the central repository for:
  506. - **Long-term planning**: Strategic goals and feature roadmaps
  507. - **Technical decisions**: Architecture choices and implementation strategies
  508. - **Process documentation**: How we work and contribute to the project
  509. - **Design artifacts**: Detailed analysis of complex features before implementation
  510. ## Learn how these crates are built, provide feedback
  511. To learn how we built this crate, please take a look at the following resources.
  512. - If you like consuming video content, here's our [YT channel]. Please consider
  513. [subscribing].
  514. ## Quick Start
  515. ### Automated Setup (Recommended)
  516. Use the bootstrap script to automatically install all required tools:
  517. ```bash
  518. # Clone the repository
  519. git clone https://github.com/r3bl-org/r3bl-open-core.git
  520. cd r3bl-open-core
  521. # Run the bootstrap script
  522. ./bootstrap.sh
  523. ```
  524. The [`bootstrap.sh`] script handles **OS-level setup** with a clean main function
  525. structure and will:
  526. - **Cross-Platform Support**: Works on **macOS** (Homebrew) and **Linux** including Ubuntu
  527. (apt), Fedora (dnf), Arch (pacman), openSUSE (zypper), and Alpine (apk)
  528. - **Core Rust Installation**: Install Rust toolchain (`rustup`) and ensure `cargo` is in
  529. `PATH`
  530. - **Development Shell**: Install `Fish` shell and `fzf` for interactive development
  531. - **File Watching**: Install file watchers (`inotifywait` on Linux, `fswatch` on macOS)
  532. - **Development Utilities**: Install `htop`, `screen`, `tmux` for system monitoring
  533. - **Node.js Ecosystem**: Install [`Node.js`] and `npm` (for Markdown formatting via
  534. Prettier and local documentation serving)
  535. - **AI (LLM) Integration (Optional)**: If you choose to use an AI coding agent, the repo
  536. supports `Antigravity CLI` (`agy`), or any tool of your choice
  537. - **Rust Development Tools Setup**: Call `fish run.fish install-cargo-tools` for all
  538. Rust-specific `cargo` tooling
  539. **Architecture**: Uses clear function separation with `main()` orchestrator and dedicated
  540. functions for each concern (`install_rustup`, `install_clang`, `install_shell_tools`,
  541. etc.)
  542. ### Manual Setup
  543. If you prefer manual installation or are on Windows:
  544. ```bash
  545. # Install Rust
  546. curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  547. # Install `fish`, `fzf`, `nodejs`, and `npm` (via package manager)
  548. # Ubuntu/Debian: sudo apt install fish fzf nodejs npm
  549. # macOS: brew install fish fzf node
  550. # Or run `./bootstrap.sh` for automatic detection
  551. # Install Rust development tools (after OS dependencies)
  552. fish run.fish install-cargo-tools
  553. ```
  554. **Note**: The manual approach requires you to install OS-level dependencies yourself. The
  555. `install-cargo-tools` command focuses specifically on **Rust development tools**:
  556. **From crates.io (via cargo-binstall with fallback to cargo install):**
  557. - **`cargo-binstall`**: Fast binary installer (installed first as foundation)
  558. - **Core Development Tools**: `bacon`, `flamegraph`, `inferno`
  559. - **Workspace Management**: `cargo-workspaces`, `cargo-cache`, `cargo-update`
  560. - **Code Quality & Link Checking**: `cargo-deny`, `cargo-unmaintained`, `cargo-expand`,
  561. `cargo-readme`, `lychee`
  562. - **Language Server Components**: `rust-analyzer` component, `rust-src`
  563. **From local source (via `cargo install --path`):**
  564. - **cmdr**: `edi`, `giti`, `rc`, `env-source` binaries (calls `run.fish install-cmdr`)
  565. - **build-infra**: `cargo-rustdoc-fmt` (calls `run.fish install-build-infra`)
  566. - **rust-analyzer-mcp-server**: `rust-analyzer-mcp-server` MCP binary (calls
  567. `run.fish install-rust-analyzer-mcp-server`)
  568. **Features:**
  569. - **Smart Installation**: Uses `cargo-binstall` for speed with fallback to
  570. `cargo install --locked`
  571. - **Local Source Rebuild**: Always rebuilds `cmdr`, `build-infra`, and
  572. `rust-analyzer-mcp-server` from source with current toolchain
  573. - **Shared Utilities**: Leverages utility functions from `script_lib.fish` for consistency
  574. ## IDE Setup and Extensions
  575. ### R3BL VSCode Extensions
  576. For an optimal development experience with r3bl-open-core in VSCode, we provide a custom
  577. extension pack specifically designed for Rust development. This extension pack is not
  578. available on the VSCode marketplace and must be installed manually.
  579. **What's included:**
  580. - **Task Spaces** - Organize and switch between collections of editor tabs for different
  581. work contexts (e.g., one space for editing features, one for writing documentation, one
  582. for debugging). Complements the `./task/` file management system by helping you organize
  583. your editor sessions.
  584. - **R3BL Theme** - A carefully crafted dark theme optimized for Rust and Markdown
  585. development
  586. - **Auto Insert Copyright** - Automatically inserts copyright headers in new files
  587. - **Semantic Configuration** - Enhanced Rust syntax highlighting with additional semantic
  588. tokens
  589. - **Extension Pack** - Bundles all R3BL extensions for easy installation
  590. **Benefits for r3bl-open-core development:**
  591. - Zero manual configuration required
  592. - Enhanced semantic highlighting for better code readability
  593. - Automatic copyright header insertion following project standards
  594. - Seamless integration with rust-analyzer
  595. - Optimized color scheme for the r3bl codebase
  596. **Installation:**
  597. ```bash
  598. # Clone the extension repository
  599. git clone https://github.com/r3bl-org/r3bl-vscode-extensions.git
  600. cd r3bl-vscode-extensions
  601. # Install extensions (works with both VSCode and VSCode Insiders)
  602. ./install.sh
  603. ```
  604. **Prerequisites:**
  605. - VSCode or VSCode Insiders installed
  606. - Bash shell (for running install.sh)
  607. **Post-installation:**
  608. 1. Restart VSCode
  609. 2. Select the R3BL Theme: `Ctrl+Shift+P` β†’ "Preferences: Color Theme" β†’ "R3BL Theme"
  610. 3. Configure copyright settings if needed
  611. The R3BL VSCode extensions work seamlessly with the existing development tools mentioned
  612. in this guide, including `rust-analyzer`, `bacon`, and the comprehensive development
  613. workflow.
  614. ### AI (LLM) Coding Agent Integration (Optional)
  615. We believe developers should be empowered to think for themselves, read & understand code,
  616. and write code. We do not push the use of AI (LLM) coding agents or advocate "vibe
  617. coding".
  618. **Comprehensive Non-AI (LLM) Tooling:**
  619. Our primary development experience is built around robust tools and scripts which don't
  620. require LLMs. These tools are deterministic (not probabilistic), don't hallucinate, are
  621. fast & efficient, and only consume your local compute and energy resources:
  622. - [`./check.fish`]: Your go-to tool for builds, tests, and linting.
  623. - [`run.fish`][unified-script-architecture]: Orchestrates workspace-wide commands.
  624. - [`bacon`][bacon-development-tools]: Provides real-time background feedback.
  625. - [`bootstrap.sh`][automated-setup-recommended]: Automated OS-level and toolchain setup.
  626. - **`cargo-rustdoc-fmt`**: Custom rustdoc formatter located in the [`build-infra/`]
  627. folder.
  628. - [R3BL VSCode Extensions]: Enhancements for the developer's environment (Themes,
  629. Copyright management, etc).
  630. - **Core Rust Stack**: `rustup`, `cargo`, `rust-analyzer`, `clippy`, `rustfmt`.
  631. - **CLI Power Tools**: `fzf` (fuzzy finding), `btop` (monitoring), `tmux` (multiplexing),
  632. `flamegraph` (profiling), `inferno` (stack collapse), `lychee` (link checking).
  633. - **Workspace Utilities**: `cargo-binstall`, `cargo-deny`, `cargo-expand`, `cargo-update`,
  634. `cargo-workspaces`, `cargo-cache`, `cargo-outdated`, `cargo-unmaintained`,
  635. `cargo-readme`, `cargo-warloc` (count lines of code).
  636. For those who choose to use AI (LLM) coding agents, this project is agent-agnostic and
  637. provides structured guidance to support you in using your tool of choice. This ensures
  638. that you can:
  639. 1. Explore the existing codebase with confidence.
  640. 2. Run tests, do profiling, and measure optimizations.
  641. 3. Refactor code or generate new code that adheres to our engineering standards. There are
  642. manual review steps and many other guardrails in place in the [`skills`] themselves.
  643. **How it works:**
  644. Using an AI coding agent is completely optional. If you do choose to use an AI/LLM coding
  645. agent (such as `Antigravity CLI` (`agy`), or any tool of your choice), point it to the
  646. instructions in [`AGENTS.md`]. This file contains our design philosophy, coding standards,
  647. and crate-specific guidance.
  648. To equip your AI coding agent with AST-aware code navigation, compiler diagnostics, and
  649. automated quick-fixes via `rust-analyzer`, connect it to our
  650. [`r3bl-rust-analyzer-mcp-server`] ([crates.io: r3bl-rust-analyzer-mcp-server]) Model
  651. Context Protocol (MCP) server.
  652. **Available Skills (`.agents/skills/`):**
  653. When used, AI (LLM) coding agents can leverage the patterns and commands defined in the
  654. `.agents/` directory:
  655. | Skill | Purpose |
  656. | --------------------- | ---------------------------------------------------------------- |
  657. | `check-code-quality` | Comprehensive quality checklist (check β†’ build β†’ clippy β†’ tests) |
  658. | `run-clippy` | Linting, comment punctuation, cargo fmt |
  659. | `write-documentation` | Rustdoc conventions, intra-doc links, constant formatting |
  660. | `organize-modules` | Private modules with public re-exports pattern |
  661. | `check-bounds-safety` | Type-safe Index/Length patterns for bounds-sensitive code |
  662. | `analyze-performance` | Flamegraph-based performance regression detection |
  663. | `design-philosophy` | Core principles: cognitive load, type safety, abstraction worth |
  664. **Slash Commands:**
  665. Invoke `skills` directly in your AI (LLM) coding agent:
  666. | Command | Action |
  667. | --------------------- | ---------------------------------------------------------------------- |
  668. | `/check` | Run comprehensive code quality checks |
  669. | `/docs` | Documentation build and formatting |
  670. | `/clippy` | Code style and linting |
  671. | `/fix-intradoc-links` | Fix rustdoc intra-doc links |
  672. | `/check-regression` | Detect performance regressions |
  673. | `/analyze-logs` | Analyze log files (strips ANSI codes) |
  674. | `/r3bl-task` | [Task management][R3BL VSCode Extensions] (create, update, load, done) |
  675. **AI (LLM) Coding Agent Synergy: R3BL VSCode Extensions**
  676. For the best experience, install the [R3BL VSCode Extensions]. They boost your
  677. productivity whether you use them standalone or hand-in-hand with AI (LLM) coding agents.
  678. Here are some highlights:
  679. | Extension | AI (LLM) Coding Agent Synergy |
  680. | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  681. | **R3BL Theme** | Optimized dark theme for long coding sessions with AI (LLM) coding agents |
  682. | **R3BL Task Spaces** | Organize editor tabs by task context β€” switch between feature work, debugging, and documentation while the agent tracks your `./task/` files |
  683. | **R3BL Copy Selection Path** | Press `Alt+O` to copy file paths with line ranges β€” paste directly into your agent for precise code references |
  684. ## Build the workspace and run tests
  685. There's a unified [`fish`] script that you can use to run the build and release pipeline
  686. for this workspace, and more (local only operations).
  687. To get a list of available commands, you can review the `fish` script in the root of this
  688. repo [`run.fish`]. To see all available commands:
  689. ```bash
  690. fish run.fish
  691. ```
  692. ### Key Commands
  693. | Command | Description |
  694. | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
  695. | `fish run.fish all` | Run all major checks (build, test, clippy, docs, audit, format) |
  696. | `fish run.fish build` | Build the entire workspace |
  697. | `fish run.fish test` | Run all tests across the workspace |
  698. | `fish run.fish cov <pkg> [test] [file] [--html]` | Run targeted `cargo-llvm-cov` with filtered output (or `--html` in browser) |
  699. | `fish run.fish install-cargo-tools` | Install all dev tools (`crates.io` + local source packages) |
  700. | `fish run.fish update-cargo-tools` | Update all tools (`crates.io` + rebuild local source packages) |
  701. | `fish run.fish install-cmdr` | Install `cmdr` binaries (`edi`, `giti`, `rc`, `env-source`) from source |
  702. | `fish run.fish install-build-infra` | Install `build-infra` tools (`cargo-rustdoc-fmt`) from source |
  703. | `fish run.fish test-watch [pattern]` | Watch for file changes and run specific test |
  704. | `fish run.fish run-examples` | Run TUI examples interactively |
  705. | `fish run.fish run-examples-flamegraph-svg` | Generate SVG flamegraph for performance analysis |
  706. | `fish run.fish run-examples-flamegraph-fold [--benchmark]` | Generate perf-folded format for analysis (use `--benchmark` for reproducible profiling) |
  707. | `fish run.fish bench` | Run benchmarks |
  708. | `fish run.fish run-binaries` | Run `cmdr` binaries (`edi`, `giti`, `rc`, `env-source`) interactively |
  709. | `fish run.fish dev-dashboard` | Start 2-pane `tmux` development dashboard (tests, docs, checks) |
  710. | `fish run.fish check-full` | Run comprehensive checks (tests, doctests, docs, toolchain validation) |
  711. | `fish run.fish check-windows-build` | Verify Windows cross-compilation (platform `cfg` gates) |
  712. | `fish run.fish toolchain-validate` | Quick toolchain validation (components only, ~1-2 seconds) |
  713. | `fish run.fish toolchain-validate-complete` | Complete toolchain validation (full build+test, ~5-10 minutes) |
  714. | `fish run.fish toolchain-update` | Update Rust to month-old nightly toolchain with cleanup |
  715. | `fish run.fish toolchain-sync` | Sync Rust environment to match `rust-toolchain.toml` |
  716. | `fish run.fish toolchain-remove` | Remove ALL toolchains (⚠️ destructive testing utility) |
  717. > **TUI Testing**: The `r3bl_tui` crate uses PTY-based testing for accurate terminal I/O
  718. > verification. See the [PTY Testing Infrastructure] section in the TUI README for details
  719. > on writing and running TUI tests.
  720. ### Automatic Tmpfs Symlink Architecture & Git Worktree Isolation
  721. **High-Performance Zero-Configuration Build Architecture**: `check.fish` dynamically
  722. provisions an isolated tmpfs target directory based on the repository and worktree
  723. location, and symlinks `./target` to that directory. This ensures blazing-fast RAM builds
  724. (~2-3x speedup) while completely eliminating lock contention across multiple terminals,
  725. IDE instances (`rust-analyzer`), and Git worktrees.
  726. #### 1. Git Worktree Isolation
  727. When working concurrently across multiple Git worktrees (e.g. `roc`, `roc-build-spawny`,
  728. `roc-fix-shift-home-lockup`), each worktree operates in its own isolated tmpfs workspace:
  729. ```text
  730. /home/user/github/roc/target -> /tmp/check-fish-$USER-roc-<hash>/target
  731. /home/user/github/roc-build-spawny/target -> /tmp/check-fish-$USER-roc-build-spawny-<hash>/target
  732. /home/user/github/roc-fix-shift-home-lockup/target -> /tmp/check-fish-$USER-roc-fix-shift-home-lockup-<hash>/target
  733. ```
  734. - **Zero Lock Contention**: Each worktree has its own dedicated `.lock` file and build
  735. cache.
  736. - **Shared IDE & Terminal Cache**: Because `./target` is a native filesystem symlink,
  737. `cargo`, `rust-analyzer`, `bacon`, and `check.fish` within the same worktree share the
  738. exact same RAM cache seamlessly without requiring custom `CARGO_TARGET_DIR` environment
  739. variables.
  740. #### 2. Smart RAM-Aware Storage Selection
  741. `check.fish` automatically inspects total physical system memory:
  742. - **High-RAM Workstations (>= 48 GiB RAM)**: Uses `/tmp` (RAM-backed tmpfs) for maximum
  743. compilation speed.
  744. - **Lower-RAM Machines (< 48 GiB RAM)**: Automatically routes to `/var/tmp` (NVMe
  745. disk-backed storage) to prevent tmpfs exhaustion and out-of-memory crashes during large
  746. builds or background system updates.
  747. #### 3. Directory Independence
  748. `check.fish` can be safely executed from any subfolder or crate directory (e.g. from
  749. `tui/`, `cmdr/`, etc.). It automatically resolves the repository root (`CHECK_REPO_ROOT`)
  750. and operates relative to the root project workspace.
  751. #### 4. Rsync & Auto-Healing Symlinks
  752. When cloning, syncing, or copying repository folders via `rsync` (or across reboots where
  753. tmpfs is wiped):
  754. - The backing store directory is automatically re-created.
  755. - Broken or misdirected `./target` symlinks are detected and auto-healed whenever
  756. `check.fish` runs.
  757. - Simply execute `./check.fish --check` on any new machine or worktree to instantly
  758. provision the build cache symlink.
  759. #### 5. Cache Management & Cleaning (`--clean`)
  760. To clear the build cache:
  761. - **`./check.fish --clean` (Recommended)**: Safely empties the backing tmpfs target
  762. directory contents and staging directories, preserving the symlink structure and
  763. avoiding OS errors.
  764. - **`cargo clean`**: Standard cargo clean works normally through the symlink.
  765. - **`rm -rf target`**: If the `./target` symlink is manually deleted from the shell,
  766. `check.fish` detects the missing symlink on the next run, wipes any orphaned backing
  767. store, and re-provisions a fresh symlink.
  768. #### Incremental Compilation Management
  769. Incremental compilation is disabled globally (`incremental = false` in
  770. `.cargo/config.toml`) to avoid issues with the `rustc` dependency graph on nightly builds:
  771. ```toml
  772. # .cargo/config.toml
  773. [build]
  774. incremental = false # Disable to avoid rustc dep graph ICE on nightly
  775. ```
  776. **Why disable incremental compilation?**
  777. - The nightly compiler has occasional bugs with the dependency graph in incremental mode
  778. - These bugs can cause Internal Compiler Errors (ICE) like
  779. "mir_drops_elaborated_and_const_checked"
  780. - Disabling it globally ensures stable builds across all `cargo` invocations
  781. - The performance impact is acceptable for development workflows
  782. **If you encounter ICE errors anyway:**
  783. ```bash
  784. # Clear any corrupted incremental artifacts
  785. rm -rf target/check target/debug target/release
  786. # Rebuild cleanly
  787. cargo check # or cargo build, cargo test, etc.
  788. ```
  789. The `check.fish` script also explicitly sets `CARGO_INCREMENTAL=0` as a redundant
  790. safeguard.
  791. ### Bacon Development Tools
  792. This project includes [bacon] configuration for background code checking and testing.
  793. `bacon` provides real-time feedback on code changes with two distinct workflows:
  794. **Interactive Workflow (Rich TUI with details):**
  795. - Full terminal UI with detailed output
  796. - Ctrl+click on errors and warnings to jump directly to source code (via `OSC` hyperlinks)
  797. - Perfect for active debugging and development
  798. **Background Workflow (Silent monitoring):**
  799. - Minimal output - just success/failure status
  800. - Answers simple yes/no questions like "do tests pass?" or "do docs build?"
  801. - Ideal for background monitoring while focusing on other tasks
  802. **Available Bacon Commands:**
  803. **Code Quality & Checking:**
  804. | Command | Description |
  805. | ------------------ | ----------------------------------------------------------- |
  806. | `bacon check` | Fast typecheck of default target |
  807. | `bacon check-all` | Typecheck all targets (lib, bins, tests, benches, examples) |
  808. | `bacon clippy` | Run `clippy` lints on default target |
  809. | `bacon clippy-all` | Run `clippy` lints on all targets (keybinding: `c`) |
  810. **Testing:**
  811. | Command | Workflow | Description |
  812. | --------------------------------- | ----------- | -------------------------------------------------------------------------- |
  813. | `bacon test` | Interactive | Run all tests with `cargo test` (includes unit, integration, and doctests) |
  814. | `bacon test -- <pattern>` | Interactive | Run specific test matching pattern |
  815. | `bacon doctests` | Interactive | Run only documentation tests (`cargo test --doc`) |
  816. | `bacon test --headless --summary` | Background | Silent test runner providing only pass/fail status |
  817. **Documentation:**
  818. | Command | Workflow | Description |
  819. | -------------------------------- | ----------- | ------------------------------------------------- |
  820. | `bacon doc` | Interactive | Generate documentation with detailed output |
  821. | `bacon doc --headless --summary` | Background | Silent doc builder answering "did docs generate?" |
  822. | `bacon doc-open` | Interactive | Generate docs and open in browser |
  823. **Running & Benchmarking:**
  824. | Command | Description |
  825. | ---------------------------- | ----------------------------------------------------------------------- |
  826. | `bacon run` | Build and run the project in background |
  827. | `bacon run-long` | Run long-running processes (e.g., servers) with auto-restart on changes |
  828. | `bacon ex -- <example_name>` | Run specific example (e.g., `bacon ex -- my-example`) |
  829. | `bacon bench` | Run performance benchmarks |
  830. Choose the workflow that matches your current needs:
  831. - Use **interactive** when actively debugging or wanting detailed feedback
  832. - Use **background** for continuous monitoring, CI/CD pipelines, or when you just need to
  833. know if things work
  834. **Testing Notes:**
  835. - Use `bacon test` to run all tests (includes unit, integration, and doctests)
  836. - Use `bacon doctests` or `bacon test --doc` to run only documentation tests
  837. ### Automated Development Monitoring
  838. The project provides two complementary approaches for continuous monitoring during
  839. development - choose based on your workflow preferences:
  840. #### Option 1: Lightweight Watch Mode (Recommended for Most Users)
  841. For developers who want automated monitoring without the overhead of `tmux`, use the
  842. standalone check script:
  843. ```bash
  844. ./check.fish --watch
  845. ```
  846. **What it does:**
  847. - **Monitors source directories**: Watches `cmdr/src/`, `analytics_schema/src/`, and
  848. `tui/src/` for changes
  849. - **Event-driven execution**: Triggers immediately on file changes (no polling delay)
  850. - **Intelligent debouncing**: 1-second delay prevents rapid re-runs during saves
  851. - **Comprehensive checks**: Runs tests, doctests, and doc builds automatically
  852. - **Clean progress output**: Shows stage-by-stage progress without verbose `cargo` logs
  853. - **Automatic toolchain validation**: Validates and repairs Rust toolchain before checks
  854. - **ICE recovery**: Detects and recovers from Internal Compiler Errors automatically
  855. - **ICE escalation**: On persistent ICE, escalates to `rust-toolchain-update.fish` to find
  856. a stable nightly
  857. - **Continuous operation**: Keeps watching even if checks fail (perfect for iterative
  858. development)
  859. **Example output:**
  860. ```
  861. πŸ‘€ Watch mode activated
  862. Monitoring: cmdr/src, analytics_schema/src, tui/src
  863. Log file: /tmp/r3bl_tui/check.log
  864. Press Ctrl+C to stop
  865. [10:00:00] πŸ”„ Quiet period reached, running checks...
  866. [10:00:01] πŸ›« Running tests...
  867. [10:00:05] βœ… tests passed (4.2s)
  868. [10:00:06] πŸ›« Running doctests...
  869. [10:00:08] βœ… doctests passed (2.1s)
  870. [10:00:09] πŸ›« Running doc build...
  871. [10:00:15] βœ… doc build passed (6.3s)
  872. [10:00:15] βœ… All checks passed!
  873. [10:00:15] πŸ‘€ Watching for changes...
  874. ```
  875. **Benefits:**
  876. - **Single window**: No `tmux` complexity - just one terminal
  877. - **Immediate feedback**: 1-second response time after file saves
  878. - **Low overhead**: Minimal resource usage compared to running multiple monitors
  879. - **Perfect for focus**: Clean output doesn't distract from your editor
  880. **Event handling:** While checks run (30+ seconds), the Linux kernel buffers new file
  881. change events. When checks complete, buffered events trigger immediately if debounce
  882. allows. This ensures no changes are lost but may cause cascading re-runs if you save
  883. multiple times during test execution. Adjust `DEBOUNCE_WINDOW_SECS` in the script if
  884. needed.
  885. **Usage:**
  886. ```bash
  887. # Show available options
  888. ./check.fish --help
  889. # Start watch mode
  890. ./check.fish --watch
  891. # Or run checks once (manual mode)
  892. ./check.fish # Default: tests + doctests + docs
  893. ./check.fish --check # Fast typecheck only (cargo check)
  894. ./check.fish --build # Compile only (cargo build)
  895. ./check.fish --clippy # Lint only (cargo clippy --all-targets)
  896. ./check.fish --fmt # Format changed files (cargo fmt + cargo-rustdoc-fmt)
  897. ./check.fish --test # Tests + doctests only
  898. ./check.fish --doc # Docs only (quick, no deps)
  899. ./check.fish --full # ALL checks + ICE escalation to toolchain update
  900. ```
  901. #### Option 2: Comprehensive Tmux Dashboard
  902. ### Tmux Development Dashboard
  903. For developers who prefer a multi-pane visual environment, the `tmux` dashboard combines
  904. documentation monitoring with a focused development shell.
  905. **Comprehensive 2-Pane Development Dashboard:**
  906. ```
  907. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  908. β”‚ Tmux Session: r3bl (2-pane vertical layout) β”‚
  909. β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
  910. β”‚ Top Pane: β”‚
  911. β”‚ ./check.fish --watch-doc β”‚
  912. β”‚ (Documentation watch mode for real-time feedback) β”‚
  913. β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
  914. β”‚ Bottom Pane: β”‚
  915. β”‚ (Empty, focused for your commands) β”‚
  916. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  917. ```
  918. **Key Features:**
  919. - **Persistent Session**: Session name "r3bl" - reconnect from other terminals with
  920. `tmux attach-session -t r3bl`
  921. - **Watch Mode Documentation**: The top pane runs `./check.fish --watch-doc` which
  922. triggers immediately on file changes to rebuild documentation.
  923. - **Focused Development**: The bottom pane is focused and ready for your manual commands,
  924. tests, or binary execution.
  925. - **Persistent Session**: survives terminal disconnects, allowing you to pick up exactly
  926. where you left off.
  927. **Usage:**
  928. ```bash
  929. # Start the development dashboard
  930. fish run.fish dev-dashboard
  931. # Reconnect to existing session from another terminal
  932. tmux attach-session -t r3bl
  933. # Kill the session when done
  934. tmux kill-session -t r3bl
  935. ```
  936. **Comparison: Standalone vs Tmux Dashboard:**
  937. | Aspect | `./check.fish --watch` | Tmux Dashboard |
  938. | ---------------------- | ----------------------------------- | ---------------------------------- |
  939. | **Setup Complexity** | Single command, one window | `tmux` session with 2 panes |
  940. | **Screen Real Estate** | Minimal (one terminal) | Standard (vertical split) |
  941. | **Monitoring Scope** | Comprehensive (tests+docs+doctests) | Documentation focused + open shell |
  942. | **Visual Separation** | Sequential output in one stream | Parallel output in dedicated panes |
  943. | **Ideal For** | Focused development, laptop screens | Continuous documentation feedback |
  944. | **Tmux Knowledge** | Not required | Helpful for navigation |
  945. | **Resource Usage** | Lower (one monitor) | Moderate (monitoring + open shell) |
  946. | **Event-Driven** | Yes (file system events) | Yes (top pane) |
  947. **When to use each:**
  948. - **Use standalone watch**: When you want simple, focused monitoring of tests and docs in
  949. a single terminal.
  950. - **Use tmux dashboard**: When you want continuous documentation feedback while
  951. maintaining an open shell for commands.
  952. Both approaches use the `check.fish` script in different contexts - standalone for
  953. comprehensive monitoring, integrated for a focused documentation dashboard.
  954. ### Cross-Platform Verification (Windows)
  955. This project uses platform-specific code gates (`#[cfg(unix)]`, `#[cfg(not(unix))]`) for
  956. Unix-specific functionality like terminal I/O. To verify these gates compile correctly on
  957. Windows without needing a full Windows cross-compiler (mingw-w64), we use Rust's
  958. metadata-only compilation.
  959. **How It Works:**
  960. The `--emit=metadata` flag tells `rustc` to stop after type checking and MIR generation,
  961. skipping code generation and linking entirely. This validates all platform-specific `cfg`
  962. gates without needing a linker for the target platform.
  963. ```bash
  964. # Verify Windows cross-compilation
  965. fish run.fish check-windows-build
  966. # Or run directly:
  967. cargo rustc -p r3bl_tui --target x86_64-pc-windows-gnu -- --emit=metadata
  968. ```
  969. **Prerequisites:**
  970. The Windows target is automatically installed by `fish run.fish install-cargo-tools`. To
  971. install manually:
  972. ```bash
  973. rustup target add x86_64-pc-windows-gnu
  974. ```
  975. **When to Use:**
  976. - After modifying `#[cfg(unix)]` or `#[cfg(not(unix))]` conditional compilation gates
  977. - Before committing platform-specific code changes
  978. - As part of CI/CD for cross-platform verification
  979. - When adding new platform-specific modules or functions
  980. **Example Output:**
  981. ```text
  982. Verifying Windows cross-compilation for r3bl_tui...
  983. Target: x86_64-pc-windows-gnu
  984. Mode: metadata only (no linking required)
  985. βœ… Windows cross-compilation check passed
  986. Platform-specific cfg gates compile correctly for Windows.
  987. ```
  988. **Technical Details:**
  989. | Aspect | Description |
  990. | ------------------- | ---------------------------------------------------------------- |
  991. | **Target** | `x86_64-pc-windows-gnu` (Windows with GNU toolchain ABI) |
  992. | **Compilation** | Stops at MIR stage (`--emit=metadata`), no object code generated |
  993. | **Linking** | Not required - no mingw-w64 or Windows SDK needed |
  994. | **What's Verified** | Syntax, types, trait bounds, cfg gate correctness |
  995. | **What's NOT** | Runtime behavior, Windows-specific API calls, linking errors |
  996. This approach catches the most common cross-platform issues (missing cfg gates, type
  997. mismatches in platform-specific code) with minimal setup overhead.
  998. > **Platform Backends**: The TUI crate supports multiple backends: `Crossterm`
  999. > (cross-platform, default on macOS/Windows) and `DirectToAnsi` (provided by `r3bl_tui`
  1000. > itself, Linux-native, ~18% better performance). We use cfg gates to ensure the selection
  1001. > of the correct backend for supported platforms. See [Platform-Specific Backends] for
  1002. > details.
  1003. ### Rust Toolchain Management
  1004. This project includes three complementary scripts for comprehensive Rust toolchain
  1005. management, each serving a specific purpose in the development workflow.
  1006. **Concurrency Safety:** Toolchain **modification** scripts (`rust-toolchain-update.fish`
  1007. and `rust-toolchain-sync-to-toml.fish`) use `mkdir` (atomic directory creation) to ensure
  1008. only one toolchain modification runs at a time. **Validation** scripts
  1009. (`rust-toolchain-validate.fish` and `check.fish`) are lock-free since they only read
  1010. toolchain state - multiple validations can run concurrently without conflict.
  1011. #### Why mkdir for Locking?
  1012. The key insight is understanding **atomicity** - when a system operation must
  1013. check-and-act in a way that's guaranteed to be indivisible:
  1014. **The Problem with File Existence Checks:**
  1015. Traditional approaches try to check if a lock exists, then create it:
  1016. ```bash
  1017. # UNSAFE - Race condition!
  1018. if [ ! -f lock ]; then
  1019. echo "timestamp" > temp
  1020. mv temp lock # TOCTOU race between check and move
  1021. fi
  1022. ```
  1023. Between the check (`[ ! -f lock ]`) and the move (`mv temp lock`), another process can
  1024. slip in and also acquire the lock. This is called a **Time-Of-Check-Time-Of-Use (TOCTOU)
  1025. race condition**.
  1026. **How mkdir Works - Atomic Check-and-Create:**
  1027. `mkdir` is different. It combines the check and create into ONE indivisible kernel
  1028. operation:
  1029. ```bash
  1030. # SAFE - Atomic operation
  1031. mkdir lock_dir # Check AND create in ONE kernel operation
  1032. # Only ONE process succeeds; all others fail
  1033. ```
  1034. When `mkdir` runs, the kernel does:
  1035. 1. **Check**: Does the directory exist?
  1036. 2. **Create**: If not, create it
  1037. 3. **Return**: With ONE atomic operation - not two separate steps
  1038. Even with perfect timing and multiple processes starting simultaneously, only ONE can
  1039. create the directory.
  1040. **Technical Implementation:**
  1041. ```fish
  1042. # In script_lib.fish
  1043. if mkdir ./rust-toolchain-script.lock 2>/dev/null
  1044. # Lock acquired - this process has exclusive access
  1045. else
  1046. # Lock held by another process
  1047. fi
  1048. ```
  1049. **Key Advantages:**
  1050. - **Atomic**: Check-and-create in ONE kernel operation (impossible to race)
  1051. - **Simple**: No file descriptors or special handling needed
  1052. - **Reliable**: Works on all Unix systems (standard POSIX behavior)
  1053. - **Stale lock detection**: Automatically removes locks older than 10 minutes (crashed
  1054. processes)
  1055. - **Crash-safe**: Abandoned locks are auto-cleaned after 10 minutes, or manually via
  1056. `rm -rf rust-toolchain-script.lock`
  1057. The locking mechanism uses:
  1058. - **mkdir (atomic directory creation)**: Creates lock directory atomically - succeeds for
  1059. one process, fails for all others
  1060. - **Atomic kernel operation**: Check-and-create happens as ONE indivisible operation - the
  1061. definition of mutual exclusion
  1062. - **Timestamp tracking**: Stores creation time in `rust-toolchain-script.lock/timestamp`
  1063. for age tracking
  1064. - **Stale lock detection**: Checks lock age on collision - auto-removes if older than 10
  1065. minutes (600 seconds)
  1066. - **Lock holder cleanup**: Process that acquired lock removes directory (including
  1067. timestamp) when done
  1068. - **Conflict detection**: Failed mkdir indicates lock is held - shows age for transparency
  1069. - **Standard Unix pattern**: Used by systemd, init systems, and most Unix tools
  1070. #### 1. `rust-toolchain-update.fish` - Smart Validated Toolchain Updates
  1071. Intelligently finds and validates a stable nightly toolchain, preferring older versions
  1072. for stability while ensuring they don't have ICE (Internal Compiler Error) bugs.
  1073. ```bash
  1074. # Via run.fish command
  1075. fish run.fish toolchain-update
  1076. # Or directly
  1077. ./rust-toolchain-update.fish
  1078. ```
  1079. **What it does:**
  1080. - **Smart search**: Tests nightly toolchains starting from 45 days ago, moving forward
  1081. day-by-day until finding a stable one (up to today)
  1082. - **ICE validation**: Runs comprehensive validation suite on each candidate:
  1083. - `cargo clippy --all-targets`
  1084. - `cargo build`
  1085. - `cargo test --all-targets`
  1086. - `cargo test --doc`
  1087. - `cargo doc --workspace --no-deps`
  1088. - **Toolchain vs code errors**: Distinguishes between:
  1089. - ❌ **ICE errors** (compiler crashes) β†’ rejects toolchain, tries next day
  1090. - βœ… **Code errors** (compilation/test failures) β†’ accepts toolchain (validates
  1091. compiler works, not your code)
  1092. - **First stable wins**: Stops at the first toolchain without ICE errors (usually finds
  1093. stable toolchain in first attempt)
  1094. - **Updates** `rust-toolchain.toml` to use the validated stable nightly
  1095. - Installs the target toolchain with `rust-analyzer` component (required by IDEs and
  1096. `cargo`)
  1097. - **Desktop notifications** (via `notify-send`):
  1098. - πŸŽ‰ Success notification when stable toolchain found (normal urgency)
  1099. - 🚨 Critical alert if no stable toolchain found in entire 45-day window (extremely
  1100. rare)
  1101. - Performs aggressive cleanup by removing all old nightly toolchains except:
  1102. - All stable toolchains (`stable-*`)
  1103. - The newly validated nightly
  1104. - **Final verification with fresh build**:
  1105. - Removes ICE failure files (`rustc-ice-*.txt`) generated during validation
  1106. - Cleans all caches: `cargo` cache, build artifacts
  1107. - Runs full verification: tests, doctests, and documentation build
  1108. - Ensures new toolchain works perfectly from scratch
  1109. - Logs all operations to `/home/nazmul/Downloads/rust-toolchain-update.log`
  1110. **When to use:**
  1111. - Weekly maintenance (can be automated via `systemd` timer)
  1112. - When you want to update to a validated stable nightly
  1113. - When you want to clean up old toolchains
  1114. - After encountering ICE errors with current toolchain
  1115. **Example output:**
  1116. ```text
  1117. ═══════════════════════════════════════════════════════
  1118. Starting search for stable toolchain
  1119. Strategy: Start 45 days ago, try progressively newer up to today
  1120. Search window: 2025-08-29 to 2025-10-13
  1121. ═══════════════════════════════════════════════════════
  1122. Attempt 1/46
  1123. Trying toolchain: nightly-2025-08-29 (45 days ago)
  1124. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1125. Validating toolchain: nightly-2025-08-29
  1126. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1127. Running validation step: `clippy`
  1128. ⚠️ Command exited with code 101 (this is OK if not ICE)
  1129. βœ… No ICE detected - continuing validation
  1130. ...
  1131. βœ… Toolchain nightly-2025-08-29 is STABLE (no ICE detected)
  1132. πŸŽ‰ FOUND STABLE TOOLCHAIN: nightly-2025-08-29
  1133. Success notification sent
  1134. βœ… Successfully updated `rust-toolchain.toml`
  1135. βœ… Successfully installed `rust-analyzer` component
  1136. Removed 2 old toolchain(s)
  1137. Toolchains directory size before cleanup: 5.3G
  1138. Toolchains directory size after cleanup: 2.6G
  1139. ```
  1140. #### 2. `rust-toolchain-sync-to-toml.fish` - Sync to Existing Config
  1141. Syncs your Rust environment to match whatever is specified in `rust-toolchain.toml`.
  1142. ```bash
  1143. # Via run.fish command
  1144. fish run.fish toolchain-sync
  1145. # Or directly
  1146. ./rust-toolchain-sync-to-toml.fish
  1147. ```
  1148. **What it does:**
  1149. - **Reads** the channel value from `rust-toolchain.toml` (doesn't modify it)
  1150. - Installs the exact toolchain specified in the TOML
  1151. - Installs `rust-analyzer` and `rust-src` components automatically (required by IDEs and
  1152. `cargo`)
  1153. - Performs aggressive cleanup by removing all old nightly toolchains except:
  1154. - All stable toolchains (`stable-*`)
  1155. - The target toolchain from the TOML
  1156. - Logs all operations to `/home/nazmul/Downloads/rust-toolchain-sync-to-toml.log`
  1157. **When to use:**
  1158. - After `git checkout/reset/pull` changes `rust-toolchain.toml`
  1159. - When `rust-analyzer` is missing for the current toolchain
  1160. - When your IDE shows "`rust-analyzer` failed to start"
  1161. - After manually editing `rust-toolchain.toml`
  1162. - When you need to stay on a specific nightly version
  1163. **Key difference from update script:**
  1164. - **This script (sync)**: Respects TOML β†’ Installs what's specified
  1165. - **Update script**: Modifies TOML β†’ Installs "1 month ago" nightly
  1166. **Example workflow:**
  1167. ```bash
  1168. # Weekly script updates TOML to nightly-2025-09-11
  1169. # But you need to stay on nightly-2025-09-05 for testing a specific feature
  1170. git checkout rust-toolchain.toml # Revert to 09-05
  1171. fish run.fish toolchain-sync # Install components for 09-05
  1172. # Now rust-analyzer works for 09-05
  1173. ```
  1174. #### 3. `rust-toolchain-validate.fish` - Unified Toolchain Validation
  1175. Consolidated validation script providing two modes: quick component check or comprehensive
  1176. build+test validation.
  1177. ```bash
  1178. # Quick mode: Fast component check (~1-2 seconds)
  1179. fish run.fish toolchain-validate
  1180. ./rust-toolchain-validate.fish quick
  1181. # Complete mode: Full build+test validation (~5-10 minutes)
  1182. fish run.fish toolchain-validate-complete
  1183. ./rust-toolchain-validate.fish complete
  1184. # View detailed help
  1185. ./rust-toolchain-validate.fish
  1186. ```
  1187. **Mode Comparison:**
  1188. | Aspect | Quick Mode | Complete Mode |
  1189. | ----------------- | ----------------------------------------- | ------------------------------------ |
  1190. | **Time** | ~1-2 seconds | ~5-10 minutes |
  1191. | **Purpose** | Component verification | Stability verification |
  1192. | **Use Case** | Fast health checks | Pre-nightly validation |
  1193. | **Checks** | Installation + components + `rustc` works | Full build + `clippy` + tests + docs |
  1194. | **ICE Detection** | No | Yes (critical for nightly selection) |
  1195. **Quick Mode Validation:**
  1196. - βœ… Toolchain is installed via `rustup`
  1197. - βœ… `rustup` profile is `default` or `complete`
  1198. - βœ… `rust-analyzer` component is present
  1199. - βœ… `rust-src` component is present
  1200. - βœ… `rustc --version` works (not corrupted)
  1201. **Complete Mode Validation:**
  1202. - βœ… All quick mode checks
  1203. - βœ… `cargo clippy --all-targets` (no ICE)
  1204. - βœ… `cargo build` (no ICE)
  1205. - βœ… `cargo test --all-targets` (no ICE)
  1206. - βœ… `cargo test --doc` (no ICE)
  1207. - βœ… `cargo doc --workspace --no-deps` (no ICE)
  1208. **Return Codes:**
  1209. - `0`: βœ… Valid (quick) or Stable (complete)
  1210. - `1`: ❌ Not installed (quick) or ICE detected (complete)
  1211. - `2`: ⚠️ Missing components (quick only)
  1212. - `3`: ❌ Toolchain corrupted (quick only)
  1213. - `4`: ❌ Failed to read `rust-toolchain.toml`
  1214. - `5`: ❌ Wrong `rustup` profile (quick only)
  1215. **When to use Quick Mode:**
  1216. - After installing/repairing toolchain with `sync-toolchain`
  1217. - Troubleshooting IDE issues (`rust-analyzer` not working?)
  1218. - Pre-flight check before running tests
  1219. - Regular health monitoring
  1220. - Part of automated CI/CD pipelines
  1221. **When to use Complete Mode:**
  1222. - Verifying nightly toolchain stability before using it
  1223. - Detecting Internal Compiler Errors (ICE) in compiler
  1224. - Before committing code with new toolchain
  1225. - During `toolchain-update` search (finding stable nightly)
  1226. - After major Rust version updates
  1227. **Integration with other toolchain scripts:**
  1228. - **`check.fish`**: Uses quick mode to check toolchain before running tests; calls
  1229. `toolchain-sync` if invalid
  1230. - **`rust-toolchain-sync-to-toml.fish`**: Performs quick validation after installing
  1231. components
  1232. - **`rust-toolchain-update.fish`**: Uses complete mode to find stable nightly
  1233. #### 4. `remove_toolchains.sh` - Testing Utility
  1234. Removes ALL Rust toolchains for testing upgrade progress display (⚠️ DESTRUCTIVE).
  1235. ```bash
  1236. ./remove_toolchains.sh
  1237. ```
  1238. **What it does:**
  1239. - Removes ALL Rust toolchains from your system
  1240. - Cleans up toolchain directories completely
  1241. - Creates a clean slate for testing `rustup` installation progress
  1242. **When to use:**
  1243. - When developing/testing the upgrade progress display in `edi` and `giti`
  1244. - To see full `rustup` download and installation progress
  1245. - For testing `cmdr/src/analytics_client/upgrade_check.rs` functionality
  1246. **Recovery after testing:**
  1247. ```bash
  1248. `rustup toolchain install stable && rustup default stable`
  1249. # Or
  1250. fish run.fish toolchain-update
  1251. ```
  1252. **⚠️ Warning:** This is a destructive testing utility. Use only when you understand the
  1253. implications and are prepared to reinstall toolchains.
  1254. #### Log File Output
  1255. All toolchain management scripts display detailed log file locations to `stdout` at
  1256. startup:
  1257. ```
  1258. πŸ“‹ Detailed log: /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log
  1259. ```
  1260. This makes it easy to monitor progress and check detailed logs after operations complete:
  1261. ```bash
  1262. # Watch logs in real-time
  1263. tail -f /home/nazmul/Downloads/rust-toolchain-update.log
  1264. # Or review after completion
  1265. cat /home/nazmul/Downloads/rust-toolchain-sync-to-toml.log
  1266. ```
  1267. #### Comprehensive Toolchain Management System
  1268. The four scripts work together to provide a complete toolchain management solution:
  1269. **Four complementary scripts:**
  1270. - **validate** (`rust-toolchain-validate.fish`): Non-destructive validation of current
  1271. toolchain
  1272. - **update** (`rust-toolchain-update.fish`): Smart search for stable nightly with
  1273. comprehensive validation
  1274. - **sync** (`rust-toolchain-sync-to-toml.fish`): Install toolchain matching
  1275. rust-toolchain.toml
  1276. - **remove** (`remove_toolchains.sh`): Testing utility to clean all toolchains
  1277. (destructive)
  1278. **Key benefits:**
  1279. - **Stability**: Month-old nightlies have proven stability while providing recent features
  1280. - **Disk space savings**: Aggressive cleanup removes accumulated old toolchains
  1281. - **Consistency**: All developers use the same Rust version via `rust-toolchain.toml`
  1282. - **Automation ready**: `update` script designed to run weekly via systemd timer
  1283. - **Recovery ready**: `sync` script fixes environment after git operations
  1284. - **Validation ready**: `validate` script enables automated health checks in CI/CD
  1285. pipelines
  1286. - **Testing support**: `remove` script enables testing upgrade workflows
  1287. - **Integrated monitoring**: `check.fish` automatically validates and repairs toolchain
  1288. before running tests
  1289. ### Unified Script Architecture
  1290. The project uses a clean separation of concerns across three main scripts with shared
  1291. utilities:
  1292. ```
  1293. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  1294. β”‚ Bootstrap Flow β”‚
  1295. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1296. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” calls β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  1297. β”‚ bootstrap.sh │──────────────►│ fish run.fish install-cargo-tools β”‚
  1298. β”‚ (OS-level) β”‚ β”‚ (Rust development tools) β”‚
  1299. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1300. β”‚ β”‚
  1301. β”‚ installs β”‚ uses
  1302. β–Ό β–Ό
  1303. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  1304. β”‚ rustup, β”‚ β”‚ script_lib.fish β”‚
  1305. β”‚ fish, fzf, β”‚ β”‚ (shared utility functions) β”‚
  1306. β”‚ inotify-tools β”‚ β”‚ β”‚
  1307. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β€’ install_windows_target β”‚
  1308. β”‚ β€’ install_if_missing β”‚
  1309. β”‚ β€’ install_cargo_tool β”‚
  1310. β”‚ β€’ read_toolchain_from_toml β”‚
  1311. β”‚ β€’ acquire_toolchain_lock β”‚
  1312. β”‚ β€’ ... 25+ shared functions β”‚
  1313. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1314. β–²
  1315. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  1316. β”‚ β”‚ β”‚
  1317. β”‚ sources β”‚ sources β”‚ sources
  1318. β”‚ β”‚ β”‚
  1319. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  1320. β”‚ run.fish β”‚ β”‚ rust-toolchain-update.fish β”‚ β”‚ rust-toolchain-sync- β”‚
  1321. β”‚ (dev commands) β”‚ β”‚ (smart toolchain updater) β”‚ β”‚ to-toml.fish β”‚
  1322. β”‚ β”‚ β”‚ β”‚ β”‚ (sync to TOML) β”‚
  1323. β”‚ β€’ build, test, docs β”‚ β”‚ β€’ install_windows_target β”‚ β”‚ β”‚
  1324. β”‚ β€’ clippy, rustfmt β”‚ β”‚ β€’ acquire_toolchain_lock β”‚ β”‚ β€’ install_windows_ β”‚
  1325. β”‚ β€’ install-cargo-toolsβ”‚ β”‚ β€’ read_toolchain_from_toml β”‚ β”‚ target β”‚
  1326. β”‚ (calls install_ β”‚ β”‚ β€’ set_toolchain_in_toml β”‚ β”‚ β€’ acquire_toolchain_ β”‚
  1327. β”‚ windows_target) β”‚ β”‚ β€’ ... β”‚ β”‚ lock β”‚
  1328. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1329. ```
  1330. **Key DRY Principle**: All shared functionality lives in `script_lib.fish`. Individual
  1331. scripts source this library and call shared functions, ensuring consistent behavior and
  1332. eliminating code duplication. When a function like `install_windows_target` needs
  1333. updating, it only needs to be changed in one place.
  1334. **[`bootstrap.sh`]** - **OS-Level Setup**
  1335. - System package manager detection and OS dependencies
  1336. - Rust toolchain installation via `rustup`
  1337. - Development environment setup (`Fish` shell, `fzf`, file watchers)
  1338. - Cross-platform compatibility (**Linux**, **macOS**)
  1339. - Calls `run.fish` for Rust-specific `cargo` tooling
  1340. **[`run.fish`]** - **Rust Development Commands**
  1341. - **Workspace-wide commands** that operate on the entire project
  1342. - **Cargo tool installation** (`install-cargo-tools` with `cargo-binstall`, `uv`, `bacon`,
  1343. etc.)
  1344. - **TUI-specific commands** for running examples and benchmarks
  1345. - **cmdr-specific commands** for binary management
  1346. - **Cross-platform file watching** using `inotifywait` (**Linux**) or `fswatch`
  1347. (**macOS**)
  1348. - **Smart log monitoring** that detects and manages log files from different workspaces
  1349. **[`script_lib.fish`]** - **Shared Utilities**
  1350. - Common functions used by both `bootstrap.sh` and `run.fish`
  1351. - Utility functions: `install_if_missing`, `install_cargo_tool`
  1352. - Cross-platform package manager detection
  1353. All commands work from the root directory, eliminating the need to navigate between
  1354. subdirectories. This architecture ensures no redundancy - each tool is installed in
  1355. exactly one place with clear ownership.
  1356. ## Star History
  1357. ![Star History](./.github/assets/star-history.svg)
  1358. ## Origin Story
  1359. After leaving Google in 2021, I ([Nazmul Idris]) embarked on a journey to create
  1360. infrastructure for modern, powerful, async CLI and TUI experiences.
  1361. I initially tried [`Node.js`] with [`ink`], but encountered fundamental limitations:
  1362. - Module incompatibilities and dependency conflicts.
  1363. - Limited control over keybindings and terminal behavior.
  1364. - High resource consumption for simple tasks.
  1365. - Screen flickering and poor rendering performance.
  1366. Since I couldn't find the framework and toolkit of my dreams, I decided to build it myself
  1367. from scratch in Rust.
  1368. The core architectural innovation: a purely async, immediate mode reactive UI (every state
  1369. change triggers a render from scratch) where nothing blocks the main thread - unlike
  1370. traditional approaches using platform-specific blocking operations like GNU [`readline`]
  1371. on Linux/macOS or Windows [`ReadConsole()`].
  1372. This fully async, responsive framework works seamlessly across Linux, macOS, and Windows.
  1373. It's optimized for use over SSH connections by painting only diffs, and handles complex
  1374. concurrent operations with low latency while ensuring no thread blocking.
  1375. ## Archive
  1376. As this repo grows, changes, and matures, pruning is necessary. The
  1377. [`r3bl-open-core-archive`] is where all the code and artifacts that are no longer needed
  1378. are moved to.
  1379. This way nothing is "lost" and if you need to use some of the code that was removed, you
  1380. can find it there.
  1381. Also if you want to make changes to this code and maintain it yourself, please let us
  1382. know.
  1383. 1. You can submit PRs and we can also accept them, and publish them to `crates.io` if that
  1384. makes sense.
  1385. 2. Or we can even work out and arrangements to move ownership of the code & crate to you
  1386. if you would like to commit to maintaining it.
  1387. <!-- Ref Def Links -->
  1388. [Nazmul Idris]: https://developerlife.com/about-me/
  1389. [`readline`]: https://manpages.debian.org/readline.3
  1390. [`ReadConsole()`]: https://learn.microsoft.com/en-us/windows/console/readconsole
  1391. [`vim`]: https://www.vim.org/
  1392. [`neovim`]: https://neovim.io/
  1393. [`ratatui`]: https://ratatui.rs/
  1394. [`Node.js`]: https://nodejs.org/
  1395. [`ink`]: https://developerlife.com/2021/11/25/ink-v3-advanced-ui-components/
  1396. [flexbox]:
  1397. https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_flexible_box_layout/Basic_concepts_of_flexbox
  1398. [declarative]: https://ui.dev/imperative-vs-declarative-programming
  1399. [CSS-like]: https://www.w3.org/TR/CSS/#css
  1400. [`React`]: https://react.dev/
  1401. [React]: https://react.dev/
  1402. [Elm]: https://guide.elm-lang.org/architecture/
  1403. [CSS]: https://www.w3.org/TR/CSS/#css
  1404. [SolidJS]: https://www.solidjs.com/
  1405. [iced-rs]: https://docs.rs/iced/latest/iced/
  1406. [Jetpack Compose]: https://developer.android.com/compose
  1407. [JSX]: https://ui.dev/imperative-vs-declarative-programming
  1408. [Tokio]: https://crates.io/crates/tokio
  1409. [Build with Naz: TTY playlist]:
  1410. https://www.youtube.com/playlist?list=PLofhE49PEwmw3MKOU1Kn3xbP4FRQR4Mb3
  1411. [Build with Naz: async readline]:
  1412. https://www.youtube.com/playlist?list=PLofhE49PEwmwelPkhfiqdFQ9IXnmGdnSE
  1413. [`r3bl_tui`]: tui/
  1414. [`r3bl-cmdr`]: cmdr/
  1415. [`r3bl-rust-analyzer-mcp-server`]: rust-analyzer-mcp-server/
  1416. [`r3bl-build-infra`]: build-infra/
  1417. [`r3bl_analytics_schema`]: analytics_schema/
  1418. [origin story]: #origin-story
  1419. [monorepo]: https://en.wikipedia.org/wiki/Monorepo
  1420. [crate]: https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html
  1421. [crates.io]: https://crates.io/crates/r3bl_tui
  1422. [Rust workspace]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
  1423. [changelog]: https://github.com/r3bl-org/r3bl-open-core/blob/main/CHANGELOG.md
  1424. [`tui`]: https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/src/tui
  1425. [`choose`]:
  1426. https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/choose_api.rs
  1427. [`readline_async`]:
  1428. https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/readline_async/readline_async_api.rs
  1429. [`tcp-api-server`]: https://github.com/nazmulidris/rust-scratch/tree/main/tcp-api-server
  1430. [`tui/examples`]: https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples
  1431. [`PTYMux`]:
  1432. https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/core/pty/pty_mux/mux.rs
  1433. [`PTYMux::run()`]:
  1434. https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/core/pty/pty_mux/mux.rs
  1435. [`GrowableBuffer`]:
  1436. https://github.com/r3bl-org/r3bl-open-core/blob/main/tui/src/tui/terminal_lib_backends/ofs_buf/storage/impls/growable_buffer.rs
  1437. [`pty_mux_example`]:
  1438. https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples/pty_mux_example.rs
  1439. [`./task/`]: https://github.com/r3bl-org/r3bl-open-core/tree/main/task
  1440. [`./task/AGENTS.md`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/task/AGENTS.md
  1441. [`AGENTS.md: task-tracking-system`]:
  1442. https://github.com/r3bl-org/r3bl-open-core/blob/main/AGENTS.md#task-tracking-system
  1443. [R3BL VSCode Extensions]: #r3bl-vscode-extensions
  1444. [research shows]:
  1445. https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/why-good-docs-matter.md
  1446. [RFC 1824]: https://rust-lang.github.io/rfcs/1824-crates.io-default-ranking.html
  1447. [2024 study]: https://arxiv.org/html/2403.03819v1
  1448. [machine-enforced]:
  1449. https://github.com/r3bl-org/r3bl-open-core/blob/main/.agents/skills/write-documentation/SKILL.md
  1450. [Pedagogical Links for Inclusivity]:
  1451. https://github.com/r3bl-org/r3bl-open-core/blob/main/.agents/skills/write-documentation/SKILL.md#pedagogical-links-for-inclusivity
  1452. [`docs/`]: https://github.com/r3bl-org/r3bl-open-core/tree/main/docs
  1453. [`why-good-docs-matter.md`]:
  1454. https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/why-good-docs-matter.md
  1455. [`release-guide.md`]:
  1456. https://github.com/r3bl-org/r3bl-open-core/blob/main/docs/release-guide.md
  1457. [`CONTRIBUTING.md`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/CONTRIBUTING.md
  1458. [YT channel]: https://www.youtube.com/@developerlifecom
  1459. [subscribing]: https://www.youtube.com/channel/UCMcsxfCwzwDevc3NRqFgfEg?sub_confirmation=1
  1460. [`bootstrap.sh`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/bootstrap.sh
  1461. [automated-setup-recommended]: #automated-setup-recommended
  1462. [`./check.fish`]: #automated-development-monitoring
  1463. [unified-script-architecture]: #unified-script-architecture
  1464. [bacon-development-tools]: #bacon-development-tools
  1465. [`build-infra/`]: build-infra/README.md
  1466. [`skills`]: .agents/skills/
  1467. [`AGENTS.md`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/AGENTS.md
  1468. [crates.io: r3bl-rust-analyzer-mcp-server]:
  1469. https://crates.io/crates/r3bl-rust-analyzer-mcp-server
  1470. [`fish`]: https://fishshell.com/
  1471. [`run.fish`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/run.fish
  1472. [PTY Testing Infrastructure]: ./tui/README.md#pty-testing-infrastructure
  1473. [bacon]: https://dystroy.org/bacon/
  1474. [Platform-Specific Backends]: ./tui/README.md#platform-specific-backends
  1475. [`script_lib.fish`]: https://github.com/r3bl-org/r3bl-open-core/blob/main/script_lib.fish
  1476. [`r3bl-open-core-archive`]: https://github.com/r3bl-org/r3bl-open-core-archive
  1477. [`curses`]: https://en.wikipedia.org/wiki/Curses_(programming_library)
  1478. [`ncurses`]: https://en.wikipedia.org/wiki/Ncurses
  1479. [`Shift+Enter`]:
  1480. https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#terminal-setup
  1481. [Kitty keyboard protocol]: https://github.com/vadimdemedes/ink/pull/855
  1482. [loosely coupled and strongly coherent]:
  1483. https://developerlife.com/2015/11/05/loosely-coupled-strongly-coherent/
  1484. [unidirectional data flow]: https://guide.elm-lang.org/architecture/
  1485. [responsive]:
  1486. https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design
  1487. [`tmux`]: https://github.com/tmux/tmux
  1488. [FUNARCH 2023 paper]: https://dl.acm.org/doi/epdf/10.1145/3609025.3609477
  1489. [FUNARCH 2026 paper]: https://dl.acm.org/doi/epdf/10.1145/3830438.3830958
  1490. [Parse, don't validate]:
  1491. https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
  1492. [make illegal states unrepresentable]: https://corrode.dev/blog/illegal-state/
  1493. [High-Performance Flat 2D Arrays in Rust (SIMD, L1 Cache)]:
  1494. https://developerlife.com/2026/07/14/build-high-performance-flat-2d-arrays-in-rust/
  1495. [Rust, Memory performance & latency]:
  1496. https://developerlife.com/2025/05/19/rust-mem-latency/

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.