deploy-stack 0.17.14 → 0.18.0

package/.github/workflows/iac-validation.yml

@@ -0,0 +1,62 @@
+name: IaC Validation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        framework: [nestjs, nextjs, nuxt, node, svelte, static, python, django, rails, go]
+    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: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup TFLint
+        uses: terraform-linters/setup-tflint@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scaffold app (${{ matrix.framework }})
+        run: |
+          TMPDIR=$(mktemp -d)
+          echo "GENERATED_DIR=$TMPDIR" >> "$GITHUB_ENV"
+          cd "$TMPDIR"
+          node "$GITHUB_WORKSPACE/bin/cli.js" --headless --preconfigured --framework=${{ matrix.framework }}
+
+      - name: Terraform Compile
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: |
+          terraform init -backend=false
+          terraform validate
+
+      - name: Init TFLint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint --init
+
+      - name: Terraform Lint
+        working-directory: ${{ env.GENERATED_DIR }}/terraform
+        run: tflint
+
+      - name: DevSecOps Scan
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          scan-ref: ${{ env.GENERATED_DIR }}
+          format: 'table'
+          severity: 'HIGH,CRITICAL'
+          exit-code: '1'

package/README.md

@@ -35,6 +35,7 @@ You retain complete ownership of your infrastructure code without relying on bla
 
 **🛡️ DevSecOps & Security**
 * **Automated Trivy Scanning:** Integrated IaC and container vulnerability scanning on every GitHub Actions run.
+* **Continuous IaC Validation:** Matrix pipeline scaffolds all 10 supported frameworks headlessly and gates every commit on `terraform validate`, `tflint`, and Trivy (HIGH/CRITICAL).
 * **Hardened Containers:** Explicitly drops root privileges using `nginx-unprivileged` and distroless bases for strict Fargate security compliance.
 * **Zero-Secret CI/CD:** Utilizes AWS IAM OpenID Connect (OIDC) for automated deployments—no long-lived AWS keys in GitHub.
 * **Built-in Secrets Manager:** Push local `.env` variables directly into encrypted AWS Secrets Manager vaults with a single CLI command.
@@ -90,7 +91,7 @@ The interactive wizard will analyze your codebase, detect your framework, estima
   Scans your local environment and generated files to ensure all required dependencies (Docker, Terraform, AWS CLI) are installed and configured correctly.
 
 * **`npx deploy-stack diagnose`** (alias: `wtf`)
-  Troubleshoots a failing ECS deployment by reporting the most recent stopped task's `stoppedReason`, failing container (with exit code), and the last 50 CloudWatch log lines.
+  Troubleshoots a failing ECS deployment by reporting the most recent stopped task's `stoppedReason`, failing container (with exit code), and the last 50 CloudWatch log lines. Stateless: derives region/cluster context from `terraform/main.tf` (see ADR-0004), no local state file required.
 
 * **`npx deploy-stack destroy`**
   Safely tears down your ECS cluster, Load Balancers, and networking resources to stop AWS billing. Includes an interactive prompt to optionally retain or delete your S3 remote state bucket.
@@ -167,17 +168,12 @@ npx deploy-stack --no-telemetry
 
 ## 🗺️ Roadmap
 
-### Current Focus (Phase 7: Team Workflows & Ecosystem Integrations)
-- [x] **Ephemeral PR Previews:** Generate GitHub Actions workflows that spin up temporary ECS Fargate tasks and post live preview URLs directly in pull request comments to streamline team code reviews.
-- [x] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring coding assistants generate accurate deployment commands tailored to the project.
-- [ ] **Native Ecosystem Integrations & Scaffolding:** Publish seamless, push-button plugins and templates across major framework package registries:
-  - [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)
-  - [x] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
-  - [x] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
-  - [x] `rails-template-deploy-stack` (Zero-click Ruby on Rails application template)
-- [x] **Automated Troubleshooting:** `deploy-stack diagnose` (alias: `wtf`) automatically analyzes common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.
+### Current Focus: Phase 8: Platform Hardening & Developer Experience
+**Goal:** Solidify the core engine's reliability, prove security compliance, and establish documentation hub before introducing Day-2 operational commands.
+- [ ] **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.
 
 👉 **[See the full project history and future plans in ROADMAP.md](./ROADMAP.md)**
 

package/docs/ROADMAP.md

@@ -22,15 +22,22 @@
 - [x] **Docker Compose to ECS Translator:** Automatically converting a familiar local `docker-compose.yml` into production ECS task definitions.
 - [x] **AI Agent Rulesets:** Publishing `.cursorrules` and Copilot instructions that teach AI assistants exactly how to utilize the CLI on the user's behalf.
 
-### Phase 7: Team Workflows & Ecosystem Integrations (Current)
+### Phase 7: Team Workflows & Ecosystem Integrations (Completed)
 *Focus: Enhance collaborative development and expand native support across major framework ecosystems.*
 - [x] **Ephemeral PR Previews:** Generate GitHub Actions workflows that spin up temporary ECS Fargate tasks and post live preview URLs directly in pull request comments to streamline team code reviews.
 - [x] **AI Context Synchronization:** Implement `deploy-stack sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring coding assistants generate accurate deployment commands tailored to the project.
-- [ ] **Native Ecosystem Integrations:** Publish seamless, push-button plugins across major frameworks.
+- [x] **Native Ecosystem Integrations:** Publish seamless, push-button plugins across major frameworks.
   - [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)
   - [x] `cookiecutter-fastapi-deploy-stack` (Cookiecutter for modern async Python)
   - [x] `nest-deploy-stack` (Native `nest add` schematic for NestJS)
   - [x] `rails-template-deploy-stack` (Zero-click Ruby on Rails application template)
-- [x] **Automated Troubleshooting:** `deploy-stack diagnose` (alias: `wtf`) automatically analyzes common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.
+- [x] **Automated Troubleshooting:** `deploy-stack diagnose` (alias: `wtf`) automatically analyzes common day-2 AWS operational issues (e.g., Fargate OOM kills, ALB 502s) directly from the terminal.
+
+### Phase 8: Platform Hardening & Developer Experience (Current)
+*Focus: Solidify the core engine's reliability, prove security compliance, and establish documentation hub before introducing Day-2 operational commands.*
+- [ ] **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.

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

@@ -2,7 +2,6 @@
 
 * **Status:** Accepted
 * **Date:** 2026-08-15 (Retroactive)
-* **Deciders:** Core Engineering Team
 
 ## Context and Problem Statement
 

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

@@ -2,7 +2,6 @@
 
 * **Status:** Accepted
 * **Date:** 2026-08-20 (Retroactive)
-* **Deciders:** Core Engineering Team
 
 ## Context and Problem Statement
 

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

@@ -2,7 +2,6 @@
 
 * **Status:** Accepted
 * **Date:** 2026-09-02 (Retroactive)
-* **Deciders:** Core Engineering Team
 
 ## Context and Problem Statement
 

package/docs/adr/0004-iac-driven-diagnostic-context.md

@@ -0,0 +1,34 @@
+# 0004. IaC-Driven Diagnostic Context (Stateless CLI)
+
+* **Status:** Accepted
+* **Date:** 2026-09-19
+
+## Context and Problem Statement
+
+To provide a seamless developer experience, the `deploy-stack diagnose` command needs to automatically fetch CloudWatch logs and ECS task failures without requiring the user to manually input their AWS Region, Cluster Name, or Log Group. 
+
+We needed a mechanism to persist or infer the deployment context locally so the CLI knows where to look for errors.
+
+## Decision Drivers
+
+* **Statelessness:** The CLI should avoid managing internal database files or proprietary local state files that can fall out of sync with actual infrastructure.
+* **Single Source of Truth:** Terraform is already the declarative source of truth for the project's infrastructure.
+* **Ecosystem Compatibility:** Developers often delete node_modules or switch laptops; context retrieval must survive typical Git workflows.
+
+## Considered Options
+
+1. **Local State File:** Create a `.deploy-stack/context.json` file upon generation. (Rejected: creates state drift and pollutes version control).
+2. **AWS Tag Querying:** Use the AWS SDK to query all clusters for a specific tag. (Rejected: too slow, requires broad IAM `ListClusters` permissions, and fails if multiple environments exist).
+3. **IaC Parsing (Stateless):** Parse the generated `terraform/main.tf` to extract the AWS Region and infer the cluster name from the local directory structure.
+
+## Decision Outcome
+
+**Chosen Option:** IaC Parsing (Stateless). The `diagnose` command reads the AWS Region directly via regex from `terraform/main.tf` and constructs standard AWS resource names based on the current working directory.
+
+### Positive Consequences
+* The CLI remains entirely stateless. If the Terraform files exist, the diagnostics work.
+* Enforces the architectural philosophy that the generated IaC is the ultimate source of truth.
+* Zero additional files are added to the user's repository.
+
+### Negative Consequences
+* If a user manually alters the `region` string inside `main.tf` using non-standard formatting, the regex parser may fail to detect it, falling back to a default region.

package/docs/testing-strategy.md

@@ -5,6 +5,10 @@ To ensure zero regressions in infrastructure generation and safe local execution
 ## 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
+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. 
 * **The Matrix:** The test suite generates dummy projects across 11 architectural topologies (including Django, Rails, Go, Nuxt, Next.js, SvelteKit, and Vercel/Heroku migrations).
@@ -17,7 +21,7 @@ To ensure tests run sub-second and deterministically without requiring real AWS
 * **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`.
