codecruise 0.1.0

package/config/agents/stack/fastify/AGENT.md

@@ -0,0 +1,397 @@
+---
+name: fastify
+description: Fastify APIs, BullMQ queues, RabbitMQ messaging. Use for backend services, API design, queue processing.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+dependencies: [shared-ts]
+---
+
+# Fastify Stack Agent
+
+You are a backend specialist for Fastify-based services with BullMQ and RabbitMQ integrations.
+
+## Stack Overview
+
+| Component | Purpose | Version |
+|-----------|---------|---------|
+| Fastify | HTTP framework | 4.x |
+| BullMQ | Job queues (Redis-backed) | 5.x |
+| RabbitMQ | Message broker | amqplib |
+| Prisma/Drizzle | Database ORM | Latest |
+| Zod | Schema validation | 3.x |
+
+## Project Structure
+
+```
+apps/api/
+├── src/
+│   ├── routes/           # Route handlers
+│   │   ├── users/
+│   │   │   ├── index.ts  # Route registration
+│   │   │   ├── handlers.ts
+│   │   │   └── schemas.ts
+│   │   └── index.ts      # Route aggregator
+│   ├── plugins/          # Fastify plugins
+│   │   ├── auth.ts
+│   │   ├── cors.ts
+│   │   └── swagger.ts
+│   ├── services/         # Business logic
+│   ├── queues/           # BullMQ workers
+│   │   ├── email.queue.ts
+│   │   └── workers/
+│   ├── messaging/        # RabbitMQ handlers
+│   ├── lib/              # Utilities
+│   └── index.ts          # App entry
+├── tests/
+└── package.json
+```
+
+---
+
+## Core Patterns
+
+### Route Registration
+
+```typescript
+// routes/users/index.ts
+import { FastifyPluginAsync } from 'fastify';
+import { createUserSchema, getUserSchema } from './schemas';
+import { createUser, getUser } from './handlers';
+
+const usersRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.post('/', { schema: createUserSchema }, createUser);
+  fastify.get('/:id', { schema: getUserSchema }, getUser);
+};
+
+export default usersRoutes;
+```
+
+### Schema Validation (Zod + Fastify)
+
+```typescript
+// routes/users/schemas.ts
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+export const createUserBody = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  role: z.enum(['USER', 'ADMIN']).default('USER'),
+});
+
+export const createUserSchema = {
+  body: zodToJsonSchema(createUserBody),
+  response: {
+    201: zodToJsonSchema(userResponseSchema),
+    400: zodToJsonSchema(errorSchema),
+  },
+};
+```
+
+### Handler Pattern
+
+```typescript
+// routes/users/handlers.ts
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { createUserBody } from './schemas';
+import { userService } from '@/services/user';
+
+export async function createUser(
+  request: FastifyRequest<{ Body: z.infer<typeof createUserBody> }>,
+  reply: FastifyReply
+) {
+  const user = await userService.create(request.body);
+  return reply.status(201).send({ data: user });
+}
+```
+
+---
+
+## BullMQ Patterns
+
+### Queue Definition
+
+```typescript
+// queues/email.queue.ts
+import { Queue, Worker, Job } from 'bullmq';
+import { redis } from '@/lib/redis';
+
+export const emailQueue = new Queue('email', { connection: redis });
+
+export type EmailJob = {
+  to: string;
+  template: 'welcome' | 'reset-password' | 'notification';
+  data: Record<string, unknown>;
+};
+
+// Add job
+export async function queueEmail(job: EmailJob) {
+  return emailQueue.add('send', job, {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 1000 },
+  });
+}
+```
+
+### Worker Definition
+
+```typescript
+// queues/workers/email.worker.ts
+import { Worker, Job } from 'bullmq';
+import { redis } from '@/lib/redis';
+import { EmailJob } from '../email.queue';
+import { sendEmail } from '@/services/email';
+
+const emailWorker = new Worker<EmailJob>(
+  'email',
+  async (job: Job<EmailJob>) => {
+    const { to, template, data } = job.data;
+    await sendEmail(to, template, data);
+    return { sent: true, to };
+  },
+  {
+    connection: redis,
+    concurrency: 5,
+  }
+);
+
+emailWorker.on('completed', (job) => {
+  console.log(`Email sent: ${job.id}`);
+});
+
+emailWorker.on('failed', (job, err) => {
+  console.error(`Email failed: ${job?.id}`, err);
+});
+```
+
+---
+
+## RabbitMQ Patterns
+
+### Connection Setup
+
+```typescript
+// messaging/connection.ts
+import amqp, { Connection, Channel } from 'amqplib';
+
+let connection: Connection;
+let channel: Channel;
+
+export async function connectRabbitMQ() {
+  connection = await amqp.connect(process.env.RABBITMQ_URL!);
+  channel = await connection.createChannel();
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    await channel.close();
+    await connection.close();
+  });
+
+  return channel;
+}
+
+export function getChannel() {
+  if (!channel) throw new Error('RabbitMQ not connected');
+  return channel;
+}
+```
+
+### Publisher
+
+```typescript
+// messaging/publishers/order.publisher.ts
+import { getChannel } from '../connection';
+
+const EXCHANGE = 'orders';
+const ROUTING_KEY = 'order.created';
+
+export async function publishOrderCreated(order: Order) {
+  const channel = getChannel();
+
+  await channel.assertExchange(EXCHANGE, 'topic', { durable: true });
+
+  channel.publish(
+    EXCHANGE,
+    ROUTING_KEY,
+    Buffer.from(JSON.stringify(order)),
+    { persistent: true }
+  );
+}
+```
+
+### Consumer
+
+```typescript
+// messaging/consumers/order.consumer.ts
+import { getChannel } from '../connection';
+import { processOrder } from '@/services/order';
+
+const QUEUE = 'order-processor';
+const EXCHANGE = 'orders';
+const ROUTING_KEY = 'order.created';
+
+export async function startOrderConsumer() {
+  const channel = getChannel();
+
+  await channel.assertExchange(EXCHANGE, 'topic', { durable: true });
+  await channel.assertQueue(QUEUE, { durable: true });
+  await channel.bindQueue(QUEUE, EXCHANGE, ROUTING_KEY);
+
+  channel.consume(QUEUE, async (msg) => {
+    if (!msg) return;
+
+    try {
+      const order = JSON.parse(msg.content.toString());
+      await processOrder(order);
+      channel.ack(msg);
+    } catch (error) {
+      // Dead letter after 3 retries
+      channel.nack(msg, false, false);
+    }
+  });
+}
+```
+
+---
+
+## Security Patterns
+
+### Authentication Plugin
+
+```typescript
+// plugins/auth.ts
+import { FastifyPluginAsync } from 'fastify';
+import fp from 'fastify-plugin';
+import { verifyToken } from '@/lib/jwt';
+
+const authPlugin: FastifyPluginAsync = async (fastify) => {
+  fastify.decorateRequest('user', null);
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    const publicRoutes = ['/health', '/auth/login', '/auth/register'];
+    if (publicRoutes.includes(request.url)) return;
+
+    const token = request.headers.authorization?.replace('Bearer ', '');
+    if (!token) {
+      return reply.status(401).send({ error: 'Unauthorized' });
+    }
+
+    try {
+      request.user = await verifyToken(token);
+    } catch {
+      return reply.status(401).send({ error: 'Invalid token' });
+    }
+  });
+};
+
+export default fp(authPlugin);
+```
+
+### Rate Limiting
+
+```typescript
+// plugins/rate-limit.ts
+import rateLimit from '@fastify/rate-limit';
+
+await fastify.register(rateLimit, {
+  max: 100,
+  timeWindow: '1 minute',
+  keyGenerator: (request) => request.user?.id || request.ip,
+});
+
+// Stricter for auth endpoints
+fastify.register(async (instance) => {
+  instance.register(rateLimit, {
+    max: 5,
+    timeWindow: '15 minutes',
+  });
+  instance.register(authRoutes);
+});
+```
+
+---
+
+## Testing Patterns
+
+### Route Testing
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { build } from '@/app';
+import { prisma } from '@/lib/prisma';
+
+describe('POST /users', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await build();
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+    await prisma.user.deleteMany();
+  });
+
+  it('should create user with valid data', async () => {
+    const response = await app.inject({
+      method: 'POST',
+      url: '/users',
+      payload: { email: 'test@example.com', name: 'Test' },
+    });
+
+    expect(response.statusCode).toBe(201);
+    expect(response.json().data.email).toBe('test@example.com');
+  });
+});
+```
+
+### Queue Testing
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { emailQueue, queueEmail } from '@/queues/email.queue';
+
+describe('Email Queue', () => {
+  it('should add job with correct options', async () => {
+    const job = await queueEmail({
+      to: 'user@example.com',
+      template: 'welcome',
+      data: { name: 'John' },
+    });
+
+    expect(job.name).toBe('send');
+    expect(job.opts.attempts).toBe(3);
+  });
+});
+```
+
+---
+
+## Rules Reference
+
+Load on-demand from `rules/`:
+- `critical.md` - Must-follow security and error handling
+- `api-design.md` - REST conventions, response formats
+- `queues.md` - BullMQ/RabbitMQ patterns
+- `security.md` - Auth, validation, rate limiting
+
+---
+
+## Output Format
+
+```
+Workspace: apps/api
+Agent: fastify + shared-ts
+
+Files modified:
+- src/routes/users/index.ts (new route)
+- src/routes/users/handlers.ts (handlers)
+- src/routes/users/schemas.ts (zod schemas)
+- tests/routes/users.test.ts (tests)
+
+Quality: ✓ PASS
+- Schema validation: Zod + JSON Schema
+- Error handling: Standardized
+- Tests: 4 passing
+```

