@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/performance-testing.md

@@ -0,0 +1,269 @@
+# Performance Testing
+
+## Load Testing with k6
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate } from 'k6/metrics';
+
+const errorRate = new Rate('errors');
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },  // Ramp-up to 100 users
+    { duration: '5m', target: 100 },  // Stay at 100 users
+    { duration: '2m', target: 200 },  // Ramp-up to 200 users
+    { duration: '5m', target: 200 },  // Stay at 200 users
+    { duration: '2m', target: 0 },    // Ramp-down to 0 users
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],
+    http_req_failed: ['rate<0.01'],
+    errors: ['rate<0.1'],
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/products');
+
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 500ms': (r) => r.timings.duration < 500,
+  }) || errorRate.add(1);
+
+  sleep(1);
+}
+```
+
+## Test Types
+
+### Load Test
+```javascript
+// Gradual ramp-up to expected production load
+export const options = {
+  stages: [
+    { duration: '5m', target: 100 },
+    { duration: '30m', target: 100 },
+    { duration: '5m', target: 0 },
+  ],
+};
+```
+
+### Stress Test
+```javascript
+// Push beyond normal capacity to find breaking point
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },
+    { duration: '5m', target: 200 },
+    { duration: '5m', target: 300 },
+    { duration: '5m', target: 400 },
+    { duration: '2m', target: 0 },
+  ],
+};
+```
+
+### Spike Test
+```javascript
+// Sudden increase in load
+export const options = {
+  stages: [
+    { duration: '1m', target: 100 },
+    { duration: '30s', target: 1000 }, // Spike
+    { duration: '3m', target: 100 },
+    { duration: '1m', target: 0 },
+  ],
+};
+```
+
+### Soak Test
+```javascript
+// Extended duration at normal load
+export const options = {
+  stages: [
+    { duration: '5m', target: 100 },
+    { duration: '8h', target: 100 },  // Long duration
+    { duration: '5m', target: 0 },
+  ],
+};
+```
+
+## Artillery.io
+
+```yaml
+# load-test.yml
+config:
+  target: 'https://api.example.com'
+  phases:
+    - duration: 60
+      arrivalRate: 10
+      name: "Warm up"
+    - duration: 300
+      arrivalRate: 50
+      name: "Sustained load"
+
+  processor: "./custom-functions.js"
+
+  variables:
+    userId:
+      - "user1"
+      - "user2"
+
+scenarios:
+  - name: "Product browsing"
+    weight: 70
+    flow:
+      - get:
+          url: "/products"
+      - think: 2
+      - get:
+          url: "/products/{{ $randomNumber(1, 100) }}"
+
+  - name: "Checkout"
+    weight: 30
+    flow:
+      - post:
+          url: "/cart"
+          json:
+            productId: "{{ $randomNumber(1, 100) }}"
+      - post:
+          url: "/checkout"
+          json:
+            userId: "{{ userId }}"
+```
+
+## Locust (Python)
+
+```python
+from locust import HttpUser, task, between
+
+class WebsiteUser(HttpUser):
+    wait_time = between(1, 3)
+
+    @task(3)
+    def view_products(self):
+        self.client.get("/products")
+
+    @task(1)
+    def view_product(self):
+        product_id = random.randint(1, 100)
+        self.client.get(f"/products/{product_id}")
+
+    @task(1)
+    def create_order(self):
+        self.client.post("/orders", json={
+            "product_id": random.randint(1, 100),
+            "quantity": random.randint(1, 5)
+        })
+
+    def on_start(self):
+        # Login or setup
+        self.client.post("/login", json={
+            "username": "test",
+            "password": "test"
+        })
+```
+
+## JMeter Thread Groups
+
+```xml
+<!-- Basic HTTP Request -->
+<ThreadGroup>
+  <stringProp name="ThreadGroup.num_threads">100</stringProp>
+  <stringProp name="ThreadGroup.ramp_time">60</stringProp>
+  <stringProp name="ThreadGroup.duration">300</stringProp>
+  <boolProp name="ThreadGroup.scheduler">true</boolProp>
+</ThreadGroup>
+```
+
+## Performance Metrics to Track
+
+```javascript
+// k6 custom metrics
+import { Counter, Trend, Gauge } from 'k6/metrics';
+
+const checkoutDuration = new Trend('checkout_duration');
+const cartSize = new Gauge('cart_size');
+const orderCounter = new Counter('orders_created');
+
+export default function () {
+  const startTime = Date.now();
+
+  const res = http.post('https://api.example.com/checkout', payload);
+
+  checkoutDuration.add(Date.now() - startTime);
+  orderCounter.add(1);
+  cartSize.add(payload.items.length);
+}
+```
+
+## Test Scenario Design
+
+```javascript
+// Realistic user journey
+import { scenario } from 'k6/execution';
+
+export const options = {
+  scenarios: {
+    browser_users: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '5m', target: 100 },
+        { duration: '10m', target: 100 },
+      ],
+      gracefulRampDown: '30s',
+    },
+    api_users: {
+      executor: 'constant-arrival-rate',
+      rate: 50,
+      timeUnit: '1s',
+      duration: '15m',
+      preAllocatedVUs: 100,
+    },
+  },
+};
+
+export default function () {
+  // Homepage
+  http.get('https://example.com/');
+  sleep(Math.random() * 3);
+
+  // Search
+  http.get('https://example.com/search?q=laptop');
+  sleep(Math.random() * 5);
+
+  // Product page
+  http.get('https://example.com/products/123');
+  sleep(Math.random() * 10);
+
+  // Add to cart (30% conversion)
+  if (Math.random() < 0.3) {
+    http.post('https://example.com/cart', { productId: 123 });
+  }
+}
+```
+
+## Quick Reference
+
+| Test Type | Purpose | Duration |
+|-----------|---------|----------|
+| Load | Normal capacity | 30m - 2h |
+| Stress | Find limits | 1h - 4h |
+| Spike | Sudden traffic | 15m - 30m |
+| Soak | Memory leaks | 4h - 24h |
+
+| Tool | Language | Best For |
+|------|----------|----------|
+| k6 | JavaScript | API testing, CI/CD |
+| Artillery | YAML/JS | Simple scenarios |
+| Locust | Python | Complex scenarios |
+| JMeter | GUI/XML | Legacy systems |
+
+| Metric | Target |
+|--------|--------|
+| p95 latency | < 500ms |
+| p99 latency | < 1s |
+| Error rate | < 1% |
+| RPS | 10x normal |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/prometheus-metrics.md

@@ -0,0 +1,136 @@
+# Prometheus Metrics
+
+## Metric Types
+
+```typescript
+import { Registry, Counter, Histogram, Gauge, Summary } from 'prom-client';
+
+const register = new Registry();
+
+// Counter - cumulative, only increases
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'path', 'status'],
+  registers: [register],
+});
+
+// Histogram - distribution with buckets
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'path'],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
+  registers: [register],
+});
+
+// Gauge - point-in-time value, can go up/down
+const activeConnections = new Gauge({
+  name: 'active_connections',
+  help: 'Number of active connections',
+  registers: [register],
+});
+
+// Summary - similar to histogram with percentiles
+const responseSummary = new Summary({
+  name: 'http_response_size_bytes',
+  help: 'HTTP response size',
+  percentiles: [0.5, 0.9, 0.99],
+  registers: [register],
+});
+```
+
+## HTTP Middleware
+
+```typescript
+app.use((req, res, next) => {
+  const end = httpDuration.startTimer({
+    method: req.method,
+    path: req.route?.path || req.path,
+  });
+
+  res.on('finish', () => {
+    httpRequests.inc({
+      method: req.method,
+      path: req.route?.path || req.path,
+      status: res.statusCode,
+    });
+    end();
+  });
+
+  next();
+});
+
+// Metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.send(await register.metrics());
+});
+```
+
+## Business Metrics
+
+```typescript
+// Orders
+const ordersCreated = new Counter({
+  name: 'orders_created_total',
+  help: 'Total orders created',
+  labelNames: ['status', 'payment_method'],
+});
+
+const orderValue = new Histogram({
+  name: 'order_value_dollars',
+  help: 'Order value in dollars',
+  buckets: [10, 50, 100, 500, 1000],
+});
+
+// Usage
+ordersCreated.inc({ status: 'completed', payment_method: 'card' });
+orderValue.observe(order.total);
+```
+
+## Default Metrics
+
+```typescript
+import { collectDefaultMetrics } from 'prom-client';
+
+// Collect Node.js metrics (memory, CPU, etc.)
+collectDefaultMetrics({ register });
+```
+
+## Python (prometheus_client)
+
+```python
+from prometheus_client import Counter, Histogram, Gauge, generate_latest
+
+http_requests = Counter(
+    'http_requests_total',
+    'Total HTTP requests',
+    ['method', 'path', 'status']
+)
+
+http_duration = Histogram(
+    'http_request_duration_seconds',
+    'HTTP request duration',
+    ['method', 'path']
+)
+
+@app.get("/metrics")
+def metrics():
+    return Response(generate_latest(), media_type="text/plain")
+```
+
+## Quick Reference
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| Counter | Cumulative totals | Requests, errors |
+| Gauge | Current value | Active users, queue size |
+| Histogram | Distributions | Response times |
+| Summary | Percentiles | Similar to histogram |
+
+| Naming | Convention |
+|--------|------------|
+| Unit suffix | `_seconds`, `_bytes`, `_total` |
+| Base unit | Use seconds, bytes (not ms, KB) |
+| Prefix | App/service name |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/structured-logging.md

@@ -0,0 +1,142 @@
+# Structured Logging
+
+## Pino (Node.js)
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  redact: ['password', 'token', 'authorization'],
+});
+
+// Structured logging
+logger.info({
+  event: 'user.login',
+  userId: user.id,
+  ip: req.ip,
+  userAgent: req.headers['user-agent'],
+  duration: Date.now() - start,
+});
+
+// Error logging with context
+logger.error({
+  event: 'payment.failed',
+  error: err.message,
+  stack: err.stack,
+  orderId: order.id,
+  amount: order.total,
+  userId: user.id,
+});
+```
+
+## Request Logging Middleware
+
+```typescript
+import { randomUUID } from 'crypto';
+
+app.use((req, res, next) => {
+  const requestId = req.headers['x-request-id'] || randomUUID();
+  const start = Date.now();
+
+  res.setHeader('x-request-id', requestId);
+
+  res.on('finish', () => {
+    logger.info({
+      event: 'http.request',
+      requestId,
+      method: req.method,
+      path: req.path,
+      status: res.statusCode,
+      duration: Date.now() - start,
+      userAgent: req.headers['user-agent'],
+      ip: req.ip,
+    });
+  });
+
+  next();
+});
+```
+
+## Python (structlog)
+
+```python
+import structlog
+
+structlog.configure(
+    processors=[
+        structlog.stdlib.filter_by_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.JSONRenderer()
+    ],
+)
+
+logger = structlog.get_logger()
+
+# Structured logging
+logger.info(
+    "user.login",
+    user_id=user.id,
+    ip=request.client.host,
+    duration=elapsed_time,
+)
+
+# Error logging
+logger.error(
+    "payment.failed",
+    error=str(exc),
+    order_id=order.id,
+    amount=order.total,
+)
+```
+
+## Log Levels
+
+| Level | Use Case |
+|-------|----------|
+| `error` | Failures needing attention |
+| `warn` | Potential problems |
+| `info` | Business events, requests |
+| `debug` | Development details |
+| `trace` | Verbose debugging |
+
+## Best Practices
+
+```typescript
+// Good: Structured fields
+logger.info({ event: 'order.created', orderId: '123', total: 99.99 });
+
+// Bad: String interpolation
+logger.info(`Order 123 created with total 99.99`);
+
+// Good: Consistent event names
+logger.info({ event: 'user.registered' });
+logger.info({ event: 'user.login' });
+logger.info({ event: 'user.logout' });
+
+// Good: Include correlation ID
+logger.info({ event: 'request.processed', requestId, userId });
+```
+
+## Quick Reference
+
+| Field | Purpose |
+|-------|---------|
+| `event` | Event name |
+| `requestId` | Correlation ID |
+| `userId` | User context |
+| `duration` | Timing info |
+| `error` / `stack` | Error details |
+| `timestamp` | When (auto-added) |
+
+| Library | Language |
+|---------|----------|
+| pino | Node.js |
+| structlog | Python |
+| slog | Go |
+| logrus | Go |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nestjs-expert/SKILL.md

@@ -0,0 +1,107 @@
+---
+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 Skill
+
+- 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       | `references/controllers-routing.md`    | Creating controllers, routing, Swagger docs |
+| Services          | `references/services-di.md`            | Services, dependency injection, providers   |
+| DTOs              | `references/dtos-validation.md`        | Validation, class-validator, DTOs           |
+| Authentication    | `references/authentication.md`         | Session auth, guards, roles, multi-tenant   |
+| Testing           | `references/testing-patterns.md`       | Unit tests, E2E tests, mocking              |
+| Express Migration | `references/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 `references/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