codecruise 0.1.0

package/config/skills/backend/SKILL.md

@@ -0,0 +1,734 @@
+---
+name: backend
+description: API design, database, and security patterns
+version: 1.0.0
+triggers:
+  - api
+  - endpoint
+  - database
+  - SQL
+  - auth
+  - server
+  - REST
+  - tRPC
+---
+
+# Backend Skill
+
+Comprehensive API, database, and security patterns.
+
+## Quick Reference
+
+### API Design
+
+| ID | Rule | Priority |
+|----|------|----------|
+| api-1 | Validate all inputs at boundaries with Zod | CRITICAL |
+| api-2 | Use proper HTTP status codes | CRITICAL |
+| api-3 | Return consistent error format | CRITICAL |
+| api-4 | Never expose internal errors to clients | CRITICAL |
+| api-5 | Use RESTful conventions for endpoints | HIGH |
+| api-6 | Implement rate limiting on public endpoints | HIGH |
+| api-7 | Version APIs when breaking changes needed | HIGH |
+| api-8 | Use pagination for list endpoints | MEDIUM |
+| api-9 | Document endpoints with OpenAPI | MEDIUM |
+| api-10 | Use service layer for business logic | MEDIUM |
+
+### Database (General)
+
+| ID | Rule | Priority |
+|----|------|----------|
+| db-1 | Use parameterized queries, never interpolate | CRITICAL |
+| db-2 | Always use transactions for related writes | CRITICAL |
+| db-3 | Prevent N+1 queries with eager loading | HIGH |
+| db-4 | Index columns used in WHERE and JOIN | HIGH |
+| db-5 | Use connection pooling in production | HIGH |
+| db-6 | Add created_at and updated_at to all tables | MEDIUM |
+| db-7 | Use soft deletes for recoverable data | MEDIUM |
+| db-8 | Validate foreign key constraints | MEDIUM |
+| db-9 | Use decimal/string for money, never float | CRITICAL |
+| db-10 | Implement optimistic locking for concurrent updates | MEDIUM |
+
+### PostgreSQL
+
+| ID | Rule | Priority |
+|----|------|----------|
+| pg-1 | Use JSONB for flexible schema fields | HIGH |
+| pg-2 | Create partial indexes for filtered queries | HIGH |
+| pg-3 | Use EXPLAIN ANALYZE for query optimization | HIGH |
+| pg-4 | Use UUID v7 for sortable primary keys | MEDIUM |
+| pg-5 | Use CTEs for complex queries | MEDIUM |
+| pg-6 | Use pg_trgm for text search | MEDIUM |
+| pg-7 | Use row-level security for multi-tenancy | HIGH |
+| pg-8 | Set statement_timeout to prevent runaway queries | HIGH |
+
+### MongoDB
+
+| ID | Rule | Priority |
+|----|------|----------|
+| mongo-1 | Design schema for query patterns, not normalization | CRITICAL |
+| mongo-2 | Embed frequently accessed related data | HIGH |
+| mongo-3 | Use references for large/unbounded arrays | HIGH |
+| mongo-4 | Create compound indexes matching query patterns | HIGH |
+| mongo-5 | Use aggregation pipeline for complex queries | MEDIUM |
+| mongo-6 | Set maxTimeMS to prevent slow queries | HIGH |
+| mongo-7 | Use change streams for real-time updates | MEDIUM |
+| mongo-8 | Avoid unbounded array growth | CRITICAL |
+
+### Security
+
+| ID | Rule | Priority |
+|----|------|----------|
+| sec-1 | Authenticate before authorize | CRITICAL |
+| sec-2 | Check resource ownership on every request | CRITICAL |
+| sec-3 | Never log passwords or tokens | CRITICAL |
+| sec-4 | Use httpOnly cookies for session tokens | CRITICAL |
+| sec-5 | Hash passwords with bcrypt/argon2 | CRITICAL |
+| sec-6 | Implement CSRF protection for mutations | HIGH |
+| sec-7 | Set secure headers (CSP, X-Frame-Options) | HIGH |
+| sec-8 | Sanitize user input before storing | HIGH |
+| sec-9 | Use secrets manager, not env files in production | HIGH |
+| sec-10 | Audit log sensitive operations | MEDIUM |
+
+---
+
+## Critical Rules
+
+### api-1: Input Validation
+
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8).regex(/[A-Z]/).regex(/[0-9]/),
+  name: z.string().min(2).max(100),
+});
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const data = CreateUserSchema.parse(body); // Throws on invalid
+  // data is now validated and typed
+}
+```
+
+### api-2: HTTP Status Codes
+
+```
+200 OK              - Success (GET, PUT, PATCH)
+201 Created         - Resource created (POST)
+204 No Content      - Success, no body (DELETE)
+400 Bad Request     - Validation error
+401 Unauthorized    - Authentication required
+403 Forbidden       - Insufficient permissions
+404 Not Found       - Resource not found
+409 Conflict        - Duplicate resource
+422 Unprocessable   - Valid syntax, invalid data
+429 Too Many        - Rate limited
+500 Internal Error  - Server error (hide details)
+```
+
+### api-3: Error Response Format
+
+```typescript
+// Consistent error format
+interface ErrorResponse {
+  error: {
+    code: string;          // Machine-readable: 'VALIDATION_ERROR'
+    message: string;       // Human-readable: 'Invalid email format'
+    details?: {            // Field-level errors
+      field: string;
+      message: string;
+    }[];
+  };
+}
+
+// Error handler middleware
+function handleError(error: unknown): NextResponse<ErrorResponse> {
+  if (error instanceof z.ZodError) {
+    return NextResponse.json({
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Invalid input',
+        details: error.errors.map(e => ({
+          field: e.path.join('.'),
+          message: e.message,
+        })),
+      },
+    }, { status: 400 });
+  }
+
+  if (error instanceof AppError) {
+    return NextResponse.json({
+      error: { code: error.code, message: error.message },
+    }, { status: error.statusCode });
+  }
+
+  // Never expose internal errors
+  console.error('Unexpected error:', error);
+  return NextResponse.json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  }, { status: 500 });
+}
+```
+
+### db-1: Parameterized Queries
+
+```typescript
+// GOOD: Prisma handles escaping
+await prisma.user.findMany({
+  where: { email: userInput }
+});
+
+// GOOD: Raw query with parameters
+await prisma.$queryRaw`
+  SELECT * FROM users WHERE email = ${userInput}
+`;
+
+// BAD: String interpolation (SQL injection!)
+// await prisma.$queryRawUnsafe(`SELECT * FROM users WHERE email = '${userInput}'`);
+```
+
+### db-2: Transactions
+
+```typescript
+// Related writes must be atomic
+await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData });
+  await tx.profile.create({ data: { userId: user.id, ...profileData } });
+  await tx.auditLog.create({ data: { action: 'USER_CREATED', userId: user.id } });
+  return user;
+});
+```
+
+### db-3: Prevent N+1
+
+```typescript
+// BAD: N+1 queries
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { userId: user.id } });
+}
+
+// GOOD: Eager loading
+const users = await prisma.user.findMany({
+  include: {
+    posts: {
+      take: 5,
+      orderBy: { createdAt: 'desc' },
+    },
+  },
+});
+```
+
+### db-9: Money as Decimal
+
+```typescript
+// BAD: Float precision issues
+// 0.1 + 0.2 = 0.30000000000000004
+
+// GOOD: Use Decimal or string in cents
+model Transaction {
+  amount    Decimal  @db.Decimal(19, 4)
+  currency  String   @db.VarChar(3)
+}
+
+// Or store cents as integer
+model Transaction {
+  amountCents  Int
+  currency     String
+}
+
+// Display: formatMoney(amountCents / 100)
+```
+
+---
+
+## PostgreSQL Best Practices
+
+### pg-1: JSONB for Flexible Fields
+
+```sql
+-- Store flexible metadata without schema changes
+CREATE TABLE products (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name TEXT NOT NULL,
+  metadata JSONB DEFAULT '{}'::jsonb
+);
+
+-- Query JSONB fields
+SELECT * FROM products
+WHERE metadata->>'category' = 'electronics'
+  AND (metadata->>'price')::numeric > 100;
+
+-- Index JSONB for performance
+CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
+
+-- Partial index for specific queries
+CREATE INDEX idx_products_category ON products ((metadata->>'category'));
+```
+
+### pg-2: Partial Indexes
+
+```sql
+-- Index only active users (smaller, faster)
+CREATE INDEX idx_users_active_email ON users (email)
+WHERE deleted_at IS NULL AND status = 'active';
+
+-- Index only recent orders
+CREATE INDEX idx_orders_recent ON orders (created_at DESC)
+WHERE created_at > NOW() - INTERVAL '30 days';
+
+-- Unique constraint with condition
+CREATE UNIQUE INDEX idx_users_unique_email ON users (email)
+WHERE deleted_at IS NULL;
+```
+
+### pg-4: UUID v7 for Primary Keys
+
+```sql
+-- UUID v7: timestamp-sortable, better for indexes
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- Drizzle schema
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  // Or use uuid_generate_v7() with extension
+});
+
+-- Benefits over serial:
+-- - No sequence contention
+-- - Can be generated client-side
+-- - Distributed-friendly
+-- - No information leakage
+```
+
+### pg-7: Row-Level Security for Multi-Tenancy
+
+```sql
+-- Enable RLS
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+-- Create policy: users see only their org's documents
+CREATE POLICY documents_isolation ON documents
+  FOR ALL
+  USING (org_id = current_setting('app.current_org_id')::uuid);
+
+-- Set org context before queries
+SET app.current_org_id = 'org-uuid-here';
+
+-- Now all queries are automatically filtered
+SELECT * FROM documents; -- Only returns current org's docs
+```
+
+### pg-8: Statement Timeout
+
+```sql
+-- Prevent runaway queries (set in connection)
+SET statement_timeout = '30s';
+
+-- Or per-transaction
+BEGIN;
+SET LOCAL statement_timeout = '5s';
+SELECT * FROM expensive_query();
+COMMIT;
+
+-- In Prisma connection string
+DATABASE_URL="postgresql://...?statement_timeout=30000"
+```
+
+---
+
+## MongoDB Best Practices
+
+### mongo-1: Schema Design for Queries
+
+```typescript
+// Design schema based on how you query, not how data relates
+
+// BAD: Normalized (requires multiple queries)
+// users collection: { _id, name }
+// orders collection: { _id, userId, items }
+// items collection: { _id, orderId, productId }
+
+// GOOD: Denormalized for common query
+// orders collection:
+{
+  _id: ObjectId,
+  user: { _id, name, email },  // Embedded (frequently accessed)
+  items: [
+    { productId, name, price, quantity }  // Embedded array
+  ],
+  total: Decimal128,
+  status: 'pending'
+}
+
+// Query: Get order with all details in ONE query
+const order = await db.orders.findOne({ _id: orderId });
+```
+
+### mongo-2: Embed vs Reference
+
+```typescript
+// EMBED when:
+// - Data is accessed together
+// - Data belongs to parent
+// - Array is bounded (<100 items)
+
+// User with addresses (bounded, always accessed together)
+{
+  _id: ObjectId,
+  name: 'John',
+  addresses: [
+    { type: 'home', street: '123 Main' },
+    { type: 'work', street: '456 Office' }
+  ]
+}
+
+// REFERENCE when:
+// - Data is large
+// - Data is accessed independently
+// - Array could grow unbounded
+
+// Blog post with comments (unbounded)
+// posts collection
+{ _id: ObjectId, title: 'Post', authorId: ObjectId }
+
+// comments collection (separate)
+{ _id: ObjectId, postId: ObjectId, text: '...', authorId: ObjectId }
+```
+
+### mongo-4: Compound Indexes
+
+```typescript
+// Index must match query pattern exactly
+// Order matters: equality → sort → range
+
+// Query: Find active users, sort by createdAt, filter by age
+db.users.find({ status: 'active', age: { $gte: 18 } }).sort({ createdAt: -1 })
+
+// Index: status (equality) → createdAt (sort) → age (range)
+db.users.createIndex({ status: 1, createdAt: -1, age: 1 });
+
+// Covered query (index-only, fastest)
+db.users.find(
+  { status: 'active' },
+  { _id: 0, status: 1, createdAt: 1 }  // Only indexed fields
+).hint({ status: 1, createdAt: -1 });
+```
+
+### mongo-5: Aggregation Pipeline
+
+```typescript
+// Complex queries with aggregation
+const result = await db.orders.aggregate([
+  // Stage 1: Filter
+  { $match: { status: 'completed', createdAt: { $gte: lastMonth } } },
+
+  // Stage 2: Group by user
+  { $group: {
+    _id: '$userId',
+    totalSpent: { $sum: '$total' },
+    orderCount: { $sum: 1 }
+  }},
+
+  // Stage 3: Sort by spend
+  { $sort: { totalSpent: -1 } },
+
+  // Stage 4: Top 10
+  { $limit: 10 },
+
+  // Stage 5: Lookup user details
+  { $lookup: {
+    from: 'users',
+    localField: '_id',
+    foreignField: '_id',
+    as: 'user'
+  }},
+
+  // Stage 6: Reshape
+  { $project: {
+    userName: { $arrayElemAt: ['$user.name', 0] },
+    totalSpent: 1,
+    orderCount: 1
+  }}
+]);
+```
+
+### mongo-8: Avoid Unbounded Arrays
+
+```typescript
+// BAD: Array grows forever
+{
+  _id: 'popular-post',
+  likes: ['user1', 'user2', ... 'user1000000']  // Document too large!
+}
+
+// GOOD: Bucket pattern (fixed array size)
+{
+  _id: ObjectId,
+  postId: 'popular-post',
+  bucket: 1,
+  likes: ['user1', ..., 'user100'],  // Max 100 per bucket
+  count: 100
+}
+
+// GOOD: Separate collection
+// likes collection
+{ postId: 'popular-post', userId: 'user1', createdAt: Date }
+
+// Count with aggregation or maintain counter
+{ _id: 'popular-post', likeCount: 1000000 }
+```
+
+### sec-2: Check Resource Ownership
+
+```typescript
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  const session = await getSession();
+  if (!session) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const resource = await prisma.resource.findUnique({
+    where: { id: params.id },
+  });
+
+  if (!resource) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  // CRITICAL: Check ownership
+  if (resource.userId !== session.user.id && session.user.role !== 'ADMIN') {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  await prisma.resource.delete({ where: { id: params.id } });
+  return NextResponse.json({ success: true });
+}
+```
+
+### sec-4: Secure Session Cookies
+
+```typescript
+const sessionOptions = {
+  password: process.env.SESSION_SECRET!, // 32+ chars
+  cookieName: 'session',
+  cookieOptions: {
+    httpOnly: true,        // No JS access
+    secure: true,          // HTTPS only
+    sameSite: 'lax',       // CSRF protection
+    maxAge: 60 * 60 * 24,  // 24 hours
+    path: '/',
+  },
+};
+```
+
+### sec-5: Password Hashing
+
+```typescript
+import { hash, verify } from '@node-rs/argon2';
+
+// Hash password before storing
+const hashedPassword = await hash(plainPassword, {
+  memoryCost: 65536,
+  timeCost: 3,
+  parallelism: 4,
+});
+
+// Verify on login
+const isValid = await verify(hashedPassword, inputPassword);
+```
+
+---
+
+## API Patterns
+
+### RESTful Endpoints
+
+```
+GET    /users           # List users
+GET    /users/:id       # Get user
+POST   /users           # Create user
+PATCH  /users/:id       # Update user
+DELETE /users/:id       # Delete user
+
+GET    /users/:id/posts # Nested resources
+POST   /users/:id/posts
+
+# Query params for filtering
+GET    /users?role=admin&status=active&page=2&limit=20&sort=-createdAt
+```
+
+### Pagination
+
+```typescript
+const PaginationSchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  limit: z.coerce.number().min(1).max(100).default(20),
+});
+
+export async function GET(request: NextRequest) {
+  const params = Object.fromEntries(request.nextUrl.searchParams);
+  const { page, limit } = PaginationSchema.parse(params);
+
+  const [data, total] = await Promise.all([
+    prisma.user.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+    }),
+    prisma.user.count(),
+  ]);
+
+  return NextResponse.json({
+    data,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  });
+}
+```
+
+### Service Layer
+
+```typescript
+// services/user.service.ts
+export class UserService {
+  async create(input: CreateUserInput): Promise<User> {
+    const existing = await prisma.user.findUnique({
+      where: { email: input.email },
+    });
+
+    if (existing) {
+      throw new ConflictError('Email already exists');
+    }
+
+    return prisma.user.create({
+      data: {
+        ...input,
+        password: await hash(input.password),
+      },
+    });
+  }
+
+  async findById(id: string): Promise<User> {
+    const user = await prisma.user.findUnique({ where: { id } });
+    if (!user) throw new NotFoundError('User');
+    return user;
+  }
+}
+```
+
+### Rate Limiting
+
+```typescript
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '10s'),
+});
+
+export async function POST(request: NextRequest) {
+  const ip = request.ip ?? '127.0.0.1';
+  const { success, remaining } = await ratelimit.limit(ip);
+
+  if (!success) {
+    return NextResponse.json(
+      { error: { code: 'RATE_LIMITED', message: 'Too many requests' } },
+      { status: 429, headers: { 'X-RateLimit-Remaining': String(remaining) } }
+    );
+  }
+
+  // Process request...
+}
+```
+
+---
+
+## Error Classes
+
+```typescript
+export class AppError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public statusCode: number = 500
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string) {
+    super('VALIDATION_ERROR', message, 400);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super('NOT_FOUND', `${resource} not found`, 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor() {
+    super('UNAUTHORIZED', 'Authentication required', 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor() {
+    super('FORBIDDEN', 'Insufficient permissions', 403);
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string) {
+    super('CONFLICT', message, 409);
+  }
+}
+```
+
+---
+
+## Logging
+
+```typescript
+// Never log sensitive data
+const logger = {
+  info: (message: string, meta?: object) => {
+    console.log(JSON.stringify({
+      level: 'info',
+      message,
+      ...meta,
+      timestamp: new Date().toISOString(),
+    }));
+  },
+
+  error: (message: string, error?: Error) => {
+    console.error(JSON.stringify({
+      level: 'error',
+      message,
+      error: error ? {
+        name: error.name,
+        message: error.message,
+        stack: process.env.NODE_ENV === 'development' ? error.stack : undefined,
+      } : undefined,
+      timestamp: new Date().toISOString(),
+    }));
+  },
+};
+
+// Usage
+logger.info('User created', { userId: user.id }); // Good
+// logger.info('User created', { email, password }); // BAD!
+```