autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/fastapi.md

@@ -0,0 +1,329 @@
+# FastAPI Skill
+
+## Project Structure
+\`\`\`
+app/
+├── main.py               # FastAPI app
+├── config.py             # Settings
+├── database.py           # DB connection
+├── dependencies.py       # Shared dependencies
+├── models/               # SQLAlchemy models
+│   └── user.py
+├── schemas/              # Pydantic schemas
+│   └── user.py
+├── routers/              # API routes
+│   ├── __init__.py
+│   └── users.py
+├── services/             # Business logic
+│   └── user.py
+└── tests/
+    └── test_users.py
+\`\`\`
+
+## App Setup
+\`\`\`python
+# main.py
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+
+from app.database import engine, Base
+from app.routers import users, auth
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown
+    await engine.dispose()
+
+app = FastAPI(
+    title="My API",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Routes
+app.include_router(auth.router, prefix="/auth", tags=["auth"])
+app.include_router(users.router, prefix="/users", tags=["users"])
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+\`\`\`
+
+## Schemas (Pydantic)
+\`\`\`python
+# schemas/user.py
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8)
+
+class UserUpdate(BaseModel):
+    name: str | None = None
+    bio: str | None = None
+
+class UserResponse(UserBase):
+    id: int
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+class UserWithPosts(UserResponse):
+    posts: list["PostResponse"] = []
+\`\`\`
+
+## Routes
+\`\`\`python
+# routers/users.py
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.schemas.user import UserCreate, UserResponse, UserUpdate
+from app.services.user import UserService
+from app.dependencies import get_current_user
+
+router = APIRouter()
+
+@router.get("/", response_model=list[UserResponse])
+async def list_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(10, ge=1, le=100),
+    db: AsyncSession = Depends(get_db),
+):
+    service = UserService(db)
+    return await service.get_users(skip=skip, limit=limit)
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(current_user: User = Depends(get_current_user)):
+    return current_user
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    service = UserService(db)
+    user = await service.get_user(user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(
+    user_data: UserCreate,
+    db: AsyncSession = Depends(get_db),
+):
+    service = UserService(db)
+    return await service.create_user(user_data)
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    user_data: UserUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    if current_user.id != user_id:
+        raise HTTPException(status_code=403, detail="Not authorized")
+    service = UserService(db)
+    return await service.update_user(user_id, user_data)
+\`\`\`
+
+## Dependency Injection
+\`\`\`python
+# 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.database import get_db
+from app.config import settings
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> 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.jwt_secret, algorithms=["HS256"])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    user = await db.get(User, int(user_id))
+    if user is None:
+        raise credentials_exception
+    return user
+
+# Optional auth
+async def get_current_user_optional(
+    token: str | None = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User | None:
+    if not token:
+        return None
+    try:
+        return await get_current_user(token, db)
+    except HTTPException:
+        return None
+
+# Role-based access
+def require_role(role: str):
+    async def role_checker(user: User = Depends(get_current_user)):
+        if user.role != role:
+            raise HTTPException(status_code=403, detail="Insufficient permissions")
+        return user
+    return role_checker
+
+# Usage
+@router.delete("/{user_id}")
+async def delete_user(
+    user_id: int,
+    admin: User = Depends(require_role("admin")),
+):
+    ...
+\`\`\`
+
+## Authentication (OAuth2 + JWT)
+\`\`\`python
+# routers/auth.py
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.security import OAuth2PasswordRequestForm
+from datetime import datetime, timedelta
+
+router = APIRouter()
+
+@router.post("/token")
+async def login(
+    form_data: OAuth2PasswordRequestForm = Depends(),
+    db: AsyncSession = Depends(get_db),
+):
+    user = await authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=401,
+            detail="Incorrect email or password",
+        )
+
+    access_token = create_access_token(
+        data={"sub": str(user.id)},
+        expires_delta=timedelta(hours=1),
+    )
+
+    return {
+        "access_token": access_token,
+        "token_type": "bearer",
+    }
+
+def create_access_token(data: dict, expires_delta: timedelta) -> str:
+    expire = datetime.utcnow() + expires_delta
+    to_encode = data.copy()
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, settings.jwt_secret, algorithm="HS256")
+\`\`\`
+
+## Error Handling
+\`\`\`python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+class AppException(Exception):
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail = detail
+
+@app.exception_handler(AppException)
+async def app_exception_handler(request: Request, exc: AppException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.detail},
+    )
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    return JSONResponse(
+        status_code=500,
+        content={"error": "Internal server error"},
+    )
+
+# Usage
+raise AppException(status_code=400, detail="Invalid input")
+\`\`\`
+
+## Background Tasks
+\`\`\`python
+from fastapi import BackgroundTasks
+
+async def send_email(email: str, message: str):
+    # Simulated email sending
+    await asyncio.sleep(5)
+    print(f"Email sent to {email}")
+
+@router.post("/users/")
+async def create_user(
+    user: UserCreate,
+    background_tasks: BackgroundTasks,
+    db: AsyncSession = Depends(get_db),
+):
+    new_user = await service.create_user(user)
+    background_tasks.add_task(send_email, new_user.email, "Welcome!")
+    return new_user
+\`\`\`
+
+## Middleware
+\`\`\`python
+from fastapi import Request
+import time
+
+@app.middleware("http")
+async def add_timing_header(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    duration = time.time() - start_time
+    response.headers["X-Response-Time"] = f"{duration:.3f}s"
+    return response
+\`\`\`
+
+## ❌ DON'T
+- Use sync operations in async routes
+- Skip response_model (loses validation)
+- Put DB logic in route handlers
+- Forget to handle exceptions
+
+## ✅ DO
+- Always define response_model
+- Use Depends() for shared logic
+- Use async for I/O operations
+- Use services for business logic
+- Use OAuth2 + JWT for auth
+- Use background tasks for slow operations
+- Handle errors with exception handlers

package/.claude/skills/fastify.md

@@ -0,0 +1,299 @@
+# Fastify Skill
+
+## Project Structure
+\`\`\`
+src/
+├── index.ts              # Entry point
+├── app.ts                # Fastify app factory
+├── plugins/
+│   ├── auth.ts           # Auth plugin
+│   └── database.ts       # DB connection
+├── routes/
+│   ├── index.ts          # Route registration
+│   └── users/
+│       ├── index.ts      # User routes
+│       └── schemas.ts    # Route schemas
+└── types/
+    └── index.d.ts        # Type extensions
+\`\`\`
+
+## App Setup with TypeBox
+\`\`\`typescript
+import Fastify from 'fastify';
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+import cors from '@fastify/cors';
+import helmet from '@fastify/helmet';
+
+export async function buildApp() {
+  const app = Fastify({
+    logger: {
+      level: process.env.LOG_LEVEL || 'info',
+    },
+  }).withTypeProvider<TypeBoxTypeProvider>();
+
+  // Plugins
+  await app.register(cors, { origin: true });
+  await app.register(helmet);
+
+  // Custom plugins
+  await app.register(import('./plugins/database'));
+  await app.register(import('./plugins/auth'));
+
+  // Routes
+  await app.register(import('./routes'), { prefix: '/api' });
+
+  return app;
+}
+\`\`\`
+
+## Routes with Type Safety
+\`\`\`typescript
+// routes/users/index.ts
+import { FastifyPluginAsync } from 'fastify';
+import { Type, Static } from '@sinclair/typebox';
+
+// Define schemas with TypeBox
+const UserSchema = Type.Object({
+  id: Type.String(),
+  email: Type.String({ format: 'email' }),
+  name: Type.String(),
+});
+
+const CreateUserSchema = Type.Object({
+  email: Type.String({ format: 'email' }),
+  name: Type.String({ minLength: 1 }),
+  password: Type.String({ minLength: 8 }),
+});
+
+const ParamsSchema = Type.Object({
+  id: Type.String(),
+});
+
+type User = Static<typeof UserSchema>;
+type CreateUser = Static<typeof CreateUserSchema>;
+
+const usersRoutes: FastifyPluginAsync = async (app) => {
+  // GET /users
+  app.get('/', {
+    schema: {
+      response: {
+        200: Type.Array(UserSchema),
+      },
+    },
+  }, async (request, reply) => {
+    const users = await app.db.user.findMany();
+    return users;
+  });
+
+  // GET /users/:id
+  app.get<{ Params: Static<typeof ParamsSchema> }>('/:id', {
+    schema: {
+      params: ParamsSchema,
+      response: {
+        200: UserSchema,
+        404: Type.Object({ error: Type.String() }),
+      },
+    },
+  }, async (request, reply) => {
+    const user = await app.db.user.findUnique({
+      where: { id: request.params.id },
+    });
+
+    if (!user) {
+      return reply.status(404).send({ error: 'User not found' });
+    }
+
+    return user;
+  });
+
+  // POST /users
+  app.post<{ Body: CreateUser }>('/', {
+    schema: {
+      body: CreateUserSchema,
+      response: {
+        201: UserSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const user = await app.db.user.create({
+      data: request.body,
+    });
+
+    return reply.status(201).send(user);
+  });
+};
+
+export default usersRoutes;
+\`\`\`
+
+## Plugins
+\`\`\`typescript
+// plugins/database.ts
+import { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import { PrismaClient } from '@prisma/client';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    db: PrismaClient;
+  }
+}
+
+const databasePlugin: FastifyPluginAsync = async (app) => {
+  const prisma = new PrismaClient();
+
+  await prisma.$connect();
+
+  app.decorate('db', prisma);
+
+  app.addHook('onClose', async () => {
+    await prisma.$disconnect();
+  });
+};
+
+// Use fp() to make decorators available to sibling plugins
+export default fp(databasePlugin, { name: 'database' });
+\`\`\`
+
+## Authentication Plugin
+\`\`\`typescript
+// plugins/auth.ts
+import { FastifyPluginAsync, FastifyRequest } from 'fastify';
+import fp from 'fastify-plugin';
+import jwt from '@fastify/jwt';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    authenticate: (request: FastifyRequest) => Promise<void>;
+  }
+}
+
+declare module '@fastify/jwt' {
+  interface FastifyJWT {
+    payload: { id: string; email: string };
+    user: { id: string; email: string };
+  }
+}
+
+const authPlugin: FastifyPluginAsync = async (app) => {
+  await app.register(jwt, {
+    secret: process.env.JWT_SECRET!,
+  });
+
+  app.decorate('authenticate', async (request: FastifyRequest) => {
+    await request.jwtVerify();
+  });
+};
+
+export default fp(authPlugin, { name: 'auth' });
+
+// Usage in routes
+app.get('/me', {
+  preHandler: [app.authenticate],
+}, async (request) => {
+  return request.user;
+});
+\`\`\`
+
+## Hooks
+\`\`\`typescript
+// Lifecycle hooks
+app.addHook('onRequest', async (request, reply) => {
+  request.startTime = Date.now();
+});
+
+app.addHook('onResponse', async (request, reply) => {
+  const duration = Date.now() - request.startTime;
+  request.log.info({ duration }, 'Request completed');
+});
+
+// Route-level hooks
+app.get('/protected', {
+  preHandler: async (request, reply) => {
+    // Auth check before handler
+    if (!request.headers.authorization) {
+      return reply.status(401).send({ error: 'Unauthorized' });
+    }
+  },
+}, async (request) => {
+  return { data: 'secret' };
+});
+
+// Validation hook (runs after schema validation)
+app.addHook('preValidation', async (request) => {
+  // Modify request before validation
+});
+\`\`\`
+
+## Error Handling
+\`\`\`typescript
+// Custom error handler
+app.setErrorHandler((error, request, reply) => {
+  request.log.error(error);
+
+  // Validation errors
+  if (error.validation) {
+    return reply.status(400).send({
+      error: 'Validation failed',
+      details: error.validation,
+    });
+  }
+
+  // Custom errors
+  if (error.statusCode) {
+    return reply.status(error.statusCode).send({
+      error: error.message,
+    });
+  }
+
+  // Generic errors
+  reply.status(500).send({
+    error: 'Internal server error',
+  });
+});
+
+// 404 handler
+app.setNotFoundHandler((request, reply) => {
+  reply.status(404).send({
+    error: 'Not found',
+    path: request.url,
+  });
+});
+\`\`\`
+
+## Decorators
+\`\`\`typescript
+// Add to FastifyInstance
+app.decorate('config', {
+  apiVersion: '1.0.0',
+  environment: process.env.NODE_ENV,
+});
+
+// Add to FastifyRequest
+app.decorateRequest('startTime', 0);
+
+// Add to FastifyReply
+app.decorateReply('success', function (data: any) {
+  return this.send({ success: true, data });
+});
+
+// Usage
+app.get('/health', async (request, reply) => {
+  return reply.success({ status: 'ok', version: app.config.apiVersion });
+});
+\`\`\`
+
+## ❌ DON'T
+- Forget to use fp() for plugins with decorators
+- Skip schema validation (it's a key Fastify feature)
+- Block the event loop in handlers
+- Ignore the logger (use request.log)
+
+## ✅ DO
+- Use TypeBox for type-safe schemas
+- Use plugins for modularity
+- Enable logging (built-in pino)
+- Use hooks for cross-cutting concerns
+- Use fp() for plugins that add decorators
+- Handle errors with setErrorHandler
+- Use preHandler for auth/validation