@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/_shared/.claude/rules/quality/observability.md

@@ -0,0 +1,240 @@
+---
+paths:
+  - "**/*"
+---
+
+# Observability (Logs, Metrics, Traces)
+
+## Three Pillars
+
+| Pillar | Purpose | Tools |
+|--------|---------|-------|
+| **Logs** | Event records, debugging | ELK, Loki, CloudWatch |
+| **Metrics** | Numeric measurements | Prometheus, Datadog, CloudWatch |
+| **Traces** | Request flow across services | Jaeger, Zipkin, X-Ray |
+
+## Structured Logging
+
+### Format (JSON)
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "level": "info",
+  "message": "User logged in",
+  "service": "auth-service",
+  "version": "1.2.3",
+  "traceId": "abc-123-def",
+  "spanId": "span-456",
+  "userId": "user-789",
+  "duration": 45,
+  "metadata": {
+    "ip": "192.168.1.1",
+    "userAgent": "Mozilla/5.0..."
+  }
+}
+```
+
+### Log Levels
+
+| Level | When to Use |
+|-------|-------------|
+| `error` | Failures requiring attention |
+| `warn` | Recoverable issues, deprecations |
+| `info` | Business events, state changes |
+| `debug` | Development details (disabled in prod) |
+
+### What to Log
+
+```
+✓ Request received (info)
+✓ Request completed with duration (info)
+✓ Business events (user created, order placed)
+✓ External service calls with duration
+✓ Errors with stack trace and context
+✓ Authentication events
+
+✗ Passwords, tokens, secrets
+✗ Credit card numbers, PII
+✗ Full request/response bodies
+✗ Health check spam
+```
+
+## Correlation IDs
+
+Pass trace ID through entire request chain:
+
+```typescript
+// Middleware to extract/generate trace ID
+app.use((req, res, next) => {
+  req.traceId = req.headers['x-trace-id'] || uuid();
+  res.setHeader('x-trace-id', req.traceId);
+  next();
+});
+
+// Include in all logs
+logger.info('Processing order', {
+  traceId: req.traceId,
+  orderId: order.id,
+});
+
+// Pass to downstream services
+await fetch(url, {
+  headers: { 'x-trace-id': req.traceId }
+});
+```
+
+## Metrics
+
+### Types
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| Counter | Cumulative totals | `http_requests_total` |
+| Gauge | Current value | `active_connections` |
+| Histogram | Value distribution | `request_duration_seconds` |
+| Summary | Percentiles | `request_latency_p99` |
+
+### Key Metrics (RED Method)
+
+```
+# Rate - requests per second
+http_requests_total{method="GET", path="/api/users"}
+
+# Errors - error rate
+http_requests_total{status="5xx"} / http_requests_total
+
+# Duration - latency percentiles
+http_request_duration_seconds{quantile="0.99"}
+```
+
+### Business Metrics
+
+```
+# Orders
+orders_created_total
+orders_value_total
+orders_by_status{status="completed"}
+
+# Users
+users_registered_total
+users_active_daily
+
+# Performance
+cache_hit_ratio
+queue_depth
+```
+
+## Health Checks
+
+### Endpoints
+
+```typescript
+// Liveness - is the app running?
+app.get('/health/live', (req, res) => {
+  res.status(200).json({ status: 'ok' });
+});
+
+// Readiness - can the app serve traffic?
+app.get('/health/ready', async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    externalApi: await checkExternalApi(),
+  };
+
+  const healthy = Object.values(checks).every(c => c.status === 'ok');
+  res.status(healthy ? 200 : 503).json({ checks });
+});
+```
+
+### Response Format
+
+```json
+{
+  "status": "healthy",
+  "version": "1.2.3",
+  "uptime": 3600,
+  "checks": {
+    "database": { "status": "ok", "latency": 5 },
+    "redis": { "status": "ok", "latency": 2 },
+    "externalApi": { "status": "degraded", "latency": 500 }
+  }
+}
+```
+
+## Distributed Tracing
+
+### Span Structure
+
+```
+Trace: abc-123
+├── Span: API Gateway (50ms)
+│   ├── Span: Auth Service (10ms)
+│   └── Span: Order Service (35ms)
+│       ├── Span: Database Query (15ms)
+│       └── Span: Payment Service (18ms)
+```
+
+### OpenTelemetry Setup
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  serviceName: 'order-service',
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://jaeger:4318/v1/traces',
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+## Alerting Rules
+
+### SLO-based Alerts
+
+```yaml
+# Alert when error rate > 1% for 5 minutes
+- alert: HighErrorRate
+  expr: |
+    sum(rate(http_requests_total{status=~"5.."}[5m]))
+    / sum(rate(http_requests_total[5m])) > 0.01
+  for: 5m
+  labels:
+    severity: critical
+
+# Alert when p99 latency > 1s
+- alert: HighLatency
+  expr: |
+    histogram_quantile(0.99,
+      rate(http_request_duration_seconds_bucket[5m])
+    ) > 1
+  for: 5m
+  labels:
+    severity: warning
+```
+
+## Dashboards
+
+### Essential Panels
+
+1. **Request rate** (per endpoint)
+2. **Error rate** (4xx, 5xx breakdown)
+3. **Latency** (p50, p95, p99)
+4. **Active connections**
+5. **Resource usage** (CPU, memory)
+6. **Business metrics** (orders, users)
+
+## Anti-patterns
+
+- Logging sensitive data
+- No correlation IDs
+- Alerting on symptoms not causes
+- Too many alerts (alert fatigue)
+- Metrics without labels
+- No retention policy
+- Health checks that don't check dependencies

package/configs/_shared/.claude/rules/quality/testing-patterns.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - "**/*"
+---
+
+# Testing Principles
+
+## Test Structure (AAA Pattern)
+
+1. **Arrange** - Set up test data and dependencies
+2. **Act** - Execute the code under test
+3. **Assert** - Verify the expected outcome
+
+## Naming Conventions
+
+| Language | Pattern |
+|----------|---------|
+| TypeScript | `should_ExpectedBehavior_When_Condition` |
+| Python | `test_action_condition_expected` |
+| C# | `MethodName_Scenario_ExpectedBehavior` |
+
+## Test Organization
+
+- Group tests by class/module
+- Sub-group by method or behavior
+- Use descriptive describe/context blocks
+
+## Mocking Best Practices
+
+- Mock only external dependencies
+- Don't mock internal implementation details
+- Use factories for test data
+- Verify interactions when behavior matters
+
+## Test Isolation
+
+- Each test must be independent
+- No shared mutable state
+- Tests should run in any order
+- Clean up after each test
+
+## What to Test
+
+| Priority | What | Why |
+|----------|------|-----|
+| High | Business logic | Core value |
+| High | Edge cases | Common bugs |
+| Medium | Error paths | Graceful degradation |
+| Medium | Integration points | Contract verification |
+| Low | Trivial getters/setters | Low value |
+
+## Coverage Guidelines
+
+- **80%+** on business logic
+- **100%** on critical paths (payments, auth)
+- Don't chase coverage numbers blindly
+- One meaningful test > many trivial tests
+
+## Anti-Patterns
+
+- Tests that depend on execution order
+- Testing implementation, not behavior
+- Excessive mocking (testing mocks, not code)
+- Flaky tests (non-deterministic)
+- Slow tests in the unit test suite

package/configs/_shared/.claude/rules/security/secrets-management.md

@@ -0,0 +1,222 @@
+---
+paths:
+  - "**/.env*"
+  - "**/secrets/**"
+  - "**/config/**"
+  - "**/appsettings*.json"
+---
+
+# Secrets Management
+
+## Core Principles
+
+- **Never commit secrets** to version control
+- **Rotate regularly** (90 days max for critical secrets)
+- **Least privilege** - only grant necessary access
+- **Audit access** - log who accessed what
+- **Encrypt at rest** and in transit
+
+## Environment Files
+
+### Structure
+
+```
+.env                 # Shared defaults (commit)
+.env.local           # Local overrides (gitignore)
+.env.development     # Dev environment (commit, no secrets)
+.env.production      # Prod template (commit, no secrets)
+.env.production.local # Prod secrets (gitignore)
+```
+
+### .gitignore
+
+```gitignore
+# Always ignore
+.env.local
+.env.*.local
+*.pem
+*.key
+**/secrets/
+credentials.json
+service-account.json
+```
+
+### Format
+
+```bash
+# .env.example (commit this as template)
+DATABASE_URL=postgresql://user:password@localhost:5432/db
+REDIS_URL=redis://localhost:6379
+JWT_SECRET=your-secret-here
+API_KEY=your-api-key-here
+
+# Required for production
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# STRIPE_SECRET_KEY=
+```
+
+## Secret Types & Storage
+
+| Type | Example | Storage |
+|------|---------|---------|
+| API Keys | Stripe, Twilio | Vault / Cloud Secrets |
+| DB Credentials | Connection strings | Vault / Cloud Secrets |
+| JWT Secrets | Signing keys | Vault / Env vars |
+| OAuth Secrets | Client secrets | Cloud Secrets |
+| Encryption Keys | AES keys | KMS / HSM |
+| Certificates | TLS certs | Cert Manager |
+
+## Cloud Provider Solutions
+
+### AWS Secrets Manager
+
+```typescript
+import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
+
+async function getSecret(secretName: string): Promise<string> {
+  const client = new SecretsManagerClient({ region: "us-east-1" });
+  const response = await client.send(
+    new GetSecretValueCommand({ SecretId: secretName })
+  );
+  return response.SecretString!;
+}
+```
+
+### Azure Key Vault
+
+```csharp
+var client = new SecretClient(
+    new Uri("https://myvault.vault.azure.net/"),
+    new DefaultAzureCredential()
+);
+KeyVaultSecret secret = await client.GetSecretAsync("my-secret");
+```
+
+### Google Secret Manager
+
+```python
+from google.cloud import secretmanager
+
+def get_secret(secret_id: str) -> str:
+    client = secretmanager.SecretManagerServiceClient()
+    name = f"projects/my-project/secrets/{secret_id}/versions/latest"
+    response = client.access_secret_version(request={"name": name})
+    return response.payload.data.decode("UTF-8")
+```
+
+## CI/CD Secrets
+
+### GitHub Actions
+
+```yaml
+# Set in: Settings > Secrets and variables > Actions
+
+jobs:
+  deploy:
+    environment: production  # Environment-specific secrets
+    steps:
+      - name: Deploy
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          API_KEY: ${{ secrets.API_KEY }}
+        run: ./deploy.sh
+```
+
+### GitLab CI
+
+```yaml
+# Set in: Settings > CI/CD > Variables
+# Mark as "Protected" and "Masked"
+
+deploy:
+  script:
+    - echo "$DATABASE_URL"  # Available as env var
+  environment:
+    name: production
+```
+
+## Docker & Kubernetes
+
+### Docker Secrets
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    secrets:
+      - db_password
+    environment:
+      - DB_PASSWORD_FILE=/run/secrets/db_password
+
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+```
+
+### Kubernetes Secrets
+
+```yaml
+# sealed-secret.yaml (encrypted, safe to commit)
+apiVersion: bitnami.com/v1alpha1
+kind: SealedSecret
+metadata:
+  name: my-secret
+spec:
+  encryptedData:
+    password: AgBy3i4OJSWK+...
+
+# Usage in pod
+env:
+  - name: DB_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        name: my-secret
+        key: password
+```
+
+## Validation at Startup
+
+```typescript
+// Validate required secrets exist at startup
+const requiredSecrets = [
+  'DATABASE_URL',
+  'JWT_SECRET',
+  'REDIS_URL',
+];
+
+for (const secret of requiredSecrets) {
+  if (!process.env[secret]) {
+    throw new Error(`Missing required secret: ${secret}`);
+  }
+}
+```
+
+## Secret Rotation
+
+1. **Generate new secret**
+2. **Deploy with both old and new** (accept both)
+3. **Update all consumers** to use new
+4. **Remove old secret** from config
+5. **Revoke old secret** in provider
+
+## Audit Checklist
+
+- [ ] No secrets in code or commits
+- [ ] All secrets in gitignore
+- [ ] Secrets encrypted at rest
+- [ ] Access logged and auditable
+- [ ] Rotation policy in place
+- [ ] Secrets validated at startup
+- [ ] Different secrets per environment
+- [ ] Backup/recovery procedure documented
+
+## Anti-patterns
+
+- Committing `.env` with real secrets
+- Using same secrets across environments
+- Sharing secrets via Slack/email
+- Hardcoding secrets in Dockerfiles
+- Not rotating compromised secrets immediately
+- Logging secrets (even accidentally)
+- Storing secrets in plain text files on servers