/**
* SFCC Script Debugger Client
*
* Provides script evaluation capabilities using the SFCC Script Debugger API.
* This client handles the complete workflow: creating debug sessions, setting breakpoints,
* triggering script execution, evaluating expressions, and cleanup.
*
* This implementation uses the existing Default-Start endpoint from app_storefront_base,
* eliminating the need to upload custom scripts.
*/
import { createClient, WebDAVClient } from 'webdav';
import { Logger } from '../../utils/logger.js';
import { SFCCConfig } from '../../types/types.js';
/** Default timeout for script evaluation in milliseconds */
const DEFAULT_TIMEOUT_MS = 30000;
/** Default site ID if none provided */
const DEFAULT_SITE_ID = 'RefArch';
/** Default locale if none provided */
const DEFAULT_LOCALE = 'default';
/** Polling interval when waiting for halted thread */
const POLL_INTERVAL_MS = 500;
/** Timeout for the storefront trigger request (short - we expect it to hang at breakpoint) */
const TRIGGER_TIMEOUT_MS = 10000;
/**
* Result of a script evaluation
*/
export interface ScriptEvaluationResult {
success: boolean;
result?: string;
error?: string;
executionTimeMs?: number;
warnings?: string[];
}
/**
* Script thread from debugger API
*/
interface ScriptThread {
id: number;
status: 'halted' | 'running';
call_stack?: Array<{
index: number;
location: {
function_name: string;
line_number: number;
script_path: string;
};
}>;
}
/**
* Debugger API response types
*/
interface ThreadsResponse {
_v: string;
script_threads?: ScriptThread[];
}
interface EvalResponse {
_v: string;
expression: string;
result: string;
}
interface FaultResponse {
_v: string;
fault?: {
type: string;
message: string;
};
}
/** Strategic breakpoint lines to catch executable code without overhead */
const DEFAULT_BREAKPOINT_LINES = [1, 10, 20, 30, 40, 50];
/**
* Cartridge configuration for breakpoint targeting
*/
interface CartridgeConfig {
cartridge: string;
controllerPath: string;
/** Single line or array of lines for breakpoints */
breakpointLines: number | number[];
type: 'sfra' | 'sitegenesis';
}
/** SFRA cartridge configuration */
const SFRA_CONFIG: CartridgeConfig = {
cartridge: 'app_storefront_base',
controllerPath: '/cartridge/controllers/Default.js',
breakpointLines: DEFAULT_BREAKPOINT_LINES, // Lines 1-50 to catch executable code
type: 'sfra',
};
/** SiteGenesis cartridge configuration */
const SITEGENESIS_CONFIG: CartridgeConfig = {
cartridge: 'app_storefront_controllers',
controllerPath: '/cartridge/controllers/Default.js',
breakpointLines: DEFAULT_BREAKPOINT_LINES, // Lines 1-50 to catch executable code
type: 'sitegenesis',
};
/**
* SFCC Script Debugger Client
*
* Orchestrates script evaluation through the Script Debugger API workflow:
* 1. Create debugger client session
* 2. Set breakpoint on Default.js controller
* 3. Trigger Default-Start via HTTP
* 4. Wait for thread to halt at breakpoint
* 5. Evaluate user's expression in halted context
* 6. Resume thread and cleanup
*
* Supports both SFRA (app_storefront_base) and SiteGenesis (app_storefront_controllers).
*/
export class ScriptDebuggerClient {
private readonly config: SFCCConfig;
private readonly logger: Logger;
private readonly debuggerClientId = 'sfcc-mcp-evaluator';
private readonly debuggerBaseUrl: string;
private readonly protocol: 'http' | 'https';
private cachedAuthHeader: string | null = null;
private webdavClient: WebDAVClient | null = null;
private isDebuggerEnabled = false;
// Active cartridge config - determined at runtime based on what exists
private activeCartridgeConfig: CartridgeConfig | null = null;
constructor(config: SFCCConfig, logger?: Logger) {
this.config = config;
this.logger = logger ?? Logger.getChildLogger('ScriptDebugger');
this.protocol = config.hostname?.startsWith('localhost') ? 'http' : 'https';
this.debuggerBaseUrl = `${this.protocol}://${config.hostname}/s/-/dw/debugger/v2_0`;
}
/**
* Evaluate a script/expression on the SFCC instance
*
* This method handles the entire workflow automatically:
* - Sets up debugger session
* - Sets breakpoint on Default-Start (or custom file/line)
* - Triggers execution and captures result
* - Cleans up all resources
*
* @param script The JavaScript code to evaluate
* @param options Optional configuration for the evaluation
*/
async evaluateScript(
script: string,
options: {
timeout?: number;
siteId?: string;
locale?: string;
breakpointFile?: string;
breakpointLine?: number;
} = {},
): Promise<ScriptEvaluationResult> {
const startTime = Date.now();
const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
const siteId = options.siteId ?? DEFAULT_SITE_ID;
const locale = this.normalizeLocale(options.locale ?? DEFAULT_LOCALE);
const warnings: string[] = [];
this.logger.debug('Starting script evaluation', {
scriptLength: script.length,
timeout,
siteId,
customBreakpoint: options.breakpointFile ? `${options.breakpointFile}:${options.breakpointLine}` : undefined,
});
try {
// Step 1: Use custom breakpoint or detect storefront cartridge
if (options.breakpointFile) {
// Use custom breakpoint configuration - single line or default to lines 1-50
const customLines = options.breakpointLine ? [options.breakpointLine] : DEFAULT_BREAKPOINT_LINES;
this.activeCartridgeConfig = {
cartridge: '', // Not used for custom - path is complete
controllerPath: options.breakpointFile,
breakpointLines: customLines,
type: 'sfra', // Doesn't matter for custom
};
this.logger.debug('Using custom breakpoint', {
file: options.breakpointFile,
lines: options.breakpointLine ?? 'strategic (1,10,20,30,40,50)',
});
} else {
// Auto-detect storefront cartridge (SFRA or SiteGenesis)
const cartridgeConfig = await this.detectStorefrontCartridge();
if (!cartridgeConfig) {
return {
success: false,
error: 'No compatible storefront cartridge found. Ensure either app_storefront_base (SFRA) or app_storefront_controllers (SiteGenesis) is deployed to your code version.',
executionTimeMs: Date.now() - startTime,
warnings: [
'Verify that your storefront cartridge exists in your active code version',
'Supported cartridges: app_storefront_base (SFRA), app_storefront_controllers (SiteGenesis)',
'Check that the code version is correctly deployed via WebDAV',
'Or specify custom breakpointFile and breakpointLine parameters',
],
};
}
this.activeCartridgeConfig = cartridgeConfig;
this.logger.debug('Using detected cartridge config', {
cartridge: cartridgeConfig.cartridge,
type: cartridgeConfig.type,
breakpointLines: 'strategic (1,10,20,30,40,50)',
});
}
// Step 2: Enable the debugger (create client)
await this.enableDebugger();
// Step 3: Set breakpoints on Default.js controller (lines 1-50 by default)
await this.setBreakpoints();
// Step 4: Trigger Default-Start via HTTP (async - don't await fully)
const triggerPromise = this.triggerDefaultStart(siteId, locale);
// Step 5: Poll for halted thread
const thread = await this.waitForHaltedThread(timeout);
if (!thread) {
// Cleanup and return error
await this.cleanup();
return {
success: false,
error: 'Timeout waiting for script to hit breakpoint. The Default-Start endpoint may not have been triggered correctly.',
executionTimeMs: Date.now() - startTime,
warnings: [
`Ensure the site "${siteId}" exists and has app_storefront_base in its cartridge path`,
'Check that the Default-Start route is accessible',
'Verify script debugging is enabled',
],
};
}
// Step 6: Evaluate the user's expression in the halted context
const evalResult = await this.evaluateInContext(thread.id, script);
// Step 7: Delete breakpoints immediately (we have our result)
try {
await this.debuggerRequest('DELETE', '/breakpoints');
} catch {
// Ignore - best effort cleanup
}
// Step 8: Resume the thread
await this.resumeThread(thread.id);
// Step 9: Disable debugger client (don't wait for trigger - it will complete/timeout on its own)
if (this.isDebuggerEnabled) {
try {
await this.debuggerRequest('DELETE', '/client');
this.isDebuggerEnabled = false;
} catch {
// Ignore
}
}
// Don't await triggerPromise - let it complete/timeout in background
triggerPromise.catch(() => {
// Expected - request may timeout after thread resumes
});
return {
success: true,
result: evalResult,
executionTimeMs: Date.now() - startTime,
warnings: warnings.length > 0 ? warnings : undefined,
};
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
this.logger.error('Script evaluation failed', { error: errorMessage });
// Always try to cleanup
try {
await this.cleanup();
} catch (cleanupError) {
this.logger.debug('Cleanup after error failed', { cleanupError });
}
return {
success: false,
error: errorMessage,
executionTimeMs: Date.now() - startTime,
warnings: this.getErrorGuidance(errorMessage),
};
}
}
/**
* Build and cache authentication header for debugger API
*/
private getAuthHeader(): string {
if (this.cachedAuthHeader) {
return this.cachedAuthHeader;
}
let credentials: string;
if (this.config.username && this.config.password) {
credentials = `${this.config.username}:${this.config.password}`;
} else if (this.config.clientId && this.config.clientSecret) {
credentials = `${this.config.clientId}:${this.config.clientSecret}`;
} else {
throw new Error('No authentication credentials available');
}
this.cachedAuthHeader = `Basic ${Buffer.from(credentials).toString('base64')}`;
return this.cachedAuthHeader;
}
/**
* Get WebDAV client credentials
*/
private getWebDAVCredentials(): { username: string; password: string } {
if (this.config.username && this.config.password) {
return { username: this.config.username, password: this.config.password };
}
if (this.config.clientId && this.config.clientSecret) {
return { username: this.config.clientId, password: this.config.clientSecret };
}
throw new Error('No authentication credentials available for WebDAV');
}
/**
* Get or create WebDAV client for cartridge verification
*/
private getWebDAVClient(): WebDAVClient {
if (!this.webdavClient) {
const webdavUrl = `${this.protocol}://${this.config.hostname}/on/demandware.servlet/webdav/Sites/Cartridges/`;
this.webdavClient = createClient(webdavUrl, this.getWebDAVCredentials());
}
return this.webdavClient;
}
/**
* Check if a specific controller exists in the code version
*/
private async controllerExists(config: CartridgeConfig): Promise<boolean> {
try {
const client = this.getWebDAVClient();
const codeVersion = this.config.codeVersion ?? 'version1';
const controllerPath = `/${codeVersion}/${config.cartridge}${config.controllerPath}`;
this.logger.debug('Checking controller exists', { controllerPath, type: config.type });
return await client.exists(controllerPath);
} catch (error) {
this.logger.debug('Controller check failed', {
cartridge: config.cartridge,
error: error instanceof Error ? error.message : String(error),
});
return false;
}
}
/**
* Detect which storefront cartridge is available (SFRA or SiteGenesis)
* Returns the cartridge config to use, or null if none found
*/
private async detectStorefrontCartridge(): Promise<CartridgeConfig | null> {
// Try SFRA first (preferred)
if (await this.controllerExists(SFRA_CONFIG)) {
this.logger.debug('Detected SFRA storefront');
return SFRA_CONFIG;
}
// Fall back to SiteGenesis
if (await this.controllerExists(SITEGENESIS_CONFIG)) {
this.logger.debug('Detected SiteGenesis storefront');
return SITEGENESIS_CONFIG;
}
this.logger.debug('No compatible storefront cartridge found');
return null;
}
/**
* Make a request to the debugger API
*/
private async debuggerRequest<T>(
method: string,
endpoint: string,
body?: unknown,
): Promise<T> {
const url = `${this.debuggerBaseUrl}${endpoint}`;
this.logger.debug(`Debugger API ${method} ${endpoint}`);
const options: RequestInit = {
method,
headers: {
Authorization: this.getAuthHeader(),
'x-dw-client-id': this.debuggerClientId,
'Content-Type': 'application/json',
},
};
if (body) {
options.body = JSON.stringify(body);
}
const response = await fetch(url, options);
// 204 No Content is success for some operations
if (response.status === 204) {
return {} as T;
}
if (!response.ok) {
let errorMessage = `Debugger API error: ${response.status} ${response.statusText}`;
try {
const errorBody = (await response.json()) as FaultResponse;
if (errorBody.fault) {
errorMessage = `${errorBody.fault.type}: ${errorBody.fault.message}`;
}
} catch {
// Could not parse error body
}
throw new Error(errorMessage);
}
// Some endpoints return no body on success
const text = await response.text();
if (!text) {
return {} as T;
}
return JSON.parse(text) as T;
}
/**
* Enable the debugger by creating a client session
*/
private async enableDebugger(): Promise<void> {
this.logger.debug('Enabling debugger');
try {
await this.debuggerRequest('POST', '/client');
this.isDebuggerEnabled = true;
this.logger.debug('Debugger enabled successfully');
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
// Check if another client already has the debugger
if (errorMessage.includes('DebuggerAlreadyEnabled') || errorMessage.includes('already')) {
this.logger.debug('Debugger already enabled by another client, attempting to take over');
// Delete existing client and retry
try {
await this.debuggerRequest('DELETE', '/client');
await this.debuggerRequest('POST', '/client');
this.isDebuggerEnabled = true;
this.logger.debug('Took over debugger session');
return;
} catch (retryError) {
throw new Error(`Failed to take over debugger session: ${retryError instanceof Error ? retryError.message : String(retryError)}`);
}
}
throw error;
}
}
/**
* Set breakpoints on the controller.
* Creates multiple breakpoints (lines 1-50 by default) to ensure we catch executable code.
*/
private async setBreakpoints(): Promise<number[]> {
if (!this.activeCartridgeConfig) {
throw new Error('No active cartridge config - call detectStorefrontCartridge first');
}
// For custom breakpoints, controllerPath is the full path
// For auto-detected, we combine cartridge + controllerPath
const scriptPath = this.activeCartridgeConfig.cartridge
? `/${this.activeCartridgeConfig.cartridge}${this.activeCartridgeConfig.controllerPath}`
: this.activeCartridgeConfig.controllerPath;
// Normalize to array of line numbers
const lineNumbers = Array.isArray(this.activeCartridgeConfig.breakpointLines)
? this.activeCartridgeConfig.breakpointLines
: [this.activeCartridgeConfig.breakpointLines];
this.logger.debug('Setting breakpoints', { scriptPath, lines: lineNumbers.length > 5 ? `${lineNumbers[0]}-${lineNumbers[lineNumbers.length - 1]}` : lineNumbers });
// Create breakpoint objects for all lines
const breakpointRequests = lineNumbers.map((line) => ({
line_number: line,
script_path: scriptPath,
}));
const response = await this.debuggerRequest<{ breakpoints: Array<{ id: number }> }>('POST', '/breakpoints', {
breakpoints: breakpointRequests,
});
if (!response.breakpoints || response.breakpoints.length === 0) {
throw new Error('Failed to create breakpoints');
}
const breakpointIds = response.breakpoints.map((bp) => bp.id);
this.logger.debug('Breakpoints set', { count: breakpointIds.length });
return breakpointIds;
}
/**
* Normalize site ID - extract the ID from "Sites-{id}-Site" format if needed
*/
private normalizeSiteId(siteId: string): string {
const match = siteId.match(/^Sites-(.+)-Site$/i);
return match ? match[1] : siteId;
}
/**
* Normalize locale value by trimming and removing leading/trailing slashes
*/
private normalizeLocale(locale: string): string {
const trimmed = locale.trim();
const cleaned = trimmed.replace(/^\/+/, '').replace(/\/+$/, '');
return cleaned.length > 0 ? cleaned : DEFAULT_LOCALE;
}
/**
* Trigger the Default-Start endpoint via HTTP
*/
private async triggerDefaultStart(siteId: string, locale: string): Promise<void> {
// Normalize site ID in case it's passed as "Sites-{id}-Site"
const normalizedSiteId = this.normalizeSiteId(siteId);
const normalizedLocale = this.normalizeLocale(locale);
// Some instances require the classic storefront URL format.
// First try without locale (may redirect), then fall back to explicit locale.
const siteSegment = `Sites-${normalizedSiteId}-Site`;
const baseUrl = `${this.protocol}://${this.config.hostname}/on/demandware.store/${siteSegment}`;
const urlWithoutLocale = `${baseUrl}/`;
const urlWithLocale = `${baseUrl}/${normalizedLocale}`;
this.logger.debug('Triggering Default-Start', {
siteId: normalizedSiteId,
locale: normalizedLocale,
urlWithoutLocale,
urlWithLocale,
});
const shouldRetryWithLocale = await this.triggerStorefrontUrl(urlWithoutLocale);
if (shouldRetryWithLocale) {
await this.triggerStorefrontUrl(urlWithLocale);
}
}
/**
* Trigger a storefront URL. Returns true if caller should retry with a fallback URL.
*
* Important: When debugging is active, the request may hang (and get aborted by timeout)
* after successfully hitting the breakpoint. In that case we should NOT retry.
*/
private async triggerStorefrontUrl(url: string): Promise<boolean> {
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), TRIGGER_TIMEOUT_MS);
const response = await fetch(url, {
method: 'GET',
signal: controller.signal,
headers: {
Accept: 'text/html,application/xhtml+xml',
},
});
clearTimeout(timeoutId);
if (!response.ok) {
this.logger.debug('Storefront trigger non-OK response', { url, status: response.status });
return true;
}
this.logger.debug('Storefront trigger response', { url, status: response.status });
return false;
} catch (error) {
// This is expected - the request may hang while we're debugging
const errorMessage = error instanceof Error ? error.message : String(error);
const isAbort = (error instanceof Error && error.name === 'AbortError') || errorMessage.toLowerCase().includes('abort');
if (isAbort) {
// Treat as success: likely hit the breakpoint and is now halted
return false;
}
this.logger.debug('Storefront trigger error', { url, error: errorMessage });
return true;
}
}
/**
* Wait for a thread to halt at our breakpoint
*/
private async waitForHaltedThread(timeout: number): Promise<ScriptThread | null> {
const startTime = Date.now();
this.logger.debug('Waiting for halted thread', { timeout });
while (Date.now() - startTime < timeout) {
try {
const response = await this.debuggerRequest<ThreadsResponse>('GET', '/threads');
if (response.script_threads && response.script_threads.length > 0) {
const haltedThread = response.script_threads.find((t) => t.status === 'halted');
if (haltedThread) {
this.logger.debug('Found halted thread', { threadId: haltedThread.id });
// Reset timeout to give us more time
await this.debuggerRequest('POST', '/threads/reset');
return haltedThread;
}
}
} catch (error) {
// Ignore errors during polling - thread might not exist yet
this.logger.debug('Thread poll error (may be normal)', {
error: error instanceof Error ? error.message : String(error),
});
}
// Wait before next poll
await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
}
this.logger.debug('Timeout waiting for halted thread');
return null;
}
/**
* Evaluate an expression in the context of a halted thread
*/
private async evaluateInContext(threadId: number, expression: string): Promise<string> {
// Frame 0 is the current execution point
const frameIndex = 0;
// URL encode the expression
const encodedExpr = encodeURIComponent(expression);
this.logger.debug('Evaluating expression', { threadId, frameIndex });
const response = await this.debuggerRequest<EvalResponse>(
'GET',
`/threads/${threadId}/frames/${frameIndex}/eval?expr=${encodedExpr}`,
);
return response.result ?? 'undefined';
}
/**
* Resume a halted thread
*/
private async resumeThread(threadId: number): Promise<void> {
this.logger.debug('Resuming thread', { threadId });
try {
await this.debuggerRequest('POST', `/threads/${threadId}/resume`);
} catch (error) {
// Thread may have already completed
this.logger.debug('Resume thread error (may be expected)', {
error: error instanceof Error ? error.message : String(error),
});
}
}
/**
* Cleanup: remove breakpoints, disable debugger
*/
private async cleanup(): Promise<void> {
this.logger.debug('Starting cleanup');
// Remove all breakpoints
try {
await this.debuggerRequest('DELETE', '/breakpoints');
} catch {
// Ignore errors
}
// Disable debugger (also resumes any halted threads)
if (this.isDebuggerEnabled) {
try {
await this.debuggerRequest('DELETE', '/client');
this.isDebuggerEnabled = false;
} catch {
// Ignore errors
}
}
this.logger.debug('Cleanup complete');
}
/**
* Get guidance based on error message
*/
private getErrorGuidance(errorMessage: string): string[] {
const guidance: string[] = [];
if (errorMessage.includes('NotAuthorizedException')) {
guidance.push('Ensure your Business Manager user has the "Modules - Script Debugger" functional permission');
guidance.push('Check that script debugging is enabled in Administration > Development Setup');
}
if (errorMessage.includes('ClientIdRequiredException')) {
guidance.push('The x-dw-client-id header is required for the Script Debugger API');
}
if (errorMessage.includes('timeout') || errorMessage.includes('Timeout')) {
guidance.push('The script execution may have timed out');
guidance.push('Ensure the site ID is correct and the Default-Start route is accessible');
guidance.push('Check that app_storefront_base is in the site\'s cartridge path');
}
if (guidance.length === 0) {
guidance.push('Check SFCC instance connectivity');
guidance.push('Verify your credentials are correct');
guidance.push('Ensure script debugging is enabled in Business Manager');
}
return guidance;
}
/**
* Test connectivity to the debugger API
*/
async testConnection(): Promise<{ success: boolean; message: string }> {
try {
// Try to create and immediately delete a client to test connectivity
await this.enableDebugger();
await this.cleanup();
return {
success: true,
message: 'Successfully connected to Script Debugger API',
};
} catch (error) {
return {
success: false,
message: error instanceof Error ? error.message : String(error),
};
}
}
}
