@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/services/DOCKER.md

@@ -1,124 +0,0 @@
-<!-- DOCKER:START -->
-# Docker Instructions
-
-**CRITICAL**: Follow these Docker best practices for all container builds.
-
-## Build Patterns
-
-### Multi-Stage Builds
-Use multi-stage builds to minimize final image size and separate build-time dependencies from runtime:
-
-```dockerfile
-FROM node:20-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-FROM node:20-alpine AS runtime
-RUN adduser -D appuser
-USER appuser
-WORKDIR /app
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-HEALTHCHECK --interval=30s --timeout=3s CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
-CMD ["node", "dist/index.js"]
-```
-
-### Base Image Selection
-- Pin base image versions: `node:20-alpine` not `node:latest`
-- Prefer `-alpine` or `-slim` variants for smaller images
-- Use official images from Docker Hub verified publishers
-
-## Security Requirements
-
-### Non-Root User
-ALL containers MUST run as a non-root user:
-```dockerfile
-RUN adduser -D appuser
-USER appuser
-```
-
-### Secrets
-- NEVER copy secrets (`.env`, credentials, keys) into image layers
-- Use Docker secrets or runtime environment variables instead
-- Scan images with `docker scout cves` or `trivy image` before pushing
-- Add `--no-cache` to package install commands to reduce attack surface
-
-### Image Scanning
-```bash
-# Docker Scout (built-in)
-docker scout cves <image>
-
-# Trivy
-trivy image <image>
-```
-
-## Required Instructions
-
-### HEALTHCHECK
-ALL production images MUST include a HEALTHCHECK:
-```dockerfile
-HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
-  CMD curl -f http://localhost:3000/health || exit 1
-```
-
-### .dockerignore Requirements
-Every Docker project MUST have a `.dockerignore` file containing at minimum:
-```
-.git
-node_modules
-dist
-coverage
-*.log
-.env*
-.DS_Store
-*.md
-.vscode
-.idea
-```
-
-## Common Patterns
-
-### Layer Caching
-Order Dockerfile instructions from least-changing to most-changing:
-```dockerfile
-# 1. Base image (rarely changes)
-FROM node:20-alpine
-
-# 2. System dependencies (changes rarely)
-RUN apk add --no-cache curl
-
-# 3. Package files (changes when deps change)
-COPY package*.json ./
-RUN npm ci --only=production
-
-# 4. Application code (changes frequently)
-COPY . .
-```
-
-### Production Optimization
-```dockerfile
-# Use npm ci for deterministic installs
-RUN npm ci --only=production
-
-# Remove unnecessary files
-RUN rm -rf /tmp/* /var/cache/apk/*
-
-# Set NODE_ENV
-ENV NODE_ENV=production
-```
-
-## Best Practices
-
-- Use `.dockerignore` to exclude unnecessary files from build context
-- One process per container (do not run multiple services in one container)
-- Use `COPY` over `ADD` unless extracting archives
-- Combine RUN commands to reduce layers: `RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*`
-- Set explicit `WORKDIR` instead of `RUN cd`
-- Use `EXPOSE` to document listening ports
-- Tag images with semantic versions, not just `latest`
-
-<!-- DOCKER:END -->

package/templates/services/DOCKER_COMPOSE.md

@@ -1,168 +0,0 @@
-<!-- DOCKER_COMPOSE:START -->
-# Docker Compose Instructions
-
-**CRITICAL**: Follow these Docker Compose best practices for local development and multi-container orchestration.
-
-## Version and Structure
-
-### File Organization
-- Use `docker-compose.yml` for base configuration
-- Use `docker-compose.override.yml` for local development overrides
-- Use `docker-compose.prod.yml` for production-specific settings
-- Do NOT commit secrets in `docker-compose.yml` — use `.env` files
-
-### Compose File
-```yaml
-services:
-  app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: runtime
-    env_file: [.env]
-    ports:
-      - "3000:3000"
-    depends_on:
-      db:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 3s
-      retries: 3
-      start_period: 10s
-    deploy:
-      resources:
-        limits:
-          memory: 512M
-          cpus: "0.5"
-    restart: unless-stopped
-```
-
-## Required Fields Per Service
-
-### Health Checks
-ALL services MUST define a healthcheck:
-```yaml
-healthcheck:
-  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
-  interval: 30s
-  timeout: 3s
-  retries: 3
-```
-
-### Resource Limits
-ALL services SHOULD define resource limits for production-like environments:
-```yaml
-deploy:
-  resources:
-    limits:
-      memory: 512M
-      cpus: "0.5"
-    reservations:
-      memory: 128M
-      cpus: "0.25"
-```
-
-### Restart Policy
-```yaml
-restart: unless-stopped
-```
-
-### Named Volumes
-Use named volumes (not bind mounts) for persistent data:
-```yaml
-volumes:
-  postgres_data:
-  redis_data:
-
-services:
-  db:
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-```
-
-## Environment Variables
-
-### Configuration
-- Use `.env` file: `env_file: [.env]`
-- Never hardcode credentials in docker-compose.yml
-- Document all required environment variables in README or `.env.example`
-
-### .env.example Pattern
-```bash
-# Database
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=myapp
-DB_USER=myuser
-DB_PASSWORD=changeme
-
-# Redis
-REDIS_URL=redis://localhost:6379
-
-# Application
-NODE_ENV=development
-PORT=3000
-```
-
-## Networking
-
-### Service Communication
-- Services on the same network communicate by service name
-- Use explicit networks for isolation:
-```yaml
-networks:
-  frontend:
-  backend:
-
-services:
-  app:
-    networks: [frontend, backend]
-  db:
-    networks: [backend]
-```
-
-## Common Patterns
-
-### Development Setup
-```yaml
-services:
-  app:
-    build: .
-    volumes:
-      - .:/app
-      - /app/node_modules
-    environment:
-      - NODE_ENV=development
-    command: npm run dev
-```
-
-### Database with Init Scripts
-```yaml
-services:
-  db:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: myapp
-      POSTGRES_USER: myuser
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U myuser"]
-      interval: 10s
-      retries: 5
-```
-
-## Best Practices
-
-- Use `depends_on` with `condition: service_healthy` for startup ordering
-- Pin image versions (e.g., `postgres:16-alpine`, not `postgres:latest`)
-- Keep compose files DRY with YAML anchors or extension fields (`x-common`)
-- Use `docker compose up --build` to rebuild images after code changes
-- Run `docker compose down -v` to clean up volumes during development
-- Separate concerns: one service per container
-
-<!-- DOCKER_COMPOSE:END -->

package/templates/services/DYNAMODB.md

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