deploy-stack 0.13.0 → 0.14.1

package/README.md

@@ -30,7 +30,7 @@ You retain complete ownership of your infrastructure code without relying on bla
 **🚀 Zero-Config Deployments**
 * **Framework Agnostic:** Tailored container presets for Next.js, Express.js, FastAPI, Go, Django, Rails, Nuxt 3, and Static Sites (React, Vue, SvelteKit, Astro).
 * **Smart Discovery:** Automatically detects build output directories and generates highly optimized, multi-stage Dockerfiles.
-* **PaaS Migration Engine:** Natively parses Heroku `Procfile` configurations to automatically translate web and background worker processes (like Celery or Sidekiq) into multi-container AWS Fargate architectures.
+* **PaaS Migration Engine:** Natively parses Heroku `Procfile` configurations and `vercel.json` files to automatically translate proprietary edge routing (redirects/rewrites) and background workers into standard AWS Fargate and Application Load Balancer architectures.
 * **Database Scaffolding:** Automatically provisions fully isolated, zero-trust AWS RDS PostgreSQL databases for backend monoliths.
 
 **🛡️ DevSecOps & Security**
@@ -51,6 +51,15 @@ You retain complete ownership of your infrastructure code without relying on bla
 
 ---
 
+## 📚 Documentation & Guides
+Transitioning from PaaS to AWS involves a few architectural shifts. We've written concise guides to help you understand how `deploy-stack` handles the heavy lifting:
+* [Migrating from Heroku to AWS (Procfile Support)](./docs/migrations/heroku-procfile-to-aws.md)
+* [Managing Secrets & Environment Variables](./docs/guides/secrets-management.md)
+* [Zero-Trust Database Connections](./docs/guides/database-connections.md)
+* [Migrating Next.js from Vercel](./docs/migrations/nextjs-vercel-to-aws.md)
+
+---
+
 ## 🚀 Quick Start
 
 Run the CLI directly in your project root:
@@ -158,7 +167,7 @@ npx deploy-stack --no-telemetry
 
 ### Phase 6: Migration & Trust Engine (Current)
 - [x] **Dry-Run Visualization:** Interactive pre-flight terminal UI with ASCII topology maps and precise, dynamic AWS cost estimation.
-- [ ] **PaaS Importers:** Auto-parse `vercel.json` or Heroku `Procfile` configurations to map build commands and environment variables automatically.
+- [x] **PaaS Importers:** Auto-parse `vercel.json` and Heroku `Procfile` configurations to map routing rules, web commands, and background workers automatically.
 - [ ] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
 - [ ] **AI Agent Rulesets:** Publishing `.cursorrules` and Copilot instructions that teach AI assistants exactly how to utilize the CLI on the user's behalf.
 

package/docs/guides/database-connections.md

@@ -0,0 +1,27 @@
+# Managed Database Connections
+
+When you run `npx deploy-stack` for a backend framework (Node, Django, Rails, Go, etc.), the CLI prompts you to automatically provision a managed AWS RDS PostgreSQL database.
+
+## Zero-Trust Architecture
+
+If you select "Yes", `deploy-stack` builds a true zero-trust network topology:
+1. The PostgreSQL instance is deployed into heavily restricted **Isolated Subnets**.
+2. It is given a strict Security Group that *only* allows inbound traffic from your specific ECS Fargate containers on port `5432`.
+3. The database is completely inaccessible from the public internet.
+
+## Auto-Injected Environment Variables
+
+You do not need to configure database connection strings manually. The generated Terraform automatically creates a secure, random master password in AWS Secrets Manager and injects the following environment variables directly into your running containers:
+
+* `DB_HOST` (The internal AWS DNS endpoint)
+* `DB_PORT` (5432)
+* `DB_NAME` (Your auto-generated database name)
+* `DB_USER` (Injected securely at runtime)
+* `DB_PASSWORD` (Injected securely at runtime)
+
+To connect your application, simply configure your ORM (Prisma, Django, TypeORM, Active Record) to read from these standard environment variables.
+
+## Running Database Migrations
+
+Because the database is in an isolated subnet, you cannot run schema migrations directly from your local laptop. 
+The best practice is to configure your CI/CD pipeline or your Docker container's startup script to run your migrations (e.g., `npx prisma deploy` or `python manage.py migrate`) before starting the main web process.

