webspresso 0.0.105 → 0.0.106

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.

package/.agents/PLUGINS.md

@@ -161,12 +161,19 @@ Schema-driven headless CMS & inline content editing.
 - **Features**: Dynamic content types & entries, public API (`/api/content/:type/:slug`), visual inline editor widget.
 
 ### 2.4 `uploadPlugin` (`plugins/upload`)
-Multipart file upload manager with local / cloud storage providers.
-- **Options**: `{ path: '/api/upload', local: { destDir, publicBasePath }, maxBytes: 10000000, mimeAllowlist: ['image/png', 'image/jpeg'] }`
-- **Features**: Single & multi-file uploads, file size & extension validation, storage drivers.
+Multipart file upload manager with local disk, AWS S3, Google Cloud Storage (GCS), and Cloudflare R2 drivers.
+- **Options**: `{ path: '/api/upload', provider, local: { destDir, publicBasePath }, maxBytes: 10000000, mimeAllowlist: ['image/png', 'image/jpeg'], presigned: true, presignedRoute: '/api/upload/presign' }`
+- **Supported Storage Drivers**:
+  - `createLocalFileProvider({ destDir, publicBasePath })`: Local disk storage (monolith / VPS).
+  - `createS3FileProvider({ s3Client, bucket, publicBaseUrl, prefix })`: AWS S3, MinIO, or S3-compatible endpoints with direct presigned PUT URLs (`createSignedUploadUrl`).
+  - `createGcsFileProvider({ bucket, storageClient, publicBaseUrl, prefix })`: Google Cloud Storage with V4 signed URLs for serverless direct uploads.
+  - `createR2FileProvider({ bucket, publicBaseUrl, prefix })`: Cloudflare Workers native R2 binding.
+- **Direct-to-Cloud Presigned Uploads**: Set `presigned: true` to mount `POST /api/upload/presign`, allowing web browsers to upload directly to S3 or GCS without passing large payloads through memory-limited or ephemeral containers.
+- **Static Asset Sync**: `webspresso assets:sync [--bucket <name>] [--provider s3|gcs|r2] [--dry-run]` to upload compiled JS/CSS bundles to cloud storage with `Cache-Control: public, max-age=31536000, immutable`.
 - **Orphan Pruning**: `scanOrphanedUploads({ db, destDir })` and `pruneOrphanedUploads({ db, destDir, dryRun })` to detect and remove disk files no longer referenced by any database model, accompanied by CLI command `webspresso upload:prune [--dry-run]`.
 
 
+
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
 - **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true, lazy: false }`

package/.agents/QUEUE.md

@@ -92,6 +92,48 @@ queuePlugin({
 });
 ```
 
+### 4. `SqsQueueAdapter` (AWS SQS)
+Zero-dependency AWS SQS adapter powered by native Node.js HTTP and standard AWS SigV4 request signing. Supports long-polling worker loops (`dequeue`), direct enqueue with delay seconds calculation, and AWS Lambda push batch execution (`processBatch`).
+
+```js
+const { SqsQueueAdapter } = require('webspresso');
+
+// Worker daemon or long-polling runner:
+const adapter = new SqsQueueAdapter({
+  queueUrl: process.env.AWS_SQS_QUEUE_URL,
+  region: process.env.AWS_REGION || 'us-east-1',
+  waitTimeSeconds: 10,
+  visibilityTimeout: 30,
+});
+
+// AWS Lambda SQS Event Handler:
+exports.handler = async (event) => {
+  return adapter.processBatch(event.Records, queueManager);
+};
+```
+
+### 5. `PubSubQueueAdapter` (Google Cloud Pub/Sub)
+Zero-dependency Google Cloud Pub/Sub adapter using standard REST API (`:publish`, `:pull`, `:acknowledge`, `:modifyAckDeadline`) with base64 payload serialization. Supports both background pull workers and Cloud Run / App Engine Push Subscription HTTP webhooks (`processPushRequest`).
+
+```js
+const { PubSubQueueAdapter } = require('webspresso');
+
+const adapter = new PubSubQueueAdapter({
+  projectId: process.env.GOOGLE_CLOUD_PROJECT,
+  topic: 'app-jobs',
+  subscription: 'app-jobs-sub',
+});
+
+// Cloud Run Push Subscription Webhook Route:
+app.post('/api/queue/push', async (req, res) => {
+  await adapter.processPushRequest(req, res, req.queue);
+});
+```
+
+### 6. `WaitUntilQueueAdapter` & `CloudflareQueueAdapter`
+- `WaitUntilQueueAdapter`: Serverless & Edge execution (Cloudflare Workers `ctx.waitUntil`, Vercel Edge).
+- `CloudflareQueueAdapter`: Cloudflare Queues integration (`env.MY_QUEUE.send`).
+
 ---
 
 ## 4. File-Based Auto-Discovery (`jobs/`)

