@adobe-commerce/aio-toolkit 1.0.14 → 1.0.16

package/CHANGELOG.md

@@ -5,6 +5,96 @@ 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.0.16] - 2026-02-23
+
+### ✨ Features
+
+- **feat(cli):** New Adobe I/O Events Onboarding CLI (`aio-toolkit-onboard-events`)
+  - Command-line tool for managing Adobe I/O Events and Commerce event integrations
+  - Three sub-commands: `execute`, `cleanup`, and `help`
+  - Automated provider, registration, and event subscription management
+  - Support for both OAuth 1.0a and IMS authentication
+  - Configuration-driven approach using YAML files
+  - Comprehensive environment variable validation
+  - Structured logging with detailed progress tracking
+  - Cleanup command for removing test/development resources
+  - Respects dependency order during cleanup (registrations → metadata → providers)
+  - 100% test coverage with comprehensive test suites
+
+### 🔧 Refactoring
+
+- **refactor(commands):** Framework command architecture refactoring (#132)
+  - Abstract command base class for consistent CLI structure
+  - Command registry pattern for extensible command management
+  - AI-agent friendly base commands (base-apply, base-check)
+  - Standardized help command implementation
+  - Improved code organization and maintainability
+  - Enhanced type safety with TypeScript interfaces
+
+- **refactor(helpers):** New helper utilities for CLI commands
+  - `ApplicationName` helper for extracting app names from config
+  - `AdobeAuthToken` helper for centralized token generation
+  - `AdobeCommerceClient` helper for Commerce API integration
+  - IO Events authentication and environment helpers
+  - Commerce helper utilities following DRY principle
+  - 100% test coverage for all helper functions
+
+### 💡 Usage Examples
+
+**Execute Adobe I/O Events onboarding**:
+```bash
+npx aio-toolkit-onboard-events execute
+```
+
+**Cleanup development resources**:
+```bash
+npx aio-toolkit-onboard-events cleanup
+```
+
+**Display help**:
+```bash
+npx aio-toolkit-onboard-events help
+```
+
+---
+
+## [1.0.15] - 2026-02-09
+
+### ✨ Features
+
+- **feat(cli):** New Cursor IDE Context Management CLI (`aio-toolkit-cursor-context`)
+  - Command-line tool for managing Cursor IDE context files in Adobe App Builder projects
+  - Three sub-commands: `check`, `apply`, and `help`
+  - Automatic IDE detection (macOS, Windows, Linux)
+  - Model Context Protocol (MCP) server configuration
+  - Force mode for CI/CD pipelines
+  - Multi-directory support (`.cursor/rules` and `.cursor/commands`)
+  - Comprehensive error handling and user feedback
+
+### 💡 Usage Examples
+
+**Check context setup**:
+```bash
+npx aio-toolkit-cursor-context check
+```
+
+**Apply contexts (standard mode)**:
+```bash
+npx aio-toolkit-cursor-context apply
+```
+
+**Apply contexts (force mode)**:
+```bash
+npx aio-toolkit-cursor-context apply -f
+```
+
+**Display help**:
+```bash
+npx aio-toolkit-cursor-context help
+```
+
+---
+
 ## [1.0.14] - 2026-01-20
 
 ### ✨ Features

package/README.md

@@ -1487,30 +1487,205 @@ const registrations = await manager.list();
 await manager.delete('your-registration-id');
 ```
 
+### 🛠️ CLI Tools
+
+#### `aio-toolkit-cursor-context`
+
+Command-line tool for managing Cursor IDE context files (rules and commands) in your Adobe App Builder projects. This CLI automatically sets up Cursor IDE-specific contexts and configures the Model Context Protocol (MCP) server for enhanced development experience.
+
+##### Commands
+
+###### `check`
+Validates that Cursor contexts are properly set up in your project.
+
+```bash
+npx aio-toolkit-cursor-context check
+```
+
+**Features:**
+- ✅ Checks for `.cursor/rules` and `.cursor/commands` directories
+- ✅ Validates MCP server configuration
+- ✅ Detects if running in Cursor IDE
+- ✅ Reports missing files or configurations
+
+**Output Example:**
+```
+✅ Cursor IDE detected
+✅ MCP server configured
+✅ Found 3 context files in .cursor/rules
+✅ Found 4 context files in .cursor/commands
+✅ Cursor contexts are properly set up
+```
+
+###### `apply`
+Copies Cursor context files from the package to your project.
+
+```bash
+# Standard mode - copies missing files only
+npx aio-toolkit-cursor-context apply
+
+# Force mode - overwrites existing files and bypasses IDE detection
+npx aio-toolkit-cursor-context apply -f
+npx aio-toolkit-cursor-context apply --force
+```
+
+**Features:**
+- 📁 Copies context files to `.cursor/rules` and `.cursor/commands`
+- 🔄 Creates MCP configuration in `.cursor/mcp.json`
+- 🛡️ IDE detection prevents accidental application in non-Cursor environments
+- ⚡ Force mode for CI/CD pipelines or when IDE detection fails
+- 📊 Reports copied, skipped, and overwritten files
+
+**Standard Mode Output:**
+```
+Copied 3 new context files to .cursor/rules
+Skipped 2 files (already exist)
+✅ MCP server configured
+✅ All cursor contexts applied successfully
+```
+
+**Force Mode Output:**
+```
+Overwritten 5 existing files in .cursor/rules
+Copied 4 new files to .cursor/commands
+✅ MCP server configured
+✅ All cursor contexts applied successfully (force mode)
+```
+
+###### `help`
+Displays help information for the CLI.
+
+```bash
+npx aio-toolkit-cursor-context help
+```
+
+##### Context Files Included
+
+The CLI provides the following context files:
+
+**Rules (`.cursor/rules/`):**
+- `aio-toolkit-create-adobe-commerce-client.mdc` - Creating Adobe Commerce client operations
+- `aio-toolkit-oop-best-practices.mdc` - Object-oriented programming best practices
+- `aio-toolkit-setup-new-relic-telemetry.mdc` - Setting up New Relic telemetry
+
+**Commands (`.cursor/commands/`):**
+- `aio-toolkit-create-event-consumer-action.md` - Create event consumer actions
+- `aio-toolkit-create-graphql-action.md` - Create GraphQL actions
+- `aio-toolkit-create-runtime-action.md` - Create runtime actions
+- `aio-toolkit-create-webhook-action.md` - Create webhook actions
+
+##### Use Cases
+
+1. **Initial Project Setup**: Run `apply` to set up all Cursor contexts
+2. **Continuous Integration**: Use `apply -f` in CI/CD pipelines
+3. **Verification**: Run `check` to ensure contexts are properly configured
+4. **Updates**: Run `apply -f` after toolkit updates to get latest contexts
+
+#### `aio-toolkit-onboard-events`
+
+Command-line tool for managing Adobe I/O Events and Commerce event integrations. This CLI automates the process of onboarding event providers, registrations, and subscriptions, as well as cleaning up resources from test/development environments.
+
+##### Commands
+
+###### `execute`
+Onboards Adobe I/O Events providers, registrations, and Commerce event subscriptions based on configuration file.
+
+```bash
+# Execute with default config (onboard.config.yaml)
+npx aio-toolkit-onboard-events execute
+```
+
+**Features:**
+- ✅ Creates Adobe I/O Events providers with automatic duplicate detection
+- ✅ Sets up event metadata for custom events
+- ✅ Configures event registrations with webhook or journal delivery
+- ✅ Subscribes to Adobe Commerce events (supports both OAuth and IMS authentication)
+- ✅ Validates environment variables upfront with clear error messages
+- ✅ Structured logging with detailed progress tracking
+
+###### `cleanup`
+Removes Adobe I/O Events resources and Commerce event subscriptions defined in configuration file.
+
+```bash
+# Cleanup with default config
+npx aio-toolkit-onboard-events cleanup
+```
+
+**Features:**
+- 🗑️ Deletes event registrations
+- 🗑️ Removes event metadata
+- 🗑️ Deletes event providers
+- 🗑️ Unsubscribes from Commerce events and removes providers
+- ⚡ Respects dependency order (registrations → metadata → providers)
+- 📊 Provides detailed cleanup summary
+
+###### `help`
+Displays help information for the CLI.
+
+```bash
+npx aio-toolkit-onboard-events help
+```
+
+##### Configuration File
+
+The CLI uses `onboard.config.yaml` to define resources. Default template:
+
+```yaml
+# Configuration file version
+version: "1.0"
+
+# Application metadata
+application:
+  name: "My App Builder Application"
+  # Description is optional
+  # description: "My App Builder Application for Adobe Commerce"
+
+# Events configuration
+events:
+  # Adobe I/O Events configuration
+  io:
+    config: io-events.json  # File path to I/O events configuration
+
+  # Adobe Commerce Events configuration
+  commerce:
+    providerKey: commerce
+    config: commerce-events.json  # File path to Commerce events configuration
+
+# Deployment settings
+deployment:
+  # Instance type: paas | cloud
+  # paas = Adobe Commerce Cloud/On-premise (OAuth)
+  # cloud = Adobe Commerce as Cloud Service (IMS)
+  type: paas
+  
+  # Authentication type (optional, auto-detected from type if not specified)
+  # Allowed values: oauth | ims
+  # Auto-detection: paas → oauth, cloud → ims
+  # authType: oauth
+```
+
+##### Use Cases
+
+1. **Development Onboarding**: Run `execute` to quickly set up event integrations
+2. **Environment Cleanup**: Run `cleanup` to remove test resources before production deployment
+3. **CI/CD Integration**: Automate event configuration in deployment pipelines
+4. **Multi-Environment Setup**: Use different config files for dev/staging/production environments
+
 ## Environment Variables
 
 Common environment variables used across components:
 
 ```bash
-# Adobe commerce credentials
-COMMERCE_BASE_URL=commerce-base-url
-COMMERCE_CONSUMER_KEY=commerce-consumer-key
-COMMERCE_CONSUMER_SECRET=commerce-consumer-secret
-COMMERCE_ACCESS_TOKEN=commerce-access-token
-COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
-# Environment from DIST file
-OAUTH_BASE_URL=https://ims-na1.adobelogin.com/ims/token/
-IO_MANAGEMENT_BASE_URL=https://api.adobe.io/events/
-# OAuth configs
+# Adobe I/O Events OAuth (Required for aio-toolkit-onboard-events)
 # The following values can be copied from the Credential details page in AppBuilder under Organization > Project > Workspace > OAuth Server-to-Server
 OAUTH_CLIENT_ID=client-id
 OAUTH_CLIENT_SECRET=client-secret
 OAUTH_TECHNICAL_ACCOUNT_ID=technical-account-id
 OAUTH_TECHNICAL_ACCOUNT_EMAIL=technical-account-email
 OAUTH_ORG_ID=org-id
-OAUTH_SCOPES=scopes
-# OAUTH_HOST=<string>
-# Workspace configs
+OAUTH_SCOPES=openid, AdobeID, adobeio_api
+
+# Adobe I/O Workspace (Required for aio-toolkit-onboard-events)
 # The following values can be copied from the JSON downloadable in AppBuilder from Organization > Project > Workspace
 # IO_CONSUMER corresponds to project.org.id
 # IO_PROJECT_ID corresponds to project.id
@@ -1518,6 +1693,36 @@ OAUTH_SCOPES=scopes
 IO_CONSUMER_ID=consumer-id
 IO_PROJECT_ID=project-id
 IO_WORKSPACE_ID=workspace-id
+
+# Workspace Configuration (Required for aio-toolkit-onboard-events)
+IO_WORKSPACE_CONFIG=path/to/onboard.config.yaml
+
+# Adobe Commerce Base Configuration (Required for Commerce events)
+COMMERCE_BASE_URL=https://your-commerce-store.com
+COMMERCE_ADOBE_IO_EVENTS_MERCHANT_ID=merchant-id
+COMMERCE_ADOBE_IO_EVENTS_ENVIRONMENT_ID=environment-id
+
+# Commerce OAuth 1.0a Authentication (Use when authType is "oauth1a")
+COMMERCE_OAUTH_CONSUMER_KEY=consumer-key
+COMMERCE_OAUTH_CONSUMER_SECRET=consumer-secret
+COMMERCE_OAUTH_ACCESS_TOKEN=access-token
+COMMERCE_OAUTH_ACCESS_TOKEN_SECRET=access-token-secret
+
+# Commerce IMS Authentication (Use when authType is "ims")
+COMMERCE_IMS_CLIENT_ID=client-id
+COMMERCE_IMS_CLIENT_SECRET=client-secret
+COMMERCE_IMS_TECHNICAL_ACCOUNT_ID=tech-account-id
+COMMERCE_IMS_TECHNICAL_ACCOUNT_EMAIL=tech-email
+COMMERCE_IMS_ORG_ID=org-id
+COMMERCE_IMS_SCOPES=openid, AdobeID, adobeio_api
+
+# Legacy Environment Variables (Still supported for backward compatibility)
+OAUTH_BASE_URL=https://ims-na1.adobelogin.com/ims/token/
+IO_MANAGEMENT_BASE_URL=https://api.adobe.io/events/
+COMMERCE_CONSUMER_KEY=commerce-consumer-key
+COMMERCE_CONSUMER_SECRET=commerce-consumer-secret
+COMMERCE_ACCESS_TOKEN=commerce-access-token
+COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
 ```
 
 ## License