ci: Update readme, ci and add cursor rules

1 files changed, 174 insertions, 0 deletions

diff --git a/.cursorrules b/.cursorrules
new file mode 100644
index 0000000..4438139
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1,174 @@
+# Rust Rules
+
+## 🧱 Project Architecture
+
+### **Modular Design**
+
+* Organize code into **crates** and **modules**:
+
+  * Use a **workspace** for multi-crate projects (`Cargo.toml` + `Cargo.lock` at root).
+  * Split concerns into crates: e.g., `core`, `network`, `storage`, `cli`, `web`, `domain`, `infra`.
+* Avoid monoliths — design for composability.
+
+### **Layered Architecture**
+
+Separate by **responsibility**, not technology:
+
+* **Domain layer** – business logic, domain models, pure logic, no dependencies.
+* **Application layer** – use-cases, orchestrators, service interfaces.
+* **Infrastructure layer** – database, HTTP clients, FS, external APIs.
+* **Presentation layer** – CLI, gRPC, REST API, etc.
+
+Use traits to **abstract interfaces** between layers.
+
+---
+
+## 📦 Crate and Module Hygiene
+
+### **Use Visibility Thoughtfully**
+
+* Keep as much private (`pub(crate)` or private) as possible.
+* Use `mod.rs` sparingly — prefer flat `mod_x.rs` and `mod x;` where possible.
+* Keep `lib.rs` or `main.rs` minimal — just wiring and top-level declarations.
+
+### **Predeclare your modules**
+
+Explicitly declare modules in parent files, avoiding implicit module discovery:
+
+```rust
+mod domain;
+mod services;
+```
+
+---
+
+## 🧠 Code Design and Idioms
+
+### **Prefer Composition Over Inheritance**
+
+* Favor structs + traits over enums for extensibility.
+* Use `impl Trait` for abstraction and `dyn Trait` for dynamic dispatch when needed.
+
+### **Minimize Unnecessary Abstractions**
+
+* Don't abstract over one implementation — wait for the second one.
+* Don’t use traits where a simple function will do.
+
+### **Idiomatic Error Handling**
+
+* Use `Result<T, E>`, `?`, and `thiserror` or `anyhow` (depending on layer).
+* Business logic: custom error enums (`thiserror`).
+* App layer or CLI: use `anyhow::Result` for bubble-up and crash-on-error.
+
+### **Zero-cost abstractions**
+
+* Use generics, lifetimes, borrowing, and ownership where appropriate.
+* Minimize heap allocations, unnecessary `.clone()`s.
+
+## 🛠️ Tooling and Dev Experience
+
+### **Use Clippy, Rustfmt, and IDEs**
+
+* `clippy`: catch non-idiomatic code.
+* `rustfmt`: consistent formatting.
+* `cargo-expand`: inspect macro-generated code.
+
+### **Use `cargo features` for Flexibility**
+
+* Feature-gate optional deps and functionalities:
+
+```toml
+[features]
+default = ["serde"]
+cli = ["clap"]
+```
+
+## 🧪 Testing & Quality
+
+### **Test by Layer**
+
+* Unit tests for pure logic.
+* Integration tests (`tests/`) for subsystems and public interfaces.
+* End-to-end/system tests where applicable.
+
+Use `mockall` or `double` for mocking when interface testing is needed.
+
+### **Property-based test* Study open-source Rust projects like `ripgrep`, `tokio`, `tower`, `axum`, or `zellij`.
+ing**
+
+* Use `proptest` for verifying correctness over ranges of inputs.
+
+## 📈 Performance and Safety
+
+### **Measure Before Optimizing**
+
+* Use `cargo bench`, `criterion`, `perf`, or `flamegraph` for real profiling.
+* Don't optimize until there's a clear need.
+
+### **Minimize Unsafe Code**
+
+* Keep `unsafe` blocks minimal, justified, and well-documented.
+* Use crates like `bytemuck`, `zeroize`, or `unsafe-libyaml` only when needed.
+
+## 📚 Dependency Hygiene
+
+### **Minimal and Audited Dependencies**
+
+* Prefer well-maintained, minimal, audited crates.
+* Avoid depending on "kitchen sink" crates unless unavoidable.
+* Regularly check for security updates via `cargo audit`.
+
+## 🧾 Documentation & Maintainability
+
+### **Document Public APIs and Crates**
+
+* Use `//!` and `///` comments.
+* Auto-generate docs with `cargo doc --open`.
+
+### **Conventional Naming**
+
+* Stick to Rust conventions: `snake_case` for functions and variables, `PascalCase` for types.
+
+## ☁️ Async, Concurrency, and IO
+
+### **Choose Your Runtime Wisely**
+
+* `tokio`: for production-grade, multi-core async workloads.
+* `async-std`: if you prefer a more "standard" style.
+* Use `tracing` instead of `log` for structured async-aware logging.
+
+### **Limit Shared Mutable State**
+
+* Prefer ownership and message passing (`tokio::sync::mpsc`, `crossbeam`, `flume`) over `Arc<Mutex<T>>`.
+* Avoid global mutable state unless it’s guarded and justified.
+
+### **Reproducible Builds**
+
+* Pin versions where critical.
+* Use lockfiles even in libraries (`[package] publish = false` in internal crates).
+
+## 📁 Example Folder Structure
+
+```text
+my-app/
+├── Cargo.toml
+├── Cargo.lock
+├── crates/
+│   ├── core/
+│   ├── api/
+│   ├── domain/
+│   └── storage/
+├── bin/
+│   └── cli.rs
+├── tests/
+│   └── integration.rs
+├── docs/
+│   └── architecture.md
+```
+
+## 🧭 Final Advice
+
+* Think in **lifetimes**, **ownership**, and **borrowing**.
+* Design for **testability** and **composability**.
+* Don't fight the compiler — **embrace it as your co-architect**.
+* Be conservative with third-party crates — **audit and isolate** them if needed.