sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/skills/sfcc-fraud-prevention/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sfcc-fraud-prevention
+description: Layered fraud prevention playbook for Salesforce B2C Commerce developers. Use this when adding fraud signals, designing a risk scoring approach, integrating third-party tools, or hardening checkout/login against bot-driven abuse.
+---
+
+# SFCC Fraud Prevention (Developer Playbook)
+
+Fraud prevention in SFCC is a *system*, not a single feature. This skill focuses on practical developer responsibilities:
+- Detectable signals you can implement
+- Where to enforce checks
+- How to store state safely
+- How to avoid performance and quota pitfalls
+
+## Quick Checklist
+
+```text
+[ ] Start at the edge: eCDN rules (block obvious bad traffic)
+[ ] Enforce payment checks (AVS/CVV/3DS where available)
+[ ] Add server-side validation (never trust the client)
+[ ] Add velocity + behavior checks using minimal state
+[ ] Ensure retention + purge jobs for any temporary state objects
+[ ] Log decisions carefully (no PII leakage)
+```
+
+## Threat Taxonomy (Why It Matters to Code)
+
+Common families you’ll see in data:
+- Card-not-present fraud
+- Account takeover (credential stuffing)
+- “Friendly fraud” / chargebacks
+- Bot-driven attacks (card testing, inventory hoarding)
+
+Your job is to translate these into **signals** you can observe and validate.
+
+## Actionable Signals (Implementation-Friendly)
+
+| Signal type | Examples |
+|---|---|
+| Data mismatches | IP geolocation vs billing/shipping country; name/address anomalies |
+| Velocity patterns | many attempts from same IP/email/device; repeated failures then success |
+| Order characteristics | unusually large order; high-risk SKUs; rush shipping |
+| Identity indicators | disposable email; gibberish names; repeated address reuse |
+
+## Layered Defense Architecture
+
+### 1) Edge controls (before app servers)
+- Use **eCDN custom rules** to block/limit known abusive traffic patterns.
+- Rate-limit endpoints that are common bot targets (login, add-to-cart, checkout).
+
+### 2) Platform + processor basics
+- Enable/enforce payment gateway features like **AVS** and **CVV** checks.
+- Prefer adding friction only when risk is elevated.
+
+### 3) Server-side rules and scoring
+Where to implement depends on architecture:
+- **SFRA**: controller middleware + fraud detection script points
+- **Headless**: keep hook logic minimal; consider custom endpoints for heavier checks
+
+A practical approach:
+- Compute a numeric risk score from signals (0–100)
+- Block above a threshold; challenge (CAPTCHA/step-up) in mid-range; allow below threshold
+
+## State Storage (Don’t Create a Quota Time Bomb)
+
+If you store historical signals:
+- Use a minimal schema (counts + timestamps), not raw event logs
+- Define retention policy and a purge job from day one
+
+If you must store per-session state:
+- Prefer session privacy storage for small values
+
+## Logging & Observability
+
+- Log risk decisions with correlation IDs and *redacted* values
+- Avoid writing PII into shared logs
+
+See also: `sfcc-logging` and `sfcc-security`.
+
+## When to Buy Instead of Build
+
+Third-party fraud tools can be the correct choice when:
+- You need global intelligence across merchants
+- You need chargeback guarantees
+- You are being hit by sophisticated bot abuse
+
+Build custom logic when:
+- You need business-specific heuristics
+- You have clear signals + small scope
+- You can commit to continuous tuning (false positives are costly)
+
+## References
+- Rhino Inquisitor: A Developer’s Guide to Combating Fraud on SFCC
+  - https://www.rhino-inquisitor.com/a-dev-guide-to-combating-fraud-on-sfcc/
+- Salesforce: Bot management guidance (high-level responsibility model)
+  - https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html

