@grada-run/grada 0.0.1 → 0.33.0

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

@@ -0,0 +1,103 @@
+---
+title: grada docs
+description: Official developer portal for grada — concepts, guides, and CLI reference.
+template: splash
+tableOfContents: false
+head:
+  - tag: style
+    content: |
+      /* Landing page: compact two-column hero, everything above the fold. */
+      #_top { display: none; }
+      .landing-hero { padding: 1.5rem 0; }
+
+      .sl-markdown-content .landing-grid {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        gap: 2rem;
+        align-items: start;
+        margin: 0;
+        padding: 0;
+      }
+
+      /* Brute-force the top alignment to ignore Starlight's markdown margins */
+      .sl-markdown-content h1.landing-title,
+      .sl-markdown-content p.landing-intro {
+        margin-top: 0 !important;
+      }
+
+      .sl-markdown-content h1.landing-title { line-height: 1.1; }
+      .sl-markdown-content .landing-tagline { margin-top: 1rem !important; }
+      .landing-actions { display: flex; gap: 0.75rem; flex-wrap: wrap; margin-top: 1.5rem; }
+
+      .sl-markdown-content .landing-cards {
+        display: grid;
+        grid-template-columns: repeat(3, 1fr);
+        gap: 1.5rem;
+        align-items: stretch;
+        margin-top: 2rem;
+        padding: 0;
+      }
+
+      /* Force height propagation through any hidden MDX wrappers */
+      .sl-markdown-content .landing-cards > * {
+        margin: 0 !important;
+        height: 100% !important;
+      }
+
+      .sl-markdown-content .landing-cards .sl-link-card,
+      .sl-markdown-content .landing-cards .sl-link-card a {
+        height: 100% !important;
+        display: flex;
+        flex-direction: column;
+      }
+
+      .sl-markdown-content .landing-footnote {
+        margin-top: 2rem;
+        font-size: var(--sl-text-sm);
+        color: var(--sl-color-gray-2);
+      }
+
+      @media (max-width: 50rem) {
+        .sl-markdown-content .landing-grid { grid-template-columns: 1fr; }
+        .sl-markdown-content .landing-cards { grid-template-columns: 1fr; }
+      }
+---
+
+import { LinkCard, LinkButton, Code } from '@astrojs/starlight/components';
+
+<div class="landing-hero">
+  <div class="landing-grid">
+    <div>
+      <h1 class="landing-title">grada docs</h1>
+      <p class="landing-tagline">Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.</p>
+      <div class="landing-actions">
+        <LinkButton href="/grada/guides/quickstart/">Get started in 5 minutes</LinkButton>
+        <LinkButton href="/grada/cli/init/" variant="minimal">CLI reference</LinkButton>
+      </div>
+    </div>
+    <div>
+      <p class="landing-intro">`grada` turns your repo into a production-ready AWS deployment — Terraform, Docker, and CI/CD generated from your code:</p>
+      <Code code={`npx grada-run        # scaffold Terraform, Dockerfile, workflows\nnpx grada-run apply  # provision the ALB, cluster, and service\ngit push                # build, scan, and roll out your image`} lang="bash" />
+    </div>
+  </div>
+</div>
+
+<div class="landing-cards">
+  <LinkCard
+    title="Deploying for the first time"
+    description="Follow the 5-minute Quickstart, then the CI/CD pipeline and first deploy."
+    href="/grada/guides/quickstart/"
+  />
+  <LinkCard
+    title="Migrating from Vercel or Heroku"
+    description="Next.js, Astro, SvelteKit, and Procfile guides for moving to AWS Fargate."
+    href="/grada/migrations/nextjs-vercel-to-aws/"
+  />
+  <LinkCard
+    title="Looking up a command"
+    description="Full CLI reference starting with npx grada-run."
+    href="/grada/cli/init/"
+  />
+</div>
+
+<p class="landing-footnote">Supports NestJS, Next.js, Nuxt, Express, SvelteKit, Astro, FastAPI, Django, Rails, and Go — see <a href="/grada/guides/frameworks/">Supported Frameworks</a> · <a href="/grada/guides/examples/">Examples</a> · <a href="/grada/adrs/0001-s3-native-state-locking/">Architecture Decisions</a></p>

package/apps/docs/src/content/docs/migrations/astro-vercel-to-aws.md

