red64-cli 0.5.0 → 0.6.0

package/framework/stacks/loco/structure.md

@@ -0,0 +1,193 @@
+# Project Structure
+
+## Organization Philosophy
+
+Convention over configuration, inspired by Rails. File location implies behavior. Loco enforces a standard layout where folder structure, configuration shape, and wiring all matter. Extend with custom modules as complexity grows.
+
+---
+
+## Directory Patterns
+
+### Application Core (`src/`)
+**Purpose**: All application code following Loco conventions
+**Pattern**: Convention-driven -- generators create files in the right place
+
+| Directory | Purpose | Naming |
+|-----------|---------|--------|
+| `controllers/` | HTTP request handlers (thin, delegate to models) | snake_case (`posts.rs`, `auth.rs`) |
+| `models/` | Domain logic, ActiveRecord-style methods | snake_case (`users.rs`, `posts.rs`) |
+| `models/_entities/` | Auto-generated SeaORM entities (read-only) | snake_case, prefixed with `_` |
+| `views/` | JSON serialization structs and response shaping | snake_case (`posts.rs`, `auth.rs`) |
+| `workers/` | Background job handlers | snake_case (`report_worker.rs`) |
+| `tasks/` | CLI-invokable administrative tasks | snake_case (`sync_data.rs`) |
+| `mailers/` | Email templates and delivery logic | snake_case (`auth.rs`) |
+| `initializers/` | App startup hooks (extra DB, custom state) | snake_case (`view_engine.rs`) |
+
+### Generated Entities (`src/models/_entities/`)
+**Purpose**: SeaORM auto-generated entity files -- never edit manually
+**Pattern**: Regenerated from database schema via `cargo loco db entities`
+
+```
+src/models/_entities/
+  mod.rs              # Re-exports all entities
+  users.rs            # Auto-generated User entity
+  posts.rs            # Auto-generated Post entity
+  prelude.rs          # Common imports
+```
+
+### Configuration (`config/`)
+**Purpose**: Environment-specific YAML configuration
+**Pattern**: One file per environment, merged with defaults
+
+```
+config/
+  development.yaml    # Dev settings (auto_migrate: true, debug logging)
+  test.yaml           # Test settings (dangerously_truncate: true)
+  production.yaml     # Production settings (no dangerous flags)
+```
+
+### Migrations (`migration/`)
+**Purpose**: Database schema changes, versioned and reproducible
+**Pattern**: Timestamped, descriptive names that drive auto-detection
+
+```
+migration/
+  src/
+    lib.rs            # Migration registry
+    m20231001_000001_create_users.rs
+    m20231002_000001_create_posts.rs
+```
+
+### Tests (`tests/`)
+**Purpose**: Integration and request tests
+**Pattern**: Mirror controller structure
+
+```
+tests/
+  requests/
+    posts.rs          # Controller integration tests
+    auth.rs           # Auth endpoint tests
+  models/
+    users.rs          # Model unit tests
+  workers/
+    report_worker.rs  # Worker tests
+```
+
+### Frontend (optional) (`frontend/`)
+**Purpose**: SPA frontend when using Loco with a JS framework
+**Pattern**: Separate directory, served as static assets
+
+---
+
+## Naming Conventions
+
+### Rust / Loco
+- **Models**: Singular, PascalCase for type (`User`, `Post`), snake_case for file (`users.rs`)
+- **Controllers**: snake_case, grouped by resource (`posts.rs`, `auth.rs`)
+- **Views**: snake_case, mirrors controller (`posts.rs`)
+- **Workers**: Descriptive + Worker (`ReportWorker` in `report_worker.rs`)
+- **Tasks**: Descriptive (`SyncData` in `sync_data.rs`)
+- **Migrations**: Timestamped + descriptive (`m20231001_000001_create_users`)
+- **Tables**: Plural, snake_case (`users`, `draft_posts`)
+- **Columns**: snake_case (`created_at`, `user_id`)
+
+### Files
+- **Rust source**: snake_case (`user_service.rs`)
+- **Config**: kebab or snake_case YAML (`development.yaml`)
+- **Migrations**: Timestamp-prefixed (`m20231001_000001_*.rs`)
+
+---
+
+## Module Organization
+
+### `src/app.rs`
+Central application hook -- register routes, workers, tasks, initializers:
+
+```rust
+impl Hooks for App {
+    fn routes(ctx: &AppContext) -> AppRoutes {
+        AppRoutes::with_default_routes()
+            .prefix("api")
+            .add_route(controllers::posts::routes())
+            .add_route(controllers::auth::routes())
+    }
+
+    async fn connect_workers(ctx: &AppContext, queue: &Queue) -> Result<()> {
+        queue.register(ReportWorker::build(ctx)).await?;
+        Ok(())
+    }
+}
+```
+
+### `src/lib.rs`
+Module declarations and re-exports:
+
+```rust
+pub mod app;
+pub mod controllers;
+pub mod models;
+pub mod views;
+pub mod workers;
+pub mod tasks;
+pub mod mailers;
+```
+
+---
+
+## Configuration Patterns
+
+### Environment-Specific (`config/*.yaml`)
+- Development: `auto_migrate: true`, debug logging, relaxed settings
+- Test: `dangerously_truncate: true` for clean test runs
+- Production: no dangerous flags, explicit migration, secure JWT secret
+
+### Key Config Sections
+```yaml
+server:
+  port: 5150
+  host: http://localhost
+
+database:
+  uri: postgres://localhost/myapp_dev
+  auto_migrate: true
+  min_connections: 1
+  max_connections: 5
+
+auth:
+  jwt:
+    secret: <secure-random>
+    expiration: 604800  # 7 days
+
+workers:
+  mode: BackgroundAsync  # or BackgroundQueue for Redis
+
+queue:
+  kind: Redis
+  uri: redis://localhost:6379
+
+logger:
+  level: debug
+  format: compact
+```
+
+---
+
+## Import Organization
+
+```rust
+// Standard library
+use std::sync::Arc;
+
+// External crates
+use loco_rs::prelude::*;
+use sea_orm::*;
+use serde::{Deserialize, Serialize};
+
+// Internal modules
+use crate::models::_entities::users;
+use crate::views::posts::PostResponse;
+```
+
+---
+
+_Document patterns, not file trees. New files following patterns should not require updates._

