cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/logging-best-practices/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: logging-best-practices
+description: Implement structured logging with JSON formats, log levels (DEBUG, INFO, WARN, ERROR), contextual logging, PII handling, and centralized logging. Use for logging, observability, log levels, structured logs, or debugging.
+---
+
+# Logging Best Practices
+
+## Overview
+
+Comprehensive guide to implementing structured, secure, and performant logging across applications. Covers log levels, structured logging formats, contextual information, PII protection, and centralized logging systems.
+
+## When to Use
+
+- Setting up application logging infrastructure
+- Implementing structured logging
+- Configuring log levels for different environments
+- Managing sensitive data in logs
+- Setting up centralized logging
+- Implementing distributed tracing
+- Debugging production issues
+- Compliance with logging regulations
+
+## Stack-Specific References
+
+After reading the methodology below, read the reference matching your surface's Languages column:
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+
+---
+
+## 1. Log Levels
+
+| Level | When to Use | Production Default |
+|-------|------------|-------------------|
+| **DEBUG** | Detailed info for debugging — request payloads, intermediate values | OFF |
+| **INFO** | General operational events — user actions, transactions, startup | ON |
+| **WARN** | Potentially harmful — rate limits approaching, retry, deprecations | ON |
+| **ERROR** | Failures the app can recover from — failed request, DB timeout | ON |
+| **FATAL** | Critical failures — the app must stop | ON (triggers alerts) |
+
+**Environment rules:**
+- Development: DEBUG and above
+- Staging: INFO and above
+- Production: INFO and above (DEBUG only via feature flag for specific modules)
+
+---
+
+## 2. Structured Logging (JSON)
+
+All production logs MUST be structured (JSON format), not free-text. Structured logs enable:
+- Machine-parseable log aggregation
+- Field-based search and filtering
+- Dashboards and alerting
+
+**Every log entry must include:**
+- `timestamp` — ISO 8601 format
+- `level` — log level string
+- `message` — human-readable description
+- `service` — service name
+- `environment` — deployment environment
+
+**Example output (any language):**
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "level": "INFO",
+  "message": "User created",
+  "service": "user-service",
+  "environment": "production",
+  "userId": "abc-123",
+  "requestId": "req-456"
+}
+```
+
+---
+
+## 3. Contextual Logging
+
+### Request Context
+Attach request metadata to every log within a request lifecycle:
+- **Request ID** — unique identifier for correlating logs from one request
+- **Correlation ID** — propagated across service boundaries in distributed systems
+- **User ID** — authenticated user (if available)
+- **HTTP method/path** — what was requested
+
+### Correlation IDs
+In distributed systems, propagate a correlation ID via headers (`X-Correlation-Id`) so that logs from multiple services can be traced together.
+
+---
+
+## 4. PII and Sensitive Data Handling
+
+**CRITICAL:** PII must NEVER appear in plaintext in logs.
+
+### Sensitive Fields (always redact or mask)
+- Passwords, tokens, API keys
+- SSN, credit card numbers
+- Email addresses (depending on regulation)
+- Phone numbers (depending on regulation)
+
+### Strategies
+| Strategy | When to Use |
+|----------|-------------|
+| **Redaction** — replace with `[REDACTED]` | Passwords, API keys, tokens |
+| **Masking** — partial reveal (`u***r@example.com`) | Email, phone, credit card |
+| **Hashing** — one-way hash | When you need to correlate without revealing |
+| **Omission** — don't log the field at all | When the field serves no diagnostic purpose |
+
+---
+
+## 5. Performance Logging
+
+Track operation timing for performance monitoring:
+- **Start timer** before operation
+- **End timer** after operation
+- **Log duration** with context
+- **Alert on threshold** if operation exceeds expected time
+
+Key operations to time:
+- Database queries
+- External API calls
+- File I/O operations
+- Complex computations
+
+---
+
+## 6. Centralized Logging
+
+For distributed systems, aggregate logs to a central system:
+
+| Tool | Type |
+|------|------|
+| **ELK Stack** | Elasticsearch + Logstash + Kibana (self-hosted) |
+| **Grafana + Loki** | Lightweight log aggregation (self-hosted) |
+| **Datadog** | Cloud monitoring and logging |
+| **AWS CloudWatch** | AWS-native log management |
+| **Splunk** | Enterprise log management |
+
+---
+
+## 7. Distributed Tracing
+
+For microservice architectures, use OpenTelemetry (or similar) to trace requests across services:
+- Create spans for each operation
+- Propagate trace context via headers
+- Export to Jaeger, Zipkin, or Datadog
+
+---
+
+## 8. Log Sampling (High-Volume Services)
+
+For high-volume services, sample INFO/DEBUG logs to reduce volume:
+- **Random sampling** — log N% of requests
+- **Consistent sampling** — hash user ID so same user always gets logged (or not)
+- **Always log** WARN and ERROR — never sample these
+
+---
+
+## Best Practices
+
+### ✅ DO
+- Use structured logging (JSON) in production
+- Include correlation/request IDs in all logs
+- Log at appropriate levels (don't overuse DEBUG)
+- Redact sensitive data (PII, passwords, tokens)
+- Include context (userId, requestId, etc.)
+- Log errors with full stack traces
+- Use centralized logging in distributed systems
+- Set up log rotation to manage disk space
+- Monitor log volume and costs
+- Use async logging for performance
+- Include timestamps in ISO 8601 format
+- Log business events (user actions, transactions)
+- Set up alerts for error patterns
+
+### ❌ DON'T
+- Log passwords, tokens, or sensitive data
+- Use print/console.log in production
+- Log at DEBUG level in production by default
+- Log inside tight loops (use sampling)
+- Include PII without anonymization
+- Ignore log rotation (disk will fill up)
+- Use synchronous logging in hot paths
+- Log to multiple transports without need
+- Forget to include error stack traces
+- Log binary data or large objects
+- Use string concatenation (use structured fields)
+- Log every single request in high-volume APIs

package/template/.claude/skills/logging-best-practices/references/go.md

@@ -0,0 +1,49 @@
+# Go Logging Patterns
+
+Language-specific patterns for the `logging-best-practices` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Libraries
+
+| Library | Use Case |
+|---------|----------|
+| **zap** | High-performance structured logging |
+| **zerolog** | Zero-allocation JSON logger |
+
+## zap Setup
+
+```go
+package main
+
+import "go.uber.org/zap"
+
+func main() {
+    // Production config (JSON output)
+    logger, _ := zap.NewProduction()
+    defer logger.Sync()
+
+    // Development config (human-readable)
+    // logger, _ := zap.NewDevelopment()
+
+    logger.Info("User created",
+        zap.String("userId", user.ID),
+        zap.String("email", user.Email),
+        zap.String("requestId", req.ID),
+    )
+
+    logger.Error("Payment processing failed",
+        zap.Error(err),
+        zap.String("orderId", order.ID),
+        zap.Float64("amount", order.Total),
+        zap.String("userId", user.ID),
+    )
+
+    // Sugared logger for convenience (slightly slower)
+    sugar := logger.Sugar()
+    sugar.Infow("User login",
+        "userId", user.ID,
+        "ip", req.IP,
+    )
+}
+```

package/template/.claude/skills/logging-best-practices/references/python.md

@@ -0,0 +1,52 @@
+# Python Logging Patterns
+
+Language-specific patterns for the `logging-best-practices` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Libraries
+
+| Library | Use Case |
+|---------|----------|
+| **structlog** | Structured logging with processors |
+| **logging** | Standard library (structlog wraps it) |
+
+## structlog Setup
+
+```python
+import structlog
+import logging
+
+structlog.configure(
+    processors=[
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+        structlog.processors.UnicodeDecoder(),
+        structlog.processors.JSONRenderer()
+    ],
+    context_class=dict,
+    logger_factory=structlog.stdlib.LoggerFactory(),
+    cache_logger_on_first_use=True,
+)
+
+logger = structlog.get_logger()
+
+# Usage
+logger.info("user_created",
+    user_id=user.id,
+    email=user.email,
+    request_id=request.id
+)
+
+logger.error("payment_failed",
+    error=str(error),
+    order_id=order.id,
+    amount=order.total,
+    user_id=user.id
+)
+```

package/template/.claude/skills/logging-best-practices/references/typescript.md

@@ -0,0 +1,215 @@
+# TypeScript Logging Patterns
+
+Language-specific patterns for the `logging-best-practices` skill. Read `SKILL.md` first for universal methodology.
+
+---
+
+## Libraries
+
+| Library | Use Case |
+|---------|----------|
+| **Winston** | Versatile, multi-transport, production-ready |
+| **Pino** | High-performance JSON logger |
+| **OpenTelemetry SDK** | Distributed tracing |
+
+## Winston Setup
+
+```typescript
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  defaultMeta: {
+    service: 'user-service',
+    environment: process.env.NODE_ENV
+  },
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    }),
+    new winston.transports.File({
+      filename: 'logs/error.log',
+      level: 'error',
+      maxsize: 5242880, maxFiles: 5
+    }),
+    new winston.transports.File({
+      filename: 'logs/combined.log',
+      maxsize: 5242880, maxFiles: 5
+    })
+  ]
+});
+
+logger.info('User created', { userId: user.id, requestId: req.id });
+logger.error('Payment failed', { error: error.message, stack: error.stack, orderId: order.id });
+```
+
+## Request Context Middleware
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+import { AsyncLocalStorage } from 'async_hooks';
+
+const asyncLocalStorage = new AsyncLocalStorage();
+
+export function requestLogger(req, res, next) {
+  const requestId = req.headers['x-request-id'] || uuidv4();
+  const context = {
+    requestId, method: req.method, path: req.path,
+    ip: req.ip, userId: req.user?.id
+  };
+
+  asyncLocalStorage.run(context, () => {
+    logger.info('Request started', context);
+    res.on('finish', () => {
+      logger.info('Request completed', {
+        ...context, statusCode: res.statusCode,
+        duration: Date.now() - req.startTime
+      });
+    });
+    req.startTime = Date.now();
+    next();
+  });
+}
+
+export function getLogger() {
+  const context = asyncLocalStorage.getStore();
+  return {
+    info: (message: string, meta?: object) =>
+      logger.info(message, { ...context, ...meta }),
+    error: (message: string, error: Error, meta?: object) =>
+      logger.error(message, { ...context, error, ...meta }),
+    warn: (message: string, meta?: object) =>
+      logger.warn(message, { ...context, ...meta }),
+    debug: (message: string, meta?: object) =>
+      logger.debug(message, { ...context, ...meta })
+  };
+}
+```
+
+## PII Sanitization
+
+```typescript
+const SENSITIVE_FIELDS = ['password', 'token', 'apiKey', 'ssn', 'creditCard', 'email', 'phone'];
+
+function sanitize(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+  if (Array.isArray(obj)) return obj.map(sanitize);
+
+  const sanitized = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (SENSITIVE_FIELDS.some(f => key.toLowerCase().includes(f.toLowerCase()))) {
+      sanitized[key] = '[REDACTED]';
+    } else if (typeof value === 'object') {
+      sanitized[key] = sanitize(value);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+
+function maskEmail(email: string): string {
+  const [local, domain] = email.split('@');
+  return `${local[0]}${'*'.repeat(local.length - 2)}${local[local.length - 1]}@${domain}`;
+}
+```
+
+## Performance Logger
+
+```typescript
+class PerformanceLogger {
+  private timers = new Map<string, number>();
+
+  start(op: string) { this.timers.set(op, Date.now()); }
+
+  end(op: string, meta?: object) {
+    const start = this.timers.get(op);
+    if (!start) return;
+    const duration = Date.now() - start;
+    this.timers.delete(op);
+    logger.info(`Performance: ${op}`, { operation: op, durationMs: duration, ...meta });
+    if (duration > 1000) {
+      logger.warn(`Slow operation: ${op}`, { operation: op, durationMs: duration, threshold: 1000, ...meta });
+    }
+  }
+
+  async measure<T>(op: string, fn: () => Promise<T>, meta?: object): Promise<T> {
+    this.start(op);
+    try { return await fn(); } finally { this.end(op, meta); }
+  }
+}
+```
+
+## Distributed Tracing (OpenTelemetry)
+
+```typescript
+import opentelemetry from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/node';
+import { SimpleSpanProcessor } from '@opentelemetry/tracing';
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(new JaegerExporter({
+    serviceName: 'user-service',
+    endpoint: 'http://jaeger:14268/api/traces'
+  }))
+);
+provider.register();
+
+const tracer = opentelemetry.trace.getTracer('user-service');
+
+app.get('/api/users/:id', async (req, res) => {
+  const span = tracer.startSpan('get-user', {
+    attributes: { 'http.method': req.method, 'http.url': req.url }
+  });
+  try {
+    const user = await fetchUser(req.params.id);
+    span.setStatus({ code: opentelemetry.SpanStatusCode.OK });
+    res.json(user);
+  } catch (error) {
+    span.setStatus({ code: opentelemetry.SpanStatusCode.ERROR, message: error.message });
+    res.status(500).json({ error: 'Internal server error' });
+  } finally {
+    span.end();
+  }
+});
+```
+
+## Centralized Logging (ELK + Winston)
+
+```typescript
+import 'winston-logstash';
+
+const elkLogger = winston.createLogger({
+  transports: [
+    new winston.transports.Logstash({
+      port: 5000, host: 'logstash',
+      node_name: 'user-service', max_connect_retries: -1
+    })
+  ]
+});
+```
+
+## Log Sampling
+
+```typescript
+class SamplingLogger {
+  constructor(private logger: Logger, private sampleRate = 0.1) {}
+
+  info(message: string, meta?: object) {
+    if (Math.random() < this.sampleRate) this.logger.info(message, meta);
+  }
+
+  warn(message: string, meta?: object) { this.logger.warn(message, meta); }
+  error(message: string, error: Error, meta?: object) { this.logger.error(message, error, meta); }
+}
+```

