@hivehub/rulebook 1.2.0

package/templates/services/POSTGRESQL.md

@@ -0,0 +1,326 @@
+<!-- POSTGRESQL:START -->
+# PostgreSQL Database Instructions
+
+**CRITICAL**: Use PostgreSQL for relational data storage with ACID compliance, transactions, and advanced features.
+
+## Core Features
+
+### Connection
+```typescript
+// Using pg (Node.js)
+import { Pool } from 'pg'
+const pool = new Pool({
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || '5432'),
+  database: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+})
+
+// Using Prisma
+import { PrismaClient } from '@prisma/client'
+const prisma = new PrismaClient()
+```
+
+### Basic Queries
+```typescript
+// SELECT
+const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId])
+const users = result.rows
+
+// INSERT
+const result = await pool.query(
+  'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
+  ['John Doe', 'john@example.com']
+)
+const newUser = result.rows[0]
+
+// UPDATE
+const result = await pool.query(
+  'UPDATE users SET name = $1 WHERE id = $2 RETURNING *',
+  ['Jane Doe', userId]
+)
+
+// DELETE
+await pool.query('DELETE FROM users WHERE id = $1', [userId])
+```
+
+### Transactions
+```typescript
+const client = await pool.connect()
+try {
+  await client.query('BEGIN')
+  
+  await client.query('INSERT INTO accounts (user_id, balance) VALUES ($1, $2)', [userId, 1000])
+  await client.query('INSERT INTO transactions (account_id, amount) VALUES ($1, $2)', [accountId, 1000])
+  
+  await client.query('COMMIT')
+} catch (error) {
+  await client.query('ROLLBACK')
+  throw error
+} finally {
+  client.release()
+}
+```
+
+### Advanced Features
+```typescript
+// JSONB queries
+await pool.query(
+  'SELECT * FROM products WHERE metadata @> $1',
+  [JSON.stringify({ category: 'electronics' })]
+)
+
+// Full-text search
+await pool.query(
+  "SELECT * FROM articles WHERE to_tsvector('english', content) @@ to_tsquery('english', $1)",
+  ['search term']
+)
+
+// Array operations
+await pool.query('SELECT * FROM posts WHERE tags && $1', [['javascript', 'typescript']])
+
+// Window functions
+await pool.query(`
+  SELECT 
+    name,
+    salary,
+    ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank
+  FROM employees
+`)
+```
+
+## Common Patterns
+
+### Connection Pooling
+```typescript
+// Reuse connection pool
+let pool: Pool | null = null
+
+export function getPool(): Pool {
+  if (!pool) {
+    pool = new Pool({
+      // ... config
+    })
+    
+    pool.on('error', (err) => {
+      console.error('Unexpected error on idle client', err)
+      process.exit(-1)
+    })
+  }
+  return pool
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  if (pool) {
+    await pool.end()
+  }
+  process.exit(0)
+})
+```
+
+### Prepared Statements
+```typescript
+// Always use parameterized queries to prevent SQL injection
+// ❌ WRONG
+await pool.query(`SELECT * FROM users WHERE email = '${email}'`)
+
+// ✅ CORRECT
+await pool.query('SELECT * FROM users WHERE email = $1', [email])
+```
+
+### Error Handling
+```typescript
+try {
+  const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId])
+  if (result.rows.length === 0) {
+    throw new Error('User not found')
+  }
+  return result.rows[0]
+} catch (error) {
+  if (error.code === '23505') { // Unique violation
+    throw new Error('Duplicate entry')
+  }
+  if (error.code === '23503') { // Foreign key violation
+    throw new Error('Referenced record does not exist')
+  }
+  throw error
+}
+```
+
+### Migrations
+```typescript
+// Using node-pg-migrate
+import { migrate } from 'node-pg-migrate'
+
+await migrate({
+  databaseUrl: process.env.DATABASE_URL,
+  dir: 'migrations',
+  direction: 'up',
+  migrationsTable: 'pgmigrations',
+  dryRun: false,
+})
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling (max 20-30 connections)
+- Always use parameterized queries ($1, $2, etc.)
+- Use transactions for multi-step operations
+- Create indexes on frequently queried columns
+- Use EXPLAIN ANALYZE to optimize queries
+- Enable connection pooling (PgBouncer for production)
+- Use SSL in production
+- Set appropriate connection timeouts
+- Monitor connection pool usage
+- Use prepared statements for repeated queries
+
+❌ **DON'T:**
+- Use string concatenation for queries (SQL injection risk)
+- Create too many connections (exhaust pool)
+- Skip error handling
+- Ignore connection pool limits
+- Use SELECT * in production (specify columns)
+- Skip indexes on foreign keys
+- Hardcode connection strings
+- Skip SSL in production
+- Ignore query performance
+- Use synchronous queries
+
+## Configuration
+
+### Environment Variables
+```bash
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+DB_USER=myuser
+DB_PASSWORD=securepassword
+DATABASE_URL=postgresql://user:password@host:port/database
+```
+
+### Docker Compose
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: myuser
+      POSTGRES_PASSWORD: securepassword
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U myuser"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+```
+
+### Prisma Schema
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  createdAt DateTime @default(now())
+  posts     Post[]
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  content   String?
+  authorId  Int
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now())
+}
+```
+
+## Performance Optimization
+
+### Indexing
+```sql
+-- Single column index
+CREATE INDEX idx_users_email ON users(email);
+
+-- Composite index
+CREATE INDEX idx_posts_author_created ON posts(author_id, created_at DESC);
+
+-- Partial index
+CREATE INDEX idx_active_users ON users(email) WHERE active = true;
+
+-- GIN index for JSONB
+CREATE INDEX idx_products_metadata ON products USING GIN(metadata);
+```
+
+### Query Optimization
+```typescript
+// Use LIMIT and OFFSET for pagination
+const result = await pool.query(
+  'SELECT * FROM posts ORDER BY created_at DESC LIMIT $1 OFFSET $2',
+  [limit, offset]
+)
+
+// Use EXISTS instead of COUNT for existence checks
+const result = await pool.query(
+  'SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)',
+  [email]
+)
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test database
+const testPool = new Pool({
+  database: 'myapp_test',
+  // ... config
+})
+
+// Clean up after tests
+afterEach(async () => {
+  await testPool.query('TRUNCATE TABLE users, posts CASCADE')
+})
+
+// Use transactions for test isolation
+beforeEach(async () => {
+  await testPool.query('BEGIN')
+})
+
+afterEach(async () => {
+  await testPool.query('ROLLBACK')
+})
+```
+
+### Health Checks
+```typescript
+async function checkDatabaseHealth(): Promise<boolean> {
+  try {
+    const result = await pool.query('SELECT 1')
+    return result.rows.length > 0
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- POSTGRESQL:END -->
+

package/templates/services/RABBITMQ.md

@@ -0,0 +1,286 @@
+<!-- RABBITMQ:START -->
+# RabbitMQ Message Queue Instructions
+
+**CRITICAL**: Use RabbitMQ for reliable message queuing, pub/sub messaging, and task distribution with multiple exchange types.
+
+## Core Features
+
+### Connection
+```typescript
+// Using amqplib
+import amqp from 'amqplib'
+
+const connection = await amqp.connect(process.env.RABBITMQ_URL || 'amqp://localhost:5672')
+const channel = await connection.createChannel()
+
+// Connection with options
+const connection = await amqp.connect({
+  protocol: 'amqp',
+  hostname: process.env.RABBITMQ_HOST || 'localhost',
+  port: parseInt(process.env.RABBITMQ_PORT || '5672'),
+  username: process.env.RABBITMQ_USER || 'guest',
+  password: process.env.RABBITMQ_PASSWORD || 'guest',
+  vhost: process.env.RABBITMQ_VHOST || '/',
+})
+```
+
+### Basic Operations
+```typescript
+// Declare queue
+await channel.assertQueue('tasks', {
+  durable: true, // Survive broker restart
+})
+
+// Send message
+channel.sendToQueue('tasks', Buffer.from(JSON.stringify({ task: 'process' })), {
+  persistent: true, // Survive broker restart
+})
+
+// Consume messages
+await channel.consume('tasks', (msg) => {
+  if (msg) {
+    const content = JSON.parse(msg.content.toString())
+    console.log('Received:', content)
+    
+    // Process message
+    processTask(content)
+    
+    // Acknowledge
+    channel.ack(msg)
+  }
+}, {
+  noAck: false, // Manual acknowledgment
+})
+```
+
+### Exchange Types
+```typescript
+// Direct exchange
+await channel.assertExchange('logs', 'direct', { durable: true })
+await channel.bindQueue('queue', 'logs', 'error')
+await channel.publish('logs', 'error', Buffer.from('Error message'))
+
+// Topic exchange
+await channel.assertExchange('events', 'topic', { durable: true })
+await channel.bindQueue('queue', 'events', 'user.*.created')
+await channel.publish('events', 'user.123.created', Buffer.from(JSON.stringify(data)))
+
+// Fanout exchange (broadcast)
+await channel.assertExchange('notifications', 'fanout', { durable: true })
+await channel.bindQueue('queue1', 'notifications', '')
+await channel.bindQueue('queue2', 'notifications', '')
+await channel.publish('notifications', '', Buffer.from('Broadcast message'))
+
+// Headers exchange
+await channel.assertExchange('headers_exchange', 'headers', { durable: true })
+await channel.bindQueue('queue', 'headers_exchange', '', {
+  'x-match': 'all',
+  type: 'notification',
+  priority: 'high',
+})
+await channel.publish('headers_exchange', '', Buffer.from('Message'), {
+  headers: { type: 'notification', priority: 'high' },
+})
+```
+
+## Common Patterns
+
+### Work Queue (Task Distribution)
+```typescript
+// Producer
+async function publishTask(task: any) {
+  await channel.assertQueue('tasks', { durable: true })
+  channel.sendToQueue('tasks', Buffer.from(JSON.stringify(task)), {
+    persistent: true,
+  })
+}
+
+// Consumer
+async function consumeTasks() {
+  await channel.assertQueue('tasks', { durable: true })
+  channel.prefetch(1) // Process one message at a time
+  
+  await channel.consume('tasks', async (msg) => {
+    if (msg) {
+      try {
+        const task = JSON.parse(msg.content.toString())
+        await processTask(task)
+        channel.ack(msg)
+      } catch (error) {
+        // Reject and requeue
+        channel.nack(msg, false, true)
+      }
+    }
+  })
+}
+```
+
+### Pub/Sub
+```typescript
+// Publisher
+async function publishEvent(eventType: string, data: any) {
+  await channel.assertExchange('events', 'topic', { durable: true })
+  channel.publish('events', eventType, Buffer.from(JSON.stringify(data)), {
+    persistent: true,
+  })
+}
+
+// Subscriber
+async function subscribeToEvents(routingKey: string, handler: (data: any) => void) {
+  await channel.assertExchange('events', 'topic', { durable: true })
+  const queue = await channel.assertQueue('', { exclusive: true })
+  await channel.bindQueue(queue.queue, 'events', routingKey)
+  
+  await channel.consume(queue.queue, (msg) => {
+    if (msg) {
+      const data = JSON.parse(msg.content.toString())
+      handler(data)
+      channel.ack(msg)
+    }
+  })
+}
+```
+
+### RPC Pattern
+```typescript
+// RPC Server
+async function setupRPCServer() {
+  await channel.assertQueue('rpc_queue', { durable: false })
+  channel.prefetch(1)
+  
+  await channel.consume('rpc_queue', async (msg) => {
+    if (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)
+    }
+  })
+}
+
+// RPC Client
+async function rpcCall(request: any): Promise<any> {
+  const queue = await channel.assertQueue('', { exclusive: true })
+  const correlationId = generateUuid()
+  
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      channel.deleteQueue(queue.queue)
+      reject(new Error('RPC timeout'))
+    }, 10000)
+    
+    channel.consume(queue.queue, (msg) => {
+      if (msg && msg.properties.correlationId === correlationId) {
+        clearTimeout(timeout)
+        const response = JSON.parse(msg.content.toString())
+        channel.deleteQueue(queue.queue)
+        resolve(response)
+      }
+    }, { noAck: true })
+    
+    channel.sendToQueue('rpc_queue', Buffer.from(JSON.stringify(request)), {
+      correlationId,
+      replyTo: queue.queue,
+    })
+  })
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use durable queues and exchanges for important messages
+- Set message persistence for critical messages
+- Use manual acknowledgment (noAck: false)
+- Implement proper error handling
+- Use prefetch to control message distribution
+- Monitor queue lengths
+- Use dead letter exchanges for failed messages
+- Implement connection retry logic
+- Use appropriate exchange types
+- Set message TTL when needed
+
+❌ **DON'T:**
+- Skip acknowledgment (lose messages on crash)
+- Use auto-ack for critical messages
+- Ignore connection errors
+- Hardcode connection strings
+- Store large messages (use external storage)
+- Skip error handling
+- Ignore queue monitoring
+- Use non-durable queues for important data
+- Skip message persistence
+- Ignore memory limits
+
+## Configuration
+
+### Environment Variables
+```bash
+RABBITMQ_URL=amqp://localhost:5672
+RABBITMQ_URL=amqp://user:password@host:5672/vhost
+RABBITMQ_HOST=localhost
+RABBITMQ_PORT=5672
+RABBITMQ_USER=guest
+RABBITMQ_PASSWORD=guest
+RABBITMQ_VHOST=/
+```
+
+### Docker Compose
+```yaml
+services:
+  rabbitmq:
+    image: rabbitmq:3-management-alpine
+    ports:
+      - "5672:5672"   # AMQP
+      - "15672:15672" # Management UI
+    environment:
+      RABBITMQ_DEFAULT_USER: admin
+      RABBITMQ_DEFAULT_PASS: securepassword
+    volumes:
+      - rabbitmq_data:/var/lib/rabbitmq
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  rabbitmq_data:
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test connection
+const testConnection = await amqp.connect('amqp://localhost:5673') // Different port
+
+// Clean up after tests
+afterEach(async () => {
+  // Delete test queues/exchanges or use separate vhost
+})
+```
+
+### Health Checks
+```typescript
+async function checkRabbitMQHealth(): Promise<boolean> {
+  try {
+    const connection = await amqp.connect(process.env.RABBITMQ_URL)
+    await connection.close()
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- RABBITMQ:END -->
+