deploy-stack 0.17.13 → 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/.muserules

@@ -0,0 +1,16 @@
+# deploy-stack: AI Agent Core Directives
+
+## 1. Architectural Boundaries
+- You are strictly forbidden from modifying the user's application code (e.g., `src/`). You only manage infrastructure and deployment scaffolding.
+- All Dockerfiles must remain at **0 CVEs**. Do not introduce unvetted packages.
+- All AWS IAM configurations must use OIDC. Never generate long-lived IAM access keys.
+
+## 2. Tech Stack & Formatting
+- **Testing:** Use `vitest` for all unit and snapshot testing.
+- **Terminal UI:** Use `picocolors` for all CLI output. Standardize on green for success, yellow for warnings, red for errors, and blue for info.
+- **CLI Framework:** Use `commander`.
+
+## 3. Workflow
+- Read the relevant `specs/` document before writing any code.
+- Run `npm test` continuously to verify your work.
+- Do not conclude your task until the test suite passes completely.

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.
@@ -89,6 +90,9 @@ The interactive wizard will analyze your codebase, detect your framework, estima
 * **`npx deploy-stack doctor`**
   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. 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.
 
@@ -97,6 +101,7 @@ The interactive wizard will analyze your codebase, detect your framework, estima
 
 * **`npx deploy-stack --headless`**
   Bypasses the interactive wizard for fully programmatic execution. Perfect for CI/CD pipelines, custom scripts, or AI agent integration. Accepts flags like `--framework=static`, `--region=us-east-2`, and `--size=micro`.
+  Pass `--preconfigured` when invoking via an external schematic or integration (e.g., `nest add nest-deploy-stack`) to suppress framework warnings for pre-validated configs.
 
 * **`npx deploy-stack sync-ai`**
   Selectively generates architecture rules for AI coding assistants (Cursor, Copilot, Windsurf, Claude). Automatically extracts your AWS Region and Container Port to prevent Terraform hallucinations.
