sfcc-dev-mcp 1.0.16 → 1.0.20

package/ai-instructions/skills/sfcc-caching/SKILL.md

@@ -1,89 +0,0 @@
----
-name: sfcc-caching
-description: Unified caching playbook for SFCC (page cache vs custom cache vs service response cache). Use this when improving performance, reducing external calls, designing cache keys/TTLs, or debugging stale cache behavior.
----
-
-# SFCC Caching (Unified Playbook)
-
-Caching in SFCC has multiple layers. The most common failures come from:
-- choosing the wrong cache layer
-- unsafe population patterns
-- invalidation assumptions (multi-node)
-- caching the wrong data types (heavy API objects)
-
-## Quick Checklist
-
-```text
-[ ] Choose cache layer: page cache (HTML) vs custom cache (data) vs service response cache
-[ ] Design keys with site + locale scoping where needed
-[ ] Use atomic get-or-load patterns (avoid double loaders)
-[ ] Cache POJOs/DTOs, not dw.* API objects
-[ ] Treat cache values as immutable snapshots; re-put updated copies
-[ ] Design around TTL, not cross-node invalidation
-[ ] Monitor hit ratios and write failures in Business Manager
-```
-
-## Cache Layers (Pick the Right Tool)
-
-| Layer | What it caches | When to use |
-|---|---|---|
-| Page cache | Rendered responses / fragments | High-traffic pages where output can be cached |
-| Custom cache (`CacheMgr`) | Application data | Expensive computations, repeated DB lookups, third-party responses |
-| Service response cache | HTTP responses inside service framework | Repeated calls to stable third-party APIs |
-
-## Scope: request vs session vs CacheMgr
-
-- `request.custom`: per-request scratchpad
-- `session.custom` / `session.privacy`: per-user, per-session data (keep small)
-- `CacheMgr`: app-server local cache shared by users on the same node
-
-Never store user-specific data in a global custom cache.
-
-## Custom Cache Mechanics (Non-Negotiable Rules)
-
-### 1) Define caches in `caches.json` and register in cartridge `package.json`
-- Cache IDs must be globally unique across the cartridge path.
-- The `package.json` that declares `"caches"` must live in the cartridge root (cartridges/{{mycartridge}}/package.json), and the `caches.json` path is relative to that.
-
-### 2) Use atomic “get-or-load”
-Prefer `cache.get(key, loader)` (single step). Avoid:
-- `if (!cache.get(key)) cache.put(key, load())`
-
-### 3) Cache POJOs, not API objects
-Don’t cache `dw.catalog.Product`, `dw.order.Order`, etc.
-Map to a lightweight object with only the fields you need.
-
-### 4) Treat cached values as immutable
-Values returned by `cache.get` are immutable copies. Do not mutate them in-place.
-If you need to update cached data, write a new object back with `cache.put(key, newValue)`.
-
-### 5) TTL over invalidation
-Per-key invalidation across all nodes is unreliable.
-Design for a small staleness window using `expireAfterSeconds`.
-
-### 6) Watch size limits and monitoring
-- Large entries can fail to store without throwing exceptions.
-- Use Business Manager stats (hit ratio, write failures) to validate effectiveness.
-
-## Service Response Caching (LocalServiceRegistry)
-
-If your third-party data is stable for short periods:
-- Enable response caching on the underlying HTTP client in the service definition
-- Ensure you understand how to clear it (BM invalidation is typically global)
-
-Key warnings:
-- stale data risk
-- debugging surprises (you may not hit the network)
-- cached calls can still affect service stats / circuit breakers
-
-## References
-- Rhino Inquisitor: Field Guide to Custom Caches
-  - https://www.rhino-inquisitor.com/field-guide-to-custom-caches-in-sfcc/
-- Rhino Inquisitor: Third-Party API Caching in Commerce Cloud
-  - https://www.rhino-inquisitor.com/third-party-api-caching-in-commerce-cloud/
-- SFCC Docs: Custom Caches
-  - https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html
-- SFCC Script API: `dw.system.Cache` (immutable copies + value constraints)
-  - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Cache.html
-- SFCC Script API: `dw.system.CacheMgr` (cartridge `package.json` cache registration)
-  - https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_CacheMgr.html

package/ai-instructions/skills/sfcc-cartridge-development/SKILL.md

