@grada-run/grada 0.0.1 → 0.32.0

package/specs/rollback-live-polling.md

@@ -0,0 +1,40 @@
+# Live Progress Updates for `deploy-stack rollback`
+
+Enhance the existing `DescribeServicesCommand` polling loop in `src/commands/rollback.js` to emit live spinner updates via `s.message(...)` so the user has continuous visibility into task provisioning, container crashes, and old-task draining.
+
+## 1. Preserve Existing Contracts (`src/commands/rollback.js`)
+Keep the existing polling architecture and test contracts intact:
+* **Keep the in-place loop:** Do not extract a new signature or alter how `service` and spinner instance `s` are referenced.
+* **Keep timing seams:** Preserve `pollIntervalMs` (default `5000`) and deadline-based `timeoutMs` (default `300000`) so all existing `{ pollIntervalMs: 1, timeoutMs: 50 }` tests continue to work without modification.
+* **Keep `PRIMARY` identity guard:** Continue matching the active deployment via `d.status === 'PRIMARY' && d.taskDefinition === targetTaskDefArn`. Never match a bare `PRIMARY` with a stale task definition ARN.
+* **Keep terminal states, UX, and telemetry:** Preserve the existing `rolloutState === 'COMPLETED'` success path, `rolloutState === 'FAILED'` failure path (`error_code: 'ROLLOUT_FAILED'`), and deadline timeout path (`error_code: 'ROLLOUT_TIMEOUT'`), along with their existing user-facing messages and guidance (`status` + `logs`).
+
+## 2. Elapsed Time & Live Counter Extraction
+1. Record `const startTime = Date.now();` when initializing the polling deadline (`const deadline = startTime + timeoutMs;`).
+2. On each poll iteration, after calling `DescribeServicesCommand`, compute:
+   * `const elapsedSec = Math.floor((Date.now() - startTime) / 1000);`
+3. If the matched `primary` deployment is not yet in a terminal state (`COMPLETED` or `FAILED`), extract its counters with safe zero defaults:
+   * `const runningCount = primary?.runningCount ?? 0;`
+   * `const desiredCount = primary?.desiredCount ?? 0;`
+   * `const pendingCount = primary?.pendingCount ?? 0;`
+   * `const failedTasks = primary?.failedTasks ?? 0;`
+
+## 3. Dynamic Spinner Messages (`s.message(...)`)
+On each non-terminal poll tick (right before checking the deadline / sleeping for `pollIntervalMs`), update the active spinner instance `s.message(...)` using the following priority order:
+
+1. **Target `PRIMARY` not yet observed (`!primary`):**
+   `Rolling back ${service} to revision ${targetRevision}... [${elapsedSec}s] (registering deployment...)`
+2. **Tasks are failing (`failedTasks > 0`):**
+   `Rolling back ${service} to revision ${targetRevision}... [${elapsedSec}s] (${runningCount}/${desiredCount} running, ${pendingCount} pending, ${failedTasks} failed ⚠️ — container crashing)`
+3. **New tasks are running, waiting on ECS cleanup/deprovisioning (`runningCount >= desiredCount && desiredCount > 0 && pendingCount === 0`):**
+   `Rolling back ${service} to revision ${targetRevision}... [${elapsedSec}s] (${runningCount}/${desiredCount} running — draining previous tasks)`
+4. **Standard provisioning (default in-progress state):**
+   `Rolling back ${service} to revision ${targetRevision}... [${elapsedSec}s] (${runningCount}/${desiredCount} running, ${pendingCount} pending)`
+
+## 4. Unit Tests (`tests/rollback.test.js`)
+* Keep all existing unit tests, timing options (`{ pollIntervalMs: 1, timeoutMs: 50 }`), and telemetry assertions (`error_code: 'ROLLOUT_FAILED'` / `'ROLLOUT_TIMEOUT'`) unchanged.
+* Add unit tests verifying that `s.message` is called with the expected progress strings during multi-poll sequences:
+  1. When the first poll has Not-Yet-Matching `PRIMARY` (`(registering deployment...)`) before transitioning to `COMPLETED`.
+  2. Standard provisioning progress (`(0/1 running, 1 pending)`).
+  3. Draining progress when `runningCount >= desiredCount` and `pendingCount === 0` (`(1/1 running — draining previous tasks)`).
+  4. Crashing container warning when `failedTasks > 0` (`(0/1 running, 0 pending, 2 failed ⚠️ — container crashing)`).