package/ai-instructions/skills/sfcc-hooks-registration/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: sfcc-hooks-registration
+description: 'Register SFCC hooks via cartridge package.json and hooks.json. Use when adding hooks or troubleshooting hook registration.'
+---
+
+# SFCC Hooks Registration
+
+## When to Use
+- Adding new script hooks for a cartridge
+- Fixing missing hook execution
+- Verifying hook registration structure
+
+## Procedure
+1. Add a package.json at the top level of the cartridge (cartridges/<cartridge-name>/package.json).
+2. Define the hooks path relative to that package.json:
+   ```json
+   {
+     "hooks": "./cartridge/scripts/hooks.json"
+   }
+   ```
+3. In hooks.json, map hook names to script files relative to hooks.json:
+   ```json
+   {
+     "hooks": [
+       {
+         "name": "dw.order.calculate",
+         "script": "./hooks/cart/calculate.js"
+       }
+     ]
+   }
+   ```
+4. Export hook functions as CommonJS exports with the unqualified hook name (for example, `dw.order.calculate` uses `exports.calculate`).
+5. Enable the **Salesforce Commerce Cloud API hook execution** feature switch in Business Manager for OCAPI/SCAPI hooks.
+6. Ensure the cartridge is in the site cartridge path and upload the cartridge.
+
+## Notes
+- The hooks path is relative to the package.json location.
+- The script path in hooks.json is relative to hooks.json itself.
+- For Shopper API hooks, returning a value can skip the system implementation; return nothing when you want the default implementation to run.

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

