@grada-run/grada 0.0.1 → 0.33.0

package/package.json

@@ -1,15 +1,115 @@
 {
   "name": "@grada-run/grada",
-  "version": "0.0.1",
-  "description": "Grada CLI — Open-hood cloud infrastructure from Day 0 to Day N.",
-  "homepage": "https://grada.run",
+  "version": "0.33.0",
+  "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "workspaces": [
+    "apps/*"
+  ],
+  "bin": {
+    "grada": "bin/cli.js",
+    "grada-run": "bin/cli.js",
+    "deploy-stack": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:update": "vitest run -u",
+    "test:iac": "node scripts/test-iac.js",
+    "test:e2e:tier0": "vitest run -c vitest.e2e.tier0.config.js",
+    "test:e2e:tier1": "vitest run -c vitest.e2e.tier1.config.js",
+    "sync:bedrock-models": "node scripts/sync-bedrock-models.js",
+    "docs:dev": "npm run dev --workspace=apps/docs",
+    "docs:build": "npm run build --workspace=apps/docs"
+  },
+  "author": "grada-run",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/grada-run/grada.git"
   },
-  "bin": {
-    "grada": "index.js",
-    "grada-run": "index.js"
+  "homepage": "https://github.com/grada-run/grada#readme",
+  "bugs": {
+    "url": "https://github.com/grada-run/grada/issues"
+  },
+  "keywords": [
+    "aws",
+    "terraform",
+    "infrastructure-as-code",
+    "devops",
+    "cli",
+    "github-actions",
+    "ci-cd",
+    "oidc",
+    "serverless",
+    "ecs",
+    "fargate",
+    "cloudfront",
+    "cdn",
+    "rds",
+    "postgres",
+    "redis",
+    "dynamodb",
+    "sqs",
+    "ses",
+    "transactional-email",
+    "nodejs",
+    "expressjs",
+    "nestjs",
+    "nextjs",
+    "nextjs-deployment",
+    "python",
+    "fastapi",
+    "django",
+    "rails",
+    "golang",
+    "sveltekit",
+    "nuxt",
+    "nuxtjs",
+    "astro",
+    "static-site",
+    "nginx",
+    "docker",
+    "docker-compose",
+    "heroku",
+    "vercel",
+    "custom-domains",
+    "ssl",
+    "route53",
+    "bedrock",
+    "generative-ai",
+    "preview-environments",
+    "zero-downtime",
+    "rollback",
+    "secrets-management",
+    "background-jobs",
+    "database-migrations",
+    "cost-optimization",
+    "deploy-stack",
+    "grada",
+    "grada-run"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-bedrock": "3.1119.0",
+    "@aws-sdk/client-cloudwatch": "3.1119.0",
+    "@aws-sdk/client-cloudwatch-logs": "3.1119.0",
+    "@aws-sdk/client-dynamodb": "3.1119.0",
+    "@aws-sdk/client-ec2": "3.1119.0",
+    "@aws-sdk/client-ecr": "3.1119.0",
+    "@aws-sdk/client-ecs": "3.1119.0",
+    "@aws-sdk/client-rds": "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",
+    "@clack/prompts": "1.7.0",
+    "dotenv": "17.4.2",
+    "js-yaml": "5.4.1",
+    "picocolors": "1.1.1"
   },
-  "license": "MIT"
+  "devDependencies": {
+    "vitest": "5.0.0"
+  }
 }

package/scripts/sync-bedrock-models.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Maintainer script: refresh the bundled Bedrock model catalog from live AWS
+// data, pruning models that are no longer available. Run with local AWS
+// credentials (`npm run sync:bedrock-models`) or via the weekly workflow.
+// Exits non-zero when live models arrive without family hint rules so the
+// catalog never silently accumulates generic entries.
+import path from 'path';
+import { refreshBedrockCatalog, validateCatalogHints } from '../src/utils/bedrock-catalog.js';
+
+const target = path.resolve('src/data/bedrock-models.json');
+const catalog = await refreshBedrockCatalog({ cachePath: target, pruneMissing: true });
+const modelCount = catalog.providers.reduce((total, group) => total + group.models.length, 0);
+console.log(
+    `Synced ${modelCount} models across ${catalog.providers.length} providers ` +
+    `to src/data/bedrock-models.json (updatedAt=${catalog.updatedAt}).`
+);
+
+const result = validateCatalogHints(catalog);
+if (!result.ok) {
+    console.error(`::error file=src/utils/bedrock-catalog.js::Unrecognized Bedrock model families missing hint rules: ${result.unmatchedModels.map(m => m.id).join(', ')}. Update generateHintForModel() in src/utils/bedrock-catalog.js.`);
+    process.exit(1);
+}