@@ -163,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)
-  - [ ] `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.
+### 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/bin/cli.js

@@ -6,6 +6,7 @@ import { runDoctor } from '../src/commands/doctor.js';
 import { pushSecrets } from '../src/commands/secrets.js';
 import { ejectStack } from '../src/commands/eject.js';
 import { applyStack } from '../src/commands/apply.js';
+import { runDiagnose } from '../src/commands/diagnose.js';
 import { syncAi } from '../src/commands/sync-ai.js';
 import { parseCliArgs } from '../src/core/parser.js';
 
@@ -33,6 +34,8 @@ if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'push') {
     ejectStack().catch(e => { console.error(e); process.exit(1); });
 } 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); });
 } else {
     mainStack({ isHeadless, headlessOptions }).catch(e => { console.error(e); process.exit(1); });
 }

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)
-  - [ ] `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.
+  - [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.
+
+### 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/guides/headless.md

@@ -28,6 +28,7 @@ You can append any of these flags to customize the generated architecture. These
 | `--enablePrPreviews` | Generates workflows for Ephemeral PR Previews. | `false` |
 | `--yes` | Automatically bypasses confirmation prompts during apply/destroy. | `false` |
 | `--no-telemetry` | Disables anonymous usage analytics. | `false` |
+| `--preconfigured` | Suppresses framework warnings for pre-validated configs from external schematics/integrations (e.g., `nest add`). | `false` |
 
 *(Note: Boolean flags like `--needsDatabase` and `--enablePrPreviews` can be passed alone or as `--flag=true`).*
 

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.13",
+  "version": "0.18.0",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"
@@ -42,7 +42,9 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@aws-sdk/client-cloudwatch-logs": "3.1119.0",
     "@aws-sdk/client-dynamodb": "3.1119.0",
+    "@aws-sdk/client-ecs": "3.1119.0",
     "@aws-sdk/client-s3": "3.1115.0",
     "@aws-sdk/client-secrets-manager": "3.1112.0",
     "@aws-sdk/client-sts": "3.1115.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/diagnose.md

@@ -0,0 +1,16 @@
+# Spec: `deploy-stack diagnose` (alias: `wtf`)
+
+## Objective
+Build a new CLI command that automatically queries AWS to troubleshoot why a deployed application is failing (e.g., container crash loops, ALB 502 Bad Gateway).
+
+## Requirements
+1. **Command Registration:** Register `diagnose` and its alias `wtf` in `bin/cli.js` using Commander.
+2. **AWS SDK Integration:** Use `@aws-sdk/client-ecs` and `@aws-sdk/client-cloudwatch-logs` to:
+   - Find the most recent stopped tasks in the ECS Fargate cluster.
+   - Extract the `stoppedReason` (e.g., OutOfMemory, Essential container in task exited).
+   - Fetch the last 50 lines of logs from CloudWatch for the failing container.
+3. **Output:** Format the output beautifully using `picocolors`. Highlight the exact error clearly so the user doesn't have to dig through JSON.
+
+## Constraints
+- Mock the AWS SDK calls in the tests so they don't require real AWS credentials to pass.
+- Do not modify the existing `apply` or `destroy` commands.

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.

package/src/commands/diagnose.js

@@ -0,0 +1,180 @@
+import { ECSClient, ListTasksCommand, DescribeTasksCommand } from '@aws-sdk/client-ecs';
+import { CloudWatchLogsClient, FilterLogEventsCommand } from '@aws-sdk/client-cloudwatch-logs';
+import fsSync from 'fs';
+import path from 'path';
+import color from 'picocolors';
+import { intro, outro, spinner } from '@clack/prompts';
+import { trackEvent, flushTelemetry } from '../core/telemetry.js';
+
+export const LOG_FETCH_LIMIT = 50;
+
+export function extractStoppedReason(task) {
+    return task?.stoppedReason || 'Unknown';
+}
+
+export function getFailingContainer(task) {
+    const containers = task?.containers || [];
+    return (
+        containers.find((c) => c.exitCode !== undefined && c.exitCode !== 0) ||
+        containers.find((c) => c.reason && c.reason !== 'Essential container in task exited') ||
+        containers[0] ||
+        {}
+    );
+}
+
+function pickMostRecentTask(tasks) {
+    if (!tasks || tasks.length === 0) return null;
+    return [...tasks].sort((a, b) => {
+        const aTime = a.stoppedAt ? new Date(a.stoppedAt).getTime() : 0;
+        const bTime = b.stoppedAt ? new Date(b.stoppedAt).getTime() : 0;
+        return bTime - aTime;
+    })[0];
+}
+
+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';
+    try {
+        const mainTfPath = path.join(process.cwd(), 'terraform', 'main.tf');
+        if (fsSync.existsSync(mainTfPath)) {
+            const mainTf = fsSync.readFileSync(mainTfPath, 'utf8');
+            // Matches: region = "us-east-2"
+            const regionMatch = mainTf.match(/region\s*=\s*"([^"]+)"/);
+            if (regionMatch) autoRegion = regionMatch[1];
+        }
+    } catch (e) {
+        // Fallback silently
+    }
+
+    const region = options.region || process.env.AWS_REGION || autoRegion;
+    const cluster = options.cluster || process.env.ECS_CLUSTER || `${projectName}-cluster`;
+    const logGroup = options.logGroup || process.env.ECS_LOG_GROUP || `/ecs/${projectName}`;
+
+    intro(color.bgCyan(color.black(' deploy-stack diagnose 🩺 ')));
+
+    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 });
+
+    try {
+        const listResp = await ecsClient.send(
+            new ListTasksCommand({
+                cluster,
+                desiredStatus: 'STOPPED',
+                sort: 'DESC',
+                maxResults: 10
+            })
+        );
+
+        const taskArns = listResp.taskArns || [];
+
+        if (taskArns.length === 0) {
+            s.stop('No stopped tasks found.');
+            console.log(color.green('✅ No stopped tasks — your service looks healthy.'));
+            outro(color.green('Diagnose complete. Nothing to fix!'));
+            trackEvent('diagnose_run', { success: true, healthy: true });
+            await flushTelemetry();
+            return { healthy: true, stoppedReason: null, logs: [] };
+        }
+
+        s.message(`Describing ${Math.min(taskArns.length, 5)} stopped task(s)...`);
+        const descResp = await ecsClient.send(
+            new DescribeTasksCommand({
+                cluster,
+                tasks: taskArns.slice(0, 5)
+            })
+        );
+
+        const tasks = descResp.tasks || [];
+        if (tasks.length === 0) {
+            s.stop('No task details returned.');
+            console.log(color.yellow('⚠ Stopped task ARNs were listed, but ECS returned no task details.'));
+            outro(color.yellow('Diagnose finished with no details.'));
+            trackEvent('diagnose_run', { success: false, error_code: 'NO_TASK_DETAILS' });
+            await flushTelemetry();
+            return { healthy: false, stoppedReason: null, logs: [] };
+        }
+
+        const failedTask = pickMostRecentTask(tasks);
+        const stoppedReason = extractStoppedReason(failedTask);
+        const failingContainer = getFailingContainer(failedTask);
+        const containerName = failingContainer.name || 'unknown';
+        const exitCode = failingContainer.exitCode;
+        const containerReason = failingContainer.reason;
+
+        s.message(`Fetching last ${LOG_FETCH_LIMIT} log lines for "${containerName}"...`);
+        let logs = [];
+        try {
+            const logsResp = await logsClient.send(
+                new FilterLogEventsCommand({
+                    logGroupName: logGroup,
+                    limit: LOG_FETCH_LIMIT
+                })
+            );
+            const events = logsResp.events || [];
+            logs = events.slice(-LOG_FETCH_LIMIT).map((e) => e.message);
+        } catch (logError) {
+            logs = [];
+        }
+
+        s.stop('Diagnosis complete.\n');
+
+        console.log(`  ${color.red(color.bold('✖ Stopped reason:'))} ${color.red(stoppedReason)}`);
+        console.log(`  ${color.dim('Cluster:')} ${color.cyan(cluster)}`);
+        console.log(`  ${color.dim('Task:')} ${color.dim(failedTask.taskArn || taskArns[0])}`);
+        console.log(`  ${color.dim('Container:')} ${color.yellow(containerName)}${exitCode !== undefined ? color.dim(` (exit code ${exitCode})`) : ''}`);
+        if (containerReason && containerReason !== stoppedReason) {
+            console.log(`  ${color.dim('Container reason:')} ${color.yellow(containerReason)}`);
+        }
+
+        if (logs.length > 0) {
+            console.log(`\n  ${color.bold(`Last ${logs.length} log lines (${color.cyan(logGroup)}):`)}`);
+            for (const line of logs) {
+                console.log(`  ${color.dim('│')} ${highlightErrorLine(line)}`);
+            }
+        } else {
+            console.log(color.dim(`\n  No recent log events found in ${logGroup}.`));
+        }
+
+        outro(color.green('Diagnose complete. Fix the error above, then redeploy. 🚀'));
+
+        trackEvent('diagnose_run', { success: true, healthy: false });
+        await flushTelemetry();
+
+        return {
+            healthy: false,
+            cluster,
+            taskArn: failedTask.taskArn || taskArns[0],
+            stoppedReason,
+            containerName,
+            exitCode,
+            containerReason,
+            logs
+        };
+    } 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.'));
+        trackEvent('diagnose_run', {
+            success: false,
+            error_code: error.name || 'UNKNOWN',
+            error_message: error.message
+        });
+        await flushTelemetry();
+        throw error;
+    }
+}
+
+function highlightErrorLine(line) {
+    if (/error|exception|failed|fatal|outofmemory|killed/i.test(line)) {
+        return color.red(line);
+    }
+    if (/warn/i.test(line)) {
+        return color.yellow(line);
+    }
+    return color.gray(line);
+}

