sfcc-dev-mcp 1.0.15 → 1.0.19

package/{docs/best-practices/scapi_hooks.md → ai-instructions/skills/sfcc-scapi-hooks/SKILL.md}

@@ -1,8 +1,13 @@
-# Quick Guide: Salesforce B2C Commerce SCAPI Hooks for AI Agents
+---
+name: sfcc-scapi-hooks
+description: Guide for implementing SCAPI hooks in Salesforce B2C Commerce. Use this when asked to create SCAPI hooks, extend Shopper API endpoints, validate API requests, or modify API responses for headless commerce.
+---
+
+# Quick Guide: Salesforce B2C Commerce SCAPI Hooks
 
 This guide provides essential best practices and code examples for implementing Salesforce Commerce API (SCAPI) hooks. It is designed to be a quick reference for development with AI code assistants.
 
-**IMPORTANT**: Before implementing SCAPI hooks, consult the **Performance and Stability Best Practices** guide from this MCP server. Review the index-friendly APIs section and job development standards to ensure your hooks follow SFCC performance requirements and avoid database-intensive operations.
+**IMPORTANT**: Before implementing SCAPI hooks, consult the **Performance and Stability Best Practices** guide. Review the index-friendly APIs section and job development standards to ensure your hooks follow SFCC performance requirements and avoid database-intensive operations.
 
 ## 1. Core Concepts
 
@@ -39,11 +44,11 @@ This file points to your hooks configuration.
 ```json
 {
   "name": "int_scapi_hooks_extension",
-  "hooks": "./cartridge/hooks.json"
+  "hooks": "./cartridge/scripts/hooks.json"
 }
 ```
 
-### `hooks.json` (e.g., `/cartridge/hooks.json`)
+### `hooks.json` (e.g., `/cartridge/scripts/hooks.json`)
 
 This file maps the hook extension point name to your script file.
 
@@ -52,15 +57,15 @@ This file maps the hook extension point name to your script file.
   "hooks": [
     {
       "name": "dw.ocapi.shop.basket.items.beforePOST",
-      "script": "./basket/validateItems.js"
+      "script": "./hooks/basket/validateItems.js"
     },
     {
       "name": "dw.ocapi.shop.customer.modifyGETResponse",
-      "script": "./customer/enrichResponse.js"
+      "script": "./hooks/customer/enrichResponse.js"
     },
     {
       "name": "dw.ocapi.shop.order.afterPOST",
-      "script": "./order/notifyOms.js"
+      "script": "./hooks/order/notifyOms.js"
     }
   ]
 }
@@ -70,16 +75,18 @@ This file maps the hook extension point name to your script file.
 Organize hook scripts by the resource they modify for better maintainability.
 
 ```
-/cartridge
-├── hooks.json
-└──/scripts
-   └──/hooks
-      ├──/basket
-      │  └── validateItems.js
-      ├──/customer
-      │  └── enrichResponse.js
-      └──/order
-         └── notifyOms.js
+my_cartridge/
+├── package.json
+└── cartridge/
+  └── scripts/
+    ├── hooks.json
+    └── hooks/
+      ├── basket/
+      │   └── validateItems.js
+      ├── customer/
+      │   └── enrichResponse.js
+      └── order/
+        └── notifyOms.js
 ```
 
 ## 3. Core Implementation Patterns
@@ -122,6 +129,26 @@ return;
 
 ```javascript
 return new Status(Status.OK);
+
+### Passing Data Between Hooks
+
+If you need to compute something in `after*` and output it in `modify*Response`, use `request.custom` within the same request.
+
+```javascript
+exports.afterPOST = function (basket, doc) {
+  request.custom.myComputedValue = 'abc';
+  return new Status(Status.OK);
+};
+
+exports.modifyPOSTResponse = function (basket, responseDoc, doc) {
+  responseDoc.c_myComputedValue = request.custom.myComputedValue;
+  return new Status(Status.OK);
+};
+```
+
+### Detecting SCAPI vs OCAPI
+
+SCAPI and OCAPI share many hook extension points. When behavior must diverge, branch on `request.isSCAPI()`.
 ```
 
 ## 4. Code Examples

