oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-backend/variants/python/api-template.py

@@ -0,0 +1,378 @@
+"""
+API Endpoint Template for Backend Agent
+
+This template demonstrates best practices for FastAPI endpoints.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+from typing import Annotated, List
+from uuid import UUID
+
+from app.database import get_db
+from app.auth import get_current_user
+from app.models import User, Resource
+from app.schemas import ResourceCreate, ResourceUpdate, ResourceResponse
+from app.services import ResourceService
+
+# Type aliases for cleaner code
+DatabaseDep = Annotated[AsyncSession, Depends(get_db)]
+UserDep = Annotated[User, Depends(get_current_user)]
+
+# Router setup
+router = APIRouter(
+    prefix="/api/resources",
+    tags=["resources"],
+    responses={404: {"description": "Not found"}},
+)
+
+
+# List endpoint with pagination and filtering
+@router.get(
+    "/",
+    response_model=List[ResourceResponse],
+    summary="List resources",
+    description="Retrieve a paginated list of resources with optional filtering"
+)
+async def list_resources(
+    db: DatabaseDep,
+    current_user: UserDep,
+    skip: int = Query(0, ge=0, description="Number of records to skip"),
+    limit: int = Query(100, ge=1, le=1000, description="Max records to return"),
+    search: str | None = Query(None, description="Search query"),
+    status: str | None = Query(None, description="Filter by status"),
+):
+    """
+    List resources with pagination.
+
+    - **skip**: Offset for pagination
+    - **limit**: Maximum number of records
+    - **search**: Optional search term
+    - **status**: Optional status filter
+    """
+    service = ResourceService(db)
+    resources = await service.list_resources(
+        user_id=current_user.id,
+        skip=skip,
+        limit=limit,
+        search=search,
+        status=status,
+    )
+    return resources
+
+
+# Get single resource
+@router.get(
+    "/{resource_id}",
+    response_model=ResourceResponse,
+    summary="Get resource",
+    responses={
+        200: {"description": "Resource found"},
+        404: {"description": "Resource not found"},
+        403: {"description": "Access denied"}
+    }
+)
+async def get_resource(
+    resource_id: UUID,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Get a specific resource by ID.
+
+    Raises:
+        404: Resource not found
+        403: User doesn't own this resource
+    """
+    service = ResourceService(db)
+    resource = await service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    # Authorization check
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    return resource
+
+
+# Create resource
+@router.post(
+    "/",
+    response_model=ResourceResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create resource",
+)
+async def create_resource(
+    resource_data: ResourceCreate,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Create a new resource.
+
+    - **name**: Resource name (required)
+    - **description**: Optional description
+    - **status**: Initial status (default: active)
+    """
+    service = ResourceService(db)
+
+    try:
+        resource = await service.create_resource(
+            user_id=current_user.id,
+            data=resource_data
+        )
+        return resource
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Update resource
+@router.patch(
+    "/{resource_id}",
+    response_model=ResourceResponse,
+    summary="Update resource",
+)
+async def update_resource(
+    resource_id: UUID,
+    resource_data: ResourceUpdate,
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Update an existing resource (partial update).
+
+    Only provided fields will be updated.
+    """
+    service = ResourceService(db)
+    resource = await service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    try:
+        updated_resource = await service.update_resource(resource, resource_data)
+        return updated_resource
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Delete resource
+@router.delete(
+    "/{resource_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete resource",
+)
+async def delete_resource(
+    resource_id: UUID,
+    db: DatabaseDep,
+    current_user: UserDep,
+    hard: bool = Query(False, description="Perform hard delete instead of soft delete"),
+):
+    """
+    Delete a resource.
+
+    - **hard=false**: Soft delete (default) - sets deleted_at timestamp
+    - **hard=true**: Hard delete - permanently removes from database
+    """
+    service = ResourceService(db)
+    resource = await service.get_resource(resource_id)
+
+    if not resource:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Resource {resource_id} not found"
+        )
+
+    if resource.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+
+    await service.delete_resource(resource, hard=hard)
+    # 204 No Content - no response body
+
+
+# Bulk operations example
+@router.post(
+    "/bulk",
+    response_model=List[ResourceResponse],
+    status_code=status.HTTP_201_CREATED,
+    summary="Bulk create resources",
+)
+async def bulk_create_resources(
+    resources_data: List[ResourceCreate],
+    db: DatabaseDep,
+    current_user: UserDep,
+):
+    """
+    Create multiple resources in one request.
+
+    Useful for batch imports.
+    """
+    if len(resources_data) > 100:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Maximum 100 resources per bulk operation"
+        )
+
+    service = ResourceService(db)
+    try:
+        return await service.bulk_create_resources(
+            user_id=current_user.id,
+            resources_data=resources_data,
+        )
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+# Repository and service templates (separate files in app/repositories and app/services)
+"""
+from datetime import datetime, timezone
+from typing import Sequence
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import Resource
+from app.schemas import ResourceCreate, ResourceUpdate
+
+
+class ResourceRepository:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+
+    async def list_for_user(
+        self,
+        user_id: UUID,
+        skip: int = 0,
+        limit: int = 100,
+        search: str | None = None,
+        status: str | None = None,
+    ) -> Sequence[Resource]:
+        statement = select(Resource).where(
+            Resource.user_id == user_id,
+            Resource.deleted_at.is_(None),
+        )
+        if search:
+            statement = statement.where(Resource.name.ilike(f"%{search}%"))
+        if status:
+            statement = statement.where(Resource.status == status)
+        result = await self.db.execute(statement.offset(skip).limit(limit))
+        return result.scalars().all()
+
+    async def get(self, resource_id: UUID) -> Resource | None:
+        statement = select(Resource).where(
+            Resource.id == resource_id,
+            Resource.deleted_at.is_(None),
+        )
+        result = await self.db.execute(statement)
+        return result.scalar_one_or_none()
+
+    def add(self, resource: Resource) -> None:
+        self.db.add(resource)
+
+    async def delete(self, resource: Resource) -> None:
+        await self.db.delete(resource)
+
+
+class ResourceService:
+    def __init__(self, db: AsyncSession):
+        self.db = db
+        self.repository = ResourceRepository(db)
+
+    async def list_resources(
+        self,
+        user_id: UUID,
+        skip: int = 0,
+        limit: int = 100,
+        search: str | None = None,
+        status: str | None = None,
+    ) -> Sequence[Resource]:
+        return await self.repository.list_for_user(
+            user_id=user_id,
+            skip=skip,
+            limit=limit,
+            search=search,
+            status=status,
+        )
+
+    async def get_resource(self, resource_id: UUID) -> Resource | None:
+        return await self.repository.get(resource_id)
+
+    async def create_resource(self, user_id: UUID, data: ResourceCreate) -> Resource:
+        resource = Resource(**data.model_dump(), user_id=user_id)
+        self.repository.add(resource)
+        try:
+            await self.db.commit()
+        except Exception:
+            await self.db.rollback()
+            raise
+        await self.db.refresh(resource)
+        return resource
+
+    async def update_resource(self, resource: Resource, data: ResourceUpdate) -> Resource:
+        for field, value in data.model_dump(exclude_unset=True).items():
+            setattr(resource, field, value)
+
+        await self.db.commit()
+        await self.db.refresh(resource)
+        return resource
+
+    async def delete_resource(self, resource: Resource, hard: bool = False) -> None:
+        if hard:
+            await self.repository.delete(resource)
+        else:
+            resource.deleted_at = datetime.now(timezone.utc)
+
+        await self.db.commit()
+
+    async def bulk_create_resources(
+        self,
+        user_id: UUID,
+        resources_data: list[ResourceCreate],
+    ) -> list[Resource]:
+        resources = [
+            Resource(**data.model_dump(), user_id=user_id)
+            for data in resources_data
+        ]
+        for resource in resources:
+            self.repository.add(resource)
+
+        try:
+            await self.db.commit()
+        except Exception:
+            await self.db.rollback()
+            raise
+
+        for resource in resources:
+            await self.db.refresh(resource)
+        return resources
+"""

