@hivehub/rulebook 2.1.0 → 3.1.0

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

@@ -0,0 +1,318 @@
+---
+name: "DynamoDB"
+description: "Use DynamoDB for serverless NoSQL database with automatic scaling, high performance, and pay-per-use pricing."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "database"]
+dependencies: []
+conflicts: []
+---
+<!-- DYNAMODB:START -->
+# AWS DynamoDB Instructions
+
+**CRITICAL**: Use DynamoDB for serverless NoSQL database with automatic scaling, high performance, and pay-per-use pricing.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @aws-sdk/client-dynamodb
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { DynamoDBDocumentClient, PutCommand, GetCommand, QueryCommand, ScanCommand } from '@aws-sdk/lib-dynamodb'
+
+const client = new DynamoDBClient({
+  region: process.env.AWS_REGION || 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
+  },
+})
+
+const docClient = DynamoDBDocumentClient.from(client)
+
+// Using AWS SDK v2
+import AWS from 'aws-sdk'
+
+const dynamodb = new AWS.DynamoDB.DocumentClient({
+  region: process.env.AWS_REGION || 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+})
+```
+
+### Basic Operations
+```typescript
+// Put item
+await docClient.send(new PutCommand({
+  TableName: 'Users',
+  Item: {
+    id: 'user-1',
+    email: 'john@example.com',
+    name: 'John Doe',
+    createdAt: new Date().toISOString(),
+  },
+}))
+
+// Get item
+const result = await docClient.send(new GetCommand({
+  TableName: 'Users',
+  Key: {
+    id: 'user-1',
+  },
+}))
+const user = result.Item
+
+// Update item
+await docClient.send(new UpdateCommand({
+  TableName: 'Users',
+  Key: { id: 'user-1' },
+  UpdateExpression: 'SET #name = :name, updatedAt = :updatedAt',
+  ExpressionAttributeNames: {
+    '#name': 'name',
+  },
+  ExpressionAttributeValues: {
+    ':name': 'Jane Doe',
+    ':updatedAt': new Date().toISOString(),
+  },
+}))
+
+// Delete item
+await docClient.send(new DeleteCommand({
+  TableName: 'Users',
+  Key: { id: 'user-1' },
+}))
+```
+
+### Query Operations
+```typescript
+// Query by partition key
+const result = await docClient.send(new QueryCommand({
+  TableName: 'Posts',
+  KeyConditionExpression: 'userId = :userId',
+  ExpressionAttributeValues: {
+    ':userId': 'user-1',
+  },
+  ScanIndexForward: false, // Sort descending
+  Limit: 10,
+}))
+
+// Query with GSI (Global Secondary Index)
+const result = await docClient.send(new QueryCommand({
+  TableName: 'Users',
+  IndexName: 'EmailIndex',
+  KeyConditionExpression: 'email = :email',
+  ExpressionAttributeValues: {
+    ':email': 'john@example.com',
+  },
+}))
+
+// Scan (use sparingly)
+const result = await docClient.send(new ScanCommand({
+  TableName: 'Users',
+  FilterExpression: '#status = :status',
+  ExpressionAttributeNames: {
+    '#status': 'status',
+  },
+  ExpressionAttributeValues: {
+    ':status': 'active',
+  },
+  Limit: 100,
+}))
+```
+
+### Advanced Features
+```typescript
+// Batch operations
+import { BatchWriteCommand } from '@aws-sdk/lib-dynamodb'
+
+await docClient.send(new BatchWriteCommand({
+  RequestItems: {
+    Users: [
+      {
+        PutRequest: {
+          Item: { id: 'user-1', name: 'User 1' },
+        },
+      },
+      {
+        PutRequest: {
+          Item: { id: 'user-2', name: 'User 2' },
+        },
+      },
+    ],
+  },
+}))
+
+// Transactions
+import { TransactWriteCommand } from '@aws-sdk/lib-dynamodb'
+
+await docClient.send(new TransactWriteCommand({
+  TransactItems: [
+    {
+      Put: {
+        TableName: 'Accounts',
+        Item: { userId: 'user-1', balance: 1000 },
+      },
+    },
+    {
+      Put: {
+        TableName: 'Transactions',
+        Item: { id: 'tx-1', userId: 'user-1', amount: 1000 },
+      },
+    },
+  ],
+}))
+
+// Conditional writes
+await docClient.send(new PutCommand({
+  TableName: 'Users',
+  Item: { id: 'user-1', email: 'john@example.com' },
+  ConditionExpression: 'attribute_not_exists(id)',
+}))
+```
+
+## Common Patterns
+
+### Single Table Design
+```typescript
+// Store different entity types in one table
+await docClient.send(new PutCommand({
+  TableName: 'AppData',
+  Item: {
+    PK: 'USER#user-1',
+    SK: 'METADATA',
+    EntityType: 'User',
+    email: 'john@example.com',
+    name: 'John Doe',
+  },
+}))
+
+await docClient.send(new PutCommand({
+  TableName: 'AppData',
+  Item: {
+    PK: 'USER#user-1',
+    SK: 'POST#post-1',
+    EntityType: 'Post',
+    title: 'My Post',
+    content: 'Content here',
+  },
+}))
+
+// Query all posts for a user
+const result = await docClient.send(new QueryCommand({
+  TableName: 'AppData',
+  KeyConditionExpression: 'PK = :pk AND begins_with(SK, :sk)',
+  ExpressionAttributeValues: {
+    ':pk': 'USER#user-1',
+    ':sk': 'POST#',
+  },
+}))
+```
+
+### Time-to-Live (TTL)
+```typescript
+// Items automatically deleted after TTL
+await docClient.send(new PutCommand({
+  TableName: 'Sessions',
+  Item: {
+    sessionId: 'session-1',
+    userId: 'user-1',
+    ttl: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+  },
+}))
+```
+
+## Best Practices
+
+✅ **DO:**
+- Design for access patterns
+- Use appropriate partition keys
+- Create GSIs for alternative access patterns
+- Use batch operations when possible
+- Implement exponential backoff for throttling
+- Use TTL for temporary data
+- Monitor provisioned capacity
+- Use transactions for atomic operations
+- Implement proper error handling
+- Use single table design when appropriate
+
+❌ **DON'T:**
+- Use Scan for frequent queries
+- Create too many GSIs (affects write performance)
+- Store large items (> 400KB)
+- Ignore throttling errors
+- Hardcode table names
+- Skip error handling
+- Use eventually consistent reads when strong consistency needed
+- Ignore capacity planning
+- Store sensitive data without encryption
+- Skip monitoring
+
+## Configuration
+
+### Environment Variables
+```bash
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+DYNAMODB_TABLE_PREFIX=myapp_
+```
+
+### IAM Policy
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:PutItem",
+        "dynamodb:GetItem",
+        "dynamodb:UpdateItem",
+        "dynamodb:DeleteItem",
+        "dynamodb:Query",
+        "dynamodb:Scan"
+      ],
+      "Resource": "arn:aws:dynamodb:*:*:table/myapp-*"
+    }
+  ]
+}
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use DynamoDB Local
+const localClient = new DynamoDBClient({
+  endpoint: 'http://localhost:8000',
+  region: 'local',
+  credentials: {
+    accessKeyId: 'local',
+    secretAccessKey: 'local',
+  },
+})
+
+// Clean up after tests
+afterEach(async () => {
+  // Delete test items or use separate test table
+})
+```
+
+### Health Checks
+```typescript
+async function checkDynamoDBHealth(): Promise<boolean> {
+  try {
+    await docClient.send(new GetCommand({
+      TableName: 'HealthCheck',
+      Key: { id: 'health' },
+    }))
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- DYNAMODB:END -->
+

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

@@ -0,0 +1,357 @@
+---
+name: "Elasticsearch"
+description: "Use Elasticsearch for full-text search, log aggregation, and real-time analytics with distributed architecture."
+version: "1.0.0"
+category: "services"
+author: "Rulebook"
+tags: ["services", "database"]
+dependencies: []
+conflicts: []
+---
+<!-- 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 -->
+