bstein/lesavka
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lesavka/AGENTS.md

2.9 KiB
Raw Blame History

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.