package/src/utils/aws.js

@@ -21,7 +21,7 @@ export async function provisionStateBucket(region, projectName) {
     try {
         await s3Client.send(new CreateBucketCommand({
             Bucket: stateBucketName,
-            CreateBucketConfiguration: region === 'us-east-2' ? undefined : { LocationConstraint: region }
+            CreateBucketConfiguration: region === 'us-east-1' ? undefined : { LocationConstraint: region }
         }));
 
         await s3Client.send(new PutBucketTaggingCommand({

package/tests/aws.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { provisionStateBucket } from '../src/utils/aws.js';
+
+const {
+  mockS3Send,
+  mockStsSend,
+  MockS3Client,
+  MockSTSClient,
+  MockGetCallerIdentityCommand,
+  MockCreateBucketCommand,
+  MockPutBucketVersioningCommand,
+  MockPutBucketTaggingCommand,
+} = vi.hoisted(() => {
+  const s3Send = vi.fn();
+  const stsSend = vi.fn();
+  const mockCommand = (input) => Object.assign({}, input);
+  return {
+    mockS3Send: s3Send,
+    mockStsSend: stsSend,
+    MockS3Client: vi.fn(function () {
+      this.send = s3Send;
+    }),
+    MockSTSClient: vi.fn(function () {
+      this.send = stsSend;
+    }),
+    MockGetCallerIdentityCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockCreateBucketCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockPutBucketVersioningCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+    MockPutBucketTaggingCommand: vi.fn(function (input) {
+      Object.assign(this, mockCommand(input));
+    }),
+  };
+});
+
+vi.mock('@aws-sdk/client-s3', () => {
+  return {
+    S3Client: MockS3Client,
+    CreateBucketCommand: MockCreateBucketCommand,
+    PutBucketVersioningCommand: MockPutBucketVersioningCommand,
+    PutBucketTaggingCommand: MockPutBucketTaggingCommand,
+  };
+});
+
+vi.mock('@aws-sdk/client-sts', () => {
+  return {
+    STSClient: MockSTSClient,
+    GetCallerIdentityCommand: MockGetCallerIdentityCommand,
+  };
+});
+
+describe('provisionStateBucket', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockS3Send.mockReset().mockResolvedValue({});
+    mockStsSend.mockReset().mockResolvedValue({ Account: '123456789012' });
+  });
+
+  it("when region is 'us-east-1', CreateBucketConfiguration is undefined", async () => {
+    await provisionStateBucket('us-east-1', 'my-project');
+
+    expect(MockCreateBucketCommand).toHaveBeenCalledWith(
+      expect.objectContaining({ CreateBucketConfiguration: undefined }),
+    );
+    expect(MockCreateBucketCommand.mock.calls[0][0].CreateBucketConfiguration).toBeUndefined();
+  });
+
+  it("when region is 'us-east-2', CreateBucketConfiguration has LocationConstraint 'us-east-2'", async () => {
+    await provisionStateBucket('us-east-2', 'my-project');
+
+    expect(MockCreateBucketCommand).toHaveBeenCalledWith(
+      expect.objectContaining({
+        CreateBucketConfiguration: { LocationConstraint: 'us-east-2' },
+      }),
+    );
+    expect(MockCreateBucketCommand.mock.calls[0][0].CreateBucketConfiguration).toEqual({
+      LocationConstraint: 'us-east-2',
+    });
+  });
+});

package/tests/diagnose.test.js

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { runDiagnose } from '../src/commands/diagnose.js';
+
+// Mock the AWS SDK clients (no real credentials needed)
+const {
+    mockEcsSend,
+    mockLogsSend,
+    MockECSClient,
+    MockListTasksCommand,
+    MockDescribeTasksCommand,
+    MockLogsClient,
+    MockFilterLogEventsCommand
+} = vi.hoisted(() => {
+    const ecsSend = vi.fn();
+    const logsSend = vi.fn();
+    return {
+        mockEcsSend: ecsSend,
+        mockLogsSend: logsSend,
+        MockECSClient: vi.fn(function () {
+            this.send = ecsSend;
+        }),
+        MockListTasksCommand: vi.fn(function (input) {
+            Object.assign(this, input);
+        }),
+        MockDescribeTasksCommand: vi.fn(function (input) {
+            Object.assign(this, input);
+        }),
+        MockLogsClient: vi.fn(function () {
+            this.send = logsSend;
+        }),
+        MockFilterLogEventsCommand: vi.fn(function (input) {
+            Object.assign(this, input);
+        })
+    };
+});
+
+vi.mock('@aws-sdk/client-ecs', () => {
+    return {
+        ECSClient: MockECSClient,
+        DescribeTasksCommand: MockDescribeTasksCommand,
+        ListTasksCommand: MockListTasksCommand
+    };
+});
+
+vi.mock('@aws-sdk/client-cloudwatch-logs', () => {
+    return {
+        CloudWatchLogsClient: MockLogsClient,
+        FilterLogEventsCommand: MockFilterLogEventsCommand
+    };
+});
+
+// Silence interactive prompts and telemetry during tests
+vi.mock('@clack/prompts', () => ({
+    intro: vi.fn(),
+    outro: vi.fn(),
+    spinner: () => ({ start: vi.fn(), stop: vi.fn(), message: vi.fn() })
+}));
+
+vi.mock('../src/core/telemetry.js', () => ({
+    trackEvent: vi.fn(),
+    flushTelemetry: vi.fn().mockResolvedValue()
+}));
+
+describe('Command: diagnose', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockEcsSend.mockReset();
+        mockLogsSend.mockReset();
+    });
+
+    it('should extract and format the stoppedReason from a failed ECS task', async () => {
+        const stoppedReason = 'OutOfMemoryError: Container killed due to memory usage';
+
+        // 1. ListTasks -> one stopped task; DescribeTasks -> failed task detail
+        mockEcsSend
+            .mockResolvedValueOnce({
+                taskArns: ['arn:aws:ecs:us-east-1:123456789012:task/test-cluster/abc123']
+            })
+            .mockResolvedValueOnce({
+                tasks: [
+                    {
+                        taskArn: 'arn:aws:ecs:us-east-1:123456789012:task/test-cluster/abc123',
+                        stoppedReason,
+                        stoppedAt: new Date().toISOString(),
+                        containers: [
+                            { name: 'app', exitCode: 137, reason: 'Essential container in task exited' }
+                        ]
+                    }
+                ]
+            });
+
+        // 2. CloudWatch -> 55 events, only the last 50 should be used
+        const events = Array.from({ length: 55 }, (_, i) => ({
+            message: i === 54 ? `FATAL ${stoppedReason}` : `log line ${i + 1}`
+        }));
+        mockLogsSend.mockResolvedValueOnce({ events });
+
+        // 3. Capture formatted console output
+        const output = [];
+        const consoleSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
+            output.push(args.join(' '));
+        });
+
+        try {
+            const result = await runDiagnose({
+                cluster: 'test-cluster',
+                region: 'us-east-1',
+                logGroup: '/ecs/test'
+            });
+
+            // Return value carries the extracted reason
+            expect(result.stoppedReason).toBe(stoppedReason);
+            // Last-50-lines limit honored
+            expect(result.logs).toHaveLength(50);
+            // Formatted output highlights the exact error
+            expect(output.join('\n')).toContain(stoppedReason);
+            // Log fetch asked CloudWatch for the last 50 lines
+            expect(MockFilterLogEventsCommand).toHaveBeenCalledWith(
+                expect.objectContaining({ limit: 50 })
+            );
+        } finally {
+            consoleSpy.mockRestore();
+        }
+    });
+
+    it('should report healthy when there are no stopped tasks', async () => {
+        mockEcsSend.mockResolvedValueOnce({ taskArns: [] });
+
+        const output = [];
+        const consoleSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
+            output.push(args.join(' '));
+        });
+
+        try {
+            const result = await runDiagnose({ cluster: 'test-cluster', region: 'us-east-1' });
+            expect(result.healthy).toBe(true);
+            expect(mockLogsSend).not.toHaveBeenCalled();
+            expect(output.join('\n')).toMatch(/healthy|No stopped tasks/i);
+        } finally {
+            consoleSpy.mockRestore();
+        }
+    });
+});