package/.agents/RATE_LIMIT.md

@@ -0,0 +1,147 @@
+# Native Zero-Dependency Rate Limiting Engine (`core/rate-limit`)
+
+Webspresso features a high-performance, zero-dependency Rate Limiting Engine located in `core/rate-limit/`. It works seamlessly across both traditional Express middleware pipelines and modern edge/serverless contexts (such as Hono), providing standard RFC 6585 and IETF Draft rate limit headers with memory leak-free in-memory and distributed Redis sliding-window stores.
+
+---
+
+## 🎯 Native Core vs. Plugin Comparison
+
+| Feature | Core Rate Limiter (`core/rate-limit`) | Rate Limit Plugin (`plugins/rate-limit`) |
+| :--- | :--- | :--- |
+| **Dependencies** | **Zero external dependencies** (pure Node.js) | Requires `express-rate-limit` peer dependency |
+| **Import** | `const { rateLimit, RateLimiter } = require('webspresso')` | `const { rateLimitPlugin } = require('webspresso')` |
+| **Framework Agnostic** | ✅ Express `(req, res, next)` & Hono `(c, next)` | Express only |
+| **Stores** | Native Sliding Window `MemoryRateLimitStore` & `RedisRateLimitStore` | `express-rate-limit` memory or external store |
+| **Headers** | RFC 6585 `RateLimit-*`, `Retry-After`, legacy `X-RateLimit-*` | `standardHeaders: 'draft-7'`, `legacyHeaders` |
+| **File Route Usage** | Universal middleware in API routes and standalone apps | Named middleware via `ctx.middlewares.rateLimit` |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Basic Express Route Limiting
+
+```javascript
+const { rateLimit } = require('webspresso');
+
+// 60 requests per minute
+const apiLimiter = rateLimit({
+  window: '1m',
+  limit: 60,
+});
+
+// Use as standard middleware
+app.use('/api', apiLimiter);
+```
+
+### 2. File-Based API Route (`pages/api/...`)
+
+```javascript
+const { defineApi, rateLimit } = require('webspresso');
+
+const strictLimiter = rateLimit({
+  window: '10s',
+  limit: 5,
+  message: { error: 'Too many requests. Please slow down.' },
+});
+
+module.exports = defineApi({
+  middleware: [strictLimiter],
+  handler: async (req, res) => {
+    return res.json({ success: true });
+  },
+});
+```
+
+### 3. Distributed Redis Rate Limiting (Scale-Out)
+
+```javascript
+const { rateLimit, RedisRateLimitStore } = require('webspresso');
+const Redis = require('ioredis');
+
+const redis = new Redis(process.env.REDIS_URL);
+
+const limiter = rateLimit({
+  window: '15m',
+  limit: 100,
+  store: new RedisRateLimitStore({
+    client: redis,
+    prefix: 'rl:auth:',
+    passOnStoreError: true, // Fail-open if Redis drops
+  }),
+});
+```
+
+### 4. Edge / Hono Application Usage
+
+The middleware automatically detects Hono's `(c, next)` context signature:
+
+```javascript
+const { Hono } = require('hono');
+const { rateLimit } = require('webspresso');
+
+const app = new Hono();
+const limiter = rateLimit({ limit: 100, window: '1m' });
+
+app.use('*', (c, next) => limiter(c, next));
+```
+
+---
+
+## ⚙️ Options Reference
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `limit` / `max` | `number` | `60` | Maximum number of allowed requests within the time window. |
+| `window` / `windowMs`| `string\|number` | `'1m'` | Window duration in ms or string shorthand (`'500ms'`, `'10s'`, `'1m'`, `'1h'`, `'1d'`). |
+| `store` | `RateLimitStore` | `MemoryRateLimitStore` | Underlying storage engine. Defaults to sliding window in-memory store. |
+| `keyGenerator` | `(req) => string` | `extractClientIp` | Function to identify client. Extracts Cloudflare, X-Forwarded-For, or socket IP by default. |
+| `skip` | `(req) => boolean` | `() => false` | Condition to skip rate limiting (e.g. internal healthchecks). |
+| `standardHeaders` | `boolean` | `true` | Send standard RFC headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`). |
+| `legacyHeaders` | `boolean` | `false` | Send legacy `X-RateLimit-*` headers. |
+| `skipFailedRequests` | `boolean` | `false` | When `true`, failed requests (`statusCode >= 400`) decrement hit count upon finish. |
+| `skipSuccessfulRequests`| `boolean` | `false` | When `true`, successful requests (`statusCode < 400`) decrement hit count upon finish. |
+| `statusCode` | `number` | `429` | HTTP status code returned when limit is exceeded. |
+| `message` | `string\|object` | `{ error: 'Too Many Requests', ... }` | Response payload on limit exceeded. |
+| `handler` | `Function` | `null` | Custom callback when limit is exceeded `(req, res, next, info) => void`. |
+
+---
+
+## 📡 HTTP Response Headers
+
+When enabled, the rate limiter emits standard headers:
+
+```http
+HTTP/1.1 200 OK
+RateLimit-Limit: 60
+RateLimit-Remaining: 58
+RateLimit-Reset: 42
+RateLimit-Policy: 60;w=60
+```
+
+When the limit is exceeded (HTTP 429 Too Many Requests):
+
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 42
+RateLimit-Limit: 60
+RateLimit-Remaining: 0
+RateLimit-Reset: 42
+RateLimit-Policy: 60;w=60
+Content-Type: application/json
+
+{"error":"Too Many Requests","message":"Too many requests, please try again later.","statusCode":429}
+```
+
+---
+
+## 🛡️ Reverse Proxy & Client IP Extraction
+
+`extractClientIp(req)` extracts client IP in the following priority order:
+1. `req.ip` (Express `trust proxy`)
+2. `CF-Connecting-IP` (Cloudflare)
+3. `Fastly-Client-IP` / `True-Client-IP` (Fastly / Akamai)
+4. `X-Forwarded-For` (First client IP in comma-separated list)
+5. `X-Real-IP` (Nginx / HAProxy)
+6. `socket.remoteAddress` (Normalized IPv4 / IPv6)
+7. Fallback `127.0.0.1`

