@adobe-commerce/aio-toolkit 1.0.13 → 1.0.15

package/CHANGELOG.md

@@ -5,6 +5,122 @@ 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.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
+
+- **feat(telemetry):** Enhanced telemetry instrumentation with conditional span access
+  - Added `Telemetry.getCurrentSpan()` method that accepts params and conditionally returns spans based on `ENABLE_TELEMETRY` flag
+  - Updated all action classes to pass params to `getCurrentSpan()` for conditional instrumentation
+  - Enables developers to access current OpenTelemetry span for custom instrumentation when telemetry is enabled
+  - Returns `undefined` when telemetry is disabled, allowing safe optional chaining patterns
+
+### 🔧 Refactoring
+
+- **refactor(telemetry):** Converted Telemetry class from static to instance methods
+  - Telemetry class now uses instance methods instead of static methods for better testability
+  - Added telemetry object to action context (`ctx.telemetry`) for easy access in action handlers
+  - Standardized parameter ordering across all action classes (params, ctx, logger)
+  - Updated JSDoc documentation with consistent examples showing telemetry usage
+  - Improved encapsulation and dependency injection patterns
+
+### 📝 Technical Details
+
+- Enhanced action classes with telemetry context:
+  - `RuntimeAction`: Added `ctx.telemetry` with access to current span and `instrument()` method
+  - `WebhookAction`: Added `ctx.telemetry` with access to current span and `instrument()` method
+  - `OpenwhiskAction`: Added `ctx.telemetry` with access to current span and `instrument()` method
+  - `EventConsumerAction`: Added `ctx.telemetry` with access to current span and `instrument()` method
+  - `GraphQlAction`: Added `ctx.telemetry` with access to current span and `instrument()` method
+- Telemetry API methods:
+  - `getCurrentSpan(params?)`: Returns current OpenTelemetry span (conditional based on ENABLE_TELEMETRY)
+  - `instrument(spanName, fn)`: Wraps function with automatic span creation for custom instrumentation
+- Achieved 100% test coverage for all framework action classes:
+  - RuntimeAction (100% statements/branches/functions/lines)
+  - Telemetry (100% statements/branches/functions/lines)
+  - WebhookAction (100% statements/branches/functions/lines)
+  - OpenwhiskAction (100% statements/branches/functions/lines)
+  - GraphQlAction (100% statements/branches/functions/lines)
+  - EventConsumerAction (100% statements/branches/functions/lines)
+- Added 25 comprehensive instrumentation tests covering all action types and edge cases
+- Fixed all linting and formatting issues (0 errors, 0 warnings)
+- All 636 tests passing across 30 test suites
+- No breaking changes - purely additive enhancements with backward compatibility
+
+### 💡 Usage Example
+
+```typescript
+const { RuntimeAction, RuntimeActionResponse, HttpMethod } = require('@adobe-commerce/aio-toolkit');
+
+// Custom function with telemetry
+const processData = (data, telemetry, logger) => {
+  const span = telemetry?.getCurrentSpan?.();
+  if (span) {
+    span.setAttribute('data.size', data.length);
+  }
+  logger.info('Processing data');
+  return { processed: true };
+};
+
+exports.main = RuntimeAction.execute(
+  'my-action',
+  [HttpMethod.POST],
+  ['data'],
+  ['Authorization'],
+  async (params, ctx) => {
+    const { logger, telemetry } = ctx;
+
+    // Wrap function to create child span
+    const instrumented = telemetry?.instrument?.('data.process', processData) || processData;
+    const result = instrumented(params.data, telemetry, logger);
+
+    return RuntimeActionResponse.success(result);
+  }
+);
+```
+
+**Key Features:**
+- `telemetry.getCurrentSpan(params)` - Access current span for custom attributes and events
+- `telemetry.instrument(spanName, fn)` - Wrap functions to create child spans automatically
+- Safe with optional chaining - gracefully degrades when telemetry is disabled
+
 ## [1.0.13] - 2026-01-07
 
 ### ✨ Features

package/README.md

@@ -289,6 +289,9 @@ OpenTelemetry integration for enterprise-grade observability with distributed tr
 - Automatic telemetry instrumentation for all framework action classes
 - Request ID correlation across all log messages (`x-adobe-commerce-request-id`)
 - Action type identification for better filtering (`action.type`)
+- Access to current OpenTelemetry span via `ctx.telemetry` for custom instrumentation
+- `telemetry.instrument()` method for wrapping functions with automatic span creation
+- Conditional span access based on `ENABLE_TELEMETRY` flag
 - Multi-provider support (New Relic implemented, Grafana ready)
 - Graceful fallback when telemetry is not configured
 - Zero performance impact when disabled (opt-in via feature flags)
@@ -334,27 +337,43 @@ Telemetry is automatically initialized when you use framework action classes:
  */
 
 const { RuntimeAction, RuntimeActionResponse, HttpMethod } = require("@adobe-commerce/aio-toolkit");
-const name = 'runtime-action';
+
+// Custom function with telemetry
+const processData = (data, telemetry, logger) => {
+  const span = telemetry?.getCurrentSpan?.();
+  if (span) {
+    span.setAttribute('data.size', data.length);
+  }
+  logger.info('Processing data');
+  return { processed: true };
+};
 
 exports.main = RuntimeAction.execute(
-  name,
+  'my-action',
   [HttpMethod.POST],
-  [],
+  ['data'],
   ['Authorization'],
   async (params, ctx) => {
-    const { logger } = ctx;
+    const { logger, telemetry } = ctx;
 
     // Logger automatically includes x-adobe-commerce-request-id and action.type
-    logger.info({
-      message: `${name}-log`,
-      params: JSON.stringify(params),
-    });
+    logger.info('Action started');
+
+    // Wrap function to create child span
+    const instrumented = telemetry?.instrument?.('data.process', processData) || processData;
+    const result = instrumented(params.data, telemetry, logger);
 
-    return RuntimeActionResponse.success("Hello World");
+    return RuntimeActionResponse.success(result);
   }
 );
 ```
 
+**Key Features:**
+- `telemetry.getCurrentSpan(params)` - Access current span for custom attributes and events
+- `telemetry.instrument(spanName, fn)` - Wrap functions to create child spans automatically
+- Safe with optional chaining - gracefully degrades when telemetry is disabled
+- Logger automatically includes request ID and action type for correlation
+
 **What Gets Logged Automatically:**
 
 All log messages automatically include:
@@ -1468,6 +1487,100 @@ 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
+
 ## Environment Variables
 
 Common environment variables used across components: