mirror of
https://github.com/feschber/lan-mouse.git
synced 2026-03-27 15:10:53 +03:00
4d8f7d7813
* chore: developer experience - pre-commit hook, ai instructions, yaml formatting for prettier * no prettierrc, editorconfig instead * fixes from copilot suggestions --------- Co-authored-by: Ferdinand Schober <ferdinandschober20@gmail.com>
66 lines
3.6 KiB
Markdown
66 lines
3.6 KiB
Markdown
# Lan Mouse Agent Instructions
|
|
|
|
## Overview
|
|
|
|
Lan Mouse is an open-source Software KVM sharing mouse/keyboard input across local networks. The Rust workspace combines a GTK frontend, CLI/daemon mode, and multi-OS capture/emulation backends for Linux, Windows, and macOS.
|
|
|
|
## Core principles
|
|
|
|
- **Scope discipline.** Only implement what was requested; describe follow-up work instead of absorbing it.
|
|
- **Clarify OS behavior.** Ask when requirements touch OS-specific capture/emulation (they differ significantly).
|
|
- **Docs stay current.** Update [README.md](README.md) or [DOC.md](DOC.md) when touching public APIs or platform support.
|
|
- **Rust idioms.** Use `Result`/`Option`, `thiserror` for errors, descriptive logs, and concise comments for non-obvious invariants.
|
|
|
|
## Terminology
|
|
|
|
- **Client:** A remote machine that can receive or send input events. Each client is either _active_ (receiving events) or _inactive_ (can send events back). This mutual exclusion prevents feedback loops.
|
|
- **Backend:** OS-specific implementation for capture or emulation (e.g., libei, layer-shell, wlroots, X11, Windows, macOS).
|
|
- **Handle:** A per-client identifier used to route events and track state (pressed keys, position).
|
|
|
|
## Architecture
|
|
|
|
**Pipeline:** `input-capture` → `lan-mouse-ipc` → `input-emulation`
|
|
|
|
- **input-capture:** Reads OS events into a `Stream<CaptureEvent>`. Backends tried in priority order (libei → layer-shell → X11 → fallback). Tracks `pressed_keys` to avoid stuck modifiers. `position_map` queues events when multiple clients share a screen edge.
|
|
- **input-emulation:** Replays events via the `Emulation` trait (`consume`, `create`, `destroy`, `terminate`). Maintains `pressed_keys` and releases them on disconnect.
|
|
- **lan-mouse-ipc / lan-mouse-proto:** Protocol glue and serialization. Events are UDP; connection requests are TCP on the same port. Version bumps required when serialization changes.
|
|
- **input-event:** Shared scancode enums and abstract event types—extend here, don't duplicate translations.
|
|
|
|
## Feature & cfg discipline
|
|
|
|
- Feature flags live in root `Cargo.toml`. Gate OS-specific modules with tight cfgs (e.g., `cfg(all(unix, feature = "layer_shell", not(target_os = "macos")))`).
|
|
- Prefer module-level gating over per-function cfgs to avoid empty stubs.
|
|
- New backends: add feature in `Cargo.toml`, create gated module, log backend selection.
|
|
|
|
## Async patterns
|
|
|
|
- Tokio runtime with `futures` streams and `async_trait`. Model new flows as streams or async methods.
|
|
- Avoid blocking; use `spawn_blocking` if needed. Prefer existing single-threaded stream handling.
|
|
- `InputCapture` implements `Stream` and manually pumps backends—don't short-circuit this logic.
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
cargo build --workspace # full build
|
|
cargo build -p <crate> # single crate
|
|
cargo test --workspace # all tests
|
|
cargo fmt && cargo clippy --workspace --all-targets --all-features # lint
|
|
RUST_LOG=lan_mouse=debug cargo run # debug logging
|
|
```
|
|
|
|
Run from repo root—no `cd` in scripts.
|
|
|
|
## Testing
|
|
|
|
- Unit tests for utilities; integration tests for protocol behavior.
|
|
- OS-specific backends: test via GTK/CLI on target OS or document manual verification.
|
|
- Dummy backend exercises pipeline without real dependencies.
|
|
- Verify `terminate()` releases keys on unexpected disconnect.
|
|
|
|
## Workflow
|
|
|
|
1. Clarify ambiguous requirements, especially OS-specific behavior.
|
|
2. Implement minimal change; flag follow-up work.
|
|
3. Add proportional tests; run `cargo test` on affected crates.
|
|
4. Run `cargo fmt` and `cargo clippy --workspace --all-targets --all-features`.
|