deploy-stack 0.17.7 → 0.17.9

package/.github/workflows/publish.yml

@@ -28,6 +28,31 @@ jobs:
         
       - name: Install dependencies
         run: npm install
+
+      # --- Phase 1: Static Generation Validation ---
+      - name: Run Unit & Snapshot Tests
+        run: npm test
+
+      # --- Phase 2: Execution & Security Validation ---
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Init TFLint
+        run: tflint --init
+
+      - name: Run TFLint across Terraform files
+        run: tflint --recursive || true
+
+      - name: Run Trivy IaC Config Scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'config'
+          scan-dir: '.'
+          format: 'table'
+          exit-code: '0' 
       
+      # --- Phase 3: Publish ---
       - name: Publish to NPM
         run: npm publish --provenance

package/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Test Suite
+
+on:
+  push:
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run Vitest Suite
+        run: npm test
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Init TFLint
+        run: tflint --init
+
+      - name: Run TFLint across Terraform files
+        run: tflint --recursive || true
+
+      - name: Run Trivy IaC Config Scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'config'
+          scan-dir: '.'
+          format: 'table'
+          exit-code: '0' # Set to '1' to block PRs on Trivy findings once baselined

package/README.md

@@ -28,7 +28,7 @@ You retain complete ownership of your infrastructure code without relying on bla
 ## ✨ Features
 
 **🚀 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).
+* **Framework Agnostic:** Tailored container presets for Next.js, Express.js, NestJS, 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.
 * **Migration Engines:** Natively parses Heroku `Procfile` configurations, `vercel.json` routing rules, and `docker-compose.yml` sidecar architectures to automatically translate them into standard AWS Fargate and Application Load Balancer topologies.
 * **Database Scaffolding:** Automatically provisions fully isolated, zero-trust AWS RDS PostgreSQL databases for backend monoliths.
@@ -170,8 +170,8 @@ npx deploy-stack --no-telemetry
   - [x] `vite-plugin-deploy-stack` (Vite / React / Vue SPA ecosystem)
   - [x] `svelte-adapter-deploy-stack` (SvelteKit adapter integration)
   - [x] `cookiecutter-django-deploy-stack` (Listed on Django Packages)
-  - [ ] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
-  - [ ] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
+  - [x] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
+  - [x] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
   - [ ] `rails-template-deploy-stack` (Zero-click Ruby on Rails application template)
 - [ ] **Automated Troubleshooting:** Build `deploy-stack diagnose` (alias: `wtf`) to automatically analyze and troubleshoot common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.
 

package/bin/cli.js

@@ -7,61 +7,31 @@ import { pushSecrets } from '../src/commands/secrets.js';
 import { ejectStack } from '../src/commands/eject.js';
 import { applyStack } from '../src/commands/apply.js';
 import { syncAi } from '../src/commands/sync-ai.js';
+import { parseCliArgs } from '../src/core/parser.js';
 
-// 1. Extract the telemetry flag and set the environment variable
 const rawArgs = process.argv.slice(2);
-const hasNoTelemetry = rawArgs.some(arg => arg === '--no-telemetry' || arg.startsWith('--no-telemetry='));
+const parsed = parseCliArgs(rawArgs);
 
