@adobe-commerce/aio-toolkit 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -5,6 +5,151 @@ 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.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
+
+- **chore(release): bump version to 1.2.5 to fix version inconsistency**
+
+  Version was out of sync between the package and the release tag. This patch
+  release corrects the version number with no functional code changes.
+
+---
+
 ## [1.2.4] - 2026-04-20
 
 ### ✨ Features

package/README.md

@@ -1650,6 +1650,73 @@ if (stats.errors.length) {
 
 ---
 
+#### `AmazonSQSClient`
+Batched publisher and long-polling consumer for Amazon SQS standard and FIFO queues.
+
+**Installation**
+```bash
+npm install @aws-sdk/client-sqs
+```
+
+**Basic Usage**
+```typescript
+const { AmazonSQSClient } = require('@adobe-commerce/aio-toolkit');
+
+const client = new AmazonSQSClient({
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue',
+});
+```
+
+**Publishing messages**
+```typescript
+const payloads = orders.map(o => JSON.stringify(o));
+const stats = await client.publish(payloads);
+
+console.log(`published=${stats.published} failed=${stats.failed}`);
+if (stats.errors.length) {
+  console.error('Failed payloads:', stats.errors);
+}
+```
+
+**Publishing to a FIFO queue**
+```typescript
+const fifoClient = new AmazonSQSClient({
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue.fifo',
+  messageGroupId: 'order-processing',         // required for FIFO
+  messageDeduplicationId: 'unique-batch-id',  // optional — omit to use content-based dedup
+});
+
+const stats = await fifoClient.publish(payloads);
+```
+
+**Consuming messages**
+```typescript
+const stats = await client.consume(
+  { batchSize: 10, waitTimeSeconds: 20 }, // long polling
+  async (message) => {
+    const order = JSON.parse(message.body);
+    await processOrder(order);
+  }
+);
+
+console.log(`consumed=${stats.consumed} acked=${stats.acked} failed=${stats.failed}`);
+```
+
+**API Reference**
+
+| Method | Description | Returns |
+|---|---|---|
+| `publish(payloads)` | Sends each payload as an SQS message; FIFO queues include group/dedup IDs | `Promise<PublishStats>` |
+| `consume(options, handler)` | Long-polls the queue, invokes `handler` for each message, auto-deletes on success | `Promise<ConsumeStats>` |
+
+---
+
 #### `InfiniteLoopBreaker`
 Detect and prevent infinite loops in event-driven applications.
 
@@ -2118,6 +2185,108 @@ deployment:
 3. **CI/CD Integration**: Automate event configuration in deployment pipelines
 4. **Multi-Environment Setup**: Use different config files for dev/staging/production environments
 
+#### `aio-toolkit-cli-workflow`
+
+Command-line tool for orchestrating Adobe I/O CLI workflows in your App Builder projects. This CLI acts as a wrapper around the `aio` CLI to streamline environment setup, resets, and cron rule management via interactive prompts.
+
+> **Prerequisite:** The `aio` CLI must be installed. If it is missing, the command will detect this at startup and print installation instructions pointing to the [Adobe App Builder CLI install guide](https://developer.adobe.com/app-builder/docs/guides/runtime_guides/tools/cli-install).
+
+##### Commands
+
+###### `env:setup`
+Interactively configure the AIO Console environment (org → project → workspace).
+
+```bash
+npx aio-toolkit-cli-workflow env:setup
+
+# Skip the interactive prompt and use a specific workspace config file
+npx aio-toolkit-cli-workflow env:setup --config-file ./path/to/.aio
+```
+
+**Flow without `--config-file`:**
+1. Prompts "Do you have a workspace config file?" (yes/no).
+2. If **yes** — prompts for the file path and runs `aio app use <file>`.
+3. If **no** — runs `aio console org select` → `aio console project select` → `aio console workspace select` interactively.
+
+###### `env:reset`
+Fully reset the AIO CLI environment and re-authenticate.
+
+```bash
+# Reset for production (default)
+npx aio-toolkit-cli-workflow env:reset
+
+# Reset for staging
+npx aio-toolkit-cli-workflow env:reset --env stage
+```
+
+**Steps performed:**
+1. `aio auth logout`
+2. `aio config clear -f` (local) + `aio config clear -g -f` (global)
+3. `aio telemetry off`
+4. `aio config set cli.env <stage|prod>`
+5. `aio auth login`
+6. `aio telemetry on`
+
+After reset, verify with `aio config get cli.env` and `aio console where`.
+
+###### `cron:status`
+Display the status of all AIO Runtime cron rules in the current workspace.
+
+```bash
+# List all cron rules
+npx aio-toolkit-cli-workflow cron:status
+
+# Inspect a single rule by name
+npx aio-toolkit-cli-workflow cron:status --name myRuleName
+```
+
+**Output per rule:** rule name, status (active/inactive), action name, action path, publish status, trigger name, cron schedule, version.
+
+###### `cron:enable`
+Enable AIO Runtime cron rules interactively.
+
+```bash
+# Interactive rule selection
+npx aio-toolkit-cli-workflow cron:enable
+
+# Enable all rules without prompting
+npx aio-toolkit-cli-workflow cron:enable --all
+```
+
+###### `cron:disable`
+Disable AIO Runtime cron rules interactively.
+
+```bash
+# Interactive rule selection
+npx aio-toolkit-cli-workflow cron:disable
+
+# Disable all rules without prompting
+npx aio-toolkit-cli-workflow cron:disable --all
+```
+
+###### `cron:delete`
+Delete AIO Runtime cron rules and their associated triggers.
+
+```bash
+npx aio-toolkit-cli-workflow cron:delete
+```
+
+Confirms the workspace, lists all rules (with trigger names), and prompts for one or more rule numbers to delete. For each selected rule the associated trigger is deleted first (`aio rt trigger delete`) and then the rule (`aio rt rule delete`).
+
+###### `help`
+Displays help information for the CLI.
+
+```bash
+npx aio-toolkit-cli-workflow help
+```
+
+##### Use Cases
+
+1. **First-time setup**: Run `env:setup` to select org, project, and workspace in one step.
+2. **Environment switching**: Run `env:reset --env stage` or `env:reset --env prod` to cleanly switch AIO CLI environments.
+3. **Cron management**: Use `cron:status` to audit schedules, then `cron:enable` / `cron:disable` to control them without memorising `aio rt` commands.
+4. **Rule cleanup**: Use `cron:delete` to remove stale rules and their triggers together.
+
 ## Environment Variables
 
 Common environment variables used across components: