@adobe-commerce/aio-toolkit 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -5,6 +5,256 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.7] - 2026-06-18
+
+### ✨ Features
+
+- **feat(telemetry): add Grafana LGTM telemetry provider**
+
+  New `GrafanaTelemetry` class in `src/framework/telemetry/grafana/` forwards OpenTelemetry
+  signals (traces, metrics, logs) to a Grafana LGTM collector via OTLP/HTTP. Three operating
+  modes:
+
+  - **Dev** (`GRAFANA_DEV=true`) — targets `http://localhost:4318`, the default OTLP port of the
+    [Grafana LGTM Docker image](https://github.com/grafana/docker-otel-lgtm); no credentials
+    required. Start the stack with:
+    ```bash
+    docker run --rm -p 3000:3000 -p 4317:4317 -p 4318:4318 --name otel-lgtm grafana/otel-lgtm:latest
+    ```
+  - **Tunnel / deployed** — targets `GRAFANA_ENDPOINT` without authentication; use a Cloudflare
+    tunnel to expose a local stack to deployed Runtime actions:
+    ```bash
+    npx cloudflared tunnel --url http://localhost:4318
+    ```
+  - **Grafana Cloud** (`GRAFANA_CLOUD=true`) — targets `GRAFANA_ENDPOINT` with HTTP Basic auth
+    derived from `GRAFANA_INSTANCE_ID` and `GRAFANA_API_KEY`.
+
+  Added to the provider fallback chain after New Relic:
+  1. New Relic — `NEW_RELIC_TELEMETRY=true`
+  2. Grafana LGTM — `GRAFANA_TELEMETRY=true`
+  3. No telemetry — original action runs uninstrumented
+
+  **Configuration reference:**
+
+  | Variable | Required | Default | Description |
+  |---|---|---|---|
+  | `ENABLE_TELEMETRY` | ✅ | — | Must be `true` to enable any telemetry |
+  | `GRAFANA_TELEMETRY` | ✅ | — | Must be `true` to select this provider |
+  | `GRAFANA_DEV` | — | `false` | `true` for localhost dev mode |
+  | `GRAFANA_ENDPOINT` | ✅ tunnel & Cloud / — dev | — | Collector base URL |
+  | `GRAFANA_SERVICE_NAME` | — | `app-builder-app` | Service name tag |
+  | `GRAFANA_CLOUD` | — | `false` | `true` for Grafana Cloud Basic auth |
+  | `GRAFANA_INSTANCE_ID` | ✅ when `GRAFANA_CLOUD=true` | — | Grafana Cloud stack instance ID |
+  | `GRAFANA_API_KEY` | ✅ when `GRAFANA_CLOUD=true` | — | Grafana Cloud API key / token |
+
+- **feat(log-sanitizer): add `LogSanitizer` class and `SENSITIVE_KEYS` param support**
+
+  New `LogSanitizer` class in `src/framework/telemetry/helpers/log-sanitizer/` deep-clones a
+  value and replaces sensitive field values with `"[REDACTED]"` before they reach the log stream.
+
+  **Built-in sensitive key detection (case-insensitive):**
+  - Exact matches: `authorization`, `x-api-key`, `cookie`, `set-cookie`
+  - Suffix patterns: `*_api_key`, `*_secret`, `*_token`, `*_password`, `*_key`, `*-token`, `*-secret`, `*-key`
+
+  All action classes (`RuntimeAction`, `EventConsumerAction`, `OpenwhiskAction`) automatically
+  sanitize headers, parameters, and results in their debug log calls. `Telemetry.createLogger()`
+  also sanitizes all object-type arguments passed to the returned logger. `LogSanitizer` is
+  exported from the main package index for direct use.
+
+  **Project-specific keys via `SENSITIVE_KEYS` param:**
+
+  New `static parseSensitiveKeys(raw: unknown): ReadonlySet<string>` parses the optional
+  `SENSITIVE_KEYS` action param into additional keys to redact. All action classes and
+  `Telemetry.createLogger()` call it automatically. Accepts:
+
+  | Input type | Example | Result |
+  |---|---|---|
+  | Comma-separated string | `"x-merchant-token,internal_id"` | `Set { "x-merchant-token", "internal_id" }` |
+  | Array | `["x-merchant-token", "INTERNAL_ID"]` | `Set { "x-merchant-token", "internal_id" }` |
+  | Single string | `"x-merchant-token"` | `Set { "x-merchant-token" }` |
+  | Anything else (incl. `undefined`) | — | `Set {}` (no additional keys) |
+
+  Add project-specific keys in `app.config.yaml`:
+  ```yaml
+  inputs:
+    SENSITIVE_KEYS: "x-merchant-token,internal_order_id"
+  ```
+
+### 🛠️ Internal
+
+- **chore(telemetry): replace `@ts-expect-error` directives with ambient OTel type declaration**
+
+  Three stale `@ts-expect-error` directives in the telemetry source are replaced by a new
+  ambient module declaration in `src/global-types/adobe-aio-lib-telemetry-otel.d.ts` that
+  correctly types the `@adobe/aio-lib-telemetry/otel` sub-path export.
+
+- **refactor(log-sanitizer): extract constants to `types.ts`**
+
+  `EXACT_SENSITIVE_KEYS` and `SENSITIVE_KEY_SUFFIXES` moved from inline module-level constants
+  to exported constants in a dedicated `types.ts`, making them importable and independently
+  testable.
+
+- **feat(telemetry): add `GrafanaTelemetryValidator`**
+
+  New `GrafanaTelemetryValidator` implementing `BaseTelemetryValidator`:
+  - `isConfigured()` — `true` when both `ENABLE_TELEMETRY=true` and `GRAFANA_TELEMETRY=true`
+  - `validateConfiguration()` — no-op in dev mode; throws `TelemetryInputError` when
+    `GRAFANA_ENDPOINT` or `GRAFANA_SERVICE_NAME` is missing/empty in tunnel or Cloud mode
+
+- **chore(test): add `test/tsconfig.json`**
+
+  Gives VS Code's TypeScript language server the correct context for test files (jest/node
+  types, relaxed `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`).
+
+- **chore(test): fix missing platform mock in Linux `isCursorIde()` test**
+
+  The Linux `execPath` test case was not mocking `os.platform()` to return `'linux'`,
+  causing it to fall through to the macOS branch on macOS developer machines.
+
+### 📚 Documentation
+
+- **README** — new Grafana LGTM section covering all three operating modes, `app.config.yaml`
+  snippets, `.env` variables, usage example, and full env-var reference table.
+- **README** — `LogSanitizer` section documenting the class API, `parseSensitiveKeys()`,
+  `SENSITIVE_KEYS` param usage, sensitive key detection table, constructor options, and
+  behavioural notes.
+
+---
+
+## [1.2.6] - 2026-05-10
+
+### ✨ Features
+
+- **feat(cli-workflow): add `aio-toolkit-cli-workflow` CLI**
+
+  New `npx aio-toolkit-cli-workflow` binary for orchestrating Adobe I/O CLI workflows.
+  Performs an AIO CLI pre-flight check with installation guidance on startup.
+
+  **`env:setup`** — interactive environment configuration:
+  - Prompts "Do you have a workspace config file?" and runs `aio app use <file>` if yes.
+  - Falls back to `aio console org select` → `aio console project select` → `aio console workspace select` if no config file is provided.
+  - Accepts `--config-file` to skip the prompt and use a specified file directly.
+
+  **`env:reset`** — full AIO CLI environment reset:
+  - Accepts `--env stage|prod` (default `prod`).
+  - Runs: logout → clear local & global config → telemetry off → set env → login → telemetry on.
+
+  **`cron:enable`** — enable AIO Runtime cron rules:
+  - Confirms the current workspace, lists rules via `aio rt rule list --json`, and prompts for rule selection.
+  - Accepts `--all` to enable every rule without prompting.
+
+  **`cron:disable`** — disable AIO Runtime cron rules:
+  - Mirrors `cron:enable` but calls `aio rt rule disable`.
+
+  **`cron:status`** — display detailed cron rule status:
+  - Lists all rules with action name, status, trigger name, cron schedule, and version.
+  - Accepts `--name <ruleName>` to inspect a single rule.
+  - Uses a multi-strategy JSON parser (stdout/stderr fallback, ANSI stripping, oclif-envelope unwrapping, prefix-text slicing) for reliable output capture.
+
+  **`cron:delete`** — delete cron rules and their triggers:
+  - Confirms workspace, prompts for rule selection, then deletes the trigger (`aio rt trigger delete`) before the rule (`aio rt rule delete`).
+
+- **feat(integration): add `AmazonSQSClient`**
+
+  New `AmazonSQSClient` in `src/integration/amazon-sqs-client/` for Amazon SQS integration:
+  - **Batched publish** for standard and FIFO queues (with `MessageGroupId` and `MessageDeduplicationId` support).
+  - **Long-polling consume** with configurable batch size, wait time, and auto-deletion.
+  - Full TypeScript types: `AmazonSQSConfig`, `MessageHandler`, `PublishStats`, `ConsumeStats`.
+  - 38 tests with 100% statement, branch, function, and line coverage.
+
+### 🛠️ Internal
+
+- **feat(framework): add `ParseCliFlag` helper**
+
+  New `ParseCliFlag` class with a static `parse(args, flag)` method that handles both
+  `--flag=value` and `--flag value` argument styles. Used by `env:setup`, `env:reset`,
+  and `cron:status`.
+
+- **feat(framework): add `AioCliDetector` helper**
+
+  New `AioCliDetector` class to detect whether the `aio` CLI is installed and to verify
+  availability of sub-commands. Integrated into the `aio-toolkit-cli-workflow` startup check.
+
+- **feat(framework): extend `CommandDescriptor` with `options`**
+
+  Added optional `options?: CommandOption[]` to `CommandDescriptor` so each command class
+  can declare its own flags. `CliWorkflowHelp` reads these dynamically when rendering help output.
+
+### 📚 Documentation & Cursor Context
+
+- **Package overview** — added `docs/OVERVIEW.md` covering installation, dependency
+  resolution, and a full module index for all toolkit components.
+
+- **Framework reference docs** — new docs added under `docs/framework/`:
+  `runtime-action`, `webhook-action`, `graphql-action`, `event-consumer-action`,
+  `openwhisk`, `publish-event`, `abdb-collection`, `abdb-repository`,
+  `file-repository`, `runtime-api-gateway-service`, `telemetry`.
+
+- **Commerce reference docs** — new docs added under `docs/commerce/`:
+  `adobe-commerce-client`, `adobe-auth`, `shipping-carrier`, `onboard-commerce`.
+
+- **Integration reference docs** — new `docs/integration/amazon-sqs-client.md`.
+
+- **Security rules** — 13 global security rules added under `.cursor/rules/security-global/`
+  covering API security, authentication, injection, SSRF, path traversal, SQL, XXE,
+  output encoding, data protection, error handling, dependency management, input validation,
+  and dangerous flows. Also added `security-lang-node.mdc` for Node.js-specific patterns.
+
+- **New Cursor commands**:
+  - `aio-toolkit-create-openwhisk-action.md` — AI-guided scaffolding for OpenWhisk sub-actions and orchestrators.
+  - `aio-toolkit-analyze-adobe-commerce-module.md` — analyzes existing Adobe Commerce modules.
+  - `aio-toolkit-create-shipping-carrier.md` — scaffolds a custom shipping carrier integration.
+  - `aio-toolkit-create-amazon-sqs-consumer.md` — scaffolds an Amazon SQS consumer action.
+
+- **New Cursor rules**:
+  - `aio-toolkit-use-publish-event.mdc` — guides integrating `PublishEvent` for CloudEvents publishing to Adobe I/O Events.
+  - `aio-toolkit-use-abdb-collection.mdc` — guides schema-validated ABDB collection usage.
+  - `aio-toolkit-use-abdb-repository.mdc` — guides repository pattern usage with ABDB.
+  - `aio-toolkit-use-file-repository.mdc` — guides Adobe I/O Files-based persistence.
+  - `aio-toolkit-use-runtime-api-gateway-service.mdc` — guides API Gateway HTTP calls via `RuntimeApiGatewayService`.
+  - `aio-toolkit-use-adobe-auth.mdc` — guides Adobe IMS authentication patterns.
+  - `aio-toolkit-use-amazon-sqs-publish.mdc` — guides SQS message publishing with `AmazonSQSClient`.
+
+### 🔧 Fixes & Improvements
+
+- **fix(cursor): rename exception field `class` → `type` in webhook command**
+
+  `WebhookActionResponse.exception()` parameter renamed from `exceptionClass` to
+  `exceptionType` and the JSON response field from `class` to `type`, matching the
+  actual library behavior introduced in v1.2.4.
+
+- **fix(cursor): correct `IMS_ORD_ID` typo to `IMS_ORG_ID` in Commerce client rule**
+
+  All env var references in `aio-toolkit-create-adobe-commerce-client.mdc` now use
+  the correct `IMS_ORG_ID` key.
+
+- **fix(cursor): document `raw-http: true` requirement for webhook signature verification**
+
+  The webhook command now explicitly states that `raw-http: true` must be set under
+  `annotations:` in `app.config.yaml` for signature verification to work.
+
+- **fix(cursor): expand GraphQL resolver `ctx` destructuring in commands and rules**
+
+  Resolver examples now show the full context (`logger`, `headers`, `telemetry`,
+  `params`) with inline descriptions of each field.
+
+- **fix(cursor): add HEAD/OPTIONS to supported HTTP methods in runtime-action command**
+
+  `create-runtime-action.md` now lists all six supported methods including `HEAD`
+  and `OPTIONS`.
+
+- **fix(cursor): document optional `headers` parameter on `RuntimeActionResponse.success()`**
+
+  Updated command docs to reflect that `success(result, headers?)` accepts an optional
+  second argument for custom HTTP response headers.
+
+- **chore(cursor): set `alwaysApply: false` on Commerce client rule**
+
+  `aio-toolkit-create-adobe-commerce-client.mdc` is now opt-in; it was previously
+  applying on every session regardless of context.
+
+---
+
 ## [1.2.5] - 2026-04-20
 
 ### 🔧 Chores