package/framework/stacks/loco/tech.md

@@ -0,0 +1,129 @@
+# Technology Stack
+
+## Architecture
+
+Rust web application built on Loco framework (Rails-inspired). Axum-based HTTP layer, SeaORM for persistence, Tokio async runtime, background workers via Redis or in-process queues, single-binary deployment.
+
+---
+
+## Core Technologies
+
+- **Language**: Rust stable (Edition 2021, 1.70+)
+- **Framework**: Loco (Rails-inspired, convention over configuration)
+- **Web Server**: Axum (Tower-based, Tokio-native)
+- **Async Runtime**: Tokio (multi-threaded)
+- **ORM**: SeaORM (async, ActiveRecord-style)
+- **Database**: PostgreSQL, SQLite, or MySQL
+- **Serialization**: serde + serde_json
+
+---
+
+## Key Libraries
+
+### Web & API
+- **Axum**: HTTP routing and middleware (managed by Loco)
+- **Tower / tower-http**: Middleware stack (CORS, compression, tracing, secure headers)
+- **utoipa**: OpenAPI documentation generation
+- **validator**: Struct validation with derive macros
+
+### Database & Storage
+- **SeaORM**: Async ORM with migration system and entity generation
+- **sea-orm-cli**: Code generation and migration tooling
+- **loco-rs storage**: Multi-backend storage (disk, S3, GCP, Azure, in-memory)
+
+### Background Processing
+- **sidekiq-rs** (via Loco): Redis-backed background job queue
+- **Tokio tasks**: In-process async workers for lightweight jobs
+
+### Authentication & Security
+- **jsonwebtoken**: JWT token generation and validation
+- **bcrypt**: Password hashing
+- **loco-rs auth**: Built-in JWT + API key authentication middleware
+
+### Serialization & Validation
+- **serde**: Derive-based serialization/deserialization
+- **serde_json**: JSON support
+- **validator**: Struct-level validation with derive macros
+
+### Observability
+- **tracing**: Structured, async-aware logging and diagnostics
+- **tracing-subscriber**: Log formatting (compact, pretty, JSON)
+
+### Testing
+- **cargo test / cargo-nextest**: Test execution
+- **loco-rs testing**: Custom test kit per app layer (models, requests, workers)
+- **insta**: Snapshot testing for views and responses
+
+---
+
+## Development Environment
+
+### Required Tools
+- Rust stable 1.70+ (Edition 2021)
+- Cargo (bundled with rustup)
+- Loco CLI (`cargo install loco`)
+- SeaORM CLI (`cargo install sea-orm-cli`)
+- PostgreSQL 14+ or SQLite3
+- Redis 7+ (for queue-backed workers)
+- Docker & Docker Compose (optional)
+
+### Common Commands
+```bash
+# Project setup
+loco new                              # Scaffold new project
+cargo build                           # Build project
+cargo build --release                 # Release build
+
+# Dev server
+cargo loco start                      # Start server
+cargo loco start --server-and-worker  # Server + workers in one process
+
+# Workers
+cargo loco start --worker             # Standalone worker process
+cargo loco start --worker email       # Worker filtered by tag
+
+# Generators
+cargo loco generate model posts title:string! content:text
+cargo loco generate controller posts
+cargo loco generate scaffold posts title:string! content:text
+cargo loco generate worker report_generator
+cargo loco generate task sync_data
+
+# Database
+cargo loco db migrate                 # Run pending migrations
+cargo loco db down                    # Rollback last migration
+cargo loco db seed                    # Seed database
+cargo loco db entities                # Regenerate entities from schema
+
+# Tasks
+cargo loco task <task_name>           # Run a task
+
+# Code quality
+cargo clippy -- -D warnings           # Lint (deny warnings)
+cargo fmt                             # Format
+cargo test                            # All tests
+cargo nextest run                     # Faster parallel test runner
+
+# Deployment
+cargo loco generate deployment        # Generate Docker/Nginx/Shuttle configs
+cargo loco doctor --production        # Validate production environment
+```
+
+---
+
+## Key Technical Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Loco over bare Axum** | Convention over configuration; generators, auth, workers, and ORM integrated out of the box |
+| **SeaORM over SQLx/Diesel** | ActiveRecord-style fits Loco's Rails philosophy; async-native, migration system, entity generation |
+| **Axum (via Loco)** | Tower middleware ecosystem, Tokio-native, best DX in Rust web |
+| **Redis queue over in-process** | Scales horizontally; workers run as separate processes in production |
+| **JWT for authentication** | Stateless, SaaS-ready; built into Loco's starter templates |
+| **tracing over log** | Structured, span-based, async-aware, OpenTelemetry compatible |
+| **Single binary deployment** | No runtime dependencies on server; ~20MB binary, minimal resource usage |
+| **Convention over configuration** | Folder structure, config shape, and wiring follow Loco conventions to reduce decision fatigue |
+
+---
+
+_Document standards and patterns, not every dependency. See `loco.md` for detailed framework conventions._

