@hivehub/rulebook 1.2.0

package/templates/services/AZURE_BLOB.md

@@ -0,0 +1,184 @@
+<!-- AZURE_BLOB:START -->
+# Azure Blob Storage Instructions
+
+**CRITICAL**: Use Azure Blob Storage for object storage, file uploads, static assets, and backup storage in Azure cloud.
+
+## Core Features
+
+### Connection
+```typescript
+// Using @azure/storage-blob
+import { BlobServiceClient, StorageSharedKeyCredential } from '@azure/storage-blob'
+
+const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME || ''
+const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY || ''
+
+const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey)
+const blobServiceClient = new BlobServiceClient(
+  `https://${accountName}.blob.core.windows.net`,
+  sharedKeyCredential
+)
+
+const containerClient = blobServiceClient.getContainerClient(
+  process.env.AZURE_CONTAINER_NAME || 'mycontainer'
+)
+```
+
+### Basic Operations
+```typescript
+// Create container
+await containerClient.createIfNotExists({
+  access: 'blob', // 'blob', 'container', or 'private'
+})
+
+// Upload blob
+const blockBlobClient = containerClient.getBlockBlobClient('path/to/file.jpg')
+await blockBlobClient.upload(fileBuffer, fileBuffer.length, {
+  blobHTTPHeaders: {
+    blobContentType: 'image/jpeg',
+  },
+  metadata: {
+    userId: '123',
+    originalName: 'photo.jpg',
+  },
+})
+
+// Download blob
+const downloadResponse = await blockBlobClient.download()
+const fileContent = await streamToBuffer(downloadResponse.readableStreamBody)
+
+// Delete blob
+await blockBlobClient.delete()
+
+// List blobs
+for await (const blob of containerClient.listBlobsFlat()) {
+  console.log(blob.name, blob.properties.contentLength)
+}
+```
+
+### Advanced Features
+```typescript
+// Generate SAS URL
+import { generateBlobSASQueryParameters, BlobSASPermissions, StorageSharedKeyCredential } from '@azure/storage-blob'
+
+const sasToken = generateBlobSASQueryParameters(
+  {
+    containerName: 'mycontainer',
+    blobName: 'path/to/file.jpg',
+    permissions: BlobSASPermissions.parse('r'), // read
+    startsOn: new Date(),
+    expiresOn: new Date(new Date().valueOf() + 3600 * 1000), // 1 hour
+  },
+  sharedKeyCredential
+).toString()
+
+const sasUrl = `https://${accountName}.blob.core.windows.net/mycontainer/path/to/file.jpg?${sasToken}`
+
+// Copy blob
+const sourceBlobClient = containerClient.getBlockBlobClient('source/file.jpg')
+const destBlobClient = containerClient.getBlockBlobClient('dest/file.jpg')
+await destBlobClient.beginCopyFromURL(sourceBlobClient.url)
+
+// Set blob metadata
+await blockBlobClient.setMetadata({
+  category: 'profile',
+  uploadedBy: 'user-123',
+})
+
+// Get blob properties
+const properties = await blockBlobClient.getProperties()
+console.log(properties.contentType, properties.contentLength, properties.metadata)
+```
+
+## Common Patterns
+
+### File Upload Handler
+```typescript
+async function uploadFile(file: Buffer, filename: string, userId: string) {
+  const blobName = `users/${userId}/${Date.now()}-${filename}`
+  const blobClient = containerClient.getBlockBlobClient(blobName)
+  
+  await blobClient.upload(file, file.length, {
+    blobHTTPHeaders: {
+      blobContentType: getContentType(filename),
+    },
+    metadata: {
+      userId,
+      originalName: filename,
+      uploadedAt: new Date().toISOString(),
+    },
+  })
+  
+  return {
+    blobName,
+    url: blobClient.url,
+  }
+}
+```
+
+### Temporary Access URL
+```typescript
+async function generateTemporaryUrl(blobName: string, expiresInMinutes: number = 60) {
+  const blobClient = containerClient.getBlockBlobClient(blobName)
+  const sasToken = generateBlobSASQueryParameters(
+    {
+      containerName: containerClient.containerName,
+      blobName,
+      permissions: BlobSASPermissions.parse('r'),
+      expiresOn: new Date(Date.now() + expiresInMinutes * 60 * 1000),
+    },
+    sharedKeyCredential
+  ).toString()
+  
+  return `${blobClient.url}?${sasToken}`
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use appropriate access tiers (Hot, Cool, Archive)
+- Set blob metadata for organization
+- Use SAS tokens for temporary access
+- Implement proper error handling
+- Use appropriate content types
+- Enable soft delete for important data
+- Monitor storage usage and costs
+- Use lifecycle management policies
+- Implement retry logic
+- Use connection strings or managed identity
+
+❌ **DON'T:**
+- Store sensitive data without encryption
+- Use public access unnecessarily
+- Hardcode credentials
+- Ignore error handling
+- Skip content-type validation
+- Ignore lifecycle policies
+- Skip access logging
+- Use default access levels
+- Ignore cost optimization
+- Store large files without chunking
+
+## Configuration
+
+### Environment Variables
+```bash
+AZURE_STORAGE_ACCOUNT_NAME=myaccount
+AZURE_STORAGE_ACCOUNT_KEY=your-account-key
+AZURE_CONTAINER_NAME=mycontainer
+AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+```
+
+### Managed Identity (Recommended)
+```typescript
+import { DefaultAzureCredential } from '@azure/identity'
+
+const blobServiceClient = new BlobServiceClient(
+  `https://${accountName}.blob.core.windows.net`,
+  new DefaultAzureCredential()
+)
+```
+
+<!-- AZURE_BLOB:END -->
+

package/templates/services/CASSANDRA.md

@@ -0,0 +1,239 @@
+<!-- CASSANDRA:START -->
+# Apache Cassandra Database Instructions
+
+**CRITICAL**: Use Cassandra for distributed NoSQL database with high availability, linear scalability, and eventual consistency.
+
+## Core Features
+
+### Connection
+```typescript
+// Using cassandra-driver
+import { Client } from 'cassandra-driver'
+
+const client = new Client({
+  contactPoints: (process.env.CASSANDRA_HOSTS || 'localhost').split(','),
+  localDataCenter: process.env.CASSANDRA_DATACENTER || 'datacenter1',
+  keyspace: process.env.CASSANDRA_KEYSPACE || 'myapp',
+  credentials: {
+    username: process.env.CASSANDRA_USER || 'cassandra',
+    password: process.env.CASSANDRA_PASSWORD || 'cassandra',
+  },
+  queryOptions: {
+    consistency: 1, // ONE, QUORUM, ALL
+    prepare: true,
+  },
+})
+```
+
+### Basic Operations
+```typescript
+// Create keyspace
+await client.execute(`
+  CREATE KEYSPACE IF NOT EXISTS myapp
+  WITH REPLICATION = {
+    'class': 'SimpleStrategy',
+    'replication_factor': 1
+  }
+`)
+
+// Use keyspace
+await client.execute('USE myapp')
+
+// Create table
+await client.execute(`
+  CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY,
+    email TEXT,
+    name TEXT,
+    created_at TIMESTAMP
+  )
+`)
+
+// Create index
+await client.execute('CREATE INDEX IF NOT EXISTS ON users (email)')
+
+// Insert
+await client.execute(
+  'INSERT INTO users (id, email, name, created_at) VALUES (?, ?, ?, ?)',
+  [cassandra.types.Uuid.random(), 'john@example.com', 'John Doe', new Date()],
+  { prepare: true }
+)
+
+// Select
+const result = await client.execute(
+  'SELECT * FROM users WHERE id = ?',
+  [userId],
+  { prepare: true }
+)
+const user = result.first()
+
+// Update
+await client.execute(
+  'UPDATE users SET name = ? WHERE id = ?',
+  ['Jane Doe', userId],
+  { prepare: true }
+)
+
+// Delete
+await client.execute(
+  'DELETE FROM users WHERE id = ?',
+  [userId],
+  { prepare: true }
+)
+```
+
+### Advanced Features
+```typescript
+// Batch operations
+const queries = [
+  {
+    query: 'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+    params: [id1, 'user1@example.com', 'User 1'],
+  },
+  {
+    query: 'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+    params: [id2, 'user2@example.com', 'User 2'],
+  },
+]
+
+await client.batch(queries, { prepare: true })
+
+// Collections
+await client.execute(`
+  CREATE TABLE IF NOT EXISTS products (
+    id UUID PRIMARY KEY,
+    name TEXT,
+    tags SET<TEXT>,
+    metadata MAP<TEXT, TEXT>
+  )
+`)
+
+await client.execute(
+  'UPDATE products SET tags = tags + ? WHERE id = ?',
+  [['electronics', 'gadgets'], productId],
+  { prepare: true }
+)
+
+// Time-to-Live (TTL)
+await client.execute(
+  'INSERT INTO sessions (id, data) VALUES (?, ?) USING TTL 3600',
+  [sessionId, sessionData],
+  { prepare: true }
+)
+```
+
+## Common Patterns
+
+### Data Modeling
+```typescript
+// Design tables for query patterns
+// Query: Get users by email
+await client.execute(`
+  CREATE TABLE users_by_email (
+    email TEXT PRIMARY KEY,
+    id UUID,
+    name TEXT,
+    created_at TIMESTAMP
+  )
+`)
+
+// Query: Get posts by user and date
+await client.execute(`
+  CREATE TABLE posts_by_user (
+    user_id UUID,
+    created_at TIMESTAMP,
+    post_id UUID,
+    title TEXT,
+    content TEXT,
+    PRIMARY KEY (user_id, created_at, post_id)
+  ) WITH CLUSTERING ORDER BY (created_at DESC)
+`)
+```
+
+### Consistency Levels
+```typescript
+// Read with QUORUM consistency
+const result = await client.execute(
+  'SELECT * FROM users WHERE id = ?',
+  [userId],
+  {
+    consistency: 2, // QUORUM
+    prepare: true,
+  }
+)
+
+// Write with ALL consistency (strongest)
+await client.execute(
+  'INSERT INTO users (id, email, name) VALUES (?, ?, ?)',
+  [id, email, name],
+  {
+    consistency: 3, // ALL
+    prepare: true,
+  }
+)
+```
+
+## Best Practices
+
+✅ **DO:**
+- Design tables for query patterns (denormalize)
+- Use appropriate partition keys
+- Use clustering keys for sorting
+- Create secondary indexes sparingly
+- Use prepared statements
+- Set appropriate consistency levels
+- Use TTL for time-based data
+- Monitor cluster health
+- Use batch operations carefully
+- Implement retry logic
+
+❌ **DON'T:**
+- Use secondary indexes on high-cardinality columns
+- Create too many secondary indexes
+- Use ALL consistency for all operations
+- Store large values (> 1MB)
+- Skip error handling
+- Ignore cluster topology
+- Hardcode contact points
+- Use SELECT * in production
+- Ignore data modeling best practices
+- Skip monitoring
+
+## Configuration
+
+### Environment Variables
+```bash
+CASSANDRA_HOSTS=localhost
+CASSANDRA_HOSTS=node1:9042,node2:9042,node3:9042
+CASSANDRA_DATACENTER=datacenter1
+CASSANDRA_KEYSPACE=myapp
+CASSANDRA_USER=cassandra
+CASSANDRA_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  cassandra:
+    image: cassandra:4
+    ports:
+      - "9042:9042"
+    environment:
+      CASSANDRA_CLUSTER_NAME: my-cluster
+      CASSANDRA_DC: datacenter1
+      CASSANDRA_RACK: rack1
+      CASSANDRA_ENDPOINT_SNITCH: GossipingPropertyFileSnitch
+    volumes:
+      - cassandra_data:/var/lib/cassandra
+    healthcheck:
+      test: ["CMD-SHELL", "nodetool status | grep -E '^UN' || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+
+volumes:
+  cassandra_data:
+```
+
+<!-- CASSANDRA:END -->
+

package/templates/services/DYNAMODB.md

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