package/ai-instructions/skills/sfcc-script-evaluation/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: sfcc-script-evaluation
+description: Guide for using the evaluate_script tool to execute JavaScript on SFCC instances via the script debugger
+---
+
+# SFCC Script Evaluation Skill
+
+This skill documents how to use the `evaluate_script` tool effectively for executing JavaScript code on an SFCC instance via the script debugger.
+
+## Overview
+
+The `evaluate_script` tool allows you to execute arbitrary JavaScript code on an SFCC sandbox instance. It works by:
+
+1. Creating a debugger session
+2. Setting a breakpoint on a controller
+3. Triggering the controller via HTTP
+4. Evaluating your expression in the halted context
+5. Returning the result and cleaning up
+
+## Required Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `script` | Yes | - | The JavaScript code to execute |
+| `siteId` | No | `RefArch` | The site ID (accepts either `RefArch` or `Sites-RefArch-Site`) |
+| `locale` | No | `default` | Storefront locale segment used when triggering the controller (tries without locale first, then retries with `/{locale}` if needed) |
+| `timeout` | No | `30000` | Maximum execution time in milliseconds |
+| `breakpointFile` | No | Auto-detected | Custom controller path for breakpoint |
+| `breakpointLine` | No | `1,10,20,30,40,50` | Specific line for a single breakpoint; if omitted, strategic lines (1,10,20,30,40,50) are used |
+
+## Script Syntax Rules
+
+### ✅ DO: Use expressions that return a value
+
+The last expression in your script is returned as the result.
+
+```javascript
+// Simple expressions
+1 + 1
+// Result: 2
+
+dw.system.Site.current.ID
+// Result: "RefArchGlobal"
+```
+
+### ❌ DON'T: Use `return` at the top level
+
+```javascript
+// WRONG - causes compilation error
+return 1 + 1
+
+// Error: "invalid return"
+```
+
+### ❌ DON'T: Use `var` assignments expecting the variable
+
+```javascript
+// WRONG - var declarations return null in debugger context
+var result = {}; result.foo = 'bar';
+
+// Error: Cannot set property "foo" of null
+```
+
+### ✅ DO: Use inline object literals with JSON.stringify
+
+```javascript
+// CORRECT - inline object literal wrapped in JSON.stringify
+JSON.stringify({siteId: dw.system.Site.current.ID, locale: request.locale})
+// Result: {"siteId":"RefArchGlobal","locale":"en_GB"}
+```
+
+### ✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic
+
+```javascript
+// CORRECT - IIFE pattern for multi-step logic
+(function() {
+  var p = dw.catalog.ProductMgr.getProduct('25518704M');
+  return JSON.stringify({id: p.ID, name: p.name, online: p.online});
+})()
+// Result: {"id":"25518704M","name":"Pull On Pant","online":true}
+```
+
+### ❌ DON'T: Use `require()` statements
+
+```javascript
+// WRONG - require() returns null in debugger context
+var CustomerMgr = require('dw/customer/CustomerMgr');
+CustomerMgr.getSiteCustomerList()
+
+// Error: Cannot call method "getSiteCustomerList" of null
+```
+
+### ✅ DO: Use global `dw.*` namespace directly
+
+```javascript
+// CORRECT - access SFCC APIs via global dw namespace
+dw.customer.CustomerMgr.getSiteCustomerList().ID
+// Result: "RefArch"
+```
+
+## Accessing SFCC Objects
+
+### Site Information
+
+```javascript
+// Current site ID
+dw.system.Site.current.ID
+
+// All sites
+(function() {
+  var sites = dw.system.Site.getAllSites();
+  var result = [];
+  for (var i = 0; i < sites.size(); i++) {
+    result.push(sites[i].ID);
+  }
+  return JSON.stringify(result);
+})()
+
+// Site preferences (list all custom preference keys)
+JSON.stringify(Object.keys(dw.system.Site.current.preferences.custom))
+
+// Get specific site preference value
+dw.system.Site.current.preferences.custom.myPreferenceName
+```
+
+### Products
+
+```javascript
+// Get product by ID
+dw.catalog.ProductMgr.getProduct('productId')
+
+// Get product details
+(function() {
+  var p = dw.catalog.ProductMgr.getProduct('25518704M');
+  if (!p) return 'Product not found';
+  return JSON.stringify({
+    id: p.ID,
+    name: p.name,
+    online: p.online,
+    brand: p.brand
+  });
+})()
+
+// Product custom attributes
+(function() {
+  var p = dw.catalog.ProductMgr.getProduct('25518704M');
+  return JSON.stringify(Object.keys(p.custom));
+})()
+```
+
+### Customers
+
+```javascript
+// Site customer list
+dw.customer.CustomerMgr.getSiteCustomerList().ID
+
+// Get customer by ID (requires customer number)
+dw.customer.CustomerMgr.getCustomerByCustomerNumber('00001234')
+```
+
+### Orders
+
+```javascript
+// Search orders (always close the iterator!)
+(function() {
+  var orders = dw.order.OrderMgr.searchOrders(
+    'orderNo != {0}',
+    'creationDate desc',
+    ''
+  );
+  var result = [];
+  var i = 0;
+  while (orders.hasNext() && i < 5) {
+    var o = orders.next();
+    result.push({
+      orderNo: o.orderNo,
+      status: o.status.value,
+      total: o.totalGrossPrice.value
+    });
+    i++;
+  }
+  orders.close(); // IMPORTANT: Always close iterators
+  return JSON.stringify(result);
+})()
+```
+
+### Request/Session Context
+
+```javascript
+// Current request locale
+request.locale
+// Result: "en_GB"
+
+// Session ID
+session.sessionID
+
+// Current customer (if logged in)
+session.customer
+```
+
+## Working with Collections
+
+SFCC collections need special handling - they're not JavaScript arrays.
+
+### Iterating Collections
+
+```javascript
+// Using size() and index access
+(function() {
+  var sites = dw.system.Site.getAllSites();
+  var result = [];
+  for (var i = 0; i < sites.size(); i++) {
+    result.push(sites[i].ID);
+  }
+  return JSON.stringify(result);
+})()
+
+// Using Iterator pattern
+(function() {
+  var iter = dw.catalog.CatalogMgr.getSiteCatalog().getRoot().getSubCategories();
+  var result = [];
+  while (iter.hasNext()) {
+    var cat = iter.next();
+    result.push({id: cat.ID, name: cat.displayName});
+  }
+  return JSON.stringify(result);
+})()
+```
+
+### Array Operations
+
+```javascript
+// Arrays work normally, use JSON.stringify for readable output
+JSON.stringify([1, 2, 3].map(function(x) { return x * 2; }))
+// Result: [2,4,6]
+
+// Arrow functions are supported
+JSON.stringify([1, 2, 3].map(x => x * 2))
+// Result: [2,4,6]
+```
+
+## Return Value Formatting
+
+### Primitives
+
+```javascript
+// Strings, numbers, booleans return directly
+'hello'
+// Result: "hello"
+
+42
+// Result: 42
+
+true
+// Result: true
+```
+
+### Objects
+
+```javascript
+// Raw objects return [object Object]
+({foo: 'bar'})
+// Result: [object Object]
+
+// Use JSON.stringify for readable output
+JSON.stringify({foo: 'bar'})
+// Result: {"foo":"bar"}
+```
+
+### SFCC Objects
+
+```javascript
+// SFCC objects return their string representation
+dw.catalog.ProductMgr.getProduct('25518704M')
+// Result: [Product sku=25518704M]
+
+// Access properties directly or use JSON.stringify
+dw.catalog.ProductMgr.getProduct('25518704M').name
+// Result: "Pull On Pant"
+```
+
+## Error Handling
+
+### Check for null values
+
+```javascript
+// WRONG - throws error if product doesn't exist
+dw.catalog.ProductMgr.getProduct('invalid').name
+// Error: Cannot read property "name" from null
+
+// CORRECT - check for null
+(function() {
+  var p = dw.catalog.ProductMgr.getProduct('invalid');
+  return p ? p.name : 'Product not found';
+})()
+// Result: "Product not found"
+```
+
+### Wrap complex logic in try-catch
+
+```javascript
+(function() {
+  try {
+    var p = dw.catalog.ProductMgr.getProduct('25518704M');
+    return JSON.stringify({id: p.ID, name: p.name});
+  } catch (e) {
+    return 'Error: ' + e.message;
+  }
+})()
+```
+
+## Best Practices Summary
+
+1. **Never use `return` at top level** - use expression evaluation instead
+2. **Never use `require()`** - use global `dw.*` namespace
+3. **Wrap complex logic in IIFEs** for variable declarations
+4. **Use `JSON.stringify()`** for object/array output
+5. **Close iterators** after use (OrderMgr.searchOrders, etc.)
+6. **Check for null** before accessing properties
+7. **Verify API usage** with `get_sfcc_class_info` tool before calling unknown methods
+
+## Common Patterns
+
+### Quick Value Check
+
+```javascript
+dw.system.Site.current.ID
+```
+
+### Multi-Value Query
+
+```javascript
+JSON.stringify({
+  siteId: dw.system.Site.current.ID,
+  locale: request.locale,
+  customerList: dw.customer.CustomerMgr.getSiteCustomerList().ID
+})
+```
+
+### Complex Data Retrieval
+
+```javascript
+(function() {
+  // Your multi-step logic here
+  var result = [];
+  // ... build result ...
+  return JSON.stringify(result);
+})()
+```
+
+## Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `invalid return` | Using `return` at top level | Remove `return`, use expression or IIFE |
+| `Cannot call method of null` | Using `require()` | Use `dw.*` global namespace |
+| `Cannot set property of null` | `var x = {}` returns null | Use IIFE or inline object literal |
+| `Timeout waiting for breakpoint` | Wrong siteId or instance unreachable | Verify siteId, check instance connectivity |
+| `Unexpected token '<'` | Auth/connectivity issue | Check dw.json credentials, verify instance is accessible |
+| `Unauthorized` / `401` | Username case mismatch | **Username is case-sensitive** - match exactly from BM user |
+| `No compatible storefront cartridge` | Missing SFRA or SiteGenesis | Deploy app_storefront_base or specify custom breakpoint |
+
+## Pre-Flight Checklist
+
+Before using `evaluate_script`:
+
+1. ✅ Valid credentials in dw.json configuration
+2. ✅ **Username matches BM user exactly (case-sensitive!)**
+3. ✅ Sandbox instance is accessible
+4. ✅ Storefront cartridge deployed (app_storefront_base or app_storefront_controllers)
+5. ✅ Script uses `dw.*` namespace, not `require()`
+6. ✅ Complex logic wrapped in IIFE
+7. ✅ Objects/arrays wrapped in `JSON.stringify()`
+
+## Requirements
+
+- SFCC sandbox instance
+- Either `app_storefront_base` (SFRA) or `app_storefront_controllers` (SiteGenesis) deployed
+- Valid credentials in dw.json configuration
+- **Important:** Username in dw.json must match BM user exactly (case-sensitive)

