deploy-stack 0.18.0 → 0.18.2

package/{docs → apps/docs/src/content/docs/guides}/examples.md

@@ -1,16 +1,22 @@
-# 📦 Reference Implementations & Examples
+---
+title: Reference Implementations & Examples
+description: Example repositories demonstrating how deploy-stack handles frameworks and architectural patterns, plus ecosystem plugins and starters.
+---
 
 These repositories demonstrate how `deploy-stack` handles various frameworks and architectural patterns. Each example includes the auto-generated Terraform, GitHub Actions, and container configurations.
 
-### Featured Migrations
+## Featured migrations
+
 * **[Heroku to AWS Migration (Django)](https://github.com/anton-codes-iac/deploy-stack-heroku-django-example):** A classic Heroku-style monolith migrated via the Procfile Importer, demonstrating a multi-container Web and Celery Worker architecture deployed from a single codebase.
 * **[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.
 * **[Docker Compose to AWS Migration](https://github.com/anton-codes-iac/deploy-stack-docker-compose-example):** Demonstrates automatic translation of local `docker-compose.yml` sidecars (like Redis) into a multi-container AWS ECS Task Definition communicating over `localhost`.
 
-### DevSecOps & Security Architectures
+## DevSecOps & security architectures
+
 * **[Zero-Secret AWS Secrets Manager Injection](https://github.com/anton-codes-iac/deploy-stack-secrets-example):** A production-grade Node.js architecture demonstrating zero-plaintext secret injection. It pushes local `.env` variables directly to AWS and maps them into ECS memory at runtime, exposing a live endpoint querying GitHub's API.
 
-### Frontend & Fullstack Frameworks
+## Frontend & fullstack frameworks
+
 * **[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.
 * **[Vite / React SPA](https://github.com/anton-codes-iac/deploy-stack-vite-example):** Demonstrates SPA routing and `dist/` auto-detection.
 * **[Create React App](https://github.com/anton-codes-iac/deploy-stack-cra-example):** Validates backward compatibility with legacy Webpack pipelines and `build/` auto-detection.
@@ -18,17 +24,18 @@ These repositories demonstrate how `deploy-stack` handles various frameworks and
 * **[SvelteKit Application](https://github.com/anton-codes-iac/deploy-stack-svelte-example):** Demonstrates static adapter integration and custom output folder detection.
 * **[Nuxt 3 (SSR)](https://github.com/anton-codes-iac/deploy-stack-nuxt-example):** Demonstrates a fully server-side rendered Nuxt application using Nitro's optimized Node output.
 
-### Backend APIs & Monoliths
+## 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.
+* **[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 `RAILS_MASTER_KEY` string-literal injection into the initial Secrets Manager placeholder.
 * **[Django / Python](https://github.com/anton-codes-iac/deploy-stack-django-example):** A secure Gunicorn/WSGI implementation with PostgreSQL and unprivileged container adapters.
 * **[Go / Fiber](https://github.com/anton-codes-iac/deploy-stack-go-example):** A distroless, compiled Go binary deployment demonstrating ultra-low memory footprints and instant boot times.
 
 ---
 
-## 🧩 Ecosystem Plugins & Starters
+## Ecosystem plugins & starters
 
 In addition to standalone reference repositories, `deploy-stack` provides native integrations that hook directly into framework build pipelines and community template engines:
 
@@ -38,4 +45,4 @@ In addition to standalone reference repositories, `deploy-stack` provides native
 * **[svelte-adapter-deploy-stack](https://www.npmjs.com/package/svelte-adapter-deploy-stack):** Native SvelteKit adapter producing optimized Fargate container builds.
 * **[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.
+* **[cookiecutter-fastapi-deploy-stack](https://github.com/anton-codes-iac/cookiecutter-fastapi-deploy-stack):** Instant scaffolding for modern, async FastAPI deployments.

package/apps/docs/src/content/docs/guides/frameworks.md

@@ -0,0 +1,88 @@
+---
+title: Supported Frameworks & Detection
+description: Which frameworks deploy-stack detects, the signals it looks for, the valid --framework ids, and per-framework requirements.
+sidebar:
+  order: 2
+---
+
+`deploy-stack` is designed to be as "zero-config" as possible. During setup, it inspects your repo (`src/utils/detector.js`) and preselects a framework preset. 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.
+
+## Detection precedence
+
+Checks run top-down; the first match wins.
+
+| # | Signal | Preset (`id` / name) |
+| - | ------ | -------------------- |
+| 1 | `package.json` depends on `@nestjs/core` | `nestjs` / NestJS |
+| 2 | `package.json` depends on `next` | `nextjs` / Next.js |
+| 3 | `package.json` depends on `nuxt` | `nuxt` / Nuxt 3 (SSR) |
+| 4 | `package.json` depends on `express` | `node` / Node.js / Express |
+| 5 | `package.json` depends on `@sveltejs/kit` | `svelte` / SvelteKit SSR |
+| 6 | `package.json` depends on `react-scripts`, `gatsby`, `astro`, `vite`, `@vue/cli-service`, or `@angular/cli` | `static` / (that generator) |
+| 7 | `requirements.txt` contains `fastapi` | `python` / Python FastAPI |
+| 8 | `requirements.txt` contains `django`, or `manage.py` exists | `django` / Django |
+| 9 | `Gemfile` contains a `rails` gem | `rails` / Ruby on Rails |
+| 10 | `go.mod` exists | `go` / Go |
+| 11 | No match | No preset — you pick from the interactive list |
+
+Notes from the actual code:
+
+- Both `dependencies` and `devDependencies` are searched, so a framework listed only under dev dependencies still matches.
+- A malformed `package.json` or `vercel.json` is silently ignored (no match), never fatal.
+- An empty `vercel.json` (no `redirects`, `headers`, or `rewrites`) is treated as absent.
+
+## Valid `--framework` ids
+
+The interactive picker and the headless `--framework` flag accept: `node`, `nestjs`, `nextjs`, `nuxt`, `svelte`, `python`, `django`, `rails`, `go`, `static`. In headless mode with no `--framework`, detection applies and anything unmatched falls back to `static`.
+
+## Per-framework defaults
+
+- **Static build directory** (`buildDir`): SvelteKit `build`, Gatsby `public`, everything else (`astro`, `vite`, Vue, Angular) `dist`. This selects the folder the generated `Dockerfile` serves.
+- **Default container port**: `8080` for `static` and `go`, `8000` for `python` and `django`, `3000` for everything else (headless uses `8080` only when `--framework=static`, else `3000`).
+- **Database prompt**: offered only for backend presets (`node`, `nestjs`, `nextjs`, `nuxt`, `python`, `django`, `rails`, `go`).
+
+## 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 adapter, `RAILS_MASTER_KEY` injection into Secrets Manager placeholder, Kamal Dockerfile replaced with 0-CVE Alpine build | None (0.0.0.0 set via Docker CMD) | `rails-template-deploy-stack` |
+| **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` |
+
+## Post-detection checks
+
+After detection, setup validates framework-specific requirements and warns before generating:
+
+- **NestJS**: `src/main.ts` (or `main.js`) must bind `0.0.0.0`, e.g. `await app.listen(process.env.PORT ?? 3000, '0.0.0.0')`.
+- **Next.js**: config must set `output: 'standalone'` (`.js/.mjs/.cjs/.ts` checked).
+- **SvelteKit**: adapter must not be `@sveltejs/adapter-vercel` or `adapter-auto`.
+- **Astro**: adapter must not be `@astrojs/vercel`.
+
+Alongside detection, setup also auto-detects `Procfile` (web/worker commands), `vercel.json` edge rules (translated to ALB listener rules), and `docker-compose.yml` services (port override plus sidecars).
+
+## 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`.**
+
+## See also
+
+- [Dockerfiles & the container contract](/guides/dockerfiles/) for what your app must do at runtime.
+- [Headless Mode](/guides/headless/) for automating framework selection.
+- [Examples](/examples/) for reference repositories and ecosystem plugins per framework.

package/{docs → apps/docs/src/content/docs}/guides/headless.md

@@ -1,4 +1,7 @@
-# Headless Mode & Automation Guide
+---
+title: "Headless Mode & Automation Guide"
+description: "The deploy-stack CLI is designed to be fully automatable for CI/CD pipelines, custom scripts, Cookiecutters, and framework plugins (like vite-plugin-deploy-stac"
+---
 
 The `deploy-stack` CLI is designed to be fully automatable for CI/CD pipelines, custom scripts, Cookiecutters, and framework plugins (like `vite-plugin-deploy-stack`). 
 

package/apps/docs/src/content/docs/guides/rerun-init.md

@@ -0,0 +1,43 @@
+---
+title: Re-running Init Safely
+description: What happens when setup finds existing files — backups, regeneration, and how to recover.
+sidebar:
+  order: 5
+---
+
+Re-running `npx deploy-stack` to change region, size, or framework is safe and predictable: setup never merges with your existing generated files. It backs them up, regenerates from scratch, and tells you exactly what moved.
+
+## The conflict prompt
+
+When setup finds any of `terraform/`, `Dockerfile`, or `.github/workflows/deploy.yml` in the target directory (`src/utils/backup.js`), it lists the conflicts and offers two choices:
+
+- **Backup & Regenerate** — each conflicting path is renamed with a timestamp suffix (e.g. `terraform.bak.1726771200000`), then fresh files are generated.
+- **Cancel** — exits immediately with no changes.
+
+In `--headless` mode there is no prompt: existing files are backed up automatically. Either way, nothing is ever merged or partially overwritten.
+
+## Backups stay local
+
+After backing up, setup appends a `# deploy-stack backups` block (`*.bak.*`) to `.gitignore` (creating the file if needed), so backup clutter never reaches GitHub. To recover a previous configuration, compare with `diff -r terraform.bak.<timestamp> terraform/` and copy back what you need — then delete the `.bak.*` directory when you are satisfied. (`npx deploy-stack eject` removes all `*.bak.*` files as part of decoupling.)
+
+## What regeneration touches
+
+`src/utils/generator.js` writes a fixed file set and handles pre-existing files explicitly:
+
+- `terraform/*.tf`, `Dockerfile`, `.github/workflows/deploy.yml`, plus `preview.yml`/`teardown.yml` only when PR previews are enabled.
+- `terraform/secret_keys.json` is reset to `[]` — re-push secrets afterward with `npx deploy-stack secrets push`.
+- If your repo already has a `README.md`, it is kept and gets a short Deployment pointer appended; the generated guide goes to `DEPLOYMENT.md` instead.
+- Existing `.gitignore` / `.dockerignore` files are preserved with only the deploy-stack entries appended (Terraform state paths, `.env`); missing ones are created with framework-appropriate presets.
+- **Rails only:** if `ci.yml` or `dependabot.yml` exist, setup asks whether to disable them by renaming to `.bak` (default CI usually crashes without a database service); in headless mode they are disabled automatically.
+
+## Suggested workflow
+
+1. Commit your work before re-running, so `git status` shows exactly what regeneration changed.
+2. Re-run, review the diff (`git diff`, plus `diff -r` against the `.bak` copies for untracked files like `terraform/` internals).
+3. Run `npx deploy-stack apply` to converge AWS with the new configuration.
+4. Delete the `.bak.<timestamp>` copies once the new infrastructure is verified.
+
+## See also
+
+- [apply](/cli/apply/) for converging AWS after regeneration.
+- [eject](/cli/eject/) for what happens to backups on decoupling.

package/{docs → apps/docs/src/content/docs}/guides/secrets-management.md

@@ -1,4 +1,7 @@
-# Secrets Management in deploy-stack
+---
+title: "Secrets Management in deploy-stack"
+description: "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 Man"
+---
 
 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.
 

package/apps/docs/src/content/docs/index.mdx

@@ -0,0 +1,36 @@
+---
+title: deploy-stack docs
+description: Official developer portal for deploy-stack — concepts, guides, and CLI reference.
+template: splash
+hero:
+  tagline: Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.
+  actions:
+    - text: Read the guides
+      link: /guides/headless/
+      icon: right-arrow
+    - text: CLI reference
+      link: /cli/init/
+      variant: minimal
+---
+
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+## Start here
+
+<CardGrid stagger>
+  <LinkCard 
+    title="Deployment Guides" 
+    description="Learn how to deploy Rails, NestJS, and SvelteKit applications." 
+    href="/guides/aws-credentials/" 
+  />
+  <LinkCard 
+    title="CLI Reference" 
+    description="Explore the full list of commands and headless flags." 
+    href="/cli/init/" 
+  />
+  <LinkCard 
+    title="Architecture Decisions" 
+    description="Read the ADRs detailing our infrastructure choices." 
+    href="/adrs/001-initial-architecture/" 
+  />
+</CardGrid>

package/{docs/migration → apps/docs/src/content/docs/migrations}/astro-vercel-to-aws.md

@@ -1,4 +1,7 @@
-# Migrating Astro from Vercel to AWS Fargate
+---
+title: "Migrating Astro from Vercel to AWS Fargate"
+description: "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 proprie"
+---
 
 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. 
 

package/{docs/migration → apps/docs/src/content/docs/migrations}/heroku-procfile-to-aws.md

@@ -1,4 +1,7 @@
-# Migrating from Heroku to AWS (Procfile Support)
+---
+title: "Migrating from Heroku to AWS (Procfile Support)"
+description: "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 C"
+---
 
 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). 
 

package/{docs/migration → apps/docs/src/content/docs/migrations}/nextjs-vercel-to-aws.md

@@ -1,4 +1,7 @@
-# Migrating Next.js from Vercel to AWS Fargate
+---
+title: "Migrating Next.js from Vercel to AWS Fargate"
+description: "If you are seeing a warning from deploy-stack about output: 'standalone', your Next.js configuration is missing a crucial setting required for containerized env"
+---
 
 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.
 

package/{docs/migration → apps/docs/src/content/docs/migrations}/sveltekit-vercel-to-aws.md

@@ -1,4 +1,7 @@
-# Migrating SvelteKit from Vercel to AWS Fargate
+---
+title: "Migrating SvelteKit from Vercel to AWS Fargate"
+description: "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 Verc"
+---
 
 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`.
 

package/{docs/ROADMAP.md → apps/docs/src/content/docs/roadmap.md}

@@ -1,4 +1,7 @@
-# 🗺️ deploy-stack Roadmap
+---
+title: Roadmap
+description: Where deploy-stack has been and what comes next — completed phases and the current platform-hardening milestone.
+---
 
 ### Phase 1–3: The Core Engine (Completed)
 - [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB generation, CI/CD, and Secrets sync.
@@ -40,4 +43,4 @@
 - [ ] **Documentation Hub:** Launch a dedicated Astro Starlight documentation site featuring interactive architecture diagrams, core concept deep-dives, and detailed CLI references.
 - [ ] **Continuous Infrastructure Validation:** Implement a GitHub Actions matrix pipeline that automatically generates, compiles, and validates Terraform syntax (`terraform validate`, `tflint`) against all supported frameworks on every commit.
 - [ ] **Automated Security & Compliance Proving:** Integrate DevSecOps infrastructure scanning (`trivy` or `tfsec`) directly into the CI pipeline to mathematically guarantee zero-CVE, secure-by-default AWS provisioning.
-- [ ] **Integration Stability Suite:** Expand Vitest coverage to enforce strict contracts for headless execution flags (`--preconfigured`, `--headless`), ensuring seamless interoperability with third-party scaffolding tools.
+- [ ] **Integration Stability Suite:** Expand Vitest coverage to enforce strict contracts for headless execution flags (`--preconfigured`, `--headless`), ensuring seamless interoperability with third-party scaffolding tools.

package/{docs → apps/docs/src/content/docs}/testing-strategy.md

@@ -1,27 +1,31 @@
-# deploy-stack Testing Strategy
+---
+title: Testing Strategy
+description: How deploy-stack prevents regressions — unit tests, snapshot harness, API mocking, and CI validation.
+---
 
 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
+## 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.
 
-## 1.5. Ecosystem Integration Contracts
+## 1.5. Ecosystem integration contracts
 Because `deploy-stack` acts as the underlying engine for ecosystem wrappers (e.g., `nest-deploy-stack`, `cookiecutter-fastapi`), we strictly test execution flags that bypass interactive prompts:
 * **Headless Validation:** Vitest specifically asserts that when `--headless` and `--preconfigured` are passed, the CLI never initializes the `inquirer` prompt module and never throws interactive warnings. This guarantees stability for automated ecosystem integrations.
 
-## 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. 
+## 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
+## 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)
+## 4. Continuous integration & execution validation (CI)
 While Vitest proves the CLI generates the *correct* files, GitHub Actions proves those files *actually work*. Unit and snapshot tests are gated via `.github/workflows/test.yml`; live template compilation is gated via `.github/workflows/iac-validation.yml`.
 * **Phase 1 (Generation):** Vitest runs unit and snapshot tests to verify the CLI contract.
-* **Phase 2 (Static Application Security Testing - SAST):** CI runs `trivy config` against the generated `Dockerfile` and Terraform snapshots to guarantee they remain compliant with strict security policies.
-* **Phase 3 (IaC Validation):** The `iac-validation` matrix workflow scaffolds all 10 supported frameworks headlessly (`--headless --preconfigured`), then runs `terraform init -backend=false` + `terraform validate`, `tflint`, and a Trivy filesystem scan (fails on HIGH/CRITICAL) — fully offline with no AWS credentials.
+* **Phase 2 (Static Application Security Testing - SAST):** CI runs a pinned Trivy filesystem scan (`aquasecurity/trivy-action` by SHA) against each generated project directory, writing advisory `trivy-fs-results.txt` reports (`HIGH,CRITICAL`, `exit-code: 0`) instead of failing the build.
+* **Phase 3 (IaC Validation):** The `iac-validation` matrix workflow scaffolds all 10 supported frameworks headlessly (`--headless --preconfigured`), then runs `terraform init -backend=false` + `terraform validate`, `tflint`, the advisory filesystem scan, a stripped-Dockerfile `docker build`, and an advisory container-image scan (`trivy-image-results.txt`).
+* **Phase 4 (Release gate):** `.github/workflows/publish.yml` reuses `iac-validation.yml` via `workflow_call` as a `validate` job; `build-and-publish` has `needs: [validate]`, so NPM publishing on release is blocked until the full matrix passes.

package/apps/docs/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/apps/docs/src/custom.css

@@ -0,0 +1,14 @@
+:root {
+    /* Make all base text slightly smaller */
+    --sl-text-base: 0.95rem;
+    --sl-line-height: 1.6;
+
+    /* Shrink the headings */
+    --sl-text-h1: 2.2rem;
+    --sl-text-h2: 1.75rem;
+    --sl-text-h3: 1.35rem;
+
+    /* Tighten the left sidebar padding */
+    --sl-nav-pad-y: 0.25rem;
+    --sl-nav-gap: 0.5rem;
+}

package/apps/docs/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "strictNullChecks": true
+  }
+}

package/bin/cli.js

@@ -35,7 +35,7 @@ if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'push') {
 } else if (positionalArgs[0] === 'sync-ai') {
     syncAi().catch(e => { console.error(e); process.exit(1); });
 } else if (positionalArgs[0] === 'diagnose' || positionalArgs[0] === 'wtf') {
-    runDiagnose().catch(e => { console.error(e); process.exit(1); });
+    runDiagnose(headlessOptions).catch(e => { console.error(e); process.exit(1); });
 } else {
     mainStack({ isHeadless, headlessOptions }).catch(e => { console.error(e); process.exit(1); });
 }

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "deploy-stack",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"
   },
   "type": "module",
+  "workspaces": [
+    "apps/*"
+  ],
   "bin": {
     "deploy-stack": "bin/cli.js"
   },
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:update": "vitest run -u"
+    "test:update": "vitest run -u",
+    "docs:dev": "npm run dev --workspace=apps/docs",
+    "docs:build": "npm run build --workspace=apps/docs"
   },
   "author": "anton-codes-iac",
   "repository": {

package/src/commands/diagnose.js

@@ -35,7 +35,7 @@ export async function runDiagnose(options = {}) {
     const projectName = path.basename(process.cwd());
 
     // Attempt to read the region from the generated Terraform variables
-    let autoRegion = 'us-east-1';
+    let autoRegion = 'us-east-2';
     try {
         const mainTfPath = path.join(process.cwd(), 'terraform', 'main.tf');
         if (fsSync.existsSync(mainTfPath)) {
@@ -48,7 +48,7 @@ export async function runDiagnose(options = {}) {
         // Fallback silently
     }
 
-    const region = options.region || process.env.AWS_REGION || autoRegion;
+    const region = options.region || process.env.AWS_REGION || 'us-east-2';
     const cluster = options.cluster || process.env.ECS_CLUSTER || `${projectName}-cluster`;
     const logGroup = options.logGroup || process.env.ECS_LOG_GROUP || `/ecs/${projectName}`;
 
@@ -57,8 +57,13 @@ export async function runDiagnose(options = {}) {
     const s = spinner();
     s.start('Looking up recent stopped ECS tasks...');
 
-    const ecsClient = options.ecsClient || new ECSClient({ region });
-    const logsClient = options.logsClient || new CloudWatchLogsClient({ region });
+    const ecsClient = (options.ecsClient && typeof options.ecsClient.send === 'function')
+        ? options.ecsClient
+        : new ECSClient({ region });
+
+    const logsClient = (options.logsClient && typeof options.logsClient.send === 'function')
+        ? options.logsClient
+        : new CloudWatchLogsClient({ region });
 
     try {
         const listResp = await ecsClient.send(
@@ -157,12 +162,21 @@ export async function runDiagnose(options = {}) {
         };
     } catch (error) {
         s.stop(color.red('❌ Diagnose failed.'));
-        console.log(color.red(`✖ ${error.message || error}`));
-        console.log(color.dim('Check your AWS credentials and region, then try again.'));
+
+        if (error.name === 'UnrecognizedClientException' || error.name === 'ExpiredTokenException') {
+            console.log(color.yellow('\n⚠️  AWS Session Expired / Invalid Credentials'));
+            console.log(`Run ${color.cyan('aws sso login')} or ${color.cyan('aws configure')} to refresh your credentials.`);
+            console.log(color.blue(`\n📘 Troubleshooting Guide: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/guides/aws-credentials.md')}\n`));
+        } else {
+            console.log(color.red(`✖ ${error.message || error}`));
+            console.log(color.dim('Check your AWS credentials and region, then try again.'));
+        }
+
         trackEvent('diagnose_run', {
             success: false,
             error_code: error.name || 'UNKNOWN',
-            error_message: error.message
+            error_message: error.message,
+            stack_trace: error.name === 'TypeError' ? error.stack : undefined
         });
         await flushTelemetry();
         throw error;

package/src/commands/init.js

@@ -86,19 +86,19 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
         const nextConfig = analyzeNextConfig(dirConfig.targetDir);
         if (nextConfig.hasConfig && !nextConfig.isStandalone) {
             log.warn(color.yellow('⚠️ Next.js config is missing "output: \'standalone\'".'));
-            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/nextjs-vercel-to-aws.md'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/migrations/nextjs-vercel-to-aws.md'));
         }
     } else if (detectedFramework?.name === 'SvelteKit') {
         const svelteConfig = analyzeSvelteConfig(dirConfig.targetDir);
         if (svelteConfig.adapter === 'vercel' || svelteConfig.adapter === 'auto') {
             log.warn(color.yellow('⚠️ SvelteKit is locked into the Vercel/Auto adapter.'));
-            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/sveltekit-vercel-to-aws.md'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/migrations/sveltekit-vercel-to-aws.md'));
         }
     } else if (detectedFramework?.name === 'Astro') {
         const astroConfig = analyzeAstroConfig(dirConfig.targetDir);
         if (astroConfig.adapter === 'vercel') {
             log.warn(color.yellow('⚠️ Astro is locked into the Vercel adapter.'));
-            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/astro-vercel-to-aws.md'));
+            console.log(color.cyan('   Fix it here: https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/migrations/astro-vercel-to-aws.md'));
         }
     }
 
@@ -285,9 +285,9 @@ export async function mainStack({ isHeadless = false, headlessOptions = {} } = {
 
     let docsTip = '';
     if (procfile) {
-        docsTip = `\n  ${color.blue('📘 Read the Heroku Migration Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/migrations/heroku-procfile-to-aws.md')}`;
+        docsTip = `\n  ${color.blue('📘 Read the Heroku Migration Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/migrations/heroku-procfile-to-aws.md')}`;
     } else if (config.needsDatabase) {
-        docsTip = `\n  ${color.blue('📘 Read the Database Connections Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/database-connections.md')}`;
+        docsTip = `\n  ${color.blue('📘 Read the Database Connections Guide:')} ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/guides/database-connections.md')}`;
     }
 
     outro(`${color.green('✅ Templates generated!')} ${color.blue('🛡️ DevSecOps scanning enabled.')}

package/src/commands/secrets.js

@@ -7,20 +7,29 @@ import path from 'path';
 import { trackEvent, flushTelemetry } from '../core/telemetry.js';
 
 export async function pushSecrets(envFilePath, projectName) {
+    // Ensure envFilePath is a valid string, defaulting to '.env' if undefined or an object
+    const resolvedFilePath = (typeof envFilePath === 'string' && envFilePath.trim())
+        ? envFilePath.trim()
+        : '.env';
+
+    const resolvedProjectName = (typeof projectName === 'string' && projectName.trim())
+        ? projectName.trim()
+        : path.basename(process.cwd());
+
     const s = spinner();
     s.start(`Reading ${envFilePath} and pushing to AWS Secrets Manager...`);
 
     try {
         // 1. Read and parse the local .env file
-        const envPath = path.resolve(process.cwd(), envFilePath);
+        const envPath = path.resolve(process.cwd(), resolvedFilePath);
         let envContent;
         try {
             envContent = await fs.readFile(envPath, 'utf-8');
         } catch (fsError) {
             if (fsError.code === 'ENOENT') {
-                throw new Error(`File not found: ${envFilePath}. Please ensure the file exists before pushing.`);
+                throw new Error(`File not found: "${resolvedFilePath}". Please ensure the file exists before pushing.`);
             }
-            throw fsError; // Re-throw if it's a permissions issue
+            throw fsError;
         }
 
         const parsedSecrets = dotenv.parse(envContent);
@@ -62,7 +71,7 @@ export async function pushSecrets(envFilePath, projectName) {
         s.stop(`✅ Successfully pushed ${Object.keys(parsedSecrets).length} secrets to AWS (${targetRegion || 'default region'})!`);
         console.log(color.cyan(`\nUpdated ${keysFilePath}`));
         console.log(color.green('Commit this file and push to GitHub to trigger a deployment with your new variables.'));
-        console.log(color.blue(`\n📘 Learn how secrets reach your app: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/docs/guides/secrets-management.md')}`));
+        console.log(color.blue(`\n📘 Learn how secrets reach your app: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/guides/secrets-management.md')}`));
 
         trackEvent('secrets_pushed', {
             projectName,
@@ -73,19 +82,25 @@ export async function pushSecrets(envFilePath, projectName) {
 
     } catch (error) {
         if (error.name === 'ResourceNotFoundException') {
-            s.stop(color.red(`❌ Secrets Vault "${projectName}-secrets" does not exist in AWS yet.`));
+            s.stop(color.red(`❌ Secrets Vault "${resolvedProjectName}-secrets" does not exist in AWS yet.`));
             console.log(color.yellow('\n💡 Next Step:'));
             console.log(`Run ${color.cyan('npx --yes deploy-stack apply')} first to provision the infrastructure and Secrets Manager vault.`);
-            console.log(`Once applied, run ${color.cyan(`npx deploy-stack secrets push ${envFilePath}`)} to upload your environment variables.\n`);
+            console.log(`Once applied, run ${color.cyan(`npx deploy-stack secrets push ${resolvedFilePath}`)} to upload your environment variables.\n`);
+        } else if (error.name === 'UnrecognizedClientException' || error.name === 'ExpiredTokenException') {
+            s.stop(color.red('❌ AWS session expired or invalid credentials.'));
+            console.log(color.yellow('\n💡 Next Step:'));
+            console.log(`Run ${color.cyan('aws sso login')} or ${color.cyan('aws configure')} to refresh your credentials.`);
+            console.log(color.blue(`\n📘 Troubleshooting Guide: ${color.underline('https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/guides/aws-credentials.md')}\n`));
         } else {
             s.stop(`❌ Failed to push secrets: ${error.message}`);
         }
 
         trackEvent('secrets_pushed', {
-            projectName,
+            projectName: resolvedProjectName,
             success: false,
             error_code: error.name || 'UNKNOWN',
-            error_message: error.message
+            error_message: error.message,
+            stack_trace: error.name === 'TypeError' ? error.stack : undefined
         });
         await flushTelemetry();
         process.exit(1);

package/src/core/telemetry.js

@@ -11,11 +11,13 @@ export function trackEvent(eventName, properties) {
     }
 
     // 2. Hash the project name so it is completely anonymous
-    const rawProjectName = properties.projectName || 'unknown';
+    const eventProps = { ...properties };
+
+    const rawProjectName = eventProps.projectName || 'unknown';
     const anonymousProjectId = crypto.createHash('sha256').update(rawProjectName).digest('hex').substring(0, 16);
 
     // 3. Strip the raw name out of the payload
-    delete properties.projectName;
+    delete eventProps.projectName;
 
     const payload = {
         api_key: POSTHOG_API_KEY,
@@ -25,8 +27,9 @@ export function trackEvent(eventName, properties) {
             os: process.platform,
             node_version: process.version,
             is_ci: Boolean(process.env.CI || process.env.CONTINUOUS_INTEGRATION),
-            cli_command: process.env.CLI_COMMAND || 'unknown',
-            ...properties
+            cli_command: process.env.CLI_COMMAND || process.argv.slice(2).join(' ') || 'unknown',
+            framework: process.env.DEPLOY_STACK_FRAMEWORK || eventProps.framework || undefined,
+            ...eventProps
         }
     };
 
@@ -35,7 +38,7 @@ export function trackEvent(eventName, properties) {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(payload),
-    }).catch((err) => {
+    }).catch(() => {
         // Silently swallow network errors (e.g., user is offline)
     });