Is sfcc-script-evaluation safe to install?

SaferSkills independently audited sfcc-script-evaluation (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

ai-instructions/skills/sfcc-script-evaluation/SKILL.md · 1 file

ai-instructions/skills/sfcc-script-evaluation/SKILL.md9.7 KB · Markdown

name: sfcc-script-evaluation

description: Guide for using the evaluate_script tool to execute JavaScript on SFCC instances via the script debugger

SFCC Script Evaluation Skill

This skill documents how to use the evaluate_script tool effectively for executing JavaScript code on an SFCC instance via the script debugger.

Overview

The evaluate_script tool allows you to execute arbitrary JavaScript code on an SFCC sandbox instance. It works by:

Creating a debugger session
Setting a breakpoint on a controller
Triggering the controller via HTTP
Evaluating your expression in the halted context
Returning the result and cleaning up

Required Parameters

Parameter	Required	Default	Description
`script`	Yes	-	The JavaScript code to execute
`siteId`	No	`RefArch`	The site ID (accepts either `RefArch` or `Sites-RefArch-Site`)
`locale`	No	`default`	Storefront locale segment used when triggering the controller (tries without locale first, then retries with `/{locale}` if needed)
`timeout`	No	`30000`	Maximum execution time in milliseconds
`breakpointFile`	No	Auto-detected	Custom controller path for breakpoint
`breakpointLine`	No	`1,10,20,30,40,50`	Specific line for a single breakpoint; if omitted, strategic lines (1,10,20,30,40,50) are used
`triggerUrl`	No	Auto-detected	Custom storefront URL or path to trigger; site-relative paths are resolved to `https://{hostname}/s/{siteId}/...`

Script Syntax Rules

✅ DO: Use expressions that return a value

The last expression in your script is returned as the result.

// Simple expressions
1 + 1
// Result: 2

dw.system.Site.current.ID
// Result: "RefArchGlobal"

❌ DON'T: Use `return` at the top level

// WRONG - causes compilation error
return 1 + 1

// Error: "invalid return"

❌ DON'T: Use `var` assignments expecting the variable

// WRONG - var declarations return null in debugger context
var result = {}; result.foo = 'bar';

// Error: Cannot set property "foo" of null

✅ DO: Use inline object literals with JSON.stringify

// CORRECT - inline object literal wrapped in JSON.stringify
JSON.stringify({siteId: dw.system.Site.current.ID, locale: request.locale})
// Result: {"siteId":"RefArchGlobal","locale":"en_GB"}

✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic

// CORRECT - IIFE pattern for multi-step logic
(function() {
  var p = dw.catalog.ProductMgr.getProduct('25518704M');
  return JSON.stringify({id: p.ID, name: p.name, online: p.online});
})()
// Result: {"id":"25518704M","name":"Pull On Pant","online":true}

❌ DON'T: Use `require()` statements

// WRONG - require() returns null in debugger context
var CustomerMgr = require('dw/customer/CustomerMgr');
CustomerMgr.getSiteCustomerList()

// Error: Cannot call method "getSiteCustomerList" of null

✅ DO: Use global `dw.*` namespace directly

// CORRECT - access SFCC APIs via global dw namespace
dw.customer.CustomerMgr.getSiteCustomerList().ID
// Result: "RefArch"

Accessing SFCC Objects

Site Information

// Current site ID
dw.system.Site.current.ID

// All sites
(function() {
  var sites = dw.system.Site.getAllSites();
  var result = [];
  for (var i = 0; i < sites.size(); i++) {
    result.push(sites[i].ID);
  }
  return JSON.stringify(result);
})()

// Site preferences (list all custom preference keys)
JSON.stringify(Object.keys(dw.system.Site.current.preferences.custom))

// Get specific site preference value
dw.system.Site.current.preferences.custom.myPreferenceName

Products

// Get product by ID
dw.catalog.ProductMgr.getProduct('productId')

// Get product details
(function() {
  var p = dw.catalog.ProductMgr.getProduct('25518704M');
  if (!p) return 'Product not found';
  return JSON.stringify({
    id: p.ID,
    name: p.name,
    online: p.online,
    brand: p.brand
  });
})()

// Product custom attributes
(function() {
  var p = dw.catalog.ProductMgr.getProduct('25518704M');
  return JSON.stringify(Object.keys(p.custom));
})()

Customers

// Site customer list
dw.customer.CustomerMgr.getSiteCustomerList().ID

// Get customer by ID (requires customer number)
dw.customer.CustomerMgr.getCustomerByCustomerNumber('00001234')

Orders

// Search orders (always close the iterator!)
(function() {
  var orders = dw.order.OrderMgr.searchOrders(
    'orderNo != {0}',
    'creationDate desc',
    ''
  );
  var result = [];
  var i = 0;
  while (orders.hasNext() && i < 5) {
    var o = orders.next();
    result.push({
      orderNo: o.orderNo,
      status: o.status.value,
      total: o.totalGrossPrice.value
    });
    i++;
  }
  orders.close(); // IMPORTANT: Always close iterators
  return JSON.stringify(result);
})()

Request/Session Context

// Current request locale
request.locale
// Result: "en_GB"

// Session ID
session.sessionID

// Current customer (if logged in)
session.customer

Working with Collections

SFCC collections need special handling - they're not JavaScript arrays.

Iterating Collections

// Using size() and index access
(function() {
  var sites = dw.system.Site.getAllSites();
  var result = [];
  for (var i = 0; i < sites.size(); i++) {
    result.push(sites[i].ID);
  }
  return JSON.stringify(result);
})()

// Using Iterator pattern
(function() {
  var iter = dw.catalog.CatalogMgr.getSiteCatalog().getRoot().getSubCategories();
  var result = [];
  while (iter.hasNext()) {
    var cat = iter.next();
    result.push({id: cat.ID, name: cat.displayName});
  }
  return JSON.stringify(result);
})()

Array Operations

// Arrays work normally, use JSON.stringify for readable output
JSON.stringify([1, 2, 3].map(function(x) { return x * 2; }))
// Result: [2,4,6]

// Arrow functions are supported
JSON.stringify([1, 2, 3].map(x => x * 2))
// Result: [2,4,6]

Return Value Formatting

Primitives

// Strings, numbers, booleans return directly
'hello'
// Result: "hello"

42
// Result: 42

true
// Result: true

Objects

// Raw objects return [object Object]
({foo: 'bar'})
// Result: [object Object]

// Use JSON.stringify for readable output
JSON.stringify({foo: 'bar'})
// Result: {"foo":"bar"}

SFCC Objects

// SFCC objects return their string representation
dw.catalog.ProductMgr.getProduct('25518704M')
// Result: [Product sku=25518704M]

// Access properties directly or use JSON.stringify
dw.catalog.ProductMgr.getProduct('25518704M').name
// Result: "Pull On Pant"

Error Handling

Check for null values

// WRONG - throws error if product doesn't exist
dw.catalog.ProductMgr.getProduct('invalid').name
// Error: Cannot read property "name" from null

// CORRECT - check for null
(function() {
  var p = dw.catalog.ProductMgr.getProduct('invalid');
  return p ? p.name : 'Product not found';
})()
// Result: "Product not found"

Wrap complex logic in try-catch

(function() {
  try {
    var p = dw.catalog.ProductMgr.getProduct('25518704M');
    return JSON.stringify({id: p.ID, name: p.name});
  } catch (e) {
    return 'Error: ' + e.message;
  }
})()

Best Practices Summary

Never use `return` at top level - use expression evaluation instead
Never use `require()` - use global dw.* namespace
Wrap complex logic in IIFEs for variable declarations
Use `JSON.stringify()` for object/array output
Close iterators after use (OrderMgr.searchOrders, etc.)
Check for null before accessing properties
Verify API usage with get_sfcc_class_info tool before calling unknown methods

Common Patterns

Quick Value Check

dw.system.Site.current.ID

Multi-Value Query

JSON.stringify({
  siteId: dw.system.Site.current.ID,
  locale: request.locale,
  customerList: dw.customer.CustomerMgr.getSiteCustomerList().ID
})

Complex Data Retrieval

(function() {
  // Your multi-step logic here
  var result = [];
  // ... build result ...
  return JSON.stringify(result);
})()

Troubleshooting

Error	Cause	Solution
`invalid return`	Using `return` at top level	Remove `return`, use expression or IIFE
`Cannot call method of null`	Using `require()`	Use `dw.*` global namespace
`Cannot set property of null`	`var x = {}` returns null	Use IIFE or inline object literal
`Timeout waiting for breakpoint`	Wrong siteId or instance unreachable	Verify siteId, check instance connectivity
`Unexpected token '<'`	Auth/connectivity issue	Check dw.json credentials, verify instance is accessible
`Unauthorized` / `401`	Username case mismatch	Username is case-sensitive - match exactly from BM user
`No compatible storefront cartridge`	Missing SFRA or SiteGenesis	Deploy app_storefront_base or specify custom breakpoint

Pre-Flight Checklist

Before using evaluate_script:

✅ Valid credentials in dw.json configuration
✅ Username matches BM user exactly (case-sensitive!)
✅ Sandbox instance is accessible
✅ Storefront cartridge deployed (app_storefront_base or app_storefront_controllers)
✅ Script uses dw.* namespace, not require()
✅ Complex logic wrapped in IIFE
✅ Objects/arrays wrapped in JSON.stringify()

Requirements

SFCC sandbox instance
Either app_storefront_base (SFRA) or app_storefront_controllers (SiteGenesis) deployed
Valid credentials in dw.json configuration
Important: Username in dw.json must match BM user exactly (case-sensitive)

sfcc-script-evaluation— agent skill

Is sfcc-script-evaluation safe to install?

SFCC Script Evaluation Skill

Overview

Required Parameters

Script Syntax Rules

✅ DO: Use expressions that return a value

❌ DON'T: Use `return` at the top level

❌ DON'T: Use `var` assignments expecting the variable

✅ DO: Use inline object literals with JSON.stringify

✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic

❌ DON'T: Use `require()` statements

✅ DO: Use global `dw.*` namespace directly

Accessing SFCC Objects

Site Information

Products

Customers

Orders

Request/Session Context

Working with Collections

Iterating Collections

Array Operations

Return Value Formatting

Primitives

Objects

SFCC Objects

Error Handling

Check for null values

Wrap complex logic in try-catch

Best Practices Summary

Common Patterns

Quick Value Check

Multi-Value Query

Complex Data Retrieval

Troubleshooting

Pre-Flight Checklist

Requirements

Audit the pieces. Scan the whole. Decide.

Is sfcc-script-evaluation safe to install?

SFCC Script Evaluation Skill

Overview

Required Parameters

Script Syntax Rules

✅ DO: Use expressions that return a value

❌ DON'T: Use return at the top level

❌ DON'T: Use var assignments expecting the variable

✅ DO: Use inline object literals with JSON.stringify

✅ DO: Use IIFEs (Immediately Invoked Function Expressions) for complex logic

❌ DON'T: Use require() statements

✅ DO: Use global dw.* namespace directly

Accessing SFCC Objects

Site Information

Products

Customers

Orders

Request/Session Context

Working with Collections

Iterating Collections

Array Operations

Return Value Formatting

Primitives

Objects

SFCC Objects

Error Handling

Check for null values

Wrap complex logic in try-catch

Best Practices Summary

Common Patterns

Quick Value Check

Multi-Value Query

Complex Data Retrieval

Troubleshooting

Pre-Flight Checklist

Requirements

Audit the pieces. Scan the whole. Decide.

❌ DON'T: Use `return` at the top level

❌ DON'T: Use `var` assignments expecting the variable

❌ DON'T: Use `require()` statements

✅ DO: Use global `dw.*` namespace directly