sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-page-designer/references/META-DEFINITIONS.md

@@ -0,0 +1,322 @@
+# Page Designer Meta Definitions Reference
+
+Complete JSON schema for page types and component types.
+
+## Page Type Schema
+
+```json
+{
+    "name": "Page Type Name",
+    "description": "Description shown in editor",
+    "region_definitions": [
+        {
+            "id": "regionId",
+            "name": "Region Name",
+            "max_components": 5,
+            "component_type_exclusions": [],
+            "component_type_inclusions": []
+        }
+    ]
+}
+```
+
+### Page Type Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | Yes | Display name in editor |
+| `description` | string | No | Description shown when selecting page type |
+| `region_definitions` | array | Yes | List of content regions |
+
+### Region Definition Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Unique identifier (alphanumeric, underscore) |
+| `name` | string | Yes | Display name in editor |
+| `max_components` | integer | No | Maximum components allowed |
+| `component_type_exclusions` | array | No | Components NOT allowed in region |
+| `component_type_inclusions` | array | No | ONLY these components allowed |
+
+## Component Type Schema
+
+```json
+{
+    "name": "Component Name",
+    "description": "Component description",
+    "group": "content",
+    "attribute_definition_groups": [
+        {
+            "id": "groupId",
+            "name": "Group Name",
+            "description": "Group description",
+            "attribute_definitions": [
+                {
+                    "id": "attributeId",
+                    "name": "Attribute Name",
+                    "description": "Help text",
+                    "type": "string",
+                    "required": false,
+                    "default_value": "default"
+                }
+            ]
+        }
+    ],
+    "region_definitions": []
+}
+```
+
+### Component Type Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | Yes | Display name |
+| `description` | string | No | Description in editor |
+| `group` | string | No | Sidebar group (content, products, etc.) |
+| `attribute_definition_groups` | array | Yes | Grouped attribute definitions |
+| `region_definitions` | array | No | Nested regions (for container components) |
+
+### Attribute Definition Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Yes | Attribute identifier |
+| `name` | string | Yes | Display name |
+| `description` | string | No | Help text |
+| `type` | string | Yes | Attribute type |
+| `required` | boolean | No | Whether required (default false) |
+| `default_value` | varies | No | Default value |
+| `values` | array | No | Options for enum type |
+
+## Complete Page Type Example
+
+```json
+{
+    "name": "Product Landing Page",
+    "description": "Landing page for product campaigns with hero, features, and product grid",
+    "region_definitions": [
+        {
+            "id": "hero",
+            "name": "Hero Section",
+            "max_components": 1,
+            "component_type_inclusions": [
+                { "type_id": "hero-banner" },
+                { "type_id": "video-hero" }
+            ]
+        },
+        {
+            "id": "features",
+            "name": "Features Section",
+            "max_components": 4,
+            "component_type_inclusions": [
+                { "type_id": "feature-card" },
+                { "type_id": "icon-block" }
+            ]
+        },
+        {
+            "id": "products",
+            "name": "Product Grid",
+            "max_components": 1,
+            "component_type_inclusions": [
+                { "type_id": "product-grid" },
+                { "type_id": "product-carousel" }
+            ]
+        },
+        {
+            "id": "content",
+            "name": "Additional Content",
+            "component_type_exclusions": [
+                { "type_id": "hero-banner" },
+                { "type_id": "video-hero" }
+            ]
+        },
+        {
+            "id": "cta",
+            "name": "Call to Action",
+            "max_components": 1
+        }
+    ]
+}
+```
+
+## Complete Component Type Example
+
+```json
+{
+    "name": "Product Card",
+    "description": "Display a single product with image, name, price, and add to cart",
+    "group": "products",
+    "attribute_definition_groups": [
+        {
+            "id": "product",
+            "name": "Product Selection",
+            "attribute_definitions": [
+                {
+                    "id": "product",
+                    "name": "Product",
+                    "description": "Select the product to display",
+                    "type": "product",
+                    "required": true
+                }
+            ]
+        },
+        {
+            "id": "display",
+            "name": "Display Options",
+            "attribute_definitions": [
+                {
+                    "id": "showPrice",
+                    "name": "Show Price",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "showRating",
+                    "name": "Show Rating",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "showAddToCart",
+                    "name": "Show Add to Cart Button",
+                    "type": "boolean",
+                    "default_value": true
+                },
+                {
+                    "id": "imageSize",
+                    "name": "Image Size",
+                    "type": "enum",
+                    "values": ["small", "medium", "large"],
+                    "default_value": "medium"
+                }
+            ]
+        },
+        {
+            "id": "style",
+            "name": "Styling",
+            "attribute_definitions": [
+                {
+                    "id": "cardStyle",
+                    "name": "Card Style",
+                    "type": "enum",
+                    "values": ["default", "bordered", "shadow", "minimal"],
+                    "default_value": "default"
+                },
+                {
+                    "id": "backgroundColor",
+                    "name": "Background Color",
+                    "description": "CSS color value (e.g., #ffffff or white)",
+                    "type": "string"
+                }
+            ]
+        }
+    ]
+}
+```
+
+## Container Component Example
+
+Component with nested regions:
+
+```json
+{
+    "name": "Two Column Layout",
+    "description": "Container with two side-by-side columns",
+    "group": "layout",
+    "attribute_definition_groups": [
+        {
+            "id": "layout",
+            "name": "Layout Options",
+            "attribute_definitions": [
+                {
+                    "id": "leftWidth",
+                    "name": "Left Column Width",
+                    "type": "enum",
+                    "values": ["25%", "33%", "50%", "66%", "75%"],
+                    "default_value": "50%"
+                },
+                {
+                    "id": "gap",
+                    "name": "Column Gap",
+                    "type": "enum",
+                    "values": ["none", "small", "medium", "large"],
+                    "default_value": "medium"
+                }
+            ]
+        }
+    ],
+    "region_definitions": [
+        {
+            "id": "left",
+            "name": "Left Column"
+        },
+        {
+            "id": "right",
+            "name": "Right Column"
+        }
+    ]
+}
+```
+
+**Script for container:**
+```javascript
+'use strict';
+
+var Template = require('dw/util/Template');
+var HashMap = require('dw/util/HashMap');
+var PageRenderHelper = require('*/cartridge/experience/utilities/PageRenderHelper');
+
+module.exports.render = function (context) {
+    var model = new HashMap();
+    var component = context.component;
+
+    model.put('leftWidth', context.content.leftWidth || '50%');
+    model.put('gap', context.content.gap || 'medium');
+
+    // Render nested regions
+    model.put('leftRegion', PageRenderHelper.renderRegion(component.getRegion('left')));
+    model.put('rightRegion', PageRenderHelper.renderRegion(component.getRegion('right')));
+
+    return new Template('experience/components/twocolumn').render(model).text;
+};
+```
+
+## Page Script Context
+
+Properties available in `context` parameter:
+
+```javascript
+module.exports.render = function (context) {
+    var page = context.page;                    // dw.experience.Page
+    var renderParameters = context.renderParameters;  // HashMap from PageMgr.renderPage()
+
+    // Page methods
+    var pageId = page.ID;
+    var pageName = page.name;
+    var isVisible = page.isVisible();
+    var region = page.getRegion('regionId');    // dw.experience.Region
+};
+```
+
+## Component Script Context
+
+Properties available in `context` parameter:
+
+```javascript
+module.exports.render = function (context) {
+    var component = context.component;          // dw.experience.Component
+    var content = context.content;              // HashMap of attribute values
+    var componentRenderSettings = context.componentRenderSettings;
+
+    // Access attributes
+    var image = content.image;                  // dw.experience.image.Image
+    var product = content.product;              // dw.catalog.Product
+    var category = content.category;            // dw.catalog.Category
+    var text = content.headline;                // String
+    var enabled = content.showPrice;            // Boolean
+    var url = content.ctaUrl;                   // String (URL)
+
+    // For container components
+    var region = component.getRegion('regionId');
+};
+```

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