@@ -0,0 +1,55 @@
+---
+title: "Migrating Astro from Vercel to AWS Fargate"
+description: "Switch the Astro adapter to Node standalone to leave Vercel for AWS Fargate."
+---
+
+If you are seeing a warning from `grada` about your Astro adapter, it means your project is currently configured to build specifically for Vercel's proprietary serverless network. 
+
+To deploy Astro as a containerized application on standard AWS infrastructure, you simply need to switch to Astro's official Node.js adapter.
+
+## How to Fix
+
+### 1. Install the Node adapter
+Run the following command in your terminal to swap out the Vercel adapter for the Node adapter:
+
+\`\`\`bash
+npm install @astrojs/node
+npm uninstall @astrojs/vercel
+\`\`\`
+
+### 2. Update `astro.config.mjs`
+Open your Astro configuration file and replace the Vercel import with the Node import.
+
+**Before (Vercel Lock-in):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel/serverless';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+});
+\`\`\`
+
+**After (AWS Ready):**
+\`\`\`javascript
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone'
+  }),
+});
+\`\`\`
+
+### 3. Deploy
+That's it! Your Astro app is now decoupled from Vercel. 
+
+Run `npx grada-run apply` and the CLI will automatically package this standalone Node server into a hardened Docker container and deploy it to your AWS cluster.
+
+## Next steps
+
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for what happens on `git push`.
+- [Supported Frameworks](/grada/guides/frameworks/) for Astro build requirements.

package/apps/docs/src/content/docs/migrations/heroku-procfile-to-aws.md

@@ -0,0 +1,41 @@
+---
+title: "Migrating from Heroku to AWS (Procfile Support)"
+description: "Map Heroku Procfile web and worker processes to AWS ECS Fargate services."
+---
+
+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). 
+
+`grada` natively understands Heroku `Procfile` syntax and automatically translates it into a production-grade, multi-container AWS architecture.
+
+## How it Works
+
+When you run `npx grada-run`, the CLI scans your root directory for a `Procfile`. 
+
+### The `web` Process
+If the CLI detects a `web:` declaration:
+1. It overrides the default Docker `CMD`.
+2. It provisions an AWS ECS Fargate service for this process.
+3. It automatically wires this specific container to your public-facing Application Load Balancer (ALB) so it can receive internet traffic.
+
+### The `worker` Process
+If the CLI detects a `worker:` declaration:
+1. It generates a completely separate ECS Fargate task definition and private service (`worker.tf`) running the same image with your worker command.
+2. The service gets **no load balancer**, so nothing routes internet traffic to it — it still reaches your database, caches, and queues over the VPC network.
+3. It shares the web container's secrets, database variables, and log group (worker entries carry the `worker` stream prefix), scaling independently of the web service.
+
+## Example
+
+**Your `Procfile`:**
+```text
+web: gunicorn myapp.wsgi
+worker: celery -A myapp worker -l info
+```
+
+**The Result:**
+Running `grada` will automatically generate the Terraform required to spin up both containers simultaneously from the exact same Docker image, scaling them independently based on your needs.
+
+## Next steps
+
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for what happens on `git push`.
+- [Supported Frameworks](/grada/guides/frameworks/) for Procfile and framework detection.
+- [Background Workers](/grada/guides/background-workers/) for the worker service, SQS scale-to-zero, and day-2 operations.

package/apps/docs/src/content/docs/migrations/nextjs-vercel-to-aws.md

@@ -0,0 +1,51 @@
+---
+title: "Migrating Next.js from Vercel to AWS Fargate"
+description: "Add output: 'standalone' to run Next.js in a lean AWS Fargate container."
+---
+
+If you are seeing a warning from `grada` about `output: 'standalone'`, your Next.js configuration is missing a crucial setting required for containerized environments.
+
+By default, Next.js requires your entire `node_modules` folder to run the production server. This creates massive, bloated Docker containers that boot slowly and cost more to host. The `standalone` output mode tells Next.js to trace your code and bundle *only* the specific files and dependencies actually used in production, creating an ultra-lean deployment artifact.
+
+## How to Fix
+
+### 1. Update `next.config.js` (or `.mjs` / `.cjs`)
+Open your Next.js configuration file in the root of your project and add `output: 'standalone'` to the configuration object.
+
+**Before (Vercel Default):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+**After (AWS Ready):**
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  output: 'standalone', // <-- Add this line
+  // Other existing config...
+};
+
+export default nextConfig;
+```
+
+### 2. (Optional) Define a Health Check Route
+AWS Application Load Balancers require a route to ping to ensure your app is healthy. If you don't already have one, create a simple API route in your app (e.g., `app/api/health/route.ts` for App Router, or `pages/api/health.ts` for Pages Router) that returns a `200 OK` status.
+
+When running `grada`, choose **Advanced Configuration** and set your ALB Health Check Path to this route (e.g., `/api/health`).
+
+### 3. Deploy
+Your Next.js app is now perfectly optimized for AWS ECS Fargate! 
+
+Run `npx grada-run apply`. The CLI's generated `Dockerfile` will automatically target your new `.next/standalone` directory and deploy the optimized build to the cloud.
+
+## Next steps
+
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for what happens on `git push`.
+- [Supported Frameworks](/grada/guides/frameworks/) for Next.js requirements.

package/apps/docs/src/content/docs/migrations/sveltekit-vercel-to-aws.md

