sfcc-dev-mcp 1.0.15 → 1.0.19

package/dist/ai-instructions/skills/sfcc-job-development/references/CHUNK-ORIENTED.md

@@ -0,0 +1,393 @@
+# Chunk-Oriented Job Steps Reference
+
+Complete reference for chunk-oriented (chunk-script-module-step) job development in SFCC.
+
+## When to Use Chunk-Oriented Jobs
+
+Choose chunk-oriented jobs for:
+- Processing large datasets (>1000 items)
+- Iterating over products, orders, customers, or file rows
+- When progress monitoring is required
+- When failure resilience is critical
+- When transaction control is important
+
+## Lifecycle Functions
+
+### Required Functions (Data Pipeline)
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `read()` | Get next item from data source | Item or nothing (signals end) |
+| `process(item)` | Transform item | Processed item or nothing (filters out) |
+| `write(items)` | Save chunk of items | Nothing |
+
+### Optional Functions
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `beforeStep()` | Initialize (open files, queries) | Nothing |
+| `afterStep(success)` | Cleanup (close files) | Nothing |
+| `getTotalCount()` | Return total items for progress | Number |
+| `beforeChunk()` | Before each chunk | Nothing |
+| `afterChunk()` | After each chunk | Nothing |
+
+## Complete Script Example
+
+```javascript
+'use strict';
+
+var File = require('dw/io/File');
+var FileReader = require('dw/io/FileReader');
+var CSVStreamReader = require('dw/io/CSVStreamReader');
+var ProductMgr = require('dw/catalog/ProductMgr');
+var Transaction = require('dw/system/Transaction');
+var Logger = require('dw/system/Logger');
+
+var csvReader;
+var totalLines = 0;
+var processedLines = 0;
+var logger = Logger.getLogger('jobs', 'BulkProductUpdate');
+
+/**
+ * Setup function - opens input file and prepares for processing
+ */
+exports.beforeStep = function (parameters, stepExecution) {
+    try {
+        var inputFile = new File(File.IMPEX + parameters.inputFileName);
+        if (!inputFile.exists()) {
+            throw new Error('Input file not found: ' + parameters.inputFileName);
+        }
+        
+        var fileReader = new FileReader(inputFile);
+        csvReader = new CSVStreamReader(fileReader);
+        
+        // Skip header row if present
+        if (parameters.hasHeader === 'true') {
+            csvReader.readNext();
+        }
+        
+        logger.info('Started processing file: {0}', parameters.inputFileName);
+        
+    } catch (e) {
+        logger.error('Setup failed: {0}', e.message);
+        throw e;
+    }
+};
+
+/**
+ * Returns total count for progress monitoring
+ */
+exports.getTotalCount = function (parameters, stepExecution) {
+    return totalLines > 0 ? totalLines : null;
+};
+
+/**
+ * Reads next item from data source
+ * @returns {Object|null} Next item or null when finished
+ */
+exports.read = function (parameters, stepExecution) {
+    var line = csvReader.readNext();
+    if (line && line.length > 0) {
+        return {
+            productID: line[0],
+            newOnlineStatus: line[1] === 'true',
+            lineNumber: ++processedLines
+        };
+    }
+    return null; // Signals end of data
+};
+
+/**
+ * Processes a single item
+ * @param {Object} item - Item from read()
+ * @returns {Object|null} Processed item or null to filter out
+ */
+exports.process = function (item, parameters, stepExecution) {
+    try {
+        var product = ProductMgr.getProduct(item.productID);
+        if (!product) {
+            return {
+                productID: item.productID,
+                status: 'ERROR',
+                message: 'Product not found',
+                lineNumber: item.lineNumber
+            };
+        }
+        
+        if (typeof item.newOnlineStatus !== 'boolean') {
+            return {
+                productID: item.productID,
+                status: 'SKIPPED',
+                message: 'Invalid online status value',
+                lineNumber: item.lineNumber
+            };
+        }
+        
+        return {
+            product: product,
+            productID: item.productID,
+            newOnlineStatus: item.newOnlineStatus,
+            status: 'READY',
+            lineNumber: item.lineNumber
+        };
+        
+    } catch (e) {
+        logger.warn('Error processing product {0}: {1}', item.productID, e.message);
+        return {
+            productID: item.productID,
+            status: 'ERROR',
+            message: e.message,
+            lineNumber: item.lineNumber
+        };
+    }
+};
+
+/**
+ * Writes a chunk of processed items
+ * @param {dw.util.ArrayList} chunk - Collection of processed items
+ */
+exports.write = function (chunk, parameters, stepExecution) {
+    var successCount = 0;
+    var errorCount = 0;
+    
+    for (var i = 0; i < chunk.size(); i++) {
+        var item = chunk.get(i);
+        
+        if (item.status === 'READY') {
+            try {
+                item.product.setOnlineFlag(item.newOnlineStatus);
+                successCount++;
+            } catch (e) {
+                errorCount++;
+                logger.error('Failed to update product {0}: {1}', item.productID, e.message);
+            }
+        } else {
+            errorCount++;
+        }
+    }
+    
+    logger.info('Chunk processed: {0} success, {1} errors', successCount, errorCount);
+};
+
+/**
+ * Pre-chunk setup to begin a transaction
+ */
+exports.beforeChunk = function (parameters, stepExecution) {
+    Transaction.begin();
+};
+
+/**
+ * Commits transaction after successful chunk processing
+ */
+exports.afterChunk = function (parameters, stepExecution) { 
+    Transaction.commit();
+};
+
+/**
+ * Cleanup function - closes resources
+ */
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (csvReader) {
+        csvReader.close();
+    }
+    
+    logger.info('Processing completed. Total lines processed: {0}', processedLines);
+    
+    if (!success) {
+        logger.error('Job completed with errors');
+    }
+};
+```
+
+## SeekableIterator Optimization (Critical)
+
+**ALWAYS** use the SeekableIterator's built-in count property instead of creating separate iterators for counting.
+
+### ✅ OPTIMAL Pattern
+
+```javascript
+var products; // Declare at module level
+
+exports.beforeStep = function(parameters) {
+    products = ProductMgr.queryAllSiteProductsSorted(); // Single query
+}
+
+exports.getTotalCount = function() {
+    if (products && products.getCount) {
+        var totalCount = products.getCount(); // Instant, no DB hit
+        return totalCount >= 0 ? totalCount : null;
+    }
+    return null;
+}
+
+exports.read = function() {
+    return products.hasNext() ? products.next() : null;
+}
+```
+
+### ❌ ANTI-PATTERN (Avoid!)
+
+```javascript
+// Creates TWO expensive database queries!
+exports.getTotalCount = function() {
+    var counter = ProductMgr.queryAllSiteProducts(); // Unnecessary Query #1
+    var count = 0;
+    while (counter.hasNext()) { counter.next(); count++; } // Manual counting!
+    counter.close();
+    return count;
+}
+
+exports.read = function() {
+    if (!products) {
+        products = ProductMgr.queryAllSiteProductsSorted(); // Query #2
+    }
+    return products.hasNext() ? products.next() : null;
+}
+```
+
+**Performance Impact:** The anti-pattern increases database load by **100%** and can add **1-5 minutes** to job startup for large catalogs.
+
+## Transaction Per Chunk Pattern
+
+```javascript
+exports.beforeChunk = function (parameters, stepExecution) {
+    Transaction.begin();
+};
+
+exports.write = function (chunk, parameters, stepExecution) {
+    for (var i = 0; i < chunk.size(); i++) {
+        var item = chunk.get(i);
+        updateDatabaseObject(item);
+    }
+};
+
+exports.afterChunk = function (parameters, stepExecution) {
+    try {
+        Transaction.commit();
+    } catch (e) {
+        Transaction.rollback();
+        throw e;
+    }
+};
+```
+
+## steptypes.json Configuration
+
+```json
+{
+    "step-types": {
+        "chunk-script-module-step": [
+            {
+                "@type-id": "custom.BulkProductUpdate",
+                "@supports-parallel-execution": false,
+                "@supports-site-context": true,
+                "@supports-organization-context": false,
+                "description": "Updates product online status from CSV file in chunks",
+                "module": "plugin_examplecartridge/cartridge/scripts/jobs/bulkProductUpdate.js",
+                "before-step-function": "beforeStep",
+                "total-count-function": "getTotalCount",
+                "before-chunk-function": "beforeChunk",
+                "read-function": "read",
+                "process-function": "process",
+                "write-function": "write",
+                "after-chunk-function": "afterChunk",
+                "after-step-function": "afterStep",
+                "chunk-size": 200,
+                "transactional": false,
+                "parameters": {
+                    "parameter": [
+                        {
+                            "@name": "inputFileName",
+                            "@type": "string",
+                            "@required": true,
+                            "description": "Name of CSV file in IMPEX folder"
+                        },
+                        {
+                            "@name": "hasHeader",
+                            "@type": "boolean",
+                            "@required": false,
+                            "description": "Whether CSV file has header row"
+                        }
+                    ]
+                },
+                "status-codes": {
+                    "status": [
+                        { "@code": "OK", "description": "Processing completed successfully" },
+                        { "@code": "ERROR", "description": "An error occurred during processing" }
+                    ]
+                }
+            }
+        ]
+    }
+}
+```
+
+## Chunk-Specific Attributes
+
+| Attribute | Required | Description | Default |
+|-----------|----------|-------------|---------|
+| `before-step-function` | No | Setup function before processing starts | None |
+| `total-count-function` | No | Returns total items for progress tracking | None |
+| `before-chunk-function` | No | Setup before each chunk | None |
+| `read-function` | No | Reads next item from data source | `read` |
+| `process-function` | No | Processes individual items | `process` |
+| `write-function` | No | Writes processed chunk | `write` |
+| `after-chunk-function` | No | Cleanup after each chunk | None |
+| `after-step-function` | No | Final cleanup after all chunks | None |
+| `chunk-size` | **Yes** | Number of items per chunk | Must be > 0 |
+
+## Chunk Size Guidelines
+
+| Operation Type | Recommended Chunk Size |
+|----------------|------------------------|
+| Simple attribute updates | 500-1000 items |
+| Complex object creation | 100-300 items |
+| File I/O operations | 200-500 items |
+| General operations | 250 items (good balance) |
+
+## Memory Management
+
+### Always Use Streaming APIs
+
+```javascript
+// ❌ WRONG: Loading entire file into memory
+var content = new FileReader(file).readBytes();
+var lines = content.toString().split('\n');
+
+// ✅ CORRECT: Stream processing
+var csvReader = new CSVStreamReader(new FileReader(file));
+var line;
+while ((line = csvReader.readNext()) !== null) {
+    // Process one line at a time
+}
+csvReader.close();
+```
+
+### Always Close Iterators
+
+```javascript
+exports.afterStep = function (success, parameters, stepExecution) {
+    if (csvReader) csvReader.close();
+    if (xmlReader) xmlReader.close();
+    if (iterator) iterator.close(); // Critical: prevents memory leaks
+};
+```
+
+### Avoid Object Accumulation
+
+```javascript
+// ❌ WRONG: Accumulating objects
+var allProducts = [];
+while (products.hasNext()) {
+    allProducts.push(products.next()); // Memory grows linearly
+}
+
+// ✅ CORRECT: Process and release
+while (products.hasNext()) {
+    var product = products.next();
+    processProduct(product);
+    // Product reference goes out of scope
+}
+```
+
+**Important:** Chunk-oriented steps always finish with either **OK** or **ERROR**. Custom exit status codes are not supported for chunk steps.

