@grada-run/grada 0.0.1 → 0.32.0

package/specs/deploy-stack-to-grada-run-rebrand.md

@@ -0,0 +1,45 @@
+# Specification: The Grada Brand Transition
+
+## 1. Overview
+Transition the `deploy-stack` codebase to the new brand identity: **Grada**. 
+Existing deployments must not break; implement robust dual-read fallbacks for state files, machine markers, and tags. Version bump to `0.32.0`.
+
+## 2. NPM, Repository & Binary Renaming
+- `package.json`: Update name to `grada-run`. Update `author` and `keywords` to include Grada terminology. 
+- `package.json`: Map the `bin` field to: `"grada": "./bin/cli.js"`, `"grada-run": "./bin/cli.js"`, and a deprecated fallback `"deploy-stack": "./bin/cli.js"`.
+- `package.json` fields (`repository`, `bugs`, `homepage`) must point to `[https://github.com/grada-run/grada](https://github.com/grada-run/grada)`.
+- Replace hardcoded `anton-codes-iac/deploy-stack` GitHub URLs across the codebase (error logs, docs) with `grada-run/grada`.
+- Rename `CLI_ENTRY_BASENAMES` in `src/core/telemetry.js` to include `grada` and `grada-run`.
+- Update CLI banner texts, `.muserules` title, AI rules filenames (write new ones, do not delete user legacy ones), and help texts to use `Grada` / `npx grada-run`.
+
+## 3. Dual-Read Local State & Env Vars
+Read from `.grada/` first, fall back to `.deploy-stack/`. Write new state to `.grada/`.
+- **Telemetry:** Check `~/.grada/telemetry-id` (raw text file) -> fallback to `~/.deploy-stack/telemetry-id`. Copy to new path on fallback.
+- **Sleep Ledger:** Check `.grada/sleep-state.json` -> fallback to `.deploy-stack/sleep-state.json`. In `ensureSleepGitignore`, append `.grada/` but leave `.deploy-stack/`.
+- **Bedrock Cache:** Check `~/.grada/bedrock-models-cache.json` -> fallback `~/.deploy-stack/bedrock-models-cache.json`.
+- **Env Vars:** Rename `DEPLOY_STACK_TELEMETRY_ID_PATH` -> `GRADA_TELEMETRY_ID_PATH`, `DEPLOY_STACK_FRAMEWORK` -> `GRADA_FRAMEWORK`, and `DEPLOY_STACK_BEDROCK_CACHE_PATH` -> `GRADA_BEDROCK_CACHE_PATH` (all with legacy read fallbacks). Leave `DO_NOT_TRACK` as the sole telemetry opt-out. Rename `DEPLOY_STACK_BYPASS` in the Svelte template to `GRADA_BYPASS`.
+
+## 4. Machine Markers (Dual-Read)
+The CLI must parse both `deploy-stack` and `grada` variants for existing files, but write `grada` for new ones.
+- Domain mode: `# deploy-stack:domain-mode=` / `# grada:domain-mode=` AND `# deploy-stack:zone-id=` / `# grada:zone-id=`
+- Migrate gate: `# deploy-stack:db-migrate-start` / `# grada:db-migrate-start` AND `# deploy-stack:db-migrate-end` / `# grada:db-migrate-end`
+- AI Context: Dual read both HTML (`<!-- BEGIN GRADA CONTEXT -->` / `<!-- END GRADA CONTEXT -->`) and hash (`# BEGIN GRADA CONTEXT` / `# END GRADA CONTEXT`) block variants.
+
+## 5. Templates, Tagging & Eject
+- Rename *all* cosmetic occurrences of the brand in templates (e.g., `npx deploy-stack` -> `npx grada-run`, `Generated by deploy-stack`, `# deploy-stack generated infrastructure`, `# deploy-stack addon:`, `deploy-stack-cron`, and git commit messages).
+- Update `ManagedBy = "grada"` for new writes in templates, S3 state buckets, RDS snapshots, and providers. Rename `startedBy` to `grada-db-*`.
+- In `src/commands/eject.js`, ensure the cleanup regex strips *both variants* of all four block types: `ManagedBy` tag blocks, cosmetic addon headers, `# deploy-stack backups` gitignore comments, and `# deploy-stack generated infrastructure` main.tf headers.
+
+## 6. Documentation & Generators
+- **Docs Site (`apps/docs/`):** Update `astro.config.mjs` (`site: '[https://grada.run](https://grada.run)'`, remove the `base` property entirely, update `title`, `editLink`, `social` hrefs, redirects, and sidebar labels). Execute Astro build to regenerate `apps/docs/dist/`. Update internal `/deploy-stack/` links across `README.md`, `release_notes.md`, and all `apps/docs/src/` pages.
+- **Generator Fallback Doc:** Rename fallback constant to `GRADA.md`. `resolveDocDest` precedence chain: `README.md` -> `DEPLOYMENT.md` -> `GRADA.md` -> legacy `DEPLOY-STACK.md` (returning the first missing-or-managed). 
+- **Cost Sync:** `syncDocCostEstimate` must scan `GRADA.md` and legacy `DEPLOY-STACK.md` in addition to `README.md` and `DEPLOYMENT.md`.
+
+## 7. GitHub Actions & CI
+- Update `uses:` step from `anton-codes-iac/deploy-stack-action@v1` to `grada-run/grada-action@v1`.
+- Update `scripts/test-iac.js` and `iac-validation.yml` to assert the new `grada` migrate markers.
+- Validate that `.github/workflows/publish.yml` publishes `grada-run` and the scoped alias `@grada-run/grada`.
+
+## 8. Testing
+- Use `npm run test:update` to carefully update the 131 legacy snapshot matches across the 12 test files.
+- Add unit tests asserting the dual-read marker logic, telemetry fallback, sleep ledger fallback, and `eject` multi-brand cleanup.

package/specs/deployment-safety.md

