create-tigra 1.0.0

package/template/.claude/rules/server-09-api-documentation-v2.md

@@ -0,0 +1,169 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# API Documentation
+
+## Stack
+
+```json
+{
+  "dependencies": {
+    "@fastify/swagger": "^8.12.0",
+    "@fastify/swagger-ui": "^2.0.0",
+    "zod-to-json-schema": "^3.22.0"
+  }
+}
+```
+
+## Setup
+
+```typescript
+// app.ts
+import swagger from '@fastify/swagger';
+import swaggerUI from '@fastify/swagger-ui';
+
+await app.register(swagger, {
+  openapi: {
+    info: {
+      title: 'API Server',
+      version: '1.0.0',
+    },
+    servers: [
+      { url: 'http://localhost:3000', description: 'Development' },
+    ],
+    tags: [
+      { name: 'auth', description: 'Authentication' },
+      { name: 'resources', description: 'Resource operations' },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+      },
+    },
+  },
+});
+
+await app.register(swaggerUI, {
+  routePrefix: '/docs',
+  uiConfig: { docExpansion: 'list', deepLinking: true },
+});
+```
+
+**Access:** `http://localhost:3000/docs`
+
+## Route Documentation Pattern
+
+```typescript
+// modules/resources/resources.schemas.ts
+import { z } from 'zod';
+
+export const CreateResourceSchema = z.object({
+  title: z.string().min(1).max(200),
+  price: z.number().positive(),
+});
+
+export const ResourceResponseSchema = z.object({
+  success: z.literal(true),
+  message: z.string(),
+  data: z.object({
+    id: z.string().uuid(),
+    title: z.string(),
+    price: z.number(),
+  }),
+});
+```
+
+```typescript
+// modules/resources/resources.routes.ts
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import * as schemas from './resources.schemas';
+
+app.post('/resources', {
+  schema: {
+    description: 'Create a new resource',
+    tags: ['resources'],
+    summary: 'Create resource',
+    body: zodToJsonSchema(schemas.CreateResourceSchema, 'CreateResource'),
+    response: {
+      201: zodToJsonSchema(schemas.ResourceResponseSchema, 'ResourceResponse'),
+      400: {
+        description: 'Validation error',
+        type: 'object',
+        properties: {
+          success: { type: 'boolean', enum: [false] },
+          error: {
+            type: 'object',
+            properties: {
+              code: { type: 'string' },
+              message: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+    security: [{ bearerAuth: [] }],
+  },
+  handler: resourceController.createResource,
+});
+```
+
+## Document All Responses
+
+```typescript
+response: {
+  200: successSchema,
+  400: validationErrorSchema,
+  401: unauthorizedSchema,
+  404: notFoundSchema,
+  500: internalErrorSchema,
+}
+```
+
+## Production Config
+
+```typescript
+if (process.env.NODE_ENV === 'production') {
+  // Option 1: Disable docs
+  // Don't register swagger-ui
+  
+  // Option 2: Require auth for docs
+  await app.register(swaggerUI, {
+    routePrefix: '/docs',
+    transformSpecification: (swaggerObject, request, reply) => {
+      if (!request.headers.authorization) {
+        reply.code(401).send({ error: 'Unauthorized' });
+      }
+      return swaggerObject;
+    },
+  });
+}
+```
+
+## Best Practices
+
+### ✅ DO:
+- Use Zod schemas for all routes
+- Document all error responses
+- Add descriptions and summaries
+- Include security requirements
+- Tag routes by domain
+
+### ❌ DON'T:
+- Skip documentation on routes
+- Forget error response schemas
+- Expose docs publicly in production
+- Use generic descriptions
+
+## Checklist
+
+- [ ] Swagger and Swagger UI registered
+- [ ] All routes have schemas
+- [ ] Zod schemas converted to JSON Schema
+- [ ] Error responses documented
+- [ ] Tags used for grouping
+- [ ] Security requirements documented
+- [ ] Production docs secured

package/template/.claude/rules/server-10-background-jobs-v2.md

