AGENTS.md

Project Identity

Project Name: ratatui_ruby

Description: A high-performance Ruby wrapper for the Ratatui TUI library.

Architecture:

• Frontend (Ruby): Pure Data objects (Ruby 3.2+) defining the View Tree. Immediate mode.

• Backend (Rust): A generic renderer using ratatui and magnus that traverses the Ruby Data tree and renders to the terminal buffer.

1. File & Coding Standards

Licensing & Copyright (Strict)

Every file must begin with an SPDX-compliant header. Use the following format:

# frozen_string_literal: true

# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
# SPDX-License-Identifier: AGPL-3.0-or-later

• Ruby/Rust/Config files: Use comments appropriate for the language (# or //).

• Markdown: Use HTML comment style <!-- -->.

• Exceptions: REUSE.toml manages exceptions (e.g., binary files or .gitignore).

Ruby Standards

• Version: Tested against the latest releases of Ruby 3.2, 3.3, and 3.4, and must work. Also tested in CI (with allowed failures) against the latest preview Ruby 4.0 to prepare for its release. Local development happens on the latest stable release.

• Linter: Run via rake lint. You are not done until all linting passes.

• Style:

  • Use Data.define for all value objects (UI Nodes). (Prefer class Foo < Data.define() over Foo = Data.define() do).

  • Prefer frozen_string_literal: true.

  • Use Minitest for testing.

  • Define types in .rbs files. Don’t use untyped just because it’s easy; be comprehensive and accurate. Do not include initialize in .rbs files; use self.new for constructors instead.

  • Every line of Ruby must be covered by tests that would stand up to mutation testing. This includes all examples in the examples/ directory; they should have corresponding tests in examples/ to ensure they continue to work as intended and serve as reliable documentation. Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code “doesn’t crash” is insufficient and unacceptable. For UI widgets, this means using with_test_terminal to verify every character of the terminal buffer’s content.

  • Every public Ruby class/method must be documented for humans in RDoc (preferred)–not YARD–or markdown files (fallback), and must have *.rbs types defined.

  • Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.

Rust Standards

• Crate Type: cdylib.

• Linter: clippy and rustfmt.

• Bindings: Use magnus.

• Platform: Support macOS (Apple Silicon), Linux, and Windows.

• Linker Flags: Must handle macOS -undefined dynamic_lookup.

• Every line of Rust must be covered by tests that would stand up to mutation testing. This includes every widget implementation in ext/ratatui_ruby/src/widgets/; each must have a tests module with unit tests verifying basic rendering. Tests must be meaningful; simply verifying that code “doesn’t crash” or “compiles” is insufficient.

2. Directory Structure Convention

The project follows a standard Gem layout with an ext/ directory for Rust code.

/
├── .cargo/                 # Cargo configuration (linker flags)
├── .github/                # CI/CD workflows
├── bin/                    # Executables (console, setup)
├── docs/                   # Documentation tree
│   ├── contributors/       # Design docs, ecosystem notes
│   └── index.md
├── ext/
│   └── ratatui_ruby/       # RUST SOURCE CODE GOES HERE
│       ├── src/
│       │   └── lib.rs      # Entry point
│       ├── Cargo.toml
│       └── extconf.rb      # Makefile generator
├── lib/
│   ├── ratatui_ruby/
│   │   ├── schema/         # Ruby Data definitions
│   │   └── version.rb
│   └── ratatui_ruby.rb     # Main loader
├── test/
│   ├── data/               # Data-driven test files
│   └── ratatui_ruby/       # Unit tests
├── vendor/                 # Vendorized style configs (goodcop)
├── AGENTS.md               # Context for AI agents
├── Gemfile
├── Rakefile
├── REUSE.toml              # Compliance definition
└── ratatui_ruby.gemspec

3. Configuration & Tooling

Development Environment

• Setup: bin/setup must handle both Bundler and Cargo dependencies.

• Pre-commit: Use .pre-commit-config.yaml to enforce rake and cargo fmt.

Documentation

• Follow the docs/ structure: index.md -> contributors/ | quickstart.md.

• Documentation should separate “User Guide” (Ruby API for TUI developers) from “Contributor Guide” (Ruby/Rust/Magnus internals).

• Don’t write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate.

• Never edit the doc/ folder directly. It is automatically generated by rake rerdoc. If you need to refresh the generated documentation, run that command instead.

4. The Ruby <-> Rust Bridge Contract

The Ruby Side (lib/)

• Refer to docs/contributors/design/ruby_frontend.md for detailed design philosophy regarding the Data-Driven UI and Immediate Mode paradigm.

The Rust Side (ext/)

• Refer to docs/contributors/design/rust_backend.md for detailed implementation guidelines, module structure, and rendering logic.

5. Deployment / Release

• The gem builds a native extension.

• Artifact naming: Ensure the output shared library matches Ruby’s expectation on macOS (rename .dylibto .bundle if necessary during the build process in extconf.rb or Rakefile).