@@ -1,240 +0,0 @@
----
-name: sfcc-cartridge-development
-description: Guide for creating, configuring, and deploying custom SFRA cartridges in Salesforce B2C Commerce. Use this when asked to create a new cartridge, set up a cartridge structure, or work with cartridge paths.
----
-
-# Instructions for Creating a Salesforce B2C Commerce (SFRA) Cartridge
-
-This document provides instructions to create, configure, and deploy a new custom cartridge for Salesforce B2C Commerce using the Storefront Reference Architecture (SFRA).
-
-**NOTE**: When doing this, also consult the **sfcc-sfra-controllers** skill for controller development patterns and the **sfcc-performance** skill to ensure your cartridge follows performance optimization strategies and coding standards.
-
-## 1. Core Principles
-
-**Cartridge:** A cartridge is a self-contained module for code and data. It is the fundamental unit for extending functionality.
-
-**Cartridge Path:** A colon-separated list of cartridge names that dictates the order of code execution. The path is searched from left to right, and the first resource found is used.
-
-**Override Mechanism:** To customize functionality, create a new cartridge (e.g., app_custom_mybrand) and place it at the beginning of the cartridge path. This allows your custom files to override the base functionality without modifying the core app_storefront_base cartridge.
-
-**Example Path:** `app_custom_mybrand:app_storefront_base`
-
-## 2. Prerequisites
-
-- **Git Client:** Installed and configured.
-- **Node.js:** Version 18 is recommended for compatibility.
-- **SFCC Sandbox:** Access to a sandbox instance, including Business Manager credentials.
-- **GitHub Access:** Ability to clone SalesforceCommerceCloud repositories.
-
-## 3. Environment Setup
-
-Create a parent project directory.
-
-Clone the following repositories as siblings inside the parent directory:
-
-Note: This step is not necessary unless specifically asked for. You should only clone these if the user requests it, for most
-projects, there is only a need for the new cartridge that is being built - but not the entire storefront reference architecture.
-
-```bash
-# Contains the base cartridge (app_storefront_base)
-git clone git@github.com:SalesforceCommerceCloud/storefront-reference-architecture.git
-
-# Contains build and deployment scripts
-git clone git@github.com:SalesforceCommerceCloud/sgmf-scripts.git
-```
-
-Install dependencies:
-
-```bash
-cd storefront-reference-architecture
-npm install
-```
-
-## 4. Cartridge File Structure
-
-A new cartridge should be created using the provided scaffolding tool. The core structure is as follows:
-
-```
-package.json
-.eslintrc.json
-.eslintignore
-.stylelintrc.json
-.gitignore
-README.md
-dw.json    
-webpack.config.js           
-cartridges/
-└── plugin_my_custom_cartridge/
-    |── package.json
-    └── cartridge/
-        ├── client/             
-        │   └── default/
-        │       ├── js/
-        │       └── scss/
-        ├── controllers/        
-        ├── models/             
-        ├── scripts/            
-        └── templates/       
-            └── default/
-```
-
-Optional but common directories:
-
-- `cartridge/forms/default/`: XML form definitions.
-- `cartridge/services/`: Definitions for external web service integrations.
-- `cartridge/scripts/jobs/`: Scripts for automated tasks scheduled in Business Manager.
-- `cartridge/properties/`: Localization string files (.properties).
-
-## 4.1 Cartridge `package.json` Capabilities (Often Missed)
-
-Beyond basic metadata, `package.json` can declare cartridge-owned configuration files that the platform consumes.
-  The `package.json` must be in the cartridge root (cartridges/{{mycartridge}}/package.json), and paths are relative to that.
-
-- **Hooks**: add a `hooks` entry pointing to your `hooks.json` (commonly under `cartridge/scripts/hooks.json`).
-- **Custom Caches**: add a `caches` entry pointing to `caches.json` so `CacheMgr.getCache('<id>')` can resolve your cache.
-- **Custom SCAPI APIs**: custom endpoints live under `cartridge/rest-apis/{api-name}/` (with `schema.yaml`, `script.js`, `api.json`).
-
-Example snippet:
-
-```json
-{
-    "name": "plugin_my_custom_cartridge",
-    "hooks": "./cartridge/scripts/hooks.json",
-    "caches": "./caches.json"
-}
-```
-
-## 5. Creating a New Cartridge
-
-### Step 1: Generate the Cartridge Structure
-
-!IMPORTANT!: Always do this step, don't attempt to create the cartridge structure manually. The MCP server ensures all necessary files and configurations are created correctly.
-
-**Using MCP Server (Recommended)**
-Use the `generate_cartridge_structure` tool from the sfcc-dev-mcp server to automatically create the cartridge structure:
-
-```json
-{
-  "cartridgeName": "plugin_my_custom_cartridge",
-  "targetPath": "/path/to/your/project",
-  "fullProjectSetup": true
-}
-```
-
-This tool will:
-- Create all necessary configuration files (package.json, webpack.config.js, etc.)
-- Set up the complete cartridge structure with proper organization
-- Ensure the cartridge is created exactly where needed in your project structure
-- Generate all required directories and files for a fully functional cartridge
-
-## 6. "Hello, World" Example
-
-### Step 1: Navigate to Your Project
-
-After creating the cartridge structure, navigate to your project directory:
-
-```bash
-# If you kept the subdirectory structure:
-cd plugin_my_custom_cartridge
-
-# If you moved files to root level, you're already in the right place
-```
-
-### Step 2: Create the Controller
-
-**File:** `cartridges/plugin_my_custom_cartridge/cartridge/controllers/Hello.js`
-
-```javascript
-'use strict';
-
-var server = require('server');
-
-// URL: /Hello-Show
-server.get('Show', function (req, res, next) {
-    res.render('hello/helloTemplate', {
-        message: 'Hello from a custom cartridge!'
-    });
-    next();
-});
-
-module.exports = server.exports();
-```
-
-### Step 3: Create the ISML Template
-
-**File:** `cartridges/plugin_my_custom_cartridge/cartridge/templates/default/hello/helloTemplate.isml`
-
-```html
-<iscontent type="text/html" charset="UTF-8" compact="true"/>
-<isdecorate template="common/layout/page">
-    <isreplace name="main">
-        <div class="container">
-            <h1>Custom Page</h1>
-            <p>${pdict.message}</p>
-        </div>
-    </isreplace>
-</isdecorate>
-```
-
-### Step 4: Update Deployment Configuration
-
-Ensure your `dw.json` file has the correct sandbox credentials (this file is automatically generated but needs your specific sandbox details).
-
-## 7. Deployment and Registration
-
-### Step 1: Upload the Cartridge
-
-From the project root, run:
-
-```bash
-npm run uploadCartridge plugin_my_custom_cartridge
-```
-
-For continuous development, use `npm run watch`.
-
-## 8. Naming Conventions & Best Practices
-
-**Cartridge Naming:** Use standard prefixes.
-
-- `app_custom_*`: Site-specific customizations.
-- `int_*`: Third-party integrations.
-- `bm_*`: Business Manager extensions.
-- `plugin_*`: Reusable SFRA feature extensions.
-
-**File Naming:** Controllers use PascalCase.js. Other JS files use camelCase.js.
-
-**NEVER modify app_storefront_base or other base/plugin cartridges directly.**
-
-**Extend, Don't Replace:** Use server.append() or server.prepend() to extend controllers. Avoid server.replace().
-
-**Logic-less Templates:** Keep business logic out of ISML files. Use models to prepare data.
-
-**Security:** Protect all state-changing POST requests with CSRF tokens. Properly encode all user-provided output to prevent XSS.
-
-**Localization:** Use Resource.msg() in templates to fetch text from .properties files.
-
-## 9. MCP Integration Workflow
-
-When using the sfcc-dev-mcp server for cartridge development, follow this enhanced workflow:
-
-1. **Generate Cartridge Structure**: Use the `generate_cartridge_structure` tool to create the initial cartridge with all necessary files and configurations
-2. **Consult Skills**: Use the relevant skills for controller development patterns (sfcc-sfra-controllers), security (sfcc-security), and performance (sfcc-performance)
-3. **Search Documentation**: Use `search_sfcc_classes` and `get_sfcc_class_info` for API reference
-4. **Debug Issues**: Use log analysis tools to troubleshoot deployment or runtime issues
-5. **Handle Deployment Issues**: If new cartridge features (jobs, SCAPI endpoints, hooks) don't appear after upload:
-   - **Check Code Versions**: Use `get_code_versions` tool to see available versions
-   - **Activate Version**: Use `activate_code_version` tool to ensure proper registration
-   - **Alternative**: Manually switch code versions in Business Manager (Administration > Site Development > Code Deployment)
-
-### Common Deployment Troubleshooting
-
-**Issue**: Custom jobs or SCAPI endpoints not visible after cartridge deployment
-**Solution**: 
-1. Use MCP `get_code_versions` tool to check available code versions
-2. Use MCP `activate_code_version` tool to switch to the uploaded version
-3. Verify registration in logs using log analysis tools
-
-**Issue**: Hooks not taking effect after deployment
-**Solution**: Follow the same code version activation process above
-
-This integrated approach ensures your cartridge follows all best practices and leverages the full power of the SFCC development ecosystem with direct file generation capabilities.

