codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/fastapi-router-py/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: fastapi-router-py
+description: "Create FastAPI routers following established patterns with proper authentication, response models, and HTTP status codes."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# FastAPI Router
+
+Create FastAPI routers following established patterns with proper authentication, response models, and HTTP status codes.
+
+## Quick Start
+
+Copy the template from assets/template.py and replace placeholders:
+- `{{ResourceName}}` → PascalCase name (e.g., `Project`)
+- `{{resource_name}}` → snake_case name (e.g., `project`)
+- `{{resource_plural}}` → plural form (e.g., `projects`)
+
+## Authentication Patterns
+
+```python
+# Optional auth - returns None if not authenticated
+current_user: Optional[User] = Depends(get_current_user)
+
+# Required auth - raises 401 if not authenticated
+current_user: User = Depends(get_current_user_required)
+```
+
+## Response Models
+
+```python
+@router.get("/items/{item_id}", response_model=Item)
+async def get_item(item_id: str) -> Item:
+    ...
+
+@router.get("/items", response_model=list[Item])
+async def list_items() -> list[Item]:
+    ...
+```
+
+## HTTP Status Codes
+
+```python
+@router.post("/items", status_code=status.HTTP_201_CREATED)
+@router.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)
+```
+
+## Integration Steps
+
+1. Create router in `src/backend/app/routers/`
+2. Mount in `src/backend/app/main.py`
+3. Create corresponding Pydantic models
+4. Create service layer if needed
+5. Add frontend API functions
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/templates/.agent/skills/fastapi-templates/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: fastapi-templates
+description: "Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# FastAPI Project Templates
+
+Production-ready FastAPI project structures with async patterns, dependency injection, middleware, and best practices for building high-performance APIs.
+
+## Use this skill when
+
+- Starting new FastAPI projects from scratch
+- Implementing async REST APIs with Python
+- Building high-performance web services and microservices
+- Creating async applications with PostgreSQL, MongoDB
+- Setting up API projects with proper structure and testing
+
+## Do not use this skill when
+
+- The task is unrelated to fastapi project templates
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/templates/.agent/skills/fastapi-templates/resources/implementation-playbook.md

