lesavka/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- `common/`: tonic/prost definitions; edit `proto/lesavka.proto` and let `build.rs` regenerate bindings.
- `server/`: gRPC relay and media handling; entrypoint `src/main.rs`; integration tests in `server/tests`.
- `client/`: GTK + GStreamer desktop agent; input adapters live in `src/input`, UVC output in `src/output`, helpers/tests in `src/tests`.
- `scripts/`: `install/` provisioning for Arch-based hosts, `daemon/lesavka-core.sh` systemd entrypoint, `manual/` diagnostics (VPN, USB reset, media capture).

## Build, Test, and Development Commands
- Formatting: `cargo fmt --all --manifest-path client/Cargo.toml` (repeat for `server`/`common`).
- Linting: `cargo clippy --all-targets --manifest-path server/Cargo.toml -D warnings` (run for client too).
- Build: `cargo build --all-targets --manifest-path server/Cargo.toml` and `cargo build --all-targets --manifest-path client/Cargo.toml`; building either pulls `common`.
- Tests: `cargo test --manifest-path server/Cargo.toml` runs async RPC tests; `cargo test --manifest-path client/Cargo.toml` covers keymap/unit cases.
- Runtime: `cargo run --manifest-path server/Cargo.toml` to start the relay; `LESAVKA_SERVER_ADDR=<host:port> cargo run --manifest-path client/Cargo.toml` to point the client at a server.
- Provisioning: `scripts/install/server.sh` and `scripts/install/client.sh` install dependencies and systemd units; rerun after changing installers or binary names.

## Coding Style & Naming Conventions
- Rust 2024 with four-space indentation; `snake_case` for functions/modules, `CamelCase` for types and Protobuf messages.
- Keep RPC shapes defined in `common/proto/lesavka.proto`; never hand-edit generated code in `target/` or `OUT_DIR`.
- Prefer tonic streaming APIs over manual channels; keep GStreamer/GTK wiring in small helpers to avoid sprawling `main.rs`.
- Use `tracing` consistently; default `RUST_LOG=info,lesavka=debug` for local runs.

## Testing Guidelines
- Async integration tests mirror `server/tests/hid.rs` using `#[tokio::test]` and an in-process tonic server/client pair.
- Place client unit tests next to modules (`client/src/tests`); name cases after behavior (`keycode_to_usage_maps_letters`, `hid_roundtrip`).
- For new RPCs, add end-to-end assertions for request/response, stream termination, and error paths; prefer deterministic timeouts over sleeps.

## Commit & Pull Request Guidelines
- Git history favors short, imperative subjects (`"install mic deps"`, `"client: improve mic defaults"`); keep each commit focused.
- Before opening a PR, run fmt, clippy, and tests for client and server; note any manual steps or env vars used (`LESAVKA_SERVER_ADDR`, `LESAVKA_UVC_DEV`, `LESAVKA_UAC_DEV`).
- PR descriptions should summarize intent, attach logs/screenshots when touching media paths, and flag installer/systemd changes so operators can re-run the relevant scripts.