red64-cli 0.5.0 → 0.6.0

package/framework/stacks/javascript/testing.md

@@ -0,0 +1,209 @@
+# Testing Patterns
+
+Comprehensive Vitest patterns for modern Node.js projects.
+
+---
+
+## Philosophy
+
+- **Fast feedback**: Unit tests run in milliseconds, no I/O
+- **Realistic integration**: Test with real HTTP calls and database when it matters
+- **Readable tests**: Each test tells a story with arrange-act-assert
+- **Native ESM**: Vitest runs ESM natively, no transpilation step
+
+---
+
+## Test Organization
+
+```
+tests/
+  setup.js                    # Global test setup
+  unit/
+    services/
+      user-service.test.js
+    utils/
+      validation.test.js
+  integration/
+    api/
+      users.test.js
+    repositories/
+      user-repo.test.js
+  fixtures/
+    users.js
+```
+
+**Pattern**: Mirror `src/` structure. Suffix all test files with `.test.js`.
+
+---
+
+## Vitest Configuration
+
+```javascript
+// vitest.config.js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.js'],
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.js'],
+      thresholds: { lines: 80, functions: 80, branches: 75 },
+    },
+    testTimeout: 5000,
+    hookTimeout: 10000,
+  },
+});
+```
+
+---
+
+## Basic Test Patterns
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { calculateTotal } from '../../src/services/pricing.js';
+
+describe('calculateTotal', () => {
+  it('sums item prices', () => {
+    const items = [{ price: 1000 }, { price: 2500 }];
+    expect(calculateTotal(items)).toBe(3500);
+  });
+
+  it('returns 0 for empty array', () => {
+    expect(calculateTotal([])).toBe(0);
+  });
+});
+```
+
+---
+
+## Mocking
+
+### vi.fn() and vi.mock()
+
+```javascript
+import { describe, it, expect, vi } from 'vitest';
+import { createUser } from '../../src/services/user-service.js';
+
+vi.mock('../../src/repositories/user-repo.js', () => ({
+  userRepo: { findByEmail: vi.fn(), save: vi.fn() },
+}));
+
+import { userRepo } from '../../src/repositories/user-repo.js';
+
+describe('createUser', () => {
+  it('saves user when email is available', async () => {
+    userRepo.findByEmail.mockResolvedValue(null);
+    userRepo.save.mockResolvedValue({ id: 1, name: 'Alice' });
+
+    const user = await createUser({ name: 'Alice', email: 'alice@test.com', password: 'secret' });
+
+    expect(user.id).toBe(1);
+    expect(userRepo.save).toHaveBeenCalledOnce();
+  });
+
+  it('throws ConflictError when email exists', async () => {
+    userRepo.findByEmail.mockResolvedValue({ id: 99 });
+
+    await expect(
+      createUser({ name: 'Bob', email: 'taken@test.com', password: 'secret' }),
+    ).rejects.toThrow('Email already registered');
+  });
+});
+```
+
+---
+
+## Testing Async Code
+
+```javascript
+it('rejects with NotFoundError for missing user', async () => {
+  await expect(userService.getUser(999)).rejects.toThrow('User not found');
+  await expect(userService.getUser(999)).rejects.toBeInstanceOf(NotFoundError);
+});
+```
+
+---
+
+## Integration Testing with Supertest
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import { app } from '../../src/app.js';
+
+describe('POST /api/users', () => {
+  it('creates a new user', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: 'Alice', email: 'alice@test.com', password: 'secure123' })
+      .expect(201);
+
+    expect(response.body.email).toBe('alice@test.com');
+    expect(response.body).not.toHaveProperty('password');
+  });
+
+  it('returns 422 for invalid data', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({ name: '' })
+      .expect(422);
+
+    expect(response.body.error.code).toBe('VALIDATION_ERROR');
+  });
+});
+```
+
+---
+
+## Test Fixtures
+
+```javascript
+// tests/fixtures/users.js
+export function buildUser(overrides = {}) {
+  return {
+    id: 1,
+    name: 'Alice',
+    email: 'alice@test.com',
+    role: 'user',
+    isActive: true,
+    createdAt: new Date('2025-01-01'),
+    ...overrides,
+  };
+}
+```
+
+---
+
+## Parameterized Tests
+
+```javascript
+describe('isValidEmail', () => {
+  it.each([
+    ['user@example.com', true],
+    ['invalid', false],
+    ['', false],
+    ['@example.com', false],
+  ])('validates "%s" as %s', (email, expected) => {
+    expect(isValidEmail(email)).toBe(expected);
+  });
+});
+```
+
+---
+
+## Test Commands
+
+```bash
+npx vitest run tests/unit/ --reporter=dot     # Unit tests, minimal output
+npx vitest                                    # Watch mode with HMR
+npx vitest run --coverage                     # All tests + coverage
+npx vitest run --reporter=junit --outputFile=results.xml  # CI
+```
+
+---
+
+_Tests document behavior. Each test should read as a specification of what the code does._