package/config/agents/stack/fastify/rules/api-design.md

@@ -0,0 +1,283 @@
+# API Design Rules - Fastify
+
+REST conventions, response formats, versioning.
+
+---
+
+## Response Format
+
+### API-001: Use consistent response envelope
+
+```typescript
+// Success responses
+{
+  "data": { ... },           // Single resource or array
+  "meta": {                  // Optional pagination
+    "page": 1,
+    "perPage": 20,
+    "total": 100
+  }
+}
+
+// Error responses
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [             // Optional field errors
+      { "field": "email", "message": "Required" }
+    ]
+  }
+}
+```
+
+### API-002: Use appropriate HTTP status codes
+
+```typescript
+// Success
+200 - OK (GET, PUT, PATCH)
+201 - Created (POST)
+204 - No Content (DELETE)
+
+// Client errors
+400 - Bad Request (validation)
+401 - Unauthorized (no/invalid auth)
+403 - Forbidden (auth valid, no permission)
+404 - Not Found
+409 - Conflict (duplicate, state conflict)
+422 - Unprocessable Entity (semantic errors)
+429 - Too Many Requests
+
+// Server errors
+500 - Internal Server Error
+503 - Service Unavailable
+```
+
+---
+
+## Route Design
+
+### API-003: Use plural nouns for resources
+
+```typescript
+// BAD
+GET /user/:id
+POST /user
+
+// GOOD
+GET /users/:id
+POST /users
+```
+
+### API-004: Use kebab-case for multi-word resources
+
+```typescript
+// BAD
+GET /orderItems
+GET /order_items
+
+// GOOD
+GET /order-items
+```
+
+### API-005: Nest routes for relationships (max 2 levels)
+
+```typescript
+// GOOD - clear relationship
+GET /users/:userId/orders
+GET /orders/:orderId/items
+
+// BAD - too deep
+GET /users/:userId/orders/:orderId/items/:itemId/reviews
+
+// GOOD - flatten with query params
+GET /reviews?orderId=123&itemId=456
+```
+
+### API-006: Use query params for filtering, sorting, pagination
+
+```typescript
+// Filtering
+GET /users?role=admin&status=active
+
+// Sorting
+GET /users?sort=createdAt&order=desc
+
+// Pagination
+GET /users?page=2&perPage=20
+
+// Or cursor-based
+GET /users?cursor=abc123&limit=20
+```
+
+---
+
+## Versioning
+
+### API-007: Version via URL prefix
+
+```typescript
+// GOOD
+fastify.register(v1Routes, { prefix: '/v1' });
+fastify.register(v2Routes, { prefix: '/v2' });
+
+// Routes
+GET /v1/users
+GET /v2/users  // New format, breaking changes
+```
+
+### API-008: Document breaking changes
+
+```typescript
+/**
+ * @version 2.0.0
+ * @breaking Response format changed from array to envelope
+ * @migration Use response.data instead of response
+ */
+```
+
+---
+
+## Request Handling
+
+### API-009: Parse pagination with defaults
+
+```typescript
+const paginationSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  perPage: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+// In handler
+const { page, perPage } = paginationSchema.parse(request.query);
+const skip = (page - 1) * perPage;
+```
+
+### API-010: Validate IDs in params
+
+```typescript
+const paramsSchema = z.object({
+  id: z.string().cuid(), // or .uuid()
+});
+
+// Schema definition
+{
+  params: zodToJsonSchema(paramsSchema)
+}
+```
+
+### API-011: Handle partial updates correctly
+
+```typescript
+// PATCH - partial update
+fastify.patch('/users/:id', async (request, reply) => {
+  const { id } = request.params;
+  const updates = request.body; // Only fields to update
+
+  const user = await db.user.update({
+    where: { id },
+    data: updates,
+  });
+
+  return { data: user };
+});
+
+// PUT - full replacement (require all fields)
+fastify.put('/users/:id', async (request, reply) => {
+  const { id } = request.params;
+  const fullUser = request.body; // All fields required
+
+  const user = await db.user.update({
+    where: { id },
+    data: fullUser,
+  });
+
+  return { data: user };
+});
+```
+
+---
+
+## Documentation
+
+### API-012: Use Swagger/OpenAPI
+
+```typescript
+// plugins/swagger.ts
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+
+fastify.register(swagger, {
+  openapi: {
+    info: {
+      title: 'API',
+      version: '1.0.0',
+    },
+    servers: [{ url: 'http://localhost:3000' }],
+  },
+});
+
+fastify.register(swaggerUi, {
+  routePrefix: '/docs',
+});
+```
+
+### API-013: Document endpoints with schemas
+
+```typescript
+const createUserSchema = {
+  description: 'Create a new user',
+  tags: ['users'],
+  body: zodToJsonSchema(createUserBody),
+  response: {
+    201: {
+      description: 'User created successfully',
+      ...zodToJsonSchema(userResponseSchema),
+    },
+    400: {
+      description: 'Validation error',
+      ...zodToJsonSchema(errorSchema),
+    },
+  },
+};
+```
+
+---
+
+## Performance
+
+### API-014: Use select/include to limit data
+
+```typescript
+// BAD - fetches all fields
+const user = await db.user.findUnique({ where: { id } });
+
+// GOOD - only needed fields
+const user = await db.user.findUnique({
+  where: { id },
+  select: {
+    id: true,
+    email: true,
+    name: true,
+    // Omit password, internal fields
+  },
+});
+```
+
+### API-015: Add ETags for cacheable resources
+
+```typescript
+fastify.get('/users/:id', async (request, reply) => {
+  const user = await getUser(id);
+  const etag = generateETag(user);
+
+  if (request.headers['if-none-match'] === etag) {
+    return reply.status(304).send();
+  }
+
+  return reply
+    .header('ETag', etag)
+    .header('Cache-Control', 'private, max-age=60')
+    .send({ data: user });
+});
+```