sfcc-dev-mcp 1.0.16 → 1.0.20

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

@@ -1,370 +0,0 @@
----
-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

@@ -1,116 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-# 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.

package/ai-instructions/skills/sfcc-isml-development/references/SFRA-PAGES-CART-ACCOUNT-AUTH.md

@@ -1,45 +0,0 @@
-# SFRA Page Patterns (Cart, Account, Auth)
-
-These patterns are common in SFRA for stateful and account-related pages.
-
-## Cart
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- Uses Bootstrap alerts for errors
-- Renders line items via includes by product type
-- Renders totals + promo/coupon UX in a right-side column on desktop
-
-Common includes:
-
-- `cart/productCard/cartProductCard`
-- `cart/productCard/cartBundleCard`
-- `cart/cartTotals`
-- `cart/cartPromoCode`
-- `cart/checkoutButtons`
-
-Keep cart-specific fragments local unless you have a strong cache boundary reason.
-
-## Account (Dashboard + Subpages)
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- Left-side navigation include: `account/accountNav`
-- Card layout for subpages and content areas
-
-Avoid putting “which subpage is active” logic in ISML beyond simple conditionals. Prefer controller flags (`pdict.profile`, `pdict.orderHistory`, etc.).
-
-## Login / Registration
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- CSRF hidden fields required
-- Bootstrap 4 validation patterns:
-  - input adds `is-invalid` when field invalid
-  - error text rendered in `invalid-feedback`
-- Uses `autocomplete` attributes for UX and accessibility
-
-Reminder: do not output raw form attributes with `encoding="off"` unless the source is trusted.

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

@@ -1,85 +0,0 @@
-# SFRA Page Patterns (Catalog/Search)
-
-These are common SFRA patterns for pages that list or describe products/categories.
-
-## Homepage
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- Uses content slots (`<isslot>`) for BM-driven content
-- Uses Bootstrap grid containers for layout
-
-Example skeleton:
-
-```html
-<isdecorate template="common/layout/page">
-    <isscript>
-        var assets = require('*/cartridge/scripts/assets.js');
-        assets.addCss('/css/homePage.css');
-        assets.addJs('/js/productTile.js');
-    </isscript>
-
-    <div class="home-main homepage">
-        <isslot id="home-main-m" description="Main home page slot." context="global" />
-    </div>
-</isdecorate>
-```
-
-## Product Detail Page (PDP)
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- Creates a page-scoped `product` convenience variable
-- Uses responsive patterns (`d-md-none`, etc.)
-
-Example skeleton:
-
-```html
-<isdecorate template="common/layout/page">
-    <isscript>
-        var assets = require('*/cartridge/scripts/assets.js');
-        assets.addCss('/css/product/detail.css');
-        assets.addJs('/js/productDetail.js');
-    </isscript>
-
-    <isset name="product" value="${pdict.product}" scope="page" />
-
-    <div class="container product-detail" data-pid="${product.id}">
-        <div class="row">
-            <div class="col-12">
-                <h1 class="product-name">${product.productName}</h1>
-                <isinclude template="product/components/pricing/main"/>
-            </div>
-        </div>
-    </div>
-</isdecorate>
-```
-
-## Search Results
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- `refinement-bar` sidebar + grid content area
-- Product tiles rendered via local include(s)
-
-Key include components you’ll typically see:
-
-- `search/refinements`
-- `search/searchResultsCount`
-- `search/sortOrderMenu`
-- `search/searchResultsPagination`
-- `product/productTile`
-
-## Category Landing
-
-Typical traits:
-
-- Decorated with `common/layout/page`
-- Breadcrumbs via `components/breadcrumbs/pageBreadcrumbs`
-- Optional custom template selection via `pdict.category.template`
-- Content slots for BM-managed category content
-
-If you need a “hero image” style, prefer safe attribute construction and encoded values. Avoid mixing ISML tags into the middle of an HTML tag in a way that produces invalid markup.