autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/prisma.md

@@ -0,0 +1,293 @@
+# Prisma Skill
+
+## Schema Design
+\`\`\`prisma
+// schema.prisma
+generator client {
+  provider = "prisma-client-js"
+  previewFeatures = ["fullTextSearch", "filteredRelationCount"]
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id            String    @id @default(cuid())
+  email         String    @unique
+  name          String?
+  role          Role      @default(USER)
+  posts         Post[]
+  profile       Profile?
+  accounts      Account[]
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+  deletedAt     DateTime? // Soft delete
+
+  @@index([email])
+  @@index([createdAt])
+  @@map("users") // Table name
+}
+
+model Post {
+  id          String     @id @default(cuid())
+  title       String
+  content     String?
+  published   Boolean    @default(false)
+  author      User       @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  authorId    String
+  categories  Category[]
+  createdAt   DateTime   @default(now())
+
+  @@index([authorId])
+  @@index([published, createdAt])
+}
+
+model Category {
+  id    String @id @default(cuid())
+  name  String @unique
+  posts Post[]
+}
+
+// One-to-one
+model Profile {
+  id     String @id @default(cuid())
+  bio    String?
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  userId String @unique
+}
+
+enum Role {
+  USER
+  ADMIN
+  MODERATOR
+}
+\`\`\`
+
+## Query Patterns
+\`\`\`typescript
+// CRUD Operations
+const user = await prisma.user.create({
+  data: {
+    email: 'user@example.com',
+    name: 'John',
+    profile: { create: { bio: 'Developer' } }, // Nested create
+  },
+  include: { profile: true },
+});
+
+// Find operations
+const user = await prisma.user.findUnique({
+  where: { id },
+  select: { id: true, email: true, name: true }, // Only select needed fields
+});
+
+const user = await prisma.user.findUniqueOrThrow({ where: { id } }); // Throws if not found
+
+// Filter with multiple conditions
+const users = await prisma.user.findMany({
+  where: {
+    AND: [
+      { email: { contains: '@company.com' } },
+      { role: 'USER' },
+      { deletedAt: null },
+    ],
+    OR: [
+      { name: { startsWith: 'A' } },
+      { name: { startsWith: 'B' } },
+    ],
+    NOT: { role: 'ADMIN' },
+  },
+  orderBy: { createdAt: 'desc' },
+  skip: 0,
+  take: 20,
+});
+
+// Include relations with filtering
+const usersWithPosts = await prisma.user.findMany({
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5,
+    },
+    _count: { select: { posts: true } }, // Count relations
+  },
+});
+
+// Update operations
+const updated = await prisma.user.update({
+  where: { id },
+  data: {
+    name: 'New Name',
+    posts: {
+      updateMany: { where: { published: false }, data: { published: true } },
+    },
+  },
+});
+
+// Upsert
+const user = await prisma.user.upsert({
+  where: { email: 'user@example.com' },
+  update: { name: 'Updated Name' },
+  create: { email: 'user@example.com', name: 'New User' },
+});
+
+// Delete with cascade (defined in schema)
+await prisma.user.delete({ where: { id } });
+
+// Soft delete pattern
+await prisma.user.update({
+  where: { id },
+  data: { deletedAt: new Date() },
+});
+\`\`\`
+
+## Transactions
+\`\`\`typescript
+// Sequential transactions (array)
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: userData }),
+  prisma.post.create({ data: postData }),
+]);
+
+// Interactive transactions (function)
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUnique({ where: { id } });
+  if (!user) throw new Error('User not found');
+
+  const updatedUser = await tx.user.update({
+    where: { id },
+    data: { balance: { decrement: 100 } },
+  });
+
+  await tx.transaction.create({
+    data: { userId: id, amount: -100, type: 'WITHDRAWAL' },
+  });
+
+  return updatedUser;
+}, {
+  maxWait: 5000, // Max wait to start transaction
+  timeout: 10000, // Max transaction duration
+  isolationLevel: 'Serializable', // Optional isolation level
+});
+\`\`\`
+
+## Middleware
+\`\`\`typescript
+// Logging middleware
+prisma.$use(async (params, next) => {
+  const before = Date.now();
+  const result = await next(params);
+  const after = Date.now();
+
+  console.log(\`Query \${params.model}.\${params.action} took \${after - before}ms\`);
+  return result;
+});
+
+// Soft delete middleware
+prisma.$use(async (params, next) => {
+  if (params.model === 'User') {
+    // Intercept delete and convert to soft delete
+    if (params.action === 'delete') {
+      params.action = 'update';
+      params.args.data = { deletedAt: new Date() };
+    }
+
+    // Filter out soft-deleted in find queries
+    if (params.action === 'findMany' || params.action === 'findFirst') {
+      params.args.where = { ...params.args.where, deletedAt: null };
+    }
+  }
+  return next(params);
+});
+\`\`\`
+
+## Raw Queries
+\`\`\`typescript
+// Raw SQL queries
+const users = await prisma.$queryRaw\`
+  SELECT * FROM users
+  WHERE email LIKE \${pattern}
+  LIMIT \${limit}
+\`;
+
+// Raw SQL with typed result
+const users = await prisma.$queryRaw<User[]>\`
+  SELECT id, email, name FROM users WHERE role = \${role}
+\`;
+
+// Execute raw (INSERT, UPDATE, DELETE)
+const count = await prisma.$executeRaw\`
+  UPDATE users SET updated_at = NOW() WHERE id = \${id}
+\`;
+\`\`\`
+
+## Prisma Client Extensions
+\`\`\`typescript
+// Extend Prisma Client (v4.16+)
+const prisma = new PrismaClient().$extends({
+  model: {
+    user: {
+      async findByEmail(email: string) {
+        return prisma.user.findUnique({ where: { email } });
+      },
+      async softDelete(id: string) {
+        return prisma.user.update({
+          where: { id },
+          data: { deletedAt: new Date() },
+        });
+      },
+    },
+  },
+  result: {
+    user: {
+      fullName: {
+        needs: { firstName: true, lastName: true },
+        compute(user) {
+          return \`\${user.firstName} \${user.lastName}\`;
+        },
+      },
+    },
+  },
+});
+
+// Usage
+const user = await prisma.user.findByEmail('test@example.com');
+console.log(user?.fullName);
+\`\`\`
+
+## Migrations
+\`\`\`bash
+# Create migration from schema changes
+npx prisma migrate dev --name add_user_role
+
+# Apply migrations in production
+npx prisma migrate deploy
+
+# Reset database (dangerous!)
+npx prisma migrate reset
+
+# Generate Prisma Client
+npx prisma generate
+
+# View database in browser
+npx prisma studio
+\`\`\`
+
+## ❌ DON'T
+- Use \`findMany()\` without pagination on large tables
+- Fetch relations you don't need (use select/include wisely)
+- Ignore the N+1 problem with nested queries
+- Use raw queries when Prisma Client suffices
+- Skip migrations in production
+
+## ✅ DO
+- Use \`select\` to fetch only needed fields
+- Use \`take\` and \`skip\` for pagination (or cursor-based)
+- Use transactions for related operations
+- Use middleware for cross-cutting concerns
+- Use extensions for reusable model methods
+- Use \`findUniqueOrThrow\` when record must exist
+- Run migrations in CI/CD pipeline

package/.claude/skills/pydantic.md

@@ -0,0 +1,304 @@
+# Pydantic Skill
+
+## Basic Model with Validators
+\`\`\`python
+from pydantic import BaseModel, EmailStr, Field, field_validator, model_validator
+from typing import Annotated
+from datetime import datetime
+
+class UserBase(BaseModel):
+    """Base model with shared fields and configuration."""
+    email: EmailStr
+    name: Annotated[str, Field(min_length=1, max_length=100)]
+
+    model_config = {
+        "from_attributes": True,  # ORM mode
+        "str_strip_whitespace": True,
+        "validate_assignment": True,
+    }
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8)
+    password_confirm: str
+
+    @field_validator('name')
+    @classmethod
+    def name_must_not_be_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError('Name cannot be empty')
+        return v.title()
+
+    @model_validator(mode='after')
+    def passwords_match(self) -> 'UserCreate':
+        if self.password != self.password_confirm:
+            raise ValueError('Passwords do not match')
+        return self
+
+class UserResponse(UserBase):
+    id: int
+    created_at: datetime
+\`\`\`
+
+## Computed Fields
+\`\`\`python
+from pydantic import BaseModel, computed_field
+from datetime import datetime, date
+
+class User(BaseModel):
+    first_name: str
+    last_name: str
+    birth_date: date
+
+    @computed_field
+    @property
+    def full_name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+
+    @computed_field
+    @property
+    def age(self) -> int:
+        today = date.today()
+        return today.year - self.birth_date.year - (
+            (today.month, today.day) < (self.birth_date.month, self.birth_date.day)
+        )
+
+class Order(BaseModel):
+    items: list[dict]
+    tax_rate: float = 0.08
+
+    @computed_field
+    @property
+    def subtotal(self) -> float:
+        return sum(item['price'] * item['quantity'] for item in self.items)
+
+    @computed_field
+    @property
+    def total(self) -> float:
+        return self.subtotal * (1 + self.tax_rate)
+\`\`\`
+
+## Custom Types and Validators
+\`\`\`python
+from pydantic import BaseModel, BeforeValidator, AfterValidator, PlainValidator
+from typing import Annotated
+import re
+
+# Custom type with validation
+def validate_phone(v: str) -> str:
+    digits = re.sub(r'\\D', '', v)
+    if len(digits) != 10:
+        raise ValueError('Phone must be 10 digits')
+    return f"({digits[:3]}) {digits[3:6]}-{digits[6:]}"
+
+PhoneNumber = Annotated[str, AfterValidator(validate_phone)]
+
+# Coercing validator
+def to_lowercase(v: str) -> str:
+    return v.lower().strip()
+
+LowercaseStr = Annotated[str, BeforeValidator(to_lowercase)]
+
+# Multiple validators
+def validate_username(v: str) -> str:
+    if not re.match(r'^[a-z0-9_]+$', v):
+        raise ValueError('Username must be alphanumeric with underscores')
+    if len(v) < 3:
+        raise ValueError('Username must be at least 3 characters')
+    return v
+
+Username = Annotated[str, BeforeValidator(to_lowercase), AfterValidator(validate_username)]
+
+class Contact(BaseModel):
+    username: Username
+    email: LowercaseStr
+    phone: PhoneNumber
+\`\`\`
+
+## Discriminated Unions
+\`\`\`python
+from pydantic import BaseModel, Field
+from typing import Literal, Union
+from datetime import datetime
+
+class EmailNotification(BaseModel):
+    type: Literal["email"] = "email"
+    recipient: str
+    subject: str
+    body: str
+
+class SMSNotification(BaseModel):
+    type: Literal["sms"] = "sms"
+    phone_number: str
+    message: str
+
+class PushNotification(BaseModel):
+    type: Literal["push"] = "push"
+    device_token: str
+    title: str
+    body: str
+
+# Discriminated union - Pydantic uses 'type' field to determine which model
+Notification = Union[EmailNotification, SMSNotification, PushNotification]
+
+class NotificationRequest(BaseModel):
+    notification: Annotated[Notification, Field(discriminator='type')]
+    scheduled_at: datetime | None = None
+
+# Usage
+req = NotificationRequest(
+    notification={"type": "email", "recipient": "user@example.com", "subject": "Hi", "body": "Hello!"}
+)
+\`\`\`
+
+## Settings Management
+\`\`\`python
+from pydantic import Field, SecretStr, PostgresDsn
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="APP_",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # App settings
+    app_name: str = "MyApp"
+    debug: bool = False
+    environment: Literal["development", "staging", "production"] = "development"
+
+    # Database
+    database_url: PostgresDsn
+    db_pool_size: int = Field(default=5, ge=1, le=100)
+
+    # Secrets
+    secret_key: SecretStr
+    api_key: SecretStr
+
+    # External services
+    redis_url: str = "redis://localhost:6379"
+
+    @computed_field
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+
+@lru_cache
+def get_settings() -> Settings:
+    """Cached settings instance."""
+    return Settings()
+
+# Usage in FastAPI
+# settings = get_settings()
+# app = FastAPI(title=settings.app_name, debug=settings.debug)
+\`\`\`
+
+## Serialization Options
+\`\`\`python
+from pydantic import BaseModel, Field, ConfigDict
+from datetime import datetime
+from enum import Enum
+
+class Status(Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+
+class User(BaseModel):
+    model_config = ConfigDict(
+        use_enum_values=True,
+        populate_by_name=True,  # Allow alias or field name
+    )
+
+    id: int
+    email: str
+    internal_code: str = Field(exclude=True)  # Never serialized
+    display_name: str = Field(alias="displayName")
+    status: Status
+    created_at: datetime
+
+user = User(
+    id=1,
+    email="user@example.com",
+    internal_code="SECRET123",
+    displayName="John Doe",
+    status=Status.ACTIVE,
+    created_at=datetime.now()
+)
+
+# Serialization methods
+user.model_dump()                          # Dict with all fields (except excluded)
+user.model_dump(by_alias=True)             # Use aliases in keys
+user.model_dump(exclude={"email"})         # Exclude specific fields
+user.model_dump(include={"id", "email"})   # Only include specific fields
+user.model_dump(exclude_none=True)         # Exclude None values
+user.model_dump(mode='json')               # JSON-compatible types
+
+user.model_dump_json()                     # JSON string
+user.model_dump_json(indent=2)             # Formatted JSON
+
+# Round-trip
+User.model_validate(user.model_dump())              # From dict
+User.model_validate_json(user.model_dump_json())    # From JSON string
+\`\`\`
+
+## Generic Models
+\`\`\`python
+from pydantic import BaseModel
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    per_page: int
+
+    @computed_field
+    @property
+    def total_pages(self) -> int:
+        return (self.total + self.per_page - 1) // self.per_page
+
+    @computed_field
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.total_pages
+
+class User(BaseModel):
+    id: int
+    name: str
+
+class Product(BaseModel):
+    id: int
+    title: str
+    price: float
+
+# Usage
+users_response: PaginatedResponse[User] = PaginatedResponse(
+    items=[User(id=1, name="John")],
+    total=50,
+    page=1,
+    per_page=10
+)
+\`\`\`
+
+## ✅ DO
+- Use \`model_config\` instead of nested Config class (Pydantic v2)
+- Use \`@field_validator\` with \`@classmethod\` decorator
+- Use \`computed_field\` for derived properties
+- Use \`Annotated\` types for reusable validation
+- Use \`pydantic-settings\` for environment configuration
+- Use discriminated unions for polymorphic data
+- Use \`SecretStr\` for sensitive data (won't be logged)
+
+## ❌ DON'T
+- Don't use \`@validator\` (Pydantic v1 syntax, deprecated)
+- Don't use \`class Config:\` (use \`model_config\` dict)
+- Don't store secrets as plain strings
+- Don't use \`.dict()\` (use \`.model_dump()\`)
+- Don't use \`.json()\` (use \`.model_dump_json()\`)