@@ -1,3 +1,8 @@
+---
+name: sfcc-performance
+description: Performance optimization strategies for Salesforce B2C Commerce Cloud including caching, efficient data retrieval, index-friendly APIs, and job optimization. Use when asked about SFCC performance, caching strategies, or optimization.
+---
+
 # Salesforce B2C Commerce Cloud: Performance Best Practices
 
 This document outlines key performance optimization strategies for Salesforce B2C Commerce Cloud, focusing on caching and efficient data retrieval.
@@ -202,8 +207,8 @@ Use custom caches for application-level data caching within dynamic requests (e.
    {
        "caches": [
            {
-               "name": "ExternalAPICache",
-               "ttl": 300
+               "id": "ExternalAPICache",
+               "expireAfterSeconds": 300
            }
        ]
    }
@@ -212,9 +217,36 @@ Use custom caches for application-level data caching within dynamic requests (e.
 2. **Register in `package.json`:**
    ```json
    {
-     "caches": "./cartridge/scripts/caches.json"
+     "caches": "./caches.json"
    }
    ```
+    The `package.json` must be in the cartridge root (cartridges/{{mycartridge}}/package.json), and the `caches.json` path is relative to that.
+
+### Practical Constraints (Why Cache Design Matters)
+
+- Custom cache memory is limited (roughly tens of MB per app server for all custom caches combined).
+- Individual entries have size limits; store only primitives / arrays / plain objects (use `null`, not `undefined`).
+- Caches are **per app server** (no cross-node synchronization). Always handle cache misses gracefully.
+
+### Recommended Usage Pattern: `get(key, loader)`
+
+Prefer the loader form so the expensive work only runs on cache miss:
+
+```javascript
+var CacheMgr = require('dw/system/CacheMgr');
+var Site = require('dw/system/Site');
+
+var cache = CacheMgr.getCache('ExternalAPICache');
+
+function getSiteScopedValue(keySuffix, loader) {
+    var key = Site.current.ID + '_' + keySuffix;
+    return cache.get(key, loader);
+}
+```
+
+### Cache Invalidation Reality
+
+Custom caches can be cleared by operational events (code changes/activation, replications). Design code so cache eviction is safe and does not break core flows.
 
 ### The "Get-or-Load" Pattern (Required)
 

package/ai-instructions/skills/sfcc-platform-limits/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: sfcc-platform-limits
+description: Cheat-sheet and design patterns for surviving SFCC quotas and limits (script timeouts, HTTPClient call caps, session size, custom object quotas, file I/O restrictions, and headless rate limits). Use this when debugging enforced quota violations or designing scalable SFCC architectures.
+---
+
+# SFCC Platform Limits (Quota Survival Skill)
+
+SFCC limits are not “edge cases”; they shape correct architecture. This skill is a pragmatic guide to:
+- Recognizing limit symptoms
+- Picking the correct workaround pattern
+- Avoiding designs that will fail under load
+
+## Quick Checklist
+
+```text
+[ ] Identify your execution context (storefront controller vs hook vs job)
+[ ] Assume strict timeouts in hook/script contexts (design for the smallest budget)
+[ ] Keep external calls bounded; cache aggressively; avoid chatty integrations
+[ ] Never store large objects in session (store IDs; refetch/cache)
+[ ] Never write files from storefront requests (offload to jobs)
+[ ] Put retention policies on temporary custom objects from day one
+```
+
+## Common Limits → Symptoms → Fix Patterns
+
+| Symptom | Likely limit | Fix pattern |
+|---|---|---|
+| “ScriptingTimeoutError” / request abort | Storefront script timeout | Move heavy work to jobs; reduce synchronous work; fail fast on services |
+| Generic 500 from OCAPI hook | Hook execution timeout | Keep hooks lightweight; move heavy logic to async processing or custom endpoint |
+| “Too many HTTPClient calls” / enforced quota | Outbound call cap per request | Aggregate calls (BFF), cache, pre-load via feeds/jobs |
+| Session data truncation / instability | Session size cap | Store identifiers only; use cache or refetch |
+| Errors creating custom objects | CO quotas / create-per-request cap | Consolidate data; implement purge jobs; avoid COs for transactional logging |
+| “Page size limit exceeded” | Rendered HTML size cap | Pagination, remote includes, lazy loading, move logic out of templates |
+| Storefront fails when writing files | Storefront file I/O = 0 | Use job + WebDAV download pattern |
+| SCAPI returns 429 | Rate limiting / load shedding | Honor `Retry-After`; exponential backoff; client-side caching |
+
+## Context Matters: Timeouts Differ
+
+Design for the *most restrictive* context a script might run in.
+- Storefront controllers can have relatively generous execution budgets.
+- Hook/script contexts (OCAPI hooks, Page Designer scripts, etc.) can be much tighter.
+
+Rule of thumb: if code could run in a hook, keep it hook-safe.
+
+## Integration Limits: External Calls Must Be Budgeted
+
+Common failure mode: a page that makes many independent external calls.
+
+Preferred architecture:
+- **Aggregation layer** (BFF/gateway): 1 call from SFCC, many calls downstream outside SFCC quotas
+- **Aggressive caching** for anything not truly real-time
+- **Data feeds via jobs** for data that can be slightly stale
+
+## Session: Treat It Like a Tiny Backpack
+
+- Store small primitives (IDs, flags), not full objects
+- Prefer `session.privacy` for user-specific temporary values that should clear on logout
+
+## Custom Objects: Treat Quotas as a Data Hygiene Contract
+
+Anti-pattern: using custom objects as a high-volume event log.
+
+Better:
+- Put integration/event logs in an external system of record
+- If you must store temporary records, define:
+  - retention period
+  - purge job
+  - monitoring alerts
+
+## Storefront File I/O: The Asynchronous File Pattern
+
+When you need a file (export/report) initiated by a shopper:
+1. Storefront creates a “token” record (status = pending)
+2. Job generates file into WebDAV (`/impex/src/...`)
+3. UI polls a lightweight endpoint for status
+4. UI offers download link once complete
+5. Purge token + old files
+
+## Headless / Composable Notes
+
+- Expect **HTTP 429**; design the client to retry responsibly
+- Token churn can trigger SLAS limits; token caching + refresh flow correctness is mandatory
+- Managed runtime proxies can enforce hard request timeouts; long-running work must be async + poll
+
+## References
+- Rhino Inquisitor: The SFCC Quota Gauntlet (platform limits)
+  - https://www.rhino-inquisitor.com/a-survival-guide-to-sfcc-platform-limits/
+- Salesforce Commerce API docs (timeouts troubleshooting)
+  - https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeout-troubleshoot.html