package/dist/ai-instructions/skills/sfcc-job-development/references/STEPTYPES-JSON.md

@@ -0,0 +1,271 @@
+# steptypes.json Reference
+
+Complete schema and configuration reference for SFCC job step type definitions.
+
+## File Placement
+
+**Critical Requirements:**
+- File must be named **exactly** `steptypes.json`
+- Must be placed in the **root folder** of your custom cartridge (not inside the cartridge subfolder)
+- Only **one** `steptypes.json` file per cartridge is allowed
+- Cannot coexist with `steptypes.xml` - choose one format only
+
+**Correct File Structure:**
+```
+my_cartridge/
+├── cartridge/
+│   ├── controllers/
+│   ├── scripts/
+│   │   └── steps/
+│   │       ├── myTaskStep.js
+│   │       └── myChunkStep.js
+│   └── my_cartridge.properties
+└── steptypes.json ← Must be here, NOT inside cartridge/
+```
+
+## Root Structure
+
+```json
+{
+  "step-types": {
+    "script-module-step": [],
+    "chunk-script-module-step": [],
+    "pipeline-step": []
+  }
+}
+```
+
+**Note**: At least one step type category must be defined, but all three are optional.
+
+## Parameter Types
+
+| Type | Description | Example Value |
+|------|-------------|---------------|
+| `string` | Text value | `"my-value"` |
+| `boolean` | true/false | `true` |
+| `long` | Integer | `12345` |
+| `double` | Decimal | `123.45` |
+| `datetime-string` | ISO datetime | `"2024-01-15T10:30:00Z"` |
+| `date-string` | ISO date | `"2024-01-15"` |
+| `time-string` | ISO time | `"10:30:00"` |
+
+## Parameter Validation Attributes
+
+| Attribute | Applies To | Description |
+|-----------|------------|-------------|
+| `@trim` | All | Trim whitespace before validation (default: `true`) |
+| `@required` | All | Mark as required (default: `true`) |
+| `@target-type` | datetime-string, date-string, time-string | Convert to `long` or `date` (default: `date`) |
+| `pattern` | string | Regex pattern for validation |
+| `min-length` | string | Minimum string length (must be ≥1) |
+| `max-length` | string | Maximum string length (max 1000 chars total) |
+| `min-value` | long, double, datetime-string, time-string | Minimum numeric value |
+| `max-value` | long, double, datetime-string, time-string | Maximum numeric value |
+| `enum-values` | All | Restrict to allowed values (dropdown in BM) |
+
+## Script-Module-Step Attributes
+
+| Attribute | Required | Description | Default |
+|-----------|----------|-------------|---------|
+| `@type-id` | **Yes** | Unique ID (must start with `custom.`, max 100 chars) | - |
+| `@supports-parallel-execution` | No | Allow parallel execution | `true` |
+| `@supports-site-context` | No | Available in site-scoped jobs | `true` |
+| `@supports-organization-context` | No | Available in org-scoped jobs | `true` |
+| `description` | No | Internal description (not shown in BM) | - |
+| `module` | **Yes** | Path to script module | - |
+| `function` | **Yes** | Function name to execute | `execute` |
+| `transactional` | No | Wrap in single transaction | `false` |
+| `timeout-in-seconds` | No | Step timeout | - |
+
+## Chunk-Script-Module-Step Attributes
+
+All script-module-step attributes plus:
+
+| Attribute | Required | Description | Default |
+|-----------|----------|-------------|---------|
+| `before-step-function` | No | Setup function name | None |
+| `total-count-function` | No | Progress tracking function | None |
+| `before-chunk-function` | No | Pre-chunk function | None |
+| `read-function` | No | Read next item function | `read` |
+| `process-function` | No | Process item function | `process` |
+| `write-function` | No | Write chunk function | `write` |
+| `after-chunk-function` | No | Post-chunk function | None |
+| `after-step-function` | No | Cleanup function | None |
+| `chunk-size` | **Yes** | Items per chunk | Must be > 0 |
+
+## Complete Task-Oriented Example
+
+```json
+{
+  "step-types": {
+    "script-module-step": [
+      {
+        "@type-id": "custom.DeactivateProducts",
+        "@supports-parallel-execution": true,
+        "@supports-site-context": true,
+        "@supports-organization-context": false,
+        "description": "Deactivates all online products in a specified category",
+        "module": "plugin_examplecartridge/cartridge/scripts/jobs/deactivateProducts.js",
+        "function": "execute",
+        "transactional": false,
+        "timeout-in-seconds": 900,
+        "parameters": {
+          "parameter": [
+            {
+              "@name": "categoryID",
+              "@type": "string",
+              "@required": true,
+              "description": "ID of the category containing products to deactivate"
+            },
+            {
+              "@name": "dryRun",
+              "@type": "boolean", 
+              "@required": false,
+              "description": "If true, only logs what would be deactivated"
+            }
+          ]
+        },
+        "status-codes": {
+          "status": [
+            { "@code": "OK", "description": "Products deactivated successfully" },
+            { "@code": "ERROR", "description": "An error occurred during processing" }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Complete Chunk-Oriented Example
+
+```json
+{
+  "step-types": {
+    "chunk-script-module-step": [
+      {
+        "@type-id": "custom.BulkPriceUpdate",
+        "@supports-parallel-execution": false,
+        "@supports-site-context": true,
+        "@supports-organization-context": false,
+        "description": "Updates product prices from CSV file in chunks",
+        "module": "plugin_examplecartridge/cartridge/scripts/jobs/bulkPriceUpdate.js",
+        "before-step-function": "beforeStep",
+        "total-count-function": "getTotalCount",
+        "before-chunk-function": "beforeChunk",
+        "read-function": "read",
+        "process-function": "process",
+        "write-function": "write",
+        "after-chunk-function": "afterChunk",
+        "after-step-function": "afterStep",
+        "chunk-size": 200,
+        "transactional": false,
+        "timeout-in-seconds": 1800,
+        "parameters": {
+          "parameter": [
+            {
+              "@name": "inputFileName",
+              "@type": "string",
+              "@required": true,
+              "min-length": 1,
+              "max-length": 255,
+              "description": "Name of CSV file in IMPEX folder"
+            },
+            {
+              "@name": "hasHeader",
+              "@type": "boolean",
+              "@required": false,
+              "default-value": "true",
+              "description": "Whether CSV file has header row"
+            },
+            {
+              "@name": "priceMultiplier",
+              "@type": "double",
+              "@required": false,
+              "min-value": 0.01,
+              "max-value": 100.0,
+              "default-value": "1.0",
+              "description": "Factor to multiply prices by"
+            }
+          ]
+        },
+        "status-codes": {
+          "status": [
+            { "@code": "OK", "description": "Processing completed successfully" },
+            { "@code": "ERROR", "description": "An error occurred during processing" }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Parameter with Enum Values
+
+```json
+{
+  "@name": "exportFormat",
+  "@type": "string",
+  "@required": true,
+  "description": "Output format for export",
+  "enum-values": {
+    "value": ["CSV", "XML", "JSON"]
+  }
+}
+```
+
+## Pipeline Step (Legacy)
+
+```json
+{
+  "step-types": {
+    "pipeline-step": [
+      {
+        "@type-id": "custom.LegacyPipelineStep",
+        "@supports-site-context": true,
+        "@supports-organization-context": false,
+        "description": "Legacy pipeline step",
+        "pipeline": "cartridge/pipelines/jobs/LegacyPipeline.xml",
+        "start-node": "Start"
+      }
+    ]
+  }
+}
+```
+
+**Note**: Pipeline steps are legacy - use script-module-step or chunk-script-module-step for new development.
+
+## Context Constraints
+
+**Important:** `@supports-site-context` and `@supports-organization-context` cannot both be `true` or both be `false` - one must be `true` and the other `false`.
+
+## Status Codes
+
+Custom status codes enable flow control in Business Manager:
+
+```json
+{
+  "status-codes": {
+    "status": [
+      { "@code": "OK", "description": "Standard success" },
+      { "@code": "NO_DATA", "description": "No data to process" },
+      { "@code": "PARTIAL", "description": "Partial completion" },
+      { "@code": "ERROR", "description": "Processing failed" }
+    ]
+  }
+}
+```
+
+**Task-Oriented:** Custom status codes work only with `Status.OK`. If used with `Status.ERROR`, the custom code is replaced with `ERROR`.
+
+**Chunk-Oriented:** Only `OK` or `ERROR` status is supported. Custom codes are not available.
+
+## Validation Rules Summary
+
+- `@type-id`: Must start with `custom.`, max 100 chars, no whitespace, unique across all cartridges
+- `@type-id`: Cannot conflict with system step types like `ExecutePipeline` or `IncludeStepsFromJob`
+- `description`: Max 4000 characters
+- `module` and `function`: No leading/trailing whitespace
+- `chunk-size`: Must be numeric > 0
+- Status codes: Cannot contain commas, wildcards, or exceed 100 characters