@hivehub/rulebook 1.2.0

package/templates/services/MARIADB.md

@@ -0,0 +1,183 @@
+<!-- MARIADB:START -->
+# MariaDB Database Instructions
+
+**CRITICAL**: Use MariaDB for MySQL-compatible relational database with enhanced features, performance improvements, and open-source licensing.
+
+## Core Features
+
+### Connection
+```typescript
+// Using mysql2 (compatible with MySQL)
+import mysql from 'mysql2/promise'
+
+const pool = mysql.createPool({
+  host: process.env.DB_HOST || 'localhost',
+  port: parseInt(process.env.DB_PORT || '3306'),
+  database: process.env.DB_NAME || 'myapp',
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  waitForConnections: true,
+  connectionLimit: 10,
+  queueLimit: 0,
+  enableKeepAlive: true,
+  keepAliveInitialDelay: 0,
+})
+
+// Using Prisma
+import { PrismaClient } from '@prisma/client'
+const prisma = new PrismaClient()
+```
+
+### Basic Queries
+```typescript
+// SELECT
+const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
+const users = rows as User[]
+
+// INSERT
+const [result] = await pool.execute(
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['John Doe', 'john@example.com']
+)
+const insertId = (result as any).insertId
+
+// UPDATE
+const [result] = await pool.execute(
+  'UPDATE users SET name = ? WHERE id = ?',
+  ['Jane Doe', userId]
+)
+
+// DELETE
+await pool.execute('DELETE FROM users WHERE id = ?', [userId])
+```
+
+### Advanced Features
+```typescript
+// JSON operations (MariaDB 10.2.7+)
+const [rows] = await pool.execute(
+  "SELECT * FROM products WHERE JSON_EXTRACT(metadata, '$.category') = ?",
+  ['electronics']
+)
+
+// Window functions (MariaDB 10.2+)
+const [rows] = await pool.execute(`
+  SELECT 
+    name,
+    salary,
+    ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank
+  FROM employees
+`)
+
+// Common Table Expressions (CTE) (MariaDB 10.2+)
+const [rows] = await pool.execute(`
+  WITH RECURSIVE cte AS (
+    SELECT id, name, parent_id FROM categories WHERE parent_id IS NULL
+    UNION ALL
+    SELECT c.id, c.name, c.parent_id FROM categories c
+    INNER JOIN cte ON c.parent_id = cte.id
+  )
+  SELECT * FROM cte
+`)
+
+// Sequences (MariaDB 10.3+)
+await pool.execute('CREATE SEQUENCE user_id_seq START WITH 1 INCREMENT BY 1')
+const [result] = await pool.execute('SELECT NEXT VALUE FOR user_id_seq')
+```
+
+## Common Patterns
+
+### Connection Pooling
+```typescript
+let pool: mysql.Pool | null = null
+
+export function getPool(): mysql.Pool {
+  if (!pool) {
+    pool = mysql.createPool({
+      // ... config
+    })
+  }
+  return pool
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  if (pool) {
+    await pool.end()
+  }
+  process.exit(0)
+})
+```
+
+### Error Handling
+```typescript
+try {
+  const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
+  if ((rows as any[]).length === 0) {
+    throw new Error('User not found')
+  }
+  return rows[0]
+} catch (error: any) {
+  if (error.code === 'ER_DUP_ENTRY') {
+    throw new Error('Duplicate entry')
+  }
+  throw error
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling (10-20 connections)
+- Always use parameterized queries (?)
+- Use transactions for multi-step operations
+- Create indexes on frequently queried columns
+- Use InnoDB engine (ACID compliance)
+- Set appropriate charset (utf8mb4)
+- Monitor slow query log
+- Use prepared statements
+
+❌ **DON'T:**
+- Use string concatenation for queries
+- Create too many connections
+- Skip error handling
+- Use MyISAM engine
+- Hardcode connection strings
+- Ignore query performance
+
+## Configuration
+
+### Environment Variables
+```bash
+DB_HOST=localhost
+DB_PORT=3306
+DB_NAME=myapp
+DB_USER=myuser
+DB_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  mariadb:
+    image: mariadb:11
+    environment:
+      MYSQL_DATABASE: myapp
+      MYSQL_USER: myuser
+      MYSQL_PASSWORD: securepassword
+      MYSQL_ROOT_PASSWORD: rootpassword
+    ports:
+      - "3306:3306"
+    volumes:
+      - mariadb_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  mariadb_data:
+```
+
+<!-- MARIADB:END -->
+

package/templates/services/MEMCACHED.md

@@ -0,0 +1,242 @@
+<!-- MEMCACHED:START -->
+# Memcached Cache Instructions
+
+**CRITICAL**: Use Memcached for simple, high-performance distributed caching with minimal overhead.
+
+## Core Features
+
+### Connection
+```typescript
+// Using memcached (Node.js)
+import Memcached from 'memcached'
+
+const memcached = new Memcached(process.env.MEMCACHED_SERVERS || 'localhost:11211', {
+  maxKeySize: 250,
+  maxExpiration: 2592000, // 30 days
+  maxValue: 1048576, // 1MB
+  poolSize: 10,
+  reconnect: true,
+  timeout: 5000,
+  retries: 3,
+  retry: 1000,
+  remove: true,
+  idle: 5000,
+})
+```
+
+### Basic Operations
+```typescript
+// Set
+memcached.set('user:1', { name: 'John', email: 'john@example.com' }, 3600, (err) => {
+  // Expires in 1 hour
+})
+
+// Get
+memcached.get('user:1', (err, data) => {
+  console.log(data)
+})
+
+// Delete
+memcached.del('user:1', (err) => {
+  // Deleted
+})
+
+// Replace (only if key exists)
+memcached.replace('user:1', newData, 3600, (err) => {
+  // Replaced
+})
+
+// Add (only if key doesn't exist)
+memcached.add('user:1', data, 3600, (err) => {
+  // Added
+})
+```
+
+### Advanced Operations
+```typescript
+// Multiple gets
+memcached.getMulti(['user:1', 'user:2', 'user:3'], (err, data) => {
+  // Returns object with keys as properties
+})
+
+// Increment/Decrement
+memcached.incr('counter', 1, (err, value) => {
+  // Incremented
+})
+
+memcached.decr('counter', 1, (err, value) => {
+  // Decremented
+})
+
+// Touch (update expiration)
+memcached.touch('user:1', 7200, (err) => {
+  // Expiration updated to 2 hours
+})
+
+// Stats
+memcached.stats((err, stats) => {
+  console.log(stats)
+})
+```
+
+## Common Patterns
+
+### Caching with Promises
+```typescript
+function getCached(key: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    memcached.get(key, (err, data) => {
+      if (err) reject(err)
+      else resolve(data)
+    })
+  })
+}
+
+function setCached(key: string, value: any, ttl: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    memcached.set(key, value, ttl, (err) => {
+      if (err) reject(err)
+      else resolve()
+    })
+  })
+}
+
+// Usage
+async function getCachedUser(userId: string) {
+  const cached = await getCached(`user:${userId}`)
+  if (cached) {
+    return cached
+  }
+  
+  const user = await fetchUserFromDatabase(userId)
+  await setCached(`user:${userId}`, user, 3600)
+  return user
+}
+```
+
+### Cache-Aside Pattern
+```typescript
+async function getWithCache(key: string, fetchFn: () => Promise<any>, ttl: number) {
+  try {
+    const cached = await getCached(key)
+    if (cached) {
+      return cached
+    }
+  } catch (err) {
+    // Cache miss or error, continue to fetch
+  }
+  
+  const data = await fetchFn()
+  try {
+    await setCached(key, data, ttl)
+  } catch (err) {
+    // Cache set failed, but we have the data
+  }
+  
+  return data
+}
+```
+
+### Rate Limiting
+```typescript
+async function checkRateLimit(identifier: string, limit: number, window: number): Promise<boolean> {
+  const key = `ratelimit:${identifier}`
+  
+  return new Promise((resolve) => {
+    memcached.incr(key, 1, (err, value) => {
+      if (err || value === false) {
+        // Key doesn't exist, create it
+        memcached.set(key, 1, window, () => {
+          resolve(true)
+        })
+      } else if (value > limit) {
+        resolve(false)
+      } else {
+        if (value === 1) {
+          // First increment, set expiration
+          memcached.touch(key, window, () => {})
+        }
+        resolve(true)
+      }
+    })
+  })
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling
+- Set appropriate TTL for cached data
+- Handle cache misses gracefully
+- Use consistent key naming conventions
+- Monitor cache hit rates
+- Use multiple servers for redundancy
+- Compress large values before storing
+- Implement cache warming strategies
+- Use appropriate data serialization
+- Monitor memory usage
+
+❌ **DON'T:**
+- Store large values (> 1MB, use external storage)
+- Use Memcached as primary database
+- Store sensitive data without encryption
+- Skip error handling
+- Ignore connection failures
+- Hardcode server addresses
+- Use blocking operations
+- Store complex nested objects (flatten when possible)
+- Ignore eviction policies
+- Skip monitoring
+
+## Configuration
+
+### Environment Variables
+```bash
+MEMCACHED_SERVERS=localhost:11211
+MEMCACHED_SERVERS=server1:11211,server2:11211,server3:11211
+```
+
+### Docker Compose
+```yaml
+services:
+  memcached:
+    image: memcached:1.6-alpine
+    ports:
+      - "11211:11211"
+    command: ["-m", "64", "-I", "1m"]  # 64MB memory, 1MB max item size
+    healthcheck:
+      test: ["CMD", "nc", "-z", "localhost", "11211"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test Memcached instance
+const testMemcached = new Memcached('localhost:11212') // Different port
+
+// Clean up after tests
+afterEach((done) => {
+  testMemcached.flush((err) => {
+    done()
+  })
+})
+```
+
+### Health Checks
+```typescript
+function checkMemcachedHealth(): Promise<boolean> {
+  return new Promise((resolve) => {
+    memcached.stats((err) => {
+      resolve(!err)
+    })
+  })
+}
+```
+
+<!-- MEMCACHED:END -->
+

package/templates/services/MINIO.md

@@ -0,0 +1,201 @@
+<!-- MINIO:START -->
+# MinIO S3-Compatible Storage Instructions
+
+**CRITICAL**: Use MinIO for S3-compatible object storage, self-hosted file storage, and development/testing with S3 APIs.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @aws-sdk/client-s3 (S3-compatible)
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3'
+
+const s3Client = new S3Client({
+  endpoint: process.env.MINIO_ENDPOINT || 'http://localhost:9000',
+  region: process.env.MINIO_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.MINIO_ACCESS_KEY || 'minioadmin',
+    secretAccessKey: process.env.MINIO_SECRET_KEY || 'minioadmin',
+  },
+  forcePathStyle: true, // Required for MinIO
+})
+
+// Using minio-js
+import * as MinIO from 'minio'
+
+const minioClient = new MinIO.Client({
+  endPoint: process.env.MINIO_ENDPOINT?.replace('http://', '').replace('https://', '') || 'localhost',
+  port: parseInt(process.env.MINIO_PORT || '9000'),
+  useSSL: process.env.MINIO_USE_SSL === 'true',
+  accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
+  secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin',
+})
+```
+
+### Basic Operations
+```typescript
+// Using S3 SDK
+// Create bucket
+await s3Client.send(new CreateBucketCommand({
+  Bucket: 'my-bucket',
+}))
+
+// Upload file
+await s3Client.send(new PutObjectCommand({
+  Bucket: 'my-bucket',
+  Key: 'path/to/file.jpg',
+  Body: fileBuffer,
+  ContentType: 'image/jpeg',
+}))
+
+// Download file
+const response = await s3Client.send(new GetObjectCommand({
+  Bucket: 'my-bucket',
+  Key: 'path/to/file.jpg',
+}))
+const fileContent = await response.Body?.transformToByteArray()
+
+// Using MinIO SDK
+// Upload file
+await minioClient.putObject('my-bucket', 'path/to/file.jpg', fileBuffer, fileBuffer.length, {
+  'Content-Type': 'image/jpeg',
+})
+
+// Download file
+const dataStream = await minioClient.getObject('my-bucket', 'path/to/file.jpg')
+const chunks: Buffer[] = []
+for await (const chunk of dataStream) {
+  chunks.push(chunk)
+}
+const fileContent = Buffer.concat(chunks)
+
+// List objects
+const objectsStream = minioClient.listObjects('my-bucket', 'prefix/', true)
+for await (const obj of objectsStream) {
+  console.log(obj.name, obj.size)
+}
+```
+
+### Advanced Features
+```typescript
+// Presigned URL (S3 SDK)
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+
+const command = new PutObjectCommand({
+  Bucket: 'my-bucket',
+  Key: 'uploads/file.jpg',
+  ContentType: 'image/jpeg',
+})
+
+const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 3600 })
+
+// Presigned URL (MinIO SDK)
+const url = await minioClient.presignedPutObject('my-bucket', 'uploads/file.jpg', 3600)
+
+// Bucket policies
+const policy = {
+  Version: '2012-10-17',
+  Statement: [
+    {
+      Effect: 'Allow',
+      Principal: { AWS: ['*'] },
+      Action: ['s3:GetObject'],
+      Resource: ['arn:aws:s3:::my-bucket/*'],
+    },
+  ],
+}
+
+await minioClient.setBucketPolicy('my-bucket', JSON.stringify(policy))
+```
+
+## Common Patterns
+
+### File Upload Handler
+```typescript
+async function uploadFile(file: Buffer, filename: string, userId: string) {
+  const key = `users/${userId}/${Date.now()}-${filename}`
+  
+  await s3Client.send(new PutObjectCommand({
+    Bucket: process.env.MINIO_BUCKET,
+    Key: key,
+    Body: file,
+    ContentType: getContentType(filename),
+    Metadata: {
+      userId,
+      originalName: filename,
+    },
+  }))
+  
+  return {
+    key,
+    url: `${process.env.MINIO_ENDPOINT}/${process.env.MINIO_BUCKET}/${key}`,
+  }
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use S3-compatible APIs for portability
+- Set appropriate content types
+- Use presigned URLs for client uploads
+- Implement proper error handling
+- Use bucket policies for access control
+- Enable versioning for important data
+- Monitor storage usage
+- Use lifecycle policies
+- Implement retry logic
+- Use TLS in production
+
+❌ **DON'T:**
+- Store sensitive data without encryption
+- Use default credentials in production
+- Hardcode endpoint URLs
+- Ignore error handling
+- Skip content-type validation
+- Ignore access policies
+- Skip monitoring
+- Use HTTP in production
+- Ignore storage limits
+- Store large files without chunking
+
+## Configuration
+
+### Environment Variables
+```bash
+MINIO_ENDPOINT=http://localhost:9000
+MINIO_ENDPOINT=https://minio.example.com
+MINIO_PORT=9000
+MINIO_USE_SSL=false
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+MINIO_BUCKET=my-bucket
+MINIO_REGION=us-east-1
+```
+
+### Docker Compose
+```yaml
+services:
+  minio:
+    image: minio/minio:latest
+    ports:
+      - "9000:9000"  # API
+      - "9001:9001"  # Console
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: securepassword
+    command: server /data --console-address ":9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+
+volumes:
+  minio_data:
+```
+
+<!-- MINIO:END -->
+