sfcc-dev-mcp 1.0.19 → 1.0.21

package/ai-instructions/skills/sfcc-sfra-client-side-js/references/PLUGIN-PATTERNS.md

@@ -1,185 +0,0 @@
-# Plugin Cartridge Patterns & Anti-Patterns
-
-Analysis of real patterns from plugin cartridges with concrete guidance for creating maintainable, secure, and accessible client-side code.
-
-## Observed Anti-Patterns & Risks
-
-| Category | Issue | Why It Matters | Recommended Fix |
-|----------|-------|----------------|-----------------|
-| Message UI | Repeated ad-hoc containers: `$('body').append('<div class="messages"></div>')` | Duplicated logic, memory churn, inconsistent roles, XSS risk | Centralize via `toastService.show(type, message)` with single managed region |
-| String HTML | Concatenating user data into HTML | XSS vulnerability if data not sanitized | Use `escapeHtml()` or build DOM with jQuery `.text()` |
-| Oversized Module | Single file ~600 lines exporting giant object | Hard to test, cognitive overload, hidden coupling | Split by concern into focused modules |
-| Global Delegation | Universal `$('body').on('click', '.selector', ...)` | Higher event dispatch cost; collision risk | Delegate from closest stable container |
-| No Event Namespaces | Triggers without namespaces | Difficult selective unbinding, collision risk | Use `$('...').on('click.wishlistRemove', ...)` |
-| Unscoped Spinners | `$.spinner().start()` without container scoping | Flicker, race conditions | Use `$container.spinner().start()` with `try/finally` |
-| Manual Modal Assembly | String concatenation for full modal markup | Drift vs. base styles, missing a11y attributes | Provide reusable `createModalShell()` helper |
-| Clipboard | Direct `navigator.clipboard.writeText` | Fails silently on insecure origins | Add feature detect & fallback |
-| Uncached Selectors | Repeated `$('.class')` inside loops | Performance waste | Cache at module scope before loops |
-| Icon Toggle | Direct class swap without state semantics | No accessibility state conveyed | Add `aria-pressed` or `aria-label` update |
-| Error Handling | Passing entire `err` object expecting `{success,msg}` | `undefined` outputs; user confusion | Normalize with `extractMessage(xhr)` utility |
-
-## Improved Architecture
-
-Break monolithic modules by concern:
-
-```javascript
-// wishlist/index.js (page orchestrator)
-'use strict';
-var initModal = require('./modal');
-var initPublicStatus = require('./publicStatus');
-var initItems = require('./items');
-var initSearch = require('./search');
-var toast = require('./toast');
-
-module.exports = function () {
-    toast.init();
-    initModal();
-    initPublicStatus();
-    initItems();
-    initSearch();
-};
-```
-
-## Central Toast Service
-
-```javascript
-// utils/toast.js
-'use strict';
-var REGION_SELECTOR = '#global-toast-region';
-
-function ensureRegion() {
-    if (!$(REGION_SELECTOR).length) {
-        $('body').append(
-            '<div id="global-toast-region" class="toast-region" ' +
-            'aria-live="polite" aria-atomic="true"></div>'
-        );
-    }
-}
-
-function escapeHtml(str) {
-    return String(str)
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
-function show(type, message, opts) {
-    ensureRegion();
-    var safe = escapeHtml(message);
-    var $r = $(REGION_SELECTOR);
-    var $toast = $('<div class="alert alert-' + (type || 'info') + '" role="alert"></div>')
-        .html(safe);
-    $r.append($toast);
-    
-    setTimeout(function () { 
-        $toast.fadeOut(150, function () { $(this).remove(); }); 
-    }, (opts && opts.duration) || 3000);
-}
-
-module.exports = { init: ensureRegion, show: show };
-```
-
-Usage:
-```javascript
-var toast = require('./toast');
-toast.show(data.success ? 'success' : 'danger', data.msg);
-```
-
-## Namespaced Events & Scoped Delegation
-
-```javascript
-// Instead of $('body').on('click', '.remove-item', handler)
-$('.wishlist-container').on('click.wishlistRemove', '.remove-item', handler);
-
-// Add cleanup
-function destroy() { 
-    $('.wishlist-container').off('.wishlistRemove'); 
-}
-```
-
-## AJAX Utility Wrapper
-
-```javascript
-// utils/ajax.js
-module.exports = function request(opts) {
-    var d = $.Deferred();
-    
-    $.ajax(opts)
-        .done(d.resolve)
-        .fail(function (xhr) {
-            var msg = (xhr.responseJSON && (xhr.responseJSON.msg || xhr.responseJSON.message)) 
-                      || 'Unexpected error';
-            d.reject({ success: false, msg: msg });
-        });
-    
-    return d.promise();
-};
-```
-
-## Safer Dynamic List Rendering
-
-```javascript
-function renderHits(hits) {
-    var html = hits.map(function (h) {
-        var name = escapeHtml(h.firstName + ' ' + h.lastName);
-        var urlText = escapeHtml(h.urlText);
-        
-        return '<div class="row hit">' +
-            '<div class="col-6">' + name + '</div>' +
-            '<div class="col-6">' +
-            '<a href="' + h.url + '" ' +
-            'title="' + escapeHtml(h.urlTitle) + '" ' +
-            'data-id="' + h.id + '">' + urlText + '</a>' +
-            '</div></div>';
-    }).join('');
-    
-    $('.hits-container').html(html);
-}
-```
-
-## Accessibility Enhancements
-
-| Pattern | Upgrade |
-|---------|---------|
-| Heart toggle icon changes class only | Add `aria-pressed` state + label update |
-| Toasts missing live region | Use single `aria-live="polite"` container |
-| Modal close sets focus implicitly | Explicitly return focus to invoking control |
-| Copy link success only visual | Append visually-hidden status text for screen readers |
-
-## Performance & Maintainability Payoffs
-
-| Refactor | Benefit |
-|----------|---------|
-| Split mega file into 6 modules | Lower merge conflict risk; targeted test surfaces |
-| Central toast service | One place for styling, timing, a11y |
-| Namespaced events | Predictable teardown preventing memory leaks |
-| Escaping utility | Mitigates XSS across all dynamic insertions |
-| AJAX wrapper | Consistent error contract for UI handlers |
-
-## Code Review Checklist
-
-Before finalizing a new client feature:
-
-1. Does any module exceed ~200 LOC? If yes, split
-2. Are all dynamic string insertions encoded? (Search for `+` around user data)
-3. Do events have namespaces for teardown? (Search: `.on('[^']+\.`)
-4. Are repeated UX patterns (toast, modal, spinner) abstracted?
-5. Are POSTs including CSRF token & handling both transport + business errors?
-6. Is there at least one accessibility enhancement (live region, focus management, ARIA state)?
-
-## Escaping Utility
-
-```javascript
-function escapeHtml(str) {
-    return String(str)
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-```
-
-Always use when inserting: query params, form input values, server-returned text fields that originated from users.