@@ -0,0 +1,370 @@
+---
+name: sfcc-isml-development
+description: SFRA-first guide for developing ISML templates in Salesforce B2C Commerce (Bootstrap 4 conventions). Use this when creating, modifying, or troubleshooting SFRA templates, decorators, components, forms, includes, and caching.
+---
+
+# ISML Development (SFRA + Bootstrap 4)
+
+This skill is **SFRA-only**. It intentionally avoids SiteGenesis patterns.
+
+SFRA storefront markup is built around **Bootstrap 4** (grid, forms, alerts, utilities). Keep your ISML consistent with existing SFRA markup and CSS conventions.
+
+## When to Use
+
+- You’re editing `templates/default/**` in an SFRA cartridge.
+- You need to apply/extend SFRA layout (`common/layout/page` / `common/layout/checkout`).
+- You’re building reusable components via `<isinclude>` and Bootstrap 4 markup.
+- You’re debugging output encoding, caching, or remote include behaviour.
+
+## When NOT to Use
+
+- For business logic, data fetching, persistence, or complex transformations (belongs in controllers/models/scripts).
+- For redesigning UI with a different framework (SFRA baseline expects Bootstrap 4).
+
+## Quick Checklist
+
+```text
+[ ] No business logic in ISML (no data fetches, no persistence)
+[ ] <isscript> used only for SFRA asset registration (CSS/JS)
+[ ] Output encoding is NOT disabled unless justified and safe
+[ ] <iscontent>/<isredirect>/<iscache> placement constraints respected
+[ ] Remote includes used sparingly with security middleware
+[ ] Template receives all data via pdict (controller owns data)
+[ ] Markup uses Bootstrap 4 classes (grid, forms, alerts)
+```
+
+## Where Templates Live (SFRA)
+
+```
+/my-cartridge/cartridge/templates/
+    /default                    # Default templates (SFRA)
+        /product/detail.isml
+        /util/modules.isml      # Optional: <ismodule> tag definitions
+    /fr_FR                      # Locale overrides (use sparingly)
+```
+
+## SFRA Golden Rule: Templates Are Presentation-Only
+
+**NEVER use `<isscript>` for business logic.** The only exception is asset management:
+
+```html
+<!-- ✅ Only acceptable use of isscript -->
+<isscript>
+    var assets = require('*/cartridge/scripts/assets.js');
+    assets.addCss('/css/product.css');
+    assets.addJs('/js/product.js');
+</isscript>
+```
+
+All data comes from controllers via `pdict`:
+
+```html
+<!-- ✅ Correct: Data from controller -->
+<div class="price h5 mb-0">${pdict.product.price.sales.formatted}</div>
+```
+
+## Bootstrap 4 Conventions (SFRA UI Baseline)
+
+Use these classes/patterns by default:
+
+| Goal | Bootstrap 4 pattern |
+|------|----------------------|
+| Layout | `container` → `row` → `col-*` |
+| Spacing | `mt-*`, `mb-*`, `py-*`, `px-*` |
+| Buttons | `btn btn-primary`, `btn btn-outline-primary` |
+| Alerts | `alert alert-danger`, `alert alert-success` |
+| Forms | `form-group`, `form-control`, `is-invalid`, `invalid-feedback` |
+| Responsive show/hide | `d-none d-md-block`, `d-md-none` |
+
+Avoid mixing Bootstrap 5-only classes (e.g. `g-*`, `row-cols-*`, `btn-close`, `badge bg-*`) into SFRA baseline templates.
+
+## Essential Tags
+
+### Conditional Logic
+
+```html
+<isif condition="${pdict.product.available}">
+    <span class="badge badge-success">${Resource.msg('label.instock','product',null)}</span>
+<iselseif condition="${pdict.product.preorderable}">
+    <span class="badge badge-info">${Resource.msg('label.preorder','product',null)}</span>
+<iselse>
+    <span class="badge badge-secondary">${Resource.msg('label.outofstock','product',null)}</span>
+</isif>
+```
+
+### Loops
+
+```html
+<isloop items="${products}" var="product" status="loopstate">
+    <div class="col-6 col-sm-4 col-lg-3 mb-3">
+        <div class="card h-100">
+            <div class="card-body">
+                <div class="small text-muted">#${loopstate.count}</div>
+                <div class="font-weight-bold">${product.name}</div>
+            </div>
+        <isif condition="${loopstate.first}">
+            <div class="card-footer bg-transparent">
+                <span class="badge badge-warning">${Resource.msg('label.featured','common',null)}</span>
+            </div>
+        </isif>
+        </div>
+    </div>
+</isloop>
+```
+
+Loop status: `count` (1-based), `index` (0-based), `first`, `last`, `odd`, `even`
+
+### Variables
+
+```html
+<isset name="productName" value="${product.name}" scope="page"/>
+<span>${productName}</span>
+<isremove name="productName" scope="page"/>
+```
+
+Scopes (required): `page`, `request`, `session`, `pdict`
+
+### Output
+
+```html
+<!-- HTML encoded (default) -->
+<isprint value="${product.name}"/>
+
+<!-- Unencoded (use carefully) -->
+<isprint value="${htmlContent}" encoding="off"/>
+
+<!-- Formatted -->
+<isprint value="${price}" style="CURRENCY"/>
+<isprint value="${order.creationDate}" style="DATE_SHORT"/>
+```
+
+### Includes
+
+```html
+<!-- Local include (shared pdict) -->
+<isinclude template="product/components/price"/>
+
+<!-- Remote include (isolated, own cache) -->
+<isinclude url="${URLUtils.url('Product-GetPrice', 'pid', product.ID)}"/>
+```
+
+Prefer local includes for components. Only use remote includes when you need an **independent cache policy** or **request isolation**; see the remote include reference.
+
+## Decorator Pattern
+
+**Decorator template** (`common/layout/page.isml`):
+```html
+<!DOCTYPE html>
+<html>
+<head><title>${pdict.pageTitle}</title></head>
+<body>
+    <isinclude template="components/header"/>
+    <main>
+        <isreplace/>  <!-- Content inserted here -->
+    </main>
+    <isinclude template="components/footer"/>
+</body>
+</html>
+```
+
+**Using decorator:**
+```html
+<isdecorate template="common/layout/page">
+    <div class="content">
+        <h1>${pdict.welcomeMessage}</h1>
+    </div>
+</isdecorate>
+```
+
+SFRA provides two primary decorators:
+- `common/layout/page` - Standard storefront pages
+- `common/layout/checkout` - Checkout process pages
+
+Use `<isdecorate>` on almost all storefront templates; keep full `<html>/<head>/<body>` only in layout templates.
+
+## Tag Location Constraints
+
+| Tag | Constraint |
+|-----|------------|
+| `<iscontent>` | Must be before DOCTYPE |
+| `<isredirect>` | Must be before DOCTYPE |
+| `<iscache>` | Place at beginning |
+| `<isreplace/>` | Only inside decorator templates |
+| `<isbreak>/<iscontinue>/<isnext>` | Only inside `<isloop>` |
+
+## Caching
+
+```html
+<!-- Cache for 24 hours -->
+<iscache type="relative" hour="24"/>
+
+<!-- Daily cache (expires at midnight) -->
+<iscache type="daily" hour="0" minute="0"/>
+
+<!-- Vary by price/promotion -->
+<iscache type="relative" hour="1" varyby="price_promotion"/>
+```
+
+Place `<iscache>` at the beginning of the template.
+
+Prefer **controller caching middleware** (SFRA `*/cartridge/scripts/middleware/cache`) for page-level caching decisions; use `<iscache>` selectively for fragments.
+
+## Content Type
+
+```html
+<!-- Must be first in template -->
+<iscontent type="text/html" charset="UTF-8"/>
+
+<!-- For JSON -->
+<iscontent type="application/json" charset="UTF-8"/>
+```
+
+## Custom Modules
+
+**Define in `util/modules.isml`:**
+```html
+<ismodule template="components/productcard"
+          name="productcard"
+          attribute="product"
+          attribute="showPrice"/>
+```
+
+**Use anywhere:**
+```html
+<isinclude template="util/modules"/>
+<isproductcard product="${product}" showPrice="${true}"/>
+```
+
+In SFRA, most reuse is done via `<isinclude template="...">`. Use `<ismodule>` custom tags only when it measurably improves readability/consistency.
+
+## Security: XSS Prevention
+
+**Always rely on default encoding.** `<isprint>` automatically HTML-encodes:
+
+```html
+<!-- ✅ Secure (default) -->
+<isprint value="${pdict.searchPhrase}" />
+
+<!-- ❌ Vulnerable -->
+<isprint value="${pdict.searchPhrase}" encoding="off" />
+```
+
+For JavaScript context, use `SecureEncoder`:
+
+```html
+<script>
+    var term = "${require('dw/util/SecureEncoder').forJavaScript(pdict.searchPhrase)}";
+</script>
+```
+
+For HTML attributes, prefer `SecureEncoder.forHTMLAttribute(...)`. Avoid `encoding="off"` unless the value is fully controlled and intentionally contains HTML.
+
+## Built-in Utilities
+
+Pre-imported, use directly:
+
+```html
+<!-- URLUtils -->
+<a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">View</a>
+<img src="${URLUtils.staticURL('/images/logo.png')}" alt="Logo"/>
+
+<!-- Resource (localization) -->
+${Resource.msg('button.addtocart', 'product', null)}
+${Resource.msgf('cart.items', 'cart', null, cartCount)}
+
+<!-- StringUtils -->
+${StringUtils.truncate(description, 100, '...')}
+```
+
+## Expressions
+
+```html
+<!-- Property access -->
+${pdict.product.name}
+${pdict.product.price.sales.value}
+
+<!-- Method calls -->
+${product.getAvailabilityModel().isInStock()}
+
+<!-- Operators -->
+${price > 100 ? 'expensive' : 'affordable'}
+${firstName + ' ' + lastName}
+```
+
+## Comments
+
+```html
+<!-- HTML comment (visible in source) -->
+
+<iscomment>
+    ISML comment - stripped from output.
+    Use for sensitive documentation.
+</iscomment>
+```
+
+## Best Practices
+
+1. Use Bootstrap 4 components/utilities for UI consistency
+2. Use `<isdecorate>` with SFRA layouts (`common/layout/page`, `common/layout/checkout`)
+3. Keep templates “dumb”: controllers/models prepare view models; templates render
+4. Use `<isinclude template>` for component composition; keep components small
+5. Default encoding prevents XSS; use `SecureEncoder` for JS/attribute contexts
+6. Minimize remote includes; when used, require `server.middleware.include` + explicit security + cache policy
+7. Prefer controller caching middleware; use `<iscache>` thoughtfully
+
+## Common SFRA Form Pattern (Bootstrap 4)
+
+```html
+<form action="${URLUtils.url('Account-Login')}" method="post" class="login">
+    <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>
+
+    <div class="form-group">
+        <label class="form-control-label" for="login-email">
+            ${Resource.msg('label.login.email','login',null)}
+        </label>
+        <input
+            id="login-email"
+            type="email"
+            class="form-control <isif condition="${pdict.loginForm.username.invalid}">is-invalid</isif>"
+            name="${pdict.loginForm.username.htmlName}"
+            value="${pdict.loginForm.username.value}"
+            autocomplete="email"
+            required>
+        <isif condition="${pdict.loginForm.username.invalid}">
+            <div class="invalid-feedback">
+                <isprint value="${pdict.loginForm.username.error}"/>
+            </div>
+        </isif>
+    </div>
+
+    <button type="submit" class="btn btn-primary btn-block">
+        ${Resource.msg('button.login','login',null)}
+    </button>
+</form>
+```
+
+## MCP ISML Tools
+
+```javascript
+search_isml_elements("loop")     // Find by intent
+get_isml_element("isprint")      // Full documentation
+list_isml_elements()             // All elements by category
+```
+
+## Related Skills
+
+- **[sfcc-localization](../sfcc-localization/SKILL.md)** - Essential companion skill for localizing template text. Covers resource bundles, `Resource.msg()`, parameterized messages, locale fallback, and internationalization best practices. **Always use resource bundles instead of hardcoded text in templates.**
+
+## Detailed References
+
+- [Remote Includes](references/REMOTE-INCLUDES.md) - Local vs remote, caching, security
+- [Utilities & Expressions](references/UTILITIES-EXPRESSIONS.md) - Built-in objects, expression syntax
+- [SFRA Base Templates (Index)](references/sfra-base-templates-architecture.md) - Jumping-off point
+- [SFRA Layouts](references/SFRA-LAYOUTS.md) - Decorators, hooks, `<isreplace/>`
+- [SFRA Structure & Components](references/SFRA-STRUCTURE-COMPONENTS.md) - Where templates live, composition patterns
+- [SFRA Pages: Catalog/Search](references/SFRA-PAGES-CATALOG.md) - Homepage/PDP/search/category patterns
+- [SFRA Pages: Cart/Account/Auth](references/SFRA-PAGES-CART-ACCOUNT-AUTH.md) - Cart/account/login patterns
+
+## External Reference
+
+- Legacy long-form doc (for deeper examples): https://raw.githubusercontent.com/taurgis/sfcc-dev-mcp/refs/heads/main/docs/best-practices/isml_templates.md