@@ -0,0 +1,566 @@
+# FastAPI Project Templates Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# FastAPI Project Templates
+
+Production-ready FastAPI project structures with async patterns, dependency injection, middleware, and best practices for building high-performance APIs.
+
+## When to Use This Skill
+
+- Starting new FastAPI projects from scratch
+- Implementing async REST APIs with Python
+- Building high-performance web services and microservices
+- Creating async applications with PostgreSQL, MongoDB
+- Setting up API projects with proper structure and testing
+
+## Core Concepts
+
+### 1. Project Structure
+
+**Recommended Layout:**
+
+```
+app/
+├── api/                    # API routes
+│   ├── v1/
+│   │   ├── endpoints/
+│   │   │   ├── users.py
+│   │   │   ├── auth.py
+│   │   │   └── items.py
+│   │   └── router.py
+│   └── dependencies.py     # Shared dependencies
+├── core/                   # Core configuration
+│   ├── config.py
+│   ├── security.py
+│   └── database.py
+├── models/                 # Database models
+│   ├── user.py
+│   └── item.py
+├── schemas/                # Pydantic schemas
+│   ├── user.py
+│   └── item.py
+├── services/               # Business logic
+│   ├── user_service.py
+│   └── auth_service.py
+├── repositories/           # Data access
+│   ├── user_repository.py
+│   └── item_repository.py
+└── main.py                 # Application entry
+```
+
+### 2. Dependency Injection
+
+FastAPI's built-in DI system using `Depends`:
+
+- Database session management
+- Authentication/authorization
+- Shared business logic
+- Configuration injection
+
+### 3. Async Patterns
+
+Proper async/await usage:
+
+- Async route handlers
+- Async database operations
+- Async background tasks
+- Async middleware
+
+## Implementation Patterns
+
+### Pattern 1: Complete FastAPI Application
+
+```python
+# main.py
+from fastapi import FastAPI, Depends
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan events."""
+    # Startup
+    await database.connect()
+    yield
+    # Shutdown
+    await database.disconnect()
+
+app = FastAPI(
+    title="API Template",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+from app.api.v1.router import api_router
+app.include_router(api_router, prefix="/api/v1")
+
+# core/config.py
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+class Settings(BaseSettings):
+    """Application settings."""
+    DATABASE_URL: str
+    SECRET_KEY: str
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    API_V1_STR: str = "/api/v1"
+
+    class Config:
+        env_file = ".env"
+
+@lru_cache()
+def get_settings() -> Settings:
+    return Settings()
+
+# core/database.py
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from app.core.config import get_settings
+
+settings = get_settings()
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=True,
+    future=True
+)
+
+AsyncSessionLocal = sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False
+)
+
+Base = declarative_base()
+
+async def get_db() -> AsyncSession:
+    """Dependency for database session."""
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+```
+
+### Pattern 2: CRUD Repository Pattern
+
+```python
+# repositories/base_repository.py
+from typing import Generic, TypeVar, Type, Optional, List
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from pydantic import BaseModel
+
+ModelType = TypeVar("ModelType")
+CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
+UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
+
+class BaseRepository(Generic[ModelType, CreateSchemaType, UpdateSchemaType]):
+    """Base repository for CRUD operations."""
+
+    def __init__(self, model: Type[ModelType]):
+        self.model = model
+
+    async def get(self, db: AsyncSession, id: int) -> Optional[ModelType]:
+        """Get by ID."""
+        result = await db.execute(
+            select(self.model).where(self.model.id == id)
+        )
+        return result.scalars().first()
+
+    async def get_multi(
+        self,
+        db: AsyncSession,
+        skip: int = 0,
+        limit: int = 100
+    ) -> List[ModelType]:
+        """Get multiple records."""
+        result = await db.execute(
+            select(self.model).offset(skip).limit(limit)
+        )
+        return result.scalars().all()
+
+    async def create(
+        self,
+        db: AsyncSession,
+        obj_in: CreateSchemaType
+    ) -> ModelType:
+        """Create new record."""
+        db_obj = self.model(**obj_in.dict())
+        db.add(db_obj)
+        await db.flush()
+        await db.refresh(db_obj)
+        return db_obj
+
+    async def update(
+        self,
+        db: AsyncSession,
+        db_obj: ModelType,
+        obj_in: UpdateSchemaType
+    ) -> ModelType:
+        """Update record."""
+        update_data = obj_in.dict(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(db_obj, field, value)
+        await db.flush()
+        await db.refresh(db_obj)
+        return db_obj
+
+    async def delete(self, db: AsyncSession, id: int) -> bool:
+        """Delete record."""
+        obj = await self.get(db, id)
+        if obj:
+            await db.delete(obj)
+            return True
+        return False
+
+# repositories/user_repository.py
+from app.repositories.base_repository import BaseRepository
+from app.models.user import User
+from app.schemas.user import UserCreate, UserUpdate
+
+class UserRepository(BaseRepository[User, UserCreate, UserUpdate]):
+    """User-specific repository."""
+
+    async def get_by_email(self, db: AsyncSession, email: str) -> Optional[User]:
+        """Get user by email."""
+        result = await db.execute(
+            select(User).where(User.email == email)
+        )
+        return result.scalars().first()
+
+    async def is_active(self, db: AsyncSession, user_id: int) -> bool:
+        """Check if user is active."""
+        user = await self.get(db, user_id)
+        return user.is_active if user else False
+
+user_repository = UserRepository(User)
+```
+
+### Pattern 3: Service Layer
+
+```python
+# services/user_service.py
+from typing import Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.repositories.user_repository import user_repository
+from app.schemas.user import UserCreate, UserUpdate, User
+from app.core.security import get_password_hash, verify_password
+
+class UserService:
+    """Business logic for users."""
+
+    def __init__(self):
+        self.repository = user_repository
+
+    async def create_user(
+        self,
+        db: AsyncSession,
+        user_in: UserCreate
+    ) -> User:
+        """Create new user with hashed password."""
+        # Check if email exists
+        existing = await self.repository.get_by_email(db, user_in.email)
+        if existing:
+            raise ValueError("Email already registered")
+
+        # Hash password
+        user_in_dict = user_in.dict()
+        user_in_dict["hashed_password"] = get_password_hash(user_in_dict.pop("password"))
+
+        # Create user
+        user = await self.repository.create(db, UserCreate(**user_in_dict))
+        return user
+
+    async def authenticate(
+        self,
+        db: AsyncSession,
+        email: str,
+        password: str
+    ) -> Optional[User]:
+        """Authenticate user."""
+        user = await self.repository.get_by_email(db, email)
+        if not user:
+            return None
+        if not verify_password(password, user.hashed_password):
+            return None
+        return user
+
+    async def update_user(
+        self,
+        db: AsyncSession,
+        user_id: int,
+        user_in: UserUpdate
+    ) -> Optional[User]:
+        """Update user."""
+        user = await self.repository.get(db, user_id)
+        if not user:
+            return None
+
+        if user_in.password:
+            user_in_dict = user_in.dict(exclude_unset=True)
+            user_in_dict["hashed_password"] = get_password_hash(
+                user_in_dict.pop("password")
+            )
+            user_in = UserUpdate(**user_in_dict)
+
+        return await self.repository.update(db, user, user_in)
+
+user_service = UserService()
+```
+
+### Pattern 4: API Endpoints with Dependencies
+
+```python
+# api/v1/endpoints/users.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import List
+
+from app.core.database import get_db
+from app.schemas.user import User, UserCreate, UserUpdate
+from app.services.user_service import user_service
+from app.api.dependencies import get_current_user
+
+router = APIRouter()
+
+@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    user_in: UserCreate,
+    db: AsyncSession = Depends(get_db)
+):
+    """Create new user."""
+    try:
+        user = await user_service.create_user(db, user_in)
+        return user
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+@router.get("/me", response_model=User)
+async def read_current_user(
+    current_user: User = Depends(get_current_user)
+):
+    """Get current user."""
+    return current_user
+
+@router.get("/{user_id}", response_model=User)
+async def read_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Get user by ID."""
+    user = await user_service.repository.get(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+@router.patch("/{user_id}", response_model=User)
+async def update_user(
+    user_id: int,
+    user_in: UserUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Update user."""
+    if current_user.id != user_id:
+        raise HTTPException(status_code=403, detail="Not authorized")
+
+    user = await user_service.update_user(db, user_id, user_in)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Delete user."""
+    if current_user.id != user_id:
+        raise HTTPException(status_code=403, detail="Not authorized")
+
+    deleted = await user_service.repository.delete(db, user_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="User not found")
+```
+
+### Pattern 5: Authentication & Authorization
+
+```python
+# core/security.py
+from datetime import datetime, timedelta
+from typing import Optional
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from app.core.config import get_settings
+
+settings = get_settings()
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+ALGORITHM = "HS256"
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
+    """Create JWT access token."""
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=15)
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=ALGORITHM)
+    return encoded_jwt
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify password against hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def get_password_hash(password: str) -> str:
+    """Hash password."""
+    return pwd_context.hash(password)
+
+# api/dependencies.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.core.security import ALGORITHM
+from app.core.config import get_settings
+from app.repositories.user_repository import user_repository
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.API_V1_STR}/auth/login")
+
+async def get_current_user(
+    db: AsyncSession = Depends(get_db),
+    token: str = Depends(oauth2_scheme)
+):
+    """Get current authenticated user."""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[ALGORITHM])
+        user_id: int = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    user = await user_repository.get(db, user_id)
+    if user is None:
+        raise credentials_exception
+
+    return user
+```
+
+## Testing
+
+```python
+# tests/conftest.py
+import pytest
+import asyncio
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+
+from app.main import app
+from app.core.database import get_db, Base
+
+TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
+
+@pytest.fixture(scope="session")
+def event_loop():
+    loop = asyncio.get_event_loop_policy().new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest.fixture
+async def db_session():
+    engine = create_async_engine(TEST_DATABASE_URL, echo=True)
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    AsyncSessionLocal = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+
+    async with AsyncSessionLocal() as session:
+        yield session
+
+@pytest.fixture
+async def client(db_session):
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        yield client
+
+# tests/test_users.py
+import pytest
+
+@pytest.mark.asyncio
+async def test_create_user(client):
+    response = await client.post(
+        "/api/v1/users/",
+        json={
+            "email": "test@example.com",
+            "password": "testpass123",
+            "name": "Test User"
+        }
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "test@example.com"
+    assert "id" in data
+```
+
+## Resources
+
+- **references/fastapi-architecture.md**: Detailed architecture guide
+- **references/async-best-practices.md**: Async/await patterns
+- **references/testing-strategies.md**: Comprehensive testing guide
+- **assets/project-template/**: Complete FastAPI project
+- **assets/docker-compose.yml**: Development environment setup
+
+## Best Practices
+
+1. **Async All The Way**: Use async for database, external APIs
+2. **Dependency Injection**: Leverage FastAPI's DI system
+3. **Repository Pattern**: Separate data access from business logic
+4. **Service Layer**: Keep business logic out of routes
+5. **Pydantic Schemas**: Strong typing for request/response
+6. **Error Handling**: Consistent error responses
+7. **Testing**: Test all layers independently
+
+## Common Pitfalls
+
+- **Blocking Code in Async**: Using synchronous database drivers
+- **No Service Layer**: Business logic in route handlers
+- **Missing Type Hints**: Loses FastAPI's benefits
+- **Ignoring Sessions**: Not properly managing database sessions
+- **No Testing**: Skipping integration tests
+- **Tight Coupling**: Direct database access in routes