67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Scope
|
|
|
|
This file applies to the Rust workspace at `digitemp-rrdgraph/`.
|
|
|
|
## Project Summary
|
|
|
|
- The binary provides three operational subcommands: `update`, `check-alert`, and `send-info`.
|
|
- The repository is a Cargo workspace with a CLI crate at the repository root and an internal library crate at `crates/core/` named `digitemp_rrdgraph_core`.
|
|
- The system depends on external commands and resources: `digitemp`, `rrdtool`, SMTP, JSON config files under `etc/`, Tera templates under `templates/`, generated graphs under `html/images/`, and RRD files under `db/`.
|
|
|
|
## Source Of Truth
|
|
|
|
- Treat this Rust repository as the sole implementation and documentation target.
|
|
- Preserve the CLI contract exposed by `src/main.rs`, the command modules under `src/commands/`, and the public interfaces exposed by `crates/core/src/lib.rs` unless the user explicitly requests a behavior change.
|
|
- Preserve the configuration schema in `etc/config.sample.json` unless the user explicitly asks for a breaking change.
|
|
- Preserve template variable names expected by `templates/*.tera` unless the templates are updated in the same change.
|
|
|
|
## Documentation And Language
|
|
|
|
- Write repository documentation such as `AGENTS.md`, `README.md`, and other project documents in English by default.
|
|
- When adding comments to source code, configuration files, templates, or scripts, write those comments in English.
|
|
- Keep user-facing configuration keys, template names, and command names stable unless the task explicitly requires a change.
|
|
|
|
## Change Priorities
|
|
|
|
- Prefer fixes at the behavior or interface boundary, not cosmetic refactors.
|
|
- Keep CLI behavior and config keys stable.
|
|
- Keep changes small and local to the affected command or library module.
|
|
- Avoid introducing new crates unless the standard library or existing dependencies are clearly insufficient.
|
|
- Prefer explicit error propagation with `Result` over `unwrap` or `expect` in runtime paths.
|
|
|
|
## Safe Editing Rules
|
|
|
|
- Do not edit generated or runtime data under `target/`, `db/`, or `html/images/` unless the task explicitly requires it.
|
|
- Do not overwrite `etc/digitemp-rrdgraph.conf` for convenience; use `etc/config.sample.json` as the editable reference.
|
|
- Be careful with commands that can talk to real hardware, modify RRD files, or send email.
|
|
- When validation would invoke external systems, prefer build-only or isolated checks unless the user explicitly wants end-to-end execution.
|
|
|
|
## Validation Expectations
|
|
|
|
- After Rust code changes, run `cargo build` in this repository at minimum. Prefer `cargo build --workspace` when changes affect `crates/core/` or workspace wiring.
|
|
- If you add or refactor logic that can be unit tested without hardware or SMTP, add focused tests and run them.
|
|
- Prefer tests around pure logic such as config parsing, digitemp config parsing, template rendering, and any command-argument construction helpers.
|
|
- If a change depends on hardware access or local services, state clearly what could not be verified.
|
|
|
|
## Implementation Guidance
|
|
|
|
- Keep path handling relative to the repository root unless a config field explicitly stores an absolute path.
|
|
- Encapsulate shell command construction so it can be inspected or tested without executing the command.
|
|
- Match existing naming and module boundaries under `src/commands/` and `crates/core/src/`.
|
|
- Keep CLI-only orchestration in the root crate and reusable logic in `digitemp_rrdgraph_core`.
|
|
- Prefer direct, maintainable implementations over compatibility layers or unnecessary abstraction.
|
|
|
|
## Useful References
|
|
|
|
- Rust entrypoint: `src/main.rs`
|
|
- Rust commands: `src/commands/`
|
|
- Internal library crate manifest: `crates/core/Cargo.toml`
|
|
- Rust support modules: `crates/core/src/`
|
|
- Sample config: `etc/config.sample.json`
|
|
- Email templates: `templates/`
|
|
- RRD files: `db/`
|
|
- Graph images: `html/images/`
|
|
- External dependencies: `digitemp`, `rrdtool`, SMTP server
|