grada-run 0.32.0 → 0.33.0

package/.github/workflows/e2e.yml

@@ -0,0 +1,73 @@
+name: E2E
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+jobs:
+  tier0:
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Run Tier 0 E2E
+        run: npm run test:e2e:tier0
+
+      - name: Upload workspace on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-tier0-workspace
+          path: tests/e2e/.tmp/
+          if-no-files-found: ignore
+
+  tier1:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-east-2
+
+      - name: Run Tier 1 live E2E
+        run: npm run test:e2e:tier1
+
+      - name: Upload workspace on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-tier1-workspace
+          path: tests/e2e/.tmp/
+          if-no-files-found: ignore

package/apps/docs/src/content/docs/cli/add.md

@@ -54,7 +54,7 @@ To switch Bedrock models later, just run `grada add ai:bedrock` again (interacti
 | `--model <id>` | Bedrock model or inference profile ID (default `us.anthropic.claude-sonnet-4-6`). Only applies to `ai:bedrock`. |
 | `--list-models` | Print the Bedrock model catalog (works offline, no project required). Only applies to `ai:bedrock`. |
 | `--refresh` | Refresh the Bedrock model catalog from live AWS data before listing or provisioning. Only applies to `ai:bedrock`. |
-| `--domain <domain>` | Domain for the SES identity (defaults to your `domain add` domain, or prompts interactively). Only applies to `email:ses`. |
+| `--domain <domain>` | Domain for the SES identity (defaults to your `domain add` domain, or prompts interactively; required in `--headless` mode without a `domain.tf`). Only applies to `email:ses`. |
 | `--from-email <email>` | Default sender address (default `noreply@<domain>`). Must belong to the SES domain. Only applies to `email:ses`. |
 | `--zone-id <id>` | Route 53 hosted zone ID for automatic DKIM/SPF/DMARC records. Only applies to `email:ses`. |
 | `--schedule <expr>` | EventBridge Scheduler expression, e.g. `cron(0 2 * * ? *)` or `rate(1 hour)` (default `cron(0 0 * * ? *)`). Only applies to `cron`. |
@@ -62,6 +62,7 @@ To switch Bedrock models later, just run `grada add ai:bedrock` again (interacti
 | `--name <job>` | Job slug customizing the schedule name (default `daily-job`). Only applies to `cron`. |
 | `--timezone <tz>` | IANA timezone for the schedule expression (default `UTC`). Only applies to `cron`. |
 | `--force` | Overwrite the existing addon file (also accepts `--force=false`). Without it, re-adding refuses to clobber your edits. |
+| `--headless` | Scaffold without interactive prompts, using flag values and built-in defaults (Bedrock default model, daily cron schedule). |
 
 Requires a project initialized with `grada` (`terraform/main.tf` must exist).
 

package/apps/docs/src/content/docs/cli/apply.md

@@ -11,8 +11,8 @@ Run the Terraform plan/apply flow against the generated configuration.
 - Renders an infrastructure preview from your Terraform config and framework detection: a `Fixed Baseline` monthly figure with per-service breakdown, one topology entry per provisioned [`add`](/grada/cli/add/) addon (collapsing to a single `Addons (N)` line when three or more are active), and a one-line `Usage-based (N addons)` summary of metered billing drivers (shown only when usage-billed addons are present). With `--dry-run` it stops there and provisions nothing.
 - Otherwise runs `terraform init -upgrade` followed by `terraform apply -auto-approve` in `terraform/`, streaming progress, then prints the live URLs from the Terraform outputs (`cloudfront_url` and `alb_direct_url`, or `api_gateway_url` on `--target lambda`) plus the `git push` command that deploys your app and clears the initial 503.
 - On `--target lambda` projects, ensures the ECR repository exists first and seeds a minimal placeholder image under `:latest` when nothing has been pushed yet (Lambda rejects empty repositories), so Day-0 provisioning succeeds before the first code push.
-- Asks for confirmation after the preview; declining aborts without provisioning anything.
-- If the S3 state bucket is missing (e.g. deleted manually), offers to recreate it and resume automatically instead of failing.
+- Asks for confirmation after the preview; declining aborts without provisioning anything. With `--auto-approve` (or the global `--headless` flag), the preview still renders but provisioning proceeds without prompting.
+- If the S3 state bucket is missing (e.g. deleted manually), offers to recreate it and resume automatically instead of failing; `--auto-approve` and `--headless` accept the recovery without prompting.
 - If the environment is asleep (a `.grada/sleep-state.json` entry exists), warns you to run [`wake`](/grada/cli/sleep/) first — applying would start tasks against a stopped database.
 - On the known GitHub OIDC provider conflict (`EntityAlreadyExists` for `token.actions.githubusercontent.com`), tells you to set `create_oidc_provider = false` in `terraform/oidc.tf` and re-run; other failures print the Terraform error and the manual `cd terraform && terraform apply` fallback.
 
@@ -21,6 +21,7 @@ Run the Terraform plan/apply flow against the generated configuration.
 ```bash
 npx grada-run apply
 npx grada-run apply --dry-run
+npx grada-run apply --auto-approve
 ```
 
 ## Flags
@@ -28,5 +29,7 @@ npx grada-run apply --dry-run
 | Flag | Description |
 | ---- | ----------- |
 | `--dry-run` | Render a preview of the planned changes without applying them. |
+| `--auto-approve` | Skip the post-preview confirmation (and the state-bucket recovery prompt) for non-interactive runs. |
+| `--headless` | Global automation flag; implies `--auto-approve` for this command. |
 
 `apply` shells out to the `terraform` binary in your generated `terraform/` directory and streams progress while it runs.

package/apps/docs/src/content/docs/cli/destroy.md

@@ -8,21 +8,25 @@ Permanently delete the AWS infrastructure created by `apply` when a project is r
 ## What it does
 
 - Verifies you are in a grada project (`terraform/backend.tf` must exist) and that the `terraform` binary is installed, exiting otherwise.
-- Asks for explicit confirmation before doing anything destructive; declining cancels with no changes.
+- Asks for explicit confirmation before doing anything destructive; declining cancels with no changes. With `--yes` (or the global `--headless` flag), destruction proceeds without prompting.
 - Before destroying, wakes a stopped or transitional-state database back to `available` (RDS refuses to delete databases that aren't available), so tearing down an asleep environment succeeds instead of failing mid-destroy; aborts with a retry message if the database never becomes ready.
 - Runs `terraform destroy -auto-approve` in `terraform/`, streaming progress, so all compute resources (ECS or Lambda, ALB or API Gateway, database, and related resources) are removed.
-- Parses the state bucket name and region out of `terraform/backend.tf` (region defaults to `us-east-2` when not found), then optionally asks whether to also empty and delete the S3 state bucket via `teardownStateBucket`. Answering "No" keeps the bucket so `apply` can restore the infrastructure later.
+- Parses the state bucket name and region out of `terraform/backend.tf` (region defaults to `us-east-2` when not found), then optionally asks whether to also empty and delete the S3 state bucket via `teardownStateBucket`. Answering "No" keeps the bucket so `apply` can restore the infrastructure later. With `--yes` (or `--headless`), the bucket is deleted without asking.
 - Emits an `infrastructure_destroyed` telemetry event recording success and whether the state bucket was retained.
 
 ## Usage
 
 ```bash
 npx grada-run destroy
+npx grada-run destroy --yes
 ```
 
 ## Flags
 
-This command accepts no CLI flags. Both confirmation prompts are interactive.
+| Flag | Description |
+| ---- | ----------- |
+| `--yes` | Answer "Yes" to both the destruction and state-bucket confirmations for non-interactive runs. |
+| `--headless` | Global automation flag; implies `--yes` for this command. |
 
 ## See also
 

package/apps/docs/src/content/docs/cli/eject.md

@@ -7,7 +7,7 @@ Take permanent, sole ownership of your infrastructure files when you no longer w
 
 ## What it does
 
-- Asks for explicit confirmation (defaulting to "No"); declining cancels with no changes.
+- Asks for explicit confirmation (defaulting to "No"); declining cancels with no changes. With `--yes` (or the global `--headless` flag), ejection proceeds without prompting.
 - Strips grada metadata from your local files: removes the `# grada generated infrastructure` header and the `default_tags { tags = { ManagedBy = "grada" } }` block from `terraform/main.tf`, and removes the `# grada backups` block from `.gitignore`.
 - Recursively deletes every `*.bak.*` backup file in the project (skipping `node_modules` and `.git`).
 - Leaves your infrastructure fully operational as raw, standalone Terraform. As a final step, run `terraform apply` inside `terraform/` so AWS syncs state and removes the live `ManagedBy` tags.
@@ -17,11 +17,15 @@ Take permanent, sole ownership of your infrastructure files when you no longer w
 
 ```bash
 npx grada-run eject
+npx grada-run eject --yes
 ```
 
 ## Flags
 
-This command accepts no CLI flags. The confirmation prompt is interactive.
+| Flag | Description |
+| ---- | ----------- |
+| `--yes` | Skip the confirmation prompt for non-interactive runs. |
+| `--headless` | Global automation flag; implies `--yes` for this command. |
 
 ## See also
 

package/apps/docs/src/content/docs/guides/headless.md

@@ -68,6 +68,18 @@ npx grada-run --headless --framework=nestjs --needsDatabase \
   --with db:redis,ai:bedrock,email:ses --domain example.com --setup-ci-migrate
 ```
 
+## Automating lifecycle commands
+
+`--headless` also suppresses confirmations in the Day-2 lifecycle commands, so scripted pipelines can provision, tear down, and decouple without hanging on a prompt:
+
+```bash
+npx grada-run apply --auto-approve   # provision without the preview confirmation
+npx grada-run destroy --yes          # tear down compute and delete the state bucket
+npx grada-run eject --yes            # strip CLI metadata without confirming
+```
+
+Each command also accepts `--headless` directly (implying the approval flag). Without an approval flag, a non-interactive invocation cancels with no changes rather than destroying anything.
+
 ## See also
 
 - [`npx grada-run`](/grada/cli/init/) for the full flag table.

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

@@ -80,11 +80,13 @@ description: Where grada has been and what comes next — completed phases and t
 ### Phase 11: The `grada.run` Rebrand, Daily Observability & Agentic Ecosystem (Current)
 **Goal:** Transition the platform identity to **Grada (`grada.run`)**, close the daily observability gap with zero-cost CloudWatch Golden Signals, eliminate cross-command state-transition bugs, and launch the native MCP and AI Agent Plugin ecosystem.
 
-- [ ] **Unified Brand & Binary Transition (`grada`):** Transition the primary CLI binary and npm packages to `grada` / `@grada-run/grada` (while publishing a forwarding wrapper on `grada`) with transparent dual-read fallbacks for AWS tags (`ManagedBy: grada` + `grada`), local state ledgers (`.grada/` + `.grada/`), doc ownership markers (`GRADA.md`), and environment variables.
+- [x] **Unified Brand & Binary Transition (`grada`):** Ship the `grada` binary alongside `grada-run` (plus a deprecated `deploy-stack` alias) and publish the `@grada-run/grada` scoped alias on release, keeping existing deployments working through transparent dual-read fallbacks for AWS tags, local state ledgers (`.grada/` + `.deploy-stack/`), machine markers, doc ownership markers (`GRADA.md` + `DEPLOY-STACK.md`), and environment variables. (Verified live.)
 - [ ] **AI-Driven Edge-Case & State Transition Audit:** Run a systematic codebase audit tracing multi-step lifecycle mutations across both `--target ecs` and `--target lambda` (e.g., scaffold with `--db-engine aurora-postgresql` → `add queue:sqs` → `add cron` → `db enable-vector` → `sleep` → `wake` → `drift` → `rollback` → `eject` → `destroy`), patching race conditions, partial Terraform state locks, and UX dead ends.
-- [ ] **Deterministic E2E & Flaky Test Elimination:** Harden the Vitest suite by isolating network/loopback and SDK mocks, eliminating timing-dependent test flakiness, and running automated LocalStack E2E lifecycle tests (`init` → `apply` → `status` → `destroy`) in GitHub Actions.
+- [x] **Two-Tier E2E Harness & Automation Bypasses:** Ship the black-box harness (`tests/e2e/`, Tier 0 mock-AWS suite on every PR, Tier 1 live `init` → `apply` → `status` → `destroy` lifecycle on a nightly schedule) plus `--auto-approve`/`--yes`/`--headless` bypasses for `apply`, `destroy`, and `eject`, replacing the planned LocalStack approach.
+- [ ] **Deterministic Suite & Flaky Test Elimination:** Isolate network/loopback and SDK mocks in the Vitest suite, eliminate the timing-dependent loopback failure, and record first-green Tier 0 (PR) and Tier 1 (nightly) runs.
+- [ ] **Live Service Acceptance (Tier 2 E2E):** Provision each add-on capability on real AWS (nightly) and verify runtime behavior — SQS send/receive + DLQ, DynamoDB put/get, Redis connectivity, S3 presigned-URL flow, SES send, Bedrock invoke, cron scheduling — with per-service setup/assert/teardown and spend caps.
 - [ ] **Multi-Stage Dockerfile Hardening:** Refactor generated Dockerfiles to use multi-stage builds (e.g., `node:22-alpine AS builder` → `distroless/nodejs`), explicitly stripping package managers (`npm`, `yarn`) from the final runtime image to mathematically eliminate `HIGH`/`CRITICAL` vulnerability scanner noise on Day-0.
-- [ ] **Test Suite Deduplication & Hygiene:** Extract the hand-rolled `@clack/prompts` and `telemetry` mocks currently duplicated across 15+ test files into a centralized `tests/helpers/` directory to shrink maintenance surface area without dropping the 1,000+ test coverage count.
+- [x] **Test Suite Deduplication & Hygiene:** Extract the hand-rolled `@clack/prompts` and `telemetry` mocks currently duplicated across 15+ test files into a centralized `tests/helpers/` directory to shrink maintenance surface area without dropping the 1,000+ test coverage count.
 - [ ] **Golden Signals Live Telemetry & Alert Webhooks:** Upgrade `grada status` (and `grada status --watch`) to surface real-time CloudWatch Golden Signals (ECS CPU/Memory %, ALB requests/min, p95 latency, 5xx count, and RDS connections / Aurora ACUs) at $0 extra AWS cost, and add `grada alerts` to wire CloudWatch 5xx alarms and container crash events directly to Slack, Discord, or email.
 - [ ] **Architecture Decision Records (ADRs) & Docs Audit:** Review and standardize all ADRs and Astro Starlight documentation under the `grada` brand to ensure every Phase 9–11 command, flag, compute target (`ecs` and `lambda`), and IAM security boundary is accurately documented with zero stale references.
 - [ ] **Zero-Compute Static Target (`--target static`):** Provide a dedicated target for Vite SPAs, Astro SSG, and Next.js static exports that bypasses compute entirely, deploying pre-built assets directly to an S3 bucket fronted by CloudFront.

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

@@ -19,7 +19,7 @@ Because `grada` generates highly dynamic Terraform (`.tf`), GitHub Actions (`.ym
 * **Updating Snapshots:** If a template change is intentional, developers must run `npm run test:update` to overwrite the baseline `__snapshots__`.
 
 ## 3. External API mocking
-To ensure tests run sub-second and deterministically without requiring real AWS credentials, we intercept network boundaries:
+To ensure tests run sub-second and deterministically without requiring real AWS credentials, we intercept network boundaries. Shared mock factories live in `tests/helpers/` (`clack.js` for `@clack/prompts`, `telemetry.js` for PostHog tracking, `console.js` for process/console spies, `tmpdir.js` for fixture directories) so new suites reuse one-liner `vi.mock` delegations instead of hand-rolling mocks:
 * **AWS Secrets Manager:** `tests/secrets.test.js` uses Vitest's `vi.hoisted()` and `vi.mock()` to intercept `@aws-sdk/client-secrets-manager` (plus an injected ECS client for the restart path). This verifies push/pull/audit payload handling, key-change detection, and network exceptions (like `ResourceNotFoundException`) completely offline.
 * **ECS & CloudWatch Logs:** `tests/diagnose.test.js` injects mock ECS/CloudWatch clients to verify failure analysis (stopped reasons, exit codes, log extraction) and behavior contracts — e.g., expired sessions (`UnrecognizedClientException`) exit gracefully with code 1, and unrecognized `secrets push` filenames fall back to `.env` with a warning.
 * **Telemetry:** PostHog tracking is mocked to prevent test executions from polluting production analytics.
@@ -30,3 +30,8 @@ While Vitest proves the CLI generates the *correct* files, GitHub Actions proves
 * **Phase 2 (Static Application Security Testing - SAST):** CI runs a pinned Trivy filesystem scan (`aquasecurity/trivy-action` by SHA) against each generated project directory, writing advisory `trivy-fs-results.txt` reports (`HIGH,CRITICAL`, `exit-code: 0`) instead of failing the build.
 * **Phase 3 (IaC Validation):** The `iac-validation` matrix workflow scaffolds all 10 supported frameworks headlessly (`--headless --preconfigured`), then runs `terraform init -backend=false` + `terraform validate`, `tflint`, the advisory filesystem scan, a stripped-Dockerfile `docker build`, and an advisory container-image scan (`trivy-image-results.txt`).
 * **Phase 4 (Release gate):** `.github/workflows/publish.yml` reuses `iac-validation.yml` via `workflow_call` as a `validate` job; `build-and-publish` has `needs: [validate]`, so NPM publishing on release is blocked until the full matrix passes.
+
+## 5. End-to-end lifecycle testing
+Black-box suites under `tests/e2e/` execute the real `bin/cli.js` via `child_process` with stdin closed (a prompt crashes loudly instead of hanging) and `DO_NOT_TRACK=1`. They are excluded from the default `npm test` run and have dedicated configs:
+* **Tier 0 (`npm run test:e2e:tier0`, every PR):** mock-AWS scaffold checks (`init` for ECS and Lambda targets, the full 7-capability `add` matrix plus an `init --with` composition, `terraform validate`), local checks (`doctor`, `eject`), and failure-path contracts (clean exit-1 shapes, no stack traces). Runs in `.github/workflows/e2e.yml` alongside Tier 1.
+* **Tier 1 (`npm run test:e2e:tier1`, nightly/manual only):** the full live lifecycle (`init` → `apply --auto-approve` → `status` with a retry-until-healthy loop → `destroy --yes`) against real AWS via OIDC, skipping gracefully without credentials.

package/bin/cli.js

@@ -29,8 +29,8 @@ const HELP_TEXT = [
     '',
     'Commands:',
     '  init                 Provision infrastructure and CI/CD pipelines',
-    '  apply                Apply infrastructure changes',
-    '  destroy              Tear down infrastructure',
+    '  apply                Apply infrastructure changes (--auto-approve)',
+    '  destroy              Tear down infrastructure (--yes)',
     '  doctor               Run pre-flight dependency checks',
     '  logs [service]       Stream CloudWatch logs (--tail, -f/--follow, --error, --since, --region)',
     '  status               Service health dashboard (--region, --json)',
@@ -52,7 +52,7 @@ const HELP_TEXT = [
     '  secrets push         Push environment secrets',
     '  secrets pull         Pull environment secrets',
     '  secrets audit        Audit local vs remote secrets drift',
-    '  eject                Eject to self-managed configs',
+    '  eject                Eject to self-managed configs (--yes)',
     '  sync-ai              Sync AI assistant rules',
     '',
     'Init options:',
@@ -67,7 +67,7 @@ if (parsed.hasNoTelemetry) {
 }
 process.env.CLI_COMMAND = parsed.baseCommand;
 
-const { positionalArgs, isHeadless, isDryRun, isPreconfigured, headlessOptions, initOptions } = parsed;
+const { positionalArgs, isHeadless, isDryRun, isPreconfigured, autoApprove, yes: confirmYes, headlessOptions, initOptions } = parsed;
 
 function parseRegionFlag(args) {
     for (let i = 0; i < args.length; i++) {
@@ -100,13 +100,13 @@ if (positionalArgs[0] === 'secrets' && positionalArgs[1] === 'push') {
     const projectName = path.basename(process.cwd());
     runCommand(auditSecrets(envFile, projectName, { region: parseRegionFlag(rawArgs) }));
 } else if (positionalArgs[0] === 'apply') {
-    runCommand(applyStack({ isDryRun }));
+    runCommand(applyStack({ isDryRun, ...(autoApprove ? { autoApprove: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
 } else if (positionalArgs[0] === 'doctor') {
     runCommand(runDoctor());
 } else if (positionalArgs[0] === 'destroy') {
-    runCommand(destroyStack());
+    runCommand(destroyStack({ ...(confirmYes ? { yes: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
 } else if (positionalArgs[0] === 'eject') {
-    runCommand(ejectStack());
+    runCommand(ejectStack({ ...(confirmYes ? { yes: true } : {}), ...(isHeadless ? { isHeadless: true } : {}) }));
 } else if (positionalArgs[0] === 'sync-ai') {
     runCommand(syncAi());
 } else if (positionalArgs[0] === 'diagnose' || positionalArgs[0] === 'wtf') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grada-run",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Provision production-ready AWS infrastructure and CI/CD pipelines in seconds.",
   "engines": {
     "node": ">=18.0.0"
@@ -19,6 +19,8 @@
     "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"

package/specs/e2e-testing.md

@@ -0,0 +1,50 @@
+# Specification: E2E Lifecycle Testing Harness
+
+## 1. Overview
+Implement a deterministic, two-tiered End-to-End (E2E) testing harness that executes the actual `bin/cli.js` entrypoint via `child_process`.
+This spec includes a "Phase 0" to wire minimal headless bypasses into the CLI so automated lifecycle commands do not hang on interactive prompts.
+
+## 2. Boundaries & Constraints
+- **ISOLATION:** The main unit test suite must remain blazing fast. You MUST add `exclude: ['tests/e2e/**']` to the root `vitest.config.js`.
+- **NO UNIT MOCKS:** The E2E harness must execute the real binary against the real filesystem.
+- **HEADLESS PURITY:** All E2E `execFileSync` calls must use `stdio: ['ignore', 'inherit', 'inherit']` (closing stdin). If a command attempts to prompt, it must crash loudly rather than hanging the test.
+- **ENVIRONMENT:** All E2E tests must run with `DO_NOT_TRACK=1` and `TF_PLUGIN_CACHE_DIR`. Tier 0 explicitly sets `CI_MOCK_AWS=true`. Tier 1 explicitly requires real AWS credentials and does NOT set the mock flag.
+
+## 3. Phase 0: Minimal Headless Wiring (Production)
+Do not write new flag parsers; `--headless` is already parsed globally as `isHeadless` in `bin/cli.js`. Implement a shared bypass helper (e.g., using `resolveHeadless()`) to handle the `--headless`, `--auto-approve`, and `--yes` precedence seamlessly:
+- **Apply:** Bypass the `renderDryRunPreview` confirm prompt AND the `NoSuchBucket` recovery prompt if `--auto-approve` or `--headless` is true.
+- **Destroy:** Bypass both confirm prompts if `--yes` or `--headless` is true.
+- **Eject:** Bypass the confirm prompt if `--yes` or `--headless` is true.
+
+## 4. Phase 1: Tier 0 E2E (Fast, PR-Friendly, Mock AWS)
+Create `tests/e2e/tier0.e2e.test.js` and `vitest.e2e.tier0.config.js` (with a `300s` test timeout). Add `"test:e2e:tier0": "vitest run -c vitest.e2e.tier0.config.js"` to `package.json`. Ensure `CI_MOCK_AWS=true` is set.
+**Targets:**
+1. **ECS Scaffold:** In a single shared tmpdir, run `node bin/cli.js init --target ecs --headless` -> `node bin/cli.js add queue:sqs --headless`.
+   - *Assertions:* Exit 0. Verify `README.md` (the primary doc destination), `main.tf`, and addon files exist. Run `terraform init -backend=false && terraform validate`.
+1b. **Addon Matrix:** For each remaining capability (`storage:s3`, `db:dynamodb`, `db:redis`, `ai:bedrock`, `email:ses` with `--domain example.com`, `cron`): fresh tmpdir, `init --target ecs --headless`, `add <capability> --headless`, assert exit 0 and the capability `.tf` file exists, then init + validate. Plus one `init --target ecs --with queue:sqs,db:redis --headless` composition asserting both `.tf` files exist, then init + validate.
+2. **Lambda Scaffold:** `node bin/cli.js init --target lambda --headless`.
+   - *Assertions:* Exit 0. Validate Terraform.
+3. **Local Checks:** 
+   - `eject --headless`: In a *fresh* isolated tmpdir, run `init` first, then run `eject`. Behaviorally verify metadata is stripped from files.
+   - `doctor`: Assert exit 0.
+4. **Failure Paths (Contract Pinning):** 
+   - `apply --headless` outside a project directory.
+   - `init --target fake-target`.
+   - *Assertions:* Must exit 1 cleanly with expected error shape (no stack traces).
+
+## 5. Phase 2: Tier 1 E2E (Real AWS, Nightly/Manual)
+Create `tests/e2e/tier1.live.e2e.test.js` and `vitest.e2e.tier1.config.js` (with a `15+` minute timeout). Add `"test:e2e:tier1": "vitest run -c vitest.e2e.tier1.config.js"`.
+- **Skip Logic:** Use `test.skipIf(!process.env.AWS_ACCESS_KEY_ID)` so this suite gracefully skips if run locally without credentials.
+- **The Lifecycle:** Run `init --target ecs --headless` -> `apply --auto-approve` -> `status` -> `destroy --yes` in sequence.
+- **Assertions:** Exit code 0 for all steps. *Critical:* For `status`, implement a retry-until-healthy loop (e.g., check every 15s for up to 3 mins) since ECS tasks take time to boot after `apply`. Post-destroy, assert the state bucket was successfully deleted.
+
+## 6. GitHub Actions Integration
+Create `.github/workflows/e2e.yml`:
+- **Job 1 (Tier 0):** Runs on `pull_request` and `push`. Steps: checkout, setup-node (v24), `npm ci`, `hashicorp/setup-terraform`, and `npm run test:e2e:tier0`. Upload the workspace as an artifact on failure.
+- **Job 2 (Tier 1 Live):** Runs on `workflow_dispatch` and a nightly `schedule` (`cron: '0 2 * * *'`). Steps: checkout, setup-node, `npm ci`, setup-terraform. Configure AWS credentials using `aws-actions/configure-aws-credentials@v4` with `role-to-assume: ${{ vars.AWS_ROLE_ARN }}` (the role must have broad deploy permissions). Execute `npm run test:e2e:tier1`. Upload the workspace as an artifact on failure.
+
+## 7. Acceptance Criteria
+1. The standard unit test suite has the same count and status as the baseline (1,068 total; only the known loopback failure), with E2E files correctly excluded from the default run.
+2. Tier 0 runs green locally and in PRs.
+3. Tier 1 passes against real AWS (or correctly skips if `AWS_ACCESS_KEY_ID` is absent).
+4. The Phase 0 bypass flags (`--headless`, `--auto-approve`, `--yes`) function correctly when invoked from a real terminal.

package/specs/test-suite-deduplication.md

@@ -0,0 +1,42 @@
+# Specification: Test Suite Deduplication & Hygiene
+
+## 1. Overview
+The current Vitest test suite contains significant boilerplate. Mocks for terminal interactions (`@clack/prompts`), telemetry (`src/core/telemetry.js`), and basic console/tmpdir helpers are hand-rolled and duplicated across 17+ test files. 
+
+This task extracts these shared mocks into a centralized `tests/helpers/` directory to shrink the maintenance surface area.
+
+## 2. Boundaries & Constraints
+- **NO PRODUCTION CHANGES:** Do not modify any files in `src/`, `bin/`, or `templates/`. Do not modify `vitest.config.js`.
+- **OUT OF SCOPE FILES:** Do not migrate `tests/telemetry.test.js` or `tests/commands-import.test.js` (leave their bespoke mocks intact to prevent import/circular breakages).
+- **OUT OF SCOPE MOCKS:** Do NOT attempt to unify AWS SDK or `child_process` mocks in this pass. 
+- **EXPLICIT IMPORTS:** Use explicit `vi.hoisted` imports per test file. Do not use global `setupFiles` auto-mocking.
+
+## 3. Extraction Targets
+Create the `tests/helpers/` directory and extract the following:
+
+1. **`@clack/prompts` Mock:**
+   - Centralize the mock implementations for all used exports: `intro`, `outro`, `text`, `select`, `confirm`, `spinner`, `isCancel`, `cancel`, `log`, `multiselect`, `password`, `note`, and `group`.
+   - **Bare Defaults:** Shared factories must ship with bare `vi.fn()`s. Any preset return values (like `mockResolvedValue(['claude'])`) must remain as test-specific overrides in the individual test files.
+   - **`isCancel` Semantics:** Must preserve the real behavior: `(value) => typeof value === 'symbol'`, not a bare `vi.fn()`.
+   - **`log` Union:** The helper's `log` object must include all 5 sub-methods used across the suite: `{ info, warn, message, success, error }`.
+   - **Spinner Shape:** Standardize the spinner mock shape to support `.message()` calls and track created spinners.
+
+2. **Telemetry Mock:**
+   - Centralize the `vi.mock('../src/core/telemetry.js', ...)` implementations.
+   - Mock `trackEvent`, `flushTelemetry` (with `mockResolvedValue()`), `trackSuccess`, and `trackFailure`. Ensure the success/failure mocks delegate to `trackEvent` correctly so existing success-path assertions don't break.
+   - Pass through `isActiveEnvValue` using `importOriginal`.
+
+3. **Other Duplication:**
+   - Extract the recurring `process.exit`, `console.log`, and `console.error` spy trio.
+   - Extract `tmpdir` fixture generation helpers.
+
+## 4. Implementation Strategy
+- Create clean, exportable mock factories in `tests/helpers/`.
+- Iteratively migrate the applicable test files to use these new helpers via `vi.hoisted()`.
+- Replace the duplicated inline `vi.mock()` blocks with one-liners delegating to the helper.
+- **Reset Semantics:** Each file should maintain its own `vi.clearAllMocks()` or `vi.resetAllMocks()` in its `beforeEach` hook.
+
+## 5. Acceptance Criteria
+- `tests/helpers/` exists and contains the centralized mocks.
+- No test file (except the explicitly excluded ones) retains a hand-rolled `@clack/prompts` or telemetry mock block.
+- **Coverage Preservation:** ≥1,067 passing tests, with zero failures other than the known pre-existing `db.test.js` loopback port failure.

package/src/commands/apply.js

@@ -5,7 +5,7 @@ import color from 'picocolors';
 import { renderDryRunPreview, parseTerraformConfig, buildCostTelemetryProps } from '../utils/visualizer.js';
 import { detectFramework } from '../utils/detector.js';
 import { trackEvent, flushTelemetry, trackSuccess, trackFailure } from '../core/telemetry.js';
-import { failCommand } from '../utils/command.js';
+import { failCommand, shouldAutoApprove } from '../utils/command.js';
 import { normalizeOptions } from '../utils/args.js';
 import { spawnSync } from 'child_process';
 import { provisionStateBucket } from '../utils/aws.js';
@@ -58,9 +58,9 @@ export async function applyStack(input = {}) {
             ...costProps,
         });
         process.exit(0);
-    } else if (options.autoApprove) {
+    } else if (shouldAutoApprove(options)) {
         await renderDryRunPreview(detectedConfig, true);
-    } else if (!options.autoApprove) {
+    } else {
         const confirmed = await renderDryRunPreview(detectedConfig, false);
         if (!confirmed) {
             cancel('Apply aborted.');
@@ -140,7 +140,7 @@ export async function applyStack(input = {}) {
 
             trackEvent('recovery_prompted', { type: 'state_bucket_missing' });
 
-            const shouldRecreate = await confirm({
+            const shouldRecreate = shouldAutoApprove(options) ? true : await confirm({
                 message: 'Do you want to automatically recreate the state bucket and resume provisioning?',
                 initialValue: true
             });

package/src/commands/destroy.js

@@ -6,7 +6,7 @@ import { RDSClient, DescribeDBInstancesCommand, DescribeDBClustersCommand, Start
 import { teardownStateBucket, resolveClient } from '../utils/aws.js';
 import { checkDependency, pollUntil } from '../utils/system.js';
 import { trackEvent, flushTelemetry, trackSuccess } from '../core/telemetry.js';
-import { failCommand } from '../utils/command.js';
+import { failCommand, shouldAutoApprove } from '../utils/command.js';
 import { runTerraformCommand } from '../utils/terraform.js';
 import { findDbTarget, resolveDbIdentifier, resolveDbClusterIdentifier } from '../utils/rds.js';
 import { normalizeOptions } from '../utils/args.js';
@@ -35,7 +35,7 @@ export async function destroyStack(input = {}) {
         return failCommand({ message: '✖ Terraform is not installed.', useErrorStream: true });
     }
 
-    const proceed = await confirm({
+    const proceed = shouldAutoApprove(options) ? true : await confirm({
         message: color.red('⚠️  WARNING: This will permanently destroy all AWS resources associated with this project. Are you absolutely sure?'),
         initialValue: false,
     });
@@ -187,7 +187,7 @@ export async function destroyStack(input = {}) {
     let deleteS3Bucket = false;
 
     if (bucketName) {
-        deleteS3Bucket = await confirm({
+        deleteS3Bucket = shouldAutoApprove(options) ? true : await confirm({
             message: color.yellow(`AWS compute resources destroyed. Do you also want to permanently delete the S3 state bucket?\n  (Select 'No' if you plan to run 'grada apply' later to spin this back up.)`),
             initialValue: false,
         });

package/src/commands/eject.js

@@ -3,6 +3,8 @@ import path from 'path';
 import { intro, outro, confirm, spinner, cancel } from '@clack/prompts';
 import color from 'picocolors';
 import { trackEvent, flushTelemetry } from '../core/telemetry.js';
+import { shouldAutoApprove } from '../utils/command.js';
+import { normalizeOptions } from '../utils/args.js';
 
 // Matches the `# <brand> generated infrastructure...` header line in
 // either brand variant (Lambda targets append a suffix in parentheses).
@@ -47,14 +49,15 @@ function collectTerraformFiles(dir, out = []) {
     return out;
 }
 
-export async function ejectStack() {
+export async function ejectStack(input = {}) {
+    const options = normalizeOptions(input);
     intro(color.bgRed(color.white(' grada eject ⏏️  ')));
 
     console.log(color.yellow('This will permanently decouple your infrastructure from the grada CLI.'));
     console.log(color.gray('It removes all ManagedBy tags and tool-specific metadata from your local files.'));
     console.log(color.gray('Your infrastructure will remain fully operational as raw, standalone Terraform.'));
 
-    const shouldEject = await confirm({
+    const shouldEject = shouldAutoApprove(options) ? true : await confirm({
         message: 'Are you sure you want to eject? (This cannot be undone)',
         initialValue: false,
     });

package/src/core/parser.js

@@ -120,6 +120,8 @@ export function parseCliArgs(processArgs) {
         isHeadless,
         isDryRun,
         isPreconfigured,
+        autoApprove: getBoolFlag('auto-approve') === true,
+        yes: getBoolFlag('yes') === true,
         headlessOptions,
         initOptions
     };

package/src/utils/command.js

@@ -1,5 +1,18 @@
 import color from 'picocolors';
 import { trackEvent, flushTelemetry } from '../core/telemetry.js';
+import { normalizeOptions } from './args.js';
+
+// True when a destructive confirm must be skipped: explicit approval flags
+// (--auto-approve, --yes) or explicit headless mode. Deliberately checks
+// only explicit options — never CI/non-TTY inference — so a bare command
+// in automation still prompts (and fails loudly) instead of silently
+// approving destruction.
+export function shouldAutoApprove(options = {}) {
+    const opts = normalizeOptions(options);
+    return [opts.autoApprove, opts.yes, opts.isHeadless, opts.headless].some(
+        (flag) => flag === true || flag === 'true'
+    );
+}
 
 function paint(tone, fallback) {
     return typeof color[tone] === 'function' ? color[tone] : fallback;

package/tests/add.test.js

@@ -1,4 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
+import { createTmpDirTracker } from './helpers/tmpdir.js';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -46,37 +51,15 @@ const S3_ENV = [
     { name: 'S3_CDN_URL', value: 'https://${aws_cloudfront_distribution.storage_cdn.domain_name}' },
 ];
 
-vi.mock('@clack/prompts', () => ({
-    intro: vi.fn(),
-    outro: vi.fn(),
-    select: vi.fn(),
-    text: vi.fn(),
-    spinner: () => ({ start: vi.fn(), stop: vi.fn(), message: vi.fn() }),
-    log: { info: vi.fn(), warn: vi.fn(), message: vi.fn(), success: vi.fn(), error: vi.fn() },
-    cancel: vi.fn(),
-    isCancel: (value) => typeof value === 'symbol',
-}));
-
-vi.mock('../src/core/telemetry.js', async (importOriginal) => {
-    const actual = await importOriginal();
-    const trackEvent = vi.fn();
-    const flushTelemetry = vi.fn().mockResolvedValue();
-    // Mirrors the real trackSuccess delegation so success-path assertions
-    // keep observing trackEvent (the real helper is unit-tested separately).
-    const trackSuccess = vi.fn(async (event, properties) => {
-        trackEvent(event, { ...properties, success: true });
-        await flushTelemetry();
-    });
-    return { trackEvent, flushTelemetry, trackSuccess, isActiveEnvValue: actual.isActiveEnvValue };
-});
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
+
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
-let tmpDirs = [];
+const tmp = createTmpDirTracker();
 let exitSpy;
 
 function makeTmp() {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'add-test-'));
-    tmpDirs.push(dir);
-    return dir;
+    return tmp.makeTmp('add-test-');
 }
 
 function writeWorkerTf(dir, { lifecycle = false } = {}) {
@@ -145,16 +128,14 @@ function writeMainTf(dir, environment = '') {
 }
 
 beforeEach(() => {
-    tmpDirs = [];
+    tmp.reset();
     vi.clearAllMocks();
     exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {});
 });
 
 afterEach(() => {
     exitSpy.mockRestore();
-    for (const dir of tmpDirs) {
-        fs.rmSync(dir, { recursive: true, force: true });
-    }
+    tmp.cleanup();
 });
 
 describe('parseAddArgs', () => {

package/tests/ai.test.js

@@ -1,24 +1,21 @@
 import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+// NOTE: helper imports must stay above src imports: vi.mock factories run
+// during module evaluation and need the factories initialized.
+import { clackPromptsMockFactory, mockMultiselect } from './helpers/clack.js';
+import { telemetryMockFactory } from './helpers/telemetry.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { syncAi } from '../src/commands/sync-ai.js';
 import { injectManagedBlock } from '../src/utils/ai-rules.js';
 
 // 1. Mock the interactive prompts to simulate user input
-vi.mock('@clack/prompts', () => ({
-    intro: vi.fn(),
-    outro: vi.fn(),
-    // Simulate the user selecting 'claude' from the list and hitting Enter
-    multiselect: vi.fn().mockResolvedValue(['claude']),
-    spinner: () => ({ start: vi.fn(), stop: vi.fn(), message: vi.fn() }),
-    log: { success: vi.fn(), warn: vi.fn(), error: vi.fn(), message: vi.fn() }
-}));
+vi.mock('@clack/prompts', () => clackPromptsMockFactory());
+
+// Simulate the user selecting 'claude' from the list and hitting Enter
+mockMultiselect.mockResolvedValue(['claude']);
 
 // 2. Mock telemetry to prevent real network calls
-vi.mock('../src/core/telemetry.js', () => ({
-    trackEvent: vi.fn(),
-    flushTelemetry: vi.fn().mockResolvedValue(),
-}));
+vi.mock('../src/core/telemetry.js', (importOriginal) => telemetryMockFactory(importOriginal));
 
 describe('AI Context Synchronization', () => {
     const originalCwd = process.cwd();