package/.agents/SCALE_OUT.md

@@ -0,0 +1,109 @@
+# Stateless Scale-Out & Database Connection Pool Management Guide
+
+When deploying Webspresso to serverless or auto-scaling cloud environments (Google Cloud Run, AWS App Runner, ECS Fargate, AWS Lambda, Kubernetes, or PM2 Cluster), multiple container instances run concurrently and scale up/down dynamically.
+
+To ensure seamless operation without lost user sessions or database exhaustion, Webspresso provides native zero-dependency **Stateless Scale-Out** primitives:
+1. **Distributed Redis Session Store** (`createRedisSessionStore`)
+2. **Distributed Redis Session & Device Tracker** (`createRedisSessionTracker`)
+3. **Built-in Lightweight RESP Redis Client** (`createMiniRedisClient`) & `InMemoryRedisClient`
+4. **Serverless Database Connection Pool Optimizer** (`normalizeServerlessPoolConfig`, `isServerlessEnvironment`)
+
+---
+
+## 🎯 Key Capabilities
+
+### 1. Distributed Redis Session Store (`createRedisSessionStore`)
+- Drop-in replacement for `express-session` MemoryStore.
+- Stores session data in Redis with automatic TTL expiration synced to session cookies (`maxAge`).
+- Implements the complete `express-session` Store contract: `get`, `set`, `destroy`, `touch`, `all`, `length`, `clear`.
+- Zero external dependencies: works with any standard client (`ioredis`, `redis` v4/v3, or the built-in `createMiniRedisClient`).
+- **Auto-Detection**: Setting `REDIS_URL=redis://...` or `SESSION_STORE=redis` in your environment automatically wires the Redis session store without manual boilerplate!
+
+### 2. Distributed Redis Device & Session Tracker (`createRedisSessionTracker`)
+- Replaces or supplements Knex database session tracking across ephemeral instances.
+- Maintains user active sessions (`user:sessions:<userId>`) and device metadata (`sess:device:<sessionId>`).
+- Supports remote single-session revocation, "revoke other sessions", and "force logout from all devices".
+
+### 3. Serverless DB Connection Pool Optimizer (`normalizeServerlessPoolConfig`)
+- Prevents database connection exhaustion on managed databases (Google Cloud SQL, AWS RDS / Aurora) when container replicas scale from 1 to 50+.
+- Automatically detects serverless platforms (`K_SERVICE` on Cloud Run, `AWS_EXECUTION_ENV` / `AWS_LAMBDA_FUNCTION_NAME` on AWS):
+  - Sets `pool.min: 0` (so idle containers release database sockets).
+  - Clamps `pool.max: 5` (or `2` on Lambda) per container instance.
+  - Reduces `acquireTimeoutMillis` from Knex's 60s default to 10s.
+  - Sets safe `idleTimeoutMillis: 30000`, `createTimeoutMillis: 5000`.
+
+---
+
+## 🚀 Quick Start & Usage
+
+### 1. Zero-Configuration Cloud Run / ECS Deployment
+
+Simply provide `REDIS_URL` in your container environment variables:
+
+```bash
+# In Cloud Run or AWS ECS Task Definition
+REDIS_URL=redis://default:secret@memorystore-or-elasticache:6379
+SESSION_SECRET=a_very_secure_random_production_secret_32_chars
+```
+
+Webspresso automatically detects `REDIS_URL` and activates both `createRedisSessionStore` and `normalizeServerlessPoolConfig`.
+
+---
+
+### 2. Explicit Auth Session Configuration
+
+```javascript
+// server.js
+const { createApp, createRedisSessionStore } = require('webspresso');
+
+const app = createApp({
+  auth: {
+    session: {
+      secret: process.env.SESSION_SECRET,
+      // Pass custom store or let Webspresso auto-detect REDIS_URL
+      store: createRedisSessionStore({
+        url: process.env.REDIS_URL,
+        prefix: 'myapp:sess:',
+        ttl: 86400, // 24 hours
+      }),
+    },
+  },
+  server: {
+    compression: true,
+  },
+});
+```
+
+---
+
+### 3. Explicit Database Connection Pool Configuration
+
+```javascript
+// webspresso.db.js
+module.exports = {
+  client: 'pg',
+  connection: process.env.DATABASE_URL,
+  // Enable serverless pool optimization explicitly
+  serverlessPool: true,
+  pool: {
+    // Override defaults if using a pooler like PgBouncer or RDS Proxy
+    min: 0,
+    max: 5,
+  },
+};
+```
+
+---
+
+### 4. Production Preflight Audit (`webspresso deploy:check`)
+
+Run the preflight check before deploying to verify that your session store and connection pool are properly configured for scale-out:
+
+```bash
+npx webspresso deploy:check
+```
+
+The preflight check will:
+- ✅ Verify distributed session store (Redis) is active in production instead of ephemeral MemoryStore.
+- ⚠️ Flag database connection pools with excessively large `max` (> 10) on autoscaling serverless containers.
+- ⚠️ Check that `pool.min` is set to 0 for serverless scale-to-zero workloads.

