@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/microservices.md

@@ -0,0 +1,272 @@
+---
+name: microservices
+description: Microservices patterns for service discovery, circuit breaker, saga, event sourcing, API gateway, and health checks.
+---
+
+# Microservices Patterns
+
+## When to Use
+
+Apply these patterns when building distributed systems with multiple independently
+deployable services. Use this skill for service-to-service communication, fault
+tolerance, distributed transactions, event-driven architecture, and operational
+observability. Do not adopt microservices until a monolith becomes a bottleneck.
+
+## How It Works
+
+### Service Discovery
+
+Services register themselves on startup and deregister on shutdown. Other services
+look up addresses from the registry instead of hardcoding URLs.
+
+```typescript
+// Consul-based registration
+class ServiceRegistry {
+  constructor(private consul: ConsulClient) {}
+
+  async register(service: ServiceDefinition): Promise<void> {
+    await this.consul.agent.service.register({
+      id: `${service.name}-${service.instance}`,
+      name: service.name,
+      address: service.host,
+      port: service.port,
+      check: {
+        http: `http://${service.host}:${service.port}/healthz`,
+        interval: '10s',
+        deregister_critical_service_after: '30s',
+      },
+    })
+  }
+
+  async discover(serviceName: string): Promise<ServiceInstance[]> {
+    const result = await this.consul.health.service({ service: serviceName, passing: true })
+    return result.map(entry => ({
+      host: entry.Service.Address,
+      port: entry.Service.Port,
+    }))
+  }
+}
+
+// DNS-based (Kubernetes): just use service names
+// http://user-service.default.svc.cluster.local:3000
+```
+
+### Circuit Breaker
+
+Prevent cascading failures by tracking error rates and short-circuiting calls to
+unhealthy services. Three states: closed (normal), open (failing fast), half-open
+(testing recovery).
+
+```typescript
+class CircuitBreaker {
+  private failures = 0
+  private lastFailureTime = 0
+  private state: 'closed' | 'open' | 'half-open' = 'closed'
+
+  constructor(
+    private threshold: number = 5,
+    private resetTimeout: number = 30_000,
+  ) {}
+
+  async call<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
+        this.state = 'half-open'
+      } else {
+        throw new CircuitOpenError('Circuit is open')
+      }
+    }
+
+    try {
+      const result = await fn()
+      this.onSuccess()
+      return result
+    } catch (error) {
+      this.onFailure()
+      throw error
+    }
+  }
+
+  private onSuccess(): void {
+    this.failures = 0
+    this.state = 'closed'
+  }
+
+  private onFailure(): void {
+    this.failures++
+    this.lastFailureTime = Date.now()
+    if (this.failures >= this.threshold) {
+      this.state = 'open'
+    }
+  }
+}
+
+// Usage
+const userServiceBreaker = new CircuitBreaker(5, 30_000)
+const user = await userServiceBreaker.call(() => userClient.getUser(id))
+```
+
+### Saga Pattern for Distributed Transactions
+
+Coordinate multi-service operations as a sequence of local transactions with
+compensating actions for rollback. Use orchestration (central coordinator) or
+choreography (event-driven).
+
+```typescript
+// Orchestration-based saga
+class CreateOrderSaga {
+  private steps: SagaStep[] = [
+    {
+      name: 'reserve-inventory',
+      execute: (ctx) => inventoryService.reserve(ctx.items),
+      compensate: (ctx) => inventoryService.release(ctx.reservationId),
+    },
+    {
+      name: 'charge-payment',
+      execute: (ctx) => paymentService.charge(ctx.userId, ctx.total),
+      compensate: (ctx) => paymentService.refund(ctx.chargeId),
+    },
+    {
+      name: 'create-order',
+      execute: (ctx) => orderService.create(ctx),
+      compensate: (ctx) => orderService.cancel(ctx.orderId),
+    },
+  ]
+
+  async execute(context: SagaContext): Promise<void> {
+    const completed: SagaStep[] = []
+
+    for (const step of this.steps) {
+      try {
+        const result = await step.execute(context)
+        Object.assign(context, result)
+        completed.push(step)
+      } catch (error) {
+        // Compensate in reverse order
+        for (const completedStep of completed.reverse()) {
+          try {
+            await completedStep.compensate(context)
+          } catch (compError) {
+            console.error(`Compensation failed for ${completedStep.name}:`, compError)
+            // Log for manual intervention
+          }
+        }
+        throw new SagaFailedError(step.name, error)
+      }
+    }
+  }
+}
+```
+
+### Event Sourcing
+
+Store state changes as an immutable append-only log of events. Rebuild current
+state by replaying events. Use snapshots to avoid replaying from the beginning.
+
+```typescript
+interface DomainEvent {
+  eventId: string
+  aggregateId: string
+  type: string
+  data: Record<string, unknown>
+  timestamp: number
+  version: number
+}
+
+class EventStore {
+  async append(aggregateId: string, events: DomainEvent[], expectedVersion: number): Promise<void> {
+    // Optimistic concurrency: fail if version mismatch
+    const current = await this.getVersion(aggregateId)
+    if (current !== expectedVersion) {
+      throw new ConcurrencyError(`Expected version ${expectedVersion}, got ${current}`)
+    }
+    await this.db.insert('events', events)
+    await this.publishToStream(events)
+  }
+
+  async getEvents(aggregateId: string, afterVersion = 0): Promise<DomainEvent[]> {
+    return this.db.query(
+      'SELECT * FROM events WHERE aggregate_id = $1 AND version > $2 ORDER BY version',
+      [aggregateId, afterVersion]
+    )
+  }
+}
+
+// Rebuild state from events
+function rebuildOrder(events: DomainEvent[]): Order {
+  let order = Order.empty()
+  for (const event of events) {
+    switch (event.type) {
+      case 'OrderCreated': order = order.applyCreated(event.data); break
+      case 'ItemAdded': order = order.applyItemAdded(event.data); break
+      case 'OrderShipped': order = order.applyShipped(event.data); break
+    }
+  }
+  return order
+}
+```
+
+### API Gateway
+
+Single entry point for external clients. Routes requests, handles auth, rate
+limiting, and response aggregation. Keep it thin; no business logic.
+
+```typescript
+// Gateway route config
+const routes: GatewayRoute[] = [
+  { path: '/api/users/**', upstream: 'user-service', auth: true },
+  { path: '/api/orders/**', upstream: 'order-service', auth: true },
+  { path: '/api/public/**', upstream: 'content-service', auth: false },
+]
+
+// Responsibilities: routing, auth, rate limiting, logging
+// NOT responsibilities: business logic, data transformation, orchestration
+```
+
+### Health Checks
+
+Every service exposes `/healthz` (liveness) and `/readyz` (readiness). Liveness
+checks if the process is alive. Readiness checks if it can serve traffic.
+
+```typescript
+app.get('/healthz', (req, res) => {
+  res.json({ status: 'ok' })
+})
+
+app.get('/readyz', async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    upstream: await checkUpstreamService(),
+  }
+  const healthy = Object.values(checks).every(c => c.status === 'ok')
+  res.status(healthy ? 200 : 503).json({ status: healthy ? 'ready' : 'not ready', checks })
+})
+```
+
+## Examples
+
+**Pattern: Idempotency key for safe retries**
+```typescript
+app.post('/api/payments', async (req, res) => {
+  const idempotencyKey = req.headers['idempotency-key']
+  const existing = await cache.get(`idem:${idempotencyKey}`)
+  if (existing) return res.json(JSON.parse(existing))
+  const result = await processPayment(req.body)
+  await cache.set(`idem:${idempotencyKey}`, JSON.stringify(result), 'EX', 86400)
+  res.json(result)
+})
+```
+
+## Checklist
+
+- [ ] Services register/deregister with service discovery on startup/shutdown
+- [ ] Circuit breaker wraps all cross-service HTTP calls
+- [ ] Sagas with compensating actions for multi-service transactions
+- [ ] Idempotency keys on all mutating cross-service calls
+- [ ] Event sourcing with optimistic concurrency for critical aggregates
+- [ ] API gateway handles auth, routing, rate limiting (no business logic)
+- [ ] `/healthz` (liveness) and `/readyz` (readiness) on every service
+- [ ] Structured logging with correlation/trace IDs across all services
+- [ ] Timeouts and retries with exponential backoff on all outbound calls
+- [ ] Dead letter queues for failed event processing

package/assets/skills/migration-patterns.md

@@ -0,0 +1,239 @@
+---
+name: migration-patterns
+description: Data migration patterns for zero-downtime migrations, backfills, dual-write, and schema versioning.
+---
+
+# Data Migration Patterns
+
+## When to Use
+Apply when changing database schemas, moving data between systems, or evolving data formats in production. Zero-downtime migrations are essential for any service with an SLA. The expand-contract pattern prevents breaking running code. Schema versioning keeps teams aligned on changes.
+
+## How It Works
+
+### Zero-Downtime Schema Migration (Expand-Contract)
+
+Never rename, drop, or change a column type in one step:
+
+```sql
+-- Step 1: EXPAND -- add new column alongside old
+ALTER TABLE users ADD COLUMN display_name TEXT;
+
+-- Step 2: BACKFILL -- copy data in batches (see next section)
+-- Step 3: DEPLOY -- app writes to both columns
+-- Step 4: SWITCH -- app reads from new column only
+-- Step 5: CONTRACT -- drop old column after confirming no readers
+ALTER TABLE users DROP COLUMN name;
+```
+
+Each step is a separate deployment. Never combine expand and contract.
+
+### Backfill with Batching
+
+Process millions of rows without locking the table:
+
+```typescript
+async function backfillDisplayName(batchSize = 1000): Promise<number> {
+  let totalUpdated = 0;
+  let lastId = "";
+
+  while (true) {
+    const result = await db.query(`
+      UPDATE users
+      SET display_name = name
+      WHERE id IN (
+        SELECT id FROM users
+        WHERE display_name IS NULL AND id > $1
+        ORDER BY id LIMIT $2
+      )
+      RETURNING id
+    `, [lastId, batchSize]);
+
+    if (result.rows.length === 0) break;
+    totalUpdated += result.rows.length;
+    lastId = result.rows[result.rows.length - 1].id;
+    console.log(`Backfilled ${totalUpdated} rows, last ID: ${lastId}`);
+    await new Promise((r) => setTimeout(r, 100)); // throttle
+  }
+  return totalUpdated;
+}
+```
+
+### Dual-Write Pattern
+
+Migrate between data stores without downtime:
+
+```typescript
+class UserRepository {
+  constructor(
+    private oldDb: Database,
+    private newDb: Database,
+    private phase: "dual-write" | "dual-read" | "new-only"
+  ) {}
+
+  async save(user: User): Promise<void> {
+    switch (this.phase) {
+      case "dual-write":
+        await this.oldDb.save(user);
+        await this.newDb.save(user).catch((err) =>
+          logger.error({ err, userId: user.id }, "New DB write failed")
+        );
+        break;
+      case "dual-read":
+        await Promise.all([this.newDb.save(user), this.oldDb.save(user)]);
+        break;
+      case "new-only":
+        await this.newDb.save(user);
+        break;
+    }
+  }
+
+  async findById(id: string): Promise<User | null> {
+    switch (this.phase) {
+      case "dual-write":
+        return this.oldDb.findById(id);
+      case "dual-read": {
+        const [newResult, oldResult] = await Promise.all([
+          this.newDb.findById(id),
+          this.oldDb.findById(id),
+        ]);
+        if (JSON.stringify(newResult) !== JSON.stringify(oldResult)) {
+          logger.warn({ id }, "Data mismatch between old and new DB");
+        }
+        return newResult;
+      }
+      case "new-only":
+        return this.newDb.findById(id);
+    }
+  }
+}
+```
+
+### Schema Versioning with Migration Files
+
+```typescript
+// migrations/001_create_users.ts
+import { Knex } from "knex";
+
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.createTable("users", (table) => {
+    table.uuid("id").primary().defaultTo(knex.fn.uuid());
+    table.string("email").notNullable().unique();
+    table.string("name").notNullable();
+    table.timestamp("created_at").defaultTo(knex.fn.now());
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.dropTable("users");
+}
+```
+
+```typescript
+// migrations/002_add_display_name.ts
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("users", (table) => {
+    table.string("display_name"); // nullable first
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("users", (table) => {
+    table.dropColumn("display_name");
+  });
+}
+```
+
+### Data Validation After Migration
+
+```typescript
+async function validateMigration(): Promise<{ isValid: boolean; details: string }> {
+  const [oldCount, newCount] = await Promise.all([
+    db.query("SELECT COUNT(*) FROM old_users"),
+    db.query("SELECT COUNT(*) FROM users"),
+  ]);
+
+  const mismatches = await db.query(`
+    SELECT o.id, o.email AS old_email, n.email AS new_email
+    FROM old_users o
+    LEFT JOIN users n ON o.id = n.id
+    WHERE o.email != n.email OR n.id IS NULL
+    LIMIT 100
+  `);
+
+  return {
+    isValid: mismatches.rows.length === 0,
+    details: `Old: ${oldCount.rows[0].count}, New: ${newCount.rows[0].count}, Mismatches: ${mismatches.rows.length}`,
+  };
+}
+```
+
+### Rollback Strategy with Step Tracking
+
+```typescript
+interface MigrationStep {
+  name: string;
+  forward: () => Promise<void>;
+  rollback: () => Promise<void>;
+  validate: () => Promise<boolean>;
+}
+
+async function executeMigration(steps: MigrationStep[]): Promise<void> {
+  const completed: MigrationStep[] = [];
+
+  for (const step of steps) {
+    try {
+      await step.forward();
+      const valid = await step.validate();
+      if (!valid) throw new Error(`Validation failed: ${step.name}`);
+      completed.push(step);
+      logger.info(`Completed: ${step.name}`);
+    } catch (err) {
+      logger.error({ err }, `Failed at ${step.name}, rolling back`);
+      for (const done of completed.reverse()) {
+        await done.rollback();
+        logger.info(`Rolled back: ${done.name}`);
+      }
+      throw err;
+    }
+  }
+}
+```
+
+### Dangerous Operations to Avoid
+
+```sql
+-- NEVER on large tables (locks table in PG < 11):
+ALTER TABLE users ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
+
+-- SAFE alternative:
+ALTER TABLE users ADD COLUMN status TEXT;
+-- backfill, then:
+ALTER TABLE users ALTER COLUMN status SET NOT NULL;
+ALTER TABLE users ALTER COLUMN status SET DEFAULT 'active';
+
+-- NEVER without CONCURRENTLY:
+CREATE INDEX idx_users_email ON users (email);
+-- SAFE:
+CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| Expand-contract | Column rename/type change | Zero downtime, reversible |
+| Batched backfill | Millions of rows | No table locks, throttled |
+| Dual-write | Database migration | Verify before cutover |
+| Schema versioning | Team collaboration | Ordered, repeatable |
+| Post-validation | Every migration | Catch data loss early |
+| Rollback plan | Every migration | Recover from failures |
+
+## Checklist
+- [ ] Schema changes use expand-contract, never direct rename/drop
+- [ ] Backfills process in batches with throttling
+- [ ] Dual-write validates consistency before switching reads
+- [ ] Every migration has a tested rollback procedure
+- [ ] Migration scripts are idempotent (safe to run twice)
+- [ ] Data validation runs after every migration step
+- [ ] New columns are nullable until backfill completes
+- [ ] `CREATE INDEX` always uses `CONCURRENTLY`

package/assets/skills/mongodb-patterns.md

@@ -0,0 +1,189 @@
+---
+name: mongodb-patterns
+description: MongoDB patterns for schema design, aggregation pipeline, indexes, change streams, and transactions.
+---
+
+# MongoDB Patterns
+
+## When to Use
+Use MongoDB when your data is document-shaped, schemas evolve frequently, or you need flexible nested structures. Apply these patterns for schema design decisions (embed vs. reference), aggregation pipelines for analytics, index tuning, multi-document transactions, and change streams for real-time event processing.
+
+## How It Works
+
+### Schema Design -- Embed vs. Reference
+
+**Embed** when data is always read together and the embedded array stays small:
+
+```javascript
+// Good embed: address always read with user, 1:few relationship
+{
+  _id: ObjectId("..."),
+  name: "Alice",
+  email: "alice@example.com",
+  addresses: [
+    { label: "home", street: "123 Main St", city: "Austin", zip: "78701" },
+    { label: "work", street: "456 Tech Blvd", city: "Austin", zip: "78702" }
+  ]
+}
+```
+
+**Reference** when related data is large, grows unbounded, or queried independently:
+
+```javascript
+// Orders reference user by ID
+{
+  _id: ObjectId("..."),
+  userId: ObjectId("..."),
+  items: [
+    { sku: "WIDGET-1", qty: 3, price: 1299 },
+    { sku: "GADGET-2", qty: 1, price: 4599 }
+  ],
+  totalCents: 8496,
+  status: "shipped",
+  createdAt: ISODate("2026-05-01T10:00:00Z")
+}
+```
+
+| Factor | Embed | Reference |
+|--------|-------|-----------|
+| Read together? | Always | Sometimes |
+| Array growth | Bounded (< 100) | Unbounded |
+| Update frequency | Low | High |
+| Data size | < 16MB doc limit | Any size |
+
+### Aggregation Pipeline
+
+```javascript
+// Monthly revenue by product category
+db.orders.aggregate([
+  { $match: { status: "paid", createdAt: { $gte: ISODate("2026-01-01") } } },
+  { $unwind: "$items" },
+  { $lookup: {
+      from: "products",
+      localField: "items.sku",
+      foreignField: "sku",
+      as: "product"
+  }},
+  { $unwind: "$product" },
+  { $group: {
+      _id: {
+        month: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
+        category: "$product.category"
+      },
+      revenue: { $sum: { $multiply: ["$items.qty", "$items.price"] } },
+      orderCount: { $sum: 1 }
+  }},
+  { $sort: { "_id.month": 1, revenue: -1 } }
+]);
+```
+
+Put `$match` first to leverage indexes. Use `$project` to drop unneeded fields before `$lookup`.
+
+### Indexes
+
+```javascript
+// Compound index matching common query pattern
+db.orders.createIndex({ userId: 1, createdAt: -1 });
+
+// Text index for search
+db.products.createIndex({ name: "text", description: "text" });
+
+// TTL index for auto-expiry
+db.sessions.createIndex({ lastAccess: 1 }, { expireAfterSeconds: 86400 });
+
+// Partial index -- only index active documents
+db.users.createIndex(
+  { email: 1 },
+  { unique: true, partialFilterExpression: { status: "active" } }
+);
+```
+
+Verify with `explain("executionStats")`:
+
+```javascript
+db.orders.find({ userId: id }).sort({ createdAt: -1 }).explain("executionStats");
+// Look for: winningPlan.stage === "IXSCAN", totalDocsExamined close to nReturned
+```
+
+### Transactions -- Multi-Document Atomicity
+
+```javascript
+const session = client.startSession();
+try {
+  session.startTransaction();
+  await orders.insertOne({ userId, items, totalCents }, { session });
+  await inventory.updateMany(
+    { sku: { $in: skus } },
+    { $inc: { reserved: 1 } },
+    { session }
+  );
+  await session.commitTransaction();
+} catch (err) {
+  await session.abortTransaction();
+  throw err;
+} finally {
+  session.endSession();
+}
+```
+
+Transactions require a replica set. Keep them short -- they hold locks.
+
+### Change Streams -- Real-Time Events
+
+```javascript
+const pipeline = [
+  { $match: { operationType: { $in: ["insert", "update"] } } }
+];
+const changeStream = db.collection("orders").watch(pipeline, {
+  fullDocument: "updateLookup",
+});
+
+changeStream.on("change", (event) => {
+  if (event.operationType === "insert") {
+    notifyWarehouse(event.fullDocument);
+  }
+  if (event.operationType === "update" && event.fullDocument.status === "shipped") {
+    sendTrackingEmail(event.fullDocument);
+  }
+});
+```
+
+Store the resume token (`event._id`) to survive restarts.
+
+### Schema Validation
+
+```javascript
+db.createCollection("users", {
+  validator: {
+    $jsonSchema: {
+      bsonType: "object",
+      required: ["email", "name"],
+      properties: {
+        email: { bsonType: "string", pattern: "^.+@.+\\..+$" },
+        name: { bsonType: "string", minLength: 1 },
+        status: { enum: ["active", "inactive", "suspended"] },
+      },
+    },
+  },
+});
+```
+
+## Examples
+
+| Pattern | Use Case | Key Benefit |
+|---------|----------|-------------|
+| Embedded docs | User + addresses | Single read, atomic write |
+| Referenced docs | Orders + products | Independent scaling |
+| Aggregation | Revenue dashboards | Server-side analytics |
+| TTL index | Session cleanup | Automatic expiry |
+| Change streams | Order notifications | Real-time, resumable |
+
+## Checklist
+- [ ] Schema decision (embed vs. reference) documented per collection
+- [ ] No embedded arrays that grow unbounded
+- [ ] Compound indexes match equality-sort-range (ESR) rule
+- [ ] `explain()` confirms IXSCAN for all hot queries
+- [ ] TTL indexes handle session/token expiry automatically
+- [ ] Aggregation pipelines put `$match` first
+- [ ] Multi-document writes use transactions
+- [ ] Change streams store resume tokens for crash recovery