package/ai-instructions/skills/sfcc-isml-development/references/REMOTE-INCLUDES.md

@@ -0,0 +1,116 @@
+# ISML Remote Includes Reference
+
+Comprehensive guide for local vs remote includes, caching strategies, and security.
+
+## Local vs Remote Includes
+
+| Attribute | Local Include | Remote Include |
+|-----------|---------------|----------------|
+| Syntax | `<isinclude template="...">` | `<isinclude url="...">` |
+| Processing | Single request on Application Server | Parent + secondary request via Web Adapter |
+| Data Scope | Full access to parent `pdict` & variables | Isolated – only URL query params available |
+| Cache Policy | Inherits parent (lowest TTL wins) | Independent TTL per fragment |
+| Typical Use | Reusable markup, partials | Mini-cart, personalized slots, dynamic widgets |
+| Overhead | Minimal | Extra HTTP round trip |
+| Security | Inherits parent auth state | New unauthenticated request |
+| Failure Mode | Template error breaks page | Fragment timeout can delay assembly |
+
+## When to Use Remote Includes
+
+Use a **local include** unless ALL are true:
+1. Fragment volatility differs meaningfully from page shell
+2. Output can be parameterized via simple query params
+3. Performance gain from separate caching outweighs added request
+4. Security implications are understood and mitigated
+
+## Implementing Remote Includes
+
+### Template Example
+
+Mini-cart header icon (uncached) while page shell cached for hours:
+
+```html
+<div class="header-cart" data-component="mini-cart">
+    <isinclude url="${URLUtils.url('Cart-MiniCart')}" />
+</div>
+```
+
+### Controller Pattern
+
+```javascript
+var server = require('server');
+var cache = require('*/cartridge/scripts/middleware/cache');
+
+server.get('MiniCart',
+    server.middleware.include, // Gatekeeper: only valid inside remote include
+    cache.applyShortPromotionSensitiveCache, // Or cache.disableCaching()
+    function (req, res, next) {
+        // Build isolated model – no parent pdict access
+        res.render('components/header/miniCart');
+        next();
+    }
+);
+
+module.exports = server.exports();
+```
+
+## Passing Data
+
+All context must be URL params:
+
+```html
+<isinclude url="${URLUtils.url('Page-Include', 'cid', 'footer-content-asset')}" />
+```
+
+**Warning:** Each unique full URL becomes a distinct cache entry (cache fragmentation risk).
+
+## Caching Strategy Patterns
+
+| Scenario | Page Shell TTL | Remote Include TTL | Rationale |
+|----------|----------------|--------------------|-----------|
+| Marketing landing + live inventory | 12h | 5m | Keep inventory fresh |
+| Category grid + personalized banner | 4h | 15m | Personalized offers rotate |
+| PDP + mini-cart | 2h | 0 (uncached) | Basket state = current session |
+
+Keep total remote includes per page conservative (<20 recommended).
+
+## Performance Anti-Patterns
+
+| Anti-Pattern | Why Harmful | Better Alternative |
+|--------------|-------------|-------------------|
+| Remote include per product tile | N extra HTTP requests | Single parent with local includes |
+| Position/index params that vary | Creates unique cache keys | Omit non-functional params |
+| Deep nesting (include chain) | Compounding latency | Flatten architecture |
+
+## Security Requirements
+
+Remote include endpoints are effectively **public** unless you add authentication middleware.
+
+**NEVER** expose PII or account state in an unprotected include.
+
+```javascript
+server.get('SensitiveFragment',
+    server.middleware.include,
+    userLoggedIn.validateLoggedIn, // if user-specific
+    function (req, res, next) { ... }
+);
+```
+
+## Checklist
+
+```text
+[ ] Justified different cache TTL
+[ ] URL params minimal & non-sensitive
+[ ] server.middleware.include first
+[ ] Additional auth middleware if user data
+[ ] Explicit cache middleware (or disabled)
+[ ] Fragment count on page < 20
+[ ] No nested chains beyond depth 2
+```
+
+## When NOT to Use Remote Includes
+
+- Pure presentational partials (icons, button groups)
+- Iterative children of a paginated list
+- Form bodies requiring parent validation context
+- Anything requiring parent `pdict` without trivial serialization