package/.agents/SECRETS.md

@@ -0,0 +1,117 @@
+# Cloud Secrets Management Guide (`core/secrets` & `secrets:pull`)
+
+Webspresso features an enterprise, zero-dependency Cloud Secrets Management system (`core/secrets`) designed to eliminate plain-text `.env` files and secret leakage in containerized and serverless environments (Google Cloud Run, AWS App Runner, ECS Fargate, Kubernetes).
+
+---
+
+## 🎯 Key Capabilities
+
+1. **Zero External Dependencies**:
+   - Interacts directly with cloud vault REST APIs using native Node.js standard libraries (`https`, `crypto`).
+   - **Google Cloud Secret Manager**: Automatically acquires OAuth2 tokens from the local GCP Metadata Server in Cloud Run/GKE, exchanges RSA-SHA256 signed JWTs from `GOOGLE_APPLICATION_CREDENTIALS`, or uses static tokens.
+   - **AWS Secrets Manager & SSM Parameter Store**: Employs an embedded, standards-compliant AWS Signature Version 4 (SigV4) signer with HMAC-SHA256.
+2. **In-Memory Caching with TTL & Invalidation**:
+   - Caches secret values in RAM with a configurable TTL (default: 5 minutes) to avoid redundant HTTP roundtrips.
+   - Supports single secret cache busting (`secrets.invalidate(name)`) and full cache clearing (`secrets.clearCache()`) for automated secret rotation.
+3. **JSON Secret Bundle Unpacking & Dot-Notation Subkeys**:
+   - Access specific fields within JSON bundles using dot-notation:
+     `await secrets.get('prod/app/config.DATABASE_URL')`
+   - Unpack entire JSON bundles into `process.env`:
+     `await secrets.loadBundle('prod/app/config')`
+4. **Local Developer Synchronization (`webspresso secrets:pull`)**:
+   - Pulls secrets from Google Cloud or AWS into a local `.env.local` file for local development without committing credentials to Git.
+
+---
+
+## 🚀 Usage in Application Bootstrap
+
+### 1. Hydrating Environment at Application Boot
+
+Call `loadSecrets()` before initializing your database or server:
+
+```javascript
+// server.js
+const { createApp, loadSecrets } = require('webspresso');
+
+async function start() {
+  // Load secrets from Google Cloud Secret Manager or AWS before bootstrapping
+  await loadSecrets({
+    provider: 'auto', // 'cloudrun' | 'gcp' | 'aws' | 'auto'
+    secrets: {
+      SESSION_SECRET: 'session-secret:latest',
+      DATABASE_URL: 'rds-database-url:latest',
+    },
+    // Or unpack a single JSON bundle holding all config:
+    // bundle: 'prod/webspresso/app-secrets',
+  });
+
+  const app = createApp({
+    server: { port: process.env.PORT || 3000 },
+  });
+
+  await app.listen();
+}
+
+start();
+```
+
+---
+
+## 🛠️ Standalone `SecretManager` Usage
+
+```javascript
+const { createSecretManager } = require('webspresso/core/secrets');
+
+const secrets = createSecretManager({
+  provider: 'auto',   // Auto-detects GCP or AWS based on environment markers
+  cacheTtl: '10m',    // 10 minutes cache TTL
+  projectId: 'my-gcp-project', // optional for GCP
+  region: 'us-east-1',         // optional for AWS
+});
+
+// 1. Fetch a single secret
+const apiKey = await secrets.get('STRIPE_SECRET_KEY');
+
+// 2. Fetch with fallback or enforce required
+const optionalToken = await secrets.get('SLACK_WEBHOOK', { fallback: null });
+const mustExist = await secrets.get('APP_KEY', { required: true });
+
+// 3. Dot-notation subkey access inside JSON secret bundles
+const dbPassword = await secrets.get('prod/database.password');
+
+// 4. Invalidate cache on rotation
+secrets.invalidate('STRIPE_SECRET_KEY');
+```
+
+---
+
+## 💻 CLI Synchronization Tool (`secrets:pull`)
+
+Pulls cloud secrets into `.env.local` for local development:
+
+```bash
+# Auto-detect cloud platform and pull expected secrets into .env.local
+npx webspresso secrets:pull
+
+# Explicitly pull from Google Cloud Run / 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 bundle to stdout (dry run)
+npx webspresso secrets:pull --bundle prod/app/config --dry-run
+
+# Output as JSON
+npx webspresso secrets:pull -s API_KEY DB_PASS --format json -o secrets.json
+```
+
+---
+
+## 🔒 Security Best Practices
+
+1. **Never commit `.env` or `.env.local`**: Ensure `.env.local` is listed in `.gitignore` and `.gcloudignore`.
+2. **Minimal IAM Permissions**:
+   - GCP: Grant the Cloud Run service account `roles/secretmanager.secretAccessor`.
+   - AWS: Grant the ECS Task role `secretsmanager:GetSecretValue` and `ssm:GetParameter`.
+3. **Use Short TTL for Rotating Secrets**: If secrets rotate frequently (e.g. daily), configure `cacheTtl: '15m'` or invalidate on rotation webhook triggers.