package/framework/stacks/loco/code-quality.md

@@ -0,0 +1,156 @@
+# Code Quality
+
+Code quality standards and tooling for Loco applications. Automated enforcement where possible, conventions where not.
+
+---
+
+## Tooling
+
+### Required in CI
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| `cargo fmt` | Code formatting | `cargo fmt -- --check` |
+| `cargo clippy` | Linting | `cargo clippy -- -D warnings` |
+| `cargo test` | Test suite | `cargo test` or `cargo nextest run` |
+| `cargo audit` | Dependency vulnerabilities | `cargo audit` |
+| `cargo loco doctor` | Environment validation | `cargo loco doctor --production` |
+
+### Recommended
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| `cargo nextest` | Faster parallel tests | `cargo nextest run` |
+| `cargo deny` | License and advisory checks | `cargo deny check` |
+| `cargo machete` | Unused dependency detection | `cargo machete` |
+
+---
+
+## Formatting
+
+Run `cargo fmt` and move on. Configure in `rustfmt.toml` if needed:
+
+```toml
+# rustfmt.toml
+edition = "2021"
+max_width = 100
+use_field_init_shorthand = true
+```
+
+---
+
+## Linting
+
+### Clippy Configuration
+
+Deny warnings in CI, allow iterative development locally:
+
+```bash
+# CI: strict
+cargo clippy -- -D warnings
+
+# Local: advisory
+cargo clippy
+```
+
+Common Clippy lints to enforce:
+- `clippy::unwrap_used` -- no `.unwrap()` in production code
+- `clippy::expect_used` -- prefer `?` or `.ok_or()`
+- `clippy::large_enum_variant` -- box large variants
+- `clippy::needless_pass_by_value` -- borrow instead of clone
+
+---
+
+## Code Review Checklist
+
+### Controllers
+- [ ] Thin: validate, delegate, respond (under 15 lines)
+- [ ] Uses Axum extractors for request data
+- [ ] Returns `Result<impl IntoResponse>`
+- [ ] Auth-protected routes use `auth::JWT` extractor
+
+### Models
+- [ ] Domain logic lives here, not in controllers
+- [ ] `_entities/` files are untouched
+- [ ] Validation implemented via `Validatable` trait
+- [ ] Queries use SeaORM, not raw SQL
+
+### Workers
+- [ ] Self-contained, no shared controller state
+- [ ] Args are `Serialize + Deserialize`
+- [ ] Error handling with logging context
+- [ ] Registered in `app.rs` `connect_workers`
+
+### Migrations
+- [ ] Descriptive names matching auto-detection patterns
+- [ ] `down()` implemented for rollback
+- [ ] Required fields use NOT NULL
+- [ ] Foreign keys and indexes added
+
+### Tests
+- [ ] Model tests for domain logic
+- [ ] Request tests for controller endpoints
+- [ ] Auth tested on protected routes
+- [ ] `ForegroundBlocking` mode in test config
+
+---
+
+## Dependency Management
+
+### Adding Dependencies
+
+```toml
+# Cargo.toml -- pin major versions
+[dependencies]
+loco-rs = "0.x"
+sea-orm = { version = "1", features = ["sqlx-postgres", "runtime-tokio-rustls"] }
+serde = { version = "1", features = ["derive"] }
+```
+
+### Rules
+- Pin major version, allow minor/patch updates
+- Enable only needed feature flags
+- Audit new dependencies: `cargo audit`, `cargo deny`
+- Prefer well-maintained crates with recent activity
+- Remove unused dependencies: `cargo machete`
+
+---
+
+## Performance Guidelines
+
+### Database
+- Use `includes` / eager loading for associations (avoid N+1)
+- Add indexes for frequently queried columns
+- Configure connection pool sizes per environment
+- Use `explain` for slow queries
+
+### HTTP
+- Enable compression middleware in production
+- Use Loco's built-in caching layer for repeated queries
+- Return only needed fields in view structs (not full entities)
+
+### Workers
+- Use `BackgroundQueue` (Redis/Postgres) for production horizontal scaling
+- Tag workers for resource-intensive jobs
+- Keep job args small -- pass IDs, not full objects
+
+---
+
+## Security
+
+### Built-in Protections
+- JWT authentication with configurable token location
+- Secure headers middleware (enabled by default)
+- CORS configuration via YAML
+
+### Practices
+- Never commit secrets -- use environment config or Loco's config system
+- Rotate JWT secrets in production
+- Enable `secure_headers` middleware with appropriate presets
+- Validate all user input via `Validatable` or `JsonValidate`
+- Use parameterized SeaORM queries (never string interpolation in queries)
+- Run `cargo audit` in CI
+
+---
+
+_Automate quality: fmt for formatting, clippy for linting, tests for correctness, audit for security. Human review for architecture and domain logic._

