@hivehub/rulebook 1.2.0

package/templates/services/ELASTICSEARCH.md

@@ -0,0 +1,347 @@
+<!-- ELASTICSEARCH:START -->
+# Elasticsearch Search Instructions
+
+**CRITICAL**: Use Elasticsearch for full-text search, log aggregation, and real-time analytics with distributed architecture.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @elastic/elasticsearch
+import { Client } from '@elastic/elasticsearch'
+
+const client = new Client({
+  node: process.env.ELASTICSEARCH_URL || 'http://localhost:9200',
+  auth: {
+    username: process.env.ELASTICSEARCH_USER || 'elastic',
+    password: process.env.ELASTICSEARCH_PASSWORD || '',
+  },
+  maxRetries: 5,
+  requestTimeout: 60000,
+  sniffOnStart: true,
+  sniffInterval: 30000,
+})
+```
+
+### Index Operations
+```typescript
+// Create index
+await client.indices.create({
+  index: 'users',
+  body: {
+    mappings: {
+      properties: {
+        name: { type: 'text' },
+        email: { type: 'keyword' },
+        age: { type: 'integer' },
+        createdAt: { type: 'date' },
+      },
+    },
+    settings: {
+      number_of_shards: 1,
+      number_of_replicas: 1,
+    },
+  },
+})
+
+// Delete index
+await client.indices.delete({ index: 'users' })
+
+// Check if index exists
+const exists = await client.indices.exists({ index: 'users' })
+```
+
+### Document Operations
+```typescript
+// Index document
+await client.index({
+  index: 'users',
+  id: '1',
+  body: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30,
+    createdAt: new Date(),
+  },
+})
+
+// Get document
+const result = await client.get({
+  index: 'users',
+  id: '1',
+})
+
+// Update document
+await client.update({
+  index: 'users',
+  id: '1',
+  body: {
+    doc: {
+      age: 31,
+    },
+  },
+})
+
+// Delete document
+await client.delete({
+  index: 'users',
+  id: '1',
+})
+
+// Bulk operations
+await client.bulk({
+  body: [
+    { index: { _index: 'users', _id: '1' } },
+    { name: 'User 1', email: 'user1@example.com' },
+    { index: { _index: 'users', _id: '2' } },
+    { name: 'User 2', email: 'user2@example.com' },
+  ],
+})
+```
+
+### Search Operations
+```typescript
+// Simple search
+const result = await client.search({
+  index: 'users',
+  body: {
+    query: {
+      match: {
+        name: 'John',
+      },
+    },
+  },
+})
+
+// Multi-match search
+const result = await client.search({
+  index: 'users',
+  body: {
+    query: {
+      multi_match: {
+        query: 'search term',
+        fields: ['name^2', 'email'], // name has 2x boost
+      },
+    },
+  },
+})
+
+// Bool query (AND/OR/NOT)
+const result = await client.search({
+  index: 'users',
+  body: {
+    query: {
+      bool: {
+        must: [
+          { match: { name: 'John' } },
+          { range: { age: { gte: 18, lte: 65 } } },
+        ],
+        must_not: [
+          { term: { status: 'inactive' } },
+        ],
+        should: [
+          { match: { tags: 'premium' } },
+        ],
+        minimum_should_match: 1,
+      },
+    },
+  },
+})
+
+// Aggregations
+const result = await client.search({
+  index: 'users',
+  body: {
+    aggs: {
+      age_groups: {
+        range: {
+          field: 'age',
+          ranges: [
+            { to: 25 },
+            { from: 25, to: 50 },
+            { from: 50 },
+          ],
+        },
+      },
+      avg_age: {
+        avg: { field: 'age' },
+      },
+    },
+  },
+})
+```
+
+## Common Patterns
+
+### Full-Text Search
+```typescript
+async function searchUsers(query: string, filters?: any) {
+  const must: any[] = [
+    {
+      multi_match: {
+        query,
+        fields: ['name^2', 'email'],
+        fuzziness: 'AUTO',
+      },
+    },
+  ]
+  
+  if (filters) {
+    if (filters.age) {
+      must.push({ range: { age: filters.age } })
+    }
+    if (filters.status) {
+      must.push({ term: { status: filters.status } })
+    }
+  }
+  
+  const result = await client.search({
+    index: 'users',
+    body: {
+      query: {
+        bool: {
+          must,
+        },
+      },
+      highlight: {
+        fields: {
+          name: {},
+          email: {},
+        },
+      },
+    },
+  })
+  
+  return result.body.hits.hits.map(hit => ({
+    ...hit._source,
+    score: hit._score,
+    highlights: hit.highlight,
+  }))
+}
+```
+
+### Auto-complete
+```typescript
+// Create index with completion suggester
+await client.indices.create({
+  index: 'suggestions',
+  body: {
+    mappings: {
+      properties: {
+        name: {
+          type: 'text',
+          fields: {
+            suggest: {
+              type: 'completion',
+            },
+          },
+        },
+      },
+    },
+  },
+})
+
+// Search with suggestions
+const result = await client.search({
+  index: 'suggestions',
+  body: {
+    suggest: {
+      name_suggest: {
+        prefix: 'joh',
+        completion: {
+          field: 'name.suggest',
+        },
+      },
+    },
+  },
+})
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use appropriate field types (text vs keyword)
+- Create indexes with proper mappings
+- Use bulk API for multiple operations
+- Implement proper error handling
+- Use aliases for zero-downtime reindexing
+- Monitor cluster health
+- Use appropriate shard and replica counts
+- Implement search result pagination
+- Use filters for exact matches (faster than queries)
+- Enable slow query logging
+
+❌ **DON'T:**
+- Store large binary data (use external storage)
+- Use too many shards (1 per 10-50GB)
+- Skip mapping definitions
+- Ignore cluster health
+- Hardcode connection strings
+- Use wildcard queries in production
+- Skip error handling
+- Ignore query performance
+- Store sensitive data without encryption
+- Use default refresh interval for real-time needs
+
+## Configuration
+
+### Environment Variables
+```bash
+ELASTICSEARCH_URL=http://localhost:9200
+ELASTICSEARCH_USER=elastic
+ELASTICSEARCH_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  elasticsearch:
+    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0
+    environment:
+      - discovery.type=single-node
+      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
+      - xpack.security.enabled=false
+    ports:
+      - "9200:9200"
+    volumes:
+      - elasticsearch_data:/usr/share/elasticsearch/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:9200/_cluster/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+volumes:
+  elasticsearch_data:
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test index
+const testIndex = 'test_users'
+
+beforeEach(async () => {
+  await client.indices.create({ index: testIndex })
+})
+
+afterEach(async () => {
+  await client.indices.delete({ index: testIndex })
+})
+```
+
+### Health Checks
+```typescript
+async function checkElasticsearchHealth(): Promise<boolean> {
+  try {
+    const response = await client.cluster.health()
+    return response.body.status !== 'red'
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- ELASTICSEARCH:END -->
+

package/templates/services/GCS.md

@@ -0,0 +1,178 @@
+<!-- GCS:START -->
+# Google Cloud Storage Instructions
+
+**CRITICAL**: Use Google Cloud Storage for object storage, file uploads, static assets, and backup storage in GCP.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @google-cloud/storage
+import { Storage } from '@google-cloud/storage'
+
+const storage = new Storage({
+  projectId: process.env.GCP_PROJECT_ID,
+  keyFilename: process.env.GCP_KEY_FILE, // Path to service account key
+  // Or use credentials object
+  credentials: {
+    client_email: process.env.GCP_CLIENT_EMAIL,
+    private_key: process.env.GCP_PRIVATE_KEY?.replace(/\\n/g, '\n'),
+  },
+})
+
+const bucket = storage.bucket(process.env.GCS_BUCKET_NAME || 'my-bucket')
+```
+
+### Basic Operations
+```typescript
+// Upload file
+const file = bucket.file('path/to/file.jpg')
+await file.save(fileBuffer, {
+  metadata: {
+    contentType: 'image/jpeg',
+    metadata: {
+      userId: '123',
+      originalName: 'photo.jpg',
+    },
+  },
+})
+
+// Download file
+const [fileContent] = await file.download()
+
+// Delete file
+await file.delete()
+
+// List files
+const [files] = await bucket.getFiles({
+  prefix: 'uploads/',
+  maxResults: 100,
+})
+```
+
+### Advanced Features
+```typescript
+// Generate signed URL
+const [url] = await file.getSignedUrl({
+  action: 'read',
+  expires: Date.now() + 3600 * 1000, // 1 hour
+})
+
+// Generate signed URL for upload
+const [uploadUrl] = await file.getSignedUrl({
+  action: 'write',
+  expires: Date.now() + 3600 * 1000,
+  contentType: 'image/jpeg',
+})
+
+// Copy file
+const sourceFile = bucket.file('source/file.jpg')
+const destFile = bucket.file('dest/file.jpg')
+await sourceFile.copy(destFile)
+
+// Set metadata
+await file.setMetadata({
+  metadata: {
+    category: 'profile',
+    uploadedBy: 'user-123',
+  },
+})
+
+// Get metadata
+const [metadata] = await file.getMetadata()
+console.log(metadata.contentType, metadata.size, metadata.metadata)
+```
+
+## Common Patterns
+
+### File Upload Handler
+```typescript
+async function uploadFile(file: Buffer, filename: string, userId: string) {
+  const filePath = `users/${userId}/${Date.now()}-${filename}`
+  const file = bucket.file(filePath)
+  
+  await file.save(file, {
+    metadata: {
+      contentType: getContentType(filename),
+      metadata: {
+        userId,
+        originalName: filename,
+        uploadedAt: new Date().toISOString(),
+      },
+    },
+  })
+  
+  await file.makePublic() // Or use signed URLs
+  
+  return {
+    filePath,
+    publicUrl: file.publicUrl(),
+  }
+}
+```
+
+### Temporary Access URL
+```typescript
+async function generateTemporaryUrl(filePath: string, expiresInMinutes: number = 60) {
+  const file = bucket.file(filePath)
+  const [url] = await file.getSignedUrl({
+    action: 'read',
+    expires: Date.now() + expiresInMinutes * 60 * 1000,
+  })
+  return url
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use appropriate storage classes (Standard, Nearline, Coldline, Archive)
+- Set blob metadata for organization
+- Use signed URLs for temporary access
+- Implement proper error handling
+- Use appropriate content types
+- Enable versioning for important data
+- Monitor storage usage and costs
+- Use lifecycle management policies
+- Implement retry logic
+- Use service account credentials
+
+❌ **DON'T:**
+- Store sensitive data without encryption
+- Make files public unnecessarily
+- Hardcode credentials
+- Ignore error handling
+- Skip content-type validation
+- Ignore lifecycle policies
+- Skip access logging
+- Use default permissions
+- Ignore cost optimization
+- Store large files without chunking
+
+## Configuration
+
+### Environment Variables
+```bash
+GCP_PROJECT_ID=my-project
+GCP_KEY_FILE=/path/to/service-account-key.json
+GCP_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
+GCP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
+GCS_BUCKET_NAME=my-bucket
+```
+
+### Service Account Key
+```json
+{
+  "type": "service_account",
+  "project_id": "my-project",
+  "private_key_id": "...",
+  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
+  "client_email": "service-account@project.iam.gserviceaccount.com",
+  "client_id": "...",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token"
+}
+```
+
+<!-- GCS:END -->
+