@garethdaine/agentops 0.9.0

package/templates/scaffolds/env-validation.md

@@ -0,0 +1,85 @@
+# Enterprise Pattern: Environment Validation
+
+Generate the following environment validation pattern adapted to the project's chosen stack.
+
+## Environment Schema (`src/lib/env.ts`)
+
+```typescript
+import { z } from 'zod';
+
+/**
+ * Define all required environment variables with types and defaults.
+ * The app will fail fast at startup if any required variable is missing or invalid.
+ */
+const envSchema = z.object({
+  // App
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  HOST: z.string().default('0.0.0.0'),
+  SERVICE_NAME: z.string().default('{{project_name}}'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+
+  // {{#if database}}
+  // Database
+  DATABASE_URL: z.string().url(),
+  // {{/if}}
+
+  // {{#if auth_strategy}}
+  // Auth
+  // AUTH_SECRET: z.string().min(32),
+  // {{/if}}
+
+  // Add project-specific variables below
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+function validateEnv(): Env {
+  const result = envSchema.safeParse(process.env);
+
+  if (!result.success) {
+    console.error('Environment validation failed:');
+    for (const issue of result.error.issues) {
+      console.error(`  ${issue.path.join('.')}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+
+  return result.data;
+}
+
+/**
+ * Validated environment variables — import this instead of using process.env directly.
+ * Guarantees type safety and presence of all required variables.
+ */
+export const env = validateEnv();
+```
+
+## .env.example Template
+
+```bash
+# Application
+NODE_ENV=development
+PORT=3000
+HOST=0.0.0.0
+SERVICE_NAME={{project_name}}
+LOG_LEVEL=debug
+
+# Database (uncomment if database selected)
+# DATABASE_URL=postgresql://user:password@localhost:5432/{{project_name}}?schema=public
+
+# Authentication (uncomment if auth selected)
+# AUTH_SECRET=generate-a-secret-at-least-32-chars-long
+# AUTH_URL=http://localhost:3000
+
+# External Services
+# API_KEY=your-api-key-here
+```
+
+## Usage Notes
+
+- Import `env` from `@/lib/env` instead of accessing `process.env` directly
+- Add new environment variables to both the zod schema AND `.env.example`
+- The schema validates at import time — if validation fails, the app exits immediately with clear error messages
+- Use `z.coerce.number()` for numeric env vars (they're always strings in `process.env`)
+- Mark optional variables with `.optional()` or `.default()`

package/templates/scaffolds/error-handling.md

@@ -0,0 +1,171 @@
+# Enterprise Pattern: Structured Error Handling
+
+Generate the following error handling pattern adapted to the project's chosen stack.
+
+## Core Error Classes (`src/lib/errors.ts`)
+
+```typescript
+/**
+ * Base application error with structured metadata.
+ * All custom errors extend this class for consistent handling.
+ */
+export class AppError extends Error {
+  public readonly statusCode: number;
+  public readonly code: string;
+  public readonly isOperational: boolean;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    options: {
+      statusCode?: number;
+      code?: string;
+      isOperational?: boolean;
+      details?: Record<string, unknown>;
+      cause?: Error;
+    } = {},
+  ) {
+    super(message, { cause: options.cause });
+    this.name = this.constructor.name;
+    this.statusCode = options.statusCode ?? 500;
+    this.code = options.code ?? 'INTERNAL_ERROR';
+    this.isOperational = options.isOperational ?? true;
+    this.details = options.details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details && { details: this.details }),
+      },
+    };
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, { statusCode: 400, code: 'VALIDATION_ERROR', details });
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id?: string) {
+    super(id ? `${resource} with id '${id}' not found` : `${resource} not found`, {
+      statusCode: 404,
+      code: 'NOT_FOUND',
+      details: { resource, ...(id && { id }) },
+    });
+  }
+}
+
+export class AuthenticationError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(message, { statusCode: 401, code: 'UNAUTHENTICATED' });
+  }
+}
+
+export class AuthorisationError extends AppError {
+  constructor(message = 'Insufficient permissions') {
+    super(message, { statusCode: 403, code: 'FORBIDDEN' });
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, { statusCode: 409, code: 'CONFLICT', details });
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(retryAfterSeconds?: number) {
+    super('Too many requests', {
+      statusCode: 429,
+      code: 'RATE_LIMITED',
+      details: retryAfterSeconds ? { retryAfter: retryAfterSeconds } : undefined,
+    });
+  }
+}
+```
+
+## API Error Response Format
+
+All API errors return this consistent structure:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email address is invalid",
+    "details": {
+      "field": "email",
+      "value": "not-an-email"
+    }
+  }
+}
+```
+
+## Error Handling Middleware (Express/Fastify/Hono)
+
+```typescript
+// Adapt to the chosen framework's middleware pattern
+export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  if (err instanceof AppError) {
+    logger.warn({ err, requestId: req.id }, err.message);
+    return res.status(err.statusCode).json(err.toJSON());
+  }
+
+  // Unexpected errors — log full stack, return generic message
+  logger.error({ err, requestId: req.id }, 'Unhandled error');
+  return res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'An unexpected error occurred',
+    },
+  });
+}
+```
+
+## React Error Boundary (if frontend)
+
+```typescript
+'use client';
+
+import { Component, type ReactNode } from 'react';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error('ErrorBoundary caught:', error, info);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? (
+        <div role="alert">
+          <h2>Something went wrong</h2>
+          <p>{this.state.error?.message}</p>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+```

