katamari AGENTS.md

AGENTS.md — working on katamari

katamari (ktmr) is a Rust TUI diff-review tool (ratatui + crossterm, std threads — no tokio). This file is for an agent making changes to katamari itself, not for a repo reviewed with katamari — see the marked section below for that.

Build/test

cargo is not on PATH in this environment; every command goes through mise: mise exec -- cargo <args> (or mise run <task> for the tasks in mise.toml: build, test, lint, fmt, e2e, e2e-tmux, release-check, release-check-full).

Three gates must stay green before any change is done:

mise exec -- cargo test                                    # 745+ unit tests
mise exec -- cargo clippy --all-targets -- -D warnings      # includes tests/
mise exec -- cargo fmt --check

docs/ is an Astro Starlight site (deployed to GitHub Pages by .github/workflows/docs.yml on push to main). It needs Node 22 — install one via mise use -g node@22 if node isn't already on PATH — then build from inside docs/:

cd docs
npm ci             # installs from the committed package-lock.json; never `npm install` in CI or here
npm run build      # should build with zero errors; output goes to docs/dist

docs/dist, docs/node_modules, and docs/.astro are all generated and gitignored — never commit them.

Tests

• Unit tests are colocated with the code they cover (#[cfg(test)] mod tests at the bottom of the same file) — put new ones there, not in a separate file.
• tests/e2e.rs + tests/e2e/*.rs: a PTY-driven suite that spawns the real compiled ktmr binary (tests/support/harness.rs) and asserts on the rendered terminal screen — run with mise run e2e. Use this for anything that depends on real terminal/crossterm behavior (kitty keyboard protocol, key sequences, rendering) that in-process App/View tests can't reach.
• scripts/e2e-tmux.sh (mise run e2e-tmux): a real-terminal (tmux) smoke test specifically for the kitty-protocol fallback, which needs an actual terminal emulator behind it rather than a PTY harness.