webspresso 0.0.105 → 0.0.107

package/.agents/AGENTS.md

@@ -19,6 +19,12 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](QUEUE.md) | `jobs/` |
 | **Decoupled Events & Signals** | [`.agents/EVENTS.md`](EVENTS.md) | `core/events/`, `listeners/` |
 | **Fault Tolerance / Circuit Breaker / Retry** | [`.agents/RESILIENCE.md`](RESILIENCE.md) | `core/resilience/` |
+| **Stateless Scale-Out (Redis Sessions & DB Pool)** | [`.agents/SCALE_OUT.md`](SCALE_OUT.md) | `core/auth/redis-session.js`, `core/orm/pool.js` |
+| **Cloud Secrets (GCP & AWS Secret Manager)** | [`.agents/SECRETS.md`](SECRETS.md) | `core/secrets/`, `bin/commands/secrets-pull.js` |
+| **Cloud Metrics & Distributed Tracing** | [`.agents/METRICS.md`](METRICS.md) | `core/metrics/`, `/metrics` |
+| **Cloud Migration Jobs (Zero-Downtime DB Deploy)** | [`.agents/MIGRATION_JOBS.md`](MIGRATION_JOBS.md) | `bin/commands/add-migration-job.js`, `core/orm/migrate-cloud.js` |
+| **Rate Limiting Engine (Zero-Dependency & Redis)** | [`.agents/RATE_LIMIT.md`](RATE_LIMIT.md) | `core/rate-limit/` |
+| **Feature Flags & Canary Splitter (`core/flags`)** | [`.agents/FLAGS.md`](FLAGS.md) | `core/flags/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](../index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -50,10 +56,10 @@ This `.agents/` customization root is organized into modular topic guides:
 10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
 11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
 12. **[Admin Panel Customization](.agents/ADMIN.md)** — Extending Mithril.js Admin Panel SPA (Custom pages `component.js`, custom field renderers, widgets, single & bulk actions).
-13. **[CLI Tooling & Commands](CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `add:docker`, `deploy:check`, `agents:init`.
+13. **[CLI Tooling & Commands](CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `add:docker`, `add:cloudrun`, `add:aws`, `add:cloudflare`, `deploy:check`, `agents:init`.
 14. **[Development & Testing Workflow](.agents/WORKFLOW.md)** — CLI commands, Vitest unit/integration testing, Playwright E2E tests, TypeScript type checking, and zero regression policy.
 15. **[Coding Standards & Conventions](.agents/CONVENTIONS.md)** — Zero external dependencies policy, strict function signature & schema verification, clean component separation, and log traceback inspection rules.
-16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, and Distributed Redis queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.
+16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, Distributed Redis, AWS SQS, and Google Cloud Pub/Sub queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.
 17. **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Native HTTP chunked streaming (`res.renderStream()`), deferred data loader slots (`defer: { key: promise }`), and TTFB optimization.
 18. **Polar billing production checklist** — [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md) (env, webhooks, rate limits, external tier hooks, CSP). Plugin reference: [PLUGINS.md § polarPlugin](PLUGINS.md).
 19. **[Decoupled Events & Signals Architecture](.agents/EVENTS.md)** — Zero-dependency enterprise event dispatcher (`core/events`), sync/async/parallel/serial/waterfall dispatch, wildcard listeners (`order.*`), Django-style `Signal` and sender filtering, queue bridging, and listener auto-discovery.
@@ -62,6 +68,13 @@ This `.agents/` customization root is organized into modular topic guides:
 22. **[Cloud & Kubernetes Health Probes](.agents/HEALTH.md)** — Zero-dependency RFC-compliant liveness (`/healthz`), readiness (`/readyz`), and combined diagnostic (`/health`) probes (`core/health`), event loop lag telemetry, database/queue health monitors, automatic HTTP 503 draining on graceful shutdown, and `createApp({ healthCheck: true })`.
 23. **[LRU & Tagged Cache Engine](.agents/CACHE.md)** — Zero-dependency, memory-bounded in-memory LRU cache (`core/cache`), byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (`getOrSet`), leak-free tag invalidation (`TaggedLruCache`), ORM query cache provider, and `createApp({ cache })`.
 24. **[Enterprise Resilience & Circuit Breaker](.agents/RESILIENCE.md)** — Zero-dependency fault tolerance engine (`core/resilience`), three-state `CircuitBreaker` (`CLOSED`, `OPEN`, `HALF_OPEN`), rolling window failure rate, per-call execution timeout, fallback handlers, and exponential backoff retry engine (`retry`, `withRetry`) with randomized jitter and transient error detection.
+25. **[Structured Cloud Logging & Distributed Tracing](.agents/LOGGING.md)** — Zero-dependency cloud logger (`core/logger`), GCP Cloud Logging, AWS CloudWatch, automatic trace propagation (`x-cloud-trace-context`, `x-amzn-trace-id`, `traceparent`), sensitive key redaction, and `req.logger` child context.
+26. **[Stateless Scale-Out & Database Pool Management](.agents/SCALE_OUT.md)** — Distributed Redis session store (`createRedisSessionStore`), Redis session tracker (`createRedisSessionTracker`), zero-dependency RESP client, serverless DB connection pool optimizer (`normalizeServerlessPoolConfig`), and scale-out preflight audits (`deploy:check`).
+27. **[Cloud Secrets Management](.agents/SECRETS.md)** — Zero-dependency Google Cloud Secret Manager & AWS Secrets Manager/SSM integration (`core/secrets`), in-memory caching with TTL, dot-notation JSON subkeys, process.env hydration, and `webspresso secrets:pull`.
+28. **[Cloud Metrics & Distributed Tracing](.agents/METRICS.md)** — Zero-dependency Prometheus exposition format (`/metrics`), JSON telemetry (`/metrics.json`), HTTP latency histograms, Node.js event loop/memory/pool/cache collectors, and W3C `traceparent` & `x-trace-id` propagation (`core/metrics`).
+29. **[Cloud Migration Jobs & Zero-Downtime Database Deploy](.agents/MIGRATION_JOBS.md)** — Dedicated pre-deploy migration jobs for Cloud Run, AWS ECS, and Kubernetes (`webspresso add:migration-job`), connection retries, and stale lock auto-healing (`webspresso db:migrate --safe`).
+30. **[Native Zero-Dependency Rate Limiting Engine](.agents/RATE_LIMIT.md)** — Framework-agnostic rate limiter (`core/rate-limit`), sliding window in-memory & Redis stores, RFC 6585 standard headers (`RateLimit-*`, `Retry-After`), Express & Hono dual support, and `rateLimit({ window, limit })`.
+31. **[Feature Flags & Canary Traffic Splitter](.agents/FLAGS.md)** — Zero-dependency feature flag and canary rollout engine (`core/flags`), deterministic FNV-1a bucketing, targeting rules (users, roles, email domains), A/B variants, SSR template helpers (`fsy.hasFeature`), and declarative API guards (`defineApi({ flag })`).
 
 ---
 

package/.agents/CLI.md

@@ -332,12 +332,17 @@ npx webspresso add:docker --force
 
 ## 17. Production Deployment Preflight Check (`deploy:check` / `check:deploy`)
 
-Run comprehensive pre-flight verification before deploying to Fly.io, Railway, Render, VPS, or Kubernetes:
+Run comprehensive pre-flight verification before deploying to Google Cloud Run, AWS (App Runner / ECS), Cloudflare Workers, Fly.io, Railway, Render, VPS, or Kubernetes:
 
 ```bash