package/templates/scaffolds/graceful-shutdown.md

@@ -0,0 +1,139 @@
+# Enterprise Pattern: Graceful Shutdown
+
+Generate the following graceful shutdown pattern adapted to the project's chosen framework.
+
+## Shutdown Handler (`src/lib/shutdown.ts`)
+
+```typescript
+import { logger } from '@/lib/logger';
+
+type CleanupFn = () => Promise<void> | void;
+
+const cleanupHandlers: Array<{ name: string; fn: CleanupFn }> = [];
+let isShuttingDown = false;
+
+/**
+ * Register a cleanup function to run during graceful shutdown.
+ * Handlers run in reverse registration order (LIFO).
+ *
+ * @example
+ * registerCleanup('database', async () => {
+ *   await prisma.$disconnect();
+ * });
+ *
+ * registerCleanup('http-server', async () => {
+ *   await new Promise<void>((resolve) => server.close(resolve));
+ * });
+ */
+export function registerCleanup(name: string, fn: CleanupFn): void {
+  cleanupHandlers.push({ name, fn });
+}
+
+/**
+ * Execute graceful shutdown. Called automatically on SIGTERM/SIGINT.
+ * Runs all cleanup handlers with a timeout to prevent hanging.
+ */
+async function shutdown(signal: string): Promise<void> {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  logger.info(`Received ${signal}, starting graceful shutdown...`);
+
+  const SHUTDOWN_TIMEOUT_MS = 30_000;
+  const timeoutPromise = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Shutdown timed out')), SHUTDOWN_TIMEOUT_MS),
+  );
+
+  try {
+    // Run handlers in reverse order (LIFO)
+    const handlers = [...cleanupHandlers].reverse();
+
+    await Promise.race([
+      (async () => {
+        for (const handler of handlers) {
+          try {
+            logger.info(`Cleaning up: ${handler.name}`);
+            await handler.fn();
+            logger.info(`Cleaned up: ${handler.name}`);
+          } catch (error) {
+            logger.error(`Cleanup failed: ${handler.name}`, {
+              error: error instanceof Error ? error.message : String(error),
+            });
+          }
+        }
+      })(),
+      timeoutPromise,
+    ]);
+
+    logger.info('Graceful shutdown complete');
+    process.exit(0);
+  } catch (error) {
+    logger.error('Shutdown timed out, forcing exit', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    process.exit(1);
+  }
+}
+
+/**
+ * Install signal handlers. Call this once at application startup.
+ */
+export function installShutdownHandlers(): void {
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  // Handle uncaught exceptions — log and exit
+  process.on('uncaughtException', (error) => {
+    logger.fatal('Uncaught exception', { error: error.message, stack: error.stack });
+    shutdown('uncaughtException');
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason) => {
+    logger.fatal('Unhandled rejection', {
+      reason: reason instanceof Error ? reason.message : String(reason),
+    });
+    shutdown('unhandledRejection');
+  });
+}
+```
+
+## Server Entry Point Integration
+
+```typescript
+import { installShutdownHandlers, registerCleanup } from '@/lib/shutdown';
+import { logger } from '@/lib/logger';
+import { env } from '@/lib/env';
+
+// Install signal handlers first
+installShutdownHandlers();
+
+// Start server
+const server = app.listen(env.PORT, env.HOST, () => {
+  logger.info(`Server started`, { port: env.PORT, host: env.HOST, env: env.NODE_ENV });
+});
+
+// Register cleanup: close HTTP server (stop accepting new connections, drain existing)
+registerCleanup('http-server', async () => {
+  await new Promise<void>((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+});
+
+// Register cleanup: disconnect database
+registerCleanup('database', async () => {
+  // Adapt to chosen ORM:
+  // Prisma: await prisma.$disconnect();
+  // Drizzle: await pool.end();
+  // TypeORM: await dataSource.destroy();
+});
+```
+
+## Usage Notes
+
+- Always install shutdown handlers at the very start of the application entry point
+- Register cleanup handlers immediately after creating resources (server, DB connections, etc.)
+- LIFO order ensures the HTTP server stops accepting connections before database disconnects
+- The 30-second timeout prevents infinite hangs from stuck connections
+- Docker sends SIGTERM first, then SIGKILL after the grace period (default 10s, configure with `stop_grace_period`)
+- In Kubernetes, set `terminationGracePeriodSeconds` to match or exceed the shutdown timeout

