red64-cli 0.3.0 → 0.6.0

package/framework/stacks/loco/error-handling.md

@@ -0,0 +1,225 @@
+# Error Handling
+
+Error handling patterns for Loco applications. Leverage Rust's type system and Loco's error infrastructure for predictable, user-friendly error responses.
+
+---
+
+## Philosophy
+
+- **Use `Result<T>` everywhere**: No panics in production code
+- **`?` operator for propagation**: Flat, readable error chains
+- **Typed errors for domain logic**: Custom error enums for business rules
+- **Consistent HTTP error responses**: Map errors to appropriate status codes
+- **Log context, not secrets**: Structured logging with tracing spans
+
+---
+
+## Loco Error Types
+
+### Built-in Error Hierarchy
+
+Loco provides `loco_rs::Error` as the primary error type. Controllers return `Result<impl IntoResponse>` which auto-maps errors to HTTP responses.
+
+```rust
+use loco_rs::prelude::*;
+
+// Loco maps these automatically:
+// - ModelError::EntityNotFound -> 404
+// - Error::Unauthorized -> 401
+// - Error::BadRequest -> 400
+// - Error::InternalServerError -> 500
+```
+
+### Model Errors
+
+Use `ModelResult<T>` for model-layer operations:
+
+```rust
+impl super::_entities::users::ActiveModel {
+    pub async fn find_by_email(db: &DatabaseConnection, email: &str) -> ModelResult<Self> {
+        let user = users::Entity::find()
+            .filter(users::Column::Email.eq(email))
+            .one(db)
+            .await?;
+        user.ok_or_else(|| ModelError::EntityNotFound)
+    }
+}
+```
+
+---
+
+## Controller Error Handling
+
+### Pattern: Early Returns with `?`
+
+```rust
+// GOOD: Flat, each line can fail independently
+async fn update(
+    auth: auth::JWT,
+    State(ctx): State<AppContext>,
+    Path(id): Path<i32>,
+    Json(params): Json<UpdatePostParams>,
+) -> Result<Json<PostResponse>> {
+    let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;
+    let post = posts::Model::find_by_id_and_user(&ctx.db, id, user.id).await?;
+    let updated = post.update(&ctx.db, &params).await?;
+    Ok(Json(PostResponse::from(updated)))
+}
+
+// BAD: Nested error handling
+async fn update(/* ... */) -> Result<Json<PostResponse>> {
+    match users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await {
+        Ok(user) => match posts::Model::find_by_id(&ctx.db, id).await {
+            Ok(Some(post)) => {
+                if post.user_id == user.id {
+                    // deeply nested...
+                }
+            }
+            // more nesting...
+        }
+    }
+}
+```
+
+### Custom Error Responses
+
+For domain-specific errors, return explicit HTTP responses:
+
+```rust
+async fn publish(
+    State(ctx): State<AppContext>,
+    Path(id): Path<i32>,
+) -> Result<Json<PostResponse>> {
+    let post = posts::Entity::find_by_id(id)
+        .one(&ctx.db)
+        .await?
+        .ok_or_else(|| Error::NotFound)?;
+
+    if post.status == "published" {
+        return Err(Error::BadRequest("Post is already published".into()));
+    }
+
+    let published = post.publish(&ctx.db).await?;
+    Ok(Json(PostResponse::from(published)))
+}
+```
+
+---
+
+## Validation Errors
+
+### Using `validator` Crate
+
+Return structured validation errors with field-level detail:
+
+```rust
+use loco_rs::controller::views::json_validate::JsonValidateWithMessage;
+
+async fn create(
+    State(ctx): State<AppContext>,
+    JsonValidateWithMessage(params): JsonValidateWithMessage<CreatePostParams>,
+) -> Result<Json<PostResponse>> {
+    // Validation happens automatically via extractor
+    // Returns 422 with field-level errors on failure
+    let post = posts::ActiveModel::create(&ctx.db, &params).await?;
+    Ok(Json(PostResponse::from(post)))
+}
+```
+
+### Model-Level Validation
+
+```rust
+impl Validatable for super::_entities::posts::ActiveModel {
+    fn validator(&self) -> Box<dyn Validate> {
+        Box::new(PostValidator {
+            title: self.title.clone().into_value().unwrap_or_default(),
+        })
+    }
+}
+
+// In model method:
+pub async fn create(db: &DatabaseConnection, params: &CreatePostParams) -> ModelResult<Model> {
+    let mut item = ActiveModel { ..Default::default() };
+    item.title = Set(params.title.clone());
+    item.validate()?;  // Returns validation errors before hitting DB
+    item.insert(db).await.map_err(|e| ModelError::from(e))
+}
+```
+
+---
+
+## Worker Error Handling
+
+Workers should handle errors gracefully and log context:
+
+```rust
+async fn perform(&self, args: ReportArgs) -> Result<()> {
+    let user = users::Entity::find_by_id(args.user_id)
+        .one(&self.ctx.db)
+        .await?
+        .ok_or_else(|| {
+            tracing::error!(user_id = args.user_id, "User not found for report");
+            Error::NotFound
+        })?;
+
+    match generate_report(&user).await {
+        Ok(report) => {
+            tracing::info!(user_id = args.user_id, "Report generated");
+            Ok(())
+        }
+        Err(e) => {
+            tracing::error!(user_id = args.user_id, error = %e, "Report generation failed");
+            Err(e.into())
+        }
+    }
+}
+```
+
+---
+
+## Logging with Context
+
+### Structured Tracing
+
+```rust
+use tracing;
+
+// GOOD: Structured fields for queryability
+tracing::info!(user_id = %user.id, action = "login", "User authenticated");
+tracing::error!(post_id = id, error = %e, "Failed to publish post");
+
+// BAD: Unstructured string interpolation
+tracing::info!("User {} logged in", user.id);
+```
+
+### Span Context in Controllers
+
+```rust
+async fn create(
+    State(ctx): State<AppContext>,
+    Json(params): Json<CreatePostParams>,
+) -> Result<Json<PostResponse>> {
+    let _span = tracing::info_span!("create_post", title = %params.title).entered();
+    // All logs within this scope include the span context
+    let post = posts::ActiveModel::create(&ctx.db, &params).await?;
+    Ok(Json(PostResponse::from(post)))
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| `.unwrap()` in handlers | Panics crash the request | Use `?` or `.ok_or_else()` |
+| Swallowing errors silently | Hides bugs, makes debugging impossible | Log and propagate with `?` |
+| Generic "Internal Error" for everything | Poor DX for API consumers | Map to specific HTTP status codes |
+| Logging sensitive data | Security risk | Use structured fields, redact secrets |
+| Validation in controllers | Logic duplication across endpoints | Use `Validatable` trait on models |
+| `Box<dyn Error>` as return type | Loses type information | Use Loco's `Error` / `ModelError` types |
+| Ignoring worker failures | Silent data loss | Log errors with context, use retry policies |
+
+---
+
+_Rust's type system makes error handling explicit. Use `?` for propagation, typed errors for domain logic, and structured tracing for observability._

package/framework/stacks/loco/feedback.md

@@ -0,0 +1,35 @@
+# Feedback Guidelines
+
+When reviewing or generating code for a Loco application, apply these checks.
+
+---
+
+## Always Check
+
+1. **Fat models, slim controllers**: Is business logic in models, not controllers?
+2. **Generator compliance**: Were new files created via `cargo loco generate`?
+3. **Entity files untouched**: Are `_entities/` files unmodified?
+4. **Config per environment**: Are dangerous flags disabled in production config?
+5. **No `.unwrap()` in handlers**: All error paths handled with `?`?
+6. **Worker isolation**: Workers self-contained with serializable args?
+7. **Validation on models**: `Validatable` implemented for user-input models?
+8. **View structs for responses**: Not returning raw SeaORM entities?
+
+## Red Flags
+
+- Direct SQL in controllers
+- `dangerously_*` flags in `config/production.yaml`
+- Editing files in `src/models/_entities/`
+- Workers referencing controller state
+- Missing `down()` in migrations
+- Hardcoded configuration values
+- `.unwrap()` or `.expect()` in request handlers
+
+## Encourage
+
+- Using generators for all scaffolding
+- Domain methods on models with descriptive names
+- Structured tracing with typed fields
+- Snapshot testing with `insta`
+- Request tests for all controller endpoints
+- Tagged workers for job categorization

package/framework/stacks/loco/loco.md

@@ -0,0 +1,342 @@
+# Loco Framework Conventions
+
+Conventions and patterns for Loco -- the Rust on Rails framework. Convention over configuration; decisions are made for you.
+
+---
+
+## Framework Stack
+
+### Core Technologies
+- **Loco**: Rails-inspired Rust web framework
+- **Axum**: HTTP routing and Tower middleware
+- **SeaORM**: Async ActiveRecord-style ORM
+- **Tokio**: Async runtime
+- **sidekiq-rs / Tokio**: Background workers (Redis-backed or in-process)
+- **JWT**: Stateless authentication (built-in)
+
+### Database
+- **PostgreSQL** for production (recommended)
+- **SQLite** for development and lightweight deployments
+- **MySQL** supported
+
+---
+
+## Application Architecture
+
+### MVC Patterns
+
+**Models** (`src/models/`)
+- Fat models, slim controllers: domain logic lives on models
+- Two-file pattern: `_entities/model.rs` (auto-generated, read-only) + `model.rs` (your ActiveRecord logic)
+- Implement domain operations as methods on `ActiveModel`
+- `User::create` creates a user; `user.buy(product)` buys a product
+
+```rust
+// Pattern: Domain logic on the model
+impl super::_entities::users::ActiveModel {
+    pub async fn find_by_email(db: &DatabaseConnection, email: &str) -> ModelResult<Self> {
+        let user = users::Entity::find()
+            .filter(users::Column::Email.eq(email))
+            .one(db)
+            .await?;
+        user.ok_or_else(|| ModelError::EntityNotFound)
+    }
+
+    pub async fn verify_password(&self, password: &str) -> ModelResult<bool> {
+        Ok(hash::verify_password(password, &self.password_hash))
+    }
+}
+```
+
+**Controllers** (`src/controllers/`)
+- Thin controllers: validate input, call model, return view
+- Use Axum extractors for request data
+- Return `Result<impl IntoResponse>` consistently
+- Group routes by resource with `.prefix()`
+
+```rust
+// Pattern: Thin controller delegating to model
+async fn create(
+    State(ctx): State<AppContext>,
+    Json(params): Json<CreatePostParams>,
+) -> Result<Json<PostResponse>> {
+    let post = models::posts::ActiveModel::create(&ctx.db, &params).await?;
+    Ok(Json(PostResponse::from(post)))
+}
+
+pub fn routes() -> Routes {
+    Routes::new()
+        .prefix("posts")
+        .add("/", post(create))
+        .add("/", get(list))
+        .add("/:id", get(show))
+        .add("/:id", put(update))
+        .add("/:id", delete(destroy))
+}
+```
+
+**Views** (`src/views/`)
+- JSON serialization structs for API responses
+- Keep response shaping separate from models
+- Use `serde::Serialize` derive
+
+```rust
+// Pattern: View struct for API response
+#[derive(Serialize)]
+pub struct PostResponse {
+    pub id: i32,
+    pub title: String,
+    pub content: String,
+    pub created_at: DateTime,
+}
+
+impl From<posts::Model> for PostResponse {
+    fn from(post: posts::Model) -> Self {
+        Self {
+            id: post.id,
+            title: post.title,
+            content: post.content,
+            created_at: post.created_at,
+        }
+    }
+}
+```
+
+---
+
+## Business Logic Patterns
+
+### Fat Models
+Place domain operations on models. This enables reuse across controllers, workers, and tasks:
+
+```rust
+// src/models/users.rs
+impl super::_entities::users::ActiveModel {
+    pub async fn register(db: &DatabaseConnection, params: &RegisterParams) -> ModelResult<Self> {
+        // Validation, password hashing, email verification token
+        // All in one place, testable via model tests
+    }
+
+    pub async fn reset_password(db: &DatabaseConnection, token: &str, new_password: &str) -> ModelResult<()> {
+        // Token verification, password update
+    }
+}
+```
+
+### When to Extract Services
+Extract standalone service modules only when logic:
+- Spans multiple unrelated models
+- Integrates external APIs
+- Has no natural "home" model
+
+Place in `src/services/` (create as needed).
+
+---
+
+## Background Workers
+
+### Worker Definition
+Implement `BackgroundWorker` trait with `perform` function:
+
+```rust
+#[async_trait]
+impl BackgroundWorker<ReportArgs> for ReportWorker {
+    fn build(ctx: &AppContext) -> Self {
+        Self { ctx: ctx.clone() }
+    }
+
+    async fn perform(&self, args: ReportArgs) -> Result<()> {
+        // Job logic -- self-contained, no shared controller state
+        Ok(())
+    }
+}
+```
+
+### Enqueue Jobs
+```rust
+ReportWorker::perform_later(&ctx, ReportArgs { user_id: 42 }).await?;
+```
+
+### Worker Modes
+- **BackgroundAsync**: In-process Tokio tasks (development, single-server)
+- **BackgroundQueue**: Redis/Postgres/SQLite backed (production, horizontal scaling)
+- **ForegroundBlocking**: Synchronous (testing only)
+
+### Anti-Pattern: Shared State
+Workers must be self-contained. Do not share state between controllers and workers -- workers may run in separate processes.
+
+---
+
+## Tasks
+
+CLI-invokable operations for administrative work:
+
+```rust
+#[async_trait]
+impl Task for SeedData {
+    fn task(&self) -> TaskInfo {
+        TaskInfo {
+            name: "seed_data".to_string(),
+            detail: "Seed the database with initial data".to_string(),
+        }
+    }
+
+    async fn run(&self, app_context: &AppContext, vars: &task::Vars) -> Result<()> {
+        // Business logic -- no manual DB access needed
+        Ok(())
+    }
+}
+```
+
+Run with: `cargo loco task seed_data`
+
+---
+
+## Authentication
+
+### Built-in JWT Auth (SaaS Starter)
+Loco's SaaS starter includes complete auth flow:
+- `POST /api/auth/register` -- registration with email verification
+- `POST /api/auth/login` -- returns JWT token
+- `POST /api/auth/forgot` / `POST /api/auth/reset` -- password reset
+- `GET /api/auth/verify` -- email verification
+
+### Protecting Routes
+Use `auth::JWT` extractor for authenticated endpoints:
+
+```rust
+async fn current(
+    auth: auth::JWT,
+    State(ctx): State<AppContext>,
+) -> Result<Json<UserResponse>> {
+    let user = users::Model::find_by_pid(&ctx.db, &auth.claims.pid).await?;
+    Ok(Json(UserResponse::from(user)))
+}
+```
+
+### Token Configuration
+```yaml
+auth:
+  jwt:
+    secret: <change-in-production>
+    expiration: 604800  # seconds
+    location:
+      from: Bearer       # or Cookie, Query
+```
+
+Support multiple auth methods via fallback chains (Bearer -> Cookie -> Query).
+
+---
+
+## Database Conventions
+
+### Migrations
+Migration names auto-detect operations:
+- `CreatePosts` -- new table
+- `AddNameToUsers` -- column addition
+- `RemoveAgeFromUsers` -- column removal
+- `AddUserRefToPosts` -- foreign key
+- `CreateJoinTableUsersAndGroups` -- link table
+
+```bash
+cargo loco generate model posts title:string! content:text user:references
+```
+
+Field suffixes: `!` = NOT NULL, `^` = UNIQUE, none = nullable.
+
+### Entity Generation
+After migrations, regenerate entities:
+```bash
+cargo loco db entities
+```
+
+Never edit files in `src/models/_entities/` -- they are overwritten.
+
+### Seeding
+Define fixtures in `src/fixtures/` as YAML. Load via `Hooks::seed()`:
+```bash
+cargo loco db seed --reset
+```
+
+---
+
+## Configuration Environments
+
+### Development (`config/development.yaml`)
+```yaml
+database:
+  auto_migrate: true
+  dangerously_truncate: false
+  dangerously_recreate: false
+```
+
+### Test (`config/test.yaml`)
+```yaml
+database:
+  dangerously_truncate: true    # Clean slate per test run
+```
+
+### Production (`config/production.yaml`)
+- Disable all `dangerously_*` flags
+- Set secure JWT secret
+- Configure Redis URI for queue workers
+- Set appropriate log level and format (JSON recommended)
+- Run `cargo loco doctor --production` to validate
+
+---
+
+## Deployment
+
+### Single Binary
+Build and deploy -- no Rust toolchain needed on server:
+```bash
+cargo build --release
+# Copy binary + config/ to server
+./myapp start
+```
+
+### Docker
+```bash
+cargo loco generate deployment  # Generates Dockerfile
+docker build -t myapp .
+docker run -p 5150:5150 myapp
+```
+
+### Health Check
+```bash
+cargo loco doctor --production
+```
+
+---
+
+## Generators
+
+Use generators to maintain consistency:
+
+| Generator | Command | Creates |
+|-----------|---------|---------|
+| Model | `cargo loco generate model <name> <fields>` | Migration + entity + model file |
+| Controller | `cargo loco generate controller <name>` | Controller + test file |
+| Scaffold | `cargo loco generate scaffold <name> <fields>` | Full CRUD (model + controller + view + tests) |
+| Worker | `cargo loco generate worker <name>` | Worker file |
+| Task | `cargo loco generate task <name>` | Task file |
+| Deployment | `cargo loco generate deployment` | Docker/Nginx/Shuttle configs |
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Logic in controllers | Untestable, not reusable | Move domain logic to model methods |
+| Editing `_entities/` files | Overwritten on regeneration | Add logic in `models/<name>.rs` impl blocks |
+| Shared controller/worker state | Breaks horizontal scaling | Workers are self-contained with serializable args |
+| `dangerously_*` flags in production | Data loss risk | Only enable in dev/test environments |
+| Skipping generators | Inconsistent structure | Use `cargo loco generate` for all scaffolding |
+| Raw SQL in controllers | Bypass ORM protections | Use SeaORM queries in model methods |
+| Hardcoded config values | Environment-specific failures | Use `config/*.yaml` per environment |
+| Nullable everything | Weak data integrity | Use `!` suffix for required fields in generators |
+
+---
+
+_Loco is "Rust on Rails" -- lean into conventions, use generators, keep models fat and controllers thin._