package/ai-instructions/skills/sfcc-isml-development/references/SFRA-LAYOUTS.md

@@ -0,0 +1,50 @@
+# SFRA Layout Templates (Decorators)
+
+SFRA storefront pages typically render content via:
+
+```html
+<isdecorate template="common/layout/page">
+    <!-- page content -->
+</isdecorate>
+```
+
+Keep full `<html>/<head>/<body>` markup in layout templates only.
+
+## Core Layouts
+
+SFRA commonly uses these base layout templates:
+
+- `common/layout/page.isml` — primary layout for most storefront pages
+- `common/layout/checkout.isml` — checkout layout (reduced header/navigation)
+- `common/layout/pdStorePage.isml` — Page Designer store pages (campaign banner support)
+
+These layouts typically:
+
+- Include shared head markup via `common/htmlHead`
+- Register shared scripts via `common/scripts`
+- Include header/footer components
+- Provide a single `<isreplace/>` insertion point inside `<main>`
+- Call template hooks:
+  - `dw.system.HookMgr.callHook('app.template.beforeHeader', 'beforeHeader', pdict)`
+  - `dw.system.HookMgr.callHook('app.template.afterFooter', 'afterFooter', pdict)`
+
+## `<isreplace/>` Rules
+
+- Layout templates contain `<isreplace/>`.
+- Decorated templates contain markup that will be injected at `<isreplace/>`.
+- Prefer **one** `<isreplace/>` per layout.
+
+## Bootstrap 4 Notes
+
+SFRA baseline markup uses **Bootstrap 4**:
+
+- Grid: `container` → `row` → `col-*`
+- Forms: `form-group`, `form-control`, `is-invalid`, `invalid-feedback`
+- Alerts: `alert alert-*`
+- Utilities: `d-none d-md-block`, spacing utilities `mt-*` etc.
+
+Avoid Bootstrap 5-only classes unless your project has explicitly upgraded.
+
+## Caching Reminder
+
+Prefer controller-based caching middleware for page caching; use `<iscache>` selectively for fragments.