package/specs/secrets-pull-audit.md

@@ -0,0 +1,51 @@
+# Spec: Secrets Pull and Audit Commands
+
+## 1. Overview
+Introduce two new CLI commands to manage Day-2 configuration drift:
+- `npx deploy-stack secrets pull`: Fetches the JSON payload from AWS Secrets Manager and merges it into the local `.env` file.
+- `npx deploy-stack secrets audit`: Compares the local `.env` file against the remote AWS Secrets Manager payload and displays a colored drift report (missing locally, missing remotely, conflicting values).
+
+## 2. CLI Interface & UX
+Both commands must use `@clack/prompts` and `picocolors` to match the existing CLI design system.
+
+### `secrets pull`
+- **Command:** `npx deploy-stack secrets pull [file]` (defaults to `.env`).
+- **Flow:**
+  1. Show a spinner: "Fetching secrets from AWS..."
+  2. If the local `.env` file exists and has conflicting values, use Clack's `confirm` prompt to ask: "Conflicting variables found. Overwrite local values with remote?"
+  3. If headless (`--headless`), automatically overwrite.
+  4. Write/append the variables to the `.env` file in standard `KEY="VALUE"` format.
+  5. Show an outro: "Successfully synced X secrets to .env".
+
+### `secrets audit`
+- **Command:** `npx deploy-stack secrets audit [file]` (defaults to `.env`).
+- **Flow:**
+  1. Show a spinner: "Auditing local environment against AWS..."
+  2. Parse local `.env` and fetch the remote JSON secret.
+  3. Print a visual diff:
+     - Use green for keys only present in AWS (Missing locally).
+     - Use yellow for keys with mismatched values.
+     - Use gray/dim for keys only present locally (Not tracked in AWS).
+  4. Show an outro summarizing the drift count.
+
+## 3. AWS SDK v3 Integration
+- Use `@aws-sdk/client-secrets-manager` (`GetSecretValueCommand`).
+- The secret name convention should match the one established in `secrets push` (e.g., `<projectName>-secrets`).
+- Handle `ResourceNotFoundException` gracefully by informing the user that no remote secrets exist yet and suggesting they run `secrets push` first.
+
+## 4. File System & Parsing
+- Use the built-in `fs` module to read and write `.env`.
+- To parse the `.env` file safely, you can either implement a standard regex parser or use a lightweight zero-dependency approach. Do not introduce bloated dependencies if a simple parser suffices.
+- When writing to `.env`, preserve existing local variables that do not exist in AWS. Do not delete local-only overrides unless explicitly instructed.
+
+## 5. Telemetry
+- Call `trackEvent('secrets_pull', { projectName, variablesCount })`.
+- Call `trackEvent('secrets_audit', { projectName, driftCount })`.
+- Await `flushTelemetry()` before exiting.
+
+## 6. Testing Requirements (Strictly Headless)
+- Add tests in a new file (e.g., `test/secrets-pull.test.js`).
+- Use `vitest`.
+- **Deep Mocking Required:** You must completely mock `fs` (or use a temp directory), `@clack/prompts`, and `@aws-sdk/client-secrets-manager`.
+- The test suite must not pause for user input. Simulate the `confirm` prompt returning both `true` and `false`.
+- Ensure tests run at 0 CVEs and pass in a clean CI environment.

package/specs/serverless-lambda-target.md

