@hivehub/rulebook 3.4.2 → 4.1.0

package/templates/services/DOCKER.md

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

@@ -0,0 +1,168 @@
+<!-- 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/HELM.md

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

package/templates/services/KUBERNETES.md

@@ -0,0 +1,208 @@
+<!-- KUBERNETES:START -->
+# Kubernetes Instructions
+
+**CRITICAL**: Follow these Kubernetes best practices for all cluster deployments.
+
+## Resource Requirements
+
+ALL Deployments MUST define resource requests and limits:
+```yaml
+resources:
+  requests:
+    memory: "128Mi"
+    cpu: "100m"
+  limits:
+    memory: "512Mi"
+    cpu: "500m"
+```
+
+Omitting resource limits causes unbounded resource consumption and can destabilize the cluster.
+
+## Health Probes
+
+ALL Deployments MUST define both readiness and liveness probes:
+```yaml
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  failureThreshold: 3
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 3000
+  initialDelaySeconds: 15
+  periodSeconds: 20
+  failureThreshold: 3
+```
+
+### Probe Guidelines
+- **readinessProbe**: Gates traffic to the pod. Use a lightweight endpoint
+- **livenessProbe**: Restarts the pod if unhealthy. Set `initialDelaySeconds` high enough for startup
+- Consider a **startupProbe** for slow-starting applications
+
+## Security Context
+
+ALL Pods MUST define a security context:
+```yaml
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  runAsGroup: 1000
+  fsGroup: 1000
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop:
+      - ALL
+```
+
+### Pod Security Standards
+- Apply `restricted` Pod Security Standard where possible
+- Never run containers as root
+- Drop all Linux capabilities unless explicitly required
+
+## Namespace
+
+- Use explicit namespaces for all resources (never use `default`)
+- Apply least-privilege RBAC per namespace
+- Use `ResourceQuota` and `LimitRange` per namespace
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-app
+  labels:
+    pod-security.kubernetes.io/enforce: restricted
+```
+
+## Secrets Management
+
+- NEVER put secrets in YAML files committed to git
+- Use Kubernetes Secrets or external secret managers:
+  - HashiCorp Vault
+  - AWS Secrets Manager / SSM Parameter Store
+  - Azure Key Vault
+  - Google Secret Manager
+- Use `ExternalSecret` CRD or `sealed-secrets` for GitOps workflows
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: app-secrets
+  namespace: my-app
+type: Opaque
+stringData:
+  DATABASE_URL: "postgresql://user:pass@host:5432/db"
+```
+
+## Deployment Pattern
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+  namespace: my-app
+  labels:
+    app: my-app
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: my-app
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+      containers:
+        - name: my-app
+          image: my-registry/my-app:1.0.0
+          ports:
+            - containerPort: 3000
+          env:
+            - name: NODE_ENV
+              value: "production"
+          envFrom:
+            - secretRef:
+                name: app-secrets
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "512Mi"
+              cpu: "500m"
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: 3000
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+```
+
+## Service Pattern
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: my-app
+  namespace: my-app
+spec:
+  selector:
+    app: my-app
+  ports:
+    - port: 80
+      targetPort: 3000
+      protocol: TCP
+  type: ClusterIP
+```
+
+## Labels and Annotations
+
+Apply consistent labels to all resources:
+```yaml
+metadata:
+  labels:
+    app.kubernetes.io/name: my-app
+    app.kubernetes.io/version: "1.0.0"
+    app.kubernetes.io/component: backend
+    app.kubernetes.io/managed-by: helm
+```
+
+## Best Practices
+
+- Use `RollingUpdate` strategy with `maxUnavailable: 0` for zero-downtime deploys
+- Set `PodDisruptionBudget` for high-availability workloads
+- Use `HorizontalPodAutoscaler` for auto-scaling
+- Pin container image tags (never use `latest`)
+- Use `NetworkPolicy` to restrict pod-to-pod communication
+- Store configuration in `ConfigMap`, secrets in `Secret`
+- Use `topologySpreadConstraints` for multi-zone distribution
+
+<!-- KUBERNETES:END -->

package/templates/services/OPENTELEMETRY.md

@@ -0,0 +1,25 @@
+<!-- OPENTELEMETRY:START -->
+# OpenTelemetry — Distributed Tracing
+
+## Initialization
+- Initialize OTel SDK BEFORE application code (use `--require` flag or top-level import)
+- Configure exporter based on environment (OTLP, Jaeger, console for dev)
+- Set `serviceName` from environment: `process.env.OTEL_SERVICE_NAME`
+
+## Instrumentation
+- Use auto-instrumentation packages for common libraries (HTTP, Express, pg)
+- Create manual spans for business logic operations:
+  ```typescript
+  const tracer = trace.getTracer('service-name');
+  const span = tracer.startSpan('operation.name');
+  try { ... } finally { span.end(); }
+  ```
+
+## Context Propagation
+- Always propagate context across service boundaries using W3C Trace Context headers
+- Use `context.with()` for async operations to preserve trace context
+
+## Metrics
+- Use `@opentelemetry/sdk-metrics` for custom metrics
+- Follow naming conventions: `<namespace>.<metric_type>.<name>` (e.g., `http.server.request_count`)
+<!-- OPENTELEMETRY:END -->