# Repository Guidelines
## Project Structure & Module Organization
`gruezi` is a Rust CLI crate. Main entrypoints live in `src/bin/gruezi.rs` and `src/lib.rs`. CLI parsing, dispatch, and telemetry are under `src/cli/`. Config parsing lives in `src/config.rs`. Core runtime code is under `src/gruezi/`, including HA-specific logic in `src/gruezi/ha.rs`. Build metadata is generated by `build.rs`. CI workflows live in `.github/workflows/`. There is no top-level `tests/` directory yet; tests stay close to the code under `#[cfg(test)]`.
## Build, Test, and Development Commands
Prefer `just` targets for common checks:
- `just test` runs the repository’s default gate: `clippy` and `fmt`.
- `cargo test` runs unit tests.
- `cargo check` performs a fast compile check.
- `cargo fmt --all -- --check` verifies formatting.
- `cargo clippy --all-targets --all-features` is mandatory for code changes.
- `cargo build --release --locked` builds a release binary.
- `just coverage` generates an HTML coverage report in `target/coverage/html`.
## Coding Style & Naming Conventions
Use standard Rust formatting via `rustfmt` with 4-space indentation. Follow Rust naming conventions: `snake_case` for functions/modules, `CamelCase` for types, and clear enum variant names such as `PeerStatus::Healthy`. Keep modules small and focused by responsibility (`cli`, `gruezi`). Prefer compact Rust imports: keep imports on a single line when reasonable, and use nested grouping with braces such as `use std::{env, path::Path};` to combine items from the same module. Keep code documented when behavior is not obvious: comments, docstrings, and nearby tests should explain why the code exists, the operational intent, and any important invariants or tradeoffs, rather than only restating what the code does. `Cargo.toml` enforces strict lints: warnings are denied, `clippy::pedantic` is enabled, and `unwrap`, `expect`, `panic!`, and unchecked indexing are disallowed. Do not bypass repository lint rules with local `#[allow(clippy::...)]` exceptions unless there is an explicit user-approved reason; refactor code to satisfy the configured lints instead.
## Testing Guidelines
Write unit tests close to the code they verify using `#[cfg(test)] mod tests`. Name tests descriptively, for example `test_start_command` or `encodes_and_decodes_packet`. Before finishing any code change, run:
- `cargo fmt --all -- --check`
- `cargo test`
- `cargo clippy --all-targets --all-features`
Treat `cargo fmt --all -- --check` and `cargo clippy --all-targets --all-features` as mandatory sanity checks, not optional cleanup. If telemetry, config parsing, or HA packet/timer behavior changes, cover both valid and invalid paths.
## Commit & Pull Request Guidelines
Recent history favors short, imperative commit subjects such as `fix pipeline`, `removed windows`, and `cargo fmt`. Keep commit messages concise, present tense, and scoped to one change. PRs should include a brief summary, linked issue when applicable, and example CLI output when commands or formatting change. Ensure CI passes for format, clippy, check, test, and coverage-sensitive changes.
## Configuration & Ports
Configuration is YAML. Lookup order is `--config`, then `GRUEZI_CONFIG`, then `/etc/gruezi/gruezi.yaml` if present. The current mode model is `mode: ha` for 2-node HA and `mode: kv` for 3+ quorum participants. Draft default ports are:
- `9375/udp` for HA (`gruezi-ha`)
- `9376/tcp` for API and management traffic (`gruezi-api`)
- `9377/tcp` for KV peer traffic (`gruezi-peer`)
Keep code and docs aligned when these defaults change. The intent is that CLI commands such as `status` and future management commands can target the API on `9376/tcp` in either mode.
## Observability
Telemetry is configured through OTEL environment variables such as `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS`. Do not commit secrets or local endpoints. For local tracing, `just jaeger` starts a Jaeger container and `just stop-containers` stops it.
