@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/services/ELASTICSEARCH.md

@@ -1,347 +0,0 @@
-<!-- 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

@@ -1,178 +0,0 @@
-<!-- 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 -->
-

package/templates/services/HELM.md

@@ -1,194 +0,0 @@
-<!-- HELM:START -->
-# Helm Instructions
-
-**CRITICAL**: Follow these Helm best practices for Kubernetes package management.
-
-## Chart Structure
-
-```
-charts/<name>/
-├── Chart.yaml          # Chart metadata (required)
-├── values.yaml         # Default values (required)
-├── templates/          # Kubernetes manifests
-│   ├── deployment.yaml
-│   ├── service.yaml
-│   ├── ingress.yaml
-│   ├── configmap.yaml
-│   ├── secret.yaml
-│   ├── hpa.yaml
-│   ├── _helpers.tpl    # Template helpers
-│   ├── NOTES.txt       # Post-install notes
-│   └── tests/
-│       └── test-connection.yaml
-├── charts/             # Chart dependencies
-└── .helmignore         # Files to exclude from packaging
-```
-
-## Chart.yaml Requirements
-
-```yaml
-apiVersion: v2
-name: my-app
-description: A Helm chart for my application
-type: application
-version: 1.0.0        # Chart version (bump on every change)
-appVersion: "1.0.0"   # Application version (keep in sync)
-maintainers:
-  - name: team-name
-    email: team@example.com
-dependencies:
-  - name: postgresql
-    version: "12.x.x"
-    repository: "https://charts.bitnami.com/bitnami"
-    condition: postgresql.enabled
-```
-
-## values.yaml Requirements
-
-- Document every value with a comment
-- Set sensible production defaults
-- Never hardcode image tags
-
-```yaml
-# -- Number of replicas
-replicaCount: 3
-
-image:
-  # -- Container image repository
-  repository: my-registry/my-app
-  # -- Image pull policy
-  pullPolicy: IfNotPresent
-  # -- Image tag (defaults to chart appVersion)
-  tag: ""
-
-# -- Resource requests and limits
-resources:
-  requests:
-    memory: "128Mi"
-    cpu: "100m"
-  limits:
-    memory: "512Mi"
-    cpu: "500m"
-
-# -- Enable/disable autoscaling
-autoscaling:
-  enabled: true
-  minReplicas: 2
-  maxReplicas: 10
-  targetCPUUtilizationPercentage: 80
-
-# -- Service configuration
-service:
-  type: ClusterIP
-  port: 80
-
-# -- Ingress configuration
-ingress:
-  enabled: false
-  className: ""
-  annotations: {}
-  hosts:
-    - host: my-app.example.com
-      paths:
-        - path: /
-          pathType: ImplementationSpecific
-```
-
-## Template Best Practices
-
-### _helpers.tpl
-Define reusable template fragments:
-```yaml
-{{- define "chart.fullname" -}}
-{{- if .Values.fullnameOverride }}
-{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
-{{- else }}
-{{- $name := default .Chart.Name .Values.nameOverride }}
-{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
-{{- end }}
-{{- end }}
-
-{{- define "chart.labels" -}}
-helm.sh/chart: {{ include "chart.chart" . }}
-app.kubernetes.io/name: {{ include "chart.name" . }}
-app.kubernetes.io/instance: {{ .Release.Name }}
-app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
-app.kubernetes.io/managed-by: {{ .Release.Service }}
-{{- end }}
-
-{{- define "chart.selectorLabels" -}}
-app.kubernetes.io/name: {{ include "chart.name" . }}
-app.kubernetes.io/instance: {{ .Release.Name }}
-{{- end }}
-```
-
-### Template Patterns
-- Use `{{ include "chart.fullname" . }}` for consistent naming
-- Always add labels: `{{ include "chart.labels" . | nindent 4 }}`
-- Use `{{ .Values.x | default "fallback" }}` for optional values
-- Use `{{- with .Values.x }}` blocks for conditional sections
-- Quote all string values: `{{ .Values.image.tag | quote }}`
-
-## Versioning
-
-- Bump `Chart.yaml` version on every change (semver: MAJOR.MINOR.PATCH)
-- Keep `appVersion` in sync with the application version
-- Use `helm dependency update` after changing dependencies
-- Tag releases in version control matching chart version
-
-## Linting and Validation
-
-Run these checks before every commit:
-```bash
-# Lint the chart
-helm lint charts/my-app/
-
-# Render templates locally
-helm template my-release charts/my-app/ --values values-dev.yaml
-
-# Validate rendered templates
-helm template my-release charts/my-app/ | kubeval --strict
-
-# Dry-run against cluster
-helm install my-release charts/my-app/ --dry-run --debug
-```
-
-## Common Patterns
-
-### Environment-Specific Values
-```bash
-# Development
-helm install my-app charts/my-app/ -f values-dev.yaml
-
-# Staging
-helm install my-app charts/my-app/ -f values-staging.yaml
-
-# Production
-helm install my-app charts/my-app/ -f values-prod.yaml
-```
-
-### Secrets Management
-```yaml
-# Use external-secrets or sealed-secrets
-# Never store plaintext secrets in values.yaml
-externalSecrets:
-  enabled: true
-  secretStore: aws-secrets-manager
-  data:
-    - secretKey: DATABASE_URL
-      remoteRef:
-        key: /myapp/database-url
-```
-
-## Best Practices
-
-- Use `helm create` to scaffold new charts with best-practice defaults
-- Include chart tests in `templates/tests/`
-- Document all values in `values.yaml` with comments
-- Use `.helmignore` to exclude development files from chart packages
-- Pin dependency versions (avoid `*` or floating ranges)
-- Use `helm diff` plugin to preview changes before upgrading
-- Store charts in a Helm repository (ChartMuseum, Harbor, OCI registry)
-- Run `helm lint` in CI/CD pipeline
-
-<!-- HELM:END -->