codecruise 0.1.0

package/config/agents/stack/fastify/rules/critical.md

@@ -0,0 +1,232 @@
+# Critical Rules - Fastify
+
+Must-follow rules. Violations block PR merge.
+
+---
+
+## Error Handling
+
+### CRIT-001: Always use typed errors
+
+```typescript
+// BAD
+throw new Error('User not found');
+
+// GOOD
+import { NotFoundError } from '@/lib/errors';
+throw new NotFoundError('User', userId);
+```
+
+### CRIT-002: Never expose internal errors to clients
+
+```typescript
+// BAD
+reply.status(500).send({ error: err.message, stack: err.stack });
+
+// GOOD
+fastify.setErrorHandler((error, request, reply) => {
+  if (error instanceof AppError) {
+    return reply.status(error.statusCode).send({
+      error: { code: error.code, message: error.message }
+    });
+  }
+
+  // Log internal error, send generic message
+  request.log.error(error);
+  return reply.status(500).send({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
+  });
+});
+```
+
+### CRIT-003: Always handle async errors
+
+```typescript
+// BAD - unhandled promise rejection
+fastify.get('/users', async (request) => {
+  const users = await db.users.findMany(); // Could throw
+  return users;
+});
+
+// GOOD - Fastify handles this automatically with async handlers
+// But for callbacks or event handlers:
+worker.on('error', (error) => {
+  logger.error('Worker error', { error });
+  // Graceful recovery or shutdown
+});
+```
+
+---
+
+## Validation
+
+### CRIT-004: Always validate request input
+
+```typescript
+// BAD - no validation
+fastify.post('/users', async (request) => {
+  const user = await db.users.create(request.body);
+});
+
+// GOOD - schema validation
+fastify.post('/users', {
+  schema: {
+    body: zodToJsonSchema(createUserSchema),
+  }
+}, async (request) => {
+  // request.body is validated
+});
+```
+
+### CRIT-005: Validate environment variables at startup
+
+```typescript
+// lib/env.ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  REDIS_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+---
+
+## Security
+
+### CRIT-006: Never log sensitive data
+
+```typescript
+// BAD
+logger.info('Login attempt', { email, password });
+
+// GOOD
+logger.info('Login attempt', { email, hasPassword: !!password });
+```
+
+### CRIT-007: Always use parameterized queries
+
+```typescript
+// BAD - SQL injection
+const users = await db.$queryRaw`SELECT * FROM users WHERE id = ${userId}`;
+
+// GOOD - parameterized (Prisma handles this)
+const users = await db.user.findUnique({ where: { id: userId } });
+
+// If raw SQL needed:
+const users = await db.$queryRaw(
+  Prisma.sql`SELECT * FROM users WHERE id = ${userId}`
+);
+```
+
+### CRIT-008: Validate file uploads
+
+```typescript
+// Always check:
+// - File size limits
+// - Allowed MIME types
+// - Sanitize filenames
+
+fastify.register(multipart, {
+  limits: {
+    fileSize: 5 * 1024 * 1024, // 5MB
+    files: 1,
+  },
+});
+
+// In handler
+const allowedMimes = ['image/jpeg', 'image/png', 'image/webp'];
+if (!allowedMimes.includes(file.mimetype)) {
+  throw new ValidationError('Invalid file type');
+}
+```
+
+---
+
+## Resource Management
+
+### CRIT-009: Always close connections on shutdown
+
+```typescript
+// index.ts
+const shutdown = async () => {
+  await fastify.close();
+  await prisma.$disconnect();
+  await redis.quit();
+  await rabbitConnection.close();
+  process.exit(0);
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+```
+
+### CRIT-010: Set timeouts on external calls
+
+```typescript
+// BAD - could hang forever
+const response = await fetch(externalApi);
+
+// GOOD - with timeout
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 5000);
+
+try {
+  const response = await fetch(externalApi, { signal: controller.signal });
+} finally {
+  clearTimeout(timeout);
+}
+```
+
+---
+
+## Queue Safety
+
+### CRIT-011: Always acknowledge/reject messages
+
+```typescript
+// BAD - message stuck in limbo
+channel.consume(queue, async (msg) => {
+  await processMessage(msg);
+  // Forgot to ack!
+});
+
+// GOOD
+channel.consume(queue, async (msg) => {
+  if (!msg) return;
+
+  try {
+    await processMessage(msg);
+    channel.ack(msg);
+  } catch (error) {
+    // Reject with requeue=false to avoid infinite loop
+    channel.nack(msg, false, false);
+  }
+});
+```
+
+### CRIT-012: Make queue jobs idempotent
+
+```typescript
+// BAD - could double-charge
+async function processPayment(job) {
+  await chargeCard(job.data.amount);
+}
+
+// GOOD - idempotent
+async function processPayment(job) {
+  const existing = await db.payment.findUnique({
+    where: { idempotencyKey: job.data.idempotencyKey }
+  });
+
+  if (existing) return existing;
+
+  return await db.payment.create({
+    data: { ...job.data, status: 'completed' }
+  });
+}
+```

package/config/agents/stack/fastify/rules/queues.md

@@ -0,0 +1,303 @@
+# Queue Rules - BullMQ & RabbitMQ
+
+Patterns for job queues and message brokers.
+
+---
+
+## BullMQ Patterns
+
+### QUEUE-001: Define typed job data
+
+```typescript
+// types/jobs.ts
+export interface EmailJob {
+  to: string;
+  template: 'welcome' | 'reset-password' | 'notification';
+  data: Record<string, unknown>;
+}
+
+export interface ProcessOrderJob {
+  orderId: string;
+  userId: string;
+  items: Array<{ productId: string; quantity: number }>;
+}
+
+// Queue with type
+const emailQueue = new Queue<EmailJob>('email', { connection });
+```
+
+### QUEUE-002: Configure appropriate retry strategies
+
+```typescript
+// Transient failures (network, rate limits)
+await queue.add('send-email', data, {
+  attempts: 3,
+  backoff: {
+    type: 'exponential',
+    delay: 1000, // 1s, 2s, 4s
+  },
+});
+
+// Critical jobs (payments)
+await queue.add('process-payment', data, {
+  attempts: 5,
+  backoff: {
+    type: 'exponential',
+    delay: 5000, // 5s, 10s, 20s, 40s, 80s
+  },
+});
+
+// Non-critical (analytics)
+await queue.add('track-event', data, {
+  attempts: 1, // Fire and forget
+  removeOnComplete: true,
+});
+```
+
+### QUEUE-003: Set job timeouts
+
+```typescript
+const worker = new Worker<EmailJob>('email', processor, {
+  connection,
+  lockDuration: 30000,     // 30s lock
+  stalledInterval: 15000,  // Check for stalled every 15s
+});
+
+// Or per-job
+await queue.add('long-task', data, {
+  timeout: 60000, // 1 minute max
+});
+```
+
+### QUEUE-004: Handle worker lifecycle
+
+```typescript
+const worker = new Worker('email', processor, { connection });
+
+// Graceful shutdown
+async function shutdown() {
+  await worker.close(); // Waits for current job
+  await queue.close();
+  process.exit(0);
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+// Error handling
+worker.on('failed', (job, err) => {
+  logger.error('Job failed', {
+    jobId: job?.id,
+    name: job?.name,
+    error: err.message,
+    attempts: job?.attemptsMade,
+  });
+});
+
+worker.on('error', (err) => {
+  logger.error('Worker error', { error: err.message });
+});
+```
+
+### QUEUE-005: Use job progress for long tasks
+
+```typescript
+const worker = new Worker('video-process', async (job) => {
+  const steps = ['download', 'transcode', 'upload', 'cleanup'];
+
+  for (let i = 0; i < steps.length; i++) {
+    await performStep(steps[i], job.data);
+    await job.updateProgress((i + 1) / steps.length * 100);
+  }
+});
+
+// Monitor progress
+const job = await queue.add('process', { videoId: '123' });
+job.on('progress', (progress) => {
+  console.log(`Progress: ${progress}%`);
+});
+```
+
+---
+
+## RabbitMQ Patterns
+
+### QUEUE-006: Use durable queues and persistent messages
+
+```typescript
+// Durable queue survives broker restart
+await channel.assertQueue('orders', { durable: true });
+
+// Persistent message survives broker restart
+channel.sendToQueue('orders', Buffer.from(JSON.stringify(order)), {
+  persistent: true,
+});
+```
+
+### QUEUE-007: Implement dead letter queues
+
+```typescript
+// Main queue with DLX
+await channel.assertQueue('orders', {
+  durable: true,
+  arguments: {
+    'x-dead-letter-exchange': 'orders.dlx',
+    'x-dead-letter-routing-key': 'orders.failed',
+  },
+});
+
+// Dead letter queue
+await channel.assertExchange('orders.dlx', 'direct', { durable: true });
+await channel.assertQueue('orders.failed', { durable: true });
+await channel.bindQueue('orders.failed', 'orders.dlx', 'orders.failed');
+
+// Consumer - failed messages go to DLQ after nack
+channel.consume('orders', async (msg) => {
+  try {
+    await processOrder(JSON.parse(msg.content.toString()));
+    channel.ack(msg);
+  } catch (error) {
+    // nack with requeue=false sends to DLQ
+    channel.nack(msg, false, false);
+  }
+});
+```
+
+### QUEUE-008: Use prefetch for fair dispatch
+
+```typescript
+// Don't send more than 10 messages to this worker at once
+channel.prefetch(10);
+
+// For CPU-intensive tasks, use lower prefetch
+channel.prefetch(1);
+```
+
+### QUEUE-009: Use topic exchanges for flexible routing
+
+```typescript
+// Publisher
+await channel.assertExchange('events', 'topic', { durable: true });
+
+channel.publish('events', 'order.created', Buffer.from(JSON.stringify(order)));
+channel.publish('events', 'order.shipped', Buffer.from(JSON.stringify(order)));
+channel.publish('events', 'user.registered', Buffer.from(JSON.stringify(user)));
+
+// Consumer - subscribe to patterns
+await channel.assertQueue('order-notifications');
+await channel.bindQueue('order-notifications', 'events', 'order.*');
+
+await channel.assertQueue('all-events');
+await channel.bindQueue('all-events', 'events', '#'); // All messages
+```
+
+### QUEUE-010: Implement request-reply pattern
+
+```typescript
+// Requester
+const replyQueue = await channel.assertQueue('', { exclusive: true });
+const correlationId = uuid();
+
+const response = new Promise((resolve) => {
+  channel.consume(replyQueue.queue, (msg) => {
+    if (msg.properties.correlationId === correlationId) {
+      resolve(JSON.parse(msg.content.toString()));
+    }
+  });
+});
+
+channel.sendToQueue('rpc-queue', Buffer.from(JSON.stringify(request)), {
+  correlationId,
+  replyTo: replyQueue.queue,
+});
+
+const result = await response;
+
+// Responder
+channel.consume('rpc-queue', async (msg) => {
+  const request = JSON.parse(msg.content.toString());
+  const response = await processRequest(request);
+
+  channel.sendToQueue(
+    msg.properties.replyTo,
+    Buffer.from(JSON.stringify(response)),
+    { correlationId: msg.properties.correlationId }
+  );
+
+  channel.ack(msg);
+});
+```
+
+---
+
+## Shared Patterns
+
+### QUEUE-011: Log job lifecycle
+
+```typescript
+// BullMQ
+worker.on('active', (job) => {
+  logger.info('Job started', { jobId: job.id, name: job.name });
+});
+
+worker.on('completed', (job, result) => {
+  logger.info('Job completed', {
+    jobId: job.id,
+    duration: Date.now() - job.processedOn!,
+  });
+});
+
+// RabbitMQ - wrap consumer
+function createConsumer(handler) {
+  return async (msg) => {
+    const start = Date.now();
+    logger.info('Message received', { queue, deliveryTag: msg.fields.deliveryTag });
+
+    try {
+      await handler(msg);
+      logger.info('Message processed', { duration: Date.now() - start });
+    } catch (error) {
+      logger.error('Message failed', { error: error.message });
+      throw error;
+    }
+  };
+}
+```
+
+### QUEUE-012: Use unique job IDs for deduplication
+
+```typescript
+// BullMQ - same jobId = same job (deduped)
+await queue.add('process', data, {
+  jobId: `order-${orderId}`, // Won't duplicate if already exists
+});
+
+// RabbitMQ - use message ID
+channel.sendToQueue('orders', buffer, {
+  messageId: `order-${orderId}-${Date.now()}`,
+});
+```
+
+### QUEUE-013: Monitor queue health
+
+```typescript
+// BullMQ
+async function getQueueHealth(queue: Queue) {
+  const [waiting, active, completed, failed] = await Promise.all([
+    queue.getWaitingCount(),
+    queue.getActiveCount(),
+    queue.getCompletedCount(),
+    queue.getFailedCount(),
+  ]);
+
+  return { waiting, active, completed, failed };
+}
+
+// Expose via health endpoint
+fastify.get('/health/queues', async () => {
+  return {
+    email: await getQueueHealth(emailQueue),
+    orders: await getQueueHealth(orderQueue),
+  };
+});
+```