tui-test-ghost CLAUDE.md

tui-test-ghost — TUI Testing Toolkit

What This Is

A Zig-native TUI testing toolkit built on Ghostty's ghostty-vt terminal emulation core. Tests TUI applications by spawning them in a PTY, feeding output through a real terminal emulator, and exposing structured screen state for programmatic assertion.

Build Commands

zig build          # Build library + executable
zig build test     # Run all tests
zig build run      # Run MCP server / CLI
just build         # Same via justfile
just test          # Same via justfile
just fmt           # Run zig fmt

Architecture

See PLAN.md for full architecture, milestones, and step definitions.

Data flow: TUI Process → PTY → ReadonlyStream → ghostty-vt Terminal → Screen Query API → MCP/CLI

Threading: Single-threaded with explicit drain. No background threads.

TigerStyle (Mandatory)

Every function in this codebase MUST follow TigerStyle:

1. >=2 assertions per function — pre/postconditions, paired at call+definition sites
2. 70-line function limit — extract helpers, push ifs up and fors down
3. No recursion — all iteration via bounded loops
4. Static allocation — all memory allocated at init, no dynamic allocation after startup
5. Explicitly-sized types — u16, u32, u64, not usize (except where Zig stdlib demands it)
6. Named arguments via options struct when parameters could be confused
7. No hidden control flow — no async callbacks, no background goroutines
8. All errors handled — no _ for errors, wrap with context
9. Compile-time assertions for constant relationships
10. defer for postconditions where applicable

Reference: https://github.com/tigerbeetle/tigerbeetle/blob/main/docs/TIGER_STYLE.md

Key Dependencies

Dependency	Location	What It Provides
ghostty-vt	/Users/home/Documents/Code/ghostty/	Terminal emulation core
Zig 0.15.2	/Users/home/Documents/Code/Zig/0.15.2/	Compiler + stdlib