webspresso 0.0.104 → 0.0.106

package/.agents/AGENTS.md

@@ -18,6 +18,13 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](AUTH.md) | `core/auth/` |
 | **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** |
 
 ---
@@ -49,13 +56,25 @@ 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.
+20. **[HTTP 103 Early Hints](.agents/EARLY_HINTS.md)** — Zero-dependency RFC 8288 / RFC 8297 Early Hints dispatcher (`core/early-hints`), preloading route CSS/JS and fonts before SSR loader execution, `createApp({ earlyHints })`, and `res.earlyHints(links)` / `ctx.earlyHints(links)` helpers.
+21. **[Payload Limits & DoS Protection](.agents/LIMITS.md)** — Zero-dependency request body limits and DoS protection (`core/limits`), `createApp({ limits })`, automatic `PayloadTooLargeError` (HTTP 413) mapping, route overrides (`limits.routes`), streaming bypass, and native HMAC webhook `req.rawBody` capture.
+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/ARCHITECTURE.md

@@ -51,6 +51,29 @@
 - **HTTP Response Compression (`core/compression`)**:
   - Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })`.
   - Content negotiation for Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold filtering (1 KB), and `res.compress(false)` route opt-out.
+- **Configurable Payload Size Limits & DoS Protection (`core/limits`)**:
+  - Zero-dependency request body limits configured via `createApp({ limits: { json: '1mb', urlencoded: '1mb', raw: false, text: false, parameterLimit: 1000 } })` or shorthand string/number (`limits: '5mb'`). Also accepted under `createApp({ server: { limits } })`.
+  - **HTTP 413 & 400 Error Mapping**: Payload limit violations and excessive form parameters automatically produce `PayloadTooLargeError` (HTTP 413) with `{ limit, length, expected }` metadata; malformed JSON bodies produce `BadRequestError` (HTTP 400) with `INVALID_JSON_PAYLOAD`.
+  - **Raw Body Capture for Webhooks**: `captureRawBody: true | string[] | Function` captures incoming request payload `Buffer` on `req.rawBody` for zero-overhead HMAC cryptographic verification (Polar, Stripe, GitHub).
+  - **Route Overrides & Exclusions**: `limits.routes` supports per-route limit adjustments (e.g. `routes: { '/api/upload': { json: '25mb' } }`), while `limits.exclude` completely bypasses body parsing for raw socket/streaming endpoints.
+- **Cloud & Kubernetes Health Probes (`core/health`, `/healthz`, `/readyz`, `/health`)**:
+  - RFC-compliant cloud-native endpoints enabled via `createApp({ healthCheck: true })` or fine-grained `{ path: '/healthz', readyPath: '/readyz', combinedPath: '/health', db: true, queue: true, eventLoopLag: true }`.
+  - **Liveness Probe (`/healthz`)**: Non-blocking probe reporting basic process health, memory usage (`rss`, `heapUsed`, `heapTotal`, `external`), and system uptime.
+  - **Readiness Probe (`/readyz`)**: Deep dependency inspection checking database ping (`knex.raw('SELECT 1')`), worker queue status, custom user checks, and `ShutdownManager` draining state (immediately returning HTTP 503 so upstream load balancers detach the instance).
+  - **Diagnostic Health (`/health`)**: Full operational dashboard with event loop lag percentiles (`perf_hooks.monitorEventLoopDelay`), dependency breakdown, and latency metrics.
+- **In-Memory LRU & Tagged Cache Engine (`core/cache`)**:
+  - Zero-dependency O(1) Least-Recently-Used caching engine configured via `createApp({ cache: { maxEntries, maxMemoryMb, defaultTtl } })` or `cache: false`.
+  - **Memory Budget & Leak Prevention**: Enforces byte boundaries (`maxBytes` / `maxMemoryMb`) via `approximateByteSize` to prevent process OOM errors, combined with passive and active TTL pruning (`pruneExpired()`).
+  - **Bidirectional Tag Invalidation (`TaggedLruCache`)**: Supports model and query tagging (`invalidateTag`, `invalidateTags`). When items are evicted via LRU, all associated tag sets are automatically and symmetrically cleaned up, eliminating dangling Set memory leaks.
+  - **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory, options)` deduplicates concurrent in-flight requests for cold keys so expensive factories execute only once.
+  - **Framework Integration**: Directly powers `core/orm/cache/memory-provider.js` (ORM query caching) and `core/schema-cache.js` (Zod schema cache), and is automatically exposed on `req.cache`, `req.context.cache`, and `app.cache`.
+- **Enterprise Resilience, Circuit Breaker & Retry Engine (`core/resilience`)**:
+  - Zero-dependency fault tolerance and cascading failure prevention system built natively on `events` and `perf_hooks`.
+  - **Three-State Circuit Breaker (`CircuitBreaker`)**: Standard `CLOSED`, `OPEN`, and `HALF_OPEN` states. Trips to `OPEN` when consecutive failures reach `failureThreshold` or failure rate percentage exceeds `failureRateThreshold` in a rolling sample window (`rollingWindow`).
+  - **Fail-Fast & Graceful Fallbacks**: Fast-fails calls with `CircuitBreakerOpenError` (HTTP 503) without executing downstream code when open, or seamlessly executes fallback handlers (`fallback: (err, ...args) => ...`).
+  - **Trial Recovery Probing**: Automatically transitions to `HALF_OPEN` after `resetTimeout` and tests downstream health using trial probes (`successThreshold`).
+  - **Exponential Backoff Retry with Full Jitter (`retry`, `withRetry`)**: Automatically retries transient network errors (`ECONNRESET`, `ETIMEDOUT`, 429 Too Many Requests, and 5xx errors) with randomized full jitter to prevent thundering herd spikes while avoiding retrying 4xx client errors.
+  - **Services Layer Integration**: Declarative `defineService({ circuitBreaker, retry })` seamlessly wraps service execution. Also accessible on `app.breakers`, `app.getBreaker()`, `req.breaker()`, `req.retry()`, `ctx.breaker()`, and `ctx.retry()`.
 - **Custom Error & 404 Pages (`errorPages`)**:
   - Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`.
   - **404 Not Found (`notFound`)**: Template path (`'404.njk'`) or handler `(req, res, ctx) => ...`.

package/.agents/CACHE.md

@@ -0,0 +1,147 @@
+# High-Performance In-Memory LRU & Tagged Cache Engine (`core/cache`)
+
+Webspresso includes a zero-dependency, memory-bounded, leak-free in-memory cache engine featuring O(1) Least-Recently-Used (LRU) eviction, byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (thundering herd prevention), and O(1) bidirectional tag-based invalidation.
+
+---
+
+## 🎯 Key Capabilities & Design Guarantees
+
+1. **True O(1) LRU Eviction**: Built on V8's native insertion-order Map mechanics with zero extra memory allocation for linked-list node wrappers.
+2. **Dual Capacity Boundaries**:
+   - **`maxEntries`**: Restricts the maximum number of items stored.
+   - **`maxBytes` / `maxMemoryMb`**: Enforces strict memory budgets using `approximateByteSize` to prevent process Out-Of-Memory (OOM) crashes under heavy or large payload loads.
+3. **Symmetrical Tag Cleanup (Zero Leaks)**: When an item is evicted via LRU, expired via TTL, or deleted, all associated tag index sets are automatically pruned. Empty tag sets are deleted immediately, preventing the classic "dangling Set memory leak".
+4. **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory)` coalesces concurrent requests for the same missing key, invoking the expensive calculation or DB query exactly once.
+5. **Universal Integration**:
+   - **ORM Query Cache**: Powers `core/orm/cache/memory-provider.js` with true LRU and memory budgets.
+   - **Zod Schema Cache**: Powers `core/schema-cache.js` with bounded 2,000 schemas capacity.
+   - **Application & Context**: Automatically mounted on `app.cache`, `req.cache`, and `req.context.cache` unless `cache: false` is configured.
+
+---
+
+## 🚀 Quick Usage
+
+### 1. Standalone `LruCache`
+```javascript
+const { createLruCache } = require('webspresso');
+
+const cache = createLruCache({
+  maxEntries: 1000,
+  maxMemoryMb: 50,          // 50 MB byte budget
+  defaultTtl: '15m',        // 15 minutes default TTL
+  clone: false,             // Set true if cached objects must not be mutated
+});
+
+cache.set('user:42', { name: 'Alice', role: 'admin' });
+
+const user = cache.get('user:42'); // Refreshes LRU position
+const peekUser = cache.peek('user:42'); // Reads without refreshing LRU position
+```
+
+### 2. Tagged Invalidation (`TaggedLruCache`)
+```javascript
+const { createTaggedLruCache } = require('webspresso');
+
+const cache = createTaggedLruCache({
+  maxEntries: 5000,
+  maxMemoryMb: 100,
+});
+
+// Tag items by model and primary key
+cache.set('query:users:active', usersList, { tags: ['model:User', 'q:active'] });
+cache.set('user:1:profile', userProfile, { tags: ['model:User', 'pk:1'] });
+
+// Invalidate single primary key
+cache.invalidateTag('pk:1');
+
+// Invalidate all queries related to the User model
+cache.invalidateTags(['model:User']);
+```
+
+### 3. Stampede / Thundering Herd Protection (`getOrSet`)
+```javascript
+// 50 concurrent requests for 'expensive:report' will execute the factory only once:
+const report = await cache.getOrSet('expensive:report', async (key) => {
+  return await generateHeavyReport();
+}, { ttl: '1h' });
+```
+
+---
+
+## ⚙️ Application Configuration (`createApp`)
+
+Configure the process-wide cache directly when bootstrapping Webspresso:
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  pagesDir: './pages',
+  cache: {
+    maxEntries: 5000,
+    maxMemoryMb: 64,        // 64 MB budget
+    defaultTtl: '10m',
+  },
+});
+```
+
+To disable the app cache completely:
+```javascript
+const app = createApp({
+  pagesDir: './pages',
+  cache: false,
+});
+```
+
+---
+
+## 🌐 Context & Route Usage
+
+Inside page loaders, services, or API route handlers:
+
+```javascript
+// In API routes (pages/api/stats.get.js)
+module.exports = defineApi({
+  handler: async (req, res) => {
+    const stats = await req.cache.getOrSet('site:stats', async () => {
+      return await req.db.getRepository('Order').getSummaryStats();
+    }, { ttl: '5m', tags: ['stats', 'model:Order'] });
+
+    return res.json(stats);
+  },
+});
+```
+
+```javascript
+// From any background job or script using app-context
+const { getCache } = require('webspresso');
+
+const cache = getCache();
+if (cache) {
+  cache.invalidateTag('stats');
+}
+```
+
+---
+
+## 📊 Telemetry & Observability Metrics
+
+Access real-time cache performance and memory metrics:
+
+```javascript
+const stats = app.cache.getStats();
+console.log(stats);
+// {
+//   entries: 42,
+//   tags: 5,
+//   currentBytes: 124850,
+//   maxBytes: 67108864,
+//   maxEntries: 5000,
+//   hits: 1540,
+//   misses: 23,
+//   hitRate: 0.985,
+//   sets: 65,
+//   evictions: 0,
+//   expirations: 12
+// }
+```

package/.agents/CLI.md

@@ -313,7 +313,7 @@ Generate production-ready, security-hardened, multi-stage `Dockerfile`, `.docker
 npx webspresso add:docker
 
 # Customize Node.js version, database service, or container port
