deploy-stack 0.14.1 → 0.14.2

package/README.md

@@ -124,6 +124,7 @@ your-project/
 ## 📦 Reference Implementations
 
 * **[Next.js Fullstack App](https://github.com/anton-codes-iac/deploy-stack-nextjs-example):** A complete Next.js deployment showcasing the generated Terraform, CloudFront setup, and automated OIDC workflow.
+* **[Vercel to AWS Migration (Next.js)](https://github.com/anton-codes-iac/deploy-stack-vercel-nextjs-example):** Demonstrates automatic translation of Vercel edge routing (`vercel.json`) to native AWS Application Load Balancer rules.
 * **[Express.js API](https://github.com/anton-codes-iac/deploy-stack-express-example):** A standard Node.js backend setup.
 * **[Python FastAPI](https://github.com/anton-codes-iac/deploy-stack-fastapi-example):** A Python API demonstrating unprivileged port mapping.
 * **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.

package/package.json

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

package/release_notes.md

@@ -1,20 +1,7 @@
-# 📚 The Documentation & Contextual UX Update
+# 📝 Architecture Overview & Vercel Example
 
-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.
+This patch release improves the documentation generated for end-users and adds the Vercel migration reference implementation to our ecosystem.
 
 ### 📖 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.
+* **Template Architecture Overview:** The auto-generated `README.md` placed in user repositories now includes a high-level "Architecture Overview". This ensures developers understand the AWS topology (ECS Fargate, ALB, IAM OIDC, S3 State) they just provisioned before diving into deployment commands.
+* **Vercel Example Linked:** Officially linked the `deploy-stack-vercel-nextjs-example` repository in the main project README, providing users a direct reference for migrating edge routing (`vercel.json`) and Next.js standalone configurations to AWS.

package/templates/README.md

@@ -4,6 +4,14 @@
 > 
 > It contains a production-ready AWS ECS Fargate architecture and a zero-secret GitHub Actions deployment pipeline.
 
+## 🏗️ Architecture Overview
+
+Your application has been configured for an enterprise-grade AWS deployment. Instead of relying on a black-box PaaS, you now own the underlying infrastructure:
+* **Compute:** Your app is packaged into a Docker container and runs on **AWS ECS Fargate** (Serverless compute, meaning no EC2 instances to manage).
+* **Networking:** Traffic flows through an **Application Load Balancer (ALB)**, which sits inside a custom VPC across multiple Availability Zones for high availability.
+* **Security:** Deployments are handled via GitHub Actions using **AWS IAM OIDC**. This means GitHub securely requests temporary tokens to deploy your code—no long-lived AWS keys are stored anywhere.
+* **State Management:** Terraform state is securely backed by an encrypted S3 bucket with DynamoDB locking.
+
 ## 💰 Cost Estimate & Disclaimer
 
 This infrastructure provisions a highly available Application Load Balancer (ALB) and an ECS Fargate container (Size: **{{COMPUTE_TIER}}**).
@@ -16,11 +24,11 @@ This infrastructure provisions a highly available Application Load Balancer (ALB
 ## 🚀 Deployment Guide
 
 1. **Initial Provisioning:**
+   Ensure you have configured your AWS CLI locally, then run the native deploy command:
    ```bash
-   cd terraform
-   terraform init
-   terraform apply
+   npx deploy-stack apply
    ```
+   *(Alternatively, run `cd terraform && terraform init && terraform apply`)*
 
 2. **Push Secrets (Optional):**
    If your application requires environment variables, create a local `.env` file and sync it directly to AWS Secrets Manager:
@@ -28,8 +36,8 @@ This infrastructure provisions a highly available Application Load Balancer (ALB
    npx deploy-stack secrets push .env
    ```
 
-3. **Automated CI/CD (Keyless via OIDC):**
-   Push this repository to GitHub. Your deployment pipeline uses the official [deploy-stack GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy) and AWS IAM OpenID Connect (OIDC) to authenticate securely with temporary credentials—**no long-lived AWS secret keys are required in GitHub Secrets**. Every push to `{{DEPLOY_BRANCH}}` will automatically run your infrastructure changes, build your container, and deploy your application.
+3. **Automated CI/CD:**
+   Push this repository to GitHub. Your deployment pipeline uses the official [deploy-stack GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy). Every push to `{{DEPLOY_BRANCH}}` will automatically run your infrastructure changes, build your container, and deploy your application.
 
 ### ⚠️ Troubleshooting: OIDC Provider Already Exists
 AWS only permits one GitHub Actions OIDC provider per AWS account. If `terraform apply` fails with an `EntityAlreadyExists` error regarding the OIDC provider, it indicates GitHub Actions was previously configured in this account.
@@ -42,7 +50,7 @@ variable "create_oidc_provider" {
   default = false # <--- Change this from true to false
 }
 ```
-Re-run `terraform apply` to link directly to your existing provider.
+Re-run `npx deploy-stack apply` to link directly to your existing provider.
 
 ## 🛑 Safe Teardown (Destroying the Stack)