package/ai-instructions/skills/sfcc-sfra-controllers/SKILL.md

@@ -1,347 +0,0 @@
----
-name: sfcc-sfra-controllers
-description: Guide for developing SFRA controllers in Salesforce B2C Commerce. Use this when asked to create controllers, extend base functionality, implement middleware chains, handle routing, or customize storefront behavior.
----
-
-# SFRA Controllers Skill
-
-This skill guides you through creating storefront controllers for Salesforce B2C Commerce using the Storefront Reference Architecture (SFRA).
-
-## Overview
-
-Controllers are JavaScript modules that handle storefront requests. A controller URL has this structure:
-
-```
-https://{domain}/on/demandware.store/Sites-{SiteName}-Site/{locale}/{ControllerName}-{FunctionName}
-```
-
-**Example:** `https://example.com/on/demandware.store/Sites-RefArch-Site/en_US/Home-Show`
-
-## MVC Pattern
-
-SFRA uses Model-View-Controller pattern:
-
-- **Controller** (`/controllers`): Handles requests, calls models, determines view
-- **Model** (`/models`): Business logic, returns JSON objects
-- **View** (`/templates`): ISML templates, renders pdict data only
-
-**Cartridge Path**: Custom cartridges must precede `app_storefront_base` to override functionality. Never edit the base cartridge directly.
-
-## File Location
-
-Controllers reside in the cartridge's `controllers` directory:
-
-```
-/my-cartridge
-    /cartridge
-        /controllers
-            Home.js           # URL: Home-{function}
-            Product.js        # URL: Product-{function}
-            Cart.js           # URL: Cart-{function}
-```
-
-## Basic Controller Pattern
-
-```javascript
-'use strict';
-
-var server = require('server');
-
-// Handle GET request
-server.get('Show', function (req, res, next) {
-    res.render('home/homepage');
-    next();
-});
-
-// Handle POST request
-server.post('Subscribe', function (req, res, next) {
-    var email = req.form.email;
-    res.json({ success: true });
-    next();
-});
-
-module.exports = server.exports();
-```
-
-## Request & Response Objects
-
-### Request (req)
-
-```javascript
-req.querystring          // Query parameters: ?q=shoes -> req.querystring.q
-req.form                 // Form POST data: req.form.email
-req.httpMethod           // HTTP method: 'GET', 'POST', etc.
-req.httpHeaders          // Request headers
-req.currentCustomer      // Current customer object
-req.locale               // Current locale
-req.session              // Session object
-```
-
-### Response (res)
-
-```javascript
-res.render('template', model)   // Render ISML template with data
-res.json(object)                // Return JSON response
-res.redirect(url)               // Redirect to URL
-res.setViewData(data)           // Add data to view model
-res.getViewData()               // Get current view model
-res.setStatusCode(code)         // Set HTTP status code
-res.cacheExpiration(hours)      // Set cache duration
-```
-
-## Middleware Chain
-
-Each route is a series of functions with `(req, res, next)`:
-
-```javascript
-server.get('Show', 
-    middleware1,
-    middleware2,
-    function (req, res, next) {
-        // Main handler
-        next();
-    }
-);
-```
-
-**Critical**: Always call `next()` to pass control, unless terminating the request.
-
-### Common Built-in Middleware
-
-| Middleware | Purpose |
-|------------|---------|
-| `server.middleware.https` | Require HTTPS connection |
-| `server.middleware.include` | Mark as remote include only |
-| `cache.applyDefaultCache` | Apply 24-hour page caching |
-| `csrfProtection.generateToken` | Generate CSRF token |
-| `csrfProtection.validateRequest` | Validate CSRF for POST |
-| `userLoggedIn.validateLoggedIn` | Require authenticated user |
-| `consentTracking.consent` | Check tracking consent |
-
-## Controller Extension
-
-Customize without modifying base code. Always import base first:
-
-```javascript
-'use strict';
-var server = require('server');
-var page = module.superModule; // Get base controller
-server.extend(page);
-```
-
-### Extension Methods
-
-| Method | Use Case |
-|--------|----------|
-| `server.append()` | Add/modify data after base logic (most common) |
-| `server.prepend()` | Run validation before base logic |
-| `server.replace()` | Completely replace route behavior |
-
-### Append Example (Most Common)
-
-```javascript
-server.append('Show', function (req, res, next) {
-    var viewData = res.getViewData();
-    viewData.customData = 'My custom value';
-    res.setViewData(viewData);
-    next();
-});
-
-module.exports = server.exports();
-```
-
-### Replace Example (State-Changing Actions)
-
-```javascript
-// Use replace for payment, inventory updates, etc.
-server.replace('Submit', function (req, res, next) {
-    // Custom implementation
-    res.json({ success: true });
-    next();
-});
-```
-
-**Critical**: Never use `append` for state-changing routes (payments, inventory). Use `replace` to prevent duplicate transactions.
-
-## CSRF Protection
-
-```javascript
-var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
-
-// Display form - generates token automatically
-server.get('ShowForm', csrfProtection.generateToken, function (req, res, next) {
-    res.render('myForm', { pageTitle: 'Contact' });
-    // pdict.csrf.tokenName and pdict.csrf.token auto-available
-    next();
-});
-
-// Process form - validates token
-server.post('Submit', csrfProtection.validateRequest, function (req, res, next) {
-    // Token validated, safe to process
-    next();
-});
-```
-
-**Important**: Middleware automatically adds CSRF to pdict. Never manually add tokens to viewData.
-
-Template usage:
-```html
-<input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
-```
-
-## Error Handling
-
-```javascript
-server.get('Show', function (req, res, next) {
-    try {
-        var product = ProductMgr.getProduct(req.querystring.pid);
-        
-        if (!product) {
-            res.setStatusCode(404);
-            res.render('error/notfound');
-            return next();
-        }
-        
-        res.render('product/detail', { product: product });
-    } catch (e) {
-        Logger.error('Product error: ' + e.message);
-        res.setStatusCode(500);
-        res.render('error/general');
-    }
-    next();
-});
-```
-
-## Module Imports
-
-```javascript
-// B2C Commerce APIs
-var ProductMgr = require('dw/catalog/ProductMgr');
-var Transaction = require('dw/system/Transaction');
-var Logger = require('dw/system/Logger');
-var URLUtils = require('dw/web/URLUtils');
-
-// Cartridge modules (use */ for path resolution)
-var collections = require('*/cartridge/scripts/util/collections');
-var productHelper = require('*/cartridge/scripts/helpers/productHelpers');
-```
-
-**Best Practice**: Require modules inside route functions, not at file top.
-
-## URL Generation
-
-```javascript
-var URLUtils = require('dw/web/URLUtils');
-
-// Controller URL
-var productUrl = URLUtils.url('Product-Show', 'pid', 'ABC123');
-
-// HTTPS URL
-var loginUrl = URLUtils.https('Login-Show');
-
-// Static resource URL
-var imageUrl = URLUtils.staticURL('/images/logo.png');
-```
-
-## Route Events
-
-Execute code at specific points in request lifecycle:
-
-```javascript
-server.get('Show', function (req, res, next) {
-    res.setViewData({ email: req.form.email });
-    next();
-});
-
-// Execute after all middleware, before render
-this.on('route:BeforeComplete', function (req, res) {
-    var viewData = res.getViewData();
-    // Modify view data if needed
-});
-```
-
-## JSON API Endpoints
-
-```javascript
-server.get('GetCart', function (req, res, next) {
-    var BasketMgr = require('dw/order/BasketMgr');
-    var CartModel = require('*/cartridge/models/cart');
-    
-    var basket = BasketMgr.getCurrentBasket();
-    var cart = new CartModel(basket);
-    
-    res.json(cart);
-    next();
-});
-```
-
-## Complete Controller Example
-
-```javascript
-'use strict';
-
-var server = require('server');
-var cache = require('*/cartridge/scripts/middleware/cache');
-var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
-var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');
-
-// Public page with caching
-server.get('Show',
-    cache.applyDefaultCache,
-    function (req, res, next) {
-        var ProductMgr = require('dw/catalog/ProductMgr');
-        var product = ProductMgr.getProduct(req.querystring.pid);
-        
-        res.render('product/detail', { product: product });
-        next();
-    }
-);
-
-// Protected form display
-server.get('EditProfile',
-    server.middleware.https,
-    userLoggedIn.validateLoggedIn,
-    csrfProtection.generateToken,
-    function (req, res, next) {
-        res.render('account/editProfile');
-        next();
-    }
-);
-
-// Protected form submission
-server.post('SaveProfile',
-    server.middleware.https,
-    userLoggedIn.validateLoggedIn,
-    csrfProtection.validateRequest,
-    function (req, res, next) {
-        // Process form...
-        res.json({ success: true });
-        next();
-    }
-);
-
-module.exports = server.exports();
-```
-
-## Best Practices
-
-1. **Always call `next()`** in middleware chain
-2. **Use ViewModels** to prepare data for templates
-3. **Keep controllers thin** - move logic to scripts/helpers
-4. **Use hooks** for functionality that works for storefront and OCAPI
-5. **Handle errors gracefully** - never expose stack traces
-6. **Use `*/cartridge/...`** for portable module paths
-7. **Lazy load modules** - require inside functions, not at file top
-8. **Use page caching** via middleware or `res.cacheExpiration()`
-
-## Related Skills
-
-- **[sfcc-localization](../sfcc-localization/SKILL.md)** - Essential for localizing controller responses. Use `Resource.msg()` for all user-facing messages, error strings, and JSON responses. Never hardcode text in controllers.
-- **[sfcc-logging](../sfcc-logging/SKILL.md)** - Comprehensive logging patterns including categories, custom log files, and log level checks for debugging controllers.
-
-## Detailed References
-
-For comprehensive patterns and examples:
-- [Middleware Reference](references/MIDDLEWARE-REFERENCE.md) - Full middleware documentation
-- [Remote Includes](references/REMOTE-INCLUDES.md) - Remote include patterns
-- [Standard SFRA Controllers](references/STANDARD-SFRA-CONTROLLERS.md) - Complete route reference