@@ -0,0 +1,63 @@
+---
+title: "Migrating SvelteKit from Vercel to AWS Fargate"
+description: "Switch SvelteKit to adapter-node to leave Vercel for AWS Fargate."
+---
+
+If you are seeing a warning from `grada` about your SvelteKit adapter, your project is currently using `@sveltejs/adapter-auto` (which often defaults to Vercel) or the explicit `@sveltejs/adapter-vercel`.
+
+These adapters are designed specifically for proprietary serverless edge networks. To run your SvelteKit app in a scalable, standard Docker container on AWS Fargate, you need to switch to Svelte's official Node adapter.
+
+## How to Fix
+
+### 1. Install the Node Adapter
+Run the following command in your terminal to install the Node adapter and remove the Vercel/Auto adapter:
+
+```bash
+npm install -D @sveltejs/adapter-node
+npm uninstall @sveltejs/adapter-auto @sveltejs/adapter-vercel
+```
+
+### 2. Update `svelte.config.js`
+Open your `svelte.config.js` file and change the adapter import at the top of the file.
+
+**Before (Locked into Vercel/Auto):**
+```javascript
+import adapter from '@sveltejs/adapter-auto'; // or '@sveltejs/adapter-vercel'
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+**After (AWS Ready):**
+```javascript
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;
+```
+
+### 3. Deploy
+Your SvelteKit app is now decoupled! 
+
+Run `npx grada-run apply`. The CLI will automatically detect the standard Node build output, package it into a hardened Docker container, and deploy it to your AWS cluster.
+
+## Next steps
+
+- [CI/CD Pipeline & First Deploy](/grada/guides/cicd-pipeline/) for what happens on `git push`.
+- [Supported Frameworks](/grada/guides/frameworks/) for SvelteKit adapter requirements.

package/apps/docs/src/content/docs/roadmap.md

@@ -0,0 +1,99 @@
+---
+title: Roadmap
+description: Where grada has been and what comes next — completed phases and the current milestone.
+---
+
+### Phase 1–3: The Core Engine (Completed)
+- [x] **Core MVP:** Interactive CLI, ECS Fargate + ALB generation, CI/CD, and Secrets sync.
+- [x] **Production Readiness:** CloudFront CDN edge distribution, native S3 state locking, and secure OIDC integration.
+- [x] **Smart Experience:** Zero-config framework auto-discovery for static output directories.
+- [x] **Trust & Observability:** DevSecOps Trivy scanning, automated 5XX alarms, 14-day log retention, and safe local overwrite protections.
+
+### Phase 4: Trust Anchors & TAM Expansion (Completed)
+- [x] **Ecosystem Distribution:** Native GitHub Marketplace Action for rapid discovery.
+- [x] **Cost Transparency:** Pre-flight AWS cost estimator injected directly into the CLI wizard.
+- [x] **Zero Vendor Lock-In:** Explicit `npx grada-run eject` command to safely strip `ManagedBy` tags and CLI metadata, leaving behind pure IaC.
+- [x] **Heavy Backend Monoliths:** Hardened, unprivileged container adapters for Go, Nuxt.js, Django, and Rails, complete with automated zero-trust RDS PostgreSQL provisioning.
+
+### Phase 5: The Activation Engine (Completed)
+- [x] **Local Execution Wrapper:** Native `grada apply` command with terminal-optimized streaming to eliminate Terraform context switching.
+- [x] **Ecosystem Integrations:** Official plugins published to the Astro Integrations directory (`astro-grada`) and Nuxt module registry (`nuxt-grada`).
+
+### Phase 6: Migration & Trust Engine (Completed)
+- [x] **Dry-Run Visualization:** Interactive pre-flight terminal UI with ASCII topology maps and precise, dynamic AWS cost estimation.
+- [x] **PaaS Importers:** Auto-parse `vercel.json` and Heroku `Procfile` configurations to map routing rules, web commands, and background workers automatically.
+- [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 (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 `grada sync-ai` to automatically generate `.cursorrules` and AI context files, ensuring coding assistants generate accurate deployment commands tailored to the project.
+- [x] **Native Ecosystem Integrations:** Publish seamless, push-button plugins across major frameworks.
+  - [x] `vite-plugin-grada` (Live on NPM)
+  - [x] `svelte-adapter-grada` (SvelteKit adapter integration)
+  - [x] `cookiecutter-django-grada` (Listed on Django Packages)
+  - [x] `cookiecutter-fastapi-grada` (Cookiecutter for modern async Python)
+  - [x] `nest-grada` (Native `nest add` schematic for NestJS)
+  - [x] `rails-template-grada` (Zero-click Ruby on Rails application template)
+- [x] **Automated Troubleshooting:** `grada 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 (Completed)
+*Focus: Solidify the core engine's reliability, prove security compliance, and establish documentation hub before introducing Day-2 operational commands.*
+- [x] **Documentation Hub:** Launch a dedicated Astro Starlight documentation site featuring interactive architecture diagrams, core concept deep-dives, and detailed CLI references.
+- [x] **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.
+- [x] **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.
+- [x] **Integration Stability Suite:** Expand Vitest coverage to enforce strict contracts for headless execution flags (`--preconfigured`, `--headless`), ensuring seamless interoperability with third-party scaffolding tools.
+
+### Phase 9: Day-2 Operations & Developer Retention (Completed)
+*Focus: Uninterrupted Developer Flow. Deliver a seamless Day-2 environment where users maintain full infrastructure control without leaving the command line to troubleshoot.*
+- [x] **Context-Aware Log Streaming:** `grada logs <service> --tail --error`. Implement a live stream using the CloudWatch Logs API to merge API/frontend logs in a color-coded terminal view, eliminating the need to navigate the AWS web console.
+- [x] **1-Click Container Access:** `grada exec <service>`. Automatically drop the user into a secure bash shell inside a running Fargate container using AWS Systems Manager (SSM) Session Manager, abstracting away complex IAM trust policies and local agent requirements.
+- [x] **Secure Secrets Sync & Rolling Restarts:** `grada secrets pull/audit`. Fetch vault payloads to a local `.env`, compare local vs. remote keys, and trigger rolling ECS restarts for value-only rotations.
+- [x] **Secure Database Tunneling:** `grada db connect`. Utilize SSM Port Forwarding to open a secure `localhost` tunnel directly to your private RDS PostgreSQL instance, allowing tools like DBeaver or Prisma Studio to query production data without public internet exposure.
+- [x] **Health & Alarm Dashboard:** `grada status`. Query the ECS Service status (Desired vs. Running tasks) and CloudWatch Alarms (e.g., ALB 5XX errors), printing a clear green/red operational status matrix directly in the terminal.
+- [x] **Orphaned Resource Garbage Collection:** `grada gc`. Scan the AWS account for unattached Elastic IPs, abandoned ECR image layers, and lingering CloudWatch log groups left behind by PR previews or manual deletions, safely removing them to protect the user's AWS bill.
+
+### Phase 10: Complete Day-0 to Day-N Lifecycle Mastery (Completed — 19/19)
+**Goal:** Zero-Console Production Independence. Eliminate the final architectural, data, and operational triggers that force developers to open the AWS Management Console across the entire application lifecycle.
+
+- [x] **Custom Domains & Automated SSL:** `grada domain add <domain>`. Automate Route 53 Hosted Zone bindings or provide an interactive External DNS verification flow (Cloudflare, Namecheap) with automated ACM TLS certificate issuance (including `us-east-1` validation for edge/CloudFront) and ALB listener routing.
+- [x] **Instant One-Command Rollback:** `grada rollback [revision]`. List the last 5 deployed task revisions and instantly revert the live ECS service to a prior healthy revision in under 15 seconds, bypassing lengthy rebuild cycles during production regressions.
+- [x] **Self-Healing Deployment Circuit Breakers:** Enable native ECS deployment circuit breakers (`deployment_circuit_breaker { enable = true, rollback = true }`) in Terraform, automatically rolling back failed container rollouts and broken health checks without operator intervention.
+- [x] **Pre-Deploy Database Migration Gate:** Inject an isolated `aws ecs run-task` step into `.github/workflows/deploy.yml` to execute schema migrations (`prisma migrate deploy`, `alembic upgrade head`, `rails db:migrate`) against RDS inside the VPC before rolling out the new service revision, automatically halting the release if migrations fail.
+- [x] **On-Demand Database Snapshots & Restore:** `grada db backup` and `grada db restore`. Provide instantaneous CLI wrappers around RDS manual snapshots and point-in-time recovery so developers can create pre-migration safety checkpoints or restore instances directly from the terminal.
+- [x] **Transactional Email & DKIM Automation:** `grada add email:ses`. Provision Amazon SES Domain Identities, auto-inject the 3 required DKIM CNAME records into Route 53 (or output external DNS records), configure SPF/DMARC baselines, and attach least-privilege `ses:SendEmail` permissions to the ECS Task Role.
+- [x] **Application Object Storage:** `grada add storage:s3`. Provision secure, private S3 buckets for asset uploads configured with CloudFront Origin Access Control (OAC), CORS rules, and presigned URL IAM policies injected directly into the container runtime.
+- [x] **In-Memory Caching & Async Queues:** `grada add db:redis` (powered by cost-optimized AWS ElastiCache for Valkey/Redis) and `grada add queue:sqs`. Scaffold private in-memory cache clusters, SQS queues with dead-letter queues, and scale-to-zero background worker Fargate services driven by queue depth auto-scaling (`ApproximateNumberOfMessagesVisible`).
+- [x] **Scheduled Cron Jobs:** `grada add cron`. EventBridge Scheduler rules that trigger one-off Fargate tasks on a cron schedule.
+- [x] **Serverless NoSQL:** `grada add db:dynamodb`. Provision scale-to-zero DynamoDB (`PAY_PER_REQUEST`) tables with free VPC Gateway Endpoints and auto-wired IAM policies.
+- [x] **Vector Databases:** `grada db enable-vector`. One-command `pgvector` provisioning on RDS PostgreSQL for AI/RAG embeddings without expensive OpenSearch clusters.
+- [x] **Multi-Engine RDS & Aurora Scale-to-Zero:** Support PostgreSQL, MySQL, and Aurora Serverless v2 (`0 ACU` auto-pause) across `init`, `db connect`, `db backup`, and `db restore` with automatic URI formatting (`postgresql://` and `mysql://`).
+- [x] **On-Demand Remote Migration Runner:** `grada db migrate [--cmd <command>]`. Launch an ephemeral, one-off ECS Fargate task inside the private VPC to execute ad-hoc schema migrations or seed scripts (`prisma`, `alembic`, `rails db:seed`), streaming stdout/stderr live to the terminal.
+- [x] **Zero-Trust Database Ingestion:** `grada db import [--file <dump.sql> | --from <url>]`. Stream local SQL dumps or remote databases (Heroku, Supabase, Render, Railway) directly into the isolated private RDS instance via an automated background SSM tunnel.
+- [x] **GenAI Primitives:** `grada add ai:bedrock`. Configure least-privilege IAM policies for invoking AWS Bedrock foundation models.
+- [x] **Serverless Compute Primitives:** `grada --target lambda`. Provide an alternate AWS Lambda + API Gateway deployment target for scale-to-zero web workloads.
+- [x] **Environment Hibernation & FinOps:** `grada sleep <env>` and `grada wake <env>`. Scale ECS task counts to zero, stop non-production RDS instances, guard against the AWS 7-day RDS auto-restart behavior, and display estimated hourly savings to eliminate idle staging costs.
+- [x] **Scheduled IaC Drift Detection:** `grada drift` and `--setup-ci-drift`. Generate an automated GitHub Action that periodically executes `terraform plan -detailed-exitcode` against live AWS infrastructure, opening GitHub Issues or dispatching Slack notifications when out-of-band console changes occur.
+- [x] **Dependency-Aware Init:** Scan manifests for database, worker, migration, and addon signals before prompting — pre-selecting the database question, pre-filling the worker command, pre-checking detected addons with evidence, and offering the pre-deploy migration gate — with `--with` for one-pass headless composition.
+
+### Phase 11: The `grada.run` Rebrand, Daily Observability & Agentic Ecosystem (Current)
+**Goal:** Transition the platform identity to **Grada (`grada.run`)**, close the daily observability gap with zero-cost CloudWatch Golden Signals, eliminate cross-command state-transition bugs, and launch the native MCP and AI Agent Plugin ecosystem.
+
+- [x] **Unified Brand & Binary Transition (`grada`):** Ship the `grada` binary alongside `grada-run` (plus a deprecated `deploy-stack` alias) and publish the `@grada-run/grada` scoped alias on release, keeping existing deployments working through transparent dual-read fallbacks for AWS tags, local state ledgers (`.grada/` + `.deploy-stack/`), machine markers, doc ownership markers (`GRADA.md` + `DEPLOY-STACK.md`), and environment variables. (Verified live.)
+- [ ] **AI-Driven Edge-Case & State Transition Audit:** Run a systematic codebase audit tracing multi-step lifecycle mutations across both `--target ecs` and `--target lambda` (e.g., scaffold with `--db-engine aurora-postgresql` → `add queue:sqs` → `add cron` → `db enable-vector` → `sleep` → `wake` → `drift` → `rollback` → `eject` → `destroy`), patching race conditions, partial Terraform state locks, and UX dead ends.
+- [x] **Two-Tier E2E Harness & Automation Bypasses:** Ship the black-box harness (`tests/e2e/`, Tier 0 mock-AWS suite on every PR, Tier 1 live `init` → `apply` → `status` → `destroy` lifecycle on a nightly schedule) plus `--auto-approve`/`--yes`/`--headless` bypasses for `apply`, `destroy`, and `eject`, replacing the planned LocalStack approach.
+- [ ] **Deterministic Suite & Flaky Test Elimination:** Isolate network/loopback and SDK mocks in the Vitest suite, eliminate the timing-dependent loopback failure, and record first-green Tier 0 (PR) and Tier 1 (nightly) runs.
+- [ ] **Live Service Acceptance (Tier 2 E2E):** Provision each add-on capability on real AWS (nightly) and verify runtime behavior — SQS send/receive + DLQ, DynamoDB put/get, Redis connectivity, S3 presigned-URL flow, SES send, Bedrock invoke, cron scheduling — with per-service setup/assert/teardown and spend caps.
+- [ ] **Multi-Stage Dockerfile Hardening:** Refactor generated Dockerfiles to use multi-stage builds (e.g., `node:22-alpine AS builder` → `distroless/nodejs`), explicitly stripping package managers (`npm`, `yarn`) from the final runtime image to mathematically eliminate `HIGH`/`CRITICAL` vulnerability scanner noise on Day-0.
+- [x] **Test Suite Deduplication & Hygiene:** Extract the hand-rolled `@clack/prompts` and `telemetry` mocks currently duplicated across 15+ test files into a centralized `tests/helpers/` directory to shrink maintenance surface area without dropping the 1,000+ test coverage count.
+- [ ] **Golden Signals Live Telemetry & Alert Webhooks:** Upgrade `grada status` (and `grada status --watch`) to surface real-time CloudWatch Golden Signals (ECS CPU/Memory %, ALB requests/min, p95 latency, 5xx count, and RDS connections / Aurora ACUs) at $0 extra AWS cost, and add `grada alerts` to wire CloudWatch 5xx alarms and container crash events directly to Slack, Discord, or email.
+- [ ] **Architecture Decision Records (ADRs) & Docs Audit:** Review and standardize all ADRs and Astro Starlight documentation under the `grada` brand to ensure every Phase 9–11 command, flag, compute target (`ecs` and `lambda`), and IAM security boundary is accurately documented with zero stale references.
+- [ ] **Zero-Compute Static Target (`--target static`):** Provide a dedicated target for Vite SPAs, Astro SSG, and Next.js static exports that bypasses compute entirely, deploying pre-built assets directly to an S3 bucket fronted by CloudFront.
+- [ ] **Native MCP Server Mode (`grada mcp`):** Embed a Model Context Protocol server directly inside the CLI binary exposing deterministic Day-1 (`analyze_stack`, `estimate_cost`, `add_primitive`) and Day-2 (`stack_status` with Golden Signals, `diagnose_stack`, `fetch_error_logs`, `audit_secrets`, `check_drift`) tools to AI coding assistants.
+- [ ] **Claude Code, Cursor & Codex Plugin Manifests:** Package `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `SKILL.md` playbooks so developers can install Grada natively from the Cursor Marketplace and Claude Code (`/plugin install`).
+- [ ] **Automated IDE Guardrail Hooks:** Configure agent plugin hooks that automatically run `terraform validate` after `.tf` edits and prompt `grada secrets audit` whenever new keys are added to `.env` / `.env.local`.
+- [ ] **Production Flagship Blueprint (`saas-starter`):** Publish a full-stack, production-ready SaaS reference repository (Next.js App Router + Aurora Serverless v2 PostgreSQL + Valkey/Redis + SES Transactional Email + OIDC PR Previews) deployable in one command with `grada`.
+- [ ] **Production AI Blueprint (`ai-worker`):** Publish an async AI reference repository (FastAPI + AWS Bedrock + Aurora `pgvector` + SQS scale-to-zero worker + S3 presigned ingestion) demonstrating enterprise RAG without OpenSearch costs.
+- [ ] **Serverless Scale-to-Zero Blueprint (`grada-lambda-fastapi`):** Publish a reference repository demonstrating the new `--target lambda` container image workflow with AWS Lambda Web Adapter, API Gateway HTTP API v2, and CloudFront.
+- [ ] **High-Conversion `grada.run` Launch Site:** Ship the flagship marketing front-end above the Starlight docs featuring interactive terminal demos (`grada init`, `grada status --watch`, `grada mcp`), a live PaaS-to-AWS cost savings calculator, and a visual Day-0 to Day-N capability matrix.

package/apps/docs/src/content/docs/testing-strategy.md

@@ -0,0 +1,37 @@
+---
+title: Testing Strategy
+description: How grada prevents regressions — unit tests, snapshot harness, API mocking, and CI validation.
+---
+
+To ensure zero regressions in infrastructure generation and safe local execution, `grada` relies on a multi-layered testing strategy split between fast local snapshots and rigid CI/CD validation.
+
+## 1. Unit & argument testing
+We use pure Node.js unit tests (via Vitest) to validate the CLI argument parser (`src/core/parser.js`). This ensures that flags (like `--headless` or `--no-telemetry`) are routed correctly and never hijack positional arguments like file paths.
+
+## 1.5. Ecosystem integration contracts
+Because `grada` acts as the underlying engine for ecosystem wrappers (e.g., `nest-grada`, `cookiecutter-fastapi`), we strictly test execution flags that bypass interactive prompts (written contract: `specs/integration-suite.md`, enforced by `tests/headless.test.js`):
+* **Headless Validation:** Vitest deep-mocks `@clack/prompts` — the only interactive prompt library the CLI uses — and asserts that when `--headless` and `--preconfigured` are passed (e.g., `--framework=nestjs --port=3000`), none of its prompt functions (`text`, `select`, `multiselect`, `confirm`, `group`) ever fire and no interactive warnings are thrown. The suite also asserts flag values win over interactive defaults in the generated `terraform/main.tf` and `Dockerfile`, running end to end inside a temp directory so no files pollute the repo. This guarantees stability for automated ecosystem integrations.
+
+## 2. Infrastructure snapshot harness (the static contract)
+Because `grada` generates highly dynamic Terraform (`.tf`), GitHub Actions (`.yml`), and `Dockerfile` configurations, we use **Vitest Snapshots** to lock in the expected text outputs.
+* **The Matrix:** The test suite generates dummy projects across 11 architectural topologies (including Django, Rails, Go, Nuxt, Next.js, SvelteKit, and Vercel/Heroku migrations).
+* **Negative Testing:** The suite explicitly checks for the *absence* of files (e.g., ensuring `database.tf` or `worker.tf` are not generated for static sites).
+* **Updating Snapshots:** If a template change is intentional, developers must run `npm run test:update` to overwrite the baseline `__snapshots__`.
+
+## 3. External API mocking
+To ensure tests run sub-second and deterministically without requiring real AWS credentials, we intercept network boundaries. Shared mock factories live in `tests/helpers/` (`clack.js` for `@clack/prompts`, `telemetry.js` for PostHog tracking, `console.js` for process/console spies, `tmpdir.js` for fixture directories) so new suites reuse one-liner `vi.mock` delegations instead of hand-rolling mocks:
+* **AWS Secrets Manager:** `tests/secrets.test.js` uses Vitest's `vi.hoisted()` and `vi.mock()` to intercept `@aws-sdk/client-secrets-manager` (plus an injected ECS client for the restart path). This verifies push/pull/audit payload handling, key-change detection, and network exceptions (like `ResourceNotFoundException`) completely offline.
+* **ECS & CloudWatch Logs:** `tests/diagnose.test.js` injects mock ECS/CloudWatch clients to verify failure analysis (stopped reasons, exit codes, log extraction) and behavior contracts — e.g., expired sessions (`UnrecognizedClientException`) exit gracefully with code 1, and unrecognized `secrets push` filenames fall back to `.env` with a warning.
+* **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*. 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 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.
+
+## 5. End-to-end lifecycle testing
+Black-box suites under `tests/e2e/` execute the real `bin/cli.js` via `child_process` with stdin closed (a prompt crashes loudly instead of hanging) and `DO_NOT_TRACK=1`. They are excluded from the default `npm test` run and have dedicated configs:
+* **Tier 0 (`npm run test:e2e:tier0`, every PR):** mock-AWS scaffold checks (`init` for ECS and Lambda targets, the full 7-capability `add` matrix plus an `init --with` composition, `terraform validate`), local checks (`doctor`, `eject`), and failure-path contracts (clean exit-1 shapes, no stack traces). Runs in `.github/workflows/e2e.yml` alongside Tier 1.
+* **Tier 1 (`npm run test:e2e:tier1`, nightly/manual only):** the full live lifecycle (`init` → `apply --auto-approve` → `status` with a retry-until-healthy loop → `destroy --yes`) against real AWS via OIDC, skipping gracefully without credentials.

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import path from 'path';
+import { mainStack } from '../src/commands/init.js';
+import { destroyStack } from '../src/commands/destroy.js';
+import { runDoctor } from '../src/commands/doctor.js';
+import { pushSecrets, pullSecrets, auditSecrets } 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 { runLogs, parseLogsArgs } from '../src/commands/logs.js';
+import { runStatus, parseStatusArgs } from '../src/commands/status.js';
+import { runExec, parseExecArgs } from '../src/commands/exec.js';
+import { runDb } from '../src/commands/db.js';
+import { runRollback, parseRollbackArgs } from '../src/commands/rollback.js';
+import { runGc, parseGcArgs } from '../src/commands/gc.js';
+import { runAdd, parseAddArgs } from '../src/commands/add.js';
+import { runDomain, parseDomainArgs } from '../src/commands/domain.js';
+import { runSleep, parseSleepArgs } from '../src/commands/sleep.js';
+import { runWake, parseWakeArgs } from '../src/commands/wake.js';
+import { runDrift, parseDriftArgs } from '../src/commands/drift.js';
+import { parseCliArgs } from '../src/core/parser.js';
+
+const HELP_TEXT = [
+    'grada — Provision production-ready AWS infrastructure in seconds.',
+    '',
+    'Usage:',
+    '  grada [command] [options]',
+    '',
+    'Commands:',
+    '  init                 Provision infrastructure and CI/CD pipelines',
+    '  apply                Apply infrastructure changes (--auto-approve)',
+    '  destroy              Tear down infrastructure (--yes)',
+    '  doctor               Run pre-flight dependency checks',
+    '  logs [service]       Stream CloudWatch logs (--tail, -f/--follow, --error, --since, --region)',
+    '  status               Service health dashboard (--region, --json)',
+    '  rollback [rev]       Roll back ECS service to a previous task revision',
+    '  exec                 Open an interactive shell in a running container (--cluster, --service, --container, --command, --region)',
+    '  db connect           Open a secure local tunnel to your database (--port, --show-credentials, --workspace, --region)',
+    '  db enable-vector     Enable the pgvector extension via a one-off ECS task (--task-def, --timeout)',
+    '  db import            Import a SQL dump into your database (--file, --from, --yes)',
+    '  db migrate           Run database migrations in a one-off ECS task (--cmd, --task-def, --timeout, --setup-ci)',
+    '  db backup            Create an RDS snapshot checkpoint (--id, --timeout, --no-wait)',
+    '  db restore           Restore the database from a snapshot ([snapshot-id], --yes)',
+    '  gc                   Discover and delete orphaned ECR images, log groups, and Elastic IPs (--region)',
+    '  sleep [env]          Scale ECS services to zero and stop RDS to save costs (--skip-db, --yes)',
+    '  wake [env]           Start RDS and restore ECS desired counts (--skip-db, --no-wait)',
+    '  drift                Detect Terraform drift locally or scaffold scheduled checks (--setup)',
+    '  add <capability>     Provision a modular addon (storage:s3, db:dynamodb, db:redis, queue:sqs, ai:bedrock, email:ses, cron) [--model <id>, --list-models, --refresh]',
+    '  domain add <domain>    Provision a custom domain with automated ACM TLS (--zone-id, --activate)',
+    '  domain verify|status|remove  Activate, inspect, or remove the custom domain',
+    '  secrets push         Push environment secrets',
+    '  secrets pull         Pull environment secrets',
+    '  secrets audit        Audit local vs remote secrets drift',
+    '  eject                Eject to self-managed configs (--yes)',
+    '  sync-ai              Sync AI assistant rules',
+    '',
+    'Init options:',
+    '  --target <ecs|lambda>  Compute architecture: always-on Fargate + ALB (~$31/mo flat, best for steady traffic) or scale-to-zero Lambda + API Gateway ($0/mo idle, best for sporadic traffic). Tradeoffs: Stack Architecture guide → Fargate vs Lambda.',
+];
+
+const rawArgs = process.argv.slice(2);
+const parsed = parseCliArgs(rawArgs);
+
+if (parsed.hasNoTelemetry) {
+    process.env.DO_NOT_TRACK = '1';
+}
+process.env.CLI_COMMAND = parsed.baseCommand;
+
+const { positionalArgs, isHeadless, isDryRun, isPreconfigured, autoApprove, yes: confirmYes, headlessOptions, initOptions } = parsed;
+
+function parseRegionFlag(args) {
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--region' && i + 1 < args.length) return args[i + 1];
+        if (args[i].startsWith('--region=')) return args[i].slice('--region='.length);
+    }
+    return undefined;
+}
+
+// Dispatch guard: every command promise ends here so an unexpected rejection
+// prints the error and exits non-zero instead of surfacing as an unhandled
+// rejection with a stack trace and an unpredictable exit code.
+function runCommand(promise) {
+    promise.catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
+}
+
+if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'push') {
+    const envFile = positionalArgs[2] || '.env';
+    const projectName = path.basename(process.cwd());
+    runCommand(pushSecrets(envFile, projectName, { isHeadless, region: parseRegionFlag(rawArgs) }));
+} else if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'pull') {
+    const envFile = positionalArgs[2] || '.env';
+    const projectName = path.basename(process.cwd());
+    runCommand(pullSecrets(envFile, projectName, { isHeadless, region: parseRegionFlag(rawArgs) }));
+} else if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'audit') {
+    const envFile = positionalArgs[2] || '.env';
+    const projectName = path.basename(process.cwd());
+    runCommand(auditSecrets(envFile, projectName, { region: parseRegionFlag(rawArgs) }));
+} else if (positionalArgs[0] === 'apply') {
+    runCommand(applyStack({ isDryRun, ...(autoApprove ? { autoApprove: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'doctor') {
+    runCommand(runDoctor());
+} else if (positionalArgs[0] === 'destroy') {
+    runCommand(destroyStack({ ...(confirmYes ? { yes: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'eject') {
+    runCommand(ejectStack({ ...(confirmYes ? { yes: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'sync-ai') {
+    runCommand(syncAi());
+} else if (positionalArgs[0] === 'diagnose' || positionalArgs[0] === 'wtf') {
+    runCommand(runDiagnose(headlessOptions));
+} else if (positionalArgs[0] === 'logs') {
+    runCommand(runLogs(parseLogsArgs(rawArgs)));
+} else if (positionalArgs[0] === 'status') {
+    runCommand(runStatus(parseStatusArgs(rawArgs)));
+} else if (positionalArgs[0] === 'rollback') {
+    runCommand(runRollback({ ...parseRollbackArgs(rawArgs), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'exec') {
+    runCommand(runExec(parseExecArgs(rawArgs)));
+} else if (positionalArgs[0] === 'db') {
+    runCommand(runDb(rawArgs, { ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'gc') {
+    runCommand(runGc(parseGcArgs(rawArgs)));
+} else if (positionalArgs[0] === 'add') {
+    runCommand(runAdd(parseAddArgs(rawArgs)));
+} else if (positionalArgs[0] === 'domain') {
+    runCommand(runDomain(parseDomainArgs(rawArgs)));
+} else if (positionalArgs[0] === 'sleep') {
+    runCommand(runSleep({ ...parseSleepArgs(rawArgs), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'wake') {
+    runCommand(runWake({ ...parseWakeArgs(rawArgs), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'drift') {
+    runCommand(runDrift({ ...parseDriftArgs(rawArgs), ...(isHeadless ? { isHeadless: true } : {}) }));
+} else if (positionalArgs[0] === 'help' || rawArgs.includes('--help') || rawArgs.includes('-h')) {
+    console.log(HELP_TEXT.join('\n'));
+} else {
+    runCommand(mainStack({ isHeadless, isPreconfigured, headlessOptions, initOptions }));
+}