@@ -0,0 +1,133 @@
+# Spec: Serverless Compute Primitives (`deploy-stack --target lambda`)
+
+## Overview
+Provide an alternate **AWS Lambda + Amazon API Gateway HTTP API (v2)** deployment target (`--target lambda`) alongside the default ECS Fargate + ALB architecture (`--target ecs` / `fargate`). Using the **AWS Lambda Web Adapter** extension inside the generated container image, existing web applications (Node.js/Express, Next.js, FastAPI/Python, Go, Rust, etc.) run on AWS Lambda with zero application code changes and a **$0.00/mo fixed compute and load-balancer baseline**.
+
+---
+
+## 1. CLI Flags & Interactive Prompt (`src/core/parser.js` & `src/commands/init.js`)
+
+### 1.1 Flag Parsing (`src/core/parser.js`)
+* Support `--target <target>` in `parseArgs` / `extractInitOptions`:
+  * Canonical values: `'ecs'` (default) and `'lambda'`.
+  * Accept `'fargate'` as a synonym for `'ecs'`.
+  * Reject unknown values before provisioning with `INVALID_COMPUTE_TARGET` (`✖ Invalid compute target "<value>". Supported targets: ecs, lambda`).
+
+### 1.2 Interactive & Headless `init` (`src/commands/init.js`)
+* In headless mode (`--headless`), default `target` to `'ecs'` unless `--target lambda` is explicitly passed.
+* In interactive mode, if `--target` was not explicitly passed, prompt via `@clack/prompts` `select`:
+  * Message: `"Select your AWS compute target:"`
+  * Options:
+    * `ecs` — `"ECS Fargate + ALB (Always-on containers, zero cold starts — ~$31.28/mo compute+ALB baseline)"`
+    * `lambda` — `"AWS Lambda + API Gateway v2 (Scale-to-zero serverless containers — $0.00/mo fixed compute baseline)"`
+* Pass `target` (`'ecs' | 'lambda'`) into `generateInfrastructure`, `renderPreFlightCard`, and `init_run` telemetry (`target: 'ecs' | 'lambda'`).
+
+---
+
+## 2. Container Image & AWS Lambda Web Adapter (`src/templates/dockerfile.js`)
+
+* When `target === 'lambda'`, inject the official **AWS Lambda Web Adapter** layer into the generated `Dockerfile` (final runtime stage):
+  ```dockerfile
+  COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.1 /lambda-adapter /opt/extensions/lambda-adapter
+  ENV AWS_LWA_PORT={{PORT}}
+  ENV PORT={{PORT}}
+  ```
+* This allows standard HTTP servers (`app.listen(process.env.PORT)`) to handle API Gateway HTTP API v2 payloads transparently on Lambda without changing application code or handlers.
+
+---
+
+## 3. Generated Terraform Topology (`templates/terraform/main-lambda.tf` → `terraform/main.tf`)
+
+When `target === 'lambda'`, write `templates/terraform/main-lambda.tf` to `terraform/main.tf`:
+
+### 3.1 Preserved Core Resources (Addon & Command Compatibility)
+* Keep the same resource names for shared primitives so `database.tf` and addons (`s3.tf`, `dynamodb.tf`, `bedrock.tf`, `ses.tf`, `sqs.tf`, `redis.tf`) remain compatible:
+  * `aws_ecr_repository.app` and `aws_ecr_lifecycle_policy.app`
+  * `aws_iam_role.task_role` (assumed by `["lambda.amazonaws.com", "ecs-tasks.amazonaws.com"]` so all addon `aws_iam_role_policy` attachments targeting `aws_iam_role.task_role.id` work out of the box)
+  * `aws_iam_role.execution_role`
+  * `aws_secretsmanager_secret.app_env` and `aws_secretsmanager_secret_version.app_env`
+  * `aws_vpc.main`, `aws_subnet.public`, `aws_internet_gateway.main`, `aws_route_table.public`, `aws_security_group.ecs_tasks` (kept so RDS/Aurora `database.tf` and `redis.tf` security group references `aws_security_group.ecs_tasks.id` continue to validate cleanly)
+  * GitHub OIDC provider & `aws_iam_role.github_actions` (updated to include `lambda:UpdateFunctionCode`, `lambda:GetFunction`, `lambda:GetFunctionConfiguration` alongside existing permissions).
+
+### 3.2 Serverless Compute & Routing Resources
+* **`aws_cloudwatch_log_group.app`:**
+  * `name = "/aws/lambda/${local.app_name}-fn"` (or retain `/ecs/${local.app_name}` / alias so `deploy-stack logs` can discover it).
+  * `retention_in_days = 30`
+* **`aws_lambda_function.app`:**
+  * `function_name = "${local.app_name}-fn"`
+  * `role = aws_iam_role.task_role.arn`
+  * `architectures = ["x86_64"]`
+  * `memory_size = 512`
+  * `timeout = 30`
+  * `environment { variables = { PORT = tostring(var.container_port), AWS_LWA_PORT = tostring(var.container_port), APP_SECRETS_ARN = aws_secretsmanager_secret.app_env.arn, ... } }`
+  * **Day-0 Bootstrap Compatibility:**
+    * *Important AWS API note:* AWS Lambda `CreateFunction` with `package_type = "Image"` fails on Day-0 `terraform apply` if the newly created ECR repository has no image yet (`Source image does not exist`), unlike ECS `aws_ecs_task_definition`.
+    * Evaluate and use the cleanest Day-0-safe pattern that passes `terraform validate`, `tflint`, and live `apply` before the first `git push` (or document how `apply` / `main-lambda.tf` handles Day-0 creation vs container deployment).
+* **`aws_apigatewayv2_api.main`:**
+  * `name = "${local.app_name}-http-api"`
+  * `protocol_type = "HTTP"`
+* **`aws_apigatewayv2_integration.lambda`:**
+  * `api_id = aws_apigatewayv2_api.main.id`
+  * `integration_type = "AWS_PROXY"`
+  * `integration_uri = aws_lambda_function.app.invoke_arn`
+  * `payload_format_version = "2.0"`
+* **`aws_apigatewayv2_route.default` & `aws_apigatewayv2_stage.default`:**
+  * `$default` route forwarding to `integrations/${aws_apigatewayv2_integration.lambda.id}` and `$default` stage with `auto_deploy = true`.
+* **`aws_lambda_permission.apigw`:**
+  * Grants `apigateway.amazonaws.com` `lambda:InvokeFunction` on `aws_lambda_function.app.function_name`.
+* **`aws_cloudfront_distribution.cdn`:**
+  * Fronts the API Gateway HTTP API domain (`replace(aws_apigatewayv2_api.main.api_endpoint, "https://", "")`) with `origin_protocol_policy = "https-only"` (since API Gateway v2 endpoints are HTTPS-only).
+* **Outputs:**
+  * `cloudfront_url = "https://${aws_cloudfront_distribution.cdn.domain_name}"`
+  * `api_gateway_url = aws_apigatewayv2_api.main.api_endpoint` (replaces or complements `alb_dns_name`).
+
+---
+
+## 4. CI/CD Deployment Workflow (`templates/github/deploy-lambda.yml` → `.github/workflows/deploy.yml`)
+
+* When `target === 'lambda'`, generate `.github/workflows/deploy.yml` from `templates/github/deploy-lambda.yml`:
+  * Builds the Docker image (`linux/amd64`) with the AWS Lambda Web Adapter layer and pushes `${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}` and `:latest`.
+  * Deploys to AWS Lambda via:
+    ```bash
+    aws lambda update-function-code \
+      --function-name "${PROJECT_NAME}-fn" \
+      --image-uri "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}"
+    aws lambda wait function-updated \
+      --function-name "${PROJECT_NAME}-fn"
+    ```
+
+---
+
+## 5. Pre-Flight Cost & Topology Visualizer (`src/utils/visualizer.js`)
+
+* Detect `computeTarget: 'lambda'` in `parseTerraformConfig` (when `terraform/main.tf` contains `resource "aws_lambda_function"` or via `config.target === 'lambda'`) and in `buildConfigFromInit`.
+* When `computeTarget === 'lambda'`:
+  * **Topology lines:**
+    * Replace `🌐 ALB (Public Entry & Health: ...)` with `🌐 API Gateway HTTP API v2 (Scale-to-zero HTTPS entry)`.
+    * Replace `📦 ECS Web Service ...` with `⚡ AWS Lambda Web Service 🟢 <framework> [512 MB · Scale-to-zero]`.
+  * **Cost Calculation (`calculateMonthlyCost`):**
+    * `fargate`: `$0.00` (for the web service; if a Fargate worker exists, only the worker bills Fargate).
+    * `alb`: `$0.00` (API Gateway HTTP API v2 is usage-based at `$1.00` per million requests, `$0.00/mo` fixed baseline).
+    * A Lambda + No-DB project shows `Fixed Baseline: ~$0.80/mo (Secrets: $0.80)`.
+    * A Lambda + Aurora Serverless v2 (`0 ACU`) project shows `Fixed Baseline: ~$0.80/mo (RDS: $0.00, Secrets: $0.80)`.
+
+---
+
+## 6. Addon & Day-2 Command Compatibility
+
+* **`deploy-stack add` (`src/commands/add.js`):**
+  * When injecting container environment variables into `terraform/main.tf`, support both ECS (`environment = [` JSON array inside `container_definitions`) and Lambda (`environment { variables = { ... } }` block inside `aws_lambda_function.app`), or keep a shared local/map so `deploy-stack add s3`, `dynamodb`, `bedrock`, `ses`, `redis`, `sqs` work on `--target lambda` projects.
+  * For `add cron` on a `--target lambda` project without ECS: either target `aws_lambda_function.app.arn` (`lambda:InvokeFunction`) or fail with a clear message if `cron` requires ECS.
+* **`deploy-stack logs` (`src/commands/logs.js`):**
+  * If `terraform/main.tf` is a Lambda target (`parseTerraformConfig(cwd).computeTarget === 'lambda'`), default the CloudWatch log group to `/aws/lambda/${appName}-fn`.
+
+---
+
+## 7. Documentation, Roadmap & Validation
+
+1. **Documentation & Roadmap:**
+   * Update `apps/docs/src/content/docs/cli/init.md` and `apps/docs/src/content/docs/guides/architecture.md` to document `--target lambda` and the scale-to-zero Lambda Web Adapter + API Gateway v2 topology.
+   * Mark `[x] Serverless Compute Primitives: deploy-stack --target lambda` as completed in `apps/docs/src/content/docs/roadmap.md` (completing 19/19 items in Phase 10!).
+2. **Tests & IaC Validation:**
+   * Add unit tests in `tests/generator.test.js`, `tests/visualizer.test.js`, `tests/headless.test.js`, and `tests/add.test.js` covering `--target lambda`.
+   * Add a `target: lambda` project check to `scripts/test-iac.js` and `.github/workflows/iac-validation.yml` so `templates/terraform/main-lambda.tf` is continuously validated with `terraform validate` and `tflint`.