package/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`](.agents/QUEUE.md) | `jobs/` |
 | **Decoupled Events & Signals** | [`.agents/EVENTS.md`](.agents/EVENTS.md) | `core/events/`, `listeners/` |
 | **Fault Tolerance / Circuit Breaker / Retry** | [`.agents/RESILIENCE.md`](.agents/RESILIENCE.md) | `core/resilience/` |
+| **Stateless Scale-Out (Redis Sessions & DB Pool)** | [`.agents/SCALE_OUT.md`](.agents/SCALE_OUT.md) | `core/auth/redis-session.js`, `core/orm/pool.js` |
+| **Cloud Secrets (GCP & AWS Secret Manager)** | [`.agents/SECRETS.md`](.agents/SECRETS.md) | `core/secrets/`, `bin/commands/secrets-pull.js` |
+| **Cloud Metrics & Distributed Tracing** | [`.agents/METRICS.md`](.agents/METRICS.md) | `core/metrics/`, `/metrics` |
+| **Cloud Migration Jobs (Zero-Downtime DB Deploy)** | [`.agents/MIGRATION_JOBS.md`](.agents/MIGRATION_JOBS.md) | `bin/commands/add-migration-job.js`, `core/orm/migrate-cloud.js` |
+| **Rate Limiting Engine (Zero-Dependency & Redis)** | [`.agents/RATE_LIMIT.md`](.agents/RATE_LIMIT.md) | `core/rate-limit/` |
+| **Feature Flags & Canary Splitter (`core/flags`)** | [`.agents/FLAGS.md`](.agents/FLAGS.md) | `core/flags/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -63,6 +69,10 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 - **Native Cloud & Kubernetes Health & Readiness Probes**: Zero-dependency RFC-compliant liveness (`/healthz`), readiness (`/readyz`), and combined diagnostic (`/health`) endpoints configured via `createApp({ healthCheck: true })`. Includes non-blocking event loop lag monitoring (`perf_hooks.monitorEventLoopDelay`), database/queue connectivity tests, and automatic HTTP 503 draining integration with `ShutdownManager` when pods enter graceful termination.
 - **High-Performance In-Memory LRU & Tagged Cache Engine**: Zero-dependency memory-bounded caching (`core/cache`) configured via `createApp({ cache: { maxEntries: 1000, maxMemoryMb: 50, defaultTtl: '15m' } })` or shorthand `cache: true|false`. Provides O(1) LRU eviction, byte budget constraints preventing OOM, leak-free tag invalidation (`TaggedLruCache`), stampede protection (`getOrSet`), and powers ORM query caching and Zod schema caching.
 - **Enterprise Resilience & Fault Tolerance (Circuit Breaker & Retry Engine)**: Zero-dependency resilience system (`core/resilience`) featuring a three-state `CircuitBreaker` (`CLOSED`, `OPEN`, `HALF_OPEN`), rolling window failure rate tracking, per-call execution timeouts, graceful fallbacks, and an exponential backoff retry engine (`retry`, `withRetry`) with randomized jitter and transient error detection (`ECONNRESET`, 429, 5xx). Seamlessly integrated into the Services Layer (`defineService({ circuitBreaker, retry })`) and exposed via `app.breakers`, `app.getBreaker()`, `req.breaker()`, and `req.retry()`.