+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):** 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.
+* **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.

package/package.json

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

package/specs/ci-pipeline.md

@@ -0,0 +1,17 @@
+# Spec: Continuous Infrastructure Validation Pipeline
+
+## Objective
+Create a GitHub Actions workflow that automatically generates, compiles, and security-scans our IaC templates across all supported frameworks to prevent regressions.
+
+## Requirements
+1. **Workflow Registration:** Create `.github/workflows/iac-validation.yml` triggered on push to `main` and all pull requests.
+2. **Matrix Strategy:** Run tests across all 10 supported framework permutations: `nestjs`, `nextjs`, `nuxt`, `node`, `svelte`, `static`, `python`, `django`, `rails`, and `go`.
+3. **Execution Steps:** For each framework in the matrix:
+   - Scaffold the app: Run `node bin/cli.js --headless --preconfigured --framework=<matrix-framework>` in a temporary directory.
+   - Terraform Compile: Run `terraform init -backend=false` followed by `terraform validate`.
+   - Terraform Lint: Run `tflint` to catch deprecated syntax.
+   - DevSecOps Scan: Run Trivy (via `aquasecurity/trivy-action`) to scan the generated `Dockerfile` and `terraform/` directory.
+
+## Constraints
+- The pipeline must execute completely offline without AWS credentials (hence `-backend=false`).
+- Trivy must be configured to fail the build if it detects HIGH or CRITICAL vulnerabilities.

package/specs/docs-hub.md

@@ -0,0 +1,16 @@
+# Spec: Starlight Documentation Hub
+
+## Objective
+Initialize an Astro Starlight documentation site inside the monorepo to serve as the official, version-controlled developer portal for `deploy-stack`.
+
+## Requirements
+1. **Scaffolding:** Initialize a new Astro Starlight project inside the `apps/docs/` directory.
+2. **Information Architecture:** Configure `astro.config.mjs` to render a sidebar with three main sections:
+   - **Core Concepts:** (Link to ADRs and architectural decisions).
+   - **Guides:** (Link to deployment guides and PaaS migrations).
+   - **CLI Reference:** (Command reference for init, apply, diagnose).
+3. **Migration:** Move all existing Markdown files from the root `docs/adrs/` folder into `apps/docs/src/content/docs/adrs/` so they are immediately searchable.
+
+## Constraints
+- Use the standard Astro Starlight dependency tree. 
+- Ensure a script (e.g., `"docs:dev": "npm run dev --workspace=apps/docs"`) is added to the root `package.json` to allow starting the docs from the top level.