package/template/.claude/skills/migration-management/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: database-migration-management
+description: Manage database migrations and schema versioning. Use when planning migrations, version control, rollback strategies, or data transformations for any database paradigm.
+---
+
+# Database Migration Management
+
+## Overview
+
+Implement robust database migration systems with version control, rollback capabilities, and data transformation strategies. This skill covers universal migration methodology. For paradigm-specific tooling, see references.
+
+## When to Use
+
+- Schema versioning and evolution
+- Data transformations and cleanup
+- Adding/removing tables, columns, collections, or fields
+- Index creation and optimization
+- Migration testing and validation
+- Rollback planning and execution
+- Multi-environment deployments
+
+## Paradigm-Specific References
+
+After reading the methodology below, read the reference matching your surface's Databases column in the surface stack map (`.agent/instructions/tech-stack.md`):
+
+| Paradigm | Reference | Example Stores |
+|----------|-----------|----------------|
+| Relational | `references/relational.md` | PostgreSQL, MySQL, SQLite |
+| Document | `references/document.md` | MongoDB, Firestore, CouchDB |
+| Graph | `references/graph.md` | SurrealDB, Neo4j, ArangoDB |
+
+---
+
+## Universal Migration Principles
+
+### 1. Bidirectional Migrations
+
+Every migration must have both directions:
+- **UP** — applies the change
+- **DOWN** — reverses the change
+
+If a migration cannot be reversed (e.g., data deletion), document this explicitly and require a backup before execution.
+
+### 2. Migration Ordering
+
+Migrations are **sequentially ordered** by timestamp or version number:
+- Timestamp format: `YYYYMMDD_NNN_description` (e.g., `20240115_001_add_phone_to_users`)
+- Never reorder or renumber existing migrations
+- Never modify an already-executed migration — create a new one
+
+### 3. Idempotency
+
+Migrations should be idempotent where possible:
+- Use "IF NOT EXISTS" / "IF EXISTS" guards
+- Check for the presence of the change before applying it
+- Run pre-flight checks before destructive operations
+
+### 4. Atomic Migrations
+
+Each migration should be a single logical change:
+- One migration = one purpose (add column, create table, transform data)
+- Don't combine unrelated changes
+- Use transactions for multi-statement migrations where supported
+
+---
+
+## Common Migration Patterns
+
+### Safe Schema Changes
+
+| Operation | Safe? | Strategy |
+|-----------|-------|----------|
+| Add nullable column | ✅ Always safe | Add with default or NULL |
+| Add NOT NULL column | ⚠️ Requires backfill | Add nullable → backfill → add constraint |
+| Rename column | ⚠️ Requires coordination | Add new → copy data → update app → drop old |
+| Drop column | ⚠️ Requires coordination | Stop reading → deploy → drop column |
+| Add index | ⚠️ Can lock table | Use concurrent/online index creation |
+| Drop table | 🔴 Destructive | Backup first, confirm no references |
+
+### Multi-Phase Migrations
+
+For non-trivial schema changes (rename, type change, restructure):
+
+1. **Phase 1: Expand** — Add new structure alongside old
+2. **Phase 2: Migrate** — Copy/transform data to new structure
+3. **Phase 3: Contract** — Remove old structure after verification
+
+This pattern prevents downtime and allows rollback at any phase.
+
+### Data Transformation Migrations
+
+When transforming data (normalization, cleanup, format changes):
+
+1. **Verify source data** — Count records, check constraints
+2. **Apply transformation** — Batch for large datasets
+3. **Validate results** — Compare counts, spot-check values
+4. **Document irreversibility** — If rollback requires backup restore, say so
+
+---
+
+## Rollback Strategies
+
+### Per-Migration Rollback
+
+Every migration has a DOWN direction. Execute in reverse order:
+- Migration 5 DOWN
+- Migration 4 DOWN
+- Migration 3 DOWN
+- ... until target version reached
+
+### Point-in-Time Recovery
+
+For data-destructive migrations:
+- Require backup before execution
+- Document the backup location
+- Test restore procedure before migration
+
+### Blue-Green Schema Changes
+
+For zero-downtime migrations:
+- Run new schema alongside old
+- Application supports both schemas during transition
+- Cut over when new schema is verified
+- Drop old schema after observation period
+
+---
+
+## Testing Migrations
+
+### Local Testing
+
+1. **Fresh database** — Run all migrations from scratch (empty → current)
+2. **Incremental** — Run only new migrations on a copy of production
+3. **Rollback** — Test DOWN migration after UP
+4. **Data integrity** — Verify constraints hold after migration
+
+### Staging Validation
+
+1. Restore production backup to staging
+2. Run migrations on staging
+3. Verify application works against migrated schema
+4. Run automated tests against staging
+5. Record migration timing for capacity planning
+
+### Pre-Production Checklist
+
+- [ ] Tested on local database
+- [ ] Tested on staging with production data copy
+- [ ] Rollback procedure tested
+- [ ] Backup verified before migration
+- [ ] Application code compatible with both old and new schema
+- [ ] Migration timing measured (acceptable for maintenance window?)
+- [ ] Long-running query impact assessed
+
+---
+
+## Production Deployment
+
+### Safe Migration Checklist
+
+- [ ] Test migration on production-like database
+- [ ] Verify backup exists before migration
+- [ ] Schedule during low-traffic window
+- [ ] Monitor locks and long-running queries
+- [ ] Have rollback plan ready and tested
+- [ ] Document all changes
+- [ ] Run in transaction when possible
+- [ ] Verify data integrity after migration
+- [ ] Coordinate application code deployment with migration
+- [ ] Notify team of migration window
+
+### Post-Migration Verification
+
+1. **Schema check** — Verify new structures exist
+2. **Data check** — Verify data integrity constraints
+3. **Application check** — Verify application reads/writes correctly
+4. **Performance check** — Verify query performance hasn't degraded
+5. **Monitoring** — Watch error rates for 24 hours post-migration
+
+---
+
+## Migration Tracking
+
+Maintain a migration history table (or equivalent) that records:
+- Migration version/ID
+- Migration name/description
+- Execution timestamp
+- Duration
+- Checksum (to detect tampering)
+- Status (applied, rolled back, failed)
+
+---
+
+## Resources
+
+- [Flyway](https://flywaydb.org/) — Java/JVM migration tool
+- [Liquibase](https://www.liquibase.org/) — Database changelog management
+- [Alembic](https://alembic.sqlalchemy.org/) — Python/SQLAlchemy migrations
+- [Knex.js](https://knexjs.org/) — Node.js query builder with migrations
+- [golang-migrate](https://github.com/golang-migrate/migrate) — Go migration tool