xserial/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

xserial is a Rust workspace. The root Cargo.toml defines four crates in crates/:

• xserial-core: transport, framing, protocol, and pipeline primitives in src/, with integration tests in tests/pipeline.rs.
• xserial-client: session management, history, commands, and Lua bindings, with integration tests under tests/.
• xserial-tui: terminal app entrypoint in src/main.rs.
• xserial-gui: egui/eframe app, with UI panels in src/panels/ and font helpers in src/ui_fonts.rs.

Use tools/test_plot.py as a local waveform source for GUI plot testing. Treat target/ as generated output.

Build, Test, and Development Commands

• cargo check --workspace: fast compile check for all crates.
• cargo test --workspace: run the workspace test suite, including crates/xserial-core/tests and crates/xserial-client/tests.
• cargo run -p xserial-gui: launch the desktop GUI.
• cargo run -p xserial-tui: launch the terminal UI.
• cargo fmt --all: apply standard Rust formatting.
• cargo clippy --workspace --all-targets -- -D warnings: catch lint issues before review.
• python tools/test_plot.py --help: inspect options for the TCP plot-frame generator.

Coding Style & Naming Conventions

Follow standard Rust formatting: 4-space indentation, trailing commas in multiline literals, and snake_case for modules, files, functions, and tests. Use PascalCase for structs/enums and SCREAMING_SNAKE_CASE for constants. Keep crate boundaries clean: protocol/transport code belongs in xserial-core; session and Lua integration belong in xserial-client; UI state stays in xserial-gui or xserial-tui.

Testing Guidelines

Prefer focused unit tests next to implementation and integration tests in crates/<crate>/tests/*.rs. Name tests after behavior, for example session_lifecycle or pipeline. Run cargo test --workspace before opening a PR; add targeted regression tests for transport, framing, parsing, and session-state fixes.

Commit & Pull Request Guidelines

Recent history uses short, imperative subjects such as Persist GUI font settings and Improve session controls and GUI views, with occasional feat: prefixes for major additions. Keep subjects concise and action-oriented. PRs should state which crate(s) changed, list validation commands, and include screenshots or short recordings for GUI/TUI changes. Call out protocol, transport, or Lua API compatibility impacts explicitly.