@grada-run/grada 0.0.1 → 0.33.0

package/specs/database-suite-expansion.md

@@ -0,0 +1,151 @@
+# Spec: Database Suite Completion (`db enable-vector`, `db import`, and Multi-Engine RDS / Aurora Scale-to-Zero)
+
+## Overview
+Complete the `deploy-stack db` lifecycle suite and relational database engine layer by delivering the final three database roadmap capabilities in Phase 10:
+1. **Multi-Engine RDS & Aurora Serverless v2 Scale-to-Zero:** Support PostgreSQL (`postgres`), MySQL (`mysql`), and Aurora PostgreSQL Serverless v2 (`aurora-postgresql` with `min_capacity = 0` auto-pause) across `init`, `visualizer`, `db connect`, `db migrate`, `db backup`, and `db restore`.
+2. **Vector Databases (`deploy-stack db enable-vector`):** One-command `pgvector` activation on PostgreSQL (`postgres` and `aurora-postgresql`) inside the isolated VPC without requiring `psql` inside the user's application container image.
+3. **Zero-Trust Database Ingestion (`deploy-stack db import`):** Stream a local SQL/dump file (`--file <path>`) or a remote database (`--from <url>` from Heroku, Supabase, Render, Railway, or Neon) into the private VPC database over an ephemeral SSM Port Forwarding tunnel.
+
+### Core Architectural Principles
+1. **100% Backwards Compatibility for Default PostgreSQL:** Calling `init --headless --needsDatabase` without `--db-engine` must continue to generate the exact same `postgres` (`aws_db_instance.postgres`) configuration and keep existing snapshot contracts intact.
+2. **Container-Runtime Agnostic VPC Execution:** `db enable-vector` must not assume the user's application container has the `psql` CLI installed. Execute the SQL lifecycle over a tiny zero-dependency Node.js/Python inline driver or raw PostgreSQL wire-protocol/TCP handshake inside the ephemeral ECS task, or fall back to an inline Node script using the runtime environment variables (`DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`).
+3. **Unified RDS & Cluster Discovery:** Abstract single-instance RDS (`aws_db_instance`) and Aurora Cluster (`aws_rds_cluster` + `aws_rds_cluster_instance`) behind `src/utils/rds.js` so `db connect`, `db backup`, `db restore`, `db migrate`, `db enable-vector`, and `db import` work seamlessly across all three engines.
+
+---
+
+## Part 1: Multi-Engine RDS & Aurora Scale-to-Zero
+
+### 1. Supported Database Engines (`--db-engine <engine>`)
+Introduce three canonical engine identifiers across `src/core/parser.js`, `src/commands/init.js`, `src/utils/prompts.js`, and `src/utils/generator.js`:
+* `postgres` (default): Standard RDS PostgreSQL 16 (`aws_db_instance.postgres`, `db.t4g.micro`, port `5432`, URI scheme `postgresql://`).
+* `mysql`: Standard RDS MySQL 8.0 (`aws_db_instance.postgres` or canonical resource name `aws_db_instance.main` / `postgres` kept for HCL/reference continuity or cleanly parameterized, `db.t4g.micro`, port `3306`, default username `dbadmin`, URI scheme `mysql://`).
+* `aurora-postgresql`: Amazon Aurora PostgreSQL Serverless v2 (`aws_rds_cluster.postgres` + `aws_rds_cluster_instance.postgres`, engine `aurora-postgresql`, no `engine_version` on the cluster so new databases take the regional AWS default (AWS retires pinned minors such as `16.4`), port `5432`, `serverlessv2_scaling_configuration { min_capacity = 0.0, max_capacity = 2.0 }`, `enable_http_endpoint = false`, `manage_master_user_password = true`, `storage_encrypted = true`).
+
+### 2. Interactive & Headless `init` Integration
+* **CLI Flag:** Parse `--db-engine <postgres|mysql|aurora-postgresql>` in `src/core/parser.js`. Fail fast with `INVALID_DB_ENGINE` if an unsupported value is passed.
+* **Capability Detection Alignment:** In `src/utils/capabilities.js`, when `relationalDb.detected` is true, use the detected `relationalDb.engine` (`postgres` vs `mysql`) as the default initial value in the interactive engine selector prompt.
+* **Interactive Prompt (`src/utils/prompts.js`):** When the user answers `Yes` to provisioning a managed database in interactive `init` (and `--db-engine` was not explicitly passed):
+  * Present a `select` prompt to choose the database engine:
+    1. `PostgreSQL 16 (RDS db.t4g.micro — ~$13.98/mo fixed)`
+    2. `Aurora PostgreSQL Serverless v2 (Scale-to-Zero 0–2 ACU — $0/mo idle compute + storage)`
+    3. `MySQL 8.0 (RDS db.t4g.micro — ~$13.98/mo fixed)`
+* **Headless Default:** When `--headless` or `--preconfigured` is used with `--needsDatabase` and no `--db-engine` flag is passed, default to `postgres` so all existing tests and snapshots remain unchanged.
+
+### 3. Terraform Templates & Container Environment Wiring
+* **Template Strategy:**
+  * Keep `templates/terraform/database.tf` as the single target output path (`terraform/database.tf`), rendered according to the chosen `dbEngine` (`postgres`, `mysql`, or `aurora-postgresql`).
+  * Ensure security group ingress rules on `aws_security_group.rds` open port `5432` for `postgres` / `aurora-postgresql` and port `3306` for `mysql`, restricted strictly to `aws_security_group.ecs_tasks.id`.
+  * For `aurora-postgresql`:
+    * Provision `aws_rds_cluster.postgres` with `cluster_identifier = "${local.app_name}-db-cluster"`, `engine = "aurora-postgresql"`, `database_name = replace(local.app_name, "-", "_")`, `master_username = "dbadmin"`, `manage_master_user_password = true`, `db_subnet_group_name = aws_db_subnet_group.main.name`, `vpc_security_group_ids = [aws_security_group.rds.id]`, `skip_final_snapshot = true`, `storage_encrypted = true`, and `serverlessv2_scaling_configuration { min_capacity = 0, max_capacity = 2 }`.
+    * Provision `aws_rds_cluster_instance.postgres` with `identifier = "${local.app_name}-db-instance-1"`, `cluster_identifier = aws_rds_cluster.postgres.id`, `instance_class = "db.serverless"`, `engine = aws_rds_cluster.postgres.engine`, `engine_version = aws_rds_cluster.postgres.engine_version`, `publicly_accessible = false`.
+    * Wire `DB_HOST` to `aws_rds_cluster.postgres.endpoint`, `DB_NAME` to `aws_rds_cluster.postgres.database_name`, `DB_PORT` to `"5432"`, and `DB_USER` / `DB_PASSWORD` secrets to `aws_rds_cluster.postgres.master_user_secret[0].secret_arn`.
+    * Also inject `{ "name": "DB_ENGINE", "value": "<engine>" }` (or detect the port/scheme in `migrate.js`) when `mysql` or `aurora-postgresql` is selected so runtime tools know whether to synthesize `mysql://` or `postgresql://`.
+  * Ensure all generated HCL across all three engine modes is `terraform validate`-clean and `tflint`-clean (using bare HCL references rather than deprecated single-expression interpolations).
+
+### 4. Visualizer & Cost Estimation (`src/utils/visualizer.js`)
+* Inspect `terraform/database.tf` to detect the provisioned engine (`aws_rds_cluster` -> Aurora Serverless v2; `engine = "mysql"` -> RDS MySQL; default -> RDS PostgreSQL).
+* Render accurate topology labels and cost math:
+  * `postgres`: `🐘 Amazon RDS (PostgreSQL managed instance)` — `$13.98/mo` fixed baseline.
+  * `mysql`: `🐬 Amazon RDS (MySQL managed instance)` — `$13.98/mo` fixed baseline.
+  * `aurora-postgresql`: `✨ Amazon Aurora PostgreSQL (Serverless v2 · 0–2 ACU scale-to-zero)` — `$0/mo` idle compute baseline (`+$0.12/ACU-hr when active`).
+
+### 5. Cross-Command Multi-Engine Support (`src/utils/rds.js`, `connect.js`, `migrate.js`, `backup.js`, `restore.js`)
+* **Unified `findDbTarget(rdsClient, identifier, cwd)` in `src/utils/rds.js`:**
+  * Detect whether the project uses a standard RDS instance (`aws_db_instance`) or an Aurora cluster (`aws_rds_cluster`) by inspecting `terraform/database.tf` (if present) or querying `DescribeDBInstancesCommand` (`${appName}-db`) with fallback to `DescribeDBClustersCommand` (`${appName}-db-cluster`).
+  * Return a normalized descriptor: `{ kind: 'instance' | 'cluster', id, engine, status, endpoint, port, dbName, masterSecretArn, raw }`.
+* **`db connect`:**
+  * Use the normalized `endpoint` and `port` (`5432` or `3306`).
+  * Default `--local-port` to the remote database port (`5432` for Postgres/Aurora, `3306` for MySQL) unless overridden by the user.
+  * Format the printed connection URI using `mysql://` when `engine === 'mysql'` and `postgresql://` otherwise.
+* **`db migrate`:**
+  * Update `buildRuntimeMigrationCommand` in `src/commands/db/migrate.js` so that when synthesizing `DATABASE_URL` at runtime, it uses `mysql://` if `DB_PORT === '3306'` or `DB_ENGINE === 'mysql'`, and `postgresql://` otherwise.
+* **`db backup` & `db restore`:**
+  * When `kind === 'cluster'` (Aurora), use `CreateDBClusterSnapshotCommand` and `DescribeDBClusterSnapshotsCommand` in `backup.js` / `restore.js`, and pin `snapshot_identifier` inside the `resource "aws_rds_cluster" "postgres"` block in `terraform/database.tf`.
+  * Maintain existing `CreateDBSnapshotCommand` / `DescribeDBSnapshotsCommand` behavior for `kind === 'instance'`.
+
+---
+
+## Part 2: Vector Databases (`deploy-stack db enable-vector`)
+
+### 1. Command Interface & Routing
+* Route `deploy-stack db enable-vector` through `src/commands/db.js` to a new module `src/commands/db/enable-vector.js` (`runDbEnableVector`).
+* Supported flags: `--cluster <name>`, `--service <name>`, `--container <name>`, `--task-def <arn-or-family>`, `--project-name <name>`, `--workspace <name>`, `--region <region>`, `--headless` / `--yes`.
+* Update `VALID_DB_SUBCOMMANDS` and `HELP_TEXT` in `src/commands/db.js` and `bin/cli.js`.
+
+### 2. Engine & Prerequisite Guards
+* Inspect `terraform/database.tf` (if present in `cwd`):
+  * If `terraform/database.tf` exists and its engine is `mysql`, fail fast with error code `UNSUPPORTED_VECTOR_ENGINE` explaining that `pgvector` requires PostgreSQL or Aurora PostgreSQL.
+  * If `terraform/database.tf` does not exist and no `--cluster`/`--service` overrides are passed, fail fast with `NO_DATABASE_CONFIGURED` and guide the user to enable PostgreSQL first.
+
+### 3. Zero-Dependency Ephemeral Execution Inside the VPC
+* Reuse the ephemeral Fargate task runner machinery from `src/commands/db/migrate.js` (extract shared task-launch + CloudWatch log-streaming + SIGINT cancellation into a reusable helper in `src/utils/ecs-runner.js` or `src/commands/db/migrate.js` so `migrate` and `enable-vector` do not duplicate the 150-line `RunTask` / `pollUntil` / `getLogEvents` lifecycle).
+* **How the SQL is executed inside the container:**
+  * Because user containers may be Node, Python, Go, or Ruby (and rarely have the `psql` CLI binary installed), construct a compact, self-contained shell command that tries:
+    1. `psql "$DATABASE_URL" -c "CREATE EXTENSION IF NOT EXISTS vector;"` if `psql` is on `PATH`.
+    2. Otherwise, if `node` is on `PATH` and `pg` or `@prisma/client` is installed in `node_modules`, execute a one-liner via `pg` (`Client`) or `@prisma/client` (`$executeRawUnsafe('CREATE EXTENSION IF NOT EXISTS vector;')`) and verify via `SELECT extversion FROM pg_extension WHERE extname = 'vector';`.
+    3. Otherwise, if `python3` / `python` is on `PATH` with `psycopg` / `psycopg2` / `asyncpg` / `django`, execute the equivalent 5-line Python snippet.
+    4. If none of those drivers exist in the container image, exit with a clear diagnostic code so the CLI prints an actionable hint (e.g., install `pg` / `@prisma/client` / `psycopg` or `postgresql-client` in the image).
+* **Local Project Marker & Prisma Hint:**
+  * After the remote task succeeds (exit code `0`), if `prisma/schema.prisma` exists in `cwd` and does not yet mention `postgresqlExtensions`, print a helpful note showing how to enable `previewFeatures = ["postgresqlExtensions"]` and `extensions = [vector]` in `schema.prisma`.
+  * Emit `trackSuccess('db_enable_vector', { duration_ms, engine })` on completion.
+
+---
+
+## Part 3: Zero-Trust Database Ingestion (`deploy-stack db import`)
+
+### 1. Command Interface & Flags
+* Route `deploy-stack db import` through `src/commands/db.js` to a new module `src/commands/db/import.js` (`runDbImport`).
+* Supported flags:
+  * `--file <path>`: Path to a local `.sql`, `.dump`, or `.sql.gz` file to import into the remote database.
+  * `--from <source-url>`: Source `postgresql://...` or `mysql://...` connection URI (e.g., from Heroku, Supabase, Render, Railway, or Neon) to dump and stream directly into the remote AWS database.
+  * `--yes` / `--force`: Skip the interactive confirmation prompt before importing into the remote database.
+  * Standard target overrides: `--db-identifier <id>`, `--project-name <name>`, `--workspace <name>`, `--region <region>`, `--headless`.
+
+### 2. Input Validation & Pre-Flight Checks
+* Require **exactly one** of `--file <path>` or `--from <source-url>` (or prompt interactively when in a TTY if neither was provided). If both or neither are provided in headless mode, fail fast with `INVALID_IMPORT_SOURCE`.
+* If `--file <path>` is used, verify the file exists and is readable on disk before making any AWS API calls (`IMPORT_FILE_NOT_FOUND`).
+* If `--from <source-url>` is used, validate that the URI starts with `postgres://`, `postgresql://`, or `mysql://` (`INVALID_SOURCE_URI`), and never log or emit the raw password in terminal output or telemetry (`redactUri(url)`).
+* Check local client tooling prerequisites before opening the SSM tunnel:
+  * For PostgreSQL targets: verify `psql` (or `pg_restore` for custom-format `.dump` files, plus `pg_dump` when `--from` is used) is available on the host `PATH`.
+  * For MySQL targets: verify `mysql` (plus `mysqldump` when `--from` is used) is available on the host `PATH`.
+  * If missing, fail fast with `MISSING_DB_CLIENT_BINARY` and print exact `brew install libpq` / `brew install mysql-client` instructions.
+
+### 3. Ephemeral Background SSM Tunnel + Password Retrieval
+* Extract the SSM port-forwarding tunnel setup from `src/commands/db/connect.js` into a reusable helper (e.g., `withDatabaseTunnel(options, async ({ localPort, host, port, dbName, username, password, engine }) => { ... })`) so `connect.js` and `import.js` share the exact same bastion/ECS task selection, RDS discovery (`findDbTarget`), and SSM session lifecycle:
+  * Automatically pick an ephemeral free local port (via `net.createServer().listen(0)` or a configurable port) so `db import` never collides with a local Postgres/MySQL instance running on `5432` / `3306`.
+  * Fetch the RDS master user password at runtime from AWS Secrets Manager (`GetSecretValueCommand` against `masterSecretArn` from `findDbTarget`) in memory only—never write the password to disk or command-line arguments visible in `ps` (pass via `PGPASSWORD` or `MYSQL_PWD` environment variable to the child process).
+  * Wait until the local SSM port-forwarding socket accepts TCP connections (polling `127.0.0.1:<localPort>` with `pollUntil`), then execute the import stream:
+    * **`--file <path>.sql`:** Pipe the file stream into `psql` / `mysql` connected to `127.0.0.1:<localPort>`.
+    * **`--file <path>.sql.gz`:** Pipe through `zlib.createGunzip()` into `psql` / `mysql`.
+    * **`--file <path>.dump` (Postgres custom archive):** Run `pg_restore --no-owner --no-acl -h 127.0.0.1 -p <localPort> -U <username> -d <dbName> <path>`.
+    * **`--from <source-url>`:** Spawn `pg_dump --no-owner --no-acl <source-url>` (or `mysqldump`) and pipe its `stdout` directly into `psql` (or `mysql`) connected to `127.0.0.1:<localPort>`, streaming stderr progress to the terminal.
+  * In a `finally` block, always terminate the background SSM session child process cleanly even if the import fails or the user presses `Ctrl+C`.
+
+---
+
+## Part 4: Documentation, Roadmap & Testing Requirements
+
+### 1. Documentation & Roadmap Updates
+* Update `apps/docs/src/content/docs/cli/db.md` to document:
+  * `deploy-stack db enable-vector`
+  * `deploy-stack db import --file <path>` and `deploy-stack db import --from <url>`
+  * Multi-engine support (`postgres`, `mysql`, `aurora-postgresql` scale-to-zero) across `db connect`, `db migrate`, `db backup`, and `db restore`.
+* Update `apps/docs/src/content/docs/cli/init.md` and `apps/docs/src/content/docs/architecture/database-connections.md` with the `--db-engine` flag and Aurora Serverless v2 scale-to-zero (`0 ACU`) cost breakdown.
+* Check off the 3 completed items in `apps/docs/src/content/docs/roadmap.md`:
+  * `[x] Vector Databases`
+  * `[x] Multi-Engine RDS & Aurora Scale-to-Zero`
+  * `[x] Zero-Trust Database Ingestion`
+
+### 2. Test Suite & IaC Validation Requirements
+* **Existing Snapshots Preserved:** Default `init --headless --needsDatabase` (when `--db-engine` is omitted) must keep existing snapshots untouched.
+* **New Unit & Integration Tests:**
+  * `tests/rds-multi-engine.test.js` (or in `tests/db.test.js` & `tests/headless.test.js`):
+    * Verify `init --headless --needsDatabase --db-engine mysql` generates valid MySQL 8.0 HCL (port `3306`, `mysql` engine) and injects `DB_PORT = "3306"`.
+    * Verify `init --headless --needsDatabase --db-engine aurora-postgresql` generates `aws_rds_cluster.postgres` + `aws_rds_cluster_instance.postgres` with `min_capacity = 0` and `max_capacity = 2`.
+    * Verify `visualizer.js` calculates `$0/mo` idle compute baseline for `aurora-postgresql` and `$13.98/mo` for `postgres` / `mysql`.
+    * Verify `findDbTarget` resolves both `aws_db_instance` and `aws_rds_cluster`, and that `db backup` / `db restore` use `CreateDBClusterSnapshotCommand` / `DescribeDBClusterSnapshotsCommand` and update `resource "aws_rds_cluster" "postgres"` when running against an Aurora cluster.
+  * `tests/db.test.js` additions for `enable-vector` and `import`:
+    * Verify `db enable-vector` rejects `mysql` projects with `UNSUPPORTED_VECTOR_ENGINE`, launches the ephemeral task for `postgres` / `aurora-postgresql`, and prints the Prisma vector extension hint when `prisma/schema.prisma` is present.
+    * Verify `db import` validates `--file` / `--from` exclusivity, redacts source URIs on error, checks for required local client binaries, passes `PGPASSWORD` / `MYSQL_PWD` via `env` (never CLI args), and always kills the SSM tunnel child process in `finally`.
+* **`scripts/test-iac.js` & `.github/workflows/iac-validation.yml`:**
+  * Extend `scripts/test-iac.js` to also validate `aurora-postgresql` and `mysql` scaffolded configurations with `terraform validate` and `tflint` so all three database engines are continuously verified.

