@patricio0312rev/skillset 0.1.0

package/templates/backend/api-endpoint-generator/ SKILL.md

@@ -0,0 +1,415 @@
+---
+name: api-contract-normalizer
+description: Unifies API response patterns across endpoints including pagination format, error structure, status codes, response envelopes, and versioning strategy. Provides contract documentation, shared TypeScript types, middleware utilities, and migration plan. Use when standardizing "API contracts", "response formats", "API conventions", or "API consistency".
+---
+
+# API Contract Normalizer
+
+Standardize API contracts across all endpoints for consistency and developer experience.
+
+## Core Workflow
+
+1. **Audit existing APIs**: Document current inconsistencies
+2. **Define standards**: Response format, pagination, errors, status codes
+3. **Create shared types**: TypeScript interfaces for all contracts
+4. **Build middleware**: Normalize responses automatically
+5. **Document contract**: OpenAPI spec with examples
+6. **Migration plan**: Phased rollout strategy
+7. **Versioning**: API version strategy
+
+## Standard Response Envelope
+
+```typescript
+// types/api-contract.ts
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: ApiError;
+  meta?: ResponseMeta;
+}
+
+export interface ApiError {
+  code: string;
+  message: string;
+  details?: Record<string, string[] | string>;
+  trace_id?: string;
+}
+
+export interface ResponseMeta {
+  timestamp: string;
+  request_id: string;
+  version: string;
+}
+
+export interface PaginatedResponse<T> extends ApiResponse<T[]> {
+  meta: ResponseMeta & PaginationMeta;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  total_pages: number;
+  has_next: boolean;
+  has_prev: boolean;
+}
+```
+
+## Pagination Standards
+
+```typescript
+// Standard pagination query params
+interface PaginationQuery {
+  page: number;      // 1-indexed, default: 1
+  limit: number;     // default: 10, max: 100
+  sort_by?: string;  // field name
+  sort_order?: 'asc' | 'desc'; // default: 'desc'
+}
+
+// Standard pagination response
+{
+  "success": true,
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 10,
+    "total": 156,
+    "total_pages": 16,
+    "has_next": true,
+    "has_prev": false
+  }
+}
+
+// Cursor-based pagination (for large datasets)
+interface CursorPaginationQuery {
+  cursor?: string;
+  limit: number;
+}
+
+interface CursorPaginationMeta {
+  next_cursor?: string;
+  prev_cursor?: string;
+  has_more: boolean;
+}
+```
+
+## Error Standards
+
+```typescript
+// Error taxonomy
+export enum ErrorCode {
+  // Client errors (4xx)
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  NOT_FOUND = 'NOT_FOUND',
+  CONFLICT = 'CONFLICT',
+  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
+
+  // Server errors (5xx)
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+  TIMEOUT = 'TIMEOUT',
+}
+
+// Error to HTTP status mapping
+export const ERROR_STATUS_MAP: Record<ErrorCode, number> = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMIT_EXCEEDED: 429,
+  INTERNAL_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+  TIMEOUT: 504,
+};
+
+// Standard error responses
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request data",
+    "details": {
+      "email": ["Invalid email format"],
+      "age": ["Must be at least 18"]
+    },
+    "trace_id": "abc123"
+  }
+}
+```
+
+## Response Normalization Middleware
+
+```typescript
+// middleware/normalize-response.ts
+import { Request, Response, NextFunction } from "express";
+
+export function normalizeResponse() {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const originalJson = res.json.bind(res);
+
+    res.json = function (data: any) {
+      // Already normalized
+      if (data.success !== undefined) {
+        return originalJson(data);
+      }
+
+      // Normalize success response
+      const normalized: ApiResponse = {
+        success: true,
+        data,
+        meta: {
+          timestamp: new Date().toISOString(),
+          request_id: req.id,
+          version: "v1",
+        },
+      };
+
+      return originalJson(normalized);
+    };
+
+    next();
+  };
+}
+
+// Error normalization middleware
+export function normalizeError() {
+  return (err: Error, req: Request, res: Response, next: NextFunction) => {
+    const error: ApiError = {
+      code: err.name || "INTERNAL_ERROR",
+      message: err.message || "An unexpected error occurred",
+      trace_id: req.id,
+    };
+
+    if (err instanceof ValidationError) {
+      error.details = err.details;
+    }
+
+    const statusCode = ERROR_STATUS_MAP[error.code] || 500;
+
+    res.status(statusCode).json({
+      success: false,
+      error,
+      meta: {
+        timestamp: new Date().toISOString(),
+        request_id: req.id,
+        version: "v1",
+      },
+    });
+  };
+}
+```
+
+## Status Code Standards
+
+```typescript
+// Standard status codes by operation
+const STATUS_CODES = {
+  // Success
+  OK: 200, // GET, PUT, PATCH success
+  CREATED: 201, // POST success
+  NO_CONTENT: 204, // DELETE success
+
+  // Client errors
+  BAD_REQUEST: 400, // Validation errors
+  UNAUTHORIZED: 401, // Missing/invalid auth
+  FORBIDDEN: 403, // Insufficient permissions
+  NOT_FOUND: 404, // Resource not found
+  CONFLICT: 409, // Duplicate/conflict
+  UNPROCESSABLE: 422, // Semantic errors
+  TOO_MANY_REQUESTS: 429, // Rate limit
+
+  // Server errors
+  INTERNAL_ERROR: 500, // Unexpected errors
+  SERVICE_UNAVAILABLE: 503, // Temporarily down
+  GATEWAY_TIMEOUT: 504, // Upstream timeout
+};
+```
+
+## Versioning Strategy
+
+```typescript
+// URL versioning (recommended)
+/api/v1/users
+/api/v2/users
+
+// Header versioning
+Accept: application/vnd.api.v1+json
+
+// Query param versioning (not recommended)
+/api/users?version=1
+
+// Version middleware
+export function apiVersion(version: string) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    req.apiVersion = version;
+    res.setHeader('X-API-Version', version);
+    next();
+  };
+}
+
+// Route versioning
+app.use('/api/v1', apiVersion('v1'), v1Router);
+app.use('/api/v2', apiVersion('v2'), v2Router);
+```
+
+## Migration Strategy
+
+```markdown
+# API Contract Migration Plan
+
+## Phase 1: Add Normalization (Week 1-2)
+
+- [ ] Deploy normalization middleware
+- [ ] Run alongside existing responses
+- [ ] Monitor for issues
+- [ ] No breaking changes yet
+
+## Phase 2: Deprecation Notice (Week 3-4)
+
+- [ ] Add deprecation headers
+- [ ] Update documentation
+- [ ] Notify API consumers
+- [ ] Provide migration guide
+
+## Phase 3: Dual Format Support (Week 5-8)
+
+- [ ] Support both old and new formats
+- [ ] Add ?format=v2 query param
+- [ ] Track adoption metrics
+- [ ] Help consumers migrate
+
+## Phase 4: Switch Default (Week 9-10)
+
+- [ ] New format becomes default
+- [ ] Old format requires ?format=v1
+- [ ] Final migration reminders
+- [ ] Extended support period
+
+## Phase 5: Remove Old Format (Week 12+)
+
+- [ ] Remove old format support
+- [ ] Clean up legacy code
+- [ ] Update all documentation
+- [ ] Celebrate consistency! 🎉
+```
+
+## Contract Documentation
+
+```yaml
+# openapi.yaml
+openapi: 3.0.0
+info:
+  title: Standardized API
+  version: 1.0.0
+  description: All endpoints follow this contract
+
+components:
+  schemas:
+    ApiResponse:
+      type: object
+      required: [success]
+      properties:
+        success:
+          type: boolean
+        data:
+          type: object
+        error:
+          $ref: "#/components/schemas/ApiError"
+        meta:
+          $ref: "#/components/schemas/ResponseMeta"
+
+    ApiError:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          enum: [VALIDATION_ERROR, UNAUTHORIZED, ...]
+        message:
+          type: string
+        details:
+          type: object
+          additionalProperties: true
+        trace_id:
+          type: string
+
+    PaginationMeta:
+      type: object
+      required: [page, limit, total, total_pages]
+      properties:
+        page: { type: integer }
+        limit: { type: integer }
+        total: { type: integer }
+        total_pages: { type: integer }
+        has_next: { type: boolean }
+        has_prev: { type: boolean }
+```
+
+## Shared Utilities
+
+```typescript
+// utils/api-response.ts
+export class ApiResponseBuilder {
+  static success<T>(data: T, meta?: Partial<ResponseMeta>): ApiResponse<T> {
+    return {
+      success: true,
+      data,
+      meta: {
+        timestamp: new Date().toISOString(),
+        ...meta,
+      },
+    };
+  }
+
+  static paginated<T>(
+    data: T[],
+    pagination: PaginationMeta
+  ): PaginatedResponse<T> {
+    return {
+      success: true,
+      data,
+      meta: {
+        timestamp: new Date().toISOString(),
+        ...pagination,
+      },
+    };
+  }
+
+  static error(code: ErrorCode, message: string, details?: any): ApiResponse {
+    return {
+      success: false,
+      error: { code, message, details },
+      meta: {
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+}
+```
+
+## Best Practices
+
+1. **Consistent envelope**: All responses use same structure
+2. **Type safety**: Shared types across frontend/backend
+3. **Clear errors**: Descriptive codes and messages
+4. **Standard pagination**: Same format for all lists
+5. **Versioning**: Plan for API evolution
+6. **Documentation**: OpenAPI spec as source of truth
+7. **Gradual migration**: Don't break existing clients
+8. **Monitoring**: Track adoption and errors
+
+## Output Checklist
+
+- [ ] Standard response envelope defined
+- [ ] Error taxonomy documented
+- [ ] Pagination format standardized
+- [ ] Status code mapping
+- [ ] Normalization middleware
+- [ ] Shared TypeScript types
+- [ ] Versioning strategy
+- [ ] OpenAPI specification
+- [ ] Migration plan with phases
+- [ ] Consumer communication plan

