@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/express-patterns.md

@@ -0,0 +1,239 @@
+---
+name: express-patterns
+description: Express.js patterns for middleware, error handling, validation, rate limiting, and graceful shutdown.
+---
+
+# Express.js Patterns
+
+## When to Use
+
+Apply these patterns when building Express 4/5 applications in Node.js. Use this
+skill for structuring middleware pipelines, centralizing error handling, validating
+request data, implementing rate limiting, and shutting down gracefully under load.
+
+## How It Works
+
+### Middleware Pipeline
+
+Middleware executes in order of registration. Use `app.use()` for global middleware,
+`router.use()` for route-scoped. Always call `next()` or send a response.
+
+```typescript
+import express from 'express'
+
+const app = express()
+
+// Global middleware — order matters
+app.use(express.json({ limit: '1mb' }))
+app.use(requestId())
+app.use(requestLogger())
+app.use(cors(corsOptions))
+
+// Route-scoped middleware
+const authRouter = express.Router()
+authRouter.use(authenticate) // applies to all routes in this router
+authRouter.get('/me', getProfile)
+authRouter.put('/me', validateBody(updateProfileSchema), updateProfile)
+
+app.use('/api', authRouter)
+```
+
+### Request ID Middleware
+
+Attach a unique ID to every request for tracing across logs and downstream services.
+
+```typescript
+import { randomUUID } from 'crypto'
+
+function requestId() {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const id = req.headers['x-request-id'] as string || randomUUID()
+    req.id = id
+    res.setHeader('X-Request-Id', id)
+    next()
+  }
+}
+```
+
+### Centralized Error Handling
+
+Define an error-handling middleware (4 arguments) as the last `app.use`. Catch
+async errors with a wrapper or Express 5's native async support.
+
+```typescript
+// Async wrapper for Express 4 (Express 5 handles this natively)
+function asyncHandler(fn: (req: Request, res: Response, next: NextFunction) => Promise<void>) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    fn(req, res, next).catch(next)
+  }
+}
+
+// Domain error class
+class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+// Central error handler — must be registered last
+function errorHandler(err: Error, req: Request, res: Response, _next: NextFunction) {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message },
+    })
+  }
+
+  console.error(`[${req.id}] Unhandled error:`, err)
+  res.status(500).json({
+    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' },
+  })
+}
+
+app.use(errorHandler)
+```
+
+### Validation with Zod
+
+Validate request bodies, query params, and path params at the middleware level.
+Return structured 400 errors with field-level details.
+
+```typescript
+import { z, ZodSchema } from 'zod'
+
+function validateBody(schema: ZodSchema) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body)
+    if (!result.success) {
+      return res.status(400).json({
+        error: {
+          code: 'VALIDATION_ERROR',
+          details: result.error.issues.map(i => ({
+            field: i.path.join('.'),
+            message: i.message,
+          })),
+        },
+      })
+    }
+    req.body = result.data // parsed and typed
+    next()
+  }
+}
+
+const createProjectSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  budget: z.number().positive(),
+})
+
+router.post('/projects', validateBody(createProjectSchema), asyncHandler(async (req, res) => {
+  const project = await projectService.create(req.body)
+  res.status(201).json(project)
+}))
+```
+
+### Rate Limiting
+
+Use `express-rate-limit` for basic rate limiting. Apply stricter limits to
+auth endpoints. Use Redis store in production for multi-instance deployments.
+
+```typescript
+import rateLimit from 'express-rate-limit'
+
+const globalLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: { code: 'RATE_LIMITED', message: 'Too many requests' } },
+})
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5, // stricter for login attempts
+  skipSuccessfulRequests: true,
+})
+
+app.use(globalLimiter)
+app.use('/api/auth/login', authLimiter)
+```
+
+### Graceful Shutdown
+
+Stop accepting new connections, finish in-flight requests, close database pools
+and other resources, then exit. Handle both SIGTERM and SIGINT.
+
+```typescript
+const server = app.listen(PORT, () => {
+  console.log(`Listening on port ${PORT}`)
+})
+
+async function shutdown(signal: string) {
+  console.log(`${signal} received. Shutting down gracefully...`)
+
+  server.close(async () => {
+    console.log('HTTP server closed')
+
+    try {
+      await db.end()           // close DB pool
+      await cache.quit()       // close Redis
+      console.log('All connections closed')
+      process.exit(0)
+    } catch (err) {
+      console.error('Error during shutdown:', err)
+      process.exit(1)
+    }
+  })
+
+  // Force exit after 30 seconds
+  setTimeout(() => {
+    console.error('Forced shutdown after timeout')
+    process.exit(1)
+  }, 30_000)
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'))
+process.on('SIGINT', () => shutdown('SIGINT'))
+```
+
+### Router Organization
+
+Group routes by domain in separate files. Mount on the main app with prefixes.
+
+```typescript
+// routes/projects.ts
+const router = express.Router()
+router.get('/', asyncHandler(listProjects))
+router.post('/', validateBody(createProjectSchema), asyncHandler(createProject))
+router.get('/:id', asyncHandler(getProject))
+export default router
+
+// app.ts
+import projectRoutes from './routes/projects'
+app.use('/api/v1/projects', authenticate, projectRoutes)
+```
+
+## Examples
+
+**Pattern: Health check endpoint**
+```typescript
+app.get('/healthz', (req, res) => {
+  res.json({ status: 'ok', uptime: process.uptime(), timestamp: new Date().toISOString() })
+})
+```
+
+## Checklist
+
+- [ ] Request ID middleware attached early in the pipeline
+- [ ] `express.json()` with explicit size `limit`
+- [ ] Async handler wrapper (Express 4) or native async support (Express 5)
+- [ ] Single error-handling middleware registered last (`err, req, res, next`)
+- [ ] `AppError` class with status code and error code for domain errors
+- [ ] Zod or Joi validation middleware on every POST/PUT/PATCH route
+- [ ] Rate limiting: global + stricter on auth endpoints
+- [ ] Graceful shutdown handles SIGTERM/SIGINT, closes DB/cache connections
+- [ ] Forced exit timeout (30s) prevents hanging processes
+- [ ] Routes organized by domain in separate router files

