@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/fastapi-expert/references/pydantic-v2.md

@@ -0,0 +1,135 @@
+# Pydantic V2 Schemas
+
+## Schema Patterns
+
+```python
+from pydantic import BaseModel, EmailStr, Field, field_validator, model_validator
+from typing import Self
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8)
+    username: str = Field(min_length=3, max_length=50)
+    age: int = Field(ge=18, le=120)
+
+    @field_validator('password')
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain uppercase')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain digit')
+        return v
+
+    @field_validator('username')
+    @classmethod
+    def validate_username(cls, v: str) -> str:
+        if not v.isalnum():
+            raise ValueError('Username must be alphanumeric')
+        return v.lower()
+
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    username: str | None = Field(None, min_length=3, max_length=50)
+```
+
+## ORM Mode (from_attributes)
+
+```python
+class UserResponse(BaseModel):
+    model_config = {"from_attributes": True}
+
+    id: int
+    email: EmailStr
+    username: str
+    is_active: bool = True
+    created_at: datetime
+
+# Usage with SQLAlchemy model
+user_response = UserResponse.model_validate(db_user)
+```
+
+## Model Validator
+
+```python
+class OrderCreate(BaseModel):
+    items: list[OrderItem]
+    discount_code: str | None = None
+    total: float
+
+    @model_validator(mode='after')
+    def validate_order(self) -> Self:
+        calculated = sum(item.price * item.quantity for item in self.items)
+        if abs(self.total - calculated) > 0.01:
+            raise ValueError('Total does not match items')
+        return self
+```
+
+## Nested Models
+
+```python
+class Address(BaseModel):
+    street: str
+    city: str
+    country: str = Field(default="US")
+
+class UserWithAddress(BaseModel):
+    name: str
+    addresses: list[Address] = Field(default_factory=list)
+```
+
+## Serialization Control
+
+```python
+class User(BaseModel):
+    model_config = {
+        "from_attributes": True,
+        "json_schema_extra": {
+            "example": {"email": "user@example.com", "username": "johndoe"}
+        }
+    }
+
+    id: int
+    email: EmailStr
+    password: str = Field(exclude=True)  # Never serialize
+    internal_id: str = Field(repr=False)  # Hide from repr
+
+# Serialize with aliases
+class ApiResponse(BaseModel):
+    model_config = {"populate_by_name": True}
+
+    user_id: int = Field(alias="userId", serialization_alias="user_id")
+```
+
+## Settings (Pydantic V2)
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+    )
+
+    DATABASE_URL: str
+    SECRET_KEY: str
+    DEBUG: bool = False
+    CORS_ORIGINS: list[str] = ["http://localhost:3000"]
+    API_V1_PREFIX: str = "/api/v1"
+
+settings = Settings()
+```
+
+## Quick Reference
+
+| V1 Syntax | V2 Syntax |
+|-----------|-----------|
+| `@validator` | `@field_validator` |
+| `@root_validator` | `@model_validator` |
+| `class Config` | `model_config = {}` |
+| `orm_mode = True` | `from_attributes = True` |
+| `Optional[X]` | `X \| None` |
+| `.dict()` | `.model_dump()` |
+| `.parse_obj()` | `.model_validate()` |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/fastapi-expert/references/testing-async.md

@@ -0,0 +1,159 @@
+# Async Testing
+
+## Test Setup
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+
+from app.main import app
+from app.core.deps import get_db
+from app.models import Base
+
+# Test database
+TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
+test_engine = create_async_engine(TEST_DATABASE_URL, echo=True)
+test_session = async_sessionmaker(test_engine, expire_on_commit=False)
+
+@pytest.fixture(scope="session")
+def anyio_backend():
+    return "asyncio"
+
+@pytest.fixture(scope="function")
+async def db():
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    async with test_session() as session:
+        yield session
+    async with test_engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+@pytest.fixture
+async def client(db: AsyncSession):
+    def override_get_db():
+        return db
+
+    app.dependency_overrides[get_db] = override_get_db
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test"
+    ) as ac:
+        yield ac
+    app.dependency_overrides.clear()
+```
+
+## Endpoint Tests
+
+```python
+@pytest.mark.asyncio
+async def test_create_user(client: AsyncClient):
+    response = await client.post("/api/v1/users/", json={
+        "email": "test@example.com",
+        "username": "testuser",
+        "password": "Test1234"
+    })
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert "password" not in data
+
+@pytest.mark.asyncio
+async def test_get_user_not_found(client: AsyncClient):
+    response = await client.get("/api/v1/users/999")
+    assert response.status_code == 404
+
+@pytest.mark.asyncio
+async def test_list_users(client: AsyncClient, auth_headers: dict):
+    response = await client.get("/api/v1/users/", headers=auth_headers)
+    assert response.status_code == 200
+    assert isinstance(response.json(), list)
+```
+
+## Auth Helper Fixture
+
+```python
+@pytest.fixture
+async def test_user(db: AsyncSession) -> User:
+    user = User(
+        email="auth@test.com",
+        username="authuser",
+        hashed_password=hash_password("Test1234"),
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+@pytest.fixture
+async def auth_headers(test_user: User) -> dict:
+    token = create_access_token(sub=str(test_user.id))
+    return {"Authorization": f"Bearer {token}"}
+
+@pytest.mark.asyncio
+async def test_protected_endpoint(client: AsyncClient, auth_headers: dict):
+    response = await client.get("/api/v1/users/me", headers=auth_headers)
+    assert response.status_code == 200
+
+@pytest.mark.asyncio
+async def test_protected_endpoint_no_auth(client: AsyncClient):
+    response = await client.get("/api/v1/users/me")
+    assert response.status_code == 401
+```
+
+## Service Tests
+
+```python
+@pytest.mark.asyncio
+async def test_create_user_service(db: AsyncSession):
+    user_in = UserCreate(
+        email="service@test.com",
+        username="serviceuser",
+        password="Test1234"
+    )
+    user = await create_user_db(db, user_in)
+
+    assert user.id is not None
+    assert user.email == "service@test.com"
+
+@pytest.mark.asyncio
+async def test_get_user_not_found_service(db: AsyncSession):
+    user = await get_user_db(db, 999)
+    assert user is None
+
+@pytest.mark.asyncio
+async def test_duplicate_email(db: AsyncSession):
+    user_in = UserCreate(email="dup@test.com", username="user1", password="Test1234")
+    await create_user_db(db, user_in)
+
+    with pytest.raises(IntegrityError):
+        user_in2 = UserCreate(email="dup@test.com", username="user2", password="Test1234")
+        await create_user_db(db, user_in2)
+```
+
+## Mocking Dependencies
+
+```python
+from unittest.mock import AsyncMock, patch
+
+@pytest.mark.asyncio
+async def test_with_mock_service(client: AsyncClient):
+    mock_user = User(id=1, email="mock@test.com", username="mock")
+
+    with patch("app.api.v1.users.get_user_db", new_callable=AsyncMock) as mock:
+        mock.return_value = mock_user
+        response = await client.get("/api/v1/users/1")
+        assert response.status_code == 200
+        assert response.json()["email"] == "mock@test.com"
+```
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| `@pytest.mark.asyncio` | Mark async test |
+| `AsyncClient` | HTTP client |
+| `ASGITransport(app=app)` | Test transport |
+| `app.dependency_overrides` | Override deps |
+| `AsyncMock` | Mock async functions |
+| `pytest.raises()` | Assert exception |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/fastify-patterns/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: "fastify-patterns"
+description: "NestJS + Fastify integration patterns including secure sessions, cookie authentication, performance optimization, and plugin configuration. Use for high-performance API development."
+---
+
+
+# Fastify Patterns
+
+## Overview
+
+Expert guidance for building high-performance NestJS applications with Fastify adapter. Covers secure session management, cookie-based authentication, plugin configuration, and performance optimization patterns.
+
+## Role Definition
+
+You are a backend performance specialist with deep expertise in Fastify and NestJS integration. You optimize for throughput, security, and maintainability while leveraging Fastify's plugin architecture.
+
+## When to Use This Skill
+
+- Setting up NestJS with Fastify adapter
+- Implementing cookie-based session authentication
+- Configuring Fastify plugins (helmet, cors, rate-limit)
+- Optimizing API performance
+- Migrating from Express to Fastify
+- Implementing secure stateless sessions
+
+## Core Workflow
+
+1. **Bootstrap** - Configure Fastify adapter with NestJS
+2. **Security** - Register security plugins (helmet, cors, secure-session)
+3. **Performance** - Configure rate limiting and caching
+4. **Validation** - Set up global validation pipes
+5. **Test** - Benchmark and verify performance gains
+
+## Available Steering Files
+
+| Topic                | Reference                       | Load When                                     |
+| -------------------- | ------------------------------- | --------------------------------------------- |
+| Secure Sessions      | `references/secure-sessions.md`   | Cookie auth, session management, key rotation |
+| Plugin Configuration | `references/plugin-config.md`     | Helmet, CORS, rate limiting, compression      |
+| Performance Tuning   | `references/performance.md`       | Benchmarking, optimization, caching           |
+| Migration Guide      | `references/express-migration.md` | Converting Express middleware to Fastify      |
+
+## Quick Reference
+
+### Bootstrap with Fastify
+
+```typescript
+// main.ts
+import { NestFactory } from "@nestjs/core";
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from "@nestjs/platform-fastify";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter({ logger: true }),
+  );
+
+  await app.listen(3000, "0.0.0.0");
+}
+bootstrap();
+```
+
+### Register Fastify Plugins
+
+```typescript
+// main.ts - Security plugins
+import helmet from "@fastify/helmet";
+import cors from "@fastify/cors";
+import rateLimit from "@fastify/rate-limit";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+  );
+
+  // Security headers
+  await app.register(helmet, {
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+      },
+    },
+  });
+
+  // CORS
+  await app.register(cors, {
+    origin: process.env.CORS_ORIGIN?.split(",") || [],
+    credentials: true,
+  });
+
+  // Rate limiting
+  await app.register(rateLimit, {
+    max: 100,
+    timeWindow: "1 minute",
+  });
+
+  await app.listen(3000, "0.0.0.0");
+}
+```
+
+### Secure Session Setup
+
+```typescript
+import cookie from "@fastify/cookie";
+import secureSession from "@fastify/secure-session";
+
+// Register cookie and session plugins
+await app.register(cookie);
+await app.register(secureSession, {
+  cookieName: process.env.SESSION_COOKIE_NAME || "session",
+  key: Buffer.from(process.env.SESSION_SECRET!, "hex"),
+  cookie: {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+  },
+});
+```
+
+## Constraints
+
+### MUST DO
+
+- Use `@nestjs/platform-fastify` adapter
+- Register security plugins before routes
+- Use `0.0.0.0` for Docker/container deployments
+- Generate session keys with `npx @fastify/secure-session`
+- Set `httpOnly: true` for session cookies
+- Enable `secure: true` in production
+
+### MUST NOT DO
+
+- Mix Express and Fastify middleware
+- Use Express-specific `req.ip` (use `request.ip` instead)
+- Hardcode session secrets
+- Skip rate limiting on auth endpoints
+- Use `localhost` in containerized environments
+
+## Performance Comparison
+
+| Metric        | Express | Fastify | Improvement |
+| ------------- | ------- | ------- | ----------- |
+| Requests/sec  | ~17,000 | ~30,000 | ~76% faster |
+| Latency (avg) | 5.8ms   | 3.3ms   | ~43% lower  |
+| Memory        | Higher  | Lower   | ~20% less   |