package/templates/backend/auth-module-builder/ SKILL.md

@@ -0,0 +1,99 @@
+---
+name: auth-module-builder
+description: Implements secure authentication patterns including login/registration, session management, JWT tokens, password hashing, cookie settings, and CSRF protection. Provides auth routes, middleware, security configurations, and threat model documentation. Use when building "authentication", "login system", "JWT auth", or "session management".
+---
+
+# Auth Module Builder
+
+Implement secure, production-ready authentication systems.
+
+## Core Components
+
+**Routes**: POST /login, /register, /logout, /refresh, /forgot-password
+**Middleware**: authenticate, requireAuth, optionalAuth
+**Security**: bcrypt hashing, JWT signing, secure cookies, CSRF tokens
+**Session**: Redis/DB storage, expiration, refresh tokens
+**Threats**: Document common attacks and mitigations
+
+## JWT Pattern
+
+```typescript
+// Generate tokens
+const accessToken = jwt.sign(
+  { userId: user.id, email: user.email },
+  process.env.JWT_SECRET,
+  { expiresIn: "15m" }
+);
+
+const refreshToken = jwt.sign(
+  { userId: user.id, type: "refresh" },
+  process.env.JWT_REFRESH_SECRET,
+  { expiresIn: "7d" }
+);
+
+// Verify middleware
+export const authenticate = async (req, res, next) => {
+  const token = req.headers.authorization?.split(" ")[1];
+  if (!token) return res.status(401).json({ error: "No token" });
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = await User.findById(decoded.userId);
+    next();
+  } catch (err) {
+    res.status(401).json({ error: "Invalid token" });
+  }
+};
+```
+
+## Session Pattern
+
+```typescript
+// Express session with Redis
+app.use(
+  session({
+    store: new RedisStore({ client: redisClient }),
+    secret: process.env.SESSION_SECRET,
+    resave: false,
+    saveUninitialized: false,
+    cookie: {
+      secure: process.env.NODE_ENV === "production",
+      httpOnly: true,
+      maxAge: 1000 * 60 * 60 * 24 * 7, // 7 days
+      sameSite: "lax",
+    },
+  })
+);
+```
+
+## Password Security
+
+```typescript
+import bcrypt from "bcrypt";
+
+// Hash password
+const hashedPassword = await bcrypt.hash(password, 10);
+
+// Verify password
+const isValid = await bcrypt.compare(password, user.hashedPassword);
+```
+
+## Security Checklist
+
+- [ ] Passwords hashed with bcrypt (cost ≥10)
+- [ ] JWT secrets from environment, rotated regularly
+- [ ] HTTPS only in production
+- [ ] httpOnly, secure cookies
+- [ ] CSRF protection enabled
+- [ ] Rate limiting on auth routes
+- [ ] Account lockout after failed attempts
+- [ ] Password reset tokens expire
+- [ ] Email verification for new accounts
+
+## Threat Model
+
+**Brute Force**: Rate limit + account lockout
+**Token Theft**: Short expiry, httpOnly cookies, HTTPS only
+**CSRF**: SameSite cookies + CSRF tokens
+**Session Fixation**: Regenerate session ID on login
+**XSS**: Sanitize inputs, CSP headers

