webspresso 0.0.104 → 0.0.106

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

@@ -18,6 +18,13 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](.agents/AUTH.md) | `core/auth/` |
 | **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** |
 
 ---
@@ -57,6 +64,15 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 - **Framework Exceptions & Central Error Boundary**: Built-in exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`, `ConfigurationError`, `PluginError`, `RouteNotFoundError`) and custom handler hook (`app.setErrorHandler`). Async route handlers automatically propagate rejected promises. Production responses mask 500 stack traces and error details.
 - **Graceful Shutdown & Lifecycle Management**: Configured via `createApp({ server: { shutdown: { enabled: true, mode: 'graceful'|'force', timeout: 10000 } } })`. Socket connection tracking, request draining with `Connection: close`, and reverse-order plugin disposer cleanup.
 - **HTTP Response Compression**: Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })` with Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold buffering (1 KB), and route-level opt-out (`res.compress(false)`).
+- **HTTP 103 Early Hints & Critical Asset Preloading**: Zero-dependency RFC 8288 / RFC 8297 Early Hints dispatcher configured via `createApp({ earlyHints: true })` or per-page `definePage({ earlyHints })`. Emits informational 103 status code with route CSS/JS preloads before async `load()` finishes to minimize TTFB, FCP and LCP, with safe fallback and `res.earlyHints(links)` / `ctx.earlyHints(links)` helpers.
+- **Configurable Payload Size Limits & DoS Protection**: Zero-dependency body limit enforcement configured via `createApp({ limits: { json: '1mb', urlencoded: '1mb', raw: false, text: false, parameterLimit: 1000, captureRawBody: false } })` or shorthand `limits: '5mb'`, with automatic HTTP 413 `PayloadTooLargeError` and HTTP 400 `BadRequestError` mapping, route overrides (`limits.routes`), streaming bypass (`limits.exclude`), and raw body capture on `req.rawBody` for webhook signatures.
+- **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`).

package/README.md

@@ -22,7 +22,7 @@ cd my-app
 npm run dev
 ```
 
-Open **`http://localhost:3000`** in your browser.
+Open **`http://localhost:7331`** in your browser.
 
 ---
 
@@ -147,7 +147,7 @@ const { app } = createApp({
   },
 });
 
-const PORT = process.env.PORT || 3000;
+const PORT = process.env.PORT || 7331;
 app.listen(PORT, () => {
   console.log(`Server running at http://localhost:${PORT}`);
 });

package/bin/commands/add-aws.js