@@ -0,0 +1,170 @@
+# Deployment Safety & One-Command Rollback
+
+This sprint delivers zero-downtime deployment safety nets across both infrastructure definition and Day-2 operations:
+1. Native ECS Deployment Circuit Breakers in Terraform (`templates/terraform/main.tf`).
+2. The `deploy-stack rollback [revision]` CLI command with interactive revision inspection.
+
+---
+
+## Part 1: Terraform Deployment Circuit Breakers
+
+### 1. Template Update (`templates/terraform/main.tf`)
+In `templates/terraform/main.tf` (around lines 204–225), locate the existing `resource "aws_ecs_service" "app"` block. **Do NOT replace or alter existing attributes** (`${local.app_name}`, `{{DESIRED_COUNT}}`, `{{PORT}}`, `enable_execute_command = true`, or `depends_on = [aws_lb_listener.http]`). Insert **only** the `deployment_circuit_breaker` block inside the existing resource:
+
+```hcl
+  deployment_circuit_breaker {
+    enable   = true
+    rollback = true
+  }
+```
+
+### 2. Generator Tests & Snapshot Update (`tests/generator.test.js`)
+* In `tests/generator.test.js`, add an explicit assertion verifying that the generated `main.tf` content includes `deployment_circuit_breaker` with `enable = true` and `rollback = true`.
+* Update existing snapshots in `tests/generator.test.js` by running `npx vitest run -u` and verify that the snapshot diff contains only the added `deployment_circuit_breaker` block.
+
+---
+
+## Part 2: `deploy-stack rollback` CLI Command
+
+### 1. CLI Routing & Argument Parsing (`bin/cli.js` & `src/commands/rollback.js`)
+* In `bin/cli.js`:
+  * Add `rollback` to the flat `Commands:` list in `HELP_TEXT`, immediately after the `status` line:
+    ```
+      rollback [rev]       Roll back ECS service to a previous task revision
+    ```
+  * Route `rollback` to `runRollback({ ...parseRollbackArgs(rawArgs), ...(isHeadless ? { isHeadless: true } : {}) })` exported from `src/commands/rollback.js`. **Important:** Only pass `isHeadless: true` when `--headless` was explicitly passed on the CLI; leave `options.isHeadless` as `undefined` otherwise so normal runs fall through to `process.env.CI || !process.stdin.isTTY` auto-detection while allowing tests to pass `isHeadless: false` explicitly.
+* In `src/commands/rollback.js`:
+  * Implement and export `parseRollbackArgs(argv = [])`:
+    * Strip a leading `'rollback'` token if present.
+    * First non-flag positional argument: `revision` (optional string: can be numeric like `'12'`, `family:revision` like `'my-app-task:12'`, or a full task definition ARN).
+    * Flags (supporting both `--flag value` and `--flag=value` forms):
+      * `--cluster` (string)
+      * `--service` (string)
+      * `--region` (string)
+      * `--workspace` (string)
+      * `--skip-wait` (boolean, default `false`)
+
+### 2. Resolvers, Workspace Handling & Preconditions
+* **SDK-Only Command:** Do **not** gate on `hasAwsCli` (unlike `exec` or `db connect`, `rollback` uses `@aws-sdk/client-ecs` directly, matching `status`, `logs`, and `gc`).
+* **Imports:**
+  * Import `ECSClient`, `DescribeServicesCommand`, `ListTaskDefinitionsCommand`, `DescribeTaskDefinitionCommand`, and `UpdateServiceCommand` from `@aws-sdk/client-ecs` (do not import `DescribeTasksCommand`).
+  * Import `resolveRegion`, `resolveProjectName`, `resolveCluster`, and `resolveService` from `../utils/resolvers.js`.
+  * Import `handleAwsAuthError` from `../utils/aws.js`.
+* **Workspace Resolution:**
+  * Support `--workspace` (or local `.terraform/environment` detection) using the exact `resolveWorkspaceSuffix` pattern from `src/commands/db.js`: if a non-`default` workspace is active, namespace `projectName` as `${baseProjectName}-${workspace}` before passing `projectName` into `resolveCluster` and `resolveService` (unless `--cluster` or `--service` was explicitly passed).
+* **Injectable Dependencies & Testable Headless Override:**
+  * Accept `options.ecsClient` (defaulting to `new ECSClient({ region })`).
+  * Accept `options.pollIntervalMs` (default `5000`) and `options.timeoutMs` (default `300000`).
+  * **Testable Headless Resolution:** Because `bin/cli.js` only passes `isHeadless: true` when `--headless` is set, `options.isHeadless` is `undefined` in normal runs (preserving `process.env.CI || !process.stdin.isTTY` auto-detection) while allowing unit tests in Vitest to pass `isHeadless: false` explicitly:
+    ```javascript
+    const headless = typeof options.isHeadless === 'boolean'
+        ? options.isHeadless
+        : Boolean(process.env.CI || !process.stdin.isTTY);
+    ```
+* **Spinner Lifecycle & Centralized Auth Error Handling:**
+  * Call `intro(color.bgCyan(color.black(' deploy-stack rollback ⏪ ')))` at the start of `runRollback`.
+  * Immediately instantiate `const s = spinner();` and call `s.start('Inspecting service and task revisions...');` before entering the `try` block so `s` is always initialized and safe to pass into `handleAwsAuthError`.
+  * In the outer `catch (error)` block, check for `UnrecognizedClientException` or `ExpiredTokenException`.
+  * **Critical Ordering:** Emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'AUTH_EXPIRED' })` and `await flushTelemetry()` *before* invoking `handleAwsAuthError(error, s, options)`, followed immediately by `return;`.
+
+### 3. Task Definition Discovery & Selection
+1. **Fetch Current Service State:**
+   * Call `DescribeServicesCommand({ cluster, services: [service] })`.
+   * If `services` is empty or `services[0].status !== 'ACTIVE'`, stop spinner (`s.stop(...)`), print an error that the service was not found or is inactive, emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'SERVICE_NOT_FOUND' })`, `await flushTelemetry()`, call `process.exit(1)`, and `return;`.
+   * Extract the active `currentTaskDefArn = services[0].taskDefinition` (e.g., `arn:aws:ecs:us-east-2:123456789012:task-definition/my-app-task:14`).
+   * **Extract Family Name & Revision Number:** Parse the substring between the last `/` and the last `:`:
+     ```javascript
+     const familyAndRev = currentTaskDefArn.split('/').pop();
+     const [family, currentRevStr] = familyAndRev.split(':');
+     const currentRevNum = Number(currentRevStr);
+     ```
+
+2. **Resolve Target Revision (Stopping Discovery Spinner in All Paths):**
+   * **Case A: Explicit `options.revision` provided via CLI (`rollback [rev]`):**
+     * Normalize the identifier:
+       * If `options.revision` is purely numeric (`/^\d+$/`), construct `targetInput = `${family}:${options.revision}``.
+       * Otherwise (it is already `family:rev` or a full ARN), use `targetInput = options.revision`.
+     * Validate by calling `DescribeTaskDefinitionCommand({ taskDefinition: targetInput })` directly (do **not** limit validation to the last 10 revisions from `ListTaskDefinitions`).
+     * If `DescribeTaskDefinitionCommand` throws or returns an inactive definition: stop spinner (`s.stop(...)`), print a clear error message, emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'REVISION_NOT_FOUND' })`, `await flushTelemetry()`, call `process.exit(1)`, and `return;`.
+     * Set `targetTaskDefArn = descResp.taskDefinition.taskDefinitionArn` and `targetRevisionNum = String(descResp.taskDefinition.revision)`.
+     * Stop the discovery spinner (`s.stop(\`Resolved revision \${targetRevisionNum}.\`)`) so `s` is stopped before Section 4.
+
+   * **Case B: No `options.revision` provided:**
+     * Call `ListTaskDefinitionsCommand({ familyPrefix: family, status: 'ACTIVE', sort: 'DESC', maxResults: 10 })`.
+     * **Strict Older-Revision Filtering:** Filter `taskDefinitionArns` so `eligibleArns` contains only revisions whose parsed revision number (`Number(arn.split(':').pop())`) is **strictly less than `currentRevNum`**. This prevents accidentally rolling *forward* if a newer task definition revision was registered in ECS but not deployed to the service.
+     * If `eligibleArns.length === 0`:
+       * Stop spinner (`s.stop(...)`), print `⚠ No previous task definition revisions found for family ${family}. Cannot roll back.`
+       * Emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'NO_PRIOR_REVISIONS' })`, `await flushTelemetry()`, call `process.exit(1)`, and `return;`.
+     * **If `headless` is true:**
+       * Select `targetTaskDefArn = eligibleArns[0]` (the newest revision older than `currentRevNum`) and extract `targetRevisionNum = targetTaskDefArn.split(':').pop()`.
+       * Stop the discovery spinner (`s.stop(\`Selected previous revision \${targetRevisionNum}.\`)`) so `s` is stopped before Section 4.
+     * **If `headless` is false (interactive TTY):**
+       * Take up to the first 5 ARNs from `eligibleArns` (`eligibleArns.slice(0, 5)`).
+       * Call `DescribeTaskDefinitionCommand` in parallel using `Promise.allSettled` for those 5 ARNs so a single failed describe call does not abort discovery:
+         * On `fulfilled`: extract `revision`, shortened image name/tag (`const rawImage = taskDefinition.containerDefinitions?.[0]?.image || 'unknown'; const shortImage = rawImage.split('/').pop();`), and `registeredAt` timestamp (formatted cleanly, e.g., ISO date string).
+         * On `rejected`: fallback to `revision = arn.split(':').pop()`, `shortImage = 'unknown'`, `registeredAtStr = ''`.
+       * Stop the discovery spinner (`s.stop('Found previous revisions.')`) before prompting.
+       * Prompt using `@clack/prompts` `select()`:
+         * `message: 'Select a task definition revision to roll back to:'`
+         * `options`: `{ value: arn, label: \`Revision \${rev} — \${shortImage}\`, hint: registeredAtStr }`
+       * If `isCancel(selectedArn)`:
+         * Print `outro(color.yellow('Rollback cancelled.'))` and `return { ok: false, reason: 'cancelled' }` cleanly (exit code 0, no error telemetry).
+       * Set `targetTaskDefArn = selectedArn` and `targetRevisionNum = targetTaskDefArn.split(':').pop()`.
+
+### 4. Service Update & Deployment Monitoring
+1. **Trigger Rollback:**
+   * Because Section 3 stops the discovery spinner on every path, cleanly start the rollback spinner before calling `UpdateServiceCommand`:
+     `s.start(\`Rolling back \${service} to revision \${targetRevisionNum}...\`);`
+   * Call `UpdateServiceCommand({ cluster, service, taskDefinition: targetTaskDefArn, forceNewDeployment: true })`.
+2. **If `options.skipWait` is true:**
+   * Stop spinner (`s.stop(\`Rollback to revision \${targetRevisionNum} triggered.\`)`).
+   * Emit `trackEvent('rollback_run', { projectName, success: true, targetRevision: String(targetRevisionNum), skipWait: true })` and `await flushTelemetry()`.
+   * Print `outro(color.green(\`Rollback to revision \${targetRevisionNum} initiated! 🚀\`))` and `return { ok: true, targetTaskDefArn, targetRevision: targetRevisionNum }`.
+3. **If `options.skipWait` is false (default):**
+   * Keep the spinner from Step 1 running and poll `DescribeServicesCommand({ cluster, services: [service] })` every `pollIntervalMs` until `timeoutMs` elapses:
+     * Locate the primary deployment: `const primary = svc.deployments?.find(d => d.status === 'PRIMARY' && d.taskDefinition === targetTaskDefArn);`
+     * **Success predicate:** If `primary` exists and (`primary.rolloutState === 'COMPLETED'` || (`primary.runningCount === primary.desiredCount && primary.desiredCount > 0 && svc.deployments.length === 1`)):
+       * Stop spinner with `color.green(\`Rolled back to revision \${targetRevisionNum}.\`)`.
+       * Emit `trackEvent('rollback_run', { projectName, success: true, targetRevision: String(targetRevisionNum) })` and `await flushTelemetry()`.
+       * Print `outro(color.green(\`Service successfully rolled back to revision \${targetRevisionNum}! 🚀\`))` and `return { ok: true, targetTaskDefArn, targetRevision: targetRevisionNum }`.
+     * **Failure predicate:** If `primary?.rolloutState === 'FAILED'`:
+       * Stop spinner with `color.red('❌ Rollback deployment failed.')`.
+       * Print diagnostic guidance (`npx deploy-stack status` and `npx deploy-stack logs`).
+       * Emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'ROLLOUT_FAILED', targetRevision: String(targetRevisionNum) })` and `await flushTelemetry()`.
+       * Call `process.exit(1)` and `return;`.
+   * **Timeout handling:** If the loop exceeds `timeoutMs`:
+     * Stop spinner with `color.yellow('⚠ Rollback timed out waiting for ECS stabilization.')`.
+     * Print guidance to check progress with `npx deploy-stack status`.
+     * Emit `trackEvent('rollback_run', { projectName, success: false, error_code: 'ROLLOUT_TIMEOUT', targetRevision: String(targetRevisionNum) })` and `await flushTelemetry()`.
+     * Call `process.exit(1)` and `return;`.
+
+---
+
+## Part 3: Test Suite (`tests/rollback.test.js`)
+
+Create `tests/rollback.test.js` using Vitest:
+* Inject a mocked `ecsClient` and `{ pollIntervalMs: 1, timeoutMs: 50 }` into `runRollback` so tests execute instantaneously.
+* **Test Cases:**
+  1. `parseRollbackArgs` parses positional `[rev]`, `--cluster`, `--service`, `--region`, `--workspace`, and `--skip-wait`.
+  2. Explicit numeric revision (`rollback 12`) calls `DescribeTaskDefinitionCommand` with `${family}:12`, updates service, waits for `COMPLETED`, and tracks `rollback_run` with `{ success: true, targetRevision: '12' }`.
+  3. `--skip-wait` path triggers `UpdateServiceCommand`, skips polling, emits `rollback_run` with `{ success: true, targetRevision: '12', skipWait: true }`, and returns `{ ok: true, targetTaskDefArn, targetRevision: '12' }`.
+  4. Headless mode (`isHeadless: true` or `process.env.CI = 'true'` when `isHeadless` is omitted) with no positional revision filters out revisions greater than or equal to `currentRevNum` (e.g., ignores `rev 15` when service is on `rev 14` and selects `rev 13`).
+  5. Interactive mode (`isHeadless: false`) calls `DescribeTaskDefinitionCommand` via `Promise.allSettled`, displays shortened image tags (`rawImage.split('/').pop()`), prompts via `@clack/prompts` `select`, and updates service with the chosen ARN (plus handles `isCancel` cleanly without exiting 1).
+  6. Graceful exit (`process.exit(1)`) and telemetry `error_code` tracking for:
+     * Missing/inactive service (`SERVICE_NOT_FOUND`)
+     * Single revision with no older rollback targets (`NO_PRIOR_REVISIONS`)
+     * Non-existent explicit revision (`REVISION_NOT_FOUND`)
+     * Failed rollout state (`ROLLOUT_FAILED`)
+     * Poll timeout (`ROLLOUT_TIMEOUT`)
+     * Auth expiration (`AUTH_EXPIRED`) before calling `handleAwsAuthError`.
+
+---
+
+## Part 4: Documentation & Sidebar Registration
+
+1. **CLI Reference Page (`apps/docs/src/content/docs/cli/rollback.md`):**
+   * Use the standard Starlight frontmatter (`title`, `description`).
+   * Cover automatic ECS deployment circuit breakers vs. manual `npx deploy-stack rollback [revision]`.
+   * Document flags: `--cluster`, `--service`, `--region`, `--workspace`, and `--skip-wait`.
+2. **Sidebar Registration (`apps/docs/astro.config.mjs`):**
+   * In `apps/docs/astro.config.mjs`, add `{ label: 'rollback', slug: 'cli/rollback' }` to the `CLI Reference` sidebar items immediately after `{ label: 'status', slug: 'cli/status' }`.

package/specs/diagnose.md

@@ -0,0 +1,16 @@
+# Spec: `deploy-stack diagnose` (alias: `wtf`)
+
+## Objective
+Build a new CLI command that automatically queries AWS to troubleshoot why a deployed application is failing (e.g., container crash loops, ALB 502 Bad Gateway).
+
+## Requirements
+1. **Command Registration:** Register `diagnose` and its alias `wtf` in `bin/cli.js` using Commander.
+2. **AWS SDK Integration:** Use `@aws-sdk/client-ecs` and `@aws-sdk/client-cloudwatch-logs` to:
+   - Find the most recent stopped tasks in the ECS Fargate cluster.
+   - Extract the `stoppedReason` (e.g., OutOfMemory, Essential container in task exited).
+   - Fetch the last 50 lines of logs from CloudWatch for the failing container.
+3. **Output:** Format the output beautifully using `picocolors`. Highlight the exact error clearly so the user doesn't have to dig through JSON.
+
+## Constraints
+- Mock the AWS SDK calls in the tests so they don't require real AWS credentials to pass.
+- Do not modify the existing `apply` or `destroy` commands.

package/specs/docs-hub.md

@@ -0,0 +1,16 @@
+# Spec: Starlight Documentation Hub
+
+## Objective
+Initialize an Astro Starlight documentation site inside the monorepo to serve as the official, version-controlled developer portal for `deploy-stack`.
+
+## Requirements
+1. **Scaffolding:** Initialize a new Astro Starlight project inside the `apps/docs/` directory.
+2. **Information Architecture:** Configure `astro.config.mjs` to render a sidebar with three main sections:
+   - **Core Concepts:** (Link to ADRs and architectural decisions).
+   - **Guides:** (Link to deployment guides and PaaS migrations).
+   - **CLI Reference:** (Command reference for init, apply, diagnose).
+3. **Migration:** Move all existing Markdown files from the root `docs/adrs/` folder into `apps/docs/src/content/docs/adrs/` so they are immediately searchable.
+
+## Constraints
+- Use the standard Astro Starlight dependency tree. 
+- Ensure a script (e.g., `"docs:dev": "npm run dev --workspace=apps/docs"`) is added to the root `package.json` to allow starting the docs from the top level.

package/specs/dx-polish.md

@@ -0,0 +1,46 @@
+We need to resolve three UX issues identified via telemetry.
+
+## 1. Telemetry Noise Reduction (`src/core/telemetry.js`)
+Because this is a hand-rolled fetch implementation, we are receiving rogue/junk events ('message', 'data', 'true') likely from stray event bindings or bot traffic. 
+* Add a strict guard at the very top of `trackEvent(eventName, properties)`.
+* **The Guard:** 
+  * Check if `typeof eventName !== 'string'`.
+  * Check if `eventName` includes any of these valid substrings: `['_run', '_pushed', '_pull', '_audit', '_streamed', '_executed', '_provisioned', '_ejected', '_applied', '_destroyed', 'recovery_', 'cli-error']`. Implement this using `.some(validStr => eventName.includes(validStr))`.
+  * If invalid or not a string, immediately `return;` (before the `DO_NOT_TRACK` check and without pushing anything to `pendingRequests`).
+
+## 2. Centralized AWS Auth Guidance (`src/utils/aws.js`)
+We currently have `isAuthError` / `ExpiredTokenException` catch blocks scattered across 7 call sites in 5 files (`secrets.js`, `diagnose.js`, `exec.js`, `status.js`, `logs.js`).
+* **Relocation:** Move `hasAwsCli(options = {})` AND the `AWS_CLI_INSTALL_URL` constant from `src/commands/exec.js` into `src/utils/aws.js` and export them. Ensure `utils/aws.js` imports `child_process` and `picocolors`.
+* **Test/Source Fix:** Update `src/commands/exec.js` and `tests/exec.test.js` to import `hasAwsCli` and `AWS_CLI_INSTALL_URL` from `../utils/aws.js` (or `../src/utils/aws.js` for tests).
+* **New Helper:** Create and export `handleAwsAuthError(error, clackSpinner = null, options = {})` in `src/utils/aws.js`.
+  * The caller is responsible for checking if the error is an auth error before calling this helper.
+  * **CRITICAL ORDERING:** The caller MUST emit `trackEvent` and `await flushTelemetry()` *before* invoking this helper, because this helper terminates the process.
+  * Inside the helper:
+    * If `clackSpinner` is provided, call `clackSpinner.stop(color.red('❌ AWS session expired or invalid credentials.'))`.
+    * If `hasAwsCli(options)` is false, print instructions to install the AWS CLI using `AWS_CLI_INSTALL_URL`.
+    * If `hasAwsCli(options)` is true, print: `Run aws sso login or aws configure to refresh your credentials.`
+    * In both cases, print the troubleshooting link: `https://github.com/anton-codes-iac/deploy-stack/blob/main/apps/docs/src/content/docs/guides/aws-credentials.md`
+    * Call `process.exit(1)` at the end of the helper, followed by `return;` to prevent test fall-through.
+* **Refactor Call Sites:** Update all 7 call sites to invoke this helper (passing their local `opts` or `options` object so the `spawnSyncImpl` seam works). 
+  * Remove their inline `process.exit(1)` calls. 
+  * Add an explicit `return;` immediately after invoking the helper in the caller to ensure tests do not fall through.
+  * Remove redundant `spinner.stop()` calls *only* within the auth error branches (e.g., in `diagnose.js` and `status.js`). Ensure non-auth error paths keep their `spinner.stop()` calls so they don't hang the terminal.
+
+## 3. Graceful Secrets Onboarding (`src/commands/secrets.js` & `bin/cli.js`)
+When running `secrets push`, if the `.env` file is missing, it currently throws a hard error.
+* **Plumbing:** In `bin/cli.js`, pass `{ isHeadless }` to `pushSecrets` exactly like `pullSecrets` does. Update `@clack/prompts` import in `secrets.js` to include `isCancel`. Ensure `opts` is used instead of `options`, as `pushSecrets` normalizes arguments into `opts`.
+* **UX Flow (in `pushSecrets` inner try/catch):** When `fsError.code === 'ENOENT'` is caught:
+  * Stop the spinner: `s.stop('No .env file found.');`
+  * **If `opts.isHeadless` OR `process.env.CI` is truthy:**
+    * Print exactly: `No .env file found. In automated environments, please ensure the file is generated before running secrets push.`
+    * Track event: `trackEvent('secrets_pushed', { success: false, reason: 'missing_env_headless' })` and `await flushTelemetry();`.
+    * Call `process.exit(1)` followed immediately by `return;`.
+  * **If interactive:** 
+    * Use `@clack/prompts` `confirm` to ask: `Would you like to create an empty ${resolvedFilePath} file now to get started?`
+    * Handle `isCancel(confirmed)` by printing a cancellation message and `return;`.
+    * If true: Ensure parent directories exist using `await fs.mkdir(path.dirname(envPath), { recursive: true })` (using `fs/promises`). Write `# Add your environment variables here\n` to the absolute `envPath`. Print a success message to add variables and re-run. Track `secrets_pushed` event with `{ success: false, reason: 'created_empty_file' }`, `await flushTelemetry();`, then `return;`.
+    * If false: Print a cancellation message and `return;`.
+  * Ensure this inner catch block completely handles the flow and returns, so the error does not bubble up to the outer catch block.
+* **Testing (`tests/secrets.test.js`):** 
+  * GitHub Actions automatically sets `CI=true`. To prevent interactive tests from silently failing by taking the headless route, interactive test cases MUST save the original `process.env.CI`, run `delete process.env.CI`, and restore it after the test.
+  * Headless test cases should verify both the `opts.isHeadless` flag and the `process.env.CI` fallback.