package/templates/scaffolds/health-check.md

@@ -0,0 +1,109 @@
+# Enterprise Pattern: Health Check Endpoints
+
+Generate the following health check pattern adapted to the project's chosen framework.
+
+## Health Check Routes
+
+### Liveness Check (`/health`)
+
+Returns 200 if the process is alive. No dependency checks — used by load balancers and container orchestrators for basic liveness.
+
+```typescript
+// GET /health
+export function healthHandler(req: Request, res: Response) {
+  res.status(200).json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    service: env.SERVICE_NAME,
+    uptime: process.uptime(),
+  });
+}
+```
+
+### Readiness Check (`/health/ready`)
+
+Returns 200 only if all dependencies are reachable. Used by orchestrators to determine if the service can accept traffic.
+
+```typescript
+interface HealthComponent {
+  name: string;
+  status: 'healthy' | 'unhealthy' | 'degraded';
+  responseTimeMs?: number;
+  details?: Record<string, unknown>;
+}
+
+async function checkDatabase(): Promise<HealthComponent> {
+  const start = Date.now();
+  try {
+    // Adapt to chosen ORM/database driver
+    // Prisma: await prisma.$queryRaw`SELECT 1`
+    // Drizzle: await db.execute(sql`SELECT 1`)
+    // Raw: await pool.query('SELECT 1')
+    return {
+      name: 'database',
+      status: 'healthy',
+      responseTimeMs: Date.now() - start,
+    };
+  } catch (error) {
+    return {
+      name: 'database',
+      status: 'unhealthy',
+      responseTimeMs: Date.now() - start,
+      details: { error: error instanceof Error ? error.message : 'Unknown error' },
+    };
+  }
+}
+
+// Add more dependency checks as needed:
+// async function checkRedis(): Promise<HealthComponent> { ... }
+// async function checkExternalApi(): Promise<HealthComponent> { ... }
+
+// GET /health/ready
+export async function readinessHandler(req: Request, res: Response) {
+  const checks = await Promise.all([
+    checkDatabase(),
+    // checkRedis(),
+    // checkExternalApi(),
+  ]);
+
+  const allHealthy = checks.every((c) => c.status === 'healthy');
+  const hasDegraded = checks.some((c) => c.status === 'degraded');
+
+  const overallStatus = allHealthy ? 'ok' : hasDegraded ? 'degraded' : 'unavailable';
+  const statusCode = allHealthy ? 200 : hasDegraded ? 200 : 503;
+
+  res.status(statusCode).json({
+    status: overallStatus,
+    timestamp: new Date().toISOString(),
+    service: env.SERVICE_NAME,
+    uptime: process.uptime(),
+    components: checks,
+  });
+}
+```
+
+## Response Format
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-03-17T14:00:00.000Z",
+  "service": "acme-portal",
+  "uptime": 3600.5,
+  "components": [
+    {
+      "name": "database",
+      "status": "healthy",
+      "responseTimeMs": 2
+    }
+  ]
+}
+```
+
+## Usage Notes
+
+- `/health` should be fast and dependency-free — never add database checks to liveness
+- `/health/ready` should check ALL critical dependencies
+- Set appropriate timeouts on dependency checks (2-5 seconds max)
+- In Kubernetes: use `/health` for `livenessProbe` and `/health/ready` for `readinessProbe`
+- Consider adding a `/health/startup` for slow-starting services

package/templates/scaffolds/structured-logging.md

@@ -0,0 +1,134 @@
+# Enterprise Pattern: Structured JSON Logging
+
+Generate the following logging pattern adapted to the project's chosen stack.
+
+## Logger Module (`src/lib/logger.ts`)
+
+```typescript
+import { randomUUID } from 'node:crypto';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: string;
+  correlationId?: string;
+  requestId?: string;
+  userId?: string;
+  tenantId?: string;
+  service: string;
+  [key: string]: unknown;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  fatal: 50,
+};
+
+const currentLevel = (process.env.LOG_LEVEL as LogLevel) ?? 'info';
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+function formatEntry(level: LogLevel, message: string, context?: Record<string, unknown>): string {
+  const entry: LogEntry = {
+    level,
+    message,
+    timestamp: new Date().toISOString(),
+    service: process.env.SERVICE_NAME ?? '{{project_name}}',
+    ...context,
+  };
+  return JSON.stringify(entry);
+}
+
+export const logger = {
+  debug(message: string, context?: Record<string, unknown>) {
+    if (shouldLog('debug')) console.debug(formatEntry('debug', message, context));
+  },
+  info(message: string, context?: Record<string, unknown>) {
+    if (shouldLog('info')) console.info(formatEntry('info', message, context));
+  },
+  warn(message: string, context?: Record<string, unknown>) {
+    if (shouldLog('warn')) console.warn(formatEntry('warn', message, context));
+  },
+  error(message: string, context?: Record<string, unknown>) {
+    if (shouldLog('error')) console.error(formatEntry('error', message, context));
+  },
+  fatal(message: string, context?: Record<string, unknown>) {
+    if (shouldLog('fatal')) console.error(formatEntry('fatal', message, context));
+  },
+
+  /**
+   * Create a child logger with pre-bound context (e.g., per-request).
+   */
+  child(defaultContext: Record<string, unknown>) {
+    return {
+      debug: (msg: string, ctx?: Record<string, unknown>) =>
+        logger.debug(msg, { ...defaultContext, ...ctx }),
+      info: (msg: string, ctx?: Record<string, unknown>) =>
+        logger.info(msg, { ...defaultContext, ...ctx }),
+      warn: (msg: string, ctx?: Record<string, unknown>) =>
+        logger.warn(msg, { ...defaultContext, ...ctx }),
+      error: (msg: string, ctx?: Record<string, unknown>) =>
+        logger.error(msg, { ...defaultContext, ...ctx }),
+      fatal: (msg: string, ctx?: Record<string, unknown>) =>
+        logger.fatal(msg, { ...defaultContext, ...ctx }),
+    };
+  },
+};
+
+/**
+ * Generate a correlation ID for request tracing.
+ */
+export function generateCorrelationId(): string {
+  return randomUUID();
+}
+```
+
+## Request Logging Middleware
+
+```typescript
+import { generateCorrelationId, logger } from '@/lib/logger';
+
+// Adapt to the chosen framework's middleware pattern
+export function requestLogger(req: Request, res: Response, next: NextFunction) {
+  const correlationId = (req.headers['x-correlation-id'] as string) ?? generateCorrelationId();
+  const requestId = generateCorrelationId();
+  const start = Date.now();
+
+  // Attach to request for downstream use
+  req.correlationId = correlationId;
+  req.requestId = requestId;
+
+  // Set response header for client correlation
+  res.setHeader('x-correlation-id', correlationId);
+  res.setHeader('x-request-id', requestId);
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+    logger.info('request completed', {
+      correlationId,
+      requestId,
+      method: req.method,
+      path: req.path,
+      statusCode: res.statusCode,
+      durationMs: duration,
+      userAgent: req.headers['user-agent'],
+    });
+  });
+
+  next();
+}
+```
+
+## Usage Notes
+
+- In production, pipe stdout to a log aggregator (Datadog, CloudWatch, etc.)
+- Use `logger.child()` to bind request context once, then log throughout the request lifecycle
+- Always include `correlationId` for distributed tracing across services
+- Never log sensitive data (passwords, tokens, PII) — use redaction middleware if needed