sfcc-dev-mcp 1.0.15 → 1.0.19

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

@@ -0,0 +1,45 @@
+# 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/dist/ai-instructions/skills/sfcc-isml-development/references/SFRA-PAGES-CATALOG.md

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

package/dist/ai-instructions/skills/sfcc-isml-development/references/SFRA-STRUCTURE-COMPONENTS.md

@@ -0,0 +1,63 @@
+# SFRA Template Structure & Shared Components
+
+This reference focuses on where things live and how SFRA composes templates.
+
+## Typical Structure
+
+```text
+templates/default/
+  common/
+    layout/              # page, checkout, pdStorePage layouts
+    htmlHead.isml        # shared <head> content
+    scripts.isml         # shared script includes
+  components/
+    header/
+    footer/
+    breadcrumbs/
+    modules.isml         # module registration (if your project uses it)
+    schema.isml          # structured data
+  home/
+  product/
+  cart/
+  checkout/
+  account/
+  search/
+  error/
+```
+
+## Composition Rules (SFRA)
+
+- Prefer small, reusable partials under `components/**`.
+- Use local includes for most composition:
+
+```html
+<isinclude template="components/breadcrumbs/pageBreadcrumbs"/>
+<isinclude template="product/productTile"/>
+```
+
+- Use remote includes only when you need an independent cache boundary or isolation (see `REMOTE-INCLUDES.md`).
+
+## `common/htmlHead.isml` (What it typically does)
+
+Common responsibilities:
+
+- `<title>` and environment-aware titles
+- meta tags (description/keywords)
+- canonical link when provided
+- favicon set and shared head assets
+
+Keep meta values encoded and sourced from controller-provided `pdict`.
+
+## Asset Registration (`assets.js`)
+
+Page templates may register page-specific assets:
+
+```html
+<isscript>
+    var assets = require('*/cartridge/scripts/assets.js');
+    assets.addCss('/css/search.css');
+    assets.addJs('/js/search.js');
+</isscript>
+```
+
+Do not use `<isscript>` for business logic.

package/dist/ai-instructions/skills/sfcc-isml-development/references/UTILITIES-EXPRESSIONS.md

@@ -0,0 +1,159 @@
+# ISML Utility Objects & Expressions Reference
+
+Reference for built-in template utilities and expression syntax.
+
+## Top-Level Variables
+
+The template scope automatically exposes:
+
+- `pdict` - Pipeline Dictionary (controller data)
+- `out` - Output stream
+- `request` - Current request object
+- `session` - Current session object
+
+## dw.system.Request Methods
+
+| Method | Description |
+|--------|-------------|
+| `getHttpCookies()` → `Cookies` | Returns cookies object |
+| `getHttpHeaders()` → `Map` | Returns HTTP header values |
+| `isHttpSecure()` → `Boolean` | Whether request is HTTPS |
+| `isSCAPI()` → `Boolean` | Distinguishes OCAPI vs SCAPI |
+
+**Example:**
+```html
+<isprint value="${request.custom.Container.adjustedMerchandiseTotalNetPrice}" />
+```
+
+## dw.system.Session Methods
+
+| Method | Description |
+|--------|-------------|
+| `getCustomer()` → `Customer` | Current customer (null in BM) |
+| `isCustomerAuthenticated()` → `Boolean` | Whether customer is authenticated |
+
+**Example:**
+```html
+<isprint value="${session.getCustomer().firstname}" />
+```
+
+## dw.util.StringUtils
+
+Pre-imported, call by simple name:
+
+| Method | Description |
+|--------|-------------|
+| `formatDate(date)` | Format with site's default date format |
+| `formatInteger(number)` | Format with site's integer format |
+| `formatNumber(number)` | Format with site's number format |
+| `garble(str, replaceChar, suffixLength)` | Mask string leaving suffix |
+| `pad(str, width)` | Pad string to target width |
+| `stringToHtml(str)` | Convert to HTML-safe |
+| `stringToXml(str)` | Convert to XML-safe |
+| `trim(str)` | Remove leading/trailing whitespace |
+| `truncate(str, maxLength, mode, suffix)` | Truncate text with suffix |
+
+**Example:**
+```html
+<isprint value="${StringUtils.pad('abc', 5)}" />
+${StringUtils.truncate(description, 100, '...')}
+```
+
+## dw.web.URLUtils
+
+Pre-imported for URL generation:
+
+| Method | Description |
+|--------|-------------|
+| `abs(action, ...params)` | Absolute URL from calling request |
+| `http(action, ...params)` | Absolute HTTP URL |
+| `https(action, ...params)` | Absolute HTTPS URL |
+| `httpsWebRoot()` | HTTPS web root for static assets |
+| `httpWebRoot()` | HTTP web root for static assets |
+| `url(action, ...params)` | Relative URL |
+| `webRoot()` | Relative web root |
+| `staticURL(path)` | Static resource URL |
+| `continueURL()` | Continue URL for form action |
+
+**Examples:**
+```html
+<a href="${URLUtils.url('Product-Show', 'pid', product.ID)}">View</a>
+<a href="${URLUtils.https('Account-Show')}">My Account</a>
+<img src="${URLUtils.staticURL('/images/logo.png')}" alt="Logo"/>
+
+<form action="${URLUtils.continueURL()}" method="post">
+```
+
+## Resource (Localization)
+
+```html
+<!-- Simple message -->
+${Resource.msg('button.addtocart', 'product', null)}
+
+<!-- With parameters -->
+${Resource.msgf('cart.items', 'cart', null, cartCount)}
+```
+
+## Expression Syntax
+
+### Basics
+
+- **Syntax**: `${ ... }`
+- **Scope**: Evaluates in template context (`pdict`, `request`, `session`)
+
+### Common Patterns
+
+```html
+<!-- Property access -->
+${pdict.product.name}
+${pdict.product.price.sales.value}
+
+<!-- Method calls -->
+${product.getAvailabilityModel().isInStock()}
+
+<!-- Session data -->
+${session.customer.firstName}
+
+<!-- Request params -->
+${request.httpParameterMap.pid.stringValue}
+
+<!-- Operators -->
+${price > 100 ? 'expensive' : 'affordable'}
+${firstName + ' ' + lastName}
+${quantity * unitPrice}
+```
+
+### Quick Reference
+
+| Expression | Description |
+|------------|-------------|
+| `${pdict.Product}` | Current product object |
+| `${pdict.Content.template}` | Content asset template |
+| `${pdict.ProductPrices}` | Product prices structure |
+| `${pdict.Order.orderNo}` | Order number |
+
+## Protected Strings
+
+The literal string `</body>` is reserved by ISML parser. Obfuscate if needed:
+
+```javascript
+var endBodyIndex = markup.indexOf('</bo' + 'dy>');
+```
+
+## dw.util.SecureEncoder
+
+For context-specific encoding:
+
+```html
+<isscript>
+    var SecureEncoder = require('dw/util/SecureEncoder');
+</isscript>
+
+<!-- JavaScript context -->
+<script>
+    var searchTerm = "${SecureEncoder.forJavaScript(pdict.searchPhrase)}";
+</script>
+
+<!-- HTML attribute -->
+<input type="hidden" value="${SecureEncoder.forHTMLAttribute(pdict.token)}" />
+```