package/specs/exec.md

@@ -0,0 +1,25 @@
+# Spec: 1-Click Container Access (exec)
+
+## Objective
+Implement `npx deploy-stack exec` to automatically drop the user into a secure, interactive shell inside their running AWS Fargate container using ECS Exec. 
+
+## 1. Infrastructure Updates (Terraform)
+To allow ECS Exec, the Fargate tasks need SSM permissions and the service needs a specific flag enabled.
+- **Update `templates/terraform/main.tf` (and any other relevant tf files):**
+  - Add `enable_execute_command = true` to the `aws_ecs_service` resource.
+  - Ensure the `aws_iam_role.ecs_task_role` (the role the container runs as, NOT the execution role) has the following permissions:
+    - `ssmmessages:CreateControlChannel`
+    - `ssmmessages:CreateDataChannel`
+    - `ssmmessages:OpenControlChannel`
+    - `ssmmessages:OpenDataChannel`
+
+## 2. CLI Implementation (`src/commands/exec.js`)
+- **Auto-Discovery:** Use `@aws-sdk/client-ecs` to dynamically find the active Cluster, Service, and a running Task ARN based on the current project directory.
+- **Interactive Shell:** Use Node's `child_process.spawn` with `stdio: 'inherit'` to execute the AWS CLI command: 
+  `aws ecs execute-command --cluster <cluster> --task <task_arn> --container <container_name> --interactive --command "/bin/sh"`
+- **Prerequisite Checks:** Before spawning, quickly verify the user has the `aws` CLI installed (since ECS Exec relies on the AWS CLI and the Session Manager plugin under the hood). If missing, print a friendly error with a link to install it.
+- **Error Handling:** If no tasks are running (e.g., scale is 0 or crashing), exit gracefully using `picocolors` and `@clack/prompts` explaining that a running container is required.
+
+## 3. Testing & Wiring
+- Add `exec` to `bin/cli.js`.
+- Create `tests/exec.test.js` using `vitest` to mock the ECS client and the `spawn` call, ensuring the correct AWS CLI arguments are constructed and prerequisite failures are handled smoothly.

