grada-run 0.0.1 → 0.32.0

package/src/utils/visualizer.js

@@ -0,0 +1,381 @@
+import { note, confirm, isCancel, cancel } from '@clack/prompts';
+import pc from 'picocolors';
+import fs from 'fs';
+import path from 'path';
+import { ADDON_REGISTRY } from './addons.js';
+import { trackEvent, flushTelemetry, trackFailure } from '../core/telemetry.js';
+
+export const COST_ESTIMATE_MARKER = 'Estimated Fixed Monthly Baseline:';
+export const LEGACY_COST_ESTIMATE_MARKER = 'Estimated Monthly Cost:';
+
+// Cost benchmarks for AWS us-east-2 baseline (Fargate + ALB)
+const PRICING_TABLE = {
+    fargate: {
+        cpuPerHour: 0.04048,   // per vCPU hour
+        memoryPerHour: 0.004445 // per GB hour
+    },
+    alb: {
+        basePerHour: 0.0225,   // ~$16.43/month base
+        lcuPerHour: 0.008      // Baseline ~1 LCU (~$5.84/month)
+    },
+    rds: {
+        microPerHour: 0.016,   // ~$11.68/mo for db.t4g.micro
+        storagePerMonth: 2.30,  // 20GB gp3 storage baseline
+        auroraAcuPerHour: 0.12  // Serverless v2 compute when active ($0/mo idle at 0 ACU)
+    },
+    secretsManagerPerSecret: 0.40 // per secret per month
+};
+
+// 1. Parse the local terraform files to extract the actual configuration
+export function parseTerraformConfig(tfDir) {
+    const tfvarsPath = path.join(tfDir, 'terraform.tfvars');
+    let region = 'us-east-2';
+    let cpu = 256;
+    let memory = 512;
+    let framework = 'Application';
+
+    // Read rendered cpu/memory from main.tf first so non-micro sizes chosen
+    // at init time survive apply previews and README cost syncs.
+    const mainTfPath = path.join(tfDir, 'main.tf');
+    let computeTarget = 'ecs';
+    if (fs.existsSync(mainTfPath)) {
+        const mainTf = fs.readFileSync(mainTfPath, 'utf-8');
+        const renderedCpu = mainTf.match(/cpu\s*=\s*"(\d+)"/);
+        if (renderedCpu) cpu = parseInt(renderedCpu[1], 10);
+        const renderedMemory = mainTf.match(/memory\s*=\s*"(\d+)"/);
+        if (renderedMemory) memory = parseInt(renderedMemory[1], 10);
+        // Lambda projects provision the serverless function instead of ECS.
+        if (mainTf.includes('resource "aws_lambda_function"')) computeTarget = 'lambda';
+    }
+
+    // terraform.tfvars overrides rendered values when present; hard defaults
+    // apply only when neither source specifies them.
+    if (fs.existsSync(tfvarsPath)) {
+        const content = fs.readFileSync(tfvarsPath, 'utf-8');
+
+        // Use regex to pull values out of the HCL format
+        const regionMatch = content.match(/aws_region\s*=\s*"([^"]+)"/);
+        if (regionMatch) region = regionMatch[1];
+
+        const cpuMatch = content.match(/container_cpu\s*=\s*(\d+)/);
+        if (cpuMatch) cpu = parseInt(cpuMatch[1], 10);
+
+        const memoryMatch = content.match(/container_memory\s*=\s*(\d+)/);
+        if (memoryMatch) memory = parseInt(memoryMatch[1], 10);
+    }
+
+    // Check if database files exist
+    const hasDb = fs.existsSync(path.join(tfDir, 'rds.tf')) || fs.existsSync(path.join(tfDir, 'database.tf'));
+    const hasWorker = fs.existsSync(path.join(tfDir, 'worker.tf'));
+    const hasSecrets = fs.existsSync(path.join(tfDir, 'secrets.tf'));
+
+    // Detect the provisioned engine from database.tf content (Aurora
+    // cluster first, then MySQL; anything else is standard PostgreSQL).
+    let dbEngine = 'postgres';
+    if (hasDb) {
+        const databaseTfPath = path.join(tfDir, 'database.tf');
+        if (fs.existsSync(databaseTfPath)) {
+            const databaseTf = fs.readFileSync(databaseTfPath, 'utf-8');
+            if (databaseTf.includes('resource "aws_rds_cluster"')) {
+                dbEngine = 'aurora-postgresql';
+            } else if (/engine\s*=\s*"mysql"/.test(databaseTf)) {
+                dbEngine = 'mysql';
+            }
+        }
+    }
+
+    // Registry-driven addon detection: capability keys whose .tf file exists.
+    const addons = [];
+    for (const [capability, entry] of Object.entries(ADDON_REGISTRY)) {
+        if (!entry) continue;
+        if (fs.existsSync(path.join(tfDir, entry.file))) addons.push(capability);
+    }
+
+    return { framework, region, cpu, memory, hasDb, dbEngine, hasWorker, hasSecrets, addons, computeTarget };
+}
+
+// 2. Calculate itemized monthly costs based on task definition settings
+export function estimateMonthlyCost({ cpu = 256, memory = 512, hasDb = false, dbEngine = 'postgres', hasWorker = false, hasSecrets = false, addons = [], computeTarget = 'ecs' }) {
+    const vCpu = cpu / 1024;
+    const memGb = memory / 1024;
+    const hoursInMonth = 730;
+
+    // If a worker service exists, we are running a second identical Fargate task.
+    // Lambda web functions are scale-to-zero (usage-based, $0 fixed); only a
+    // hand-attached Fargate worker would still bill.
+    const taskMultiplier = computeTarget === 'lambda' ? (hasWorker ? 1 : 0) : (hasWorker ? 2 : 1);
+
+    const fargateCost = ((vCpu * PRICING_TABLE.fargate.cpuPerHour) +
+        (memGb * PRICING_TABLE.fargate.memoryPerHour)) * hoursInMonth * taskMultiplier;
+    // API Gateway HTTP API v2 is usage-based ($1.00 per million requests)
+    // with no fixed hourly baseline.
+    const albCost = computeTarget === 'lambda'
+        ? 0
+        : (PRICING_TABLE.alb.basePerHour + PRICING_TABLE.alb.lcuPerHour) * hoursInMonth;
+    // Aurora Serverless v2 idles at 0 ACU: $0/mo idle compute baseline
+    // (+$0.12/ACU-hr when active); managed instances bill the micro rate.
+    const dbCost = !hasDb
+        ? 0
+        : dbEngine === 'aurora-postgresql'
+            ? 0
+            : (PRICING_TABLE.rds.microPerHour * hoursInMonth) + PRICING_TABLE.rds.storagePerMonth;
+
+    // Secrets Manager bills per secret: one for the base app-secrets JSON
+    // secret plus one for the RDS managed master password when hasDb is true.
+    const secretCount = (hasSecrets ? 1 : 0) + (hasDb ? 1 : 0);
+    const secretsCost = secretCount * PRICING_TABLE.secretsManagerPerSecret;
+
+    // Future addons may carry a fixed monthly fee via cost.monthlyFixed.
+    let addonsFixedCost = 0;
+    for (const key of addons || []) {
+        const entry = ADDON_REGISTRY[key];
+        if (!entry) continue;
+        if (entry.cost && entry.cost.monthlyFixed > 0) addonsFixedCost += entry.cost.monthlyFixed;
+    }
+
+    const total = fargateCost + albCost + dbCost + secretsCost + addonsFixedCost;
+
+    return {
+        fargateMonthly: fargateCost.toFixed(2),
+        albMonthly: albCost.toFixed(2),
+        dbMonthly: dbCost.toFixed(2),
+        secretsMonthly: secretsCost.toFixed(2),
+        totalMonthly: total.toFixed(2)
+    };
+}
+
+// FinOps savings while an environment sleeps: paused Fargate replicas plus
+// paused RDS compute. Storage, ALB, and Secrets Manager keep billing, so
+// they are excluded here. Aurora Serverless v2 idles at 0 ACU, so its
+// compute savings are $0 (stopping only prevents active wake-ups).
+export function estimateSleepSavings({ cpu = 256, memory = 512, hasDb = false, dbEngine = 'postgres', appReplicas = 1, workerReplicas = 0 } = {}) {
+    const vCpu = cpu / 1024;
+    const memGb = memory / 1024;
+    const hoursInMonth = 730;
+    const perReplicaMonthly = ((vCpu * PRICING_TABLE.fargate.cpuPerHour)
+        + (memGb * PRICING_TABLE.fargate.memoryPerHour)) * hoursInMonth;
+    const fargateMonthly = perReplicaMonthly * (Math.max(0, appReplicas) + Math.max(0, workerReplicas));
+    const dbComputeMonthly = !hasDb || dbEngine === 'aurora-postgresql'
+        ? 0
+        : PRICING_TABLE.rds.microPerHour * hoursInMonth;
+    const monthly = fargateMonthly + dbComputeMonthly;
+    return {
+        fargateMonthly: fargateMonthly.toFixed(2),
+        dbComputeMonthly: dbComputeMonthly.toFixed(2),
+        monthly: monthly.toFixed(2),
+        hourly: (monthly / hoursInMonth).toFixed(3),
+    };
+}
+
+// Visible width of a styled line (ANSI escapes don't occupy columns).
+function visibleLength(text) {
+    return String(text).replace(/\[[0-9;]*m/g, '').length;
+}
+
+function formatBaselineLine(totalMonthly, parts, suffix = '') {
+    const breakdown = parts.length > 0 && suffix
+        ? `${parts.join(', ')} ${suffix}`
+        : [...parts, suffix].filter(Boolean).join(', ');
+    return `${pc.bold('Fixed Baseline:')} ${pc.green(pc.bold(`~$${totalMonthly}/mo`))} ${pc.dim(`(${breakdown})`)}`;
+}
+
+// Builds the Fixed Baseline line, folding Secrets/Addons into a compact
+// `+$X other` part when the full breakdown would exceed 90 visible columns.
+export function buildBaselineLine(totalMonthly, costParts, secretsMonthly = 0, addonsMonthly = 0, suffix = '') {
+    const full = formatBaselineLine(totalMonthly, costParts, suffix);
+    if (visibleLength(full) <= 90) return full;
+
+    const folded = (Number(secretsMonthly) || 0) + (Number(addonsMonthly) || 0);
+    const compactParts = costParts.filter(
+        (part) => !part.startsWith('Secrets: ') && !part.startsWith('Addons: ')
+    );
+    if (folded > 0) compactParts.push(`+$${folded.toFixed(2)} other`);
+    const compact = formatBaselineLine(totalMonthly, compactParts, suffix);
+    if (visibleLength(compact) <= 90) return compact;
+
+    const bare = `${pc.bold('Fixed Baseline:')} ${pc.green(pc.bold(`~$${totalMonthly}/mo`))}`;
+    return suffix ? `${bare} ${pc.dim(`(${suffix})`)}` : bare;
+}
+
+// Topology line for the managed database, per provisioned engine.
+function dbTopologyLabel(dbEngine) {
+    if (dbEngine === 'aurora-postgresql') {
+        return `✨ ${pc.yellow('Amazon Aurora PostgreSQL')} (Serverless v2 · 0–2 ACU scale-to-zero)`;
+    }
+    if (dbEngine === 'mysql') {
+        return `🐬 ${pc.yellow('Amazon RDS')} (MySQL managed instance)`;
+    }
+    return `🐘 ${pc.yellow('Amazon RDS')} (PostgreSQL managed instance)`;
+}
+
+// 3. Render the terminal architecture visualization and requests confirmation
+export async function renderDryRunPreview(config, isDryRunFlag = false) {
+    const { framework = 'Node.js', region = 'us-east-2', cpu = 256, memory = 512, hasDb = false, dbEngine = 'postgres', hasWorker = false, hasSecrets = false, addons = [], computeTarget = 'ecs' } = config;
+    const isLambda = computeTarget === 'lambda';
+
+    // Fixed the duplicate hasWorker argument
+    const cost = estimateMonthlyCost({ cpu, memory, hasDb, dbEngine, hasWorker, hasSecrets, addons, computeTarget });
+
+    const hourlyRate = (Number(cost.totalMonthly) / 730).toFixed(3); // 730 hours in a month
+    const secretCount = (hasSecrets ? 1 : 0) + (hasDb ? 1 : 0);
+
+    const validAddons = (addons || []).filter((key) => Boolean(ADDON_REGISTRY[key]));
+
+    let addonsMonthly = 0;
+    for (const key of validAddons) {
+        addonsMonthly += ADDON_REGISTRY[key]?.cost?.monthlyFixed || 0;
+    }
+
+    // Lambda compute and API Gateway are usage-based with no fixed
+    // baseline, so the Lambda breakdown starts at the database.
+    const costParts = isLambda
+        ? []
+        : [`Fargate: $${cost.fargateMonthly}`, `ALB: $${cost.albMonthly}`];
+    if (hasDb) costParts.push(`RDS: $${cost.dbMonthly}`);
+    const secretsMonthly = Number(cost.secretsMonthly) || 0;
+    if (secretsMonthly > 0) costParts.push(`Secrets: $${cost.secretsMonthly}`);
+    if (addonsMonthly > 0) costParts.push(`Addons: $${addonsMonthly.toFixed(2)}`);
+
+    const addonNodes = [];
+    if (validAddons.length >= 3) {
+        addonNodes.push(`  ${pc.gray('├──')} 🧩 [${pc.bold(`Addons (${validAddons.length}): ${validAddons.join(', ')}`)}]`);
+    } else {
+        for (const key of validAddons) {
+            const entry = ADDON_REGISTRY[key];
+            addonNodes.push(`  ${pc.gray('├──')} 🧩 [${pc.bold(entry.label)}] ${pc.dim(`(${key})`)}`);
+        }
+    }
+    const usageBasedCount = validAddons.filter((key) => (ADDON_REGISTRY[key]?.cost?.monthlyFixed || 0) === 0).length;
+    const usageLine = usageBasedCount > 0
+        ? `  + Usage-based (${usageBasedCount} addon${usageBasedCount === 1 ? '' : 's'}): $0/mo fixed · per request, storage & egress`
+        : '';
+
+    const baselineLine = buildBaselineLine(cost.totalMonthly, costParts, secretsMonthly, addonsMonthly, isLambda ? '+ API GW & Lambda usage' : '');
+
+    // Flattened the tree to eliminate nesting and vertical bloat
+    const treeOutput = [
+        `${pc.bold('Topology')} (${pc.cyan(region)}):`,
+        isLambda
+            ? `  ${pc.gray('├──')} 🌐 ${pc.bold('API Gateway HTTP API v2')} (Scale-to-zero HTTPS entry)`
+            : `  ${pc.gray('├──')} 🌐 ${pc.bold('ALB')} (Public Entry & Health: ${pc.green('200 OK')})`,
+        `  ${pc.gray('├──')} 🔒 ${pc.bold('IAM OIDC')} (GitHub Auth) & 🐳 ${pc.bold('ECR')} (Registry)`,
+        hasDb ? `  ${pc.gray('├──')} ${dbTopologyLabel(dbEngine)}` : '',
+        secretCount > 0 ? `  ${pc.gray('├──')} 🔑 [${pc.bold('Secrets Manager')} (${secretCount === 1 ? '1 secret' : `${secretCount} secrets`})]` : '',
+        ...addonNodes,
+        isLambda
+            ? `  ${pc.gray('└──')} ⚡ ${pc.bold('AWS Lambda Web Service')} 🟢 ${pc.green(framework)} [512 MB · Scale-to-zero]`
+            : `  ${pc.gray(hasWorker ? '├──' : '└──')} 📦 ${pc.bold('ECS Web Service')} 🟢 ${pc.green(framework)} [${cpu} CPU / ${memory} MB]`,
+        !isLambda && hasWorker ? `  ${pc.gray('└──')} 📦 ${pc.bold('ECS Worker Service')} 🔄 Background Tasks [${cpu} CPU / ${memory} MB]` : '',
+        '',
+        baselineLine,
+        usageLine,
+        `  ${pc.dim(`* ~$${hourlyRate}/hr (us-east-2 rates) · Destroy anytime: "npx grada-run destroy"`)}`
+    ].filter(Boolean).join('\n');
+
+    note(treeOutput, 'Cloud Infrastructure Pre-Flight Inspection');
+
+    // 4. Check if this is a dry run (print & exit) or full apply (prompt & proceed)
+    if (isDryRunFlag) {
+        return true;
+    }
+
+    const shouldProceed = await confirm({
+        message: 'Review completed. Provision this infrastructure to AWS now?',
+        initialValue: true
+    });
+
+    if (isCancel(shouldProceed) || !shouldProceed) {
+        cancel('Operation canceled. No infrastructure was created.');
+        await trackFailure('infrastructure_applied', {
+            status: 'cancelled_at_preview',
+            ...buildCostTelemetryProps(config, cost),
+        });
+        process.exit(0);
+    }
+
+    return true;
+}
+
+// Shared cost/shape telemetry properties so visualizer.js and apply.js emit
+// the exact same shape. projectName flows into telemetry's hashed distinct_id,
+// keeping per-project funnels joinable without storing raw names.
+export function buildCostTelemetryProps(config = {}, costs = estimateMonthlyCost(config)) {
+    return {
+        projectName: config.projectName || path.basename(process.cwd()),
+        estimated_monthly_usd: Number(costs.totalMonthly),
+        compute_target: config.computeTarget || 'ecs',
+        cpu: config.cpu ?? 256,
+        memory: config.memory ?? 512,
+        has_db: Boolean(config.hasDb),
+        db_engine: config.hasDb ? (config.dbEngine || 'postgres') : 'none',
+        has_worker: Boolean(config.hasWorker),
+        addons: config.addons || [],
+        addon_count: (config.addons || []).length,
+    };
+}
+
+const DOC_COST_LINE = (total) =>
+    `* **${COST_ESTIMATE_MARKER}** ~$${total}/month (us-east-2 reference rates; excludes variable traffic, ECR/CloudWatch storage, and usage-based addons)`;
+
+function buildActiveAddonsSection(addons = []) {
+    const lines = [];
+    for (const key of addons || []) {
+        const entry = ADDON_REGISTRY[key];
+        if (!entry) continue;
+        lines.push(`- \`${key}\` (${entry.label}): ${entry.cost.summary}`);
+    }
+    if (lines.length === 0) return '';
+    return ['### Active Addons (Usage-Based)', '', ...lines].join('\n');
+}
+
+// Refresh the cost baseline (and usage-based addon list) in the generated
+// deployment docs after `grada add`. Checks DEPLOYMENT.md, README.md,
+// GRADA.md, then legacy DEPLOY-STACK.md; no-ops gracefully when no file
+// exists or the user removed the cost marker. Returns the updated file
+// path, or null when untouched.
+export function syncDocCostEstimate(cwd = process.cwd()) {
+    const tfDir = path.join(cwd, 'terraform');
+    if (!fs.existsSync(path.join(tfDir, 'main.tf'))) return null;
+
+    let targetPath = null;
+    for (const name of ['DEPLOYMENT.md', 'README.md', 'GRADA.md', 'DEPLOY-STACK.md']) {
+        const candidate = path.join(cwd, name);
+        if (!fs.existsSync(candidate)) continue;
+        const content = fs.readFileSync(candidate, 'utf-8');
+        if (content.includes(COST_ESTIMATE_MARKER) || content.includes(LEGACY_COST_ESTIMATE_MARKER)) {
+            targetPath = candidate;
+            break;
+        }
+    }
+    if (!targetPath) return null;
+
+    const detected = parseTerraformConfig(tfDir);
+    const costs = estimateMonthlyCost(detected);
+
+    const lines = fs.readFileSync(targetPath, 'utf-8').split('\n');
+    const markerIdx = lines.findIndex(
+        (line) => line.includes(COST_ESTIMATE_MARKER) || line.includes(LEGACY_COST_ESTIMATE_MARKER)
+    );
+    if (markerIdx === -1) return null;
+    lines[markerIdx] = DOC_COST_LINE(costs.totalMonthly);
+
+    // Drop any previously rendered Active Addons section (heading, blank
+    // separators, and our `- \`key\`` bullets) so reruns replace rather than
+    // duplicate it. Anything else is user content and stays untouched.
+    const sectionIdx = lines.findIndex((line) => line.trim() === '### Active Addons (Usage-Based)');
+    if (sectionIdx !== -1) {
+        let endIdx = sectionIdx + 1;
+        while (endIdx < lines.length && lines[endIdx].trim() === '') endIdx++;
+        while (endIdx < lines.length && lines[endIdx].trim().startsWith('- `')) endIdx++;
+        lines.splice(sectionIdx, endIdx - sectionIdx);
+        if (lines[sectionIdx] === '' && lines[sectionIdx + 1] === '') lines.splice(sectionIdx, 1);
+    }
+
+    const section = buildActiveAddonsSection(detected.addons);
+    if (section) {
+        lines.splice(markerIdx + 1, 0, '', section);
+    }
+
+    fs.writeFileSync(targetPath, lines.join('\n'));
+    return targetPath;
+}

package/src/utils/warnings.js

@@ -0,0 +1,49 @@
+import color from 'picocolors';
+
+export function getFrameworkWarning(frameworkId) {
+    switch (frameworkId) {
+        case 'nestjs':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: NESTJS SETUP REQUIRED ')) +
+                color.yellow('\n    You must ensure your app binds to 0.0.0.0 to receive traffic in AWS Fargate.') +
+                color.yellow('\n    In src/main.ts, update your bootstrap function to:') +
+                color.green('\n    await app.listen(process.env.PORT ?? 3000, \'0.0.0.0\');\n\n')
+            );
+        case 'nextjs':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: NEXT.JS SETUP REQUIRED ')) +
+                color.yellow('\n    You must modify your next.config file and create a health check route before deploying.') +
+                color.yellow('\n    See the "Critical Application Prerequisites" section in your README.md for copy-paste code.\n\n')
+            );
+        case 'node':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: NODE.JS SETUP REQUIRED ')) +
+                color.yellow('\n    1. Ensure your package.json has a "start" script (e.g., "start": "node index.js").') +
+                color.yellow('\n    2. Your app must listen on 0.0.0.0 (not localhost) to receive traffic in Docker.\n\n')
+            );
+        case 'python':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: PYTHON SETUP REQUIRED ')) +
+                color.yellow('\n    1. Ensure your requirements.txt includes your web framework (e.g., fastapi, uvicorn).') +
+                color.yellow('\n    2. Your app must listen on 0.0.0.0 (not localhost) to receive traffic in Docker.') +
+                color.yellow('\n    3. Ensure your app has a health check route returning 200 OK.\n\n')
+            );
+        case 'rails':
+            return (
+                color.bgYellow(color.black(' ℹ️  RAILS DOCKERFILE REPLACED ')) +
+                color.yellow('\n    1. We safely backed up your default Rails Dockerfile to Dockerfile.bak.') +
+                color.yellow('\n    2. We replaced it with an Alpine multi-stage build to guarantee 0 CVEs and AWS ALB compatibility.') +
+                color.yellow('\n    3. If you use SQLite locally but provisioned RDS, ensure the "pg" gem is in your Gemfile.\n\n')
+            );
+        case 'static':
+            return (
+                color.bgYellow(color.black(' ⚠️  IMPORTANT: STATIC SITE SETUP REQUIRED ')) +
+                color.yellow('\n    1. Open your generated Dockerfile.') +
+                color.yellow('\n    2. We defaulted your output folder to /app/dist.') +
+                color.yellow('\n    3. If your framework uses a different folder (like build/ or out/), change it in the COPY command.') +
+                color.yellow('\n    4. Ensure your package.json has a "build" script (e.g., "vite build").\n\n')
+            );
+        default:
+            return '';
+    }
+}