package/dist/ai-instructions/skills/sfcc-isml-development/references/sfra-base-templates-architecture.md

@@ -0,0 +1,13 @@
+## SFRA Base Templates Architecture (Index)
+
+This reference used to be a single long document. It’s now split into smaller, on-demand files so agents can load only what’s needed.
+
+### References
+
+- [SFRA Layout Templates](SFRA-LAYOUTS.md) — decorators, `<isreplace/>`, hooks, Bootstrap 4 notes
+- [SFRA Structure & Shared Components](SFRA-STRUCTURE-COMPONENTS.md) — where templates live, composition rules, `htmlHead`, asset registration
+- [SFRA Pages: Catalog/Search](SFRA-PAGES-CATALOG.md) — homepage, PDP, search, category patterns
+- [SFRA Pages: Cart/Account/Auth](SFRA-PAGES-CART-ACCOUNT-AUTH.md) — cart, account dashboard/subpages, login/registration patterns
+
+If you need deeper examples beyond these references, use the legacy long-form doc linked from the main skill.
+

package/dist/ai-instructions/skills/sfcc-job-development/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: sfcc-job-development
+description: Guide for developing custom jobs in Salesforce B2C Commerce Job Framework. Use this when asked to create batch jobs, scheduled tasks, chunk-oriented processing, or task-oriented jobs.
+---
+
+# SFCC Job Development Skill
+
+This skill guides you through creating custom job steps for Salesforce B2C Commerce batch processing.
+
+## Quick Checklist
+
+```text
+[ ] Choose the right model: task-oriented vs chunk-oriented
+[ ] steptypes.json exists at the cartridge ROOT (not under cartridge/)
+[ ] Step script exports required functions for its step type
+[ ] All resources closed (iterators, file readers/writers) in afterStep
+[ ] Timeouts are explicit and realistic for the dataset
+[ ] Transactions scoped intentionally (avoid giant single transactions)
+```
+
+## Overview
+
+Custom job steps execute custom business logic as part of B2C Commerce jobs. Two execution models:
+
+| Model | Use Case | Progress Tracking |
+|-------|----------|-------------------|
+| **Task-oriented** | Single operations (FTP, import/export) | Limited |
+| **Chunk-oriented** | Bulk data processing | Fine-grained |
+
+## File Structure
+
+```
+my_cartridge/
+├── cartridge/
+│   ├── scripts/
+│   │   └── steps/
+│   │       ├── myTaskStep.js
+│   │       └── myChunkStep.js
+│   └── my_cartridge.properties
+└── steptypes.json  ← Must be here, NOT inside cartridge/
+```
+
+**Important:** Only one `steptypes.json` per cartridge. Must be at cartridge root.
+
+## Task-Oriented Steps
+
+Use for single operations like FTP transfers, file generation, or quick database updates.
+
+```javascript
+'use strict';
+
+var Status = require('dw/system/Status');
+var Logger = require('dw/system/Logger');
+
+exports.execute = function (parameters, stepExecution) {
+    var log = Logger.getLogger('job', 'MyTaskStep');
+
+    try {
+        var inputFile = parameters.InputFile;
+        
+        if (!parameters.Enabled) {
+            log.info('Step disabled, skipping');
+            return new Status(Status.OK, 'SKIP', 'Step disabled');
+        }
+
+        // Your business logic here
+        log.info('Processing file: ' + inputFile);
+
+        return new Status(Status.OK);
+
+    } catch (e) {
+        log.error('Step failed: ' + e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};
+```
+
+### Status Codes
+
+```javascript
+// Success
+return new Status(Status.OK);
+return new Status(Status.OK, 'CUSTOM_CODE', 'Custom message');
+
+// Error
+return new Status(Status.ERROR);
+return new Status(Status.ERROR, null, 'Error message');
+```
+
+**Important:** Custom status codes work **only** with OK status. ERROR status replaces custom codes.
+
+## Chunk-Oriented Steps
+
+Use for bulk processing of countable data (products, orders, customers).
+
+### Required Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `read()` | Get next item | Item or nothing |
+| `process(item)` | Transform item | Processed item or nothing (filters) |
+| `write(items)` | Save chunk of items | Nothing |
+
+### Optional Functions
+
+| Function | Purpose |
+|----------|---------|
+| `beforeStep()` | Initialize (open files, queries) |
+| `afterStep(success)` | Cleanup (close files) |
+| `getTotalCount()` | Return total items for progress |
+| `beforeChunk()` | Before each chunk |
+| `afterChunk()` | After each chunk |
+
+### Script Example
+
+```javascript
+'use strict';
+
+var ProductMgr = require('dw/catalog/ProductMgr');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('job', 'MyChunkStep');
+var products;
+
+exports.beforeStep = function (parameters, stepExecution) {
+    log.info('Starting chunk processing');
+    products = ProductMgr.queryAllSiteProducts();
+};
+
+exports.getTotalCount = function (parameters, stepExecution) {
+    return products.count; // Use built-in count!
+};
+
+exports.read = function (parameters, stepExecution) {
+    if (products.hasNext()) {
+        return products.next();
+    }
+    // Return nothing = end of data
+};
+
+exports.process = function (product, parameters, stepExecution) {
+    if (!product.online) {
+        return;  // Filtered out
+    }
+    return {
+        id: product.ID,
+        name: product.name,
+        price: product.priceModel.price.value
+    };
+};
+
+exports.write = function (items, parameters, stepExecution) {
+    for (var i = 0; i < items.size(); i++) {
+        var item = items.get(i);
+        // Write item...
+    }
+};
+
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (products) {
+        products.close(); // Critical: close iterators!
+    }
+    log.info(success ? 'Completed successfully' : 'Failed');
+};
+```
+
+**Important:** Chunk-oriented steps always finish with either **OK** or **ERROR**. Custom exit status codes are not supported.
+
+## steptypes.json Configuration
+
+### Task-Oriented Step
+
+```json
+{
+    "step-types": {
+        "script-module-step": [
+            {
+                "@type-id": "custom.MyTaskStep",
+                "@supports-site-context": true,
+                "@supports-organization-context": false,
+                "description": "My custom task step",
+                "module": "my_cartridge/cartridge/scripts/steps/myTaskStep.js",
+                "function": "execute",
+                "timeout-in-seconds": 900,
+                "parameters": {
+                    "parameter": [
+                        {
+                            "@name": "InputFile",
+                            "@type": "string",
+                            "@required": true,
+                            "description": "Path to input file"
+                        }
+                    ]
+                },
+                "status-codes": {
+                    "status": [
+                        { "@code": "OK", "description": "Step completed" },
+                        { "@code": "ERROR", "description": "Step failed" }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```
+
+### Chunk-Oriented Step
+
+```json
+{
+    "step-types": {
+        "chunk-script-module-step": [
+            {
+                "@type-id": "custom.MyChunkStep",
+                "@supports-site-context": true,
+                "@supports-organization-context": false,
+                "description": "Bulk data processing step",
+                "module": "my_cartridge/cartridge/scripts/steps/myChunkStep.js",
+                "before-step-function": "beforeStep",
+                "read-function": "read",
+                "process-function": "process",
+                "write-function": "write",
+                "after-step-function": "afterStep",
+                "total-count-function": "getTotalCount",
+                "chunk-size": 100,
+                "transactional": false,
+                "timeout-in-seconds": 1800
+            }
+        ]
+    }
+}
+```
+
+## Key Configuration Attributes
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `@type-id` | Yes | Unique ID (must start with `custom.`) |
+| `@supports-site-context` | No | Available in site-scoped jobs |
+| `@supports-organization-context` | No | Available in org-scoped jobs |
+| `module` | Yes | Path to script module |
+| `function` | Yes | Function name (task-oriented) |
+| `chunk-size` | Yes* | Items per chunk (*chunk steps only) |
+| `timeout-in-seconds` | No | Step timeout (recommended) |
+
+**Context Constraints:** `@supports-site-context` and `@supports-organization-context` cannot both be `true` or both be `false`.
+
+## Parameter Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `string` | Text value | `"my-value"` |
+| `boolean` | true/false | `true` |
+| `long` | Integer | `12345` |
+| `double` | Decimal | `123.45` |
+
+## Critical Performance Pattern
+
+**Use SeekableIterator's built-in count** instead of creating separate iterators:
+
+```javascript
+// ✅ CORRECT - Uses built-in count
+exports.getTotalCount = function() {
+    return products.getCount(); // Instant, no DB hit
+}
+
+// ❌ WRONG - Creates duplicate query!
+exports.getTotalCount = function() {
+    var counter = ProductMgr.queryAllSiteProducts(); // Unnecessary!
+    var count = 0;
+    while (counter.hasNext()) { counter.next(); count++; }
+    counter.close();
+    return count;
+}
+```
+
+## Best Practices
+
+1. **Use chunk-oriented** for bulk data - better progress tracking and resumability
+2. **Close resources** in `afterStep()` - queries, files, connections
+3. **Set explicit timeouts** - default may be too short
+4. **Log progress** - helps debugging
+5. **Handle errors gracefully** - return proper Status objects
+6. **Don't rely on transactional=true** - use `Transaction.wrap()` for control
+7. **Use streaming APIs** for file processing
+8. **Avoid accumulating objects** in global scope
+
+## Chunk Size Guidelines
+
+| Operation Type | Recommended Size |
+|----------------|------------------|
+| Simple attribute updates | 500-1000 |
+| Complex object creation | 100-300 |
+| File I/O operations | 200-500 |
+| General operations | 250 |
+
+### How to Choose a Chunk Size (Beyond Rules of Thumb)
+
+- **Processing complexity**: complex per-record logic (extra lookups, multiple writes) usually needs smaller chunks.
+- **Memory behavior**: if memory grows with chunk size, shrink chunks and ensure references are released after `write`.
+- **Optimistic locking risk**: for “high contention” objects (e.g., profiles that can be updated by storefront traffic), smaller chunks reduce the blast radius of failures and make retries cheaper.
+
+### `transactional` Setting Guidance
+
+Keep `"transactional": false` in `steptypes.json` unless you have a very specific requirement.
+
+- When `transactional` is enabled, the platform can treat the step as one large transaction, increasing rollback risk on errors.
+- Prefer explicit, local `Transaction.wrap()` scopes inside `process` or `write` to control what is committed and when.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| OutOfMemoryError | Use streaming APIs, close iterators, reduce chunk size |
+| ScriptingTimeoutError | Use chunk-oriented model, review algorithm |
+| Transaction timeouts | Reduce chunk size, commit per chunk |
+| Job not visible in BM | Check code version is active |
+
+## Related Skills
+
+- **[sfcc-logging](../sfcc-logging/SKILL.md)** - Comprehensive logging patterns, custom log files, NDC tracing. Essential for job debugging and monitoring.
+
+## Detailed References
+
+- [Task-Oriented Steps](references/TASK-ORIENTED.md) - Full task step patterns
+- [Chunk-Oriented Steps](references/CHUNK-ORIENTED.md) - Full chunk step patterns
+- [steptypes.json Reference](references/STEPTYPES-JSON.md) - Complete schema
+
+External reading:
+- Rhino Inquisitor: Mastering Chunk-Oriented Job Steps
+    - https://www.rhino-inquisitor.com/mastering-chunk-oriented-job-steps-in-salesforce-b2c-commerce-cloud/
+- Salesforce Docs: Custom job steps (chunk-oriented)
+    - https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-job-steps.html