package/specs/finops-cron-drift.md

@@ -0,0 +1,161 @@
+# Spec: FinOps Hibernation (`sleep` / `wake`), Scheduled Cron Jobs, and IaC Drift Detection
+
+## Overview
+Deliver three Day-2 operational and FinOps capabilities in Phase 10 to complete the ECS Fargate + RDS operational lifecycle:
+1. **Environment Hibernation & FinOps (`deploy-stack sleep [env]` & `deploy-stack wake [env]`):** Pause non-production or idle environments with a single command by scaling ECS services (`app` and `worker`) to `0` and stopping RDS instances or Aurora Serverless v2 clusters, displaying exact hourly/monthly cost savings and guarding against AWS's 7-day RDS auto-restart behavior.
+2. **Scheduled Cron Jobs (`deploy-stack add cron`):** Provision Amazon EventBridge Scheduler rules (`aws_scheduler_schedule`) that invoke ephemeral ECS Fargate tasks inside the private VPC on a `cron(...)` or `rate(...)` schedule with a `$0.00/mo` fixed baseline.
+3. **Scheduled IaC Drift Detection (`deploy-stack init --setup-ci-drift` / `.github/workflows/drift.yml`):** Scaffold an automated GitHub Actions workflow that periodically runs `terraform plan -detailed-exitcode` against live AWS state and automatically opens/updates a GitHub Issue (and dispatches an optional Slack webhook) when out-of-band AWS Console changes are detected.
+
+---
+
+## Part 1: Environment Hibernation & FinOps (`deploy-stack sleep` & `deploy-stack wake`)
+
+### 1. CLI Surface & Routing
+* Register two new top-level commands in `bin/cli.js` and `src/core/parser.js`:
+  * `deploy-stack sleep [env]` → `src/commands/sleep.js` (`runSleep`)
+  * `deploy-stack wake [env]` → `src/commands/wake.js` (`runWake`)
+* Supported flags for both commands:
+  * Positional `[env]` or `--workspace <name>`: Optional workspace/environment name (e.g. `staging`, `dev`, `pr-42`). If provided, resolves resource names with the workspace suffix (`${projectName}-${env}`) matching Terraform's `local.app_name` convention (`terraform.workspace == "default" ? var.project_name : "${var.project_name}-${terraform.workspace}"`).
+  * `--project-name <name>`, `--cluster <name>`, `--service <name>`, `--db-identifier <id>`, `--region <region>`.
+  * `--skip-db`: Scale ECS services only and leave the database running.
+  * `--wait` / `--no-wait`: On `wake`, wait for RDS/Aurora to become `available` and ECS tasks to reach `runningCount >= desiredCount` (default: wait with `pollUntil`, skippable with `--no-wait`).
+  * `--yes` / `--force` / `--headless`: Skip interactive confirmation on `sleep` when targeting the default (`production`/`default`) environment.
+
+### 2. Safety Guard on Production / Default Environment
+* If no `[env]` / `--workspace` is specified (or `env === 'default'` / `'prod'` / `'production'`) and `--yes` / `--force` / `--headless` is not passed:
+  * Prompt interactively via `@clack/prompts` `confirm` (`"Put environment to sleep? This will take the web service offline until you run 'deploy-stack wake'."`, default `false`).
+  * When a non-default environment is passed (e.g., `deploy-stack sleep staging`), proceed without requiring an extra confirmation prompt.
+
+### 3. `deploy-stack sleep` Execution Flow
+1. **Resolve Target Context:**
+   * Resolve region (`resolveAwsRegion`), project name (`resolveProjectName`), and effective app prefix (`env && env !== 'default' ? `${projectName}-${env}` : projectName`).
+   * Inspect `terraform/` files locally (if present) via `parseTerraformConfig` to know whether `worker.tf` and `database.tf` exist and which `dbEngine` is configured.
+2. **Scale ECS Services to Zero:**
+   * Query `DescribeServicesCommand` on cluster `${appPrefix}-cluster` for `${appPrefix}-service` and (if present in `terraform/worker.tf` or discovered in the cluster) `${appPrefix}-worker`.
+   * Record the pre-sleep `desiredCount` (or default to `1` for web, `1` for worker) in memory/output, and call `UpdateServiceCommand({ cluster, service, desiredCount: 0 })` for each active service whose `desiredCount > 0`.
+   * If a service is already at `desiredCount === 0`, report it as already asleep (idempotent).
+3. **Stop Database (Unless `--skip-db`):**
+   * Use `findDbTarget(rdsClient, dbIdentifier, cwd)` from `src/utils/rds.js`.
+   * **Standard RDS Instance (`kind === 'instance'`):**
+     * If `status === 'available'`, call `StopDBInstanceCommand({ DBInstanceIdentifier: id })`.
+     * If `status === 'stopped'` or `'stopping'`, treat as idempotent and report already stopped/stopping.
+   * **Aurora Cluster (`kind === 'cluster'`):**
+     * If `status === 'available'`, call `StopDBClusterCommand({ DBClusterIdentifier: id })` (or if it is already configured with `0 ACU` auto-pause, note that stopping the cluster halts compute immediately and prevents wake-ups until `deploy-stack wake`).
+4. **7-Day AWS RDS Auto-Restart Guard & Savings Summary:**
+   * AWS automatically restarts stopped RDS instances and Aurora clusters after **7 consecutive days**.
+   * Print a clear warning with the exact UTC timestamp (`now + 7 days`):
+     * `⚠ AWS Note: Stopped RDS databases automatically restart after 7 days (<YYYY-MM-DD HH:mm UTC>). Re-run "npx deploy-stack sleep" or "npx deploy-stack destroy" for longer archiving.`
+   * Persist a lightweight state marker in `.deploy-stack/sleep-state.json` (gitignored if `.deploy-stack/` is local, or purely advisory) recording `{ env, sleptAt, autoRestartAt, services: { app: prevDesiredCount, worker: prevWorkerDesiredCount }, dbId, dbKind }` so `deploy-stack wake` (and `deploy-stack status`) can restore exact replica counts and warn if the 7-day window has elapsed.
+   * **FinOps Savings Calculation:**
+     * Calculate and display the exact hourly and monthly compute savings using the rates from `src/utils/visualizer.js`:
+       * Web Fargate task (`$9.01/mo` = `~$0.0123/hr` per replica)
+       * Worker Fargate task (`$9.01/mo` = `~$0.0123/hr` per replica when active)
+       * RDS `db.t4g.micro` (`$13.98/mo` = `~$0.0192/hr` compute paused; note that `20 GB` gp3 storage `~$2.30/mo` and ALB `$22.27/mo` remain active while infrastructure exists).
+     * Example output:
+       `💰 Estimated Savings While Asleep: ~$0.032/hr (~$22.99/mo in Fargate + RDS compute paused)`
+       `Wake anytime with: npx deploy-stack wake [env]`
+   * Emit `trackSuccess('sleep_run', { env_kind: isDefault ? 'default' : 'named', ecs_scaled: count, db_stopped: boolean, db_kind })`.
+
+### 4. `deploy-stack wake` Execution Flow
+1. **Start Database First (Unless `--skip-db`):**
+   * Resolve database via `findDbTarget`.
+   * If `status === 'stopped'`, call `StartDBInstanceCommand` (`kind === 'instance'`) or `StartDBClusterCommand` (`kind === 'cluster'`).
+   * Unless `--no-wait` is passed, poll with `pollUntil` (`DescribeDBInstancesCommand` / `DescribeDBClustersCommand`) until `status === 'available'` before starting ECS tasks so booting containers never crash-loop on an unreachable database.
+2. **Restore ECS Service Desired Counts:**
+   * Read `.deploy-stack/sleep-state.json` if present for the target `env` to restore previous `desiredCount` values (defaulting to `desiredCount = 1` for `${appPrefix}-service` and `desiredCount = 1` for `${appPrefix}-worker` if no state file exists).
+   * Call `UpdateServiceCommand({ cluster, service, desiredCount })`.
+   * Remove the entry for `env` from `.deploy-stack/sleep-state.json`.
+   * Emit `trackSuccess('wake_run', { env_kind, ecs_restored: count, db_started: boolean, waited: boolean })`.
+
+---
+
+## Part 2: Scheduled Cron Jobs (`deploy-stack add cron`)
+
+### 1. Capability Registration & CLI Flags
+* Add `cron` (or `cron:scheduler` with alias `cron`) to `SUPPORTED_CAPABILITIES` in `src/utils/addons.js` and `src/commands/add.js`.
+* Supported flags on `deploy-stack add cron`:
+  * `--schedule <expression>`: EventBridge Scheduler expression, e.g. `"cron(0 2 * * ? *)"` or `"rate(1 hour)"`. If omitted in interactive mode, prompt via `@clack/prompts` with common presets (`Hourly — rate(1 hour)`, `Daily at 00:00 UTC — cron(0 0 * * ? *)`, `Every 15 minutes — rate(15 minutes)`, `Custom expression...`). In headless mode without `--schedule`, default to `"cron(0 0 * * ? *)"` (daily at midnight UTC).
+  * `--cmd <command>` / `--cron-command <command>`: Command to execute inside the container when triggered (e.g. `"npm run cron"` or `"node scripts/cleanup.js"`). In headless mode without `--cmd`, default to `"npm run cron"`.
+  * `--name <job-name>`: Optional job slug (default: `"default"` or `"daily-job"`, sanitized to `[a-z0-9-]`), allowing multiple named schedules or updating in place with `--force`.
+  * `--timezone <tz>`: Optional IANA timezone string for `schedule_expression_timezone` (default: `"UTC"`).
+* Validate `--schedule` before the Terraform guard: must match `/^(cron|rate|at)\(.+\)$/` (`INVALID_CRON_SCHEDULE`).
+* Validate `--timezone` against safe characters `/^[A-Za-z0-9/_+-]{1,64}$/` (`INVALID_TIMEZONE`).
+
+### 2. Generated Terraform (`templates/terraform/addons/cron.tf` → `terraform/cron.tf`)
+* Provision:
+  1. **`aws_iam_role.scheduler_cron_role`:** Assumed by `scheduler.amazonaws.com`.
+  2. **`aws_iam_role_policy.scheduler_cron_policy`:** Grants `ecs:RunTask` on `aws_ecs_task_definition.app.arn` (both revision-specific and family wildcard `${aws_ecs_task_definition.app.family}:*`) and `iam:PassRole` on `aws_iam_role.execution_role.arn` and `aws_iam_role.task_role.arn` (with `Condition: { StringLike: { "iam:PassedToService": "ecs-tasks.amazonaws.com" } }`).
+  3. **`aws_scheduler_schedule.cron`:**
+     * `name = "${local.app_name}-cron-__CRON_NAME__"`
+     * `flexible_time_window { mode = "OFF" }`
+     * `schedule_expression = "__SCHEDULE_EXPRESSION__"`
+     * `schedule_expression_timezone = "__SCHEDULE_TIMEZONE__"`
+     * `target`:
+       * `arn = aws_ecs_cluster.main.arn`
+       * `role_arn = aws_iam_role.scheduler_cron_role.arn`
+       * `ecs_parameters`:
+         * `task_definition_arn = aws_ecs_task_definition.app.arn`
+         * `launch_type = "FARGATE"`
+         * `task_count = 1`
+         * `network_configuration` using `aws_subnet.public[*].id`, `[aws_security_group.ecs_tasks.id]`, and `assign_public_ip = true` (matching `aws_ecs_service.app` so it can pull from ECR and reach RDS without a NAT Gateway).
+       * `input = jsonencode({ containerOverrides = [{ name = "${local.app_name}-container", command = ["sh", "-c", __CRON_COMMAND_JSON__] }] })`
+* Ensure all generated HCL in `cron.tf` passes `terraform validate` and `tflint` with zero warnings.
+* **Cost Metadata (`src/utils/addons.js`):**
+  * `monthlyCost: 0.0`
+  * `pricingModel: 'usage'`
+  * `costImpact: '$0/mo fixed baseline (first 14M EventBridge Scheduler invocations/mo free); billed only for Fargate seconds while the cron task runs'`
+
+---
+
+## Part 3: Scheduled IaC Drift Detection (`.github/workflows/drift.yml`)
+
+### 1. CLI Integration (`deploy-stack drift` or `init --setup-ci-drift`)
+* Support two entrypoints so both new and existing projects can enable Scheduled IaC Drift Detection:
+  1. **During `deploy-stack init`:**
+     * New flag `--setup-ci-drift` in `src/core/parser.js` and `src/commands/init.js`.
+     * When `--setup-ci-drift` is passed (or offered in interactive `init`), scaffold `.github/workflows/drift.yml`.
+  2. **On existing projects (`deploy-stack drift` or `deploy-stack drift --setup`):**
+     * Register `drift` in `bin/cli.js` → `src/commands/drift.js` (`runDrift`).
+     * `deploy-stack drift --setup` (or `deploy-stack drift init`): Scaffolds `.github/workflows/drift.yml` into an already-initialized project (reading region and state bucket from `terraform/main.tf` and `terraform/backend.tf`).
+     * `deploy-stack drift` (default check mode): Executes `terraform init -input=false` + `terraform plan -detailed-exitcode -no-color` locally in `terraform/`, interpreting exit code `0` (`✅ No infrastructure drift detected`), exit code `2` (`⚠ Infrastructure drift detected!` with the resource diff summary and `error_code: 'DRIFT_DETECTED'`), and exit code `1` (`TERRAFORM_PLAN_FAILED`).
+
+### 2. Generated GitHub Actions Workflow (`templates/github/drift.yml` → `.github/workflows/drift.yml`)
+* **Triggers:**
+  * `schedule: [{ cron: '0 6 * * *' }]` (daily at 06:00 UTC)
+  * `workflow_dispatch: {}` (manual one-click trigger in GitHub Actions UI)
+* **Permissions:**
+  * `id-token: write` (for AWS OIDC role assumption)
+  * `contents: read`
+  * `issues: write` (to open/update GitHub Issues when drift is detected)
+* **Steps:**
+  1. Checkout repository (`actions/checkout@v4`).
+  2. Configure AWS credentials via the existing GitHub OIDC role (`aws-actions/configure-aws-credentials@v4` with `${{ secrets.AWS_ROLE_ARN }}` and the project's `AWS_REGION`).
+  3. Setup Terraform (`hashicorp/setup-terraform@v3`, `terraform_wrapper: false`).
+  4. Run `terraform init -input=false` in `working-directory: ./terraform`.
+  5. Run `terraform plan -detailed-exitcode -no-color -out=tfplan` in `./terraform`, capturing the exit code (`0`, `1`, or `2`) and saving human-readable diff output (`terraform show -no-color tfplan > plan.txt`).
+  6. **Automated Issue Creation / Update on Exit Code `2`:**
+     * Use `actions/github-script@v7` (or `gh issue`) when `steps.plan.outputs.exitcode == '2'` to search for an open issue labeled `iac-drift` (creating the label if needed):
+       * If an open `iac-drift` issue already exists, update its body/comment with the latest timestamp and Terraform plan diff (avoiding duplicate daily issue spam).
+       * Otherwise, open a new issue titled `"⚠️ Infrastructure Drift Detected in AWS"` containing the truncated Terraform plan diff and remediation commands (`npx deploy-stack apply` to reconcile or `terraform import`).
+     * If `steps.plan.outputs.exitcode == '0'` and an open `iac-drift` issue exists, automatically comment `"✅ Drift resolved"` and close the issue!
+  7. **Optional Slack Notification:**
+     * If `${{ secrets.SLACK_WEBHOOK_URL }}` is configured and exit code is `2`, POST a JSON alert payload with the repository name, workflow run link, and drift summary.
+
+---
+
+## Part 4: Documentation, Roadmap & Validation
+
+### 1. Documentation & Roadmap Updates
+* Create `apps/docs/src/content/docs/cli/sleep.md` (covering `deploy-stack sleep` and `deploy-stack wake`) and `apps/docs/src/content/docs/cli/drift.md` (covering `deploy-stack drift` and `.github/workflows/drift.yml`), and register them in the Starlight sidebar if configured.
+* Update `apps/docs/src/content/docs/cli/add.md` with `deploy-stack add cron` (`--schedule`, `--cmd`, `--name`, `--timezone`).
+* Check off the 3 items in `apps/docs/src/content/docs/roadmap.md`:
+  * `[x] Scheduled Cron Jobs`
+  * `[x] Environment Hibernation & FinOps`
+  * `[x] Scheduled IaC Drift Detection`
+
+### 2. Tests & IaC Validation
+* Add unit tests:
+  * `tests/sleep-wake.test.js`: Verify ECS scaling to `0`, RDS `StopDBInstanceCommand` / `StopDBClusterCommand`, `--skip-db`, 7-day auto-restart warning output, `.deploy-stack/sleep-state.json` persistence, `wake` RDS polling before ECS restore, and production confirmation guard.
+  * `tests/add.test.js`: Verify `deploy-stack add cron` renders `terraform/cron.tf`, validates `--schedule` and `--timezone`, supports `--cmd` and `--name`, and emits `add_run` telemetry.
+  * `tests/drift.test.js`: Verify `deploy-stack drift --setup` generates valid `.github/workflows/drift.yml` YAML, and `deploy-stack drift` handles `terraform plan -detailed-exitcode` exit codes `0`, `1`, and `2`.
+* Extend `scripts/test-iac.js` and `.github/workflows/iac-validation.yml` so `cron` is included in the `--with` addons validation run (`terraform validate` + `tflint`).

package/specs/gc.md

@@ -0,0 +1,26 @@
+# Spec: Orphaned Resource Garbage Collection (`gc`)
+
+## Overview
+The `gc` (Garbage Collection) command protects the user's AWS bill by scanning for lingering, orphaned infrastructure left behind by failed deployments, deleted PR previews, or manual AWS Console interventions.
+
+## UX & Flow
+1. Run `npx deploy-stack gc`.
+2. The CLI enters a "Dry Run / Discovery" phase, showing a spinner while it scans specific AWS services.
+3. It presents a categorized list of orphaned resources found, along with an estimated cost-saving or disk-space reclaimed.
+4. CLI prompts the user: `Are you sure you want to permanently delete these orphaned resources? (y/N)`.
+5. If confirmed, it deletes them and outputs a success summary.
+
+## Scan Targets (The Scope)
+* **Target 1: Untagged ECR Images:** Find all images in ECR repositories matching the project prefix (`<project-name>-*`) that lack a tag, and batch delete them.
+* **Target 2: Orphaned CloudWatch Log Groups:** Find log groups starting with `/ecs/<project-name>-` where the corresponding ECS cluster or service no longer exists.
+* **Target 3: Unattached Elastic IPs (EIPs):** Find any EIPs in the VPC that are not associated with a running NAT Gateway or EC2 instance (to stop the hourly unused EIP charge).
+
+## Technical Contract
+* **File:** `src/commands/gc.js`
+* **Dependencies:** `@aws-sdk/client-ecr`, `@aws-sdk/client-cloudwatch-logs`, `@aws-sdk/client-ec2`, `@clack/prompts`.
+* **Safety First:** The command must *never* delete a resource without explicit interactive confirmation. There is no `--yes` flag for this command to prevent CI pipeline accidents.
+
+## Test Requirements (`tests/gc.test.js`)
+* Mock AWS SDKs to return a mix of active and orphaned resources.
+* Prove that the dry-run output accurately counts only the orphaned resources.
+* Prove that rejecting the confirmation prompt prevents any `Delete*` commands from firing.

package/specs/integration-suite.md

@@ -0,0 +1,16 @@
+# Spec: Integration Stability Suite (Headless Contracts)
+
+## Objective
+Expand our Vitest coverage to guarantee that `deploy-stack` can be consumed by automated scripts and ecosystem wrappers (like `nest-deploy-stack`) without hanging on interactive prompts.
+
+## Requirements
+1. **Target:** Create a new test file at `tests/headless.test.js`.
+2. **Mocking:** Deep-mock `@clack/prompts` using `vi.mock()`.
+3. **Execution Assertions:** 
+   - Execute the core CLI generation logic passing `--headless` and `--preconfigured` alongside necessary configuration flags (e.g., `--framework=nestjs --port=3000`).
+   - Assert that the mocked prompt functions (`text`, `select`, `confirm`, etc.) are **never** called during execution.
+4. **Output Assertions:** Ensure the CLI correctly applies the values passed via the flags rather than falling back to interactive defaults.
+
+## Constraints
+- The test suite must run purely in memory or within a temporary directory to avoid polluting the local development environment with generated Terraform files.
+- It must execute quickly alongside the existing snapshot tests.

package/specs/logs.md

@@ -0,0 +1,32 @@
+# Spec: Context-Aware Log Streaming (`deploy-stack logs`)
+
+## Objective
+Provide real-time and historical CloudWatch log streaming directly in the terminal, automatically mapped to the ECS task and cluster without requiring the user to look up log group names or open the AWS Management Console.
+
+## CLI Command & Flags
+\`\`\`bash
+deploy-stack logs [service] [options]
+\`\`\`
+- `[service]` (optional): Name of the service/container. Defaults to the primary application service defined in `terraform/main.tf`.
+- `--tail <lines>`: Number of recent log lines to display (default: `50`).
+- `-f, --follow`: Stream logs continuously in real time (polling interval: 2 seconds).
+- `--error`: Filter output for common failure keywords (`ERROR`, `FATAL`, `Exception`, `fail`, `500`, `502`).
+- `--since <duration>`: Filter logs from a relative time window (e.g., `5m`, `1h`, `1d`). Default: `1h` when not following.
+- `--region <region>`: Explicit AWS region override.
+
+## Precedence & Resolution
+1. **Region Precedence:** `--region` flag -> `AWS_REGION` environment variable -> `terraform/main.tf` (`region = "..."`) -> fallback `us-east-2`.
+2. **Log Group Resolution:** Infer the CloudWatch log group `/ecs/<project-name>` by reading `terraform/main.tf` or project config. If not found, list log groups matching the project prefix.
+3. **AWS Session Handling:** On `ExpiredTokenException` or `UnrecognizedClientException`, print the standard recovery guidance (`aws sso login` / `aws configure`) and exit with code 1.
+
+## Output Formatting
+- Standardize on `picocolors`.
+- Prefix each line with formatted ISO timestamp (dimmed/gray) and task ID (dimmed).
+- Highlight lines containing errors or HTTP 5XX statuses in red; warnings in yellow.
+- Handle `SIGINT` (Ctrl+C) gracefully when following streams, printing a clean exit message without uncaught rejection traces.
+
+## Testing & Stability Requirements
+- Add comprehensive Vitest unit tests in `tests/logs.test.js`.
+- Mock `@aws-sdk/client-cloudwatch-logs` (`FilterLogEventsCommand`, `DescribeLogStreamsCommand`).
+- Verify region resolution precedence, error filtering, line count truncation, and graceful exit on missing log groups.
+- Zero network dependencies during test execution.