package/specs/status.md

@@ -0,0 +1,31 @@
+# Spec: Health Dashboard & Auto-Diagnostics (`deploy-stack status`)
+
+## Objective
+Serve as the single Day-2 entry point for infrastructure health. Display an instant terminal dashboard of task lifecycle states and CloudWatch alarms. If the infrastructure is healthy, exit cleanly. If a degraded state is detected, automatically transition into the `diagnose` workflow to find the root cause.
+
+## CLI Command & Flags
+\`\`\`bash
+deploy-stack status [options]
+\`\`\`
+- `--region <region>`: Explicit AWS region override.
+- `--json`: Output raw status payload as JSON (disables auto-diagnose).
+
+## Core Checks (Phase 1)
+1. **ECS Service (`@aws-sdk/client-ecs`):** Fetch `desiredCount`, `runningCount`, and `pendingCount`.
+2. **CloudWatch Alarms (`@aws-sdk/client-cloudwatch`):** Fetch state of project-prefixed alarms (e.g., `alb_5xx_errors`).
+
+## Terminal UI & The Handoff (Phase 2)
+- Print a clear, color-coded summary block using `picocolors`:
+  - **Service:** Name, Status (`ACTIVE`).
+  - **Replicas:** `runningCount / desiredCount` (green if matching, yellow if pending, red if 0 running).
+  - **Alarms:** List configured alarms with current state badges (`[OK]`, `[ALARM]`).
+- **The Trigger:** If `runningCount < desiredCount` (after a brief grace period) OR any alarm is in the `ALARM` state:
+  1. Print: `⚠️ Degraded state detected. Running automated diagnostics...`
+  2. Automatically invoke the existing `runDiagnose()` function from `src/commands/diagnose.js`.
+  3. Exit with code 1 after diagnostics complete.
+
+## Testing & Stability Requirements
+- Add unit tests in `tests/status.test.js`.
+- Mock ECS and CloudWatch clients.
+- Verify status calculation for healthy states (clean exit, code 0).
+- Verify the auto-diagnose handoff triggers correctly during a crash loop or 5XX alarm state.

package/specs/telemetry-and-spawn-hardening.md

@@ -0,0 +1,69 @@
+# Spec: Telemetry Identity Separation, Context Alignment & Binary Check Deduplication
+
+## Overview
+Resolve three telemetry and process-spawning issues observed in live PostHog exports:
+1. **Machine-Scoped `distinct_id` vs. Project-Scoped `project_id` (`src/core/telemetry.js`):**
+   * Previously, `distinct_id` hashed `properties.projectName || 'unknown'`, causing commands that omitted `projectName` (`doctor_run` and early `add_run` guards) to hash `'unknown'` (`b23a6a8439c0dde5`) and merge unrelated users across geographies into one PostHog Person.
+2. **Consistent `is_ci` & `cli_command` Context (`src/core/telemetry.js`):**
+   * Align `is_ci` with `ci_provider` so unsetting `CI` while leaving `GITHUB_ACTIONS` set never produces `is_ci: false` alongside `ci_provider: 'github_actions'`.
+   * Guard `cli_command` on `is_cli_entry` so programmatic module imports report `'module_import'` while preserving multi-word CLI command names (`db connect`, `secrets push`) on real CLI invocations.
+3. **Binary Check Deduplication (`src/utils/aws.js`, `src/commands/doctor.js`):**
+   * Prevent redundant child-process spawns when `hasAwsCli()` or `runDoctor()` is called ~32 times in rapid succession inside PID-limited containers, while keeping unit tests isolated.
+
+---
+
+## Part 1: Machine-Scoped `distinct_id`, Project-Scoped `project_id` & Test Seams (`src/core/telemetry.js`)
+
+1. **`distinct_id` Resolution & 16-Hex Format:**
+   * `distinct_id` must always be a 16-character lowercase hexadecimal SHA-256 prefix (`sha256(rawIdentity)[:16]`), and must never hash `'unknown'` or a bare project folder name.
+   * **Test Seam & Cache Reset:**
+     * Export a `resetTelemetryIdentityCache()` function that clears the in-memory cached `distinct_id` between unit tests.
+     * Support an environment variable override `process.env.DEPLOY_STACK_TELEMETRY_ID_PATH` for the persistent identity file path (defaulting to `path.join(os.homedir(), '.deploy-stack', 'telemetry-id')`).
+   * **Resolution Precedence (Cached in Memory Once Resolved):**
+     * **Explicit Override Precedence:** If `process.env.DEPLOY_STACK_TELEMETRY_ID_PATH` is explicitly set and non-empty, always take **Branch B (Persistent File)** using that path—even when `is_ci` or `is_test_env` is `true`. This guarantees persistent-file unit tests run deterministically both locally and inside GitHub Actions (`CI=true`).
+     * **Branch A — Ephemeral / CI / Unconfigured Test Environment:** When `DEPLOY_STACK_TELEMETRY_ID_PATH` is not explicitly set and either `is_ci` is `true` or `is_test_env` is `true`, compute `distinct_id` by hashing a colon-delimited string of exact machine/CI attributes: `os.hostname()`, `os.platform()`, `os.arch()`, `process.env.GITHUB_REPOSITORY || ''`, `process.env.GITHUB_RUN_ID || ''`, and `process.env.GITLAB_PROJECT_PATH || ''`. Do **not** include `process.cwd()` in `distinct_id` so multiple commands run from different directories on the same runner share one Person within a run.
+     * **Branch B — Persistent File Environment:** When `DEPLOY_STACK_TELEMETRY_ID_PATH` is explicitly set, or when neither `is_ci` nor `is_test_env` is `true`, attempt to read the trimmed UUID string from the identity file path. If the file does not exist or is empty, generate a `crypto.randomUUID()`, create the parent directory (`recursive: true`), and write the UUID to the file. Hash the read or newly generated UUID string with SHA-256 (16-hex prefix) and cache it in memory. If reading or writing throws any filesystem error, fall back cleanly to Branch A and cache that result.
+2. **`project_id` Property Derivation:**
+   * Keep the existing `String(...)` coercion on `properties.projectName` (so numeric inputs like `42` coerce to `'42'`), delete `projectName` from the outgoing event properties, and attach `project_id` set to the 16-character SHA-256 hex prefix of the resolved project name string.
+   * When `properties.projectName` is `undefined`, `null`, or empty string `''`, derive the fallback string from `path.basename(process.cwd())`; if that basename is also empty (e.g., `/`), use `'unknown'`.
+   * Update the existing `tests/telemetry.test.js` test that previously asserted `distinct_id === sha256('42')[:16]` so it now asserts `properties.project_id === sha256('42')[:16]` and verifies `distinct_id` is a stable 16-hex machine ID not equal to `sha256('unknown')[:16]`.
+
+---
+
+## Part 2: Telemetry Context Alignment (`src/core/telemetry.js`)
+
+1. **Boolean Env Helper & `is_ci` / `ci_provider` Consistency:**
+   * Treat an environment variable as active/truthy only when it is defined and its trimmed lowercase value is not `''`, `'0'`, or `'false'`.
+   * Apply this check in `detectCiProvider()` as well (fixing the pre-existing quirk where `GITHUB_ACTIONS='false'` matched `'github_actions'`).
+   * Compute `ci_provider` first, then set `is_ci` to `true` if `process.env.CI` passes the truthy check **or** `ci_provider !== 'none'`.
+2. **`cli_command` Precedence Guarded by `is_cli_entry`:**
+   * Compute `is_cli_entry` first (`['cli.js', 'deploy-stack'].includes(path.basename(process.argv?.[1] || ''))`).
+   * When `is_cli_entry` is `true`, preserve the existing precedence: use `CLI_COMMAND` (which captures two-word commands like `db connect` and `secrets push`) falling back to `process.argv.slice(2).join(' ') || 'unknown'`.
+   * When `is_cli_entry` is `false`, set `cli_command` to `'module_import'`.
+
+---
+
+## Part 3: Binary Pre-Flight Caching & Deduplication (`src/utils/aws.js` & `src/commands/doctor.js`)
+
+1. **Synchronous `hasAwsCli(options = {})` Result Caching (`src/utils/aws.js`):**
+   * Preserve the exact existing signature `hasAwsCli(options = {})` where callers pass `options.spawnSyncImpl` (used across `src/commands/exec.js`, `src/commands/db.js`, `tests/exec.test.js`, and `tests/db.test.js`).
+   * **Bypass Cache on Custom `options.spawnSyncImpl`:** Only read/populate the module-level boolean cache when `options.spawnSyncImpl` is not provided (`options.spawnSyncImpl === undefined`). Whenever a caller or test passes a custom `options.spawnSyncImpl` (such as `tests/exec.test.js` calling `hasAwsCli({ spawnSyncImpl: mockSpawn })` three times expecting `false`/`true`/`false`), execute `options.spawnSyncImpl` directly without reading or writing the cache.
+   * For default calls (`options.spawnSyncImpl === undefined`), cache the boolean result for `5000` ms (`AWS_CLI_CACHE_TTL_MS = 5000`) so 32 rapid calls in a container without injected mocks spawn `aws --version` only once instead of 32 times.
+   * Export `resetAwsCliCache()` to allow explicit cache clearing in unit tests.
+2. **In-Flight `checkDependency` Deduplication in `runDoctor()` (`src/commands/doctor.js`):**
+   * Keep the deduplication scoped to `src/commands/doctor.js` (leaving sequential single calls in `init.js` and `destroy.js` untouched).
+   * Maintain a module-scoped `Map` of in-flight promises keyed by the binary name (`cmd`). Perform the `Map` lookup and `.set(cmd, promise)` synchronously before any `await` in the wrapper, and remove the key in `.finally(() => inFlight.delete(cmd))` once the promise settles.
+
+---
+
+## Part 4: Unit Tests (`tests/telemetry.test.js`, `tests/doctor.test.js`, `tests/aws.test.js`)
+
+1. **`tests/telemetry.test.js`:**
+   * Call `resetTelemetryIdentityCache()` in `beforeEach`.
+   * Update the numeric `projectName: 42` test to assert `properties.project_id === sha256('42')[:16]` and verify `distinct_id` is a 16-hex string that stays identical across events with and without `projectName` and never equals `b23a6a8439c0dde5` (`sha256('unknown')[:16]`).
+   * Test persistent file identity using a temporary directory via `DEPLOY_STACK_TELEMETRY_ID_PATH` (verifying that a UUID file is created and subsequent calls after `resetTelemetryIdentityCache()` produce the same `distinct_id`, even when `CI=true`).
+   * Verify `is_ci` is `true` when `CI` is unset (`delete process.env.CI`) and `GITHUB_ACTIONS='true'`, and `false` when `CI='false'` and `GITHUB_ACTIONS='false'`.
+   * Verify `cli_command` is `'module_import'` when `is_cli_entry` is `false`, and preserves `CLI_COMMAND` / subcommand args when `is_cli_entry` is `true`.
+2. **`tests/doctor.test.js` & `tests/aws.test.js`:**
+   * In `tests/doctor.test.js`, verify that calling `runDoctor()` 5 times concurrently via `Promise.all` invokes `checkDependency` only once per binary (4 calls total, not 20) while the promises are in flight, and invokes it fresh on a subsequent sequential call.
+   * In `tests/aws.test.js`, use a `child_process` module mock (`vi.mock`) to verify that repeated default `hasAwsCli()` calls within the TTL spawn `aws --version` only once and reuse the cached boolean until `resetAwsCliCache()` is called, while leaving `tests/exec.test.js` undisturbed.

package/specs/telemetry-hardening.md

@@ -0,0 +1,35 @@
+# Spec: Telemetry Observability & Schema Protection
+
+## Overview
+Recent PostHog exports showed an automated analyzer importing `deploy-stack` modules directly and calling `trackEvent` with primitive values (e.g., `trackEvent(true, "test")`). We want to **keep all events** (do not drop unknown or fuzzer-generated events, as they provide valuable intelligence), while preventing primitive string/array arguments from polluting the PostHog column schema via object spreading or crashing `crypto.createHash`. We also want to add invocation context tags (`is_tty`, `is_cli_entry`).
+
+---
+
+## Part 1: Capture & Normalize in `src/core/telemetry.js`
+
+### 1. Remove the Event Allowlist & Normalize `eventName`
+* Remove the allowlist filtering in `trackEvent(eventName, properties)` so that all events (including unexpected or fuzzer-generated event names like `'test'`, `'data'`, `true`, or `1`) are captured and sent to PostHog.
+* Only return early if `process.env.DO_NOT_TRACK` is enabled or if `eventName === undefined || eventName === null || String(eventName).trim() === ''`.
+* Otherwise, normalize the event name via `const normalizedEvent = String(eventName);` so booleans or numbers are safely serialized.
+
+### 2. Protect Schema by Wrapping Non-Object `properties` & Safe Project Name Hashing
+* Check if `properties` is a plain object:
+  * If `properties === undefined || properties === null`, treat it as `{}`.
+  * If `typeof properties === 'object' && !Array.isArray(properties)`, spread it normally.
+  * If `properties` is a primitive (string, number, boolean) or an Array, preserve the data without spreading by wrapping it as `{ raw_properties: properties }`.
+* **Safe Project Name Coercion:** Before passing `rawProjectName` to `crypto.createHash('sha256').update(...)`, coerce it via `String(rawProjectName ?? 'unknown')` so non-string `projectName` properties (e.g., `{ projectName: 42 }`) never throw a `TypeError`.
+
+### 3. Invocation Context Properties
+Add two boolean properties to the default telemetry payload (alongside `is_ci` and `is_test_env`) so PostHog dashboards can segment direct module imports from interactive CLI runs:
+* `is_tty`: `Boolean(process.stdout && process.stdout.isTTY)`
+* `is_cli_entry`: Check the basename of `process.argv[1]` using `path.basename`:
+  `Boolean(process.argv && typeof process.argv[1] === 'string' && ['cli.js', 'deploy-stack'].includes(path.basename(process.argv[1])))`
+
+---
+
+## Part 2: Test Requirements (`tests/telemetry.test.js`)
+
+* Update the existing allowlist drop-tests to verify that arbitrary event names (e.g., `'test'`, `true`, `1`) **are** sent to PostHog with `event: String(eventName)`.
+* Verify that passing a primitive or array as `properties` (e.g., `trackEvent('test', 'test')` or `trackEvent('test', ['a', 'b'])`) sends `{ raw_properties: ... }` and does **not** create indexed keys (`0`, `1`, `2`, `3`).
+* Verify that passing a non-string `projectName` (e.g., `trackEvent('test', { projectName: 42 })`) hashes `'42'` cleanly without throwing.
+* Verify that events include boolean `is_tty` and `is_cli_entry` properties (asserting `typeof === 'boolean'` and testing `is_cli_entry` with stubbed `process.argv[1]`).