package/docs/guides/secrets-management.md

@@ -0,0 +1,24 @@
+# Secrets Management in deploy-stack
+
+Managing `.env` files across a team and syncing them to the cloud is a notorious pain point. `deploy-stack` solves this by natively integrating with **AWS Secrets Manager**, ensuring zero plaintext secrets ever touch your GitHub repository or CI/CD pipelines.
+
+## Pushing Secrets to AWS
+
+Instead of manually clicking through the AWS Console, use the built-in secrets command:
+
+```bash
+npx deploy-stack secrets push .env.production
+```
+
+### What happens under the hood?
+1. The CLI reads your local `.env.production` file.
+2. It encrypts the key-value pairs and pushes them securely into AWS Secrets Manager under your project's namespace (e.g., `my-project-secrets`).
+3. It generates a local `terraform/secret_keys.json` file containing *only the names* of your keys (e.g., `["API_KEY", "STRIPE_SECRET"]`), **not the values**.
+
+## How Secrets Reach Your App
+
+When you commit `terraform/secret_keys.json` and push to GitHub, your CI/CD pipeline runs Terraform. 
+
+Terraform reads the JSON array of key names and dynamically maps them to your ECS Task Definition. When your AWS Fargate container boots up, it automatically injects those secrets directly into your application's environment as standard environment variables (e.g., `process.env.STRIPE_SECRET` or `os.getenv("API_KEY")`).
+
+*Note: Because Terraform maps the secrets at runtime, updating a secret value in AWS and running an empty GitHub deployment will instantly cycle your containers with the new keys!*

package/docs/migration/astro-vercel-to-aws.md