package/scripts/test-iac.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// Local parity check for the Terraform + TFLint steps in
+// .github/workflows/iac-validation.yml (no Docker builds or Trivy scans).
+// Scaffolds a base project, a full addons + domain project, one project per
+// non-default database engine, and the Lambda equivalents (base, full
+// Aurora addons + domain, MySQL conversion) in temp dirs, runs
+// `terraform init -backend=false`, `terraform validate`, and (when
+// installed) `tflint --init` + `tflint` in each, then cleans up.
+// Exits non-zero on any failure. Run with: npm run test:iac
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = path.join(ROOT, 'bin', 'cli.js');
+
+// Shared provider cache across runs so the second project (and repeat runs)
+// skip re-downloading providers. Lives outside the per-run temp root so
+// cleanup never deletes it.
+const pluginCacheDir = path.join(os.tmpdir(), 'grada-iac-plugin-cache');
+fs.mkdirSync(pluginCacheDir, { recursive: true });
+
+const baseEnv = {
+    ...process.env,
+    CI_MOCK_AWS: 'true',
+    DO_NOT_TRACK: '1',
+    TF_PLUGIN_CACHE_DIR: pluginCacheDir,
+};
+
+function section(title) {
+    console.log(`\n=== ${title} ===`);
+}
+
+function run(cmd, args, options) {
+    console.log(`$ ${cmd} ${args.join(' ')}`);
+    execFileSync(cmd, args, { stdio: 'inherit', ...options });
+}
+
+function commandExists(cmd) {
+    try {
+        execFileSync(cmd, ['--version'], { stdio: 'pipe' });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+if (!commandExists('terraform')) {
+    console.error('ERROR: terraform is not installed. Install it (https://developer.hashicorp.com/terraform/install) and re-run.');
+    process.exit(1);
+}
+
+const tflintAvailable = commandExists('tflint');
+if (!tflintAvailable) {
+    console.log('WARNING: tflint not found on PATH — lint steps will be skipped. Install it with `brew install tflint` (macOS) or see https://github.com/terraform-linters/tflint, then re-run.');
+}
+
+function checkTerraform(terraformDir) {
+    run('terraform', ['init', '-backend=false'], { cwd: terraformDir, env: baseEnv });
+    run('terraform', ['validate'], { cwd: terraformDir, env: baseEnv });
+    if (tflintAvailable) {
+        run('tflint', ['--init'], { cwd: terraformDir, env: baseEnv });
+        run('tflint', [], { cwd: terraformDir, env: baseEnv });
+    }
+}
+
+const ADDONS = 'storage:s3,db:dynamodb,db:redis,queue:sqs,ai:bedrock,email:ses,cron';
+
+// Mirrors the Scaffold steps of the validate-addons job: without these seed
+// files init cannot generate worker.tf or the migration gate.
+function seedAddonsProject(dir) {
+    fs.writeFileSync(path.join(dir, 'package.json'), '{"scripts":{"db:migrate":"prisma migrate deploy"}}');
+    fs.writeFileSync(path.join(dir, 'Procfile'), 'web: node index.js\nworker: node worker.js\n');
+}
+
+// Lambda variant: web-only Procfile (Lambda targets run a single function,
+// so worker processes are skipped) plus a migration script (the ECS-based
+// migration gate is skipped with a warning on Lambda).
+function seedLambdaAddonsProject(dir) {
+    fs.writeFileSync(path.join(dir, 'package.json'), '{"scripts":{"db:migrate":"prisma migrate deploy"}}');
+    fs.writeFileSync(path.join(dir, 'Procfile'), 'web: node index.js\n');
+}
+
+function assertAddonsFiles(dir) {
+    for (const file of ['terraform/database.tf', 'terraform/ses.tf', 'terraform/bedrock.tf', 'terraform/cron.tf', 'terraform/worker.tf', 'terraform/domain.tf']) {
+        if (!fs.existsSync(path.join(dir, file))) {
+            throw new Error(`expected ${file} to be generated`);
+        }
+    }
+    const deployYml = fs.readFileSync(path.join(dir, '.github', 'workflows', 'deploy.yml'), 'utf-8');
+    if (!deployYml.includes('grada:db-migrate-start')) {
+        throw new Error('expected the migration gate (grada:db-migrate-start) in .github/workflows/deploy.yml');
+    }
+}
+
+function assertEngineFiles(dir, engine, marker) {
+    const databaseTf = fs.readFileSync(path.join(dir, 'terraform', 'database.tf'), 'utf-8');
+    if (!databaseTf.includes(marker)) {
+        throw new Error(`expected ${marker} in terraform/database.tf for --db-engine=${engine}`);
+    }
+}
+
+function engineProject(engine, marker) {
+    return {
+        name: `engine: ${engine}`,
+        dirName: `test-app-engine-${engine}`,
+        steps() {
+            return [
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--needsDatabase', '--db-engine', engine], { cwd: this.dir, env: baseEnv })],
+                ['assert files', () => assertEngineFiles(this.dir, engine, marker)],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    };
+}
+
+function assertLambdaBaseFiles(dir) {
+    const mainTf = fs.readFileSync(path.join(dir, 'terraform', 'main.tf'), 'utf-8');
+    for (const marker of [
+        'resource "aws_lambda_function" "app"',
+        'resource "aws_apigatewayv2_api" "main"',
+        'ignore_changes = [image_uri]',
+        'output "api_gateway_url"',
+    ]) {
+        if (!mainTf.includes(marker)) throw new Error(`expected ${marker} in terraform/main.tf`);
+    }
+    if (mainTf.includes('aws_ecs_service')) throw new Error('expected no ECS resources in terraform/main.tf');
+    const cloudfrontTf = fs.readFileSync(path.join(dir, 'terraform', 'cloudfront.tf'), 'utf-8');
+    if (!cloudfrontTf.includes('origin_protocol_policy = "https-only"')) {
+        throw new Error('expected the https-only API Gateway origin in terraform/cloudfront.tf');
+    }
+    const dockerfile = fs.readFileSync(path.join(dir, 'Dockerfile'), 'utf-8');
+    if (!dockerfile.includes('aws-lambda-adapter')) throw new Error('expected the Lambda Web Adapter in Dockerfile');
+    const deployYml = fs.readFileSync(path.join(dir, '.github', 'workflows', 'deploy.yml'), 'utf-8');
+    if (!deployYml.includes('aws lambda update-function-code')) {
+        throw new Error('expected update-function-code in .github/workflows/deploy.yml');
+    }
+    if (fs.existsSync(path.join(dir, 'terraform', 'worker.tf'))) {
+        throw new Error('expected no terraform/worker.tf on a lambda project');
+    }
+}
+
+function assertLambdaAddonsFiles(dir) {
+    for (const file of ['terraform/database.tf', 'terraform/ses.tf', 'terraform/bedrock.tf', 'terraform/cron.tf', 'terraform/redis.tf', 'terraform/domain.tf']) {
+        if (!fs.existsSync(path.join(dir, file))) {
+            throw new Error(`expected ${file} to be generated`);
+        }
+    }
+    const mainTf = fs.readFileSync(path.join(dir, 'terraform', 'main.tf'), 'utf-8');
+    if (!mainTf.includes('vpc_config {')) throw new Error('expected vpc_config in terraform/main.tf');
+    if (!mainTf.includes('REDIS_URL = ')) throw new Error('expected REDIS_URL in the function variables map');
+    if (!mainTf.includes('image_config {')) throw new Error('expected image_config from the Procfile web command');
+    const cronTf = fs.readFileSync(path.join(dir, 'terraform', 'cron.tf'), 'utf-8');
+    if (!cronTf.includes('aws_lambda_function.app.arn')) throw new Error('expected the Lambda scheduler target in terraform/cron.tf');
+    const databaseTf = fs.readFileSync(path.join(dir, 'terraform', 'database.tf'), 'utf-8');
+    if (!databaseTf.includes('resource "random_password" "db_password"')) {
+        throw new Error('expected random_password.db_password in terraform/database.tf');
+    }
+    const deployYml = fs.readFileSync(path.join(dir, '.github', 'workflows', 'deploy.yml'), 'utf-8');
+    if (deployYml.includes('grada:db-migrate-start')) {
+        throw new Error('expected no ECS migration gate in the lambda deploy workflow');
+    }
+}
+
+const projects = [
+    {
+        name: 'base (no domain)',
+        dirName: 'test-app-base',
+        steps() {
+            return [
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--needsDatabase'], { cwd: this.dir, env: baseEnv })],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    },
+    engineProject('mysql', 'engine            = "mysql"'),
+    engineProject('aurora-postgresql', 'resource "aws_rds_cluster" "postgres"'),
+    {
+        name: 'addons + domain',
+        dirName: 'test-app-addons',
+        steps() {
+            return [
+                ['seed', () => seedAddonsProject(this.dir)],
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--needsDatabase', '--with', ADDONS, '--domain', 'example.com', '--zone-id', 'Z1234567890ABC', '--setup-ci-migrate'], { cwd: this.dir, env: baseEnv })],
+                ['domain add', () => run('node', [CLI, 'domain', 'add', 'example.com', '--zone-id', 'Z1234567890ABC'], { cwd: this.dir, env: baseEnv })],
+                ['assert files', () => assertAddonsFiles(this.dir)],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    },
+    {
+        name: 'lambda base (no domain)',
+        dirName: 'test-app-lambda-base',
+        steps() {
+            return [
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--target', 'lambda'], { cwd: this.dir, env: baseEnv })],
+                ['assert files', () => assertLambdaBaseFiles(this.dir)],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    },
+    {
+        name: 'lambda aurora + addons + domain',
+        dirName: 'test-app-lambda-addons',
+        steps() {
+            return [
+                ['seed', () => seedLambdaAddonsProject(this.dir)],
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--target', 'lambda', '--needsDatabase', '--db-engine', 'aurora-postgresql', '--with', ADDONS, '--domain', 'example.com', '--zone-id', 'Z1234567890ABC', '--setup-ci-migrate'], { cwd: this.dir, env: baseEnv })],
+                ['domain add', () => run('node', [CLI, 'domain', 'add', 'example.com', '--zone-id', 'Z1234567890ABC'], { cwd: this.dir, env: baseEnv })],
+                ['assert files', () => assertLambdaAddonsFiles(this.dir)],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    },
+    {
+        name: 'lambda mysql (instance conversion)',
+        dirName: 'test-app-lambda-mysql',
+        steps() {
+            return [
+                ['scaffold', () => run('node', [CLI, 'init', '--headless', '--framework=node', '--target', 'lambda', '--needsDatabase', '--db-engine', 'mysql'], { cwd: this.dir, env: baseEnv })],
+                ['assert files', () => assertEngineFiles(this.dir, 'mysql', 'engine            = "mysql"')],
+                ['terraform', () => checkTerraform(path.join(this.dir, 'terraform'))],
+            ];
+        },
+    },
+];
+
+const failures = [];
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'grada-iac-'));
+console.log(`Working directory: ${tmpRoot}`);
+try {
+    for (const project of projects) {
+        project.dir = path.join(tmpRoot, project.dirName);
+        fs.mkdirSync(project.dir, { recursive: true });
+        section(`Project: ${project.name}`);
+        for (const [stepName, stepFn] of project.steps()) {
+            try {
+                stepFn();
+            } catch (error) {
+                failures.push({ project: project.name, step: stepName, error });
+                console.error(`FAILED: ${project.name} / ${stepName}: ${error.message}`);
+                break;
+            }
+        }
+    }
+} finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+    console.log(`Cleaned up: ${tmpRoot}`);
+}
+
+if (failures.length > 0) {
+    console.error(`\nIaC validation FAILED (${failures.length} failing step${failures.length === 1 ? '' : 's'}):`);
+    for (const failure of failures) {
+        console.error(`  - ${failure.project} / ${failure.step}`);
+    }
+    process.exit(1);
+}
+
+console.log('\nIaC validation passed.');

package/specs/add-redis-sqs-bedrock.md

@@ -0,0 +1,128 @@
+# Spec: Modular Service Engine (`deploy-stack add`) — `db:redis`, `queue:sqs` & `ai:bedrock`
+
+## Overview
+Extend the modular service engine with three new capabilities:
+1. **`db:redis`**: AWS ElastiCache for Valkey 8.0 (`cache.t4g.micro`) isolated inside the VPC with security group ingress restricted to ECS tasks.
+2. **`queue:sqs`**: Managed Amazon SQS standard queue with long polling, paired with a Dead-Letter Queue (DLQ, `maxReceiveCount = 3`), least-privilege Task Role IAM permissions, and conditional scale-to-zero worker auto-scaling.
+3. **`ai:bedrock`**: Least-privilege Amazon Bedrock runtime IAM permissions (`InvokeModel` and `InvokeModelWithResponseStream` across foundation models and cross-region inference profiles) attached to the ECS Task Role with a configurable `--model` flag.
+
+---
+
+## Part 1: Registry Contracts, CLI Flags & Container Env Wiring
+
+### 1. Preserve the Existing Split Between `src/utils/addons.js` and `src/commands/add.js`
+* **`ADDON_REGISTRY` in `src/utils/addons.js`:** Keep the exact existing schema (`file`, `template`, `label`, `cost: { model, monthlyFixed, summary }`). Do not add `envVars` to `src/utils/addons.js`.
+  * **`db:redis`**:
+    * `file` and `template`: `redis.tf`
+    * `label`: `ElastiCache Valkey 8.0`
+    * `cost`: `model` set to `fixed-baseline`, `monthlyFixed` set to `9.49` (using `$0.013/hr` / `$9.49/mo` as the canonical `us-east-2` reference rate across code, tests, and docs), and `summary` describing the `~$9.49/mo` fixed baseline (`$0.013/hr` Valkey 8.0 `cache.t4g.micro` in `us-east-2`) with `$0` intra-AZ VPC transfer.
+  * **`queue:sqs`**:
+    * `file` and `template`: `sqs.tf`
+    * `label`: `SQS + DLQ`
+    * `cost`: `model` set to `usage-based`, `monthlyFixed` set to `0`, and `summary` noting `$0/mo` fixed baseline with the first 1M requests/mo free and `$0.40` per million requests thereafter.
+  * **`ai:bedrock`**:
+    * `file` and `template`: `bedrock.tf`
+    * `label`: `Bedrock Runtime IAM`
+    * `cost`: `model` set to `usage-based`, `monthlyFixed` set to `0`, and `summary` noting `$0/mo` fixed baseline billed per 1K input/output tokens on `InvokeModel` calls.
+* **`ADDON_ENV_VARS` in `src/commands/add.js`:** Keep environment variable definitions in `ADDON_ENV_VARS` in `src/commands/add.js`:
+  * `db:redis`: injects `REDIS_URL` pointing to `redis://<cluster_node_0_address>:6379`.
+  * `queue:sqs`: injects `SQS_QUEUE_URL` (`aws_sqs_queue.main.id`) and `SQS_DLQ_URL` (`aws_sqs_queue.dlq.id`).
+  * `ai:bedrock`: injects `BEDROCK_MODEL_ID` populated with the resolved model ID.
+
+### 2. `runAdd(options = {})` Signature & `--model` Flag Handling (`src/commands/add.js`, `bin/cli.js`)
+* Preserve the existing single-object signature `runAdd(options = {})` where `capability` is read from `options`.
+* Export `DEFAULT_BEDROCK_MODEL` set to `us.anthropic.claude-sonnet-4-20250514-v1:0`.
+* Default `model` to `DEFAULT_BEDROCK_MODEL` in both `parseAddArgs` and `runAdd` (matching the exact `partitionKey` pattern).
+* Silently ignore `--model` when `capability` is not `ai:bedrock` (matching `--partition-key`).
+* Validate `model` only when `capability === 'ai:bedrock'`, positioned immediately after the `UNSUPPORTED_CAPABILITY` check and before `TERRAFORM_NOT_INITIALIZED`:
+  * Allow only alphanumeric characters, underscores, dots, colons, and hyphens.
+  * On validation failure, match the exact failure convention of `INVALID_PARTITION_KEY`: log the error, track `add_run` with `projectName`, `capability`, `success: false`, and `error_code: 'INVALID_MODEL_ID'`, flush telemetry, call `process.exit(1)`, and return `{ ok: false, reason: 'invalid_model_id' }`.
+* Update `HELP_TEXT` in `bin/cli.js` to include the new capabilities and `--model <id>`.
+
+### 3. Parameterized Container Env Injection for `main.tf` and `worker.tf` (`src/commands/add.js`)
+* Update `injectContainerEnvVars` so it is not hardcoded strictly to the `"app"` task definition resource name—either accept a target task definition resource name parameter (`"app"` vs `"worker"`) or match whichever `aws_ecs_task_definition` block is present in the file.
+* Apply `injectContainerEnvVars` to `terraform/main.tf` as today, and if `terraform/worker.tf` exists in the project's `terraform` directory, also apply `injectContainerEnvVars` to `terraform/worker.tf` (for all capabilities in `runAdd`, including reruns of `storage:s3` and `db:dynamodb`) so worker containers receive the same addon environment variables as the web container.
+
+---
+
+## Part 2: Capability 1 — `db:redis` (`templates/terraform/addons/redis.tf` -> `terraform/redis.tf`)
+
+1. **Networking & Security Group (Match `templates/terraform/network.tf`):**
+   * Define `aws_elasticache_subnet_group.redis` named `${local.app_name}-redis-subnets` referencing `aws_subnet.public[*].id`.
+   * Define `aws_security_group.redis` named `${local.app_name}-redis-sg` in `aws_vpc.main.id`:
+     * Ingress: TCP port `6379` restricted strictly to `aws_security_group.ecs_tasks.id`.
+     * Egress: standard all-traffic egress with the `trivy:ignore:AVD-AWS-0104` annotation to match `network.tf`.
+2. **Collision-Free 20-Character Cluster ID (`aws_elasticache_cluster.redis`):**
+   * AWS ElastiCache `cluster_id` allows at most 20 characters, must start with a letter, and cannot end with a hyphen. Pure prefix truncation cuts off the `-pr-N` suffix on project names >= 11 characters and collides across workspaces.
+   * Construct `cluster_id` deterministically within 20 characters by combining:
+     * A leading `ds-` prefix (3 chars, guaranteeing a leading ASCII letter),
+     * Up to 5 characters of the sanitized lowercase `local.app_name` (trimmed of trailing hyphens),
+     * A hyphen plus a 5-character substring of `md5(local.app_name)` (6 chars total, guaranteeing uniqueness between `default` and PR workspaces regardless of project name length),
+     * The `-redis` suffix (6 chars, totaling at most 20 characters).
+   * Configure `engine = "valkey"`, `engine_version = "8.0"`, `node_type = "cache.t4g.micro"`, `num_cache_nodes = 1`, `port = 6379`, `subnet_group_name`, and `security_group_ids`.
+3. **Outputs:**
+   * Output `redis_endpoint` (`cache_nodes[0].address`) and `redis_port` (`port`).
+
+---
+
+## Part 3: Capability 2 — `queue:sqs` (`templates/terraform/addons/sqs.tf` -> `terraform/sqs.tf`)
+
+1. **Queues & Redrive Policy:**
+   * `aws_sqs_queue.dlq`: named `${local.app_name}-dlq`, 14-day retention (`1209600` seconds), `sqs_managed_sse_enabled = true`.
+   * `aws_sqs_queue.main`: named `${local.app_name}-queue`, 30s visibility timeout, 4-day retention (`345600` seconds), 20s long polling (`receive_wait_time_seconds = 20`), `sqs_managed_sse_enabled = true`, and `redrive_policy` targeting `aws_sqs_queue.dlq.arn` with `maxReceiveCount = 3`.
+2. **Task Role IAM Policy (`aws_iam_role_policy.queue_sqs_access`):**
+   * Named `${local.app_name}-queue-sqs-access` attached to `aws_iam_role.task_role.id`.
+   * Grant `sqs:SendMessage`, `sqs:ReceiveMessage`, `sqs:DeleteMessage`, `sqs:ChangeMessageVisibility`, `sqs:GetQueueAttributes`, and `sqs:GetQueueUrl` on both `aws_sqs_queue.main.arn` and `aws_sqs_queue.dlq.arn`.
+3. **Worker Queue-Depth Auto-Scaling (`{{WORKER_AUTOSCALING_BLOCK}}`):**
+   * Detect whether `worker.tf` exists in the project's `terraform` directory during `runAdd` and pass a boolean flag into `renderAddonTemplate`. When `worker.tf` exists, render the auto-scaling resources as active HCL; when absent, render the same block commented out with `# ` per line.
+   * **Auto-Scaling Resources (Scale-Out + Scale-In):**
+     * `aws_appautoscaling_target.worker_scale`: `service_namespace = "ecs"`, `scalable_dimension = "ecs:service:DesiredCount"`, `resource_id = "service/${aws_ecs_cluster.main.name}/${aws_ecs_service.worker.name}"`, `min_capacity = 0`, `max_capacity = 5`. (Note: AWS Application Auto Scaling automatically creates the `AWSServiceRoleForApplicationAutoScaling_ECSService` service-linked role upon target registration.)
+     * **Scale-Out Policy & Alarm:** `aws_appautoscaling_policy.worker_scale_out` (`policy_type = "StepScaling"`, `adjustment_type = "ChangeInCapacity"`, `cooldown = 60`, step adjustment `+1` with `metric_interval_lower_bound = 0`) triggered by `aws_cloudwatch_metric_alarm.sqs_queue_high` (`AWS/SQS` `ApproximateNumberOfMessagesVisible`, `QueueName = aws_sqs_queue.main.name`, `statistic = "Average"`, `period = 60`, `evaluation_periods = 1`, `comparison_operator = "GreaterThanOrEqualToThreshold"`, `threshold = 1`).
+     * **Scale-In Policy & Alarm (Scale back to zero):** `aws_appautoscaling_policy.worker_scale_in` (`policy_type = "StepScaling"`, `adjustment_type = "ChangeInCapacity"`, `cooldown = 300`, step adjustment `-5` with `metric_interval_upper_bound = 0`) triggered by `aws_cloudwatch_metric_alarm.sqs_queue_empty` (`AWS/SQS` `ApproximateNumberOfMessagesVisible`, `QueueName = aws_sqs_queue.main.name`, `statistic = "Maximum"`, `period = 60`, `evaluation_periods = 5`, `comparison_operator = "LessThanOrEqualToThreshold"`, `threshold = 0`).
+   * **Worker `desired_count` Drift Prevention:** Add `lifecycle { ignore_changes = [desired_count] }` to `aws_ecs_service.worker` in `templates/terraform/worker.tf` (and update the `worker.tf` snapshot in `tests/generator.test.js`). Additionally, when `runAdd` runs `queue:sqs` on an existing project where `terraform/worker.tf` is present but lacks `ignore_changes`, idempotently inject `lifecycle { ignore_changes = [desired_count] }` into `aws_ecs_service.worker` in `terraform/worker.tf`.
+4. **Outputs:**
+   * Output `sqs_queue_url`, `sqs_queue_arn`, and `sqs_dlq_url`.
+
+---
+
+## Part 4: Capability 3 — `ai:bedrock` (`templates/terraform/addons/bedrock.tf` -> `terraform/bedrock.tf`)
+
+1. **Task Role IAM Policy (`aws_iam_role_policy.ai_bedrock_access`):**
+   * Named `${local.app_name}-ai-bedrock-access` attached to `aws_iam_role.task_role.id`.
+   * Grant `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` on both `arn:aws:bedrock:*::foundation-model/*` and `arn:aws:bedrock:*:*:inference-profile/*`.
+2. **Template Placeholder & Output:**
+   * Replace `{{BEDROCK_MODEL_ID}}` in `renderAddonTemplate` with the resolved model ID and expose `output "bedrock_model_id"`.
+
+---
+
+## Part 5: Visualizer, Viewport Budget & Doc Sync (`src/utils/visualizer.js`)
+
+1. **Preserve `estimateMonthlyCost(config)` Contract:**
+   * Keep the existing return object shape unchanged, summing `monthlyFixed` from active addons into the monthly total and deriving hourly cost as `total / 730`.
+2. **Deterministic Viewport Compaction in `renderDryRunPreview(config)` (<= 14 Lines, <= 90 Columns):**
+   * **Addon Tree Lines:**
+     * When `1` or `2` addons are active, keep the existing per-addon tree line format (including the puzzle emoji and ANSI styling) so existing 2-addon tests continue to pass unchanged.
+     * When `3` or more addons are active, collapse them into a single tree line displaying the puzzle emoji and `[Addons (<count>): <comma-separated capability keys>]` (e.g., `[Addons (5): storage:s3, db:dynamodb, db:redis, queue:sqs, ai:bedrock]`, which is 80 visible characters and never requires truncation).
+   * **Fixed Baseline Line (`<= 90` visible characters):**
+     * When fixed-cost addons (`monthlyFixed > 0`) are active, include `Addons: $<sum>` in `costParts`.
+     * If the resulting `Est. Fixed Baseline:` line exceeds 90 visible characters (which happens when Fargate, ALB, RDS, Secrets, and Addons are all present simultaneously), switch the parenthetical breakdown to a compact form (e.g., omitting colons or folding minor items like `Secrets: $0.40` into the total) so the line stays strictly `<= 90` visible characters.
+   * **Usage-Based Summary Line Suppression:**
+     * Filter active addons to those with `(addon.cost?.monthlyFixed || 0) === 0`.
+     * Only render the `+ Usage-based (<N> addon/addons): $0/mo fixed ...` line when that filtered count is strictly `> 0`. When only `db:redis` is active (zero usage-based addons), omit the usage-based line completely.
+3. **Keep `### Active Addons (Usage-Based)` Heading in `syncDocCostEstimate`:**
+   * Retain the existing heading string in `syncDocCostEstimate` for test compatibility.
+
+---
+
+## Part 6: Docs, Snapshots & Unit Tests
+
+1. **Snapshots (`tests/generator.test.js`):**
+   * Run `npx vitest run -u` to update the `Heroku_Procfile_Migration - worker.tf` snapshot after adding `lifecycle { ignore_changes = [desired_count] }` to `templates/terraform/worker.tf`.
+2. **Documentation & Roadmap (`apps/docs/`, `README.md`):**
+   * Update `apps/docs/src/content/docs/cli/add.md`, `apps/docs/src/content/docs/guides/ephemeral-pr-previews.md` (noting the `$9.49/mo` / `$0.013/hr` per-PR Valkey cluster cost when `db:redis` is used), `README.md`, and `apps/docs/src/content/docs/roadmap.md`.
+   * Include a note in `cli/add.md` reminding users to enable model access in the AWS Bedrock console across backing `us.*` inference profile regions.
+3. **Unit Tests (`tests/add.test.js` & `tests/visualizer.test.js`):**
+   * Cover `db:redis` (including MD5-suffixed 20-char `cluster_id` uniqueness across workspaces and fixed cost impact), `queue:sqs` (both with and without `worker.tf`, verifying active vs. commented auto-scaling and `worker.tf` env var + `ignore_changes` injection), and `ai:bedrock` (default model, custom `--model`, `INVALID_MODEL_ID` exit/return behavior, and ignoring `--model` on other capabilities).
+   * In `tests/visualizer.test.js`, test:
+     * Only `db:redis` active (verifying `+ Usage-based` line is suppressed when 0 usage-based addons are present).
+     * Maximal configuration (`hasDb: true`, `hasWorker: true`, `hasSecrets: true`, and all 5 addons active) asserting total box height `<= 14` lines and every line `<= 90` visible characters.