package/specs/db-connect.md

@@ -0,0 +1,69 @@
+# Phase 9: Secure Database Tunneling & Doc Alignment
+
+## Part 1: Fix Existing Logic & Documentation Gaps
+Address the three misalignments identified between the generated code and the documentation.
+
+**1. SvelteKit Database Prompt (Logic Gap):**
+* In `src/utils/prompts.js`, update the `isBackendFramework` check to include `'svelte'`. Currently, SvelteKit users are not prompted for a database even though it is a full-stack framework.
+
+**2. Connection String Clarity (Doc Gap):**
+* In `apps/docs/src/content/docs/guides/database-connections.md`, change "Standard environment variables" to "deploy-stack injected variables".
+* Add a brief explanation and a code block demonstrating how the user should construct their framework's connection string from these variables (e.g., `DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}"`).
+
+**3. Minor Wording Fixes:**
+* In `apps/docs/src/content/docs/guides/database-connections.md`, update "Your auto-generated database name" to "Your deterministic database name".
+* In `templates/README.md`, update "DB_USER: The auto-generated master username" to "DB_USER: The hardcoded master username (dbadmin)".
+
+## Part 2: Implement `deploy-stack db connect`
+Create a new command that securely tunnels from the developer's localhost directly to the isolated RDS instance via an active ECS container.
+
+**1. Dependencies & CLI Plumbing:**
+* Add `@aws-sdk/client-rds` to `package.json` dependencies. Pin the version to match the existing AWS SDKs (e.g., `3.1119.0`).
+* Extract `resolveRegion`, `resolveProjectName`, `resolveCluster`, and `resolveService` from `src/commands/exec.js` into a new shared module: `src/utils/resolvers.js`. 
+  * Update `src/commands/exec.js` to import them from here.
+  * **Critical Test Fix:** Update `tests/exec.test.js` to import these functions from `../src/utils/resolvers.js` instead of `exec.js`.
+  * **Scope Limit:** Leave the identical resolver functions inside `logs.js`, `status.js`, and `gc.js` completely untouched.
+* Update `bin/cli.js` to parse the `db` command and add a HELP_TEXT line for it (e.g., `  db connect           Open a secure local tunnel to your database`).
+* If the user types `deploy-stack db` with no subcommand, print the `db connect` usage and exit non-zero (do not fall through to the scaffold/init flow).
+* If the argument is `connect`, route it to `runDbConnect` exported from `src/commands/db.js`.
+* Implement `parseDbArgs` in `src/commands/db.js` to support:
+  * `--port`: Validate this is purely numeric. Default to `5432`.
+  * `--show-credentials`: Boolean.
+  * Overrides: `--region`, `--cluster`, `--service`, and `--workspace`.
+
+**2. AWS Resource Discovery (`src/commands/db.js`):**
+* **Preconditions:** Reuse the `hasAwsCli` check (and Session Manager plugin guidance) before attempting the connection.
+* **Resolve Names:** Use the shared resolvers. If a `--workspace` is provided (or if you detect one locally by reading `.terraform/environment`), append `-${workspace}` to the base project name so it correctly targets PR-preview resources (e.g., `${baseProjectName}-${workspace}-db`). If it's the default workspace, do not append anything.
+* **Find the DB:** Query RDS `DescribeDBInstances` for the resolved DB identifier. 
+  * *Edge Case:* If this throws `DBInstanceNotFound` (or if no DB is found), catch it and print a friendly, graceful exit message explaining that no database is provisioned for this environment.
+  * Extract the `Endpoint.Address`, `DBName`, and `MasterUserSecret.SecretArn`.
+* **Fetch the Credentials:** Query Secrets Manager `GetSecretValue` using the `SecretArn`. Parse the returned JSON string to dynamically extract both `username` and `password`.
+* **Find an ECS Task:** Query ECS `ListTasks` for the resolved cluster and service. Call `DescribeTasks` on the first returned task ARN. 
+  * *Robustness:* Instead of blindly taking `containers[0]`, use the same logic as `exec.js`: find the expected container by name, or fallback to the first `RUNNING` container, then extract its `runtimeId`.
+
+**3. Terminal Output & Security:**
+Print a clear success message so the user can easily copy the credentials:
+* Print the Local Host, Local Port, Database Name, and Username.
+* **Security Check:** Unless the user passed `--show-credentials`, mask the password in the terminal output as `********`. If the flag is present, print the decrypted password.
+* Print a fully formed connection string (also masking the password unless the flag is passed):
+  `postgresql://<username>:<password_or_mask>@localhost:<localPort>/<dbname>`
+
+**4. Execute the SSM Tunnel:**
+* Spawn the `aws` CLI as a child process using `spawn` (inheriting `stdio: 'inherit'`).
+* Construct the arguments as an array to prevent Windows parsing errors:
+  ```javascript
+  const ssmArgs = [
+      'ssm', 'start-session',
+      '--target', `ecs:${clusterName}_${taskId}_${runtimeId}`,
+      '--document-name', 'AWS-StartPortForwardingSessionToRemoteHost',
+      '--parameters', `{"host":["${dbHost}"],"portNumber":["5432"],"localPortNumber":["${localPort}"]}`,
+      '--region', region
+  ];
+  ```
+* Wrap the flow in the standard error handling. Explicitly check for `UnrecognizedClientException` and `ExpiredTokenException` to trigger the centralized `aws sso login` guidance. Handle the specific case where no running ECS tasks are found.
+* Fire a telemetry event named `db_connect_run`. **CRITICAL:** Explicitly ensure that the database password, username, and connection string are NEVER included in the telemetry event properties.
+
+**5. Additional Deliverables:**
+* Create `tests/db.test.js` with fully hoisted mocks for the AWS SDKs (`RDSClient`, `ECSClient`, `SecretsManagerClient`) and `spawn`. Verify the masking logic, missing DB logic, workspace resolution, and successful arg construction.
+* Create a documentation page at `apps/docs/src/content/docs/cli/db.md` explaining the `db connect` command, the `--port` flag, the `--show-credentials` flag, and the override flags (`--workspace`, `--region`, `--cluster`, `--service`).
+* **Doc Registration:** Update `apps/docs/astro.config.mjs` to register the new `db.md` page in the `sidebar` array under the CLI Reference section.