-if (hasNoTelemetry) {
+if (parsed.hasNoTelemetry) {
     process.env.DO_NOT_TRACK = '1';
 }
+process.env.CLI_COMMAND = parsed.baseCommand;
 
-// 2. Filter out the telemetry flag from the args so the subcommands don't see it
-const args = rawArgs.filter((arg) => arg !== '--no-telemetry' && !arg.startsWith('--no-telemetry='));
+const { positionalArgs, isHeadless, isDryRun, headlessOptions } = parsed;
 
-// 3. Isolate positional commands from flags
-// This ensures flags (e.g., --dry-run) don't accidentally become file paths
-const positionalArgs = args.filter(arg => !arg.startsWith('--'));
-
-// Safely capture the base command for telemetry (ignoring file paths)
-const baseCommand = positionalArgs.length > 0 ? positionalArgs.slice(0, 2).join(' ') : 'init';
-process.env.CLI_COMMAND = baseCommand;
-
-// 4. Parse headless flags
-const isHeadless = args.includes('--headless');
-const isDryRun = args.includes('--dry-run');
-const getFlag = (flagName) => {
-    const match = args.find(a => a === `--${flagName}` || a.startsWith(`--${flagName}=`));
-    if (match === `--${flagName}`) return true;
-    return match ? match.split('=')[1] : undefined;
-};
-const headlessOptions = isHeadless ? {
-    dir: getFlag('dir'),
-    framework: getFlag('framework'),
-    region: getFlag('region'),
-    port: getFlag('port'),
-    size: getFlag('size'),
-    healthCheckPath: getFlag('healthCheckPath'),
-    desiredCount: getFlag('desiredCount'),
-    branch: getFlag('branch'),
-    needsDatabase: getFlag('needsDatabase'),
-    enablePrPreviews: getFlag('enablePrPreviews')
-} : {};
-
-// 5. Handle commands
-if (args[0] === 'secrets' && args[1] === 'push') {
-    const envFile = args[2] || '.env';
+if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'push') {
+    const envFile = positionalArgs[2] || '.env';
     const projectName = path.basename(process.cwd());
     pushSecrets(envFile, projectName).catch(e => { console.error(e); process.exit(1); });
-} else if (args[0] === 'apply') {
+} else if (positionalArgs[0] === 'apply') {
     applyStack({ isDryRun }).catch(e => { console.error(e); process.exit(1); });
-} else if (args[0] === 'doctor') {
+} else if (positionalArgs[0] === 'doctor') {
     runDoctor().catch(e => { console.error(e); process.exit(1); });
-} else if (args[0] === 'destroy') {
+} else if (positionalArgs[0] === 'destroy') {
     destroyStack().catch(e => { console.error(e); process.exit(1); });
-} else if (args[0] === 'eject') {
+} else if (positionalArgs[0] === 'eject') {
     ejectStack().catch(e => { console.error(e); process.exit(1); });
-} else if (args[0] === 'sync-ai') {
+} else if (positionalArgs[0] === 'sync-ai') {
     syncAi().catch(e => { console.error(e); process.exit(1); });
 } else {
     mainStack({ isHeadless, headlessOptions }).catch(e => { console.error(e); process.exit(1); });

package/docs/ROADMAP.md

@@ -30,7 +30,7 @@
   - [x] `vite-plugin-deploy-stack` (Live on NPM)
   - [x] `svelte-adapter-deploy-stack` (SvelteKit adapter integration)
   - [x] `cookiecutter-django-deploy-stack` (Listed on Django Packages)
-  - [ ] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
-  - [ ] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
+  - [x] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
+  - [x] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
   - [ ] `rails-template-deploy-stack` (Zero-click Ruby on Rails application template)
 - [ ] **Automated Troubleshooting:** Build `deploy-stack diagnose` (alias: `wtf`) to automatically analyze and troubleshoot common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.

package/docs/adr/0001-s3-native-state-locking.md

@@ -0,0 +1,35 @@
+# 0001. S3 Native State Locking
+
+* **Status:** Accepted
+* **Date:** 2026-08-15 (Retroactive)
+* **Deciders:** Core Engineering Team
+
+## Context and Problem Statement
+
+When deploying infrastructure via Terraform across local developer workstations and automated CI/CD pipelines, remote state management is required to prevent race conditions, state drift, and concurrent apply corruption. 
+
+Traditionally, managing Terraform remote state on AWS required provisioning both an S3 bucket (for storage) and a dedicated DynamoDB table (for state locking). This added operational overhead, increased the baseline AWS resource footprint, and required developers to manage extra IAM permissions solely for locking metadata.
+
+## Decision Drivers
+
+* **Simplicity:** Minimize the number of AWS resources a user has to provision and manage day-to-day.
+* **Cost Efficiency:** Eliminate unnecessary idle infrastructure costs (e.g., DynamoDB provisioned capacity).
+* **Reliability:** Guarantee that concurrent CI/CD pipeline runs and local CLI executions cannot corrupt Terraform state files.
+
+## Considered Options
+
+1. **S3 + DynamoDB Table:** The traditional HashiCorp recommendation for remote state locking.
+2. **S3 Native State Locking:** Utilizing S3's native conditional write support for state locking directly within the S3 bucket backend.
+3. **Third-Party State Backends:** (e.g., Terraform Cloud) — rejected to preserve zero-vendor-lock-in and keep execution local to the user's AWS account.
+
+## Decision Outcome
+
+**Chosen Option:** Use an encrypted Amazon S3 bucket as the remote state backend leveraging Terraform's native S3 state locking capabilities.
+
+### Positive Consequences
+* **Zero Maintenance:** Users do not have to monitor, manage, or pay for an extra DynamoDB table.
+* **Tighter Security:** Simplifies the IAM policy scope required for the `deploy-stack` state bucket helper, adhering strictly to least privilege.
+* **Frictionless Onboarding:** Streamlines the bootstrapping experience during the initial `npx deploy-stack` run.
+
+### Negative Consequences
+* Relies on modern Terraform backend behavior that supports S3 native locks. Edge cases involving highly outdated, legacy Terraform CLI versions are not supported.

package/docs/adr/0002-eject-mechanism-pure-iac.md

@@ -0,0 +1,37 @@
+# 0002. Eject Mechanism for Pure IaC
+
+* **Status:** Accepted
+* **Date:** 2026-08-20 (Retroactive)
+* **Deciders:** Core Engineering Team
+
+## Context and Problem Statement
+
+`deploy-stack` abstracts away the complexity of writing raw Terraform for ECS Fargate, ALBs, CloudFront, OIDC, and Secrets Manager. However, a primary reason senior platform teams hesitate to adopt deployment generators is the fear of **tool lock-in**. Teams need a guarantee that if their architecture outgrows the CLI, or if they wish to take 100% manual control of the codebase, they can do so without starting from scratch.
+
+## Decision Drivers
+
+* **Zero Vendor Lock-In:** Uphold the foundational promise that developers permanently own their infrastructure code.
+* **Auditability & Freedom:** Provide teams with an unambiguous "escape hatch" to sever ties with `deploy-stack` management metadata while maintaining a perfectly functioning infrastructure pipeline.
+
+## Considered Options
+
+1. **No Eject Command:** Require users to manually delete `ManagedBy` tags and untangle state/workflows by hand.
+2. **Submodule / Framework Wrapper:** Keep the Terraform code hidden inside a remote module (rejected, as it violates the core premise of transparent, readable IaC).
+3. **Explicit `eject` Command:** Build a dedicated `npx deploy-stack eject` utility that strips all CLI metadata and tracking tags, leaving behind clean, standard Terraform and GitHub Actions files.
+
+## Decision Outcome
+
+**Chosen Option:** Implement an explicit `npx deploy-stack eject` command as a core feature.
+
+### Technical Implementation Details
+When invoked, `eject`:
+* Removes or sanitizes internal `ManagedBy = "deploy-stack"` default tags across all generated files.
+* Preserves all generated `.tf`, `Dockerfile`, and `.github/workflows/` files safely in place.
+* Detaches the project from the CLI entirely, leaving valid Terraform code that can be managed directly via the `terraform` or `opentofu` binaries.
+
+### Positive Consequences
+* Builds trust with engineers and security teams who refuse black-box wrappers.
+* Eliminates friction during adoption; users know they can safely leave at any time.
+
+### Negative Consequences
+* Ejected repositories permanently lose access to automated security patches, template updates, or CLI-driven drift synchronization.

package/docs/adr/0003-sync-ai-context-strategy.md

@@ -0,0 +1,46 @@
+# 0003. AI Context Synchronization Strategy
+
+* **Status:** Accepted
+* **Date:** 2026-09-02 (Retroactive)
+* **Deciders:** Core Engineering Team
+
+## Context and Problem Statement
+
+Modern engineering teams heavily utilize AI coding assistants (Cursor, GitHub Copilot, Windsurf, Claude Code, etc.) in their local IDEs. However, when dealing with Infrastructure-as-Code (IaC), AI models frequently hallucinate invalid Terraform syntax, recommend destructive manual AWS CLI commands, or ignore critical project-specific constraints like unprivileged container ports and OIDC auth flows.
+
+Furthermore, automatically writing instruction files into user repositories carries a high risk of clobbering a team's existing, carefully crafted agent prompts.
+
+## Decision Drivers
+
+* **Hallucination Mitigation:** Provide structured, deterministic instructions to IDE AI assistants to ensure they generate valid Terraform and safe workflows.
+* **Non-Destructive Integration:** Guarantee that existing `.cursorrules`, `CLAUDE.md`, or shared workspace instruction files are never accidentally overwritten or destroyed.
+* **Multi-Tool Support:** Support the highly fragmented landscape of AI coding tools without forcing users into a specific IDE.
+
+## Considered Options
+
+1. **Single Global Instruction File:** Only support `.cursorrules` (rejected as too narrow for modern multi-tool teams).
+2. **Blind Overwrite of Agent Files:** Replace existing AI rule files with `deploy-stack` defaults (rejected due to the unacceptable risk of destroying user configuration).
+3. **Isolated Rule Files + Delimited Block Injection (`sync-ai`):** Create dedicated files where supported (e.g., `deploy-stack.mdc`), and safely inject delimited, managed markdown blocks into existing shared instruction files where necessary.
+
+## Decision Outcome
+
+**Chosen Option:** Build a dedicated `npx deploy-stack sync-ai` command and a non-destructive auto-injection engine.
+
+### Supported Targets
+The engine intelligently maps instructions to the following environments:
+* **Cursor:** `.cursor/rules/deploy-stack.mdc`
+* **Roo Code / Roo-Cline:** `.roo/rules/deploy-stack.md`
+* **Trae:** `.trae/rules/project_rules.md` (managed block injection)
+* **Continue:** `.prompts/deploy-stack.prompt`
+* **Windsurf:** `.windsurfrules` (managed block injection)
+* **GitHub Copilot:** `.github/copilot-instructions.md` (managed block injection)
+* **Claude Code:** `CLAUDE.md` (managed block injection)
+* **Goose:** `.goosehints`
+* **Aider:** `.aider.conf.yml` / `.aider.model.settings.yml`
+
+### Positive Consequences
+* Dramatically reduces AI-induced infrastructure errors and dangerous AWS CLI recommendations.
+* Safe, idempotent execution allows teams to run `npx deploy-stack sync-ai` whenever their architecture parameters (like AWS region or ports) change, without fear of losing their own prompts.
+
+### Negative Consequences
+* Requires ongoing maintenance of parser logic and block delimiters as AI coding assistant vendors rapidly change their configuration file specifications.

package/docs/examples.md

@@ -20,6 +20,7 @@ These repositories demonstrate how `deploy-stack` handles various frameworks and
 
 ### Backend APIs & Monoliths
 * **[Express.js API](https://github.com/anton-codes-iac/deploy-stack-express-example):** A standard Node.js backend setup.
+* **[NestJS API](https://github.com/anton-codes-iac/deploy-stack-nest-example):** A robust NestJS architecture utilizing AST code-patching and highly optimized multi-stage TypeScript builds.
 * **[Python FastAPI](https://github.com/anton-codes-iac/deploy-stack-fastapi-example):** A Python API demonstrating unprivileged port mapping.
 * **[Ruby on Rails](https://github.com/anton-codes-iac/deploy-stack-rails-example):** A production Rails 7+ setup featuring an auto-provisioned PostgreSQL database and secure `.auto.tfvars` Master Key injection.
 * **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
@@ -35,4 +36,6 @@ In addition to standalone reference repositories, `deploy-stack` provides native
 * **[nuxt-deploy-stack](https://www.npmjs.com/package/nuxt-deploy-stack):** Nitro-optimized deployment integration for Nuxt 3 applications.
 * **[vite-plugin-deploy-stack](https://www.npmjs.com/package/vite-plugin-deploy-stack):** Zero-config Vite build plugin for single-page applications.
 * **[svelte-adapter-deploy-stack](https://www.npmjs.com/package/svelte-adapter-deploy-stack):** Native SvelteKit adapter producing optimized Fargate container builds.
-* **[cookiecutter-django-deploy-stack](https://github.com/anton-codes-iac/cookiecutter-django-deploy-stack):** Community Django starter listed on [Django Packages](https://djangopackages.org/packages/p/cookiecutter-django-deploy-stack/) with built-in Fargate and managed RDS scaffolding.
+* **[nest-deploy-stack](https://www.npmjs.com/package/nest-deploy-stack):** Native Angular DevKit schematic for NestJS, installable via `nest add`.
+* **[cookiecutter-django-deploy-stack](https://github.com/anton-codes-iac/cookiecutter-django-deploy-stack):** Community Django starter listed on Django Packages.
+* **[cookiecutter-fastapi-deploy-stack](https://github.com/anton-codes-iac/cookiecutter-fastapi-deploy-stack):** Instant scaffolding for modern, async FastAPI deployments.

package/docs/frameworks.md

@@ -0,0 +1,34 @@
+# 🧩 Framework Support & Quirks
+
+`deploy-stack` is designed to be as "zero-config" as possible. However, because different frameworks have unique internal architectures (especially around network binding and build outputs), a few frameworks require minor application-level tweaks to run securely in a Dockerized AWS Fargate environment.
+
+## The 3-Tier Support Philosophy
+
+We handle framework requirements using a 3-tier strategy so you are never left guessing why a deployment failed:
+
+1. **Zero-Touch Plugins (Tier 1):** If you use one of our ecosystem plugins (e.g., `nest add nest-deploy-stack` or `cookiecutter-django-deploy-stack`), your code is automatically patched and configured. Zero manual intervention required.
+2. **Intelligent CLI Pre-flight (Tier 2):** If you run the standalone `deploy-stack` CLI against a raw repository, the CLI statically analyzes your code. If it detects a missing production requirement (like a localhost binding), it will flag it inline in your terminal with the exact copy-paste fix.
+3. **In-Repo Docs (Tier 3):** The generated `DEPLOYMENT.md` file always contains a framework-specific checklist before you push to CI/CD.
+
+---
+
+## 🛠️ Framework Requirements Cheat Sheet
+
+| Framework | What `deploy-stack` Automates | Application Code Requirement | Zero-Click Starter / Plugin |
+|---|---|---|---|
+| **Next.js** | Multi-stage Dockerfile, CloudFront edge routing, `vercel.json` parsing | `output: 'standalone'` must be set in `next.config.js` | Built-in CLI detection |
+| **NestJS** | Multi-stage TypeScript build (`dist/`), unprivileged Node runtime | `await app.listen(port, '0.0.0.0')` in `src/main.ts` | `nest-deploy-stack` (`nest add`) |
+| **FastAPI** | Alpine Python container, Uvicorn CLI args, unprivileged port mapping | None (0.0.0.0 set via Docker CMD) | `cookiecutter-fastapi-deploy-stack` |
+| **Django** | Gunicorn WSGI adapter, Celery worker topologies, RDS bindings | None (0.0.0.0 set via Docker CMD) | `cookiecutter-django-deploy-stack` |
+| **Ruby on Rails** | Puma multi-threading adapter, `.auto.tfvars` Master Key injection | None (0.0.0.0 set via Docker CMD) | *Coming soon* |
+| **Nuxt 3** | Nitro-optimized Node output | None (`NITRO_HOST=0.0.0.0` injected automatically) | `nuxt-deploy-stack` |
+| **SvelteKit** | Node adapter conversion | None (`HOST=0.0.0.0` injected automatically) | `svelte-adapter-deploy-stack` |
+| **Static Sites** *(Vite, Astro, React)* | Output folder detection (`dist/`, `build/`), Nginx routing | None | `vite-plugin-deploy-stack` |
+
+## ⚠️ The Golden Rule: 0.0.0.0 vs Localhost
+
+The most common reason a newly deployed container fails its ALB health check is network binding. 
+
+In local development, frameworks bind to `localhost` (or `127.0.0.1`) for security. However, inside a Docker container on AWS ECS, binding to `localhost` means the web server only listens to internal container traffic. The AWS Application Load Balancer (ALB) trying to route traffic from the outside world will hit a closed port, resulting in a `502 Bad Gateway` or `503 Service Temporarily Unavailable`.
+
+**Always ensure your application explicitly binds to `0.0.0.0`.**

package/docs/testing-strategy.md

@@ -0,0 +1,23 @@
+# deploy-stack Testing Strategy
+
+To ensure zero regressions in infrastructure generation and safe local execution, `deploy-stack` relies on a multi-layered testing strategy split between fast local snapshots and rigid CI/CD validation.
+
+## 1. Unit & Argument Testing
+We use pure Node.js unit tests (via Vitest) to validate the CLI argument parser (`src/core/parser.js`). This ensures that flags (like `--headless` or `--no-telemetry`) are routed correctly and never hijack positional arguments like file paths.
+
+## 2. Infrastructure Snapshot Harness (The Static Contract)
+Because `deploy-stack` generates highly dynamic Terraform (`.tf`), GitHub Actions (`.yml`), and `Dockerfile` configurations, we use **Vitest Snapshots** to lock in the expected text outputs. 
+* **The Matrix:** The test suite generates dummy projects across 11 architectural topologies (including Django, Rails, Go, Nuxt, Next.js, SvelteKit, and Vercel/Heroku migrations).
+* **Negative Testing:** The suite explicitly checks for the *absence* of files (e.g., ensuring `database.tf` or `worker.tf` are not generated for static sites).
+* **Updating Snapshots:** If a template change is intentional, developers must run `npm run test:update` to overwrite the baseline `__snapshots__`.
+
+## 3. External API Mocking
+To ensure tests run sub-second and deterministically without requiring real AWS credentials, we intercept network boundaries:
+* **AWS Secrets Manager:** `tests/secrets.test.js` uses Vitest's `vi.hoisted()` and `vi.mock()` to intercept `@aws-sdk/client-secrets-manager`. This verifies the CLI correctly formats payloads and handles network exceptions (like `ResourceNotFoundException`) completely offline.
+* **Telemetry:** PostHog tracking is mocked to prevent test executions from polluting production analytics.
+
+## 4. Continuous Integration & Execution Validation (CI)
+While Vitest proves the CLI generates the *correct* files, GitHub Actions proves those files *actually work*. All tests are strictly gated via `.github/workflows/test.yml`.
+* **Phase 1 (Generation):** Vitest runs unit and snapshot tests to verify the CLI contract.
+* **Phase 2 (Static Application Security Testing - SAST):** The CI pipeline runs `trivy config` against the generated `Dockerfile` and Terraform snapshots to guarantee they remain compliant with strict security policies.
+* **Phase 3 (IaC Validation):** The CI pipeline runs `tflint` and `terraform validate` against the snapshots to ensure HashiCorp's compiler accepts the generated syntax before a release is cut.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deploy-stack",
-  "version": "0.17.7",
+  "version": "0.17.9",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"
@@ -10,7 +10,9 @@
     "deploy-stack": "bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:update": "vitest run -u"
   },
   "author": "anton-codes-iac",
   "repository": {
@@ -48,5 +50,8 @@
     "dotenv": "17.4.2",
     "js-yaml": "5.4.1",
     "picocolors": "1.1.1"
+  },
+  "devDependencies": {
+    "vitest": "5.0.0"
   }
 }

package/src/commands/init.js

@@ -10,7 +10,8 @@ import {
     parseVercelConfig,
     analyzeNextConfig,
     analyzeSvelteConfig,
-    analyzeAstroConfig
+    analyzeAstroConfig,
+    analyzeNestApp
 } from '../utils/detector.js';
 import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 import { getFrameworkWarning } from '../utils/warnings.js';
@@ -74,7 +75,14 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
     }
 
     // 4. Framework Migration Checks (Vercel Escape Hatch)
-    if (config.framework === 'nextjs') {
+    if (config.framework === 'nestjs') {
+        const nestAnalysis = analyzeNestApp(dirConfig.targetDir);
+        if (nestAnalysis.hasMain && !nestAnalysis.listensOnAllInterfaces) {
+            log.warn(color.yellow(`⚠️  NestJS must listen on 0.0.0.0 to receive traffic in AWS Fargate.`));
+            console.log(color.cyan(`   In ${nestAnalysis.filePath}, update your bootstrap:`));
+            console.log(color.green(`   await app.listen(process.env.PORT ?? 3000, '0.0.0.0');\n`));
+        }
+    } else if (config.framework === 'nextjs') {
         const nextConfig = analyzeNextConfig(dirConfig.targetDir);
         if (nextConfig.hasConfig && !nextConfig.isStandalone) {
             log.warn(color.yellow('⚠️ Next.js config is missing "output: \'standalone\'".'));

package/src/core/parser.js

@@ -0,0 +1,43 @@
+export function parseCliArgs(processArgs) {
+    // 1. Extract telemetry flag safely
+    const hasNoTelemetry = processArgs.some(arg => arg === '--no-telemetry' || arg.startsWith('--no-telemetry='));
+
+    // 2. Filter out telemetry flag
+    const args = processArgs.filter(arg => arg !== '--no-telemetry' && !arg.startsWith('--no-telemetry='));
+
+    // 3. Isolate positional commands
+    const positionalArgs = args.filter(arg => !arg.startsWith('--'));
+    const baseCommand = positionalArgs.length > 0 ? positionalArgs.slice(0, 2).join(' ') : 'init';
+
+    // 4. Parse execution flags
+    const isHeadless = args.includes('--headless');
+    const isDryRun = args.includes('--dry-run');
+
+    const getFlag = (flagName) => {
+        const match = args.find(a => a === `--${flagName}` || a.startsWith(`--${flagName}=`));
+        if (match === `--${flagName}`) return true;
+        return match ? match.split('=')[1] : undefined;
+    };
+
+    const headlessOptions = isHeadless ? {
+        dir: getFlag('dir'),
+        framework: getFlag('framework'),
+        region: getFlag('region'),
+        port: getFlag('port'),
+        size: getFlag('size'),
+        healthCheckPath: getFlag('healthCheckPath'),
+        desiredCount: getFlag('desiredCount'),
+        branch: getFlag('branch'),
+        needsDatabase: getFlag('needsDatabase'),
+        enablePrPreviews: getFlag('enablePrPreviews')
+    } : {};
+
+    return {
+        hasNoTelemetry,
+        positionalArgs,
+        baseCommand,
+        isHeadless,
+        isDryRun,
+        headlessOptions
+    };
+}

package/src/utils/detector.js

@@ -17,6 +17,7 @@ export function detectFramework(targetDir) {
             const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
 
             // Fullstack / API
+            if (deps['@nestjs/core']) return { id: 'nestjs', name: 'NestJS' };
             if (deps['next']) return { id: 'nextjs', name: 'Next.js' };
             if (deps['nuxt']) return { id: 'nuxt', name: 'Nuxt 3 (SSR)' };
             if (deps['express']) return { id: 'node', name: 'Node.js / Express' };
@@ -192,4 +193,25 @@ export function analyzeAstroConfig(targetDir) {
     else if (content.includes('@astrojs/node')) adapter = 'node';
 
     return { hasConfig: true, adapter };
+}
+
+// Checks if a NestJS app explicitly listens on 0.0.0.0 for Docker networking
+export function analyzeNestApp(targetDir) {
+    const mainTsPath = path.join(targetDir, 'src', 'main.ts');
+    const mainJsPath = path.join(targetDir, 'src', 'main.js');
+
+    const filePath = fsSync.existsSync(mainTsPath) ? mainTsPath : (fsSync.existsSync(mainJsPath) ? mainJsPath : null);
+    if (!filePath) return { hasMain: false, listensOnAllInterfaces: true };
+
+    try {
+        const content = fsSync.readFileSync(filePath, 'utf-8');
+        const hasHostBinding = content.includes('0.0.0.0');
+        return {
+            hasMain: true,
+            listensOnAllInterfaces: hasHostBinding,
+            filePath: path.relative(targetDir, filePath)
+        };
+    } catch {
+        return { hasMain: false, listensOnAllInterfaces: true };
+    }
 }

package/src/utils/generator.js

@@ -266,6 +266,7 @@ Thumbs.db
 
         const presets = {
             node: '\n# Node.js\nnode_modules/\nnpm-debug.log\nyarn-error.log\n',
+            nestjs: '\n# NestJS\nnode_modules/\ndist/\nnpm-debug.log\n',
             nextjs: '\n# Next.js\nnode_modules/\n.next/\nout/\nbuild/\nnext-env.d.ts\n',
             nuxt: '\n# Nuxt 3\nnode_modules/\n.nuxt/\n.output/\ndist/\n',
             python: '\n# Python\n__pycache__/\n*.py[cod]\n*$py.class\nvenv/\nenv/\n.venv/\n.pytest_cache/\n',

package/src/utils/prompts.js

@@ -58,6 +58,7 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
             message: 'Which framework preset should we configure?',
             options: [
                 { value: 'node', label: 'Node.js / Express' },
+                { value: 'nestjs', label: 'NestJS' },
                 { value: 'nextjs', label: 'Next.js (Standalone)' },
                 { value: 'nuxt', label: 'Nuxt 3 (SSR)' },
                 { value: 'svelte', label: 'SvelteKit (SSR)' },
@@ -90,7 +91,7 @@ export async function getProjectConfig(isHeadless, headlessOptions, targetDir, d
     } catch (e) { }
 
     let needsDatabase = false;
-    const isBackendFramework = ['node', 'nextjs', 'nuxt', 'python', 'django', 'rails', 'go'].includes(finalFramework);
+    const isBackendFramework = ['node', 'nestjs', 'nextjs', 'nuxt', 'python', 'django', 'rails', 'go'].includes(finalFramework);
 
     if (isBackendFramework) {
         const dbChoice = await confirm({

package/src/utils/warnings.js

@@ -8,6 +8,13 @@ export function getFrameworkWarning(frameworkId) {
                 color.yellow('\n    You must modify your next.config file and create a health check route before deploying.') +
                 color.yellow('\n    See the "Critical Application Prerequisites" section in your README.md for copy-paste code.\n\n')
             );
+        case 'nestjs':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: NESTJS SETUP REQUIRED ')) +
+                color.yellow('\n    You must ensure your app binds to 0.0.0.0 to receive traffic in AWS Fargate.') +
+                color.yellow('\n    In src/main.ts, update your bootstrap function to:') +
+                color.green('\n    await app.listen(process.env.PORT ?? 3000, \'0.0.0.0\');\n\n')
+            );
         case 'node':
             return (
                 color.bgYellow(color.black(' ⚠️  IMPORTANT: NODE.JS SETUP REQUIRED ')) +

package/templates/README.md

@@ -73,6 +73,7 @@ AWS constantly pings your container to ensure it is alive. If you configured a c
 Make sure your app returns a `200 OK` at your configured path:
 
 * **Next.js (App Router):** Create `app/api/health/route.ts` returning a 200 response.
+* **NestJS:** No action required if your health check path is `/` (the default `AppController` handles this). If you configured a custom path, create a specific controller for it returning a 200 response.
 * **Express.js:** Add `app.get('/api/health', (req, res) => res.sendStatus(200));`
 * **FastAPI/Python:** Add `@app.get("/api/health")` returning a 200 status.
 * **Ruby on Rails:** Rails 7.1+ includes a default `/up` health check. Ensure `Rails.application.config.force_ssl = true` isn't blocking HTTP health checks from the ALB.
@@ -101,6 +102,7 @@ export default nextConfig;
 When running inside a Docker container, your server must bind to all network interfaces (`0.0.0.0`), not just `localhost` or `127.0.0.1`. If you bind to localhost, the AWS Load Balancer will not be able to route traffic to your application.
 
 Make sure your app is configured correctly:
+* **NestJS:** Update `src/main.ts` to `await app.listen(process.env.PORT ?? 3000, '0.0.0.0');`
 * **Express.js:** `app.listen(port, '0.0.0.0', () => ...)`
 * **FastAPI:** `uvicorn.run(app, host="0.0.0.0", port=8000)`
 * **Ruby on Rails:** Bound automatically by the CLI's Puma command (`-b tcp://0.0.0.0:{{PORT}}`).

package/templates/docker/nestjs.Dockerfile

@@ -0,0 +1,21 @@
+# --- Stage 1: Build ---
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# --- Stage 2: Production ---
+FROM node:22-alpine
+# DevSecOps: Patch Alpine OS and update npm
+RUN apk update && apk upgrade --no-cache && npm install -g npm@latest
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --chown=node:node package*.json ./
+RUN npm ci --omit=dev
+COPY --chown=node:node --from=builder /app/dist ./dist
+USER node
+# Expose the port defined by Terraform
+EXPOSE {{PORT}}
+CMD ["node", "dist/main.js"]

package/templates/docker/python.Dockerfile

@@ -11,7 +11,7 @@ RUN addgroup -S appuser && \
     adduser -S appuser -G appuser -D -s /bin/sh
 
 # Install runtime libraries and temporary build tools
-RUN apk update && \
+RUN apk update && apk upgrade --no-cache && \
     apk add --no-cache libpq && \
     apk add --no-cache --virtual .build-deps gcc musl-dev postgresql-dev