package/framework/stacks/loco/coding-style.md

@@ -0,0 +1,247 @@
+# Loco Coding Style
+
+Coding style conventions for idiomatic Loco applications. Combines Rust best practices with Loco's Rails-inspired conventions.
+
+---
+
+## Philosophy
+
+- **Convention over configuration**: Follow Loco's prescribed patterns
+- **Fat models, slim controllers**: Business logic belongs on models
+- **Use generators**: Scaffolding maintains consistency
+- **Leverage the type system**: Encode invariants in types, not runtime checks
+- **Clippy is law**: If Clippy warns, fix it
+
+---
+
+## Naming Conventions
+
+### Loco-Specific Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Controller functions | snake_case verbs | `create`, `list`, `show`, `update`, `destroy` |
+| Route prefixes | plural resource name | `"posts"`, `"users"`, `"auth"` |
+| Model methods | domain verbs | `register`, `verify_email`, `reset_password` |
+| Worker structs | PascalCase + Worker | `ReportWorker`, `EmailWorker` |
+| Worker args | PascalCase + Args | `ReportArgs`, `EmailArgs` |
+| Task structs | PascalCase | `SeedData`, `SyncUsers` |
+| View structs | PascalCase + Response | `PostResponse`, `UserResponse` |
+| Migration files | timestamp + description | `m20231001_000001_create_users` |
+
+### Standard Rust Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Variables, functions | `snake_case` | `user_count`, `get_user` |
+| Types, traits, enums | `PascalCase` | `UserService`, `Serialize` |
+| Constants | `SCREAMING_SNAKE_CASE` | `MAX_RETRIES`, `DEFAULT_PORT` |
+| Modules | `snake_case` | `user_service`, `auth_utils` |
+| Lifetimes | Short lowercase with `'` | `'a`, `'ctx` |
+
+### Boolean Naming
+
+Prefix with `is_`, `has_`, `can_`, `should_`:
+
+```rust
+struct User {
+    is_active: bool,
+    has_verified_email: bool,
+    can_publish: bool,
+}
+```
+
+---
+
+## Controller Style
+
+### Thin Controllers
+
+```rust
+// GOOD: Delegates to model
+async fn create(
+    State(ctx): State<AppContext>,
+    Json(params): Json<CreatePostParams>,
+) -> Result<Json<PostResponse>> {
+    let post = posts::ActiveModel::create(&ctx.db, &params).await?;
+    Ok(Json(PostResponse::from(post)))
+}
+
+// BAD: Logic in controller
+async fn create(
+    State(ctx): State<AppContext>,
+    Json(params): Json<CreatePostParams>,
+) -> Result<Json<PostResponse>> {
+    // Validation logic here...
+    // Business rules here...
+    // Direct SQL here...
+    // Email sending here...
+}
+```
+
+### Consistent Route Structure
+
+```rust
+// GOOD: RESTful, predictable
+pub fn routes() -> Routes {
+    Routes::new()
+        .prefix("posts")
+        .add("/", get(list))
+        .add("/", post(create))
+        .add("/:id", get(show))
+        .add("/:id", put(update))
+        .add("/:id", delete(destroy))
+}
+```
+
+---
+
+## Model Style
+
+### Domain Methods
+
+```rust
+// GOOD: Rich domain model
+impl super::_entities::users::ActiveModel {
+    pub async fn register(db: &DatabaseConnection, params: &RegisterParams) -> ModelResult<Self> {
+        // Complete workflow in one place
+    }
+
+    pub async fn find_by_email(db: &DatabaseConnection, email: &str) -> ModelResult<Self> {
+        // Reusable query
+    }
+}
+
+// BAD: Anemic model, logic scattered elsewhere
+// (query in controller, validation in middleware, email in separate service)
+```
+
+### Validation
+
+Use the `validator` crate with `Validatable` trait:
+
+```rust
+impl Validatable for super::_entities::users::ActiveModel {
+    fn validator(&self) -> Box<dyn Validate> {
+        Box::new(UserValidator {
+            email: self.email.clone().into_value().unwrap_or_default(),
+        })
+    }
+}
+
+// Always validate before persistence
+user.validate()?;
+user.insert(db).await?;
+```
+
+---
+
+## Error Handling Style
+
+### Use `?` Operator Consistently
+
+```rust
+// GOOD: Flat with ? operator
+async fn publish(ctx: &AppContext, id: i32, user_id: i32) -> Result<Post> {
+    let post = posts::Entity::find_by_id(id)
+        .one(&ctx.db)
+        .await?
+        .ok_or_else(|| Error::NotFound)?;
+
+    if post.user_id != user_id {
+        return Err(Error::Unauthorized("Not your post".into()));
+    }
+
+    update_status(&ctx.db, id, Status::Published).await
+}
+
+// BAD: Deeply nested match/if chains
+```
+
+---
+
+## View Style
+
+### Explicit Response Structs
+
+```rust
+// GOOD: Dedicated view struct with From impl
+#[derive(Serialize)]
+pub struct PostResponse {
+    pub id: i32,
+    pub title: String,
+    pub author_name: String,  // Derived, not raw FK
+}
+
+impl PostResponse {
+    pub fn from_model_with_user(post: posts::Model, user: users::Model) -> Self {
+        Self {
+            id: post.id,
+            title: post.title,
+            author_name: user.name,
+        }
+    }
+}
+
+// BAD: Returning raw entity models as JSON
+```
+
+---
+
+## Worker Style
+
+### Self-Contained with Serializable Args
+
+```rust
+// GOOD: Serializable args, no shared state
+#[derive(Serialize, Deserialize)]
+pub struct EmailArgs {
+    pub user_id: i32,
+    pub template: String,
+}
+
+#[async_trait]
+impl BackgroundWorker<EmailArgs> for EmailWorker {
+    fn build(ctx: &AppContext) -> Self { Self { ctx: ctx.clone() } }
+
+    async fn perform(&self, args: EmailArgs) -> Result<()> {
+        let user = users::Entity::find_by_id(args.user_id)
+            .one(&self.ctx.db).await?
+            .ok_or(Error::NotFound)?;
+        // Send email using args.template
+        Ok(())
+    }
+}
+
+// BAD: Passing non-serializable types, referencing controller state
+```
+
+---
+
+## File and Type Size
+
+| Element | Guideline |
+|---|---|
+| Controller function | Under 15 lines (validate, delegate, respond) |
+| Model method | Under 30 lines of logic |
+| View struct | Under 50 lines |
+| Worker perform | Under 40 lines |
+| Module file | Under 300 lines, max 500 |
+| Parameters | Max 5 per function; use struct for more |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Fat controllers | Untestable, unreusable logic | Move to model methods |
+| `.unwrap()` in handlers | Panics crash the request | Use `?` and proper error types |
+| Raw entity as response | Exposes internal schema | Use view structs with `From` |
+| Business logic in workers | Duplicates model logic | Call model methods from workers |
+| Ignoring generators | Inconsistent file placement | Always use `cargo loco generate` |
+| `clone()` on large structs | Hidden performance cost | Borrow with `&` or use `Arc` |
+
+---
+
+_Follow Loco conventions: generators for scaffolding, models for logic, controllers for routing, views for shaping. Let the framework guide structure._