@@ -0,0 +1,47 @@
+# Migrating Astro from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about your Astro adapter, it means your project is currently configured to build specifically for Vercel's proprietary serverless network. 
+
+To deploy Astro as a containerized application on standard AWS infrastructure, you simply need to switch to Astro's official Node.js adapter.
+
+## How to Fix
+
+### 1. Install the Node adapter
+Run the following command in your terminal to swap out the Vercel adapter for the Node adapter:
+
+\`\`\`bash
+npm install @astrojs/node
+npm uninstall @astrojs/vercel
+\`\`\`
+
+### 2. Update `astro.config.mjs`
+Open your Astro configuration file and replace the Vercel import with the Node import.
+
+**Before (Vercel Lock-in):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel/serverless';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+});
+\`\`\`
+
+**After (AWS Ready):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone'
+  }),
+});
+\`\`\`
+
+### 3. Deploy
+That's it! Your Astro app is now decoupled from Vercel. 
+
+Run `npx deploy-stack apply` and the CLI will automatically package this standalone Node server into a hardened Docker container and deploy it to your AWS cluster.

package/docs/migration/heroku-procfile-to-aws.md

@@ -0,0 +1,32 @@
+# Migrating from Heroku to AWS (Procfile Support)
+
+When migrating from Heroku or Render, you likely rely on a `Procfile` to define your application's architecture (e.g., a web server and a background worker like Celery or Sidekiq). 
+
+`deploy-stack` natively understands Heroku `Procfile` syntax and automatically translates it into a production-grade, multi-container AWS architecture.
+
+## How it Works
+
+When you run `npx deploy-stack`, the CLI scans your root directory for a `Procfile`. 
+
+### The `web` Process
+If the CLI detects a `web:` declaration:
+1. It overrides the default Docker `CMD`.
+2. It provisions an AWS ECS Fargate service for this process.
+3. It automatically wires this specific container to your public-facing Application Load Balancer (ALB) so it can receive internet traffic.
+
+### The `worker` Process
+If the CLI detects a `worker:` declaration:
+1. It generates a completely separate ECS Fargate task definition (`worker.tf`).
+2. It spins up the worker in a **fully isolated private subnet**.
+3. It intentionally strips all public ingress, ensuring your background workers are secure and can only communicate with your database or message brokers internally.
+
+## Example
+
+**Your `Procfile`:**
+```text
+web: gunicorn myapp.wsgi
+worker: celery -A myapp worker -l info
+```
+
+**The Result:**
+Running `deploy-stack` will automatically generate the Terraform required to spin up both containers simultaneously from the exact same Docker image, scaling them independently based on your needs.

package/docs/migration/nextjs-vercel-to-aws.md

@@ -0,0 +1,43 @@
+# Migrating Next.js from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about `output: 'standalone'`, your Next.js configuration is missing a crucial setting required for containerized environments.
+
+By default, Next.js requires your entire `node_modules` folder to run the production server. This creates massive, bloated Docker containers that boot slowly and cost more to host. The `standalone` output mode tells Next.js to trace your code and bundle *only* the specific files and dependencies actually used in production, creating an ultra-lean deployment artifact.
+
+## How to Fix
+
+### 1. Update `next.config.js` (or `.mjs` / `.cjs`)
+Open your Next.js configuration file in the root of your project and add `output: 'standalone'` to the configuration object.
+
+**Before (Vercel Default):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+**After (AWS Ready):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  output: 'standalone', // <-- Add this line
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+### 2. (Optional) Define a Health Check Route
+AWS Application Load Balancers require a route to ping to ensure your app is healthy. If you don't already have one, create a simple API route in your app (e.g., `app/api/health/route.ts` for App Router, or `pages/api/health.ts` for Pages Router) that returns a `200 OK` status.
+
+When running `deploy-stack`, choose **Advanced Configuration** and set your ALB Health Check Path to this route (e.g., `/api/health`).
+
+### 3. Deploy
+Your Next.js app is now perfectly optimized for AWS ECS Fargate! 
+
+Run `npx deploy-stack apply`. The CLI's generated `Dockerfile` will automatically target your new `.next/standalone` directory and deploy the optimized build to the cloud.

package/docs/migration/sveltekit-vercel-to-aws.md

@@ -0,0 +1,55 @@
+# Migrating SvelteKit from Vercel to AWS Fargate
+
+If you are seeing a warning from `deploy-stack` about your SvelteKit adapter, your project is currently using `@sveltejs/adapter-auto` (which often defaults to Vercel) or the explicit `@sveltejs/adapter-vercel`.
+
+These adapters are designed specifically for proprietary serverless edge networks. To run your SvelteKit app in a scalable, standard Docker container on AWS Fargate, you need to switch to Svelte's official Node adapter.
+
+## How to Fix
+
+### 1. Install the Node Adapter
+Run the following command in your terminal to install the Node adapter and remove the Vercel/Auto adapter:
+
+```bash
+npm install -D @sveltejs/adapter-node
+npm uninstall @sveltejs/adapter-auto @sveltejs/adapter-vercel
+```
+
+### 2. Update `svelte.config.js`
+Open your `svelte.config.js` file and change the adapter import at the top of the file.
+
+**Before (Locked into Vercel/Auto):**
+```javascript
+import adapter from '@sveltejs/adapter-auto'; // or '@sveltejs/adapter-vercel'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+**After (AWS Ready):**
+```javascript
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+### 3. Deploy
+Your SvelteKit app is now decoupled! 
+
+Run `npx deploy-stack apply`. The CLI will automatically detect the standard Node build output, package it into a hardened Docker container, and deploy it to your AWS cluster.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"

package/release_notes.md

@@ -0,0 +1,20 @@
+# 📚 The Documentation & Contextual UX Update
+
+This patch release focuses entirely on Developer Experience (DX), ensuring that users migrating from PaaS platforms have clear, actionable documentation for AWS-native concepts right when they need them.
+
+### 📖 What's New
+* **PaaS Escape Hatch Guides:** Added step-by-step guides for decoupling frontend frameworks from Vercel's proprietary edge network:
+  * **Next.js:** Enforcing `output: 'standalone'` for standard Docker deployments.
+  * **SvelteKit:** Swapping `@sveltejs/adapter-auto` or the Vercel adapter for the official Node adapter.
+  * **Astro:** Replacing `@astrojs/vercel` with `@astrojs/node`.
+* **Comprehensive AWS Migration Guides:** Added dedicated documentation for our core backend engines:
+  * **Heroku Migration:** Detailed breakdown of how `Procfile` `web` and `worker` processes map to AWS Fargate and private subnets.
+  * **Secrets Management:** A deep dive into how `deploy-stack` leverages AWS Secrets Manager to inject environment variables at runtime.
+  * **Database Scaffolding:** Explains our zero-trust PostgreSQL architecture and auto-injected connection strings.
+
+### 🛠️ CLI UX Enhancements
+* **Context-Aware Documentation Links:** The CLI now dynamically injects links to the relevant documentation at the exact moment a user might need it. 
+  * If a Vercel-locked Next.js, SvelteKit, or Astro config is detected, the CLI links directly to the respective migration fix.
+  * If a `Procfile` is detected, the `deploy-stack` outro links to the Heroku guide.
+  * If a database is provisioned, the outro links to the database connection guide.
+  * Running `deploy-stack secrets push` now outputs a direct link explaining how those secrets reach the Fargate containers.

package/src/commands/apply.js

@@ -5,6 +5,7 @@ import { intro, outro, spinner, log, cancel } from '@clack/prompts';
 import color from 'picocolors';
 import { renderDryRunPreview, parseTerraformConfig } from '../utils/visualizer.js';
 import { detectFramework } from '../utils/detector.js';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 
 // Helper to run a command while piping the latest stdout line into a @clack spinner
 function runTerraformCommand(args, cwd, spin, loadingPrefix) {
@@ -125,6 +126,14 @@ export async function applyStack(options = {}) {
 
         outro(`${finalMessage}\n\n  ${color.yellow('Push code to deploy your app and clear the 503 error:')}\n  ${color.cyan('git add . && git commit -m "ci: infra" && git push origin main')}`);
 
+        const actualProjectName = path.basename(process.cwd());
+        trackEvent('infrastructure_applied', {
+            projectName: actualProjectName,
+            framework: detectedConfig.framework,
+            success: true
+        });
+        await flushTelemetry();
+
         process.exit(0);
 
     } catch (error) {
@@ -146,6 +155,15 @@ export async function applyStack(options = {}) {
             log.message(`${color.bold('To debug manually, navigate to your terraform folder:')}`);
             log.message(color.cyan('cd terraform && terraform apply'));
         }
+
+        const actualProjectName = path.basename(process.cwd());
+        trackEvent('infrastructure_applied', {
+            projectName: actualProjectName,
+            success: false,
+            error_code: error.code || 'UNKNOWN'
+        });
+        await flushTelemetry();
+
         process.exit(1);
     }
 }

package/src/commands/destroy.js

@@ -87,6 +87,15 @@ export async function destroyStack() {
     } catch (error) {
         s.stop(color.red('❌ Terraform destroy failed.'));
         console.error(color.red(error.message));
+
+        const actualProjectName = path.basename(process.cwd());
+        trackEvent('infrastructure_destroyed', {
+            projectName: actualProjectName,
+            success: false,
+            error_code: error.code || 'UNKNOWN'
+        });
+        await flushTelemetry();
+
         process.exit(1);
     }
 
@@ -111,9 +120,11 @@ export async function destroyStack() {
         }
     }
 
-    trackEvent('project_destroyed', {
+    const actualProjectName = path.basename(process.cwd());
+    trackEvent('infrastructure_destroyed', {
+        projectName: actualProjectName,
         region,
-        bucket: bucketName,
+        retained_state_bucket: !(deleteS3Bucket && typeof deleteS3Bucket !== 'symbol'),
         success: true
     });
     await flushTelemetry();

package/src/commands/doctor.js

@@ -1,6 +1,7 @@
 import { intro, outro, spinner } from '@clack/prompts';
 import color from 'picocolors';
 import { checkDependency } from '../utils/system.js';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 
 export async function runDoctor() {
     intro(color.bgCyan(color.black(' deploy-stack ☁️  ')));
@@ -36,4 +37,9 @@ export async function runDoctor() {
     } else {
         outro(color.yellow('Please install the missing dependencies before running the provisioning tool.'));
     }
+
+    trackEvent('doctor_run', {
+        success: hasTerraform && hasAws && hasDocker && hasGit
+    });
+    await flushTelemetry();
 }

package/src/commands/eject.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { intro, outro, confirm, spinner, cancel } from '@clack/prompts';
 import color from 'picocolors';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 
 export async function ejectStack() {
     intro(color.bgRed(color.white(' deploy-stack eject ⏏️  ')));
@@ -68,6 +69,12 @@ export async function ejectStack() {
 
     s.stop('Ejection complete.');
 
+    const actualProjectName = path.basename(process.cwd());
+    trackEvent('project_ejected', {
+        projectName: actualProjectName
+    });
+    await flushTelemetry();
+
     outro(`
     ${color.green('✅ Successfully ejected from deploy-stack!')}