-# Run production preflight verification
+# Run production preflight verification (auto-detects target platform)
 npx webspresso deploy:check
 
+# Target a specific cloud platform explicitly (cloudrun, aws, cloudflare, docker)
+npx webspresso deploy:check --platform cloudrun
+npx webspresso deploy:check --platform aws
+npx webspresso deploy:check -p cloudflare
+
 # Run against a specific environment (.env.staging or .env.production)
 npx webspresso deploy:check --env staging
 
@@ -349,11 +354,17 @@ npx webspresso deploy:check --json
 ```
 
 ### Audited Verification Areas:
-1. **Secrets & Cryptography**: Ensures `SESSION_SECRET` or `APP_KEY` is set, >= 32 characters, and not using weak placeholder defaults.
-2. **Git & Leak Prevention**: Verifies `.env` and local database files are excluded in `.gitignore`.
-3. **Container Hardening**: Ensures `Dockerfile` runs as a non-root `USER`, configures a `HEALTHCHECK`, and uses multi-stage caching.
-4. **Database & Migrations**: Audits for pending unapplied migrations and warns against ephemeral SQLite storage.
-5. **Server Optimizations**: Validates HTTP compression (`compression: true`), graceful shutdown, and health check endpoints.
+1. **Platform-Specific Cloud Preflight**:
+   - **Google Cloud Run**: Ephemeral SQLite/local upload warnings, SIGTERM timeout alignment (<= 10000ms), `.gcloudignore` secrets exclusion (`.env`), `cloudbuild.yaml` pipeline, and dynamic `PORT` binding.
+   - **AWS (App Runner / ECS Fargate)**: Ephemeral storage audits, `apprunner.yaml` / `ecs-task-definition.json` validity, and CloudWatch `awslogs` log driver configuration.
+   - **Cloudflare Workers**: `wrangler.toml` configuration and `nodejs_compat` compatibility flag verification.
+   - **Stateless Scale-Out**: Distributed Redis sessions and serverless connection pool limits.
+2. **Secrets & Cryptography**: Ensures `SESSION_SECRET` or `APP_KEY` is set, >= 32 characters, and not using weak placeholder defaults.
+3. **Git & Leak Prevention**: Verifies `.env` and local database files are excluded in `.gitignore`.
+4. **Container Hardening**: Ensures `Dockerfile` runs as a non-root `USER`, configures a `HEALTHCHECK`, and uses multi-stage caching.
+5. **Database & Migrations**: Audits for pending unapplied migrations and warns against ephemeral SQLite storage.
+6. **Server Optimizations**: Validates HTTP compression (`compression: true`), graceful shutdown, and health check endpoints.
+7. **Actionable Remediations**: Emits precise, single-command remediation steps for every warning and error detected.
 
 ---
 
@@ -435,3 +446,204 @@ npx webspresso make:mail Welcome
 # Outputs: emails/WelcomeEmail.js
 ```
 