package/templates/README.md

@@ -0,0 +1,150 @@
+# {{PROJECT_NAME}} - Cloud Infrastructure
+
+> ⚡ **This infrastructure and CI/CD pipeline was auto-generated by [grada](https://github.com/grada-run/grada).** 
+> 
+> It contains a production-ready AWS ECS Fargate architecture and a zero-secret GitHub Actions deployment pipeline.
+
+## 🏗️ Architecture Overview
+
+Your application has been configured for an enterprise-grade AWS deployment. Instead of relying on a black-box PaaS, you now own the underlying infrastructure:
+* **Compute:** Your app is packaged into a Docker container and runs on **AWS ECS Fargate** (Serverless compute, meaning no EC2 instances to manage).
+* **Networking:** Traffic flows through an **Application Load Balancer (ALB)**, which sits inside a custom VPC across multiple Availability Zones for high availability.
+* **Security:** Deployments are handled via GitHub Actions using **AWS IAM OIDC**. This means GitHub securely requests temporary tokens to deploy your code—no long-lived AWS keys are stored anywhere.
+* **State Management:** Terraform state is securely backed by an encrypted S3 bucket with native S3 locking.
+* **Modular Addons:** Extend this stack anytime with `npx grada-run add storage:s3` (private S3 + CDN), `db:dynamodb` (serverless NoSQL), `db:redis` (Valkey caching), `queue:sqs` (SQS queue + DLQ), or `ai:bedrock` (Bedrock AI models). Added resources appear in `terraform/` and your container environment automatically — see `grada add --help`.
+
+## 💰 Cost Estimate & Disclaimer
+
+This infrastructure provisions a highly available Application Load Balancer (ALB) and an ECS Fargate container (Size: **{{COMPUTE_TIER}}**).
+    
+* **Estimated Fixed Monthly Baseline:** ~${{ESTIMATED_COST}}/month (us-east-2 reference rates; excludes variable traffic, ECR/CloudWatch storage, and usage-based addons)
+* *Note: AWS bills by the hour. If you destroy this stack after a few hours of testing, it will cost less than $0.20.*
+
+> **⚠️ DISCLAIMER:** This cost is a rough estimate. AWS pricing changes and varies by region. **You are solely responsible for all AWS charges incurred by deploying this infrastructure.** The creators of `grada` are not liable for unexpected cloud costs, compromised credentials, or runaway billing. Always monitor your AWS Billing Dashboard and set up budget alerts.
+
+## 🚀 Deployment Guide
+
+1. **Initial Provisioning:**
+   Ensure you have configured your AWS CLI locally, then run the native deploy command:
+   ```bash
+   npx grada-run apply
+   ```
+   *(Alternatively, run `cd terraform && terraform init && terraform apply`)*
+
+2. **Push Secrets (Optional):**
+   If your application requires environment variables, create a local `.env` file and sync it directly to AWS Secrets Manager:
+   ```bash
+   npx grada-run secrets push .env
+   ```
+
+3. **Automated CI/CD:**
+   Push this repository to GitHub. Your deployment pipeline uses the official [Grada GitHub Action](https://github.com/marketplace/actions/deploy-stack-aws-fargate-terraform-deploy). Every push to `{{DEPLOY_BRANCH}}` will automatically run your infrastructure changes, build your container, and deploy your application.
+
+### 📟 Day-2 Operations
+Once live, manage the stack without opening the AWS console:
+* `npx grada-run status` — service health dashboard (auto-runs `diagnose` on degradation)
+* `npx grada-run logs --error` — CloudWatch logs, error-filtered
+* `npx grada-run rollback` — return to the previous task revision
+* `npx grada-run db connect` — local tunnel into private RDS
+* `npx grada-run add <capability>` — attach S3, DynamoDB, Valkey, SQS, or Bedrock later (`--list-models` shows available AI models)
+
+### ⚠️ Troubleshooting: OIDC Provider Already Exists
+If `terraform apply` fails with `EntityAlreadyExists` for the OIDC provider, this AWS account already has a GitHub Actions provider (AWS permits one per account). Set `create_oidc_provider` to `false` in `terraform/oidc.tf`:
+```hcl
+variable "create_oidc_provider" {
+  type    = bool
+  default = false # <--- Change this from true to false
+}
+```
+Re-run `npx grada-run apply` to link directly to your existing provider.
+
+## 🛑 Safe Teardown (Destroying the Stack)
+
+If you are done testing and want to stop all AWS billing, you must destroy the infrastructure. 
+
+Run the automated teardown command from the root of your project:
+```bash
+npx grada-run destroy
+```
+*Type `yes` when prompted. This will execute a safe Terraform teardown of your Load Balancer, ECS cluster, and networking components. You will then be asked whether to also empty and delete your remote S3 state bucket (kept by default, so you can re-provision later with `npx grada-run apply`).*
+
+## ⚠️ Critical Application Prerequisites
+
+Before you push your code to GitHub, ensure your application is configured to run inside a Docker container and respond to AWS Load Balancer health checks.
+
+### 1. The Health Check Route (All Frameworks)
+
+AWS constantly pings your container to ensure it is alive. If you configured a custom health check path (e.g., `/api/health`) during the CLI setup, **you must create that route in your application**. If AWS receives a `404 Not Found`, it will assume your app is broken and terminate the container.
+
+Make sure your app returns a `200 OK` at your configured path:
+
+* **Next.js (App Router):** Create `app/api/health/route.ts` returning a 200 response.
+* **NestJS:** No action required if your health check path is `/` (the default `AppController` handles this). If you configured a custom path, create a specific controller for it returning a 200 response.
+* **Express.js:** Add `app.get('/api/health', (req, res) => res.sendStatus(200));`
+* **FastAPI/Python:** Add `@app.get("/api/health")` returning a 200 status.
+* **Ruby on Rails:** Rails 7.1+ includes a default `/up` health check. Ensure `Rails.application.config.force_ssl = true` isn't blocking HTTP health checks from the ALB.
+* **Django:** Add a simple view in `urls.py` that returns `HttpResponse("OK", status=200)` at your configured path.
+* **Go:** Add a handler to your mux: `http.HandleFunc("/api/health", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) })` and listen on your configured port (e.g., `http.ListenAndServe(":{{PORT}}", nil)`).
+* **Nuxt 3:** Create a server route at `server/routes/health.ts` returning `200`.
+
+### 2. Enable Standalone Output (Next.js ONLY)
+
+Next.js must be configured in "standalone" mode so it can bundle a minimal Node.js server. Without this, your GitHub Actions Docker build will crash.
+    
+Open `next.config.js` or `next.config.ts` in your root directory and add `output: 'standalone'`:
+
+```typescript
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  output: 'standalone', // <--- Add this exact line
+};
+
+export default nextConfig;
+```
+
+### 3. Container Network Binding (Node & Python)
+
+When running inside a Docker container, your server must bind to all network interfaces (`0.0.0.0`), not just `localhost` or `127.0.0.1`. If you bind to localhost, the AWS Load Balancer will not be able to route traffic to your application.
+
+Make sure your app is configured correctly:
+* **NestJS:** Update `src/main.ts` to `await app.listen(process.env.PORT ?? 3000, '0.0.0.0');`
+* **Express.js:** `app.listen(port, '0.0.0.0', () => ...)`
+* **FastAPI:** `uvicorn.run(app, host="0.0.0.0", port=8000)`
+* **Ruby on Rails:** Bound automatically by the CLI's Puma command (`-b tcp://0.0.0.0:{{PORT}}`).
+* **Django:** Bound automatically by the CLI's Gunicorn command (`--bind 0.0.0.0:{{PORT}}`).
+* **Go:** Ensure your `ListenAndServe` string looks like this: `http.ListenAndServe(":8080", nil)` or `http.ListenAndServe("0.0.0.0:8080", nil)`.
+* **Nuxt 3:** Bound automatically via the `NITRO_HOST=0.0.0.0` environment variable injected by the CLI Dockerfile.
+
+### 4. Static Sites (Vite, Astro, React, Vue, SvelteKit)
+
+If you are deploying a static site, your application is served via a highly optimized, unprivileged Nginx container. 
+* **Zero-Config Build:** The CLI automatically detected your framework's output folder (`dist`, `build`, etc.) and pre-configured your Dockerfile. 
+* **Health Checks:** You do not need to configure a custom `/health` route. Nginx will automatically return a `200 OK` when AWS pings the root `/` index page.
+
+### 5. Database Connections (Backend Frameworks Only)
+If you opted to include a managed AWS RDS PostgreSQL database, the infrastructure automatically creates the database in isolated private subnets and injects the credentials into your container's environment variables. 
+
+Ensure your backend framework (Rails, Django, Go, etc.) is configured to consume these variables at runtime:
+* `DB_HOST`: The AWS RDS endpoint URL
+* `DB_PORT`: `5432`
+* `DB_NAME`: The auto-formatted database name
+* `DB_USER`: The hardcoded master username (dbadmin)
+* `DB_PASSWORD`: The securely injected master password (sourced from AWS Secrets Manager)
+
+### 6. Framework Adapters (SvelteKit & Astro ONLY)
+
+SvelteKit and Astro must build for Node.js, not Vercel — otherwise your Docker build will fail.
+* **SvelteKit:** Use `@sveltejs/adapter-node` in `svelte.config.js` (replace `adapter-vercel` or `adapter-auto`).
+* **Astro:** Use `@astrojs/node` as the adapter in `astro.config.mjs` (replace `@astrojs/vercel`).
+
+## 🛡️ Security Scanning
+
+This pipeline includes automated DevSecOps guardrails using [Trivy](https://trivy.dev/). 
+Every time you push code, the pipeline will scan both your Docker container and your 
+Terraform configurations for vulnerabilities and misconfigurations. 
+
+To view the security reports:
+1. Navigate to the **Actions** tab in GitHub.
+2. Click on the latest deployment run.
+3. Scroll down the **Summary** page to view the generated vulnerability tables.

package/templates/docker/django.Dockerfile

@@ -0,0 +1,40 @@
+FROM python:3.12-alpine
+
+# --- DevSecOps Patch: Upgrade Alpine system packages to clear OS-level CVEs ---
+RUN apk upgrade --no-cache
+
+# Prevent Python from writing .pyc files and buffer stdout for cleaner logs
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Create unprivileged user (Alpine syntax)
+RUN addgroup -g 1001 appgroup && \
+    adduser -u 1001 -G appgroup -s /bin/sh -D appuser
+
+# Install runtime libraries and temporary build tools
+RUN apk update && \
+    apk add --no-cache libpq && \
+    apk add --no-cache --virtual .build-deps gcc musl-dev postgresql-dev
+
+COPY requirements.txt .
+
+# Upgrade pip, install dependencies, clear caches, and NUKE package managers
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel && \
+    pip install --no-cache-dir -r requirements.txt gunicorn && \
+    find / -type d -name "ensurepip" -exec rm -rf {} + || true && \
+    rm -rf /root/.cache/pip && \
+    pip uninstall -y setuptools wheel pip
+
+# Remove the build tools to shrink the image and reduce attack surface
+RUN apk del .build-deps
+
+# Copy code with explicit ownership
+COPY --chown=appuser:appgroup . .
+
+USER appuser
+EXPOSE {{PORT}}
+
+# Run Gunicorn using the dynamically injected WSGI module
+CMD ["gunicorn", "--bind", "0.0.0.0:{{PORT}}", "--workers", "3", "{{DJANGO_WSGI}}:application"]

package/templates/docker/go.Dockerfile

@@ -0,0 +1,23 @@
+# Stage 1: Compile
+FROM golang:1.26-alpine AS builder
+WORKDIR /app
+COPY go.mod go.sum* ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 GOOS=linux go build -o /main .
+
+# Stage 2: Production runner
+FROM alpine:3.20
+WORKDIR /app
+
+# Create unprivileged user
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -S appuser -u 1001 -G appgroup
+
+# Copy compiled binary with explicit ownership
+COPY --from=builder --chown=appuser:appgroup /main /main
+
+USER appuser
+EXPOSE {{PORT}}
+
+CMD ["/main"]