package/specs/db-lifecycle-migrations.md

@@ -0,0 +1,159 @@
+# Spec: Database Lifecycle & Migration Suite (`db migrate`, `db backup`, `db restore`, & Pre-Deploy Migration Gate)
+
+## Overview
+Deliver end-to-end Day-2 relational database lifecycle management for `deploy-stack` in two clean phases:
+* **Phase A (Pre-Refactor & Shared Utilities):** Split `src/commands/db.js` into modular subcommand files under `src/commands/db/` (with `src/commands/db.js` acting as the dispatcher and re-export barrel), recurse in `tests/commands-import.test.js`, and extract shared helpers across `src/utils/rds.js`, `src/utils/ecs.js`, `src/utils/detector.js`, `src/utils/resolvers.js`, `src/utils/system.js`, and `src/commands/logs.js`.
+* **Phase B (Feature Implementation):**
+  1. **On-Demand Remote Migration Runner (`deploy-stack db migrate`):** Launch an ephemeral one-off ECS Fargate task in the service's VPC subnets using the active service task definition (or an explicit `--task-def` revision in CI), stream CloudWatch logs via `FilterLogEventsCommand` with event deduplication, and exit with the container's exit code via `failCommand`.
+  2. **Pre-Deploy Database Migration Gate (`deploy-stack db migrate --setup-ci`):** Idempotently inject a migration gate step into `.github/workflows/deploy.yml` after the task definition registration step (using `actions/setup-node@v4` and `--task-def`) so migrations from the **newly built image** execute before the ECS service updates.
+  3. **On-Demand Database Snapshots (`deploy-stack db backup`):** Create tagged manual RDS snapshots (`CreateDBSnapshotCommand`) and poll with `pollUntil` until `available` (or return immediately with `--no-wait`).
+  4. **Database Snapshot Restore (`deploy-stack db restore`):** List snapshots via `DescribeDBSnapshotsCommand` (with pagination), warn explicitly about data replacement (`skip_final_snapshot = true`), and idempotently upsert `snapshot_identifier` inside `resource "aws_db_instance" "postgres"` in `terraform/database.tf`.
+
+---
+
+## Part 1: Pre-Refactor & Shared Utilities
+
+1. **Modular `db` Directory + Recursive Import Guard:**
+   * Move the existing `connect` implementation into `src/commands/db/connect.js` and add `src/commands/db/migrate.js`, `src/commands/db/backup.js`, and `src/commands/db/restore.js`.
+   * Keep `src/commands/db.js` as the `runDb` dispatcher and re-export barrel (`runDb`, `runDbConnect`, `parseDbArgs`, `runDbMigrate`, `parseDbMigrateArgs`, `runDbBackup`, `parseDbBackupArgs`, `runDbRestore`, `parseDbRestoreArgs`, `detectMigrationCommand`) so existing imports in `bin/cli.js` and `tests/db.test.js` remain unbroken.
+   * Update `tests/commands-import.test.js` to recursively scan `src/commands/**/*.js` so all subcommand modules in `src/commands/db/` are checked by the telemetry-import guard.
+2. **`src/utils/rds.js` (New):**
+   * `findDbInstance(rdsClient, dbIdentifier)`: wraps `DescribeDBInstancesCommand({ DBInstanceIdentifier: dbIdentifier })` and returns the instance object, or returns `null` when `DBInstanceNotFound` / `DBInstanceNotFoundFault` is thrown (re-throwing unexpected errors).
+   * `generateSnapshotId(dbIdentifier, now = new Date())`: formats `${dbIdentifier}-manual-YYYYMMDD-HHmmss` in UTC (lowercased, RDS-safe).
+   * `isValidSnapshotId(id)`: validates against RDS snapshot identifier rules (`^[a-zA-Z][a-zA-Z0-9-]{0,254}$`, no `--`, no trailing `-`).
+3. **`src/utils/detector.js`:**
+   * Implement and export `detectMigrationCommand(cwd)` here (and re-export from `src/commands/db.js`), reusing the existing `package.json`, `Gemfile`, and `manage.py` inspection patterns in priority order:
+     1. `package.json` scripts: `scripts["db:migrate"]` -> `'npm run db:migrate'`, `scripts["migrate"]` -> `'npm run migrate'`.
+     2. `prisma/schema.prisma` or `prisma` in dependencies/devDependencies -> `'npx prisma migrate deploy'`.
+     3. `drizzle.config.ts` / `.js` / `.mjs` -> `'npx drizzle-kit migrate'`.
+     4. `alembic.ini` -> `'alembic upgrade head'`.
+     5. `manage.py` -> `'python manage.py migrate --noinput'`.
+     6. `bin/rails` or `Gemfile` with `rails` -> `'bundle exec rails db:migrate'`.
+     7. Otherwise `null`.
+4. **`src/utils/resolvers.js`:**
+   * Export `resolveHeadless(options = {}, env = process.env, stdin = process.stdin, stdout = process.stdout)`: returns `true` when `Boolean(options.isHeadless || options.headless || env.CI || env.VITEST || env.NODE_ENV === 'test' || !stdin?.isTTY || !stdout?.isTTY)` (with an explicit `options.isHeadless === false` override supported for unit tests that simulate interactive TTY prompts).
+   * Export `resolveAppName(projectName, workspace, env = process.env)`: combines `projectName` with `resolveWorkspaceSuffix({ workspace }, env)` (`${projectName}${suffix}`).
+5. **`src/utils/ecs.js`:**
+   * Export `fetchActiveService(ecsClient, clusterName, serviceName)`: calls `DescribeServicesCommand({ cluster: clusterName, services: [serviceName] })` and returns the service if found with `status === 'ACTIVE'`, or `null` otherwise.
+6. **`src/utils/system.js`:**
+   * Export `pollUntil({ intervalMs, timeoutMs, sleepFn = sleep, nowFn = Date.now, onTick })`: executes `await onTick({ elapsedMs })` in a loop until it returns `{ done: true, value }` or `elapsedMs >= timeoutMs` (returning `{ timedOut: true }`), sleeping `intervalMs` between ticks.
+7. **`src/commands/logs.js`:**
+   * Export `isNotFoundError(err)` and `buildLogStreamName(containerName, taskId)` (returning `ecs/${containerName}/${taskId}`).
+
+---
+
+## Part 2: CLI Dispatcher, Parsers & Telemetry Conventions (`bin/cli.js` & `src/commands/db.js`)
+
+1. **Dispatcher (`runDb`):**
+   * `bin/cli.js` routes `case 'db':` to `await runDb(args.slice(1), { ...(isHeadless ? { isHeadless: true } : {}) })` and updates `HELP_TEXT` to list `db connect`, `db migrate`, `db backup`, and `db restore`.
+   * If `subcommand` is missing or not one of `connect | migrate | backup | restore`, call `failCommand` with event `'db_run'`, `errorCode: 'UNKNOWN_DB_SUBCOMMAND'`, `reason: 'unknown-db-subcommand'`, and actionable usage output.
+2. **Subcommand Argument Parsers (Backward-Compatible):**
+   * Keep `parseDbArgs(rawArgs)` unchanged for `db connect`.
+   * `parseDbMigrateArgs(rawArgs)`:
+     * Boolean flags: `['setup-ci', 'headless']`
+     * String flags: `[{ name: 'cmd', key: 'cmd' }, { name: 'task-def', key: 'taskDef' }, { name: 'timeout', key: 'timeout' }, { name: 'project-name', key: 'projectName' }, { name: 'region', key: 'region' }, { name: 'workspace', key: 'workspace' }, { name: 'cluster', key: 'cluster' }, { name: 'service', key: 'service' }, { name: 'container', key: 'container' }]`
+     * Also capture `rest`: if `rest.length > 0`, fail fast in `runDbMigrate` with `errorCode: 'UNEXPECTED_POSITIONAL_ARGS'`, `reason: 'unexpected-positional-args'`, hinting to wrap multi-word `--cmd` values in quotes.
+   * `parseDbBackupArgs(rawArgs)`:
+     * Boolean flags: `['no-wait', 'headless']`
+     * String flags: `[{ name: 'id', key: 'snapshotId' }, { name: 'timeout', key: 'timeout' }, { name: 'project-name', key: 'projectName' }, { name: 'region', key: 'region' }, { name: 'workspace', key: 'workspace' }, { name: 'db-identifier', key: 'dbIdentifier' }]`
+   * `parseDbRestoreArgs(rawArgs)`:
+     * Boolean flags: `['yes', 'headless']`
+     * String flags: `[{ name: 'project-name', key: 'projectName' }, { name: 'region', key: 'region' }, { name: 'workspace', key: 'workspace' }, { name: 'db-identifier', key: 'dbIdentifier' }]`
+     * Positional: `snapshotId = rest[0] || ''` (matching the `rollback.js` positional pattern).
+3. **Telemetry Conventions:**
+   * Event names: `'db_migrate_run'`, `'db_backup_run'`, `'db_restore_run'`.
+   * Use `trackSuccess` and `failCommand` (with `errorCode: 'SCREAMING_SNAKE_CASE'` and `reason: 'kebab-case'`, plus `handleAuthErrorBranch` for AWS credential errors).
+   * **Privacy:** Never include raw `--cmd` strings or snapshot ARNs in telemetry properties; for `db_migrate_run`, record `cmd_source: 'explicit' | 'detected' | 'prompted'` and `ci_setup: Boolean(setupCi)`.
+
+---
+
+## Part 3: On-Demand Remote Migration Runner (`src/commands/db/migrate.js`)
+
+1. **Command Resolution & Timeout Validation:**
+   * Validate `--timeout` if provided: must parse to a positive integer (seconds, default `600`); otherwise fail before AWS calls with `errorCode: 'INVALID_TIMEOUT'`, `reason: 'invalid-timeout'`.
+   * Resolve migration command:
+     * If `cmd` flag is provided and non-empty after `.trim()`, use it (`cmd_source = 'explicit'`).
+     * Else call `detectMigrationCommand(cwd)`:
+       * In interactive mode (`!resolveHeadless(options)`), prompt via Clack `text` (with `initialValue: detectedCmd || ''`, `placeholder: 'e.g. npx prisma migrate deploy'`). Handle `isCancel` cleanly. Set `cmd_source = 'prompted'`.
+       * In headless mode, if `detectedCmd` exists, use it (`cmd_source = 'detected'`); otherwise fail with `errorCode: 'MISSING_MIGRATION_CMD'`, `reason: 'missing-migration-cmd'`.
+2. **If `--setup-ci` Is Passed (Pre-Deploy Gate Injection):**
+   * Do not make AWS API calls. Locate `.github/workflows/deploy.yml` in `cwd` (if missing, fail with `errorCode: 'WORKFLOW_NOT_FOUND'`, `reason: 'workflow-not-found'`).
+   * Inject or replace a delimited block (`# deploy-stack:db-migrate-start` ... `# deploy-stack:db-migrate-end`) inside `.github/workflows/deploy.yml`:
+     * Place the block **immediately after** the `Register new Task Definition` step (or immediately before `- name: Force ECS deployment` / service update step).
+     * Ensure `actions/setup-node@v4` (with `node-version: '20'`) is included in the injected block (unless `actions/setup-node` already exists earlier in the job) so `npx` is available on `ubuntu-latest`.
+     * Run `npx deploy-stack db migrate --cmd <shell-safe-quoted-cmd> --task-def "${{ steps.register-task-def.outputs.task-def-arn || env.NEW_TASK_DEF_ARN }}" --headless` (matching the task definition output/variable from `templates/github/deploy.yml` so migrations run using the **newly registered image revision** before the ECS service updates).
+   * Write the updated workflow file, emit `trackSuccess('db_migrate_run', { cmd_source, ci_setup: true })`, and return.
+3. **Live ECS Task Execution (`!setupCi`):**
+   * Resolve `projectName`, `region`, `appName = resolveAppName(projectName, workspace)`, `clusterName = resolveCluster({ cluster }, appName)`, `serviceName = resolveService({ service }, appName)`.
+   * Call `fetchActiveService(ecsClient, clusterName, serviceName)`:
+     * If missing, fail with `errorCode: 'ECS_SERVICE_NOT_FOUND'`, `reason: 'ecs-service-not-found'`.
+     * Extract `awsvpcConfiguration` (`subnets`, `securityGroups`, `assignPublicIp = 'ENABLED'`) from `service.networkConfiguration.awsvpcConfiguration`.
+   * Determine `targetTaskDef = options.taskDef || service.taskDefinition`.
+   * Call `DescribeTaskDefinitionCommand({ taskDefinition: targetTaskDef })` and resolve the target container via `resolveContainer({ container }, appName)` (or `pickRuntimeContainer`):
+     * If the resolved container name does not exist in `taskDefinition.containerDefinitions`, fail before `RunTaskCommand` with `errorCode: 'CONTAINER_NOT_FOUND'`, `reason: 'container-not-found'`.
+   * Launch the task via `RunTaskCommand`:
+     * `cluster`: `clusterName`
+     * `taskDefinition`: `targetTaskDef`
+     * `launchType`: `'FARGATE'`
+     * `networkConfiguration`: `{ awsvpcConfiguration: { subnets, securityGroups, assignPublicIp } }`
+     * `startedBy`: `'deploy-stack-db-migrate'`
+     * `overrides`: `{ containerOverrides: [{ name: containerName, command: ['sh', '-c', resolvedCmd] }] }`
+     * If `failures?.length > 0` or `!tasks?.[0]?.taskArn`, fail with `errorCode: 'RUN_TASK_FAILED'`, `reason: 'run-task-failed'`.
+4. **CloudWatch Log Streaming, SIGINT & Exit Code Propagation:**
+   * Register a `SIGINT` listener during polling that calls `StopTaskCommand({ cluster: clusterName, task: taskArn, reason: 'Cancelled by user via SIGINT' })` (best-effort) and cleans up the listener in `finally`.
+   * Use `pollUntil` (polling interval `2000ms` default, configurable via `options.pollIntervalMs` for tests; timeout `timeoutSeconds * 1000`):
+     * On each tick, call `FilterLogEventsCommand({ logGroupName: '/ecs/' + appName, logStreamNames: [buildLogStreamName(containerName, taskId)], startTime })` while deduplicating via a `seenEventIds = new Set()` (mirroring `src/commands/logs.js` and ignoring `isNotFoundError(err)` while the stream is initializing). Print new messages to stdout.
+     * Call `DescribeTasksCommand({ cluster: clusterName, tasks: [taskArn] })`. When `task.lastStatus === 'STOPPED'`, sleep `settleDelayMs` (`500ms` default, `0ms` in tests), perform one final log fetch, and return `{ done: true, value: task }`.
+   * If `pollUntil` times out, call `StopTaskCommand` (best-effort) and call `failCommand` with `errorCode: 'MIGRATION_TIMEOUT'`, `reason: 'migration-timeout'`.
+   * Inspect the matching container in `task.containers`:
+     * Prefer `container.reason` over `task.stoppedReason`.
+     * If `container?.exitCode === 0`, call `trackSuccess('db_migrate_run', { cmd_source, ci_setup: false })` and return `{ success: true, exitCode: 0, taskArn }`.
+     * Otherwise, compute `exitCode = (typeof container?.exitCode === 'number' && container.exitCode > 0) ? container.exitCode : 1` and call `failCommand` with event `'db_migrate_run'`, `errorCode: 'MIGRATION_TASK_FAILED'`, `reason: 'migration-task-failed'`, `exitCode`, and `extra: { exit_code: container?.exitCode ?? -1 }`.
+
+---
+
+## Part 4: On-Demand RDS Snapshots & Restore (`src/commands/db/backup.js` & `restore.js`)
+
+1. **`deploy-stack db backup` (`src/commands/db/backup.js`):**
+   * Validate `--id` (if provided) via `isValidSnapshotId(id)` before making AWS calls; if invalid, fail with `errorCode: 'INVALID_SNAPSHOT_ID'`, `reason: 'invalid-snapshot-id'`.
+   * Validate `--timeout` (if provided, positive integer seconds, default `900`).
+   * Resolve `appName = resolveAppName(projectName, workspace)` and `dbIdentifier = resolveDbIdentifier({ dbIdentifier }, appName)`.
+   * Call `findDbInstance(rdsClient, dbIdentifier)`; if `null`, fail with `errorCode: 'RDS_INSTANCE_NOT_FOUND'`, `reason: 'rds-instance-not-found'`.
+   * Generate `snapshotId = options.snapshotId || generateSnapshotId(dbIdentifier)`.
+   * Call `CreateDBSnapshotCommand({ DBInstanceIdentifier: dbIdentifier, DBSnapshotIdentifier: snapshotId, Tags: [{ Key: 'ManagedBy', Value: 'deploy-stack' }, { Key: 'Project', Value: projectName }] })`.
+   * If `--no-wait` is true, log the snapshot ID, emit `trackSuccess('db_backup_run', { waited: false })`, and return `{ snapshotId, status: 'creating' }`.
+   * Otherwise poll `DescribeDBSnapshotsCommand({ DBSnapshotIdentifier: snapshotId })` via `pollUntil` (interval `5000ms` default, configurable via `options.pollIntervalMs`; timeout `timeoutSeconds * 1000`):
+     * Ignore transient `DBSnapshotNotFound` / `DBSnapshotNotFoundFault` on early ticks (eventual consistency right after `CreateDBSnapshot`).
+     * When `snapshot.Status === 'available'`, log the snapshot ID and restore command hint (`npx deploy-stack db restore ${snapshotId}`), emit `trackSuccess('db_backup_run', { waited: true })`, and return `{ snapshotId, status: 'available' }`.
+     * On timeout, fail with `errorCode: 'SNAPSHOT_TIMEOUT'`, `reason: 'snapshot-timeout'`.
+2. **`deploy-stack db restore` (`src/commands/db/restore.js`):**
+   * Check that `terraform/database.tf` exists in `cwd` (if missing, fail with `errorCode: 'DATABASE_TF_NOT_FOUND'`, `reason: 'database-tf-not-found'`).
+   * Resolve `appName` and `dbIdentifier = resolveDbIdentifier({ dbIdentifier }, appName)`.
+   * Paginate `DescribeDBSnapshotsCommand({ DBInstanceIdentifier: dbIdentifier })` using `Marker` (and if a specific positional `snapshotId` was passed and not found under `DBInstanceIdentifier`, fall back to `DescribeDBSnapshotsCommand({ DBSnapshotIdentifier: snapshotId })` so snapshots from previously replaced/deleted instances can still be restored by ID).
+   * Sort discovered snapshots by `SnapshotCreateTime` descending:
+     * If no snapshots are found, fail with `errorCode: 'NO_SNAPSHOTS_FOUND'`, `reason: 'no-snapshots-found'`.
+   * If positional `snapshotId` is omitted:
+     * If `resolveHeadless(options)` is true, fail with `errorCode: 'MISSING_SNAPSHOT_ID'`, `reason: 'missing-snapshot-id'`.
+     * Otherwise prompt with Clack `select` displaying each snapshot's identifier, UTC timestamp, storage size, and type.
+   * Verify the selected snapshot has `Status === 'available'` (else fail with `errorCode: 'SNAPSHOT_NOT_AVAILABLE'`, `reason: 'snapshot-not-available'`).
+   * **Destructive Data Replacement Warning & Confirmation:**
+     * If `!options.yes`:
+       * In headless mode, fail with `errorCode: 'CONFIRMATION_REQUIRED'`, `reason: 'confirmation-required'`.
+       * In interactive mode, warn explicitly that setting `snapshot_identifier` on `aws_db_instance.postgres` will replace the current RDS instance on the next `apply` and (`skip_final_snapshot = true`) permanently discard any data written after the snapshot unless backed up first (recommending `npx deploy-stack db backup` first), then prompt `confirm`.
+   * **Idempotent HCL Upsert in `terraform/database.tf`:**
+     * Export a pure helper `upsertSnapshotIdentifier(hclContent, snapshotId)` scoped to `resource "aws_db_instance" "postgres"` (following the resource-scoped edit pattern in `src/commands/add.js`):
+       * Replace an existing `snapshot_identifier = "..."` attribute inside `resource "aws_db_instance" "postgres"`, or insert `snapshot_identifier = "${snapshotId}"` inside the resource block.
+       * Add or preserve a comment noting that `snapshot_identifier` should remain in `database.tf` after `apply` so subsequent applies stay no-op.
+     * Write `terraform/database.tf`, log instructions to run `npx deploy-stack apply`, call `trackSuccess('db_restore_run', {})`, and return `{ snapshotId }`.
+
+---
+
+## Part 5: Documentation, Roadmap & Unit Tests
+
+1. **Documentation & Roadmap:**
+   * Update `apps/docs/src/content/docs/cli/db.md` to cover `db connect`, `db migrate` (`--cmd`, `--task-def`, `--setup-ci`, `--timeout`), `db backup` (`--id`, `--no-wait`, `--timeout`), and `db restore` (`<snapshot-id>`, `--yes`, and the `snapshot_identifier` lifecycle note).
+   * Mark **Pre-Deploy Database Migration Gate**, **On-Demand Database Snapshots & Restore**, and **On-Demand Remote Migration Runner** as `[x]` in `README.md` and `apps/docs/src/content/docs/roadmap.md`.
+2. **Unit Tests (`tests/db.test.js` & utility test files):**
+   * Use `stripVTControlCharacters` from `node:util` on any `picocolors`-styled output assertions per `.muserules`.
+   * Test `src/utils/rds.js` (`findDbInstance`, `generateSnapshotId`, `isValidSnapshotId`), `detectMigrationCommand(cwd)` in `src/utils/detector.js`, `resolveHeadless` in `src/utils/resolvers.js`, `fetchActiveService` in `src/utils/ecs.js`, `pollUntil` in `src/utils/system.js`, and `buildLogStreamName` / `isNotFoundError` in `src/commands/logs.js`.
+   * Test `runDb` dispatcher (`UNKNOWN_DB_SUBCOMMAND`), `db migrate` (command resolution, unquoted positional guard, container validation against task definition, `--task-def` override, `FilterLogEventsCommand` deduplication + `ResourceNotFoundException` handling, exit code propagation via `failCommand`, timeout + `StopTaskCommand`, and `--setup-ci` idempotent injection into `.github/workflows/deploy.yml`), `db backup` (invalid `--id` fast failure, `--no-wait`, `DBSnapshotNotFound` eventual consistency during polling, quota/modifying error propagation), and `db restore` (pagination, fallback lookup by `DBSnapshotIdentifier`, headless guards, and idempotent `upsertSnapshotIdentifier` on `terraform/database.tf`).

