From 2c1c7abf0aa99c8465f1b8ad88841fdb1f727d42 Mon Sep 17 00:00:00 2001 From: Bill Thiede Date: Thu, 11 Sep 2025 16:13:02 -0700 Subject: [PATCH] Generated AI helper --- .github/copilot-instructions.md | 40 +++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..821ebb8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,40 @@ +# Copilot/AI Agent Instructions for Letterbox + +## Project Overview +- **Letterbox** is a Rust monorepo for a mail/newsreader system with a web frontend and a Rocket/GraphQL backend. +- Major crates: `server` (backend, Rocket+async-graphql), `web` (Seed-based WASM frontend), `notmuch` (mail integration), `shared` (common types), `procmail2notmuch` (migration/utility). +- Data flows: Email/news data is indexed and queried via the backend, exposed to the frontend via GraphQL. SQLx/Postgres is used for persistence. Notmuch and custom SQL are both used for mail storage/search. + +## Key Workflows +- **Development**: Use `dev.sh` to launch a tmux session with live-reloading for both frontend (`trunk serve`) and backend (`cargo watch ... run`). +- **Build/Release**: Use `just patch|minor|major` for versioned releases (runs SQLx prepare, bumps versions, pushes). `Makefile`'s `release` target does similar steps. +- **Frontend**: In `web/`, use `cargo make serve` and `cargo make watch` for local dev. See `web/README.md` for Seed-specific details. +- **Backend**: In `server/`, run with `cargo run` or via the tmux/dev.sh workflow. SQL migrations are in `server/migrations/`. + +## Project Conventions & Patterns +- **GraphQL**: All API boundaries are defined in `server/src/graphql.rs`. Use the `Query`, `Mutation`, and `Subscription` roots. Types are defined with `async-graphql` derive macros. +- **HTML Sanitization**: See `server/src/lib.rs` for custom HTML/CSS sanitization and transformation logic (e.g., `Transformer` trait, `sanitize_html`). +- **Tag/Query Parsing**: The `Query` struct in `server/src/lib.rs` parses user queries into filters for notmuch/newsreader/tantivy. +- **Shared Types**: Use the `shared` crate for types and helpers shared between frontend and backend. +- **Custom SQL**: Raw SQL queries are in `server/sql/`. Use these for complex queries not handled by SQLx macros. +- **Feature Flags**: The `tantivy` feature enables full-text search via Tantivy. Check for `#[cfg(feature = "tantivy")]` in backend code. + +## Integration Points +- **Notmuch**: Integrated via the `notmuch` crate for mail indexing/search. +- **Postgres**: Used for newsreader and other persistent data (see `server/migrations/`). +- **GraphQL**: All client-server communication is via GraphQL endpoints defined in the backend. +- **Seed/Trunk**: Frontend is built with Seed (Rust/WASM) and served via Trunk. + +## Examples +- To add a new GraphQL query, update `server/src/graphql.rs` and expose it in the `QueryRoot`. +- To add a new frontend page, add a module in `web/src/` and register it in the Seed app's router. +- To run the full dev environment: `./dev.sh` (requires tmux, trunk, cargo-watch, etc.). + +## References +- See `web/README.md` for frontend/Seed workflow details. +- See `Justfile` and `Makefile` for release/versioning automation. +- See `server/src/lib.rs` and `server/src/graphql.rs` for backend architecture and conventions. +- See `server/sql/` for custom SQL queries. + +--- +If any conventions or workflows are unclear, please ask for clarification or check the referenced files for examples.