+- **Stateless Scale-Out & Database Connection Pool Management**: Zero-dependency Redis session store (`createRedisSessionStore`), distributed device tracking (`createRedisSessionTracker`), lightweight RESP Redis client, serverless DB connection pool optimizer (`normalizeServerlessPoolConfig`), and scale-out audits in `webspresso deploy:check`. Automatically activates distributed sessions when `REDIS_URL` or `SESSION_STORE=redis` is configured.
+- **Enterprise Cloud Secrets Management**: Zero-dependency integration with Google Cloud Secret Manager & AWS Secrets Manager/SSM Parameter Store (`core/secrets`), in-memory caching with TTL (`cacheTtl: '5m'`), JSON secret bundle unpacking, dot-notation subkeys (`app.DB_PASSWORD`), bootstrap environment hydration (`loadSecrets()`), and local sync CLI (`webspresso secrets:pull`).
+- **Cloud Metrics & Distributed Tracing**: 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`) configured via `createApp({ metrics: true })`.
+- **Cloud Migration Jobs & Zero-Downtime Database Deploy**: Pre-deploy Cloud Run Jobs, AWS ECS Fargate one-off tasks, and Kubernetes Helm hooks (`add:migration-job`), safe retry connections, and automatic stale lock healing (`core/orm/migrate-cloud`, `webspresso db:migrate --safe`).
 - **Custom Error & 404 Pages**: Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`. Supports template paths (e.g. `notFound: '404.njk'`) or custom handler functions, passing `{ fsy, locale, isDev, url, method }` to templates.
 - **Cold Start & High-Performance Optimizations**:
   - Unified single-pass route scanner (`discoverAppRoutes`).