package/specs/dependency-aware-init.md

@@ -0,0 +1,176 @@
+# Spec: Dependency-Aware Smart `init` & Multi-Capability Composition
+
+## Overview
+Upgrade `deploy-stack init` (`mainStack` in `src/commands/init.js`) from a framework-only scaffolder into a dependency-aware stack composer that inspects project manifests, local Docker Compose topologies, and environment variable templates to pre-select infrastructure capabilities and scaffold Day-0 + Day-2 addons in a single pass—while keeping `init --headless` deterministic when `--with` is omitted.
+
+### Core Principles
+1. **Zero Duplicate Template Logic:** `src/commands/init.js` must never duplicate HCL manipulation or addon rendering. Extract a quiet `scaffoldAddon()` helper in `src/commands/add.js` (paired with the existing `resolveAddonOptions`) and reuse `injectMigrationGate` from `src/commands/db/migrate.js`.
+2. **Evidence-Based Pre-Selection:** Every pre-checked option in interactive mode displays the exact manifest or file signal that triggered it (`detected: ioredis, docker-compose redis`).
+3. **Deterministic Headless Mode:** Running `deploy-stack init --headless` without `--with` preserves existing behavior and stdout (no surprise addon `.tf` files). Passing `--with <cap1,cap2,...>` explicitly scaffolds the requested addons in headless or interactive mode.
+4. **Fail-Fast Validation Before Side Effects:** All `--with` and addon-flag validations run immediately after target directory resolution—before interactive prompts, AWS state-bucket provisioning, or `handleExistingFiles` backup creation.
+
+---
+
+## Part 1: Project Capability Scanner (`src/utils/capabilities.js` & `src/utils/detector.js`)
+
+### 1. New Module Placement & Export
+Create `src/utils/capabilities.js` exporting `detectProjectCapabilities(cwd)` and re-export it from `src/utils/detector.js`.
+
+### 2. Return Shape
+* `relationalDb`: `{ detected: boolean, evidence: string[] }` (PostgreSQL-compatible RDS signals only)
+* `worker`: `{ detected: boolean, suggestedCommand: string | null, evidence: string[] }`
+* `migration`: `{ detected: boolean, command: string | null }` (delegates to `detectMigrationCommand(cwd)` from `src/commands/db/migrate.js`)
+* `addons`: Map keyed by `ADDON_REGISTRY` capability ID (`db:redis`, `queue:sqs`, `storage:s3`, `db:dynamodb`, `ai:bedrock`, `email:ses`), each `{ detected: boolean, evidence: string[] }`
+* `upcomingHints`: `{ vector: boolean, cron: boolean, mysql: boolean }`
+
+### 3. Manifest & Config Scanning Rules (Read-Only, Fault-Tolerant, Tokenized)
+Wrap all file reads in `try/catch` (reusing `readFileSafe` where helpful) so malformed files never crash `init`.
+* **Tokenized Matching (No Substring Hazards):**
+  * `package.json`: match exact keys in merged `dependencies`, `devDependencies`, and `peerDependencies`.
+  * `requirements.txt`, `pyproject.toml`, `Pipfile`: extract normalized package names per line/entry via regex (`^[a-zA-Z0-9._-]+`, lowercased, with `_` normalized to `-` for comparison) without adding a TOML dependency.
+  * `go.mod`: match exact module paths per line.
+  * `Gemfile`: match exact gem names via `/^\s*gem\s+['"]([^'"]+)['"]/m`.
+* **Environment Template Keys Only:** Scan `.env.example`, `.env.sample`, `.env.template`, and `.env` strictly for **variable key names** (`^[A-Z0-9_]+(?==)`). Never read, parse, or log variable values.
+* **Docker Compose (`src/utils/dockerCompose.js`):** Extend `parseDockerCompose` additively to check `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, and `compose.yaml`.
+* **Signal Matrix:**
+  1. **`relationalDb` (PostgreSQL RDS Pre-Select):**
+     * Node: `pg`, `postgres`, `typeorm`, `sequelize`, `knex`, `mikro-orm`, `drizzle-orm`, `drizzle-kit`, `@prisma/client`, `prisma` (unless `prisma/schema.prisma` explicitly specifies `provider = "mysql"`, `"sqlite"`, or `"mongodb"`).
+     * Python: `psycopg2`, `psycopg2-binary`, `psycopg`, `asyncpg`, `sqlalchemy`, `sqlmodel`, `alembic`, `django`.
+     * Go: `github.com/lib/pq`, `github.com/jackc/pgx`, `gorm.io/driver/postgres`.
+     * Ruby: `pg`, `rails`.
+     * Files / Compose / Env Keys: `drizzle.config.ts|js|mjs`, `alembic.ini`, `manage.py`, `bin/rails`, `prisma/schema.prisma` with `provider = "postgresql" | "postgres" | "cockroachdb"`, Docker Compose `postgres` / `postgis/postgis` image, or env keys `DATABASE_URL`, `POSTGRES_URL`, `POSTGRES_PRISMA_URL`, `PGHOST`.
+  2. **MySQL Signals (`upcomingHints.mysql` Only — Never Pre-Select PostgreSQL RDS):**
+     * Node: `mysql2`, `mysql`; Python: `pymysql`, `mysqlclient`, `aiomysql`; Go: `github.com/go-sql-driver/mysql`, `gorm.io/driver/mysql`; Ruby: `mysql2`; `prisma/schema.prisma` with `provider = "mysql"`; Docker Compose `mysql` / `mariadb` image; env keys `MYSQL_URL`, `MYSQL_HOST`.
+     * When only MySQL signals are present (and no PostgreSQL signals), set `relationalDb.detected = false` and `upcomingHints.mysql = true`. If both PostgreSQL and MySQL signals are present, both `relationalDb.detected` and `upcomingHints.mysql` are `true`.
+  3. **`db:redis`:**
+     * Node: `ioredis`, `redis`, `@upstash/redis`, `bull`, `bullmq`; Python: `redis`, `aioredis`, `rq`, or `celery` + `redis` co-presence; Go: `github.com/redis/go-redis`, `github.com/gomodule/redigo`; Ruby: `redis`, `sidekiq`, `connection_pool`.
+     * Compose: `redis`, `valkey/valkey`, `bitnami/redis`, `redis/redis-stack`.
+     * Env keys: `REDIS_URL`, `VALKEY_URL`, `REDIS_HOST`, `CELERY_BROKER_URL`.
+  4. **`queue:sqs`:**
+     * Node: `@aws-sdk/client-sqs`, `sqs-consumer`; Python: `kombu` or env key; Go: `github.com/aws/aws-sdk-go-v2/service/sqs`; Ruby: `aws-sdk-sqs`, `shoryuken`.
+     * Compose: `localstack/localstack` (with `sqs` in `SERVICES` if present) or `roribio16/alpine-sqs`.
+     * Env keys: `SQS_QUEUE_URL`, `SQS_DLQ_URL`, `AWS_SQS_QUEUE_URL`.
+  5. **`storage:s3`:**
+     * Node: `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`, `multer-s3`; Python: `django-storages`, `s3fs`; Go: `github.com/aws/aws-sdk-go-v2/service/s3`; Ruby: `aws-sdk-s3`, `shrine`, `carrierwave`.
+     * Compose: `minio/minio`.
+     * Env keys: `S3_BUCKET_NAME`, `S3_BUCKET`, `AWS_S3_BUCKET`, `S3_CDN_URL`.
+  6. **`db:dynamodb`:**
+     * Node: `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb`, `dynamoose`; Python: `pynamodb`, `aioboto3`; Go: `github.com/aws/aws-sdk-go-v2/service/dynamodb`; Ruby: `aws-sdk-dynamodb`.
+     * Compose: `amazon/dynamodb-local`.
+     * Env keys: `DYNAMODB_TABLE_NAME`, `DYNAMODB_TABLE`.
+  7. **`ai:bedrock`:**
+     * Node: `@aws-sdk/client-bedrock-runtime`, `@aws-sdk/client-bedrock`, `@ai-sdk/amazon-bedrock`, `@langchain/aws`; Python: `langchain-aws`; Go: `github.com/aws/aws-sdk-go-v2/service/bedrockruntime`; Ruby: `aws-sdk-bedrockruntime`.
+     * Env keys: `BEDROCK_MODEL_ID`, `AWS_BEDROCK_MODEL_ID`.
+  8. **`email:ses`:**
+     * Node: `@aws-sdk/client-ses`, `@aws-sdk/client-sesv2`; Python: `django-ses`; Go: `github.com/aws/aws-sdk-go-v2/service/ses`, `github.com/aws/aws-sdk-go-v2/service/sesv2`; Ruby: `aws-sdk-ses`, `aws-sdk-sesv2`.
+     * Env keys: `SES_FROM_EMAIL`, `SES_REGION`, `AWS_SES_REGION`.
+  9. **`worker`:**
+     * `package.json` scripts containing `worker`, `queue:work`, or `bull` -> `suggestedCommand: "npm run <script>"`; Node `bullmq`/`bull`/`sqs-consumer`; Python `celery`/`rq`/`dramatiq`; Ruby `sidekiq`/`shoryuken`/`good_job`; or non-web worker service in `Procfile` / Docker Compose.
+  10. **`upcomingHints.vector` & `upcomingHints.cron`:**
+      * `vector`: `pgvector` package (Node/Python/Ruby/Go), `prisma/schema.prisma` containing `vector`, or `ankane/pgvector` / `pgvector/pgvector` image in Docker Compose.
+      * `cron`: `node-cron`, `cron`, `agenda`, `APScheduler`, `celery-beat`, `robfig/cron`, `whenever`, `sidekiq-cron`, `sidekiq-scheduler`, or a non-empty `crons` array in `vercel.json`.
+* **Evidence Formatting:** Format every evidence entry concisely as `<item>` (e.g., `'ioredis'`, `'docker-compose redis'`, `'REDIS_URL'`), deduplicated per capability and rendered in prompt hints as `detected: <item1>, <item2>`.
+
+---
+
+## Part 2: CLI Parser, `projectName` Sanitization & Fail-Fast Validation
+
+### 1. `sanitizeProjectName` in `src/utils/prompts.js`
+* Export `sanitizeProjectName(rawName)`:
+  * Coerce to string, trim, lowercase, replace any sequence of characters outside `[a-z0-9-]` (including dots `.` and underscores `_`) with a single hyphen `-`, strip leading and trailing hyphens, and fall back to `'app'` if the result is empty.
+* In `getTargetDirectory` (`src/utils/prompts.js`), apply `sanitizeProjectName` to `actualProjectName` (never to `targetDir`). If the sanitized name differs from the raw basename/input, log a dim note (`Project name sanitized to "<actualProjectName>" for AWS resource compatibility.`).
+
+### 2. Parser & Entry-Point Plumbing (`src/utils/parser.js`, `bin/cli.js`, `src/commands/init.js`)
+* In `parseCliArgs` (`src/utils/parser.js`):
+  * Extract `isPreconfigured: args.includes('--preconfigured')`.
+  * Always populate an `initOptions` object (in both interactive and headless modes):
+    * `with`: array of capability strings parsed from all `--with <csv>` and `--with=<csv>` occurrences, split on commas, trimmed, filtered for non-empty strings, and deduplicated in order.
+    * `model`: string or `null` (`--model` / `--model=`).
+    * `domain`: string or `null` (`--domain` / `--domain=`).
+    * `zoneId`: string or `null` (`--zone-id` / `--zone-id=`).
+    * `fromEmail`: string or `null` (`--from-email` / `--from-email=`).
+    * `setupCiMigrate`: boolean (`args.includes('--setup-ci-migrate')`).
+* In `bin/cli.js` and `mainStack` (`src/commands/init.js`):
+  * Pass `{ isHeadless, isPreconfigured, headlessOptions, initOptions }` into `mainStack`. Keep the function name `mainStack` unchanged.
+
+### 3. Up-Front Validation (Before Prompts, AWS Calls, or File Backups)
+Immediately after `getTargetDirectory` in `mainStack`:
+1. If `initOptions.with.length > 0`:
+   * Verify every entry exists in `ADDON_REGISTRY`. If any entry is unknown, fail immediately with `reason: 'UNSUPPORTED_CAPABILITY'`, listing valid `Object.keys(ADDON_REGISTRY)` keys.
+2. Validate addon-specific flags for capabilities present in `initOptions.with` (silently ignoring `--model` when `ai:bedrock` is not selected, and silently ignoring `--domain`/`--zone-id`/`--from-email` when `email:ses` is not selected):
+   * If `ai:bedrock` is in `initOptions.with` and `initOptions.model` is provided, validate it with the existing Bedrock model validator (`INVALID_MODEL_ID`).
+   * If `email:ses` is in `initOptions.with`:
+     * Validate `initOptions.domain` (`INVALID_DOMAIN`), `initOptions.zoneId` (`INVALID_ZONE_ID`), and `initOptions.fromEmail` (`INVALID_FROM_EMAIL`) if provided.
+     * In headless/preconfigured mode (`isHeadless || isPreconfigured`), if `initOptions.domain` is missing and no existing `terraform/domain.tf` in `targetDir` provides a domain, fail immediately with `reason: 'MISSING_SES_DOMAIN'`.
+
+---
+
+## Part 3: Interactive Prompts & Shared Addon Scaffolding
+
+### 1. Quiet `scaffoldAddon` Core in `src/commands/add.js`
+Refactor `src/commands/add.js` so `runAdd` and `mainStack` share the exact same scaffolding pipeline:
+* Extract `scaffoldAddon(capability, resolvedOpts, { cwd, region })` which renders the addon `.tf` file, writes it to `terraform/<file>`, injects environment variables into `terraform/main.tf` and `terraform/worker.tf` (if present), applies the `queue:sqs` worker `ignore_changes` lifecycle rule when `worker.tf` exists, and calls `syncReadmeCost(cwd)`—returning `{ file, envVars, costImpact }` without calling Clack `intro`/`outro`, `trackEvent('add_run')`, or `process.exit`.
+* `runAdd` continues to call `resolveAddonOptions` + `scaffoldAddon` wrapped in its existing banners and `add_run` telemetry.
+
+### 2. Interactive Flow (`!isHeadless && !isPreconfigured`)
+Run `const capabilities = detectProjectCapabilities(targetDir)` before `getProjectConfig`:
+1. **Database Prompt (`src/utils/prompts.js`):**
+   * Pass `{ capabilities }` (optional 5th parameter) to `getProjectConfig`.
+   * If `capabilities.relationalDb.detected` is `true`, set `initialValue: true` on the PostgreSQL RDS `confirm` prompt and append `(detected: ${capabilities.relationalDb.evidence.join(', ')})` to the prompt message.
+   * If `capabilities.worker.detected` is `true` and `capabilities.worker.suggestedCommand` is non-null, pre-fill the worker command text prompt's `initialValue` / placeholder.
+2. **Pre-Deploy Migration Gate Prompt (`src/commands/init.js`):**
+   * If `config.hasDb` is `true` and `capabilities.migration.detected` is `true`:
+     * If `initOptions.setupCiMigrate` was passed, enable the migration gate automatically without prompting.
+     * Otherwise prompt with Clack `confirm`:
+       * `message: 'Enable pre-deploy database migration gate in GitHub Actions? (detected: ' + capabilities.migration.command + ')'`
+       * `initialValue: true`
+3. **Addons `multiselect` Prompt (`src/commands/init.js`):**
+   * Skip for static sites (`isStaticSite === true`).
+   * Build `options` in canonical order (`storage:s3`, `db:dynamodb`, `db:redis`, `queue:sqs`, `ai:bedrock`, `email:ses`), setting `hint` to `detected: <evidence> · <costLabel>` when detected (or `<costLabel>` otherwise).
+   * Pre-check (`initialValues`) the union of `initOptions.with` and capabilities where `capabilities.addons[cap].detected === true`.
+   * Prompt with `multiselect({ message: 'Select cloud addons to scaffold (Space to toggle, Enter to confirm):', options, initialValues, required: false })`.
+4. **Follow-Up Prompts for Selected Addons (`ai:bedrock` & `email:ses`):**
+   * For `ai:bedrock`: if `initOptions.model` is set, resolve with that model. Otherwise prompt with `confirm({ message: 'Use recommended Bedrock model (' + defaultModelId + ')?', initialValue: true })`. If confirmed, resolve with the default model; if declined, call `resolveAddonOptions('ai:bedrock', {}, { cwd: targetDir, region, isInteractive: true })` to launch the two-step provider/model picker.
+   * For `email:ses`: call `resolveAddonOptions('email:ses', { domain: initOptions.domain, zoneId: initOptions.zoneId, fromEmail: initOptions.fromEmail }, { cwd: targetDir, region, isInteractive: true })`.
+   * For all other selected addons: call `resolveAddonOptions(cap, {}, { cwd: targetDir, region, isInteractive: false })`.
+
+---
+
+## Part 4: Generation Ordering, Visualizer Preview, Hints & Telemetry
+
+### 1. Generation Sequence in `mainStack` (`src/commands/init.js`)
+Execute in this exact order after prompts and `handleExistingFiles`:
+1. **Base Templates:** Compute `ESTIMATED_COST` including `selectedAddons` (`estimateMonthlyCost({ ...config, addons: selectedAddons })`) and call `generateTemplates(targetDir, ...)` so `main.tf`, `worker.tf`, `database.tf`, `README.md`, and `.github/workflows/deploy.yml` are written first.
+2. **Addon Scaffolding:** Iterate through `selectedAddons` in canonical registry order, calling `scaffoldAddon(cap, resolvedOptsByCap[cap], { cwd: targetDir, region })` and logging a concise per-addon confirmation line (`✅ Scaffolded terraform/<file> (<cap>)`).
+3. **Pre-Deploy Migration Gate:** If enabled (via interactive confirmation or `--setup-ci-migrate`), read `.github/workflows/deploy.yml`, transform it via `injectMigrationGate(content, migrationCmd)`, and write it back. If `--setup-ci-migrate` was passed in headless mode but `!config.hasDb` or `!capabilities.migration.command`, log a `log.warn` note and continue without failing.
+4. **Print-Only Visualizer Preview (When Addons Are Scaffolded):** If `selectedAddons.length > 0`, call `parseTerraformConfig(path.join(targetDir, 'terraform'))`, attach `framework`, and call `renderDryRunPreview(parsedConfig, true)` (print-only mode) so the user sees their full stack topology and cost breakdown without altering default no-addon headless stdout.
+5. **Post-Init Capability Hints:** In the outro area, if `capabilities.upcomingHints.vector`, `capabilities.upcomingHints.cron`, or `capabilities.upcomingHints.mysql` is `true`, print concise one-line informational hints (e.g., noting `pgvector`, scheduled tasks, or that RDS currently provisions PostgreSQL when MySQL dependencies were detected).
+
+### 2. Telemetry (`project_provisioned`)
+Enrich the existing `project_provisioned` event in `src/commands/init.js` with:
+* `selected_addons`: string array of scaffolded capability IDs (e.g. `['db:redis', 'queue:sqs']`, or `[]`).
+* `detected_addons`: string array of auto-detected capability IDs from `capabilities.addons`.
+* `migration_gate_enabled`: boolean.
+
+---
+
+## Part 5: CI Validation, Documentation & Unit Tests
+
+### 1. CI Workflow (`.github/workflows/iac-validation.yml`)
+Add a validation step that initializes a backend project with `--headless --with storage:s3,db:dynamodb,db:redis,queue:sqs,ai:bedrock,email:ses --domain example.com --setup-ci-migrate` (with `CI_MOCK_AWS=true`) and runs `terraform init -backend=false && terraform validate`.
+
+### 2. Documentation (`apps/docs/src/content/docs/cli/init.md` & `README.md`)
+Document smart dependency detection, the interactive addon `multiselect`, and the new flags (`--with`, `--model`, `--domain`, `--zone-id`, `--from-email`, `--setup-ci-migrate`).
+
+### 3. Unit Tests (`tests/capabilities.test.js`, `tests/headless.test.js`, `tests/parser.test.js`)
+* **`tests/capabilities.test.js` (new):**
+  * Test tokenized detection across `package.json`, `requirements.txt`, `pyproject.toml`, `Pipfile`, `go.mod`, `Gemfile`, `prisma/schema.prisma` (Postgres vs MySQL vs SQLite), `docker-compose.yml` / `compose.yaml`, `vercel.json` crons, and `.env.example` key names (verifying `.env` values are never read and substring false-positives do not fire).
+  * Verify Drizzle, Alembic, Django, and Rails trigger `relationalDb.detected === true`, while MySQL-only projects set `relationalDb.detected === false` and `upcomingHints.mysql === true`.
+* **`tests/parser.test.js`:**
+  * Test `initOptions` parsing: repeatable and comma-separated `--with` deduplication, `--model`, `--domain`, `--zone-id`, `--from-email`, `--setup-ci-migrate`, and `isPreconfigured`.
+* **`tests/headless.test.js`:**
+  * Verify `sanitizeProjectName` converts dots and underscores (`my.app_v2` -> `my-app-v2`) without changing `targetDir`.
+  * Verify default `init --headless` (without `--with`) writes no addon `.tf` files (`redis.tf`, `ses.tf`, etc.) even when dependencies exist in `package.json`.
+  * Verify `init --headless --with db:redis,queue:sqs,ai:bedrock` scaffolds `redis.tf`, `sqs.tf`, and `bedrock.tf`, injects all env vars into `main.tf` (and `worker.tf` with `ignore_changes`), and emits `selected_addons` on `project_provisioned`.
+  * Verify fail-fast guards (`UNSUPPORTED_CAPABILITY`, `MISSING_SES_DOMAIN`, `INVALID_MODEL_ID`) trigger before `provisionStateBucket` or `handleExistingFiles` backup runs.
+  * Update any telemetry module mock in `tests/headless.test.js` if needed to preserve named exports.