+---
+
+## 21. Google Cloud Run Deployment (`add:cloudrun` / `cloudrun`)
+
+Generate production-ready Google Cloud Run configuration with Google Cloud Build CI/CD pipeline, `.gcloudignore`, and one-command deployment script:
+
+```bash
+# Generate cloudbuild.yaml, .gcloudignore, deploy-cloudrun.sh, and Dockerfile
+npx webspresso add:cloudrun
+
+# Customize region, container resources, scaling limits, and Cloud SQL
+npx webspresso add:cloudrun --region europe-west1 --memory 1Gi --cpu 2 --min-instances 1 --max-instances 20 --cloud-sql my-project:europe-west1:my-db
+
+# Overwrite existing files
+npx webspresso add:cloudrun --force
+```
+
+### Generated Artifacts:
+- **`cloudbuild.yaml`**: Multi-stage Docker image build, Google Artifact Registry push, and zero-downtime serverless Cloud Run deployment with Gen2 execution environment.
+- **`.gcloudignore`**: Prevents `.env`, SQLite files, node_modules, and test directories from entering the Cloud Build upload context.
+- **`deploy-cloudrun.sh`**: Executable bash script for direct zero-friction deployment (`chmod +x`).
+- **`package.json` Scripts**: Adds `gcp:deploy` and `gcp:build`.
+
+---
+
+## 22. AWS App Runner & ECS Fargate Deployment (`add:aws` / `aws`)
+
+Generate production-ready AWS deployment configuration supporting both AWS App Runner and Amazon ECS (Fargate):
+
+```bash
+# Generate apprunner.yaml, ecs-task-definition.json, deploy-aws.sh, and Dockerfile
+npx webspresso add:aws
+
+# Customize region, CPU, and memory allocations
+npx webspresso add:aws --region us-east-1 --cpu "1 vCPU" --memory "2 GB"
+
+# Overwrite existing files
+npx webspresso add:aws --force
+```
+
+### Generated Artifacts:
+- **`apprunner.yaml`**: AWS App Runner configuration with build commands (`npm ci --omit=dev`), start command, and port network mapping.
+- **`ecs-task-definition.json`**: Production ECS Fargate task definition with `awsvpc` network mode, container resource constraints, CloudWatch `awslogs`, and native `/healthz` health checks.
+- **`deploy-aws.sh`**: Automated deployment shell script that verifies AWS credentials, creates Amazon ECR repositories, builds and pushes Docker images, and updates services.
+- **`package.json` Scripts**: Adds `aws:deploy`.
+
+---
+
+## 23. Cloudflare Workers Deployment (`add:cloudflare` / `cloudflare`)
+
+Generate serverless edge deployment files for Cloudflare Workers with D1, KV, and Queues support:
+
+```bash
+# Generate wrangler.toml and worker.js
+npx webspresso add:cloudflare
+
+# Include Cloudflare D1, KV, and Queues
+npx webspresso add:cloudflare --d1 --kv --queue
+```
+
+---
+
+## 24. Cloud Static Asset Sync (`assets:sync` / `assets-sync`)
+
+Upload and synchronize compiled static assets (`public/assets/`, `dist/`, fonts, images) to S3, Cloudflare R2, or Google Cloud Storage with immutable CDN cache headers:
+
+```bash
+# Preview files to be uploaded without transmitting data
+npx webspresso assets:sync --dry-run
+
+# Sync assets to an AWS S3 bucket
+npx webspresso assets:sync --bucket my-cdn-bucket --provider s3
+
+# Sync assets to Google Cloud Storage
+npx webspresso assets:sync --bucket my-gcs-bucket --provider gcs --prefix assets
+
+# Override directory or custom Cache-Control header
+npx webspresso assets:sync --dir public --cache-control "public, max-age=604800"
+```
+
+---
+
+## 25. Cloud Secrets Synchronization (`secrets:pull` / `pull:secrets`)
+
+Pull cloud secrets from Google Cloud Secret Manager or AWS Secrets Manager into a local `.env.local` file for secure local development:
+
+```bash
+# Auto-detect cloud platform and pull expected secrets
+npx webspresso secrets:pull
+
+# Explicitly pull specific secrets from Google Cloud Secret Manager
+npx webspresso secrets:pull --platform cloudrun -s SESSION_SECRET DATABASE_URL
+
+# Explicitly pull from AWS Secrets Manager
+npx webspresso secrets:pull --platform aws -s SESSION_SECRET DATABASE_URL
+
+# Unpack a JSON secret bundle to stdout (dry run)
+npx webspresso secrets:pull --bundle prod/app/config --dry-run
+
+# Output secrets in JSON format
+npx webspresso secrets:pull -s API_KEY DB_PASS --format json -o secrets.json
+```
+
+---
+
+## 26. Zero-Secret CI/CD Pipeline Generator (`add:ci` / `add:workflow`)
+
+Scaffold automated, keyless GitHub Actions workflows (Google WIF, AWS IAM OIDC, Cloudflare) and GitLab CI pipelines with integrated test suites and `webspresso deploy:check --strict` gating:
+
+```bash
+# Auto-detect cloud platform and scaffold GitHub Actions workflows
+npx webspresso add:ci
+
+# Explicitly target Google Cloud Run (Workload Identity Federation)
+npx webspresso add:ci --platform cloudrun
+
+# Explicitly target AWS (IAM OIDC Role & Amazon ECR)
+npx webspresso add:ci --platform aws
+
+# Explicitly target Cloudflare Workers
+npx webspresso add:ci --platform cloudflare
+
+# Scaffold all cloud workflows alongside a GitLab CI pipeline (.gitlab-ci.yml)
+npx webspresso add:ci --platform all --gitlab
+```
+
+---
+
+## 27. Type-Safe Frontend Client Generator (`client:generate` / `client:gen`)
+
+Generate an end-to-end typed TypeScript HTTP client from your Webspresso API routes and Zod schemas for React, Next.js, Vite, Vue, Svelte, or mobile apps:
+
+```bash
+# Generate client into src/client.ts (or .webspresso/client.ts)
+npx webspresso client:generate
+
+# Specify custom output path and base URL
+npx webspresso client:generate --out src/api-client.ts --base-url https://api.myapp.com
+```
+
+---
+
+## 28. DB Studio Live Telemetry & SQL Runner (`db:studio`)
+
+Launch an interactive database inspector, SQL query runner, and real-time system monitoring dashboard:
+
+```bash
+# Launch DB Studio on default port 4567
+npx webspresso db:studio
+
+# Custom port without opening default browser
+npx webspresso db:studio --port 5000 --no-open
+```
+- Schema inspection & CRUD operations for all database tables.
+- Real-time SSE Live Telemetry streaming Node.js memory metrics (RSS, Heap), Knex connection pool utilization, background queues, and circuit breaker trip states.
+- Interactive Circuit Breaker manual reset (`POST /_studio/api/breakers/:name/reset`).
+
+---
+
+## 29. Interactive REPL Console (`console` / `c`)
+
+Launch an interactive Node.js REPL session with auto-injected framework context (database, repositories, services, queues, events, feature flags, and cache):
+
+```bash
+# Start interactive console
+npx webspresso console
+# Alias:
+npx webspresso c
+
+# Evaluate a single expression and print output (with top-level await support)
+npx webspresso console -e "await Note.find({ status: 'published' })"
+
+# Target specific environment or config file
+npx webspresso console -E production -c config/db.js
+
+# Disable command history persistence or banner
+npx webspresso console --no-history --no-banner
+```
+
+### Context & Shortcuts Injected:
+- `db`: Knex / ORM database instance.
+- `<ModelName>` (e.g. `Note`, `User`): Direct repository shortcuts (`await Note.find()`, `await Note.findById(1)`).
+- `models`: Dictionary of all loaded model repositories (`models.Note`).
+- `services`: ServiceRegistry instance.
+- `service(name, input)`: Direct helper to invoke domain services (`await service('notes.create', payload)`).
+- `queue`: Background QueueDispatcher (`await queue.dispatch('email.send', data)`).
+- `events`: Decoupled EventDispatcher (`events.emit('order.created', order)`).
+- `flags`: FeatureFlagManager (`flags.isEnabled('new_checkout', { user })`).
+- `cache`: TaggedLruCache instance (`await cache.get('key')`).
+- `mailer`: Framework mailer service.
+- `reload()`: Hot-reloads all models and services from filesystem without exiting the REPL.
+- `help()`: Displays interactive help menu with all available objects and commands.
+
+### Custom REPL Dot-Commands:
+- `.models`: List all loaded models, table names, and available repository methods.
+- `.services`: List all registered business services and descriptions.
+- `.routes`: Scan and list all API endpoints and SSR pages.
+- `.flags`: List active feature flags and targeting rules.
+- `.reload`: Hot-reload models and services from filesystem.
+- `.exit`: Exit the console session (`Ctrl+D`).
+

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/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']
+```