package/framework/stacks/loco/testing.md

@@ -0,0 +1,211 @@
+# Testing
+
+Testing conventions for Loco applications. Loco provides a custom test kit tailored per app layer.
+
+---
+
+## Philosophy
+
+- **Test models thoroughly**: Fat models means model tests cover most logic
+- **Test controllers via requests**: Integration tests over unit tests for HTTP layer
+- **Test workers in isolation**: Use `ForegroundBlocking` mode in test config
+- **Snapshot tests for views**: Reduce assertion boilerplate with `insta`
+
+---
+
+## Setup
+
+### Enable Testing Features
+```toml
+# Cargo.toml
+[dev-dependencies]
+loco-rs = { version = "*", features = ["testing"] }
+serial_test = "3"
+insta = { version = "1", features = ["yaml", "redactions"] }
+```
+
+### Test Configuration (`config/test.yaml`)
+```yaml
+database:
+  uri: postgres://localhost/myapp_test
+  dangerously_truncate: true    # Clean DB per test
+  auto_migrate: true
+
+workers:
+  mode: ForegroundBlocking       # Synchronous worker execution
+```
+
+---
+
+## Model Tests
+
+Test domain logic directly on models:
+
+```rust
+#[tokio::test]
+async fn test_create_user() {
+    let boot = boot_test::<App, Migrator>().await.unwrap();
+    seed::<App>(&boot.app_context).await.unwrap();
+
+    let user = users::ActiveModel::register(
+        &boot.app_context.db,
+        &RegisterParams {
+            email: "test@example.com".into(),
+            password: "secure123".into(),
+            name: "Test User".into(),
+        },
+    )
+    .await
+    .unwrap();
+
+    assert_eq!(user.email, "test@example.com");
+    assert!(user.email_verification_token.is_some());
+}
+```
+
+---
+
+## Request Tests (Controllers)
+
+Generated automatically with `cargo loco generate controller`. Test full HTTP request/response cycle:
+
+```rust
+use loco_rs::testing::prelude::*;
+
+#[tokio::test]
+#[serial]
+async fn test_list_posts() {
+    request::<App, Migrator, _, _>(|request, ctx| async move {
+        seed::<App>(&ctx).await.unwrap();
+
+        let response = request.get("/api/posts").await;
+
+        assert_eq!(response.status_code(), 200);
+        response.assert_json_contains(json!([{"title": "First Post"}]));
+    })
+    .await;
+}
+
+#[tokio::test]
+#[serial]
+async fn test_create_post_authenticated() {
+    request::<App, Migrator, _, _>(|request, ctx| async move {
+        let user = prepare_authenticated_user(&ctx).await;
+
+        let response = request
+            .post("/api/posts")
+            .add_header("Authorization", format!("Bearer {}", user.token))
+            .json(&json!({"title": "New Post", "content": "Hello"}))
+            .await;
+
+        assert_eq!(response.status_code(), 201);
+    })
+    .await;
+}
+```
+
+### Database Isolation
+Use `request_with_create_db` for async tests requiring isolated schemas:
+
+```rust
+#[tokio::test]
+async fn test_concurrent_safe() {
+    request_with_create_db::<App, Migrator, _, _>(|request, ctx| async move {
+        // Each test gets its own database schema
+    })
+    .await;
+}
+```
+
+---
+
+## Worker Tests
+
+Configure `ForegroundBlocking` in test config for synchronous execution:
+
+```rust
+#[tokio::test]
+async fn test_report_worker() {
+    let boot = boot_test::<App, Migrator>().await.unwrap();
+
+    let result = ReportWorker::perform_later(
+        &boot.app_context,
+        ReportArgs { user_id: 1 },
+    )
+    .await;
+
+    assert!(result.is_ok());
+}
+```
+
+---
+
+## Snapshot Testing
+
+Use `insta` to snapshot API responses and reduce manual assertions:
+
+```rust
+#[tokio::test]
+#[serial]
+async fn test_user_response_shape() {
+    request::<App, Migrator, _, _>(|request, ctx| async move {
+        let response = request.get("/api/users/1").await;
+
+        insta::assert_yaml_snapshot!(
+            response.json::<serde_json::Value>(),
+            {
+                ".created_at" => "[timestamp]",
+                ".updated_at" => "[timestamp]",
+            }
+        );
+    })
+    .await;
+}
+```
+
+---
+
+## Test Organization
+
+```
+tests/
+  requests/           # Controller integration tests
+    posts.rs
+    auth.rs
+  models/             # Model unit tests
+    users.rs
+    posts.rs
+  workers/            # Worker tests
+    report_worker.rs
+```
+
+**Pattern**: Mirror `src/` structure in `tests/`.
+
+---
+
+## Common Commands
+
+```bash
+cargo test                          # Run all tests
+cargo nextest run                   # Faster parallel runner
+cargo test -- --test-threads=1      # Serial execution (DB-dependent)
+cargo test tests::requests::posts   # Run specific module
+cargo insta review                  # Review snapshot changes
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Testing controller logic directly | Misses middleware, auth, routing | Use request tests via `loco_rs::testing` |
+| Shared test database without truncation | Flaky tests from leftover data | Enable `dangerously_truncate` in test config |
+| Testing auto-generated entities | Tests break on regeneration | Test your model methods, not SeaORM internals |
+| `BackgroundAsync` in tests | Non-deterministic worker execution | Use `ForegroundBlocking` mode |
+| Large assertion blocks | Brittle, hard to maintain | Use `insta` snapshot testing |
+| Skipping auth in tests | Misses permission bugs | Use helper to create authenticated test requests |
+
+---
+
+_Test models for correctness, controllers for integration, workers for isolation. Let generators create test scaffolding._