@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/mongoose-nestjs/steering/transactions.md

@@ -0,0 +1,445 @@
+# MongoDB Transactions with Mongoose
+
+> Reference for: Mongoose NestJS
+> Load when: ACID operations, multi-document updates, session handling, retry logic, race conditions
+
+---
+
+## Overview
+
+MongoDB transactions ensure ACID compliance for multi-document operations. Use transactions when you need to update multiple documents atomically - either all changes succeed or all are rolled back.
+
+## When to Use Transactions
+
+**Use transactions for:**
+- Creating related documents together (user + profile)
+- Updating multiple collections atomically
+- Preventing race conditions (check-in/check-out)
+- Financial operations (transfers, payments)
+- Inventory management (stock updates)
+
+**Don't use transactions for:**
+- Single document operations (already atomic)
+- Read-only queries
+- Operations that can tolerate eventual consistency
+
+---
+
+## Transaction Helper
+
+```typescript
+// src/database/transaction.helper.ts
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection, ClientSession } from 'mongoose';
+
+export type TransactionCallback<T> = (session: ClientSession) => Promise<T>;
+
+@Injectable()
+export class TransactionHelper {
+  private readonly logger = new Logger(TransactionHelper.name);
+
+  constructor(
+    @InjectConnection()
+    private readonly connection: Connection,
+  ) {}
+
+  /**
+   * Execute callback within a transaction
+   */
+  async withTransaction<T>(callback: TransactionCallback<T>): Promise<T> {
+    const session = await this.connection.startSession();
+
+    try {
+      session.startTransaction({
+        readConcern: { level: 'snapshot' },
+        writeConcern: { w: 'majority' },
+      });
+
+      const result = await callback(session);
+
+      await session.commitTransaction();
+      return result;
+    } catch (error) {
+      await session.abortTransaction();
+      this.logger.error(`Transaction aborted: ${error.message}`, error.stack);
+      throw error;
+    } finally {
+      session.endSession();
+    }
+  }
+
+  /**
+   * Execute with automatic retry on transient errors
+   */
+  async withRetry<T>(
+    callback: TransactionCallback<T>,
+    maxRetries = 3,
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.withTransaction(callback);
+      } catch (error) {
+        lastError = error as Error;
+
+        if (this.isTransientError(error)) {
+          this.logger.warn(
+            `Transient error on attempt ${attempt}/${maxRetries}: ${error.message}`,
+          );
+          await this.delay(Math.pow(2, attempt) * 100); // Exponential backoff
+          continue;
+        }
+
+        // Non-transient error, don't retry
+        throw error;
+      }
+    }
+
+    this.logger.error(`Transaction failed after ${maxRetries} attempts`);
+    throw lastError;
+  }
+
+  /**
+   * Check if error is transient (retryable)
+   */
+  private isTransientError(error: unknown): boolean {
+    const transientCodes = [
+      112,  // WriteConflict
+      117,  // ConflictingOperationInProgress
+      204,  // NoSuchTransaction
+      251,  // TransactionAborted
+      11600, // InterruptedAtShutdown
+      11601, // Interrupted
+      11602, // InterruptedDueToReplStateChange
+    ];
+
+    const code = (error as { code?: number })?.code;
+    const hasTransientLabel = (error as { errorLabels?: string[] })
+      ?.errorLabels?.includes('TransientTransactionError');
+
+    return (code !== undefined && transientCodes.includes(code)) || hasTransientLabel;
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## Using Transactions in Services
+
+### Basic Transaction
+
+```typescript
+// src/modules/users/users.service.ts
+import { Injectable } from '@nestjs/common';
+import { TransactionHelper } from '../../database/transaction.helper';
+import { UsersRepository } from './users.repository';
+import { ProfilesRepository } from '../profiles/profiles.repository';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly transactionHelper: TransactionHelper,
+    private readonly usersRepository: UsersRepository,
+    private readonly profilesRepository: ProfilesRepository,
+  ) {}
+
+  async createUserWithProfile(dto: CreateUserDto): Promise<UserResponseDto> {
+    return this.transactionHelper.withTransaction(async (session) => {
+      // Create user
+      const user = await this.usersRepository.create(
+        {
+          username: dto.username,
+          password: hashedPassword,
+          organizationId: dto.organizationId,
+        },
+        session,
+      );
+
+      // Create profile (in same transaction)
+      await this.profilesRepository.create(
+        {
+          userId: user._id.toString(),
+          name: dto.name,
+          email: dto.email,
+        },
+        session,
+      );
+
+      return UserResponseDto.from(user);
+    });
+  }
+}
+```
+
+### Transaction with Retry (Race Condition Prevention)
+
+```typescript
+// src/modules/attendance/attendance.service.ts
+import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
+import { TransactionHelper } from '../../database/transaction.helper';
+
+@Injectable()
+export class AttendanceService {
+  constructor(
+    private readonly transactionHelper: TransactionHelper,
+    private readonly attendanceRepository: AttendanceRepository,
+    private readonly usersRepository: UsersRepository,
+    private readonly summaryRepository: SummaryRepository,
+  ) {}
+
+  async checkIn(userId: string, dto: CheckInDto): Promise<AttendanceResponseDto> {
+    return this.transactionHelper.withRetry(async (session) => {
+      // 1. Check for existing attendance today (with session lock)
+      const today = new Date();
+      const startOfDay = new Date(today.setHours(0, 0, 0, 0)).getTime();
+      const endOfDay = new Date(today.setHours(23, 59, 59, 999)).getTime();
+
+      const existing = await this.attendanceRepository.findOne(
+        {
+          userId,
+          checkInDateTime: { $gte: startOfDay, $lte: endOfDay },
+        },
+        session,
+      );
+
+      if (existing) {
+        throw new ConflictException('Already checked in today');
+      }
+
+      // 2. Get user details
+      const user = await this.usersRepository.findById(userId, undefined, session);
+      if (!user) {
+        throw new NotFoundException('User not found');
+      }
+
+      // 3. Create attendance record
+      const attendance = await this.attendanceRepository.create(
+        {
+          userId,
+          organizationId: user.organizationId,
+          departmentId: user.departmentId,
+          checkInDateTime: dto.timestamp,
+          checkInLocation: dto.location,
+          checkInType: dto.method,
+        },
+        session,
+      );
+
+      // 4. Update daily summary (atomic increment)
+      await this.summaryRepository.incrementCheckIn(
+        userId,
+        startOfDay,
+        session,
+      );
+
+      return AttendanceResponseDto.from(attendance);
+    });
+  }
+
+  async checkOut(userId: string, dto: CheckOutDto): Promise<AttendanceResponseDto> {
+    return this.transactionHelper.withRetry(async (session) => {
+      // Find today's attendance
+      const today = new Date();
+      const startOfDay = new Date(today.setHours(0, 0, 0, 0)).getTime();
+
+      const attendance = await this.attendanceRepository.findOne(
+        {
+          userId,
+          checkInDateTime: { $gte: startOfDay },
+          checkOutDateTime: { $exists: false },
+        },
+        session,
+      );
+
+      if (!attendance) {
+        throw new NotFoundException('No active check-in found');
+      }
+
+      // Calculate working hours
+      const workingHours = this.calculateWorkingHours(
+        attendance.checkInDateTime,
+        dto.timestamp,
+      );
+
+      // Update attendance
+      const updated = await this.attendanceRepository.update(
+        attendance._id.toString(),
+        {
+          checkOutDateTime: dto.timestamp,
+          checkOutLocation: dto.location,
+          workingHours,
+        },
+        session,
+      );
+
+      // Update summary
+      await this.summaryRepository.addWorkingHours(
+        userId,
+        startOfDay,
+        workingHours,
+        session,
+      );
+
+      return AttendanceResponseDto.from(updated);
+    });
+  }
+}
+```
+
+---
+
+## Repository Methods with Session Support
+
+```typescript
+// Ensure all repository methods accept optional session parameter
+export class AttendanceRepository extends BaseRepository<AttendanceDocument> {
+  async findTodayAttendance(
+    userId: string,
+    session?: ClientSession,
+  ): Promise<AttendanceDocument | null> {
+    const today = new Date();
+    const startOfDay = new Date(today.setHours(0, 0, 0, 0)).getTime();
+    const endOfDay = new Date(today.setHours(23, 59, 59, 999)).getTime();
+
+    return this.model
+      .findOne({
+        userId,
+        checkInDateTime: { $gte: startOfDay, $lte: endOfDay },
+      })
+      .session(session)
+      .exec();
+  }
+
+  async incrementCheckInCount(
+    userId: string,
+    date: number,
+    session?: ClientSession,
+  ): Promise<void> {
+    await this.model
+      .updateOne(
+        { userId, date },
+        { $inc: { checkInCount: 1 } },
+        { upsert: true },
+      )
+      .session(session)
+      .exec();
+  }
+}
+```
+
+---
+
+## Optimistic Locking Pattern
+
+For high-concurrency scenarios, use version-based optimistic locking:
+
+```typescript
+// Schema with version field
+@Schema({ timestamps: true, optimisticConcurrency: true })
+export class Inventory {
+  @Prop({ required: true })
+  productId: string;
+
+  @Prop({ required: true })
+  quantity: number;
+
+  // Mongoose adds __v field automatically with optimisticConcurrency: true
+}
+
+// Service with optimistic locking
+async decrementStock(productId: string, amount: number): Promise<void> {
+  const maxRetries = 3;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const inventory = await this.inventoryRepository.findOne({ productId });
+      
+      if (!inventory) {
+        throw new NotFoundException('Product not found');
+      }
+
+      if (inventory.quantity < amount) {
+        throw new BadRequestException('Insufficient stock');
+      }
+
+      // This will fail if __v changed (concurrent modification)
+      await this.inventoryRepository.update(inventory._id, {
+        quantity: inventory.quantity - amount,
+      });
+
+      return;
+    } catch (error) {
+      if (error.name === 'VersionError' && attempt < maxRetries) {
+        // Retry on version conflict
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new ConflictException('Failed to update stock after retries');
+}
+```
+
+---
+
+## Distributed Transactions (Multi-Database)
+
+For operations spanning multiple databases, use the Saga pattern:
+
+```typescript
+// Saga pattern for distributed transactions
+async transferFunds(fromAccount: string, toAccount: string, amount: number): Promise<void> {
+  // Step 1: Debit source account
+  const debitResult = await this.accountsService.debit(fromAccount, amount);
+  
+  try {
+    // Step 2: Credit destination account
+    await this.accountsService.credit(toAccount, amount);
+  } catch (error) {
+    // Compensating transaction: Reverse the debit
+    await this.accountsService.credit(fromAccount, amount);
+    throw error;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### DO
+
+- Always pass session to all operations within a transaction
+- Use `withRetry` for operations prone to write conflicts
+- Keep transactions short (< 60 seconds)
+- Handle `TransientTransactionError` with retries
+- Use read concern `snapshot` for consistent reads
+
+### DON'T
+
+- Hold transactions open while waiting for user input
+- Perform non-database operations inside transactions
+- Ignore transaction timeout limits
+- Use transactions for single-document operations
+- Nest transactions (MongoDB doesn't support it)
+
+---
+
+## MongoDB Requirements
+
+Transactions require:
+- MongoDB 4.0+ for replica sets
+- MongoDB 4.2+ for sharded clusters
+- Replica set or sharded cluster (not standalone)
+
+```bash
+# Check if replica set is configured
+mongosh --eval "rs.status()"
+```

package/Ai Agent Workflow/powers/monitoring-expert/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: monitoring-expert
+description: Use when setting up monitoring systems, logging, metrics, tracing, or alerting. Invoke for dashboards, Prometheus/Grafana, load testing, profiling, capacity planning.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: devops
+  triggers: monitoring, observability, logging, metrics, tracing, alerting, Prometheus, Grafana, DataDog, APM, performance testing, load testing, profiling, capacity planning, bottleneck
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer, debugging-wizard, architecture-designer
+---
+
+# Monitoring Expert
+
+Observability and performance specialist implementing comprehensive monitoring, alerting, tracing, and performance testing systems.
+
+## Role Definition
+
+You are a senior SRE with 10+ years of experience in production systems. You specialize in the three pillars of observability: logs, metrics, and traces. You build monitoring systems that enable quick incident response, proactive issue detection, and performance optimization.
+
+## When to Use This Skill
+
+- Setting up application monitoring
+- Implementing structured logging
+- Creating metrics and dashboards
+- Configuring alerting rules
+- Implementing distributed tracing
+- Debugging production issues with observability
+- Performance testing and load testing
+- Application profiling and bottleneck analysis
+- Capacity planning and resource forecasting
+
+## Core Workflow
+
+1. **Assess** - Identify what needs monitoring
+2. **Instrument** - Add logging, metrics, traces
+3. **Collect** - Set up aggregation and storage
+4. **Visualize** - Create dashboards
+5. **Alert** - Configure meaningful alerts
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Logging | `steering/structured-logging.md` | Pino, JSON logging |
+| Metrics | `steering/prometheus-metrics.md` | Counter, Histogram, Gauge |
+| Tracing | `steering/opentelemetry.md` | OpenTelemetry, spans |
+| Alerting | `steering/alerting-rules.md` | Prometheus alerts |
+| Dashboards | `steering/dashboards.md` | RED/USE method, Grafana |
+| Performance Testing | `steering/performance-testing.md` | Load testing, k6, Artillery, benchmarks |
+| Profiling | `steering/application-profiling.md` | CPU/memory profiling, bottlenecks |
+| Capacity Planning | `steering/capacity-planning.md` | Scaling, forecasting, budgets |
+
+## Constraints
+
+### MUST DO
+- Use structured logging (JSON)
+- Include request IDs for correlation
+- Set up alerts for critical paths
+- Monitor business metrics, not just technical
+- Use appropriate metric types (counter/gauge/histogram)
+- Implement health check endpoints
+
+### MUST NOT DO
+- Log sensitive data (passwords, tokens, PII)
+- Alert on every error (alert fatigue)
+- Use string interpolation in logs (use structured fields)
+- Skip correlation IDs in distributed systems
+
+## Knowledge Reference
+
+Prometheus, Grafana, ELK Stack, Loki, Jaeger, OpenTelemetry, DataDog, New Relic, CloudWatch, structured logging, RED metrics, USE method, k6, Artillery, Locust, JMeter, clinic.js, pprof, py-spy, async-profiler, capacity planning

package/Ai Agent Workflow/powers/monitoring-expert/steering/alerting-rules.md

@@ -0,0 +1,141 @@
+# Alerting Rules
+
+## Prometheus Alert Rules
+
+```yaml
+# alerts.yml
+groups:
+  - name: application
+    rules:
+      - alert: HighErrorRate
+        expr: |
+          sum(rate(http_requests_total{status=~"5.."}[5m]))
+          /
+          sum(rate(http_requests_total[5m])) > 0.05
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: High error rate detected
+          description: Error rate is {{ $value | humanizePercentage }}
+
+      - alert: HighLatency
+        expr: |
+          histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: High latency detected
+          description: 95th percentile latency is {{ $value }}s
+
+      - alert: ServiceDown
+        expr: up == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: Service {{ $labels.instance }} is down
+
+  - name: infrastructure
+    rules:
+      - alert: HighMemoryUsage
+        expr: |
+          (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes)
+          / node_memory_MemTotal_bytes > 0.9
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: High memory usage on {{ $labels.instance }}
+
+      - alert: HighCPUUsage
+        expr: |
+          100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: High CPU usage on {{ $labels.instance }}
+
+      - alert: DiskSpaceLow
+        expr: |
+          (node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.1
+        for: 5m
+        labels:
+          severity: critical
+        annotations:
+          summary: Disk space low on {{ $labels.instance }}
+```
+
+## Alert Design Principles
+
+```yaml
+# Good alert: Actionable, specific
+- alert: DatabaseConnectionPoolExhausted
+  expr: db_pool_available_connections == 0
+  for: 2m
+  annotations:
+    runbook_url: https://wiki.example.com/runbooks/db-pool
+
+# Bad alert: Too noisy, not actionable
+- alert: AnyError
+  expr: errors_total > 0  # Will always fire
+```
+
+## Severity Levels
+
+| Severity | Response | Example |
+|----------|----------|---------|
+| `critical` | Page immediately | Service down, data loss |
+| `warning` | Investigate soon | High latency, low disk |
+| `info` | Check in morning | Unusual traffic pattern |
+
+## Alertmanager Configuration
+
+```yaml
+# alertmanager.yml
+global:
+  slack_api_url: 'https://hooks.slack.com/...'
+
+route:
+  receiver: 'slack-notifications'
+  group_by: ['alertname', 'severity']
+  group_wait: 30s
+  group_interval: 5m
+  repeat_interval: 4h
+
+  routes:
+    - match:
+        severity: critical
+      receiver: 'pagerduty'
+    - match:
+        severity: warning
+      receiver: 'slack-notifications'
+
+receivers:
+  - name: 'slack-notifications'
+    slack_configs:
+      - channel: '#alerts'
+        send_resolved: true
+
+  - name: 'pagerduty'
+    pagerduty_configs:
+      - service_key: 'your-key'
+```
+
+## Quick Reference
+
+| Field | Purpose |
+|-------|---------|
+| `expr` | PromQL query |
+| `for` | Duration before firing |
+| `labels` | Classification (severity) |
+| `annotations` | Human-readable info |
+
+| Threshold | Use |
+|-----------|-----|
+| Error rate > 5% | Critical |
+| p95 latency > 1s | Warning |
+| Disk < 10% | Critical |
+| Memory > 90% | Warning |