package/assets/skills/fastapi-patterns.md

@@ -0,0 +1,198 @@
+---
+name: fastapi-patterns
+description: FastAPI patterns for dependency injection, Pydantic models, middleware, background tasks, and WebSockets.
+---
+
+# FastAPI Patterns
+
+## When to Use
+
+Apply these patterns when building async Python APIs with FastAPI. Use this skill
+for structuring endpoints with dependency injection, validating requests with Pydantic,
+adding middleware, running background tasks, and handling WebSocket connections.
+
+## How It Works
+
+### Dependency Injection
+
+Use `Depends()` to inject services, database sessions, and auth into endpoints.
+Dependencies can depend on other dependencies. Use `yield` dependencies for cleanup.
+
+```python
+from fastapi import Depends, FastAPI
+
+async def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: Session = Depends(get_db),
+) -> User:
+    user = await verify_token(token, db)
+    if not user:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user
+
+@app.get("/me")
+async def read_me(user: User = Depends(get_current_user)):
+    return user
+```
+
+### Pydantic Models
+
+Separate request and response models. Use `model_config` for serialization settings.
+Validate with `@field_validator` and `@model_validator`.
+
+```python
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+class CreateProject(BaseModel):
+    name: str = Field(min_length=1, max_length=100)
+    description: str = Field(default="", max_length=500)
+    budget: float = Field(gt=0)
+    tags: list[str] = Field(default_factory=list, max_length=10)
+
+    @field_validator("tags")
+    @classmethod
+    def normalize_tags(cls, v: list[str]) -> list[str]:
+        return [tag.lower().strip() for tag in v if tag.strip()]
+
+class ProjectResponse(BaseModel):
+    model_config = {"from_attributes": True}
+
+    id: int
+    name: str
+    description: str
+    budget: float
+    created_at: datetime
+```
+
+### Middleware
+
+Use pure ASGI middleware for performance-critical paths. Use `@app.middleware("http")`
+for simpler cases. Always call `call_next` and handle exceptions.
+
+```python
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class TimingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        start = time.monotonic()
+        response = await call_next(request)
+        duration = time.monotonic() - start
+        response.headers["X-Duration-Ms"] = f"{duration * 1000:.1f}"
+        return response
+
+app.add_middleware(TimingMiddleware)
+app.add_middleware(CORSMiddleware, allow_origins=["https://example.com"])
+```
+
+### Background Tasks
+
+Use `BackgroundTasks` for fire-and-forget work after the response is sent. For
+heavier work, use a task queue (Celery, arq, or Dramatiq).
+
+```python
+from fastapi import BackgroundTasks
+
+async def send_welcome_email(email: str, name: str):
+    await email_client.send(to=email, subject=f"Welcome, {name}!")
+
+@app.post("/users", status_code=201)
+async def create_user(
+    body: CreateUser,
+    bg: BackgroundTasks,
+    db: Session = Depends(get_db),
+):
+    user = await user_service.create(db, body)
+    bg.add_task(send_welcome_email, user.email, user.name)
+    return user
+```
+
+### WebSockets
+
+Accept connections explicitly. Use try/finally for cleanup. Handle
+`WebSocketDisconnect` to avoid crashes on client disconnect.
+
+```python
+from fastapi import WebSocket, WebSocketDisconnect
+
+class ConnectionManager:
+    def __init__(self):
+        self.connections: dict[str, WebSocket] = {}
+
+    async def connect(self, ws: WebSocket, user_id: str):
+        await ws.accept()
+        self.connections[user_id] = ws
+
+    async def disconnect(self, user_id: str):
+        self.connections.pop(user_id, None)
+
+    async def broadcast(self, message: dict):
+        for ws in self.connections.values():
+            await ws.send_json(message)
+
+manager = ConnectionManager()
+
+@app.websocket("/ws/{user_id}")
+async def websocket_endpoint(ws: WebSocket, user_id: str):
+    await manager.connect(ws, user_id)
+    try:
+        while True:
+            data = await ws.receive_json()
+            await handle_message(user_id, data)
+    except WebSocketDisconnect:
+        await manager.disconnect(user_id)
+```
+
+### Router Organization
+
+Split routes into routers by domain. Mount with prefixes and tags. Use
+`include_router` in the main app.
+
+```python
+# routers/projects.py
+router = APIRouter(prefix="/projects", tags=["projects"])
+
+@router.get("/", response_model=list[ProjectResponse])
+async def list_projects(db: Session = Depends(get_db)):
+    return await project_service.list_all(db)
+
+# main.py
+from routers import projects, users, auth
+app.include_router(projects.router)
+app.include_router(users.router)
+app.include_router(auth.router, prefix="/auth")
+```
+
+## Examples
+
+**Pattern: Custom exception handler**
+```python
+class AppError(Exception):
+    def __init__(self, code: str, message: str, status: int = 400):
+        self.code = code
+        self.message = message
+        self.status = status
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(status_code=exc.status, content={"error": exc.code, "message": exc.message})
+```
+
+## Checklist
+
+- [ ] Separate Pydantic models for request body vs. response
+- [ ] `Depends()` for DB sessions, auth, and services (never instantiate in handlers)
+- [ ] Yield dependencies for resources that need cleanup (DB connections, files)
+- [ ] `response_model` set on every endpoint for OpenAPI doc accuracy
+- [ ] `status_code` explicitly set on POST (201), DELETE (204) endpoints
+- [ ] Background tasks for post-response work; task queues for heavy processing
+- [ ] Custom exception handlers for domain errors (not bare `HTTPException` everywhere)
+- [ ] WebSocket handlers wrapped in try/except `WebSocketDisconnect`
+- [ ] Routes organized into `APIRouter` with prefix and tags
+- [ ] Middleware ordered correctly (CORS before auth, timing outermost)

package/assets/skills/feature-flags.md

@@ -0,0 +1,212 @@
+---
+name: feature-flags
+description: Feature flag patterns with LaunchDarkly, Unleash, gradual rollout, A/B testing, and kill switches.
+---
+
+# Feature Flags
+
+## When to Use
+Apply when you need to decouple deployment from release. Feature flags let you deploy code to production without exposing it to users, gradually roll out features to subsets of users, A/B test variations, and instantly kill a feature if it causes problems. Use flags for any change that carries risk or needs measurement.
+
+## How It Works
+
+### Basic Feature Flag Implementation
+
+Start simple before reaching for a third-party service:
+
+```typescript
+import { createHash } from "crypto";
+
+interface FlagConfig {
+  enabled: boolean;
+  rolloutPercent?: number;
+  allowList?: string[];
+  variants?: Record<string, number>;
+}
+
+const flags: Record<string, FlagConfig> = {
+  "new-checkout-flow": {
+    enabled: true,
+    rolloutPercent: 25,
+    allowList: ["user_internal_team"],
+  },
+  "pricing-v2": {
+    enabled: true,
+    variants: { control: 50, variant_a: 25, variant_b: 25 },
+  },
+};
+
+function deterministicBucket(key: string, userId: string): number {
+  const hash = createHash("md5").update(`${key}:${userId}`).digest();
+  return hash.readUInt32BE(0) % 100;
+}
+
+function isEnabled(flagKey: string, userId?: string): boolean {
+  const flag = flags[flagKey];
+  if (!flag?.enabled) return false;
+  if (userId && flag.allowList?.includes(userId)) return true;
+  if (flag.rolloutPercent !== undefined && userId) {
+    return deterministicBucket(flagKey, userId) < flag.rolloutPercent;
+  }
+  return flag.enabled;
+}
+```
+
+### LaunchDarkly Integration
+
+```typescript
+import * as LaunchDarkly from "@launchdarkly/node-server-sdk";
+
+const ldClient = LaunchDarkly.init(process.env.LAUNCHDARKLY_SDK_KEY!);
+await ldClient.waitForInitialization();
+
+async function checkFlag(flagKey: string, user: { id: string; email: string }): Promise<boolean> {
+  const context: LaunchDarkly.LDContext = {
+    kind: "user",
+    key: user.id,
+    email: user.email,
+  };
+  return ldClient.variation(flagKey, context, false);
+}
+
+// React client-side hook
+import { useFlags } from "launchdarkly-react-client-sdk";
+
+function CheckoutPage() {
+  const { newCheckoutFlow } = useFlags();
+  return newCheckoutFlow ? <NewCheckout /> : <LegacyCheckout />;
+}
+```
+
+### Unleash -- Open Source Alternative
+
+```typescript
+import { initialize, isEnabled } from "unleash-client";
+
+const unleash = initialize({
+  url: "https://unleash.example.com/api",
+  appName: "my-app",
+  customHeaders: { Authorization: process.env.UNLEASH_API_TOKEN! },
+});
+
+if (isEnabled("new-checkout-flow")) {
+  renderNewCheckout();
+}
+
+// With user context for gradual rollout
+const context = { userId: user.id, properties: { plan: user.plan } };
+if (isEnabled("premium-feature", context)) {
+  renderPremiumFeature();
+}
+```
+
+### Gradual Rollout Strategy
+
+```typescript
+// Phase 1: Internal team only
+{ enabled: true, allowList: ["team_engineering"] }
+
+// Phase 2: 5% of users -- monitor error rates
+{ enabled: true, rolloutPercent: 5 }
+
+// Phase 3: 25% -- check business metrics
+{ enabled: true, rolloutPercent: 25 }
+
+// Phase 4: 100% -- fully rolled out
+{ enabled: true, rolloutPercent: 100 }
+
+// Phase 5: Remove flag -- clean up the code path entirely
+```
+
+### A/B Testing with Variants
+
+```typescript
+function getVariant(flagKey: string, userId: string, variants: Record<string, number>): string {
+  const bucket = deterministicBucket(flagKey, userId);
+  let cumulative = 0;
+  for (const [variant, weight] of Object.entries(variants)) {
+    cumulative += weight;
+    if (bucket < cumulative) return variant;
+  }
+  return Object.keys(variants)[0];
+}
+
+const variant = getVariant("pricing-page", user.id, {
+  control: 50,
+  annual_first: 25,
+  comparison_table: 25,
+});
+
+analytics.track("pricing_page_viewed", { variant, userId: user.id });
+
+switch (variant) {
+  case "control": return <PricingOriginal />;
+  case "annual_first": return <PricingAnnualFirst />;
+  case "comparison_table": return <PricingComparison />;
+}
+```
+
+### Kill Switch Pattern
+
+```typescript
+function killSwitchMiddleware(flagKey: string) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    if (!isEnabled(flagKey)) {
+      return res.status(503).json({
+        error: "This feature is temporarily unavailable",
+        retryAfter: 300,
+      });
+    }
+    next();
+  };
+}
+
+app.post("/api/payments", killSwitchMiddleware("payments-enabled"), paymentHandler);
+```
+
+### Flag Cleanup -- Prevent Technical Debt
+
+```typescript
+interface FlagMetadata {
+  createdAt: Date;
+  owner: string;
+  jiraTicket: string;
+  expiresAt: Date;
+  type: "release" | "experiment" | "ops" | "permission";
+}
+
+function auditStaleFlags(flags: Record<string, FlagMetadata>): string[] {
+  const now = new Date();
+  return Object.entries(flags)
+    .filter(([_, meta]) => meta.type === "release" && meta.expiresAt < now)
+    .map(([key]) => key);
+}
+
+// Run in CI: fail if stale flags exist
+const stale = auditStaleFlags(flagRegistry);
+if (stale.length > 0) {
+  console.error("Stale feature flags need cleanup:", stale);
+  process.exit(1);
+}
+```
+
+## Examples
+
+| Pattern | When | Result |
+|---------|------|--------|
+| Boolean flag | Simple on/off feature | Deploy safely, enable later |
+| Gradual rollout | Risky changes | Limit blast radius to N% |
+| A/B testing | Optimize conversion | Data-driven decisions |
+| Kill switch | Payment, auth flows | Instant disable in incidents |
+| Allow list | Beta features | Internal testing first |
+| Flag cleanup | Post-rollout | Prevent code path debt |
+
+## Checklist
+- [ ] All risky features behind a feature flag
+- [ ] Gradual rollout starts at 5%, not 50%
+- [ ] Kill switches exist for critical paths (payments, auth)
+- [ ] A/B variants tracked in analytics for measurement
+- [ ] Flag defaults are safe (off) if flag service unreachable
+- [ ] Stale flags (> 90 days) cleaned up with explicit expiry
+- [ ] Flag evaluation consistent per user (deterministic hash)
+- [ ] Flag changes auditable with who/when/why