webspresso 0.0.104 → 0.0.106

package/.agents/FLAGS.md

@@ -0,0 +1,118 @@
+# Feature Flags & Canary Traffic Splitter (`core/flags`)
+
+Webspresso features an enterprise-grade, zero-dependency **Feature Flag & Canary Traffic Splitting Engine** in `core/flags/`. It enables gradual rollouts, multivariate A/B testing, user/role/domain targeting, and runtime overrides across Nunjucks SSR templates, API endpoints (`defineApi`), service layers, and Edge/Hono adapters.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Sub-Microsecond Deterministic Bucketing**:
+   - FNV-1a 32-bit hashing algorithm (`getBucket`) maps user identifiers to deterministic integer buckets `0 .. 99` across distributed nodes without network calls.
+2. **Flexible Targeting Rules**:
+   - **Boolean Toggles**: `enabled: true | false`.
+   - **Canary Percentage Rollout**: `rollout: 10` (10% of traffic, consistent per user).
+   - **Targeted Whitelists**: `users: ['user_123', 'admin@corp.com']`.
+   - **Role-Based Targeting**: `roles: ['admin', 'beta_tester']`.
+   - **Email Domain Targeting**: `emailDomains: ['acme.com']`.
+   - **Multivariate A/B Variants**: `variants: [{ name: 'blue_button', weight: 50 }, { name: 'green_button', weight: 50 }]`.
+   - **Custom Predicates**: `condition: (ctx) => ctx.plan === 'enterprise'`.
+3. **Multi-Layer Integration**:
+   - **Express / Hono Middleware**: Automatically injects `req.flags`, `req.hasFeature()`, and `req.getVariant()`.
+   - **Nunjucks SSR Templates**: Access via `{{ fsy.hasFeature('new_ui') }}` and `{{ fsy.flag('theme') }}`.
+   - **Declarative API Route Guard**: `defineApi({ flag: 'beta_feature' })` returns HTTP 404 (or configured status) if disabled.
+   - **Environment Variable Overrides**: Instant runtime overrides via `FEATURE_<FLAG_NAME>=true|false`.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Application Configuration
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  flags: {
+    // 1. Simple toggle
+    dark_mode: true,
+
+    // 2. 20% Canary rollout
+    new_checkout: {
+      rollout: 20,
+    },
+
+    // 3. User & Role targeting
+    ai_assistant: {
+      roles: ['pro', 'admin'],
+      users: ['vip_client_1'],
+    },
+
+    // 4. Multivariate A/B Test
+    pricing_page_test: {
+      variants: [
+        { name: 'control', weight: 50 },
+        { name: 'discount_banner', weight: 50 },
+      ],
+    },
+  },
+});
+```
+
+### 2. Nunjucks SSR Templates (`pages/*.njk`)
+
+```nunjucks
+{% if fsy.hasFeature('new_checkout') %}
+  {% include "components/new-checkout.njk" %}
+{% else %}
+  {% include "components/legacy-checkout.njk" %}
+{% endif %}
+
+{% if fsy.flag('pricing_page_test') == 'discount_banner' %}
+  <div class="banner">Special 20% Discount Applied!</div>
+{% endif %}
+```
+
+### 3. File-Based API Endpoints (`pages/api/...`)
+
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  // Automatically blocks request with HTTP 404 if flag is disabled
+  flag: 'ai_assistant',
+  handler: async (req, res, ctx) => {
+    // Also accessible inside ctx or req
+    const isVip = ctx.hasFeature('vip_access');
+    return res.json({ success: true, isVip });
+  },
+});
+```
+
+### 4. Route Guard Middleware
+
+```javascript
+const { createFeatureFlagManager } = require('webspresso');
+
+const flags = createFeatureFlagManager({
+  flags: { secret_admin: { roles: ['admin'] } },
+});
+
+// Use as standalone route middleware
+app.get('/admin/secret', flags.guard('secret_admin', { statusCode: 403 }), (req, res) => {
+  res.send('Welcome, Admin!');
+});
+```
+
+---
+
+## ⚙️ Environment Overrides
+
+Flags can be overridden at runtime without code deployment or restart:
+
+```bash
+# Enable flag
+FEATURE_NEW_CHECKOUT=true npm start
+
+# Disable flag
+FEATURE_NEW_CHECKOUT=false npm start
+```

package/.agents/HEALTH.md

@@ -0,0 +1,118 @@
+# Cloud & Kubernetes Health & Readiness Probes (`core/health`)
+
+Webspresso includes a zero-dependency, Docker & Kubernetes-native health inspection system. It provides standard liveness (`/healthz`), readiness (`/readyz`), and combined diagnostics endpoints with automatic database pings, background worker queue checks, event loop delay metrics, and instant graceful shutdown draining integration.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Kubernetes Liveness Probe (`/healthz`)**:
+   - Confirms process vitality and responsiveness.
+   - Gathers memory footprint (`rss`, `heapUsed`, `heapTotal` formatted and raw bytes), process uptime, PID, platform, and event loop lag statistics (`meanMs`, `maxMs`, `p99Ms`).
+   - If event loop delay exceeds threshold (`eventLoopThresholdMs`), flags status as `degraded`.
+
+2. **Kubernetes Readiness Probe (`/readyz`)**:
+   - Confirms the container is fully prepared to handle live client traffic.
+   - **Database Connectivity**: Pings active Knex instance (`SELECT 1`) with timeout protection.
+   - **Queue Readiness**: Probes worker queue instance status.
+   - **Custom Probes**: Executes user-registered async checks concurrently (`checks: { redis, stripe }`).
+   - Returns `HTTP 200` (`{ ready: true, status: 'ready' }`) when all components are healthy.
+   - Returns `HTTP 503` (`{ ready: false, status: 'unhealthy', checks: ... }`) if any component fails.
+
+3. **Graceful Draining Integration (`ShutdownManager`)**:
+   - As soon as the server enters shutdown draining (`app.close()` or `SIGTERM`/`SIGINT`), `/readyz` immediately returns `HTTP 503` (`{ ready: false, status: 'draining' }`).
+   - Cloud load balancers (AWS ALB, K8s Ingress, Google Cloud, Cloudflare) immediately stop routing new traffic to this instance, while existing active requests drain cleanly without dropping a single connection.
+
+---
+
+## 🚀 Configuration Examples
+
+### 1. Simple Enablement
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: 'pages',
+  // Enables /healthz (liveness), /readyz (readiness), and /health (combined)
+  healthCheck: true,
+});
+```
+
+Shorthand custom path:
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  healthCheck: '/api/status', // Mounts combined status on /api/status
+});
+```
+
+### 2. Full Production Configuration
+
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  db: myDatabaseInstance,
+  queue: myQueueInstance,
+  healthCheck: {
+    enabled: true,
+    path: '/healthz',               // Liveness probe URL
+    readyPath: '/readyz',           // Readiness probe URL
+    combinedPath: '/health',        // Diagnostic summary URL
+    db: true,                       // Automatically probe database (SELECT 1)
+    queue: true,                    // Automatically probe worker queue
+    eventLoopLag: true,             // Monitor event loop delay
+    eventLoopThresholdMs: 300,      // Lag threshold in ms
+    timeoutMs: 2500,                // Probe timeout before marking down
+    checks: {                       // Custom dependency probes
+      redis: async () => redisClient.ping(),
+      stripe: async () => checkStripeHealth(),
+    },
+    headers: {
+      'Cache-Control': 'no-store, no-cache, must-revalidate',
+      'X-Content-Type-Options': 'nosniff',
+    },
+  },
+});
+```
+
+---
+
+## ☸️ Kubernetes Pod Spec Example
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 10
+  timeoutSeconds: 3
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /readyz
+    port: 3000
+  initialDelaySeconds: 2
+  periodSeconds: 5
+  timeoutSeconds: 2
+  failureThreshold: 2
+```
+
+---
+
+## 🔍 Programmatic Inspection
+
+Access health state directly in code or CLI scripts:
+
+```javascript
+// Get complete diagnostic payload
+const status = await app.getHealthStatus();
+console.log('Liveness:', status.liveness);
+console.log('Readiness:', status.readiness);
+
+// Or via healthManager
+const liveness = await app.healthManager.getLiveness();
+const readiness = await app.healthManager.getReadiness();
+```

package/.agents/LIMITS.md

@@ -0,0 +1,109 @@
+# Configurable Payload Size Limits & DoS Protection (`core/limits`)
+
+Webspresso provides a zero-dependency, configurable request body size limiter and Denial of Service (DoS) protection layer. It safeguards Node.js memory against payload exhaustion attacks while supporting per-route overrides, streaming bypass, and native raw body capture for HMAC webhook verification.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Multi-Parser Configuration**:
+   - `json`: Size limit for `application/json` (default: `'1mb'`).
+   - `urlencoded`: Size limit for `application/x-www-form-urlencoded` (default: `'1mb'`).
+   - `parameterLimit`: Maximum number of URL-encoded form parameters (default: `1000`).
+   - `raw`: Size limit for `application/octet-stream` (default: `false` / disabled).
+   - `text`: Size limit for `text/plain` (default: `false` / disabled).
+2. **Standard Exception Mapping**:
+   - Limit exceeded -> Throws `PayloadTooLargeError` (HTTP 413) with `{ limit, length, expected }` details and `code: 'PAYLOAD_TOO_LARGE'`.
+   - Parameter exhaustion -> Throws `PayloadTooLargeError` (HTTP 413) with `code: 'PARAMETERS_TOO_MANY'`.
+   - Malformed JSON -> Throws `BadRequestError` (HTTP 400) with `code: 'INVALID_JSON_PAYLOAD'`.
+3. **Webhook & HMAC Signature Verification**:
+   - `captureRawBody: true` stores incoming unparsed `Buffer` on `req.rawBody` for zero-overhead cryptographic signatures (Polar, Stripe, LemonSqueezy, GitHub).
+4. **Route Overrides & Streaming Bypass**:
+   - `limits.routes`: Generous limits for specific paths (e.g. `/api/upload` -> 25MB) without loosening server-wide protection.
+   - `limits.exclude`: Completely skips global body parsers for streaming and custom multipart endpoints.
+
+---
+
+## 🚀 Configuration Examples
+
+### 1. Global Configuration
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: 'pages',
+  limits: {
+    json: '2mb',           // 2 Megabytes for JSON
+    urlencoded: '1mb',     // 1 Megabyte for Forms
+    parameterLimit: 2000,  // Up to 2000 parameters
+    raw: '10mb',           // Enable raw buffer parsing for binary data
+    captureRawBody: true,  // Automatically populate req.rawBody
+  },
+});
+```
+
+Shorthand (applies to both JSON and URL-encoded):
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  limits: '5mb', // Both json and urlencoded set to 5 MB
+});
+```
+
+### 2. Route Overrides & Exclusions
+
+```javascript
+const app = createApp({
+  pagesDir: 'pages',
+  limits: {
+    json: '500kb', // Tight global limit for standard APIs
+    routes: {
+      '/api/import/json': { json: '25mb' }, // Relaxed limit for batch import
+      '/api/webhooks/*': { raw: '5mb', captureRawBody: true },
+    },
+    exclude: [
+      '/api/stream/upload', // Skip global body parser entirely for socket streaming
+    ],
+  },
+});
+```
+
+### 3. Webhook Signature Verification with `req.rawBody`
+
+```javascript
+// pages/api/webhooks/polar.post.js
+const crypto = require('crypto');
+const { defineApi, UnauthorizedError } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const signature = req.headers['webhook-signature'];
+    const expected = crypto
+      .createHmac('sha256', process.env.POLAR_WEBHOOK_SECRET)
+      .update(req.rawBody) // Native Buffer captured via captureRawBody
+      .digest('hex');
+
+    if (signature !== expected) {
+      throw new UnauthorizedError('Invalid signature');
+    }
+
+    return res.json({ received: true });
+  },
+});
+```
+
+---
+
+## 🛡️ Standalone Middleware Usage
+
+For manual route mounting or custom Express routers:
+
+```javascript
+const { createLimitsMiddleware } = require('webspresso');
+
+// Mount on custom router or endpoint
+app.post('/custom-endpoint', createLimitsMiddleware({ json: '50mb' }), (req, res) => {
+  res.json({ size: req.body.length });
+});
+```

package/.agents/LOGGING.md

@@ -0,0 +1,93 @@
+# Structured Cloud Logging & Distributed Tracing Guide
+
+Webspresso features an enterprise, zero-dependency Structured Cloud Logger (`core/logger`) designed specifically for serverless and containerized cloud platforms (Google Cloud Run, AWS App Runner, ECS Fargate, Lambda, Kubernetes).
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Native Cloud Platform Detection & Formatting**:
+   - **Google Cloud Platform (`format: 'gcp'`)**: Automatically emits JSON payloads with Google Cloud Logging `severity` levels (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`), `logging.googleapis.com/trace`, `logging.googleapis.com/spanId`, and RFC `httpRequest` metadata.
+   - **Amazon Web Services (`format: 'aws'`)**: Formats logs with `level`, `requestId`, `xrayTraceId`, and `http` metrics compatible with AWS CloudWatch and AWS X-Ray.
+   - **Standard JSON (`format: 'json'`)**: Compact, structured single-line JSON stream for Docker, Kubernetes, and Datadog.
+   - **Development Pretty (`format: 'pretty'`)**: Fast, ANSI color-coded console logs for local developer happiness.
+2. **Distributed Tracing Context Propagation**:
+   - Parses incoming request trace headers automatically:
+     - `x-cloud-trace-context` (Google Cloud Trace)
+     - `x-amzn-trace-id` (AWS X-Ray)
+     - `traceparent` (W3C standard)
+     - `x-request-id` / `x-correlation-id`
+   - Injects trace ID and span ID into every log statement emitted during the request lifecycle.
+3. **Automatic Child Logger on Requests (`req.logger`)**:
+   - In API route handlers and SSR page loaders, `req.logger` is pre-bound to the request's trace ID and contextual metadata.
+   - Automatically logs HTTP access on request finish (`res.on('finish')`) with latency, status code, remote IP, and user-agent.
+4. **Deep Sensitive Key Redaction**:
+   - Recursively masks sensitive fields (`password`, `token`, `secret`, `authorization`, `cookie`, `apiKey`) to prevent accidental credential leakage in cloud log aggregation systems.
+
+---
+
+## 🚀 Usage in Application Code
+
+### In API Route Handlers
+
+```javascript
+// pages/api/orders.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({ amount: z.number().positive(), customerId: z.string() }),
+  }),
+  handler: async (req, res) => {
+    // req.logger is automatically bound to the request's trace ID
+    req.logger.info('Processing order checkout', {
+      customerId: req.input.body.customerId,
+      amount: req.input.body.amount,
+    });
+
+    try {
+      const order = await req.service('order.create', req.input.body);
+      req.logger.info('Order processed successfully', { orderId: order.id });
+      return res.status(201).json(order);
+    } catch (err) {
+      req.logger.error('Failed to process order', { error: err.message });
+      throw err;
+    }
+  },
+});
+```
+
+### Standalone Logger & Child Context
+
+```javascript
+const { createLogger } = require('webspresso');
+
+const logger = createLogger({
+  format: 'auto', // 'gcp' | 'aws' | 'json' | 'pretty'
+  level: 'info',
+  defaultMeta: { service: 'payment-worker' },
+  project: 'my-gcp-project', // optional GCP project ID
+});
+
+logger.info('Worker started');
+
+// Create contextual child logger
+const jobLogger = logger.child({ jobId: 'job_42' });
+jobLogger.info('Task execution started');
+```
+
+### Configuration in `createApp`
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: './pages',
+  logger: {
+    format: 'auto', // Auto-detected from K_SERVICE, AWS_EXECUTION_ENV, or NODE_ENV
+    level: 'info',
+    exclude: ['/healthz', '/readyz', '/favicon.ico'],
+    redact: ['password', 'secret', 'token'],
+  },
+});
+```

package/.agents/METRICS.md

@@ -0,0 +1,127 @@
+# Cloud Metrics & Distributed Tracing Guide
+
+Webspresso provides an enterprise-grade, zero-dependency Cloud Metrics & Distributed Tracing engine (`core/metrics`) delivering Prometheus exposition format (`/metrics`), JSON telemetry (`/metrics.json`), HTTP latency histograms, and W3C/GCP/AWS distributed tracing header propagation.
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Prometheus-Compatible Exposition Format**:
+   - Zero external dependencies (no `prom-client` or OpenTelemetry npm packages required).
+   - Generates compliant `text/plain; version=0.0.4; charset=utf-8` output directly consumable by Prometheus, Grafana Agent, Google Cloud Managed Service for Prometheus, AWS CloudWatch Container Insights, and Datadog.
+   - Dual-format exposition: `/metrics` for Prometheus scraping and `/metrics.json` (or `Accept: application/json`) for programmatic inspection or lightweight dashboards.
+2. **Distributed Tracing & W3C Propagation**:
+   - Parses incoming tracing headers automatically (`traceparent`, `x-cloud-trace-context`, `x-amzn-trace-id`, `x-request-id`).
+   - Automatically injects `x-trace-id` and W3C `traceparent` (`00-${traceId}-${spanId}-01`) onto outgoing HTTP response headers.
+   - Attaches `req.traceId` and `req.spanId` to the incoming request object for seamless correlation with `req.logger`.
+3. **Core HTTP Request Telemetry**:
+   - `webspresso_http_requests_total{method, route, status}`: Counter for all processed HTTP requests.
+   - `webspresso_http_request_duration_seconds{method, route}`: Latency histogram with cumulative buckets, `_sum`, and `_count`.
+   - `webspresso_http_active_requests`: Gauge tracking in-flight concurrent requests.
+   - **Noise-free scraping**: Internal scrape calls to `/metrics`, `/metrics.json`, and `/healthz` are excluded from HTTP latency counters to prevent self-polluting metrics graphs.
+4. **Automated Node.js & Framework Collectors**:
+   - **Process & Memory**: `process_uptime_seconds`, `nodejs_heap_size_used_bytes`, `nodejs_heap_size_total_bytes`, `process_resident_memory_bytes`, `nodejs_external_memory_bytes`.
+   - **CPU**: `process_cpu_user_seconds_total`, `process_cpu_system_seconds_total`.
+   - **Event Loop Lag**: `nodejs_eventloop_lag_seconds{quantile="0.50|0.99|max"}` via native `perf_hooks.monitorEventLoopDelay`.
+   - **Database Connection Pool**: `webspresso_db_pool_size`, `webspresso_db_pool_used`, `webspresso_db_pool_available` (Knex pool).
+   - **In-Memory Cache**: `webspresso_cache_entries`, `webspresso_cache_bytes` (LRU cache).
+   - **Circuit Breakers**: `webspresso_circuit_breaker_state{name}` (0=closed, 1=half-open, 2=open), `webspresso_circuit_breaker_failures_total{name}`.
+5. **Security & Gating**:
+   - Protect metrics endpoints with bearer token authentication (`auth: 'secret-token'`).
+
+---
+
+## 🚀 Configuration & Enabling Metrics
+
+### 1. Enabling via `createApp`
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  metrics: {
+    enabled: true,                // default: true if metrics option is passed
+    path: '/metrics',             // default: '/metrics'
+    collectDefault: true,         // default: true (system, memory, pool, cache, lag)
+    traceHeader: true,            // default: true (x-trace-id, traceparent)
+    auth: process.env.METRICS_TOKEN || null, // Optional Bearer token protection
+    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  },
+});
+```
+
+Or enable with shorthand:
+
+```javascript
+createApp({
+  metrics: true, // mounts /metrics and /metrics.json with defaults
+});
+```
+
+---
+
+## 📊 Custom Application Metrics
+
+Application routes, services, and plugins can register and record custom domain metrics via `app.metrics` or `req.metrics`:
+
+```javascript
+// Register a custom counter
+const orderCounter = app.metrics.counter(
+  'shop_orders_placed_total',
+  'Total number of completed customer orders'
+);
+
+// Register a custom gauge
+const activeUsersGauge = app.metrics.gauge(
+  'shop_active_cart_sessions',
+  'Number of carts currently active'
+);
+
+// In an API handler
+// pages/api/checkout.post.js
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const order = await req.service('order.create', req.body);
+    
+    // Increment domain metric
+    orderCounter.inc({ plan: order.plan, currency: order.currency }, 1);
+    
+    return res.status(201).json(order);
+  },
+});
+```
+
+---
+
+## 🛡️ Standalone Registry Usage
+
+```javascript
+const { createMetricsRegistry } = require('webspresso');
+
+const registry = createMetricsRegistry();
+
+const counter = registry.counter('jobs_processed_total', 'Jobs processed by worker');
+counter.inc({ queue: 'email', status: 'success' }, 1);
+
+const histogram = registry.histogram('job_execution_duration_seconds', 'Job execution duration', [0.1, 0.5, 1, 5]);
+histogram.observe({ queue: 'email' }, 0.24);
+
+// Format output
+console.log(registry.formatPrometheus());
+console.log(JSON.stringify(registry.formatJson(), null, 2));
+```
+
+---
+
+## 📈 Prometheus Scrape Configuration (`prometheus.yml`)
+
+```yaml
+scrape_configs:
+  - job_name: 'webspresso-app'
+    scrape_interval: 15s
+    metrics_path: '/metrics'
+    bearer_token: 'YOUR_METRICS_TOKEN' # if auth is enabled
+    static_configs:
+      - targets: ['localhost:3000']
+```

package/.agents/MIGRATION_JOBS.md

@@ -0,0 +1,95 @@
+# Cloud Migration Jobs & Zero-Downtime Database Deploy Guide
+
+Webspresso provides an enterprise, zero-downtime database migration architecture designed specifically for Google Cloud Run, AWS ECS Fargate, AWS App Runner, and Kubernetes.
+
+---
+
+## 🎯 The Cloud Migration Challenge
+
+In containerized, autoscaling cloud platforms (such as Google Cloud Run or AWS ECS), running migrations inside the web application container startup command (`CMD ["node", "server.js"]`) causes severe production risks:
+
+1. **Concurrent Migration Race Conditions**: If a new revision autoscales to multiple container instances, multiple containers attempt to run migrations simultaneously, causing deadlock or corrupt schema states.
+2. **Crash Loops & Downtime**: If a migration script fails, web containers fail health checks and crash-loop, but HTTP traffic might already hit partially-migrated schemas.
+3. **Stale Lock Hangs**: If a container is forcefully terminated by Cloud Run or ECS during migration, Knex's `knex_migrations_lock` table is left locked (`Migration table is already locked`), breaking all subsequent CI/CD deployments.
+
+### The Webspresso Solution: Dedicated Pre-Deploy Cloud Migration Jobs
+
+Webspresso solves this by separating database schema migrations into a single, isolated pre-deploy job that runs to completion before new web service revisions receive traffic:
+
+```
+[ Git Push / CI/CD ]
+         │
+         ▼
+[ Build Container Image ]
+         │
+         ▼
+[ Run Cloud Migration Job ] ──── (Fails? Stop deployment, keep old web version running)
+         │ (Success)
+         ▼
+[ Deploy Web Service Revision ] ─── (Safely route 100% traffic to new code)
+```
+
+---
+
+## 🚀 CLI Commands
+
+### 1. Scaffold Migration Jobs (`add:migration-job`)
+
+```bash
+# For Google Cloud Run (cloudrun-job.yaml + deploy-cloudrun-migration.sh)
+npx webspresso add:migration-job --platform cloudrun --app my-app --cloudsql "project:region:instance"
+
+# For AWS ECS Fargate & App Runner (ecs-migration-task.json + deploy-aws-migration.sh)
+npx webspresso add:migration-job --platform aws --app my-app --region us-east-1
+
+# For Kubernetes / Helm (k8s/migration-job.yaml with pre-upgrade hooks)
+npx webspresso add:migration-job --platform k8s --app my-app
+
+# For all platforms
+npx webspresso add:migration-job --platform all
+```
+
+---
+
+## ⚡ Cloud-Safe Migration Options (`db:migrate`)
+
+Webspresso's `db:migrate` command features cloud resilience flags powered by `core/orm/migrate-cloud.js`:
+
+```bash
+# Cloud-Safe mode: exponential backoff connection retries + automatic stale lock auto-healing
+npx webspresso db:migrate --safe --env production
+
+# Dry-run: preview pending migrations without altering the database
+npx webspresso db:migrate --dry-run --env production
+
+# Auto-heal hanging locks left by aborted serverless jobs
+npx webspresso db:migrate --unlock-if-stale
+
+# Force unlock migration table immediately
+npx webspresso db:migrate --force-unlock
+```
+
+---
+
+## 🛡️ Zero-Downtime Migration Rules for Schema Evolution
+
+When modifying production schemas under zero-downtime requirements, follow the **Expand and Contract (Parallel Run)** pattern:
+
+| Goal | ❌ Risky (Breaks running old version) | ✅ Zero-Downtime Pattern |
+| :--- | :--- | :--- |
+| **Rename Column** | `table.renameColumn('old', 'new')` | 1. Add `new` column<br>2. Dual-write in application<br>3. Backfill data<br>4. Drop `old` column in subsequent deploy |
+| **Drop Column** | `table.dropColumn('field')` | Remove column references in application code first, deploy code, then drop column in the next deployment. |
+| **Add NOT NULL** | `table.string('col').notNullable()` | 1. Add nullable column or column with default value<br>2. Backfill existing rows<br>3. Alter to `notNullable` |
+| **Add Index** | Raw `CREATE INDEX` (locks table) | In Postgres: use `CREATE INDEX CONCURRENTLY` |
+
+---
+
+## 🔍 Preflight Verification (`deploy:check`)
+
+Webspresso's preflight scanner automatically audits migration strategies:
+
+```bash
+npx webspresso deploy:check --platform cloudrun --strict
+```
+
+If migrations exist and no cloud migration job is detected, it emits an actionable warning to prevent production container race conditions.