chore: update readme

2025-12-22 17:19:59 +00:00 · 2025-05-31 11:48:14 -07:00
parent 99507db677
commit 748d9a862d
1 changed files with 290 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,290 @@
+# 🦀 Cursor Rust Rules
+
+> **Production-tested Rust coding standards and best practices for Cursor IDE**
+
+A comprehensive collection of Rust development rules designed for use with Cursor IDE, providing opinionated guidelines for building production-ready Rust applications with modern patterns and industry best practices.
+
+## ✨ Features
+
+- 🏗️ **Modern Architecture Patterns** - Domain-driven design, subsystem organization, and clean architecture
+- 🌐 **Web Development Standards** - Axum web framework, OpenAPI integration, authentication patterns
+- 🗄️ **Database Best Practices** - SQLx patterns, migrations, connection pooling, and repository patterns
+- ⚡ **Async & Concurrency** - Tokio patterns, async/await best practices, and concurrent data structures
+- 🛠️ **Utility Libraries** - JWT authentication, CLI development, HTTP clients, and more
+- 📦 **Workspace Organization** - Multi-crate workspace structure with clear subsystem boundaries
+- 🔍 **Code Quality** - Comprehensive linting, error handling, testing, and documentation standards
+
+## 🚀 Quick Start
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/your-username/cursor-rust-rules.git
+cd cursor-rust-rules
+```
+
+### 2. Set Up Cursor Rules
+
+Copy the rules to your Cursor configuration:
+
+```bash
+# Create cursor rules directory if it doesn't exist
+mkdir -p ~/.cursor/rules/rust
+
+# Copy all rules
+cp -r .cursor/rules/rust/* ~/.cursor/rules/rust/
+```
+
+### 3. Use in Your Rust Project
+
+In your Rust project, create or update `.cursorrules`:
+
+```yaml
+# .cursorrules
+rules:
+  - "@rust/main"          # Core Rust standards
+  - "@rust/axum"          # Web development with Axum
+  - "@rust/database"      # Database patterns with SQLx
+  - "@rust/concurrency"   # Async and concurrency patterns
+  - "@rust/utilities"     # Utility libraries and CLI tools
+  - "@rust/workspace"     # Multi-crate workspace organization
+```
+
+Or for specific features only:
+
+```yaml
+# .cursorrules - Minimal web API setup
+rules:
+  - "@rust/core/code-quality"
+  - "@rust/features/axum"
+  - "@rust/features/database"
+```
+
+## 📁 Project Structure
+
+```
+cursor-rust-rules/
+├── .cursor/rules/rust/          # Cursor rule definitions
+│   ├── main.mdc                 # Main rule loader and feature detection
+│   ├── core/                    # Core standards
+│   │   └── code-quality.mdc     # Code quality and best practices
+│   ├── features/                # Feature-specific rules
+│   │   ├── axum.mdc            # Web framework standards
+│   │   ├── database.mdc        # Database patterns
+│   │   ├── concurrency.mdc     # Async/concurrency patterns
+│   │   ├── utilities.mdc       # Utility libraries
+│   │   ├── http-client.mdc     # HTTP client patterns
+│   │   └── tools-and-config.mdc # Development tools
+│   └── complex/                 # Advanced patterns
+│       └── workspace.mdc        # Multi-crate workspace organization
+└── README.md                    # This file
+```
+
+## 🎯 Rule Categories
+
+### Core Standards
+
+- **Code Quality** (`@rust/core/code-quality`) - Error handling, logging, testing, and code organization
+
+### Feature-Specific Rules
+
+- **Web Framework** (`@rust/features/axum`) - Axum 0.8+, OpenAPI, middleware, authentication
+- **Database** (`@rust/features/database`) - SQLx patterns, migrations, connection pooling
+- **Concurrency** (`@rust/features/concurrency`) - Tokio, async patterns, concurrent data structures
+- **Utilities** (`@rust/features/utilities`) - JWT, CLI tools, builder patterns, validation
+- **HTTP Client** (`@rust/features/http-client`) - Reqwest patterns, retry logic, authentication
+- **Tools & Config** (`@rust/features/tools-and-config`) - Development tooling and configuration
+
+### Advanced Patterns
+
+- **Workspace** (`@rust/complex/workspace`) - Subsystem-based multi-crate organization
+
+## 🛠️ Usage Examples
+
+### Web API Development
+
+For building a web API with Axum:
+
+```rust
+// Cargo.toml gets configured with these dependencies
+[dependencies]
+axum = { version = "0.8", features = ["macros", "multipart", "ws"] }
+utoipa = { version = "5.0", features = ["axum_extras", "chrono", "uuid"] }
+sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
+tokio = { version = "1.45", features = ["macros", "rt-multi-thread"] }
+```
+
+Your project follows patterns like:
+
+```rust
+// AppState with hot-reloadable config
+#[derive(Clone)]
+pub struct AppState {
+    pub config: Arc<ArcSwap<AppConfig>>,
+    pub db: PgPool,
+    pub http_client: reqwest::Client,
+}
+
+// Route handlers with OpenAPI documentation
+#[utoipa::path(
+    post,
+    path = "/api/v1/users",
+    request_body = CreateUserRequest,
+    responses(
+        (status = 201, description = "User created", body = User),
+        (status = 400, description = "Validation error", body = ApiError)
+    ),
+    tag = "users"
+)]
+pub async fn create_user(
+    State(state): State<AppState>,
+    Json(request): Json<CreateUserRequest>,
+) -> Result<(StatusCode, Json<User>), ApiError> {
+    // Implementation follows validation and error handling patterns
+}
+```
+
+### Database Integration
+
+For database operations with SQLx:
+
+```rust
+// Repository patterns with proper error handling
+#[async_trait]
+pub trait UserRepository: Send + Sync {
+    async fn find_by_id(&self, id: UserId) -> Result<Option<User>, DatabaseError>;
+    async fn create(&self, user: CreateUserRequest) -> Result<User, DatabaseError>;
+    async fn update(&self, id: UserId, user: UpdateUserRequest) -> Result<User, DatabaseError>;
+}
+
+// Migration and connection management
+pub async fn setup_database(config: &DatabaseConfig) -> Result<PgPool, DatabaseError> {
+    let pool = PgPoolOptions::new()
+        .max_connections(config.max_connections)
+        .connect(&config.url)
+        .await?;
+
+    sqlx::migrate!("./migrations").run(&pool).await?;
+    Ok(pool)
+}
+```
+
+### Multi-Crate Workspace
+
+For complex applications, organize as subsystems:
+
+```
+my-ecommerce-platform/
+├── shared/                      # Cross-cutting infrastructure
+│   ├── shared-types/           # Domain primitives
+│   ├── shared-db/              # Database infrastructure
+│   └── shared-events/          # Event definitions
+├── subsystems/                 # Business subsystems
+│   ├── user-management/        # User & auth subsystem
+│   ├── product-catalog/        # Product management
+│   ├── order-management/       # Order processing
+│   └── payment/                # Payment processing
+└── services/                   # Infrastructure services
+    ├── api-gateway/            # Unified API
+    └── admin-cli/              # Admin tools
+```
+
+## 🎮 Interactive Features
+
+The rules provide intelligent feature detection and suggestions:
+
+### Automatic Dependency Detection
+
+When you use certain patterns, Cursor will suggest appropriate dependencies:
+
+```rust
+// Using async patterns triggers Tokio suggestions
+async fn my_function() -> Result<(), Error> {
+    // Cursor suggests: Add tokio = "1.45" with appropriate features
+}
+
+// Using database patterns triggers SQLx suggestions
+sqlx::query!("SELECT * FROM users")
+    // Cursor suggests: Add sqlx with postgres features
+```
+
+### Smart Code Generation
+
+Rules include templates for common patterns:
+
+- **API Endpoints** - Complete handler with validation and OpenAPI docs
+- **Database Repositories** - Repository trait and implementation
+- **Error Types** - Structured error handling with proper HTTP status codes
+- **Configuration** - Environment-based config with hot reload support
+
+## 📊 Rule Hierarchy
+
+Rules are loaded based on project complexity:
+
+1. **Simple Projects** - Core quality standards only
+2. **Web APIs** - Core + Axum + Database rules
+3. **Complex Systems** - All rules including workspace organization
+
+## 🔧 Customization
+
+### Override Specific Rules
+
+Create a local `.cursorrules` file to customize:
+
+```yaml
+rules:
+  - "@rust/main"
+
+overrides:
+  # Use different web framework
+  web_framework: "warp"
+
+  # Custom database configuration
+  database:
+    orm: "diesel"
+    features: ["mysql"]
+```
+
+### Add Project-Specific Rules
+
+Extend with your own patterns:
+
+```rust
+// .cursor/rules/rust/project/custom.mdc
+// Your project-specific patterns and standards
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-rule`)
+3. Add your rule with documentation and examples
+4. Test with real projects
+5. Submit a pull request
+
+### Rule Writing Guidelines
+
+- **Comprehensive Examples** - Show complete, working code
+- **Production Patterns** - Based on real-world usage
+- **Clear Documentation** - Explain why, not just what
+- **Test Coverage** - Include testing patterns
+- **Version Compatibility** - Specify crate versions
+
+## 📚 References
+
+- [Axum Documentation](https://docs.rs/axum/)
+- [SQLx Documentation](https://docs.rs/sqlx/)
+- [Tokio Documentation](https://docs.rs/tokio/)
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🚨 Disclaimer
+
+These rules represent opinionated best practices based on production experience. Adapt them to your specific project needs and constraints.
+
+---
+
+**Happy Coding with Rust! 🦀**