# AGENTS.md
These guidelines are mandatory for contributors and for any AI coding agent
operating in this repository. The goal is to land changes safely, keep security
invariants intact, and keep the workspace consistent over time.
## Agent Contract (Read First)
- Follow this file strictly. If a request conflicts with these rules, explain the conflict and propose a compliant alternative.
- Keep diffs minimal: do not refactor, rename, reorder, or "clean up" unrelated code.
- Do not change authentication, authorization, token semantics, or trust boundaries unless explicitly requested.
- Do not weaken validation, scope checks, rate/risk controls, TLS verification, or logging hygiene.
- If you are unsure about an invariant, prefer asking for context or leaving behavior unchanged with a clear note.
- Do not hardcode configuration values.
## 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.