package/ai-instructions/skills/sfcc-forms-development/SKILL.md

@@ -1,261 +0,0 @@
----
-name: sfcc-forms-development
-description: Guide for building, validating, securing, and persisting SFCC storefront forms (SFRA + SiteGenesis patterns). Use this when creating or troubleshooting form XML, controller handling, CSRF, and validation.
----
-
-# SFCC Forms Development Skill
-
-This skill guides you through implementing and troubleshooting the Salesforce B2C Commerce Forms Framework.
-
-It covers:
-- XML form definitions (schema, constraints, localization, reuse)
-- Controller patterns (SFRA middleware, request handling, persistence)
-- Secure validation (server-side first, CSRF/XSS protections)
-- Migration guidance (SiteGenesis ➜ SFRA)
-
-## When to Use
-
-Use this skill when you need to:
-- Create or modify a form definition in `cartridge/forms/**`.
-- Render forms in ISML using the platform’s generated field metadata.
-- Process POST submissions safely (CSRF, server-side validation, transactions).
-- Add custom validation beyond XML constraints.
-- Migrate legacy SiteGenesis form flows to SFRA.
-
-## Quick Checklist (Production-Grade Forms)
-
-```text
-[ ] Form routes are POST-only and HTTPS-only
-[ ] CSRF token is generated on GET and validated on POST
-[ ] Server-side validation gate exists (do not trust client validation)
-[ ] All string fields have max-length (DoS & storage safety)
-[ ] Regex is conservative (avoid catastrophic backtracking)
-[ ] Persistence happens inside Transaction.wrap
-[ ] SFRA persistence is isolated in route:BeforeComplete where appropriate
-[ ] Explicit mapping for writes (avoid mass assignment)
-[ ] Form state cleared when appropriate (pre-render or after success)
-[ ] User-provided values are output-encoded in ISML
-```
-
-## File Locations
-
-### Form XML
-
-Forms are defined per cartridge:
-
-```
-/my-cartridge
-  /cartridge
-    /forms
-      /default
-        profile.xml
-        contact.xml
-      /de_DE
-        profile.xml
-```
-
-### Form Labels + Error Messages (Localization)
-
-Resource bundles typically live in:
-
-```
-/my-cartridge
-  /cartridge
-    /templates
-      /resources
-        forms.properties
-        forms_de_DE.properties
-```
-
-## Architecture Notes (Know the Moving Parts)
-
-- Form XML is a strict server-side contract: it defines types, constraints, and errors.
-- Form instances are stored in session scope (stateful across requests) and must be cleared deliberately.
-- Client-side validation is UX; server-side validation is authoritative.
-
-For deeper context and SFRA vs SiteGenesis architectural differences, see:
-- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)
-
-## Form Definition (XML)
-
-### Minimal Example
-
-Keep examples small, but always include:
-- strict types
-- max-length for strings
-- mandatory + missing-error where needed
-- parse/range errors for format/constraint enforcement
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
-    <field formid="email" type="string"
-           label="form.email.label"
-           mandatory="true"
-           max-length="254"
-           regexp="^[^@\s]+@[^@\s]+\.[^@\s]+$"
-           missing-error="form.email.required"
-           parse-error="form.email.invalid"/>
-
-    <action formid="submit" valid-form="true"/>
-</form>
-```
-
-### Reuse and Modularity
-
-Prefer `include` to avoid duplicating complex groups (e.g., an address group reused in checkout, profile, and gift registry).
-
-See the cheat sheet:
-- [references/FORM-XML-CHEATSHEET.md](references/FORM-XML-CHEATSHEET.md)
-
-## Controller Patterns
-
-### SFRA: Render Form (GET)
-
-Goals:
-- clear stale state when rendering an “empty” form
-- generate a CSRF token
-
-```javascript
-'use strict';
-
-var server = require('server');
-var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
-
-server.get('Show',
-    server.middleware.https,
-    csrfProtection.generateToken,
-    function (req, res, next) {
-        var form = server.forms.getForm('contact');
-        form.clear();
-
-        res.render('forms/contact', {
-            contactForm: form
-        });
-        next();
-    }
-);
-
-module.exports = server.exports();
-```
-
-### SFRA: Handle Submission (POST)
-
-Goals:
-- validate CSRF first
-- gate all business logic on `form.valid`
-- isolate DB writes inside `Transaction.wrap`
-- prefer `route:BeforeComplete` for persistence to keep transaction boundaries tight
-
-```javascript
-'use strict';
-
-var server = require('server');
-var Transaction = require('dw/system/Transaction');
-var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
-
-server.post('Submit',
-    server.middleware.https,
-    csrfProtection.validateRequest,
-    function (req, res, next) {
-        var form = server.forms.getForm('contact');
-
-        if (!form.valid) {
-            // SFRA base commonly provides a helper like */cartridge/scripts/formErrors.
-            // Prefer using it when available.
-            res.json({
-                success: false,
-                fieldErrors: getFormErrorsSafe(form)
-            });
-            return next();
-        }
-
-        var email = form.email.value;
-        var message = form.message && form.message.value;
-
-        this.on('route:BeforeComplete', function () {
-            Transaction.wrap(function () {
-                // Persist explicitly (no mass assignment)
-                // e.g. save a Custom Object, update profile, create a case, etc.
-                // Keep only assignments inside the transaction.
-            });
-
-            form.clear();
-        });
-
-        res.json({ success: true });
-        next();
-    }
-);
-
-function getFormErrorsSafe(form) {
-    try {
-        var formErrors = require('*/cartridge/scripts/formErrors');
-        if (formErrors && typeof formErrors.getFormErrors === 'function') {
-            return formErrors.getFormErrors(form);
-        }
-    } catch (e) {
-        // Optional dependency; fall back if not present.
-    }
-    return {};
-}
-
-module.exports = server.exports();
-```
-
-Notes:
-- Use `csrfProtection.validateAjaxRequest` if your route expects AJAX conventions.
-- Keep transactions short: no remote API calls, no heavy computation inside `Transaction.wrap`.
-
-### SiteGenesis (SGJC): Key Differences
-
-- Form is typically accessed via `app.getForm('id')` and rendered via `pdict.CurrentForms`.
-- Templates must use generated `htmlName` (SiteGenesis uses `dwfrm_` prefixes + session-specific IDs).
-- CSRF is often handled manually via `dw.web.CSRFProtection`.
-
-Use this for migration and pitfalls:
-- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)
-
-## ISML Rendering Rules
-
-### Always Use Generated Field Metadata
-
-- Prefer `field.htmlName` over hardcoded names.
-- Use server-provided `pdict.csrf.*` when using SFRA CSRF middleware.
-
-Typical SFRA token:
-
-```html
-<input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}" />
-```
-
-### XSS Safety
-
-When outputting user-provided values, ensure the context is encoded (default output encoding is usually safe, but be deliberate):
-
-```html
-<isprint value="${pdict.contactForm.email.value}" encoding="htmlcontent" />
-```
-
-## Custom Validation
-
-Use custom validation for business rules that XML cannot express (uniqueness checks, cross-field constraints, etc.).
-
-Patterns:
-- Field-level: invalidate a specific field.
-- Group-level: invalidate the group for cross-field rules.
-- Form-level: invalidate the form for global errors.
-
-Keep custom validation server-side. Client-side validation is optional and must never be the security gate.
-
-## Related Skills
-
-- `sfcc-security` (CSRF, XSS, input validation)
-- `sfcc-sfra-controllers` (middleware patterns, response handling)
-- `sfcc-isml-development` (safe output encoding, template constraints)
-- `sfcc-localization` (resource bundles, locale fallback)
-
-## References
-
-- [references/FORM-XML-CHEATSHEET.md](references/FORM-XML-CHEATSHEET.md)
-- [references/ARCHITECTURE-SGJC-SFRA.md](references/ARCHITECTURE-SGJC-SFRA.md)