@hivehub/rulebook 1.2.0

package/templates/services/REDIS.md

@@ -0,0 +1,292 @@
+<!-- REDIS:START -->
+# Redis Cache Instructions
+
+**CRITICAL**: Use Redis for high-performance caching, session storage, pub/sub messaging, and real-time features.
+
+## Core Features
+
+### Connection
+```typescript
+// Using redis (Node.js)
+import { createClient } from 'redis'
+
+const client = createClient({
+  url: process.env.REDIS_URL || 'redis://localhost:6379',
+  socket: {
+    reconnectStrategy: (retries) => {
+      if (retries > 10) {
+        return new Error('Too many reconnection attempts')
+      }
+      return Math.min(retries * 100, 3000)
+    },
+  },
+})
+
+await client.connect()
+
+// Using ioredis
+import Redis from 'ioredis'
+
+const redis = new Redis({
+  host: process.env.REDIS_HOST || 'localhost',
+  port: parseInt(process.env.REDIS_PORT || '6379'),
+  password: process.env.REDIS_PASSWORD,
+  retryStrategy: (times) => Math.min(times * 50, 2000),
+  maxRetriesPerRequest: 3,
+})
+```
+
+### Basic Operations
+```typescript
+// String operations
+await client.set('user:1', JSON.stringify({ name: 'John', email: 'john@example.com' }))
+await client.set('user:1', 'value', { EX: 3600 }) // Expire in 1 hour
+const user = await client.get('user:1')
+await client.del('user:1')
+
+// Multiple operations
+await client.mSet({
+  'key1': 'value1',
+  'key2': 'value2',
+})
+const values = await client.mGet(['key1', 'key2'])
+
+// Increment/Decrement
+await client.incr('counter')
+await client.incrBy('counter', 5)
+await client.decr('counter')
+```
+
+### Data Structures
+```typescript
+// Lists
+await client.lPush('tasks', 'task1', 'task2')
+await client.rPush('tasks', 'task3')
+const task = await client.lPop('tasks')
+const tasks = await client.lRange('tasks', 0, -1)
+
+// Sets
+await client.sAdd('tags', 'javascript', 'typescript', 'nodejs')
+const tags = await client.sMembers('tags')
+const exists = await client.sIsMember('tags', 'javascript')
+await client.sRem('tags', 'javascript')
+
+// Sorted Sets
+await client.zAdd('leaderboard', {
+  score: 100,
+  value: 'player1',
+})
+const topPlayers = await client.zRange('leaderboard', 0, 9, { REV: true })
+
+// Hashes
+await client.hSet('user:1', {
+  name: 'John',
+  email: 'john@example.com',
+  age: '30',
+})
+const user = await client.hGetAll('user:1')
+await client.hIncrBy('user:1', 'age', 1)
+```
+
+### Advanced Features
+```typescript
+// Pub/Sub
+const publisher = client.duplicate()
+await publisher.connect()
+
+const subscriber = client.duplicate()
+await subscriber.connect()
+
+await subscriber.subscribe('notifications', (message) => {
+  console.log('Received:', message)
+})
+
+await publisher.publish('notifications', JSON.stringify({ type: 'alert', message: 'Hello' }))
+
+// Streams
+await client.xAdd('events', '*', {
+  type: 'user_login',
+  userId: '123',
+  timestamp: Date.now().toString(),
+})
+
+const events = await client.xRead({
+  key: 'events',
+  id: '0',
+}, {
+  COUNT: 10,
+  BLOCK: 1000,
+})
+
+// Transactions
+const multi = client.multi()
+multi.set('key1', 'value1')
+multi.set('key2', 'value2')
+multi.incr('counter')
+await multi.exec()
+```
+
+## Common Patterns
+
+### Caching
+```typescript
+async function getCachedUser(userId: string) {
+  const cached = await client.get(`user:${userId}`)
+  if (cached) {
+    return JSON.parse(cached)
+  }
+  
+  const user = await fetchUserFromDatabase(userId)
+  await client.set(`user:${userId}`, JSON.stringify(user), { EX: 3600 })
+  return user
+}
+
+// Cache with tags (for invalidation)
+async function cacheWithTags(key: string, value: any, tags: string[], ttl: number) {
+  await client.set(key, JSON.stringify(value), { EX: ttl })
+  for (const tag of tags) {
+    await client.sAdd(`tag:${tag}`, key)
+  }
+}
+
+async function invalidateByTag(tag: string) {
+  const keys = await client.sMembers(`tag:${tag}`)
+  if (keys.length > 0) {
+    await client.del(...keys)
+  }
+  await client.del(`tag:${tag}`)
+}
+```
+
+### Rate Limiting
+```typescript
+async function checkRateLimit(userId: string, limit: number, window: number): Promise<boolean> {
+  const key = `ratelimit:${userId}`
+  const current = await client.incr(key)
+  
+  if (current === 1) {
+    await client.expire(key, window)
+  }
+  
+  return current <= limit
+}
+```
+
+### Session Storage
+```typescript
+async function setSession(sessionId: string, data: any, ttl: number) {
+  await client.set(`session:${sessionId}`, JSON.stringify(data), { EX: ttl })
+}
+
+async function getSession(sessionId: string) {
+  const data = await client.get(`session:${sessionId}`)
+  return data ? JSON.parse(data) : null
+}
+
+async function deleteSession(sessionId: string) {
+  await client.del(`session:${sessionId}`)
+}
+```
+
+### Distributed Locks
+```typescript
+async function acquireLock(key: string, ttl: number): Promise<boolean> {
+  const result = await client.set(key, 'locked', {
+    EX: ttl,
+    NX: true, // Only set if not exists
+  })
+  return result === 'OK'
+}
+
+async function releaseLock(key: string) {
+  await client.del(key)
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling
+- Set appropriate TTL for cached data
+- Use pipelining for multiple operations
+- Use transactions (MULTI/EXEC) for atomic operations
+- Monitor memory usage
+- Use appropriate data structures (hash for objects, set for unique values)
+- Implement cache invalidation strategies
+- Use Redis Cluster for high availability
+- Enable persistence (RDB or AOF) for production
+- Use Redis Sentinel for failover
+
+❌ **DON'T:**
+- Store large values (> 100KB, use compression or external storage)
+- Use Redis as primary database (it's a cache)
+- Skip error handling
+- Ignore memory limits
+- Hardcode connection strings
+- Use KEYS command in production (use SCAN instead)
+- Store sensitive data without encryption
+- Skip connection retry logic
+- Ignore eviction policies
+- Use blocking operations without timeouts
+
+## Configuration
+
+### Environment Variables
+```bash
+REDIS_URL=redis://localhost:6379
+REDIS_URL=redis://:password@host:6379
+REDIS_URL=rediss://host:6380  # SSL
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --requirepass securepassword --appendonly yes
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  redis_data:
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test Redis instance
+const testClient = createClient({
+  url: 'redis://localhost:6380', // Different port for tests
+})
+
+// Clean up after tests
+afterEach(async () => {
+  await testClient.flushDb()
+})
+```
+
+### Health Checks
+```typescript
+async function checkRedisHealth(): Promise<boolean> {
+  try {
+    await client.ping()
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- REDIS:END -->
+

package/templates/services/S3.md

@@ -0,0 +1,298 @@
+<!-- S3:START -->
+# AWS S3 Storage Instructions
+
+**CRITICAL**: Use AWS S3 for object storage, file uploads, static assets, and backup storage with high availability.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @aws-sdk/client-s3
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3'
+
+const s3Client = new S3Client({
+  region: process.env.AWS_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+  },
+})
+
+// Using AWS SDK v2
+import AWS from 'aws-sdk'
+
+const s3 = new AWS.S3({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  region: process.env.AWS_REGION || 'us-east-1',
+})
+```
+
+### Basic Operations
+```typescript
+// Upload file
+const uploadParams = {
+  Bucket: process.env.S3_BUCKET || 'my-bucket',
+  Key: 'path/to/file.jpg',
+  Body: fileBuffer,
+  ContentType: 'image/jpeg',
+  ACL: 'private', // or 'public-read'
+}
+
+await s3Client.send(new PutObjectCommand(uploadParams))
+
+// Upload with metadata
+await s3Client.send(new PutObjectCommand({
+  ...uploadParams,
+  Metadata: {
+    userId: '123',
+    originalName: 'photo.jpg',
+  },
+  TagSet: [
+    { Key: 'category', Value: 'profile' },
+  ],
+}))
+
+// Get file
+const getParams = {
+  Bucket: process.env.S3_BUCKET,
+  Key: 'path/to/file.jpg',
+}
+
+const response = await s3Client.send(new GetObjectCommand(getParams))
+const fileContent = await response.Body?.transformToByteArray()
+
+// Delete file
+await s3Client.send(new DeleteObjectCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'path/to/file.jpg',
+}))
+```
+
+### Advanced Features
+```typescript
+// Presigned URL for upload
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+
+const command = new PutObjectCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'uploads/file.jpg',
+  ContentType: 'image/jpeg',
+})
+
+const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 3600 })
+
+// Presigned URL for download
+const getCommand = new GetObjectCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'path/to/file.jpg',
+})
+
+const downloadUrl = await getSignedUrl(s3Client, getCommand, { expiresIn: 3600 })
+
+// Multipart upload (for large files)
+import { CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3'
+
+const createCommand = new CreateMultipartUploadCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'large-file.zip',
+  ContentType: 'application/zip',
+})
+
+const { UploadId } = await s3Client.send(createCommand)
+
+// Upload parts
+const part1 = await s3Client.send(new UploadPartCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'large-file.zip',
+  PartNumber: 1,
+  UploadId,
+  Body: part1Buffer,
+}))
+
+// Complete upload
+await s3Client.send(new CompleteMultipartUploadCommand({
+  Bucket: process.env.S3_BUCKET,
+  Key: 'large-file.zip',
+  UploadId,
+  MultipartUpload: {
+    Parts: [
+      { PartNumber: 1, ETag: part1.ETag },
+    ],
+  },
+}))
+
+// List objects
+import { ListObjectsV2Command } from '@aws-sdk/client-s3'
+
+const listCommand = new ListObjectsV2Command({
+  Bucket: process.env.S3_BUCKET,
+  Prefix: 'uploads/',
+  MaxKeys: 100,
+})
+
+const { Contents } = await s3Client.send(listCommand)
+```
+
+## 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.S3_BUCKET,
+    Key: key,
+    Body: file,
+    ContentType: getContentType(filename),
+    Metadata: {
+      userId,
+      originalName: filename,
+      uploadedAt: new Date().toISOString(),
+    },
+  }))
+  
+  return {
+    key,
+    url: `https://${process.env.S3_BUCKET}.s3.${process.env.AWS_REGION}.amazonaws.com/${key}`,
+  }
+}
+```
+
+### Temporary File Access
+```typescript
+async function generateTemporaryDownloadUrl(key: string, expiresIn: number = 3600) {
+  const command = new GetObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: key,
+  })
+  
+  return await getSignedUrl(s3Client, command, { expiresIn })
+}
+```
+
+### File Cleanup
+```typescript
+async function deleteFilesByPrefix(prefix: string) {
+  const listCommand = new ListObjectsV2Command({
+    Bucket: process.env.S3_BUCKET,
+    Prefix: prefix,
+  })
+  
+  let continuationToken: string | undefined
+  
+  do {
+    const response = await s3Client.send({
+      ...listCommand,
+      ContinuationToken: continuationToken,
+    })
+    
+    if (response.Contents) {
+      for (const object of response.Contents) {
+        if (object.Key) {
+          await s3Client.send(new DeleteObjectCommand({
+            Bucket: process.env.S3_BUCKET,
+            Key: object.Key,
+          }))
+        }
+      }
+    }
+    
+    continuationToken = response.NextContinuationToken
+  } while (continuationToken)
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use presigned URLs for client uploads
+- Set appropriate Content-Type headers
+- Use versioning for important files
+- Implement lifecycle policies for cleanup
+- Use multipart upload for files > 5MB
+- Enable encryption (SSE-S3 or SSE-KMS)
+- Use appropriate storage classes (Standard, IA, Glacier)
+- Implement proper error handling
+- Use bucket policies for access control
+- Monitor bucket usage and costs
+
+❌ **DON'T:**
+- Store sensitive data without encryption
+- Use public-read ACL unnecessarily
+- Hardcode credentials
+- Ignore error handling
+- Skip content-type validation
+- Store large files without multipart upload
+- Ignore lifecycle policies
+- Skip access logging
+- Use default bucket policies
+- Ignore cost optimization
+
+## Configuration
+
+### Environment Variables
+```bash
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+S3_BUCKET=my-bucket
+```
+
+### IAM Policy
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject",
+        "s3:GetObject",
+        "s3:DeleteObject"
+      ],
+      "Resource": "arn:aws:s3:::my-bucket/*"
+    }
+  ]
+}
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test bucket or LocalStack
+const testS3Client = new S3Client({
+  endpoint: 'http://localhost:4566', // LocalStack
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: 'test',
+    secretAccessKey: 'test',
+  },
+  forcePathStyle: true,
+})
+
+// Clean up after tests
+afterEach(async () => {
+  // Delete test files
+})
+```
+
+### Health Checks
+```typescript
+async function checkS3Health(): Promise<boolean> {
+  try {
+    await s3Client.send(new ListObjectsV2Command({
+      Bucket: process.env.S3_BUCKET,
+      MaxKeys: 1,
+    }))
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- S3:END -->
+