-npx webspresso add:docker --node 22-alpine --db postgres --redis --port 3000
+npx webspresso add:docker --node 22-alpine --db postgres --redis --port 7331
 
 # Overwrite existing files
 npx webspresso add:docker --force
@@ -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/EARLY_HINTS.md

@@ -0,0 +1,120 @@
+# HTTP 103 Early Hints & Critical Asset Preloading
+
+Webspresso features built-in, zero-dependency support for **HTTP 103 Early Hints** (RFC 8288 / RFC 8297).
+Early Hints allow Webspresso to send informational HTTP headers (containing CSS, JavaScript, and font preload instructions) to the client **before** server-side rendering (`load()`, database queries, external API calls) finishes, allowing the browser to download critical page assets in parallel.
+
+---
+
+## 🚀 How It Works
+
+1. The client sends an HTTP request (`GET /products/123`).
+2. Webspresso resolves the matching route and its companion CSS/JS asset candidates via `AssetManager`.
+3. If Early Hints are enabled, Webspresso immediately writes an `HTTP/1.1 103 Early Hints` response with `Link: </css/products.css>; rel=preload; as=style, </js/products.js>; rel=preload; as=script`.
+4. While the browser starts downloading stylesheets and scripts, Webspresso runs the page's async `load()` function and Nunjucks rendering.
+5. Once the HTML is ready, Webspresso returns `HTTP/1.1 200 OK` with the final document.
+6. The browser can immediately render without waiting for secondary asset network round-trips (reducing TTFB, FCP and LCP).
+
+---
+
+## 🛠️ Configuration
+
+### Global Configuration (`createApp`)
+
+Enable automatic route asset preloading globally:
+
+```javascript
+const { createApp } = require('webspresso');
+
+const app = createApp({
+  earlyHints: true, // Automatically preloads route CSS & JS
+  // Or with custom default links:
+  // earlyHints: {
+  //   auto: true,
+  //   links: ['/css/global.css', '/fonts/inter.woff2'],
+  // }
+});
+```
+
+### Route / Page Configuration (`definePage`)
+
+Configure Early Hints per-page inside your page module:
+
+```javascript
+const { definePage } = require('webspresso');
+
+module.exports = definePage({
+  // Preload route assets automatically
+  earlyHints: true,
+
+  // Or specify exact links:
+  // earlyHints: [
+  //   '/css/special.css',
+  //   { url: '/fonts/inter.woff2', as: 'font', crossOrigin: 'anonymous' }
+  // ],
+
+  load: async (ctx) => {
+    // You can also dispatch hints manually during load:
+    ctx.earlyHints(['/extra-chunk.js']);
+
+    const product = await ctx.db.getRepository('Product').findById(ctx.params.id);
+    return { product };
+  },
+});
+```
+
+### In Route Handlers and API Middleware
+
+`res.earlyHints(links, [callback])` is attached to `res` on every request:
+
+```javascript
+app.get('/dashboard', (req, res) => {
+  // Send 103 Early Hints
+  res.earlyHints([
+    '/css/dashboard.css',
+    '/js/charts.js',
+  ]);
+
+  // Run async queries...
+  setTimeout(() => {
+    res.send('<h1>Dashboard</h1>');
+  }, 200);
+});
+```
+
+---
+
+## 📋 Link Options & Deduction
+
+Webspresso automatically deduces `as` and `crossorigin` attributes based on URL file extensions:
+
+| Extension | Inferred `as` | Browser CORS Requirement |
+| :--- | :--- | :--- |
+| `.css` | `style` | - |
+| `.js`, `.mjs`, `.cjs` | `script` | - |
+| `.woff2`, `.woff`, `.ttf` | `font` | Auto-adds `crossorigin` |
+| `.png`, `.jpg`, `.webp`, `.svg` | `image` | - |
+| `.json` | `fetch` | - |
+
+You can also pass full descriptor objects:
+
+```javascript
+res.earlyHints([
+  {
+    url: '/fonts/inter.woff2',
+    as: 'font',
+    crossOrigin: 'anonymous',
+    fetchPriority: 'high',
+  },
+  {
+    url: 'https://cdn.example.com',
+    rel: 'preconnect',
+  },
+]);
+```
+
+---
+
+## 🛡️ Resilience & Fallbacks
+
+- If the client or proxy does not support HTTP 103, or if running in an environment without `res.writeEarlyHints` (HTTP/1.0, test mocks), `sendEarlyHints` returns `false` safely without throwing.
+- Calling `earlyHints` after response headers have been sent (`res.headersSent === true`) is a safe no-op.