package/skills/oma-backend/variants/python/snippets.md

@@ -0,0 +1,199 @@
+# Backend Agent - Code Snippets
+
+Copy-paste ready patterns. Use these as starting points, adapt to the specific task.
+
+---
+
+## FastAPI Route with Auth
+
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import get_current_user, get_db
+from app.models.user import User
+from app.schemas.resource import ResourceCreate, ResourceResponse
+
+router = APIRouter(prefix="/api/resources", tags=["resources"])
+
+@router.post("/", response_model=ResourceResponse, status_code=status.HTTP_201_CREATED)
+async def create_resource(
+    data: ResourceCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    resource = Resource(**data.model_dump(), user_id=current_user.id)
+    db.add(resource)
+    await db.commit()
+    await db.refresh(resource)
+    return resource
+```
+
+---
+
+## Pydantic Schema Pair
+
+```python
+from datetime import datetime
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+class ResourceCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=200)
+    description: str | None = None
+
+class ResourceResponse(BaseModel):
+    id: UUID
+    title: str
+    description: str | None
+    user_id: UUID
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+```
+
+---
+
+## SQLAlchemy Model
+
+```python
+import uuid
+from datetime import datetime
+from sqlalchemy import ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+class Resource(Base):
+    __tablename__ = "resources"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    title: Mapped[str] = mapped_column(String(200), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False, index=True)
+    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
+
+    user: Mapped["User"] = relationship(back_populates="resources")
+```
+
+---
+
+## JWT Auth Dependency
+
+```python
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+
+from app.core.config import settings
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+        user_id = payload.get("sub")
+        if user_id is None:
+            raise HTTPException(status_code=401, detail="Invalid token")
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+    user = await db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user
+```
+
+---
+
+## Password Hashing
+
+```python
+from passlib.context import CryptContext
+
+# argon2 (Argon2id) is the default; bcrypt stays verifiable so legacy hashes
+# re-hash to argon2 transparently on next successful login
+pwd_context = CryptContext(schemes=["argon2", "bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+```
+
+---
+
+## Paginated Query
+
+```python
+from sqlalchemy import select, func
+
+async def paginate(
+    db: AsyncSession,
+    query,
+    page: int = 1,
+    size: int = 20,
+):
+    total = await db.scalar(select(func.count()).select_from(query.subquery()))
+    items = await db.scalars(query.offset((page - 1) * size).limit(size))
+    return {
+        "items": list(items),
+        "total": total,
+        "page": page,
+        "size": size,
+    }
+```
+
+---
+
+## Alembic Migration
+
+```python
+"""add resources table
+
+Revision ID: xxxx
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+def upgrade() -> None:
+    op.create_table(
+        "resources",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True),
+        sa.Column("title", sa.String(200), nullable=False),
+        sa.Column("description", sa.Text, nullable=True),
+        sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
+    )
+    op.create_index("ix_resources_user_id", "resources", ["user_id"])
+
+def downgrade() -> None:
+    op.drop_table("resources")
+```
+
+---
+
+## Test with httpx
+
+```python
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_create_resource(client: AsyncClient, auth_headers: dict):
+    response = await client.post(
+        "/api/resources/",
+        json={"title": "Test", "description": "Test desc"},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["title"] == "Test"
+    assert "id" in data
+```

package/skills/oma-backend/variants/python/stack.yaml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=../stack.schema.json
+language: python
+framework: fastapi
+orm: sqlalchemy
+source: variant
+
+verify:
+  detect: pyproject.toml
+  syntax:
+    cmd: "python -m compileall -q ."
+  tests:
+    cmd: "uv run pytest"
+    skip_if_missing: uv
+  raw_sql:
+    patterns:
+      - "f[\"'].*(SELECT|INSERT|UPDATE|DELETE)"
+    include_glob: "*.py"
+    exclude_dirs: [test, tests, node_modules, .venv]

package/skills/oma-backend/variants/python/tech-stack.md

@@ -0,0 +1,45 @@
+# Backend Agent - Tech Stack Reference
+
+## Python (Preferred)
+- **Framework**: FastAPI 0.110+
+- **ORM**: SQLAlchemy 2.0 (async)
+- **Validation**: Pydantic v2
+- **Database**: PostgreSQL 16+, Redis 7+
+- **Auth**: python-jose (JWT), passlib[argon2] (Argon2id; bcrypt verify for legacy hashes)
+- **Testing**: pytest, httpx (async test client)
+- **Migrations**: Alembic
+
+## Node.js (Alternative)
+- **Framework**: Express.js, NestJS, Hono
+- **ORM**: Prisma, Drizzle
+- **Validation**: Zod
+- **Auth**: jsonwebtoken, argon2 (node-argon2)
+- **Testing**: Jest, Supertest
+
+## Architecture
+
+```
+backend/
+  domain/           # Business logic (pure Python, no framework deps)
+  application/      # Use cases, services
+  infrastructure/   # Database, cache, external APIs
+  presentation/     # API endpoints, middleware
+```
+
+## Security Requirements
+- Password hashing: Argon2id (bcrypt cost 10-12 acceptable for legacy compatibility)
+- JWT: 15min access tokens, 7 day refresh tokens
+- Rate limiting on auth endpoints
+- Input validation with Pydantic/Zod
+- Parameterized queries (never string interpolation)
+
+## ORM Guidance
+- Cross-ORM operational rules and official vendor references: `resources/orm-reference.md`
+- Primary references covered there: Prisma, SQLAlchemy, TypeORM, Sequelize, Hibernate
+
+## Optional Serena examples
+
+These examples apply only when Serena is the configured provider and its tools are available. Otherwise use the project-selected provider or native search under the shared code-intelligence contract.
+- `find_symbol("create_todo")`: Locate existing function
+- `get_symbols_overview("app/api")`: List all endpoints
+- `find_referencing_symbols("User")`: Find all usages of a model