@hivehub/rulebook 2.1.0 → 3.1.0

package/templates/skills/services/memcached/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: "Memcached"
+description: "Use Memcached for simple, high-performance distributed caching with minimal overhead."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "caching"]
+dependencies: []
+conflicts: []
+---
+<!-- 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/skills/services/minio/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: "MinIO"
+description: "Use MinIO for S3-compatible object storage, self-hosted file storage, and development/testing with S3 APIs."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "storage"]
+dependencies: []
+conflicts: []
+---
+<!-- 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 -->
+