package/templates/backend/background-jobs-designer/ SKILL.md

@@ -0,0 +1,166 @@
+---
+name: background-jobs-designer
+description: Designs background job processing systems with queue integration (BullMQ/Celery), job definitions, retry policies, exponential backoff, idempotent execution, and monitoring hooks. Use when implementing "background jobs", "task queues", "async processing", or "job workers".
+---
+
+# Background Jobs Designer
+
+Design reliable background job processing with retries and monitoring.
+
+## Queue Integration
+
+**BullMQ (Node.js)**:
+
+```typescript
+import { Queue, Worker } from "bullmq";
+
+const emailQueue = new Queue("email", {
+  connection: { host: "localhost", port: 6379 },
+});
+
+// Add job
+await emailQueue.add(
+  "send-welcome",
+  {
+    userId: "123",
+    email: "user@example.com",
+  },
+  {
+    attempts: 3,
+    backoff: { type: "exponential", delay: 2000 },
+  }
+);
+```
+
+**Celery (Python)**:
+
+```python
+from celery import Celery
+
+app = Celery('tasks', broker='redis://localhost:6379')
+
+@app.task(bind=True, max_retries=3)
+def send_email(self, user_id, email):
+    try:
+        # Send email
+        pass
+    except Exception as exc:
+        raise self.retry(exc=exc, countdown=60)
+```
+
+## Job Definitions
+
+```typescript
+export interface Job {
+  id: string;
+  type: string;
+  payload: unknown;
+  attempts: number;
+  maxAttempts: number;
+  createdAt: Date;
+  processedAt?: Date;
+  failedAt?: Date;
+  error?: string;
+}
+
+export const JOB_TYPES = {
+  SEND_EMAIL: "send-email",
+  PROCESS_PAYMENT: "process-payment",
+  GENERATE_REPORT: "generate-report",
+  SYNC_DATA: "sync-data",
+} as const;
+```
+
+## Retry Strategy
+
+```typescript
+// Exponential backoff
+const RETRY_CONFIG = {
+  maxAttempts: 5,
+  delays: [
+    1000, // 1 second
+    5000, // 5 seconds
+    30000, // 30 seconds
+    300000, // 5 minutes
+    1800000, // 30 minutes
+  ],
+};
+
+// Worker with retry
+const worker = new Worker("email", async (job) => {
+  try {
+    await sendEmail(job.data);
+  } catch (error) {
+    if (job.attemptsMade < RETRY_CONFIG.maxAttempts) {
+      throw error; // Will retry
+    }
+    await handleFailedJob(job, error);
+  }
+});
+```
+
+## Idempotent Jobs
+
+```typescript
+// Track processed jobs
+export const processJob = async (job: Job) => {
+  // Check if already processed
+  const processed = await db.query(
+    "SELECT 1 FROM processed_jobs WHERE job_id = $1",
+    [job.id]
+  );
+
+  if (processed.rows.length > 0) {
+    console.log("Job already processed");
+    return; // Idempotent
+  }
+
+  await db.transaction(async (trx) => {
+    // Mark as processed
+    await trx("processed_jobs").insert({ job_id: job.id });
+
+    // Do work
+    await performWork(job, trx);
+  });
+};
+```
+
+## Monitoring
+
+```typescript
+// Job events
+worker.on("completed", (job) => {
+  metrics.increment("jobs.completed", { type: job.name });
+});
+
+worker.on("failed", (job, err) => {
+  metrics.increment("jobs.failed", { type: job.name });
+  logger.error("Job failed", { jobId: job.id, error: err });
+});
+
+worker.on("stalled", (jobId) => {
+  metrics.increment("jobs.stalled");
+  logger.warn("Job stalled", { jobId });
+});
+```
+
+## Best Practices
+
+- Jobs should be idempotent
+- Use exponential backoff for retries
+- Set reasonable timeouts
+- Monitor queue depth
+- Dead letter queue for failed jobs
+- Log job start/completion
+- Graceful shutdown handling
+
+## Output Checklist
+
+- [ ] Queue setup (Redis/RabbitMQ)
+- [ ] Job type definitions
+- [ ] Retry policy with backoff
+- [ ] Idempotency tracking
+- [ ] Error handling
+- [ ] Monitoring/metrics
+- [ ] Dead letter queue
+- [ ] Graceful shutdown