@@ -0,0 +1,186 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# Background Jobs & Queue Processing
+
+## Stack
+
+```json
+{
+  "dependencies": {
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.3.0"
+  }
+}
+```
+
+## Redis Setup
+
+```typescript
+// libs/redis.ts
+import Redis from 'ioredis';
+
+export const redis = new Redis({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: parseInt(process.env.REDIS_PORT || '6379'),
+  maxRetriesPerRequest: null, // Required for BullMQ
+});
+```
+
+## Queue Setup
+
+```typescript
+// libs/queue.ts
+import { Queue, Worker, QueueEvents } from 'bullmq';
+import { redis } from './redis';
+
+export const emailQueue = new Queue('emails', {
+  connection: redis,
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 2000 },
+    removeOnComplete: { age: 3600, count: 100 },
+    removeOnFail: { age: 86400 },
+  },
+});
+```
+
+## Worker Pattern
+
+```typescript
+// workers/email.worker.ts
+import { Worker, Job } from 'bullmq';
+
+interface EmailJobData {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+export const emailWorker = new Worker<EmailJobData>(
+  'emails',
+  async (job: Job<EmailJobData>) => {
+    const { to, subject, body } = job.data;
+    
+    logger.info({ jobId: job.id, to }, 'Processing email');
+    
+    await sendEmail({ to, subject, body });
+    
+    return { success: true, sentAt: new Date().toISOString() };
+  },
+  {
+    connection: redis,
+    concurrency: 5,
+    limiter: { max: 100, duration: 60000 }, // 100 jobs/minute
+  }
+);
+```
+
+## Job Patterns
+
+### 1. Immediate Background Job
+```typescript
+// Add to queue (non-blocking)
+await emailQueue.add('welcome-email', {
+  to: user.email,
+  subject: 'Welcome!',
+  body: 'Thanks for signing up',
+});
+```
+
+### 2. Delayed Job
+```typescript
+// Send after 24 hours
+await emailQueue.add(
+  'reminder-email',
+  { to: user.email, subject: 'Reminder', body: 'Complete your profile' },
+  { delay: 24 * 60 * 60 * 1000 }
+);
+```
+
+### 3. Scheduled Job (Cron)
+```typescript
+// Daily at 2 AM
+await cleanupQueue.add(
+  'daily-cleanup',
+  {},
+  { repeat: { pattern: '0 2 * * *' } }
+);
+```
+
+### 4. Priority Job
+```typescript
+await paymentQueue.add(
+  'process-payment',
+  { orderId, amount },
+  { priority: 1 } // Lower = higher priority
+);
+```
+
+## Error Handling
+
+```typescript
+emailWorker.on('failed', (job, error) => {
+  logger.error({ jobId: job?.id, error }, 'Job failed');
+  
+  // Move to dead letter queue after all retries
+  if (job && job.attemptsMade >= job.opts.attempts!) {
+    deadLetterQueue.add('failed-email', {
+      originalJob: job.data,
+      failedReason: error.message,
+    });
+  }
+});
+```
+
+## Graceful Shutdown
+
+```typescript
+// server.ts
+const workers = [emailWorker, fileWorker];
+
+async function gracefulShutdown() {
+  logger.info('Shutting down workers...');
+  await Promise.all(workers.map((w) => w.close()));
+  process.exit(0);
+}
+
+process.on('SIGTERM', gracefulShutdown);
+process.on('SIGINT', gracefulShutdown);
+```
+
+## Use Cases
+
+- **Email sending** (welcome, verification, notifications)
+- **File processing** (image thumbnails, video encoding)
+- **Report generation** (PDFs, exports)
+- **Data cleanup** (expired records, temp files)
+- **External API calls** (webhooks, third-party sync)
+
+## Best Practices
+
+### ✅ DO:
+- Use background jobs for slow operations (>1s)
+- Set appropriate retry strategies
+- Implement rate limiting for external APIs
+- Monitor job failures
+- Clean up old jobs
+
+### ❌ DON'T:
+- Block HTTP responses with heavy processing
+- Forget error handling
+- Skip monitoring
+- Use queues for everything (simple tasks can run inline)
+
+## Checklist
+
+- [ ] BullMQ and Redis installed
+- [ ] Queues created with retry config
+- [ ] Workers implemented with error handling
+- [ ] Graceful shutdown configured
+- [ ] Job monitoring in place
+- [ ] Dead letter queue for failures

package/template/.claude/rules/server-11-rate-limiting-v2.md

@@ -0,0 +1,211 @@
+---
+trigger: always_on
+globs: "server/**/*"
+---
+
+> **SCOPE**: These rules apply specifically to the **server** directory.
+
+# Rate Limiting & Throttling
+
+## Stack
+
+```json
+{
+  "dependencies": {
+    "@fastify/rate-limit": "^9.0.0",
+    "ioredis": "^5.3.0"
+  }
+}
+```
+
+## Basic Setup
+
+```typescript
+// app.ts
+import rateLimit from '@fastify/rate-limit';
+import { redis } from './libs/redis';
+
+await app.register(rateLimit, {
+  global: true,
+  max: 100,
+  timeWindow: '15 minutes',
+  redis,
+  nameSpace: 'rate-limit:',
+  addHeaders: {
+    'x-ratelimit-limit': true,
+    'x-ratelimit-remaining': true,
+    'x-ratelimit-reset': true,
+    'retry-after': true,
+  },
+  errorResponseBuilder: (request, context) => ({
+    success: false,
+    error: {
+      code: 'RATE_LIMIT_EXCEEDED',
+      message: `Rate limit exceeded. Retry in ${Math.ceil(context.ttl / 1000)}s.`,
+    },
+  }),
+});
+```
+
+## Per-Route Limits
+
+```typescript
+// Disable global, configure per route
+await app.register(rateLimit, { global: false, redis });
+
+// Strict limit for login
+app.post('/auth/login', {
+  config: {
+    rateLimit: {
+      max: 5,
+      timeWindow: '15 minutes',
+    },
+  },
+  handler: authController.login,
+});
+
+// Generous limit for authenticated routes
+app.get('/resources', {
+  preHandler: [app.authenticate],
+  config: {
+    rateLimit: {
+      max: 1000,
+      timeWindow: '15 minutes',
+    },
+  },
+  handler: resourceController.listResources,
+});
+```
+
+## Custom Rate Limit Keys
+
+```typescript
+await app.register(rateLimit, {
+  redis,
+  keyGenerator: (request) => {
+    // Authenticated: rate limit by user ID
+    if (request.user) {
+      return `user:${request.user.id}`;
+    }
+    // Anonymous: rate limit by IP
+    return `ip:${request.ip}`;
+  },
+});
+```
+
+## User-Based Tiered Limits
+
+```typescript
+await app.register(rateLimit, {
+  redis,
+  max: async (request) => {
+    if (!request.user) return 100; // Anonymous
+    if (request.user.role === 'ADMIN') return 10000;
+    if (request.user.tier === 'PREMIUM') return 5000;
+    return 1000; // Standard
+  },
+});
+```
+
+## Rate Limit Tiers
+
+```typescript
+// lib/constants/rate-limits.ts
+export const RATE_LIMITS = {
+  LOGIN: { max: 5, timeWindow: '15 minutes' },
+  REGISTER: { max: 3, timeWindow: '1 hour' },
+  PASSWORD_RESET: { max: 3, timeWindow: '1 hour' },
+  PUBLIC: { max: 100, timeWindow: '15 minutes' },
+  AUTHENTICATED: { max: 1000, timeWindow: '15 minutes' },
+  PREMIUM: { max: 5000, timeWindow: '15 minutes' },
+  ADMIN: { max: 10000, timeWindow: '15 minutes' },
+  FILE_UPLOAD: { max: 10, timeWindow: '1 hour' },
+} as const;
+```
+
+## Monitoring
+
+```typescript
+await app.register(rateLimit, {
+  redis,
+  onExceeding: (request, key) => {
+    logger.warn({ key, ip: request.ip, url: request.url }, 'Approaching limit');
+  },
+  onExceeded: (request, key) => {
+    logger.error({ key, ip: request.ip, url: request.url }, 'Limit exceeded');
+  },
+});
+```
+
+## Whitelist IPs
+
+```typescript
+app.addHook('preHandler', async (request, reply) => {
+  const whitelistedIPs = ['127.0.0.1', '::1'];
+  if (whitelistedIPs.includes(request.ip)) {
+    // @ts-ignore
+    request.bypassRateLimit = true;
+  }
+});
+
+await app.register(rateLimit, {
+  redis,
+  skip: (request) => request.bypassRateLimit === true,
+});
+```
+
+## Check Rate Limit Status
+
+```typescript
+app.get('/me/rate-limit', {
+  preHandler: [app.authenticate],
+  handler: async (request, reply) => {
+    const key = `user:${request.user.id}`;
+    const current = await redis.get(`rate-limit:${key}`);
+    const ttl = await redis.ttl(`rate-limit:${key}`);
+    
+    return {
+      limit: 1000,
+      used: parseInt(current || '0'),
+      remaining: 1000 - parseInt(current || '0'),
+      resetIn: ttl,
+    };
+  },
+});
+```
+
+## Strategy Summary
+
+| Endpoint | Max | Window | Key |
+|----------|-----|--------|-----|
+| Login | 5 | 15 min | IP |
+| Register | 3 | 1 hour | IP + email |
+| Public API | 100 | 15 min | IP |
+| Authenticated | 1000 | 15 min | User ID |
+| Premium | 5000 | 15 min | User ID |
+| Admin | 10000 | 15 min | User ID |
+
+## Best Practices
+
+### ✅ DO:
+- Use Redis for distributed rate limiting
+- Set stricter limits for auth endpoints
+- Return helpful error messages with retry time
+- Log rate limit violations
+- Add rate limit headers to responses
+- Whitelist localhost for testing
+
+### ❌ DON'T:
+- Use in-memory rate limiting in production
+- Apply same limits to all endpoints
+- Block users permanently without investigation
+- Forget to test rate limits
+
+## Checklist
+
+- [ ] Rate limiting configured with Redis
+- [ ] Per-route limits set appropriately
+- [ ] Custom error responses implemented
+- [ ] Rate limit headers enabled
+- [ ] Monitoring and logging in place
+- [ ] Whitelist configured for testing