package/{docs/best-practices/security.md → ai-instructions/skills/sfcc-security/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: sfcc-security
+description: Secure coding best practices for Salesforce B2C Commerce Cloud including CSRF protection, authentication, authorization, cryptography, and secrets management. Use when asked about SFCC security, input validation, or secure coding patterns.
+---
+
 # Salesforce B2C Commerce Cloud: Secure Coding Best Practices
 
 This document provides a concise guide to security best practices for Salesforce B2C Commerce Cloud development, focusing on SFRA Controllers, OCAPI/SCAPI Hooks, and Custom SCAPI Endpoints.
@@ -57,7 +62,7 @@ server.post('UpdateProfile', userLoggedIn.validateLoggedIn, function (req, res,
 
 module.exports = server.exports();
 
-````
+```
 
 ### Cross-Site Request Forgery (CSRF) Protection
 
@@ -72,7 +77,7 @@ Use the `csrfProtection` middleware for any state-changing POST request. [12, 13
     <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
     <button type="submit">Save</button>
 </form>
-````
+```
 
 ```javascript
 // In your controller
@@ -146,7 +151,7 @@ server.get('AccountWidget',
 );
 ```
 
-NEVER put `userLoggedIn.validateLoggedIn` before `server.middleware.include` – bots probing the route directly would still trigger authentication logic (unnecessary overhead) and you’d miss the explicit architectural contract.
+NEVER put `userLoggedIn.validateLoggedIn` before `server.middleware.include` – bots probing the route directly would still trigger authentication logic (unnecessary overhead) and you'd miss the explicit architectural contract.
 
 #### Identifying Remote Include Requests
 `req.includeRequest === true` inside the controller. Log defensively:
@@ -383,3 +388,7 @@ var encryptedBase64 = aesGcmCipher.encrypt(plainText, base64Key, 'AES/GCM/NoPadd
 - **Unique IVs**: Always generate a unique, random IV for each encryption operation. Never reuse IVs with the same key.
 
 - **Avoid Weak Classes**: Never use WeakCipher, WeakMac, WeakMessageDigest, or any other deprecated cryptographic classes.
+
+## Related Skills
+
+- **[sfcc-logging](../sfcc-logging/SKILL.md)** - Logging best practices including avoiding sensitive data in logs. Essential for security auditing and incident forensics.