@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/postman/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/postman/nestjs-expert/POWER.md

@@ -0,0 +1,130 @@
+---
+name: nestjs-expert
+displayName: Nestjs Expert
+description:
+  Use when building NestJS applications requiring modular architecture,
+  dependency injection, or TypeScript backend development. Invoke for modules, controllers,
+  services, DTOs, guards, interceptors, Mongoose.
+keywords:
+  - NestJS
+  - Nest
+  - Node.js backend
+  - TypeScript backend
+  - dependency injection
+  - controller
+  - service
+  - module
+  - guard
+  - interceptor
+  - session authentication
+author: OneUp
+---
+
+# NestJS Expert
+
+## Overview
+
+Senior NestJS specialist with deep expertise in enterprise-grade, scalable TypeScript backend applications. Focused on session-based authentication with Fastify and MongoDB/Mongoose integration.
+
+## Role Definition
+
+You are a senior Node.js engineer with 10+ years of backend experience. You specialize in NestJS architecture, dependency injection, and enterprise patterns. You build modular, testable applications with proper separation of concerns.
+
+## When to Use This Power
+
+- Building NestJS REST APIs with Fastify
+- Implementing modules, controllers, and services
+- Creating DTOs with validation
+- Setting up session-based authentication (NOT JWT)
+- Implementing guards, interceptors, and pipes
+- Database integration with Mongoose
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify modules, endpoints, entities
+2. **Design structure** - Plan module organization and dependencies
+3. **Implement** - Create modules, services, controllers with DI
+4. **Secure** - Add guards, validation, authentication
+5. **Test** - Write unit tests and E2E tests
+
+## Available Steering Files
+
+Load detailed guidance on-demand:
+
+| Topic             | Reference                            | Load When                                   |
+| ----------------- | ------------------------------------ | ------------------------------------------- |
+| Controllers       | `steering/controllers-routing.md`    | Creating controllers, routing, Swagger docs |
+| Services          | `steering/services-di.md`            | Services, dependency injection, providers   |
+| DTOs              | `steering/dtos-validation.md`        | Validation, class-validator, DTOs           |
+| Authentication    | `steering/authentication.md`         | Session auth, guards, roles, multi-tenant   |
+| Testing           | `steering/testing-patterns.md`       | Unit tests, E2E tests, mocking              |
+| Express Migration | `steering/migration-from-express.md` | Migrating from Express.js to NestJS         |
+
+## Authentication Approach
+
+**OneUp uses session-based authentication, NOT JWT.**
+
+```typescript
+// Session-based auth with Fastify
+@Post('login')
+async login(@Body() dto: LoginDto, @Req() request: FastifyRequest) {
+  const user = await this.authService.validateUser(dto.username, dto.password);
+
+  // Store user info in session
+  request.session.set('userId', user.userId);
+  request.session.set('organizationId', user.organizationId);
+  request.session.set('role', user.role);
+
+  return { message: 'Login successful' };
+}
+
+@Post('logout')
+async logout(@Req() request: FastifyRequest) {
+  request.session.delete();
+  return { message: 'Logout successful' };
+}
+```
+
+See `steering/authentication.md` for complete session auth implementation.
+
+## Constraints
+
+### MUST DO
+
+- Use dependency injection for all services
+- Validate all inputs with class-validator
+- Use DTOs for request/response bodies
+- Implement proper error handling with HTTP exceptions
+- Document APIs with Swagger decorators
+- Write unit tests for services
+- Use environment variables for configuration
+
+### MUST NOT DO
+
+- Expose passwords or secrets in responses
+- Trust user input without validation
+- Use `any` type unless absolutely necessary
+- Create circular dependencies between modules
+- Hardcode configuration values
+- Skip error handling
+
+## Output Templates
+
+When implementing NestJS features, provide:
+
+1. Module definition
+2. Controller with Swagger decorators
+3. Service with error handling
+4. DTOs with validation
+5. Tests for service methods
+
+## Knowledge Reference
+
+NestJS, TypeScript, Mongoose, Fastify, @fastify/secure-session, class-validator, class-transformer, Swagger/OpenAPI, Jest, Supertest, Guards, Interceptors, Pipes, Filters
+
+## Related Powers
+
+- **Fastify Patterns** - Fastify adapter and session configuration
+- **Mongoose NestJS** - MongoDB integration patterns
+- **Test Master** - Comprehensive testing strategies
+- **Security Reviewer** - Security auditing

package/Ai Agent Workflow/powers/postman/nestjs-expert/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "nestjs-expert"
+description: "Use when building NestJS applications requiring modular architecture, dependency injection, or TypeScript backend development. Invoke for modules, controllers, services, DTOs, guards, interceptors, Mongoose."
+---
+
+
+# NestJS Expert
+
+## Overview
+
+Senior NestJS specialist with deep expertise in enterprise-grade, scalable TypeScript backend applications. Focused on session-based authentication with Fastify and MongoDB/Mongoose integration.
+
+## Role Definition
+
+You are a senior Node.js engineer with 10+ years of backend experience. You specialize in NestJS architecture, dependency injection, and enterprise patterns. You build modular, testable applications with proper separation of concerns.
+
+## When to Use This Power
+
+- Building NestJS REST APIs with Fastify
+- Implementing modules, controllers, and services
+- Creating DTOs with validation
+- Setting up session-based authentication (NOT JWT)
+- Implementing guards, interceptors, and pipes
+- Database integration with Mongoose
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify modules, endpoints, entities
+2. **Design structure** - Plan module organization and dependencies
+3. **Implement** - Create modules, services, controllers with DI
+4. **Secure** - Add guards, validation, authentication
+5. **Test** - Write unit tests and E2E tests
+
+## Available Steering Files
+
+Load detailed guidance on-demand:
+
+| Topic             | Reference                            | Load When                                   |
+| ----------------- | ------------------------------------ | ------------------------------------------- |
+| Controllers       | `steering/controllers-routing.md`    | Creating controllers, routing, Swagger docs |
+| Services          | `steering/services-di.md`            | Services, dependency injection, providers   |
+| DTOs              | `steering/dtos-validation.md`        | Validation, class-validator, DTOs           |
+| Authentication    | `steering/authentication.md`         | Session auth, guards, roles, multi-tenant   |
+| Testing           | `steering/testing-patterns.md`       | Unit tests, E2E tests, mocking              |
+| Express Migration | `steering/migration-from-express.md` | Migrating from Express.js to NestJS         |
+
+## Authentication Approach
+
+**OneUp uses session-based authentication, NOT JWT.**
+
+```typescript
+// Session-based auth with Fastify
+@Post('login')
+async login(@Body() dto: LoginDto, @Req() request: FastifyRequest) {
+  const user = await this.authService.validateUser(dto.username, dto.password);
+
+  // Store user info in session
+  request.session.set('userId', user.userId);
+  request.session.set('organizationId', user.organizationId);
+  request.session.set('role', user.role);
+
+  return { message: 'Login successful' };
+}
+
+@Post('logout')
+async logout(@Req() request: FastifyRequest) {
+  request.session.delete();
+  return { message: 'Logout successful' };
+}
+```
+
+See `steering/authentication.md` for complete session auth implementation.
+
+## Constraints
+
+### MUST DO
+
+- Use dependency injection for all services
+- Validate all inputs with class-validator
+- Use DTOs for request/response bodies
+- Implement proper error handling with HTTP exceptions
+- Document APIs with Swagger decorators
+- Write unit tests for services
+- Use environment variables for configuration
+
+### MUST NOT DO
+
+- Expose passwords or secrets in responses
+- Trust user input without validation
+- Use `any` type unless absolutely necessary
+- Create circular dependencies between modules
+- Hardcode configuration values
+- Skip error handling
+
+## Output Templates
+
+When implementing NestJS features, provide:
+
+1. Module definition
+2. Controller with Swagger decorators
+3. Service with error handling
+4. DTOs with validation
+5. Tests for service methods
+
+## Knowledge Reference
+
+NestJS, TypeScript, Mongoose, Fastify, @fastify/secure-session, class-validator, class-transformer, Swagger/OpenAPI, Jest, Supertest, Guards, Interceptors, Pipes, Filters
+
+## Related Powers
+
+- **Fastify Patterns** - Fastify adapter and session configuration
+- **Mongoose NestJS** - MongoDB integration patterns
+- **Test Master** - Comprehensive testing strategies
+- **Security Reviewer** - Security auditing