@@ -0,0 +1,396 @@
+/**
+ * Add AWS Command
+ * Generate production-ready AWS configuration (apprunner.yaml, ecs-task-definition.json, deploy-aws.sh)
+ * Supports AWS App Runner and AWS ECS (Fargate) container deployments
+ * @module bin/commands/add-aws
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { generateDockerfile, generateDockerignore } = require('./add-docker');
+
+/**
+ * Normalize CPU value to ECS Fargate units (256, 512, 1024, 2048, 4096)
+ * @param {string|number} cpu
+ * @returns {string}
+ */
+function normalizeEcsCpu(cpu) {
+  if (!cpu) return '512';
+  const str = String(cpu).trim().toLowerCase();
+  if (str === '0.25' || str === '0.25 vcpu') return '256';
+  if (str === '0.5' || str === '0.5 vcpu') return '512';
+  if (str === '1' || str === '1 vcpu') return '1024';
+  if (str === '2' || str === '2 vcpu') return '2048';
+  if (str === '4' || str === '4 vcpu') return '4096';
+  return str.replace(/[^0-9]/g, '') || '512';
+}
+
+/**
+ * Normalize Memory value to ECS Fargate MiB (512, 1024, 2048, etc.)
+ * @param {string|number} memory
+ * @returns {string}
+ */
+function normalizeEcsMemory(memory) {
+  if (!memory) return '1024';
+  const str = String(memory).trim().toLowerCase();
+  if (str.endsWith('gb') || str.endsWith('g')) {
+    const num = parseFloat(str);
+    return String(Math.round(num * 1024));
+  }
+  if (str.endsWith('mib') || str.endsWith('mb') || str.endsWith('mi')) {
+    return str.replace(/[^0-9]/g, '') || '1024';
+  }
+  return str.replace(/[^0-9]/g, '') || '1024';
+}
+
+/**
+ * Generate apprunner.yaml for AWS App Runner
+ * @param {Object} options
+ * @param {string} options.appName
+ * @param {number} [options.port=7331]
+ * @param {string} [options.nodeVersion='nodejs20']
+ * @returns {string}
+ */
+function generateAppRunnerYaml(options = {}) {
+  const {
+    port = 7331,
+    nodeVersion = 'nodejs20',
+  } = options;
+
+  return `# ==============================================================================
+# AWS App Runner Configuration for Webspresso
+# Fully-managed container & code runtime with auto-scaling and zero-ops TLS
+# Docs: https://docs.aws.amazon.com/apprunner/latest/dg/config-file.html
+# ==============================================================================
+
+version: 1.0
+runtime: ${nodeVersion}
+
+build:
+  commands:
+    build:
+      - npm ci --omit=dev
+      - npm run build --if-present
+  env:
+    - name: NODE_ENV
+      value: production
+
+run:
+  command: npm start
+  network:
+    port: "${port}"
+    env: PORT
+  env:
+    - name: NODE_ENV
+      value: production
+    - name: PORT
+      value: "${port}"
+`;
+}
+
+/**
+ * Generate AWS ECS Task Definition JSON for AWS Fargate
+ * @param {Object} options
+ * @param {string} options.appName
+ * @param {string} [options.region='us-east-1']
+ * @param {string|number} [options.cpu='512']
+ * @param {string|number} [options.memory='1024']
+ * @param {number} [options.port=7331]
+ * @returns {string}
+ */
+function generateEcsTaskDefinition(options = {}) {
+  const {
+    appName = 'webspresso-app',
+    region = 'us-east-1',
+    cpu = '512',
+    memory = '1024',
+    port = 7331,
+  } = options;
+
+  const normalizedCpu = normalizeEcsCpu(cpu);
+  const normalizedMemory = normalizeEcsMemory(memory);
+
+  const taskDef = {
+    family: appName,
+    networkMode: 'awsvpc',
+    requiresCompatibilities: ['FARGATE'],
+    cpu: normalizedCpu,
+    memory: normalizedMemory,
+    executionRoleArn: 'arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/ecsTaskExecutionRole',
+    taskRoleArn: 'arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/ecsTaskRole',
+    containerDefinitions: [
+      {
+        name: appName,
+        image: `YOUR_AWS_ACCOUNT_ID.dkr.ecr.${region}.amazonaws.com/${appName}:latest`,
+        essential: true,
+        portMappings: [
+          {
+            containerPort: port,
+            hostPort: port,
+            protocol: 'tcp',
+          },
+        ],
+        environment: [
+          { name: 'NODE_ENV', value: 'production' },
+          { name: 'PORT', value: String(port) },
+        ],
+        healthCheck: {
+          command: [
+            'CMD-SHELL',
+            `node -e 'require("http").get("http://localhost:${port}/healthz", (r) => process.exit(r.statusCode === 200 ? 0 : 1))' || exit 1`,
+          ],
+          interval: 30,
+          timeout: 5,
+          retries: 3,
+          startPeriod: 15,
+        },
+        logConfiguration: {
+          logDriver: 'awslogs',
+          options: {
+            'awslogs-group': `/ecs/${appName}`,
+            'awslogs-region': region,
+            'awslogs-stream-prefix': 'ecs',
+            'awslogs-create-group': 'true',
+          },
+        },
+      },
+    ],
+  };
+
+  return JSON.stringify(taskDef, null, 2) + '\n';
+}
+
+/**
+ * Generate deploy-aws.sh script for automated deployment to ECR, App Runner, or ECS
+ * @param {Object} options
+ * @param {string} options.appName
+ * @param {string} [options.region='us-east-1']
+ * @param {number} [options.port=7331]
+ * @returns {string}
+ */
+function generateAwsDeployScript(options = {}) {
+  const {
+    appName = 'webspresso-app',
+    region = 'us-east-1',
+    port = 7331,
+  } = options;
+
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# Webspresso AWS Deployment Automation Script
+# Builds hardened Docker image, pushes to Amazon ECR, and updates App Runner / ECS
+# Usage: ./deploy-aws.sh [APP_NAME] [REGION]
+# ==============================================================================
+
+APP_NAME="\${1:-${appName}}"
+REGION="\${2:-\${AWS_REGION:-${region}}}"
+PORT="\${PORT:-${port}}"
+
+echo "☁️  Webspresso AWS Deployment Target: '\$APP_NAME' in '\$REGION'"
+
+# 1. Verify AWS CLI
+if ! command -v aws &> /dev/null; then
+  echo "❌ Error: 'aws' CLI is not installed or not in PATH."
+  echo "Please install AWS CLI: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html"
+  exit 1
+fi
+
+# 2. Verify Docker
+if ! command -v docker &> /dev/null; then
+  echo "❌ Error: 'docker' is not installed or not running."
+  exit 1
+fi
+
+# 3. Retrieve AWS Account ID
+AWS_ACCOUNT_ID="\$(aws sts get-caller-identity --query Account --output text 2>/dev/null || true)"
+if [ -z "\$AWS_ACCOUNT_ID" ]; then
+  echo "❌ Error: Could not determine AWS Account ID. Are your AWS credentials configured?"
+  echo "Run: aws configure"
+  exit 1
+fi
+
+ECR_URI="\$AWS_ACCOUNT_ID.dkr.ecr.\$REGION.amazonaws.com/\$APP_NAME"
+IMAGE_TAG="\$(git rev-parse --short HEAD 2>/dev/null || echo 'latest')"
+
+echo "🔑 Authenticated as AWS Account: \$AWS_ACCOUNT_ID"
+echo "📦 Target ECR Repository: \$ECR_URI"
+
+# 4. Ensure ECR Repository exists
+aws ecr describe-repositories --repository-names "\$APP_NAME" --region "\$REGION" &>/dev/null || {
+  echo "📁 Creating ECR repository '\$APP_NAME'..."
+  aws ecr create-repository \\
+    --repository-name "\$APP_NAME" \\
+    --image-scanning-configuration scanOnPush=true \\
+    --region "\$REGION" >/dev/null
+}
+
+# 5. Authenticate Docker with Amazon ECR
+echo "🔐 Logging in to Amazon ECR..."
+aws ecr get-login-password --region "\$REGION" | docker login --username AWS --password-stdin "\$AWS_ACCOUNT_ID.dkr.ecr.\$REGION.amazonaws.com"
+
+# 6. Build production multi-stage Docker image
+echo "🔨 Building Docker image..."
+docker build -t "\$APP_NAME:\$IMAGE_TAG" -t "\$ECR_URI:\$IMAGE_TAG" -t "\$ECR_URI:latest" .
+
+# 7. Push to ECR
+echo "🚀 Pushing image to Amazon ECR..."
+docker push "\$ECR_URI:\$IMAGE_TAG"
+docker push "\$ECR_URI:latest"
+
+echo ""
+echo "✅ Image successfully built and pushed to Amazon ECR:"
+echo "   \$ECR_URI:\$IMAGE_TAG"
+echo "   \$ECR_URI:latest"
+echo ""
+echo "Next steps to complete deployment:"
+echo "  Option A (AWS App Runner):"
+echo "    aws apprunner create-service --service-name \$APP_NAME \\"
+echo "      --source-configuration ImageRepository='{ImageIdentifier=\"'\$ECR_URI:latest'\",ImageRepositoryType=\"ECR\",ImageConfiguration={Port=\"'\$PORT'\"}}'"
+echo ""
+echo "  Option B (AWS ECS Fargate):"
+echo "    aws ecs register-task-definition --cli-input-json file://ecs-task-definition.json"
+echo "    aws ecs update-service --cluster \$APP_NAME-cluster --service \$APP_NAME-service --force-new-deployment"
+echo ""
+`;
+}
+
+/**
+ * Register command with Commander
+ * @param {import('commander').Command} program
+ */
+function registerCommand(program) {
+  program
+    .command('add:aws')
+    .alias('aws')
+    .alias('add-aws')
+    .description('Generate production-ready AWS deployment configuration (App Runner & ECS Fargate)')
+    .option('-r, --region <region>', 'AWS region', 'us-east-1')
+    .option('--port <port>', 'Container port (Webspresso default is 7331)', (v) => parseInt(v, 10), 7331)
+    .option('--cpu <cpu>', 'CPU allocation for ECS/App Runner (e.g. 512, 1024 or 1 vCPU)', '512')
+    .option('--memory <memory>', 'Memory allocation for ECS/App Runner (e.g. 1024, 1GB)', '1024')
+    .option('-f, --force', 'Overwrite existing files without prompting', false)
+    .action(async (...actionArgs) => {
+      const cmd = actionArgs[actionArgs.length - 1];
+      const options = (cmd && typeof cmd.opts === 'function')
+        ? cmd.opts()
+        : (actionArgs.find((a) => a && typeof a === 'object') || {});
+
+      const cwd = process.cwd();
+      const pkgPath = path.join(cwd, 'package.json');
+
+      if (!fs.existsSync(pkgPath)) {
+        console.error('❌ Not a Webspresso project! package.json was not found in current directory.');
+        process.exit(1);
+      }
+
+      let pkg = {};
+      try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      } catch (err) {
+        console.error(`❌ Failed to parse package.json: ${err.message}`);
+        process.exit(1);
+      }
+
+      const appName = pkg.name ? pkg.name.replace(/[^a-zA-Z0-9_-]/g, '-') : 'webspresso-app';
+      const force = Boolean(options.force);
+      const region = options.region || 'us-east-1';
+      const port = options.port || 7331;
+      const cpu = options.cpu || '512';
+      const memory = options.memory || '1024';
+
+      const appRunnerPath = path.join(cwd, 'apprunner.yaml');
+      const ecsTaskDefPath = path.join(cwd, 'ecs-task-definition.json');
+      const scriptPath = path.join(cwd, 'deploy-aws.sh');
+      const dockerfilePath = path.join(cwd, 'Dockerfile');
+      const dockerignorePath = path.join(cwd, '.dockerignore');
+
+      console.log(`\n☁️  Scaffolding AWS deployment configuration for "${appName}"...`);
+
+      // 1. Ensure Dockerfile exists (needed by ECR & container deploy)
+      if (!fs.existsSync(dockerfilePath)) {
+        const dockerfileContent = generateDockerfile({ port, node: '22-alpine' });
+        fs.writeFileSync(dockerfilePath, dockerfileContent, 'utf8');
+        console.log(`✅ Created Dockerfile (configured for port ${port})`);
+      }
+
+      if (!fs.existsSync(dockerignorePath)) {
+        const dockerignoreContent = generateDockerignore();
+        fs.writeFileSync(dockerignorePath, dockerignoreContent, 'utf8');
+        console.log(`✅ Created .dockerignore`);
+      }
+
+      // 2. apprunner.yaml
+      if (fs.existsSync(appRunnerPath) && !force) {
+        console.log(`⚠️  ${path.basename(appRunnerPath)} already exists. Skipping (use --force to overwrite).`);
+      } else {
+        const appRunnerContent = generateAppRunnerYaml({
+          appName,
+          port,
+        });
+        fs.writeFileSync(appRunnerPath, appRunnerContent, 'utf8');
+        console.log(`✅ Created ${path.basename(appRunnerPath)} (AWS App Runner)`);
+      }
+
+      // 3. ecs-task-definition.json
+      if (fs.existsSync(ecsTaskDefPath) && !force) {
+        console.log(`⚠️  ${path.basename(ecsTaskDefPath)} already exists. Skipping (use --force to overwrite).`);
+      } else {
+        const taskDefContent = generateEcsTaskDefinition({
+          appName,
+          region,
+          cpu,
+          memory,
+          port,
+        });
+        fs.writeFileSync(ecsTaskDefPath, taskDefContent, 'utf8');
+        console.log(`✅ Created ${path.basename(ecsTaskDefPath)} (AWS ECS Fargate Task Definition)`);
+      }
+
+      // 4. deploy-aws.sh
+      if (fs.existsSync(scriptPath) && !force) {
+        console.log(`⚠️  ${path.basename(scriptPath)} already exists. Skipping (use --force to overwrite).`);
+      } else {
+        const scriptContent = generateAwsDeployScript({
+          appName,
+          region,
+          port,
+        });
+        fs.writeFileSync(scriptPath, scriptContent, { encoding: 'utf8', mode: 0o755 });
+        console.log(`✅ Created ${path.basename(scriptPath)} (executable)`);
+      }
+
+      // 5. Update package.json scripts
+      let modifiedPkg = false;
+      if (!pkg.scripts) pkg.scripts = {};
+      if (!pkg.scripts['aws:deploy']) {
+        pkg.scripts['aws:deploy'] = './deploy-aws.sh';
+        modifiedPkg = true;
+      }
+
+      if (modifiedPkg) {
+        try {
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+          console.log(`✅ Added "aws:deploy" script to package.json`);
+        } catch (_) {}
+      }
+
+      console.log('\n🎉 AWS deployment configuration complete!');
+      console.log('\nNext steps:');
+      console.log('  1. Configure AWS CLI: `aws configure`');
+      console.log('  2. Review ecs-task-definition.json and apprunner.yaml');
+      console.log('  3. Deploy container via ECR: `npm run aws:deploy`\n');
+    });
+}
+
+module.exports = {
+  registerCommand,
+  generateAppRunnerYaml,
+  generateEcsTaskDefinition,
+  generateAwsDeployScript,
+  normalizeEcsCpu,
+  normalizeEcsMemory,
+};