pixtuoid rust.instructions.md

Rust standards — pixtuoid

These apply to all Rust in this Cargo workspace. The authoritative source is the root CLAUDE.md and the nested crates/*/CLAUDE.md — read those for the architecture invariants. Many things that look like a bug are documented, load-bearing design — read the item's own doc comment. This file is the condensed coding-standard slice.

Errors & panics

• No unwrap() / expect() in non-test code. Tests may unwrap freely.
• App/binary code propagates errors via anyhow::Result. Core (pixtuoid-core) reaches for thiserror only when a typed error becomes load-bearing.
• The hook listener and JSONL watcher log and continue on malformed input — they never panic.
• The hook shim must always exit 0 silently on any error — blocking Claude Code breaks the user's primary workflow. The 200 ms write timeout is non-negotiable.

Crate boundaries (load-bearing)

• pixtuoid-core and pixtuoid-scene have no terminal/window dependencies — never add ratatui, crossterm, winit, softbuffer, or stdout/println! there (the crate boundary + just arch enforce it). Terminal/window code lives only in the pixtuoid binary's painters over the engine's render seam (pixtuoid_scene::floor::render_floor / pixel_painter::render_to_rgb_buffer). There is no core render trait.
• Events flow through one channel typed mpsc::Sender<(Transport, AgentEvent)>. Don't hardcode Transport::Hook on the consumer side — each Source tags its own events.
• The Source trait is the only seam for adding agent CLIs. Don't bypass it.

Logging

• Use tracing::{info, warn, error} — not println!/eprintln!. The only exceptions are the headless summary and explicit user-facing CLI output.

Tests (TDD-first)

• Write the failing test before the implementation. Don't add code without a test that exercises it.
• Unit tests: #[cfg(test)] mod tests next to the code, or a sibling tests.rs declared #[cfg(test)] mod tests; for large modules (keeps production readable without widening the API).
• Integration / public-contract tests live in crates/<crate>/tests/*.rs (they see only the pub API).
• Run the suite with just test (nextest). Scope with cargo nextest run -p <crate> <filter> while iterating. Don't chain cargo clippy && cargo test — they use separate build caches, so chaining recompiles the workspace twice. Run just preflight or one check at a time.