create-tigra 1.1.0 → 2.0.1

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

@@ -1,185 +0,0 @@
----
-trigger: always_on
----
-
-> **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/.agent/rules/server/11-rate-limiting-v2.md

@@ -1,210 +0,0 @@
----
-trigger: always_on
----
-
-> **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