# Repository Guidelines
## Project Structure & Module Organization
`pgmon` is a small Rust CLI/TUI application. Core code lives in `src/`:
- `src/main.rs`: entry point.
- `src/cli/`: argument parsing, dispatch, telemetry, and command actions.
- `src/pg/`: PostgreSQL client logic and SQL query constants.
- `src/tui/`: app state and Ratatui rendering.
Build metadata is generated by `build.rs`. Project usage and examples live in `README.md`. Tests are currently inline unit tests under `#[cfg(test)]`, for example in `src/cli/commands/mod.rs`.
## Build, Test, and Development Commands
- `cargo build`: compile a debug build.
- `cargo build --release`: build the optimized binary used for packaging.
- `cargo run -- --dsn "postgresql://user:pass@localhost:5432/postgres"`: run the TUI locally.
- `cargo test`: run the unit test suite.
- `cargo fmt --check`: verify standard Rust formatting.
- `cargo clippy --all-targets --all-features`: check against the strict lint policy in `Cargo.toml`.
## Coding Style & Naming Conventions
Use Rust 2024 edition conventions with default `rustfmt` formatting. Follow Rust naming conventions:
- `snake_case` for functions, modules, and variables
- `PascalCase` for enums/structs
- `UPPER_SNAKE_CASE` for SQL constants
All production code should be documented. Add docs for public modules, types, functions, and constants, and document non-obvious internal logic that would otherwise be hard to maintain safely.
Clippy is strict here: `all` and `pedantic` are denied. Prefer small, focused functions and propagate errors with `?` and typed errors where practical. Do not introduce `unwrap`, `expect`, or panics. Do not add `#[allow(...)]` in production code; limit those exceptions to test modules when they are genuinely needed.
## Testing Guidelines
Add unit tests next to the code they cover. Use descriptive names with the existing `test_*` pattern, such as `test_cli_default_values`. Prioritize coverage for CLI parsing, validation, data shaping, and pure helper logic. Run `cargo test` before opening a PR.
## AI Agent Workflow
Before concluding any task that changes code, AI agents must complete this sequence:
1. `cargo fmt --all`
2. `cargo clippy --all-targets --all-features -- -D warnings`
3. `cargo test --all-features`
4. Perform a final self-review for obvious errors, regressions, and deviations from these guidelines.
## Commit & Pull Request Guidelines
Recent history mixes release tags (`0.1.0`) with short maintenance commits like `fix tests and cargo clippy`. Prefer short, imperative commit messages focused on one change, for example `fix clippy warnings in tui chart`.
PRs should include:
- a brief summary of behavior changes
- test or verification notes
- linked issues when applicable
- screenshots or terminal captures for TUI/UI changes
## Security & Configuration Tips
Never commit real DSNs, passwords, or local connection details. Prefer the `PGMON_DSN` environment variable for local development instead of hardcoding credentials in commands or docs.