sfcc-dev-mcp 1.0.22 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- a0f5fbb: Add script debugger support for credentialed troubleshooting, including dedicated storefront authentication and custom trigger URLs.
+
+  Improve MCP execution and configuration handling with progress notifications, request cancellation, runtime WebDAV capability checks, flexible `dw.json` authentication, strict tool argument validation, and structured timeout-aware tool results.
+
+  Strengthen overall reliability with broader documentation and skill guidance, stronger tests and post-publish validation, and robustness improvements across the server, handlers, and configuration pipeline.
+
 All notable changes to this project will be documented in this file.
 
 The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -7,8 +17,10 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.
 Release comparison links are provided at the bottom. Earlier patch releases on the same day may represent rapid iterations (e.g. architectural + documentation expansions). Dates are derived from git tag timestamps.
 
 ## [1.0.15] - 2025-10-03
+
 ### Added
-- **SFRA Best Practices Expansion**: 
+
+- **SFRA Best Practices Expansion**:
   - SFRA SCSS best practices guide with theming and override patterns
   - SFRA client-side JavaScript guide covering AJAX flows, validation, and accessibility
 - **OCAPI Select Parameter Support**: Comprehensive support for OCAPI select syntax to control response field selection
@@ -25,6 +37,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **Custom Endpoint Caching**: Comprehensive caching strategies documentation for custom SCAPI endpoints with two-tier pattern examples
 
 ### Changed
+
 - **Testing Framework Migration**: Replaced Conductor with Aegis for MCP testing with improved declarative YAML patterns
 - **Documentation Modernization**:
   - Revamped documentation site with improved layout and readability
@@ -41,16 +54,19 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **AI Interface Enhancements**: Improved AI interface and configuration documentation
 
 ### Fixed
+
 - **SSR Hydration**: Fixed SSR hydration mismatch in OnThisPage component
 - **Hash Navigation**: Resolved hash navigation issues after search operations
 
 ### Documentation
+
 - **CSRF Middleware**: Clarified CSRF middleware usage patterns in SFRA
 - **Remote Include Architecture**: Added detailed explanation of remote include patterns for dynamic content
 - **Aegis Testing**: Comprehensive updates to Aegis testing documentation with best practices
 - **Performance Guidance**: Enhanced performance best practices with SCAPI-specific caching strategies
 
 ### Testing
+
 - **Comprehensive Test Coverage**:
   - OCAPI error handling and validation tests
   - Site preferences search tool tests
@@ -64,6 +80,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
   - Enhanced test targeting and organization
 
 ### Dependencies
+
 - **GitHub Actions Updates**:
   - `actions/checkout` from 4 to 5
   - `actions/configure-pages` from 4 to 5
@@ -77,16 +94,19 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
   - Updated `ts-jest` in Jest group
 
 ### Notes
+
 - Major testing infrastructure modernization with Aegis framework adoption
 - Significant documentation site improvements with SSG migration and enhanced UX
 - Expanded SFRA best practices coverage for complete development lifecycle
 - Enhanced OCAPI functionality with select parameter support and comprehensive mocking
 
 ## [1.0.14] - 2025-09-16
+
 ### Added
+
 - **SFCC Class Information Filtering**: Enhanced `get_sfcc_class_info` tool with comprehensive filtering capabilities including search parameter, inclusion/exclusion of descriptions, constants, properties, methods, and inheritance hierarchy.
 - **AI Response Comparison Modals**: Interactive modals on documentation site showing side-by-side comparison of AI responses with and without MCP server, including zoom functionality for detailed inspection.
-- **Documentation Site Enhancements**: 
+- **Documentation Site Enhancements**:
   - Examples page with practical usage scenarios and filtering demonstrations
   - Tools page documenting all available MCP tools
   - Features page highlighting key capabilities
@@ -99,6 +119,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **Anchor Link Navigation**: Added IDs to documentation headers for direct linking.
 
 ### Changed
+
 - **Project Licensing**: Aligned to MIT License (replaced ISC LICENSE text, updated `package.json` license field).
 - **CI/CD Pipeline**: Enhanced with improved linting and security checks.
 - **Documentation Structure**: Comprehensive reorganization and expansion of documentation site structure.
@@ -107,152 +128,199 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 - **UI/UX Polish**: Improved padding, layout adjustments, and site navigation structure.
 
 ### Fixed
+
 - **URL Fragment Handling**: Fixed URL-encoded hash fragment handling in documentation site.
 - **Workflow Deployment**: Corrected path issues for page deployment.
 - **Log Tool Validation**: Improved argument validation robustness for log analysis tools.
 
 ### Documentation
+
 - **AI Interface Setup**: Comprehensive guides for Claude Desktop, Cursor, and GitHub Copilot integration.
 - **Security Guidance**: Enhanced security considerations and best practices documentation.
 - **Troubleshooting**: Added comprehensive troubleshooting guide for common setup and usage issues.
 - **Development Workflow**: Detailed development guidelines and contribution instructions.
 
 ### Testing
-- **Enhanced Test Coverage**: 
+
+- **Enhanced Test Coverage**:
   - Comprehensive programmatic tests for SFCC class info filtering in documentation mode
   - Enhanced YAML-based MCP tests for class information tools
   - Job execution summary tests and job log analysis tests
   - Improved test setup reliability and CI stability
 
 ### Notes
+
 - Major documentation site expansion with React/Vite architecture
 - Enhanced developer experience with comprehensive filtering and search capabilities
 - Improved AI assistant integration with detailed setup guides for multiple platforms
 
 ## [1.0.13] - 2025-09-15
+
 ### Added
+
 - `engines` field in `package.json` enforcing Node >=18 and npm >=8.
 - Comprehensive architectural documentation (handler modularization, capability gating, services layer, log subsystem, tool-configs, caching).
 - Initial `CHANGELOG.md` introduction.
 
 ### Changed
+
 - Server reported version synchronized with `package.json`.
 - Development guide: migrated from legacy Jekyll instructions to Vite workflow; updated tool addition workflow for new handler architecture.
 
 ### Fixed
+
 - Removed references to non-existent config files (`config.ts`, `constants.ts`).
 - Corrected debug flag examples (`--debug` vs `--debug true`).
 - Escaping/format fixes in development guide code blocks.
 
 ### Notes
+
 - Pre-1.0.14 license mismatch (ISC vs MIT badge) resolved in 1.0.14.
 
 ## [1.0.12] - 2025-08-19
+
 ### Added
+
 - Code version management tools (listing & activation) with supporting documentation.
 - Cartridge generation enhancements: page layout & styling improvements; prevention of overwriting existing files.
 - Security and OCAPI configuration warnings; highlighted AI instruction files.
 - Additional SFRA model and best practice documentation (ISML decorators, LocalServiceRegistry, Auth examples, BM configuration guide).
 
 ### Changed
+
 - ESLint configuration (global vars, lint fix script), table styling, documentation site theme updates, repository URL in config, branch protection for deploy (restricted to main), improved instance type check.
 - Documentation structure reorganized (multiple passes consolidating guides, theme adjustments, layout evolution and subsequent refinements / reverts).
 
 ### Fixed
+
 - Removal of `resourceState` from activateCodeVersion request.
 
 ### Documentation
+
 - Large expansion of SFRA models, cartridge creation, ISML templates, decorators warnings, URL patterns, customer context, authentication flows, endpoint security guidance.
 
 ### Notes
+
 - Multiple rapid doc iterations (additions, reverts, restyles) before stabilization.
 
 ## [1.0.11] - 2025-08-15
+
 ### Added
+
 - SFCC development rules and SFRA controllers best practices guide.
 - AI interface instruction documentation.
 
 ### Changed
+
 - Refactored rule configurations; enhanced SFCC debugging workflows; streamlined documentation tools; removed improvement roadmap.
 
 ### Fixed
+
 - Log files now sorted by last modification for accurate recency ordering.
 
 ### Testing
+
 - Enhanced log client test coverage.
 
 ### Notes
+
 - Documentation emphasis on rule context explanation and operational clarity.
 
 ## [1.0.10] - 2025-08-15
+
 ### Added
+
 - Custom object attribute search capability.
 - Progressive development guide (subsequently refined) and job framework best practices.
 - Additional documentation: steptypes configuration, ISML templates, SCAPI custom endpoint guide, path parameter & search query usage clarifications, SFRA documentation support expansion.
 
 ### Changed
+
 - Auth examples refactored into appendix; logging improvements and build output cleanliness.
 
 ### Fixed
+
 - Reversal / clarification cycles for job framework status codes and default values (cleanup of earlier docs ambiguities).
 
 ### Notes
+
 - Foundation for expanded SCAPI / SFRA documentation just before rapid rule & controller additions in 1.0.11.
 
 ## [1.0.9-2] - 2025-08-13
+
 ### Changed
+
 - Enhanced release workflow (iteration on same-day release of 1.0.9).
 
 ## [1.0.9] - 2025-08-13
+
 ### Added
+
 - Initial modular handler & directory architecture groundwork: secure config loading, debug log support, documentation-only mode, system object exposure, site preferences & attribute search, OCAPI client integration.
 - CI workflow, caching layer for documentation, expanded class details, path resolver, pre-commit hooks, NPM publishing & Dependabot configuration, issue templates.
 
 ### Changed
+
 - Large-scale codebase reorganization (directory structure, authentication & logging refactors, configuration loading improvements, handler refactors, OAuth token management relocation, package metadata updates, JSON serialization, system object description refinements, server architecture refactor).
 - Log tool naming alignment & tool description clarity improvements.
 
 ### Fixed
+
 - File path security validation enhancements.
 
 ### Documentation
+
 - Extensive expansion: best practices (security, performance, cartridge creation), contributing guidelines, search tool description, quick setup, system object definitions, Copilot instructions, local dev focus clarification.
 
 ### Testing
+
 - Added Jest framework and early test coverage (config factory, OAuth token manager, log client, attribute definitions, best practices client).
 
 ### Notes
+
 - Represents the foundational public baseline preceding rapid feature layering in 1.0.10+.
 
 ## [1.0.8] - 2025-08-13
+
 ### Changed
+
 - Package version alignment & metadata updates; project structure and documentation improvements; Node version CI expansions.
 
 ### Added
+
 - Security & performance best practices guides, contributing guidelines, AI assistant integration guide, deprecation support, attribute definition search, site preferences search.
 
 ### Notes
+
 - Last pre-architecture refactor baseline before major handler and structural reorganization in 1.0.9.
 
 ## [1.0.2] - 2025-08-08
+
 ### Added
+
 - Debug logging capabilities, caching for documentation, expanded class details, initial SFCC MCP server feature set (system object & attribute tools, OCAPI integration, documentation retrieval).
 - Jest testing framework & initial unit tests.
 
 ### Changed
+
 - Centralized logging infrastructure; configuration logging & security tightening; authentication config refactors.
 
 ### Documentation
+
 - Cartridge creation guide, npx usage instructions, API docs, system object definitions resource.
 
 ### Notes
+
 - Early stabilization phase; intermediate patch releases between 1.0.2 and 1.0.8 consolidated here (internal iteration without tags not reconstructed individually).
 
 ## [1.0.0] - 2025-08-08
+
 ### Added
+
 - Initial commit introducing SFCC Dev MCP Server core (base server, tooling scaffolding, initial documentation framework).
 
 ### Notes
+
 - Foundation commit history includes scaffolding, early capability extensions, and initial architectural decisions.
 
 ---
@@ -260,6 +328,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 ---
 
 ### Future
+
 - Add automation for changelog validation in CI (ensure categories & links present).
 - Add script to generate comparison links automatically when tagging.
 - Potential provenance notes for security-impacting changes (e.g., file path validation hardening).
@@ -267,6 +336,7 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 ---
 
 ### Comparison Links
+
 [1.0.15]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.14...v1.0.15
 [1.0.14]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.13...v1.0.14
 [1.0.13]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.12...v1.0.13
@@ -278,4 +348,3 @@ Release comparison links are provided at the bottom. Earlier patch releases on t
 [1.0.8]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.2...v1.0.8
 [1.0.2]: https://github.com/taurgis/sfcc-dev-mcp/compare/v1.0.0...v1.0.2
 [1.0.0]: https://github.com/taurgis/sfcc-dev-mcp/tree/v1.0.0
-

package/README.md

@@ -12,7 +12,7 @@ An AI-powered Model Context Protocol (MCP) server that provides comprehensive ac
 - **🧱 ISML Template Reference** - Complete ISML element documentation with examples and usage guidance
 - **📊 Log Analysis Tools** - Real-time error monitoring, debugging, and job log analysis for SFCC instances
 - **⚙️ System Object Definitions** - Explore custom attributes and site preferences
-- **🧪 Script Debugger** - Execute and inspect script-debugger endpoints in credentialed mode
+- **🧪 Script Debugger** - Execute and inspect script-debugger endpoints in credentialed mode, including custom trigger URLs/paths for non-default storefront routes
 - **🚀 Cartridge Generation** - Automated cartridge structure creation with workspace-bound path safety (writes stay inside workspace roots, or current working directory fallback when roots are unavailable; home-directory fallback is blocked)
 - **🧩 Agent Skill Bootstrap** - Install or merge AGENTS.md and bundled skills into the current project or a temp directory for AI assistants
 - **✅ Tool Argument Validation** - Runtime schema validation enforces required fields, type checks, enum constraints, integer/numeric bounds, and strict unknown-key checks for object schemas (top-level and nested) before handler execution
@@ -47,11 +47,14 @@ An AI-powered Model Context Protocol (MCP) server that provides comprehensive ac
 Create a `dw.json` file with your SFCC credentials. You can use either auth mode (or both):
 - Basic auth: `username` + `password`
 - OAuth: `client-id` + `client-secret`
+- Optional storefront auth (for script debugger trigger on Basic-Auth storefronts): `storefrontUsername` + `storefrontPassword`
 ```json
 {
   "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
   "username": "your-username",
-  "password": "your-password", 
+  "password": "your-password",
+  "storefrontUsername": "your-storefront-basic-user",
+  "storefrontPassword": "your-storefront-basic-password",
   "client-id": "your-client-id",
   "client-secret": "your-client-secret"
 }
@@ -210,9 +213,27 @@ The server writes logs to your system's temporary directory:
 node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"
 ```
 
-## 🧪 Release Validation (Maintainers)
+## 🧪 Release Flow (Maintainers)
 
-The publish workflow runs MCP tests against the just-published npm artifact (`npx sfcc-dev-mcp@<version>`) before publishing to the MCP Registry.
+This repository now uses Changesets for npm releases.
+
+When a change should ship in a new `sfcc-dev-mcp` version, add a changeset from the repository root:
+
+```bash
+npm run changeset
+```
+
+Check pending release state against `main` before merging:
+
+```bash
+npm run release:status
+```
+
+The release workflow on `main` creates or updates a release pull request from pending changesets. Merging that release pull request publishes the npm package through npm trusted publishing (GitHub Actions OIDC), waits for npm propagation, reruns MCP tests against the published NPX artifact, and then publishes the same version to the MCP Registry.
+
+`npm run version-packages` also syncs `server.json` with the package version so `validate:server-json` keeps passing in the release PR.
+
+Package publication now uses GitHub Actions OIDC trusted publishing, so no separate npm publish secret is required.
 
 You can run the same validation locally:
 

package/dist/ai-instructions/skills/sfcc-script-evaluation/SKILL.md

@@ -27,6 +27,7 @@ The `evaluate_script` tool allows you to execute arbitrary JavaScript code on an
 | `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
 

package/dist/clients/script-debugger/script-debugger-client.d.ts

@@ -64,6 +64,7 @@ export declare class ScriptDebuggerClient {
         locale?: string;
         breakpointFile?: string;
         breakpointLine?: number;
+        triggerUrl?: string;
     }): Promise<ScriptEvaluationResult>;
     private enqueueSerializedEvaluation;
     private resolveCartridgeConfig;
@@ -74,6 +75,16 @@ export declare class ScriptDebuggerClient {
      * Build and cache authentication header for debugger API
      */
     private getAuthHeader;
+    /**
+     * Build auth header for storefront trigger requests.
+     *
+     * Preference order:
+     * 1) Dedicated storefront credentials from dw.json
+     * 2) Primary basic auth credentials (username/password)
+     *
+     * OAuth credentials are intentionally not sent to storefront routes.
+     */
+    private getStorefrontTriggerAuthHeader;
     /**
      * Get WebDAV client credentials
      */
@@ -112,6 +123,16 @@ export declare class ScriptDebuggerClient {
      * Normalize locale value by trimming and removing leading/trailing slashes
      */
     private normalizeLocale;
+    /**
+     * Resolve a storefront trigger input into a fully-qualified URL for the configured instance.
+     *
+     * Supported forms:
+     * - Full URL (https://hostname/...)
+     * - Hostname-prefixed URL without scheme (hostname/...)
+     * - Absolute path (/on/demandware.store/... or /s/...)
+     * - Site-relative path (/womens/?lang=en_US -> /s/{siteId}/womens/?lang=en_US)
+     */
+    private resolveTriggerUrl;
     /**
      * Trigger the Default-Start endpoint via HTTP
      */

package/dist/clients/script-debugger/script-debugger-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-debugger-client.d.ts","sourceRoot":"","sources":["../../../src/clients/script-debugger/script-debugger-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAqBlD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAsED;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAAK;gBAElB,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM;IAO/C;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;KACpB,GACL,OAAO,CAAC,sBAAsB,CAAC;YA+FpB,2BAA2B;YAwB3B,sBAAsB;YA+BtB,qBAAqB;YAQrB,gBAAgB;YAQhB,sBAAsB;IAgBpC;;OAEG;IACH,OAAO,CAAC,aAAa;IAkBrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;YACW,gBAAgB;IAkB9B;;;OAGG;YACW,yBAAyB;IAiBvC;;OAEG;YACW,eAAe;IAoE7B;;OAEG;YACW,cAAc;IA8B5B;;;OAGG;YACW,cAAc;IAkC5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;YACW,mBAAmB;IAyBjC;;;;;OAKG;YACW,oBAAoB;IAuClC;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;YACW,iBAAiB;IAiB/B;;OAEG;YACW,YAAY;IAa1B;;OAEG;YACW,OAAO;IAcf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiBvE"}
+{"version":3,"file":"script-debugger-client.d.ts","sourceRoot":"","sources":["../../../src/clients/script-debugger/script-debugger-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAqBlD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAsED;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAAK;gBAElB,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM;IAO/C;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;KAChB,GACL,OAAO,CAAC,sBAAsB,CAAC;YAqGpB,2BAA2B;YAwB3B,sBAAsB;YA+BtB,qBAAqB;YAQrB,gBAAgB;YAQhB,sBAAsB;IAgBpC;;OAEG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;;;;;OAQG;IACH,OAAO,CAAC,8BAA8B;IAkBtC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;YACW,gBAAgB;IAkB9B;;;OAGG;YACW,yBAAyB;IAiBvC;;OAEG;YACW,eAAe;IAoE7B;;OAEG;YACW,cAAc;IA8B5B;;;OAGG;YACW,cAAc;IAkC5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAuCzB;;OAEG;YACW,mBAAmB;IAkCjC;;;;;OAKG;YACW,oBAAoB;IA6ClC;;OAEG;YACW,mBAAmB;IA8CjC;;OAEG;YACW,iBAAiB;IAiB/B;;OAEG;YACW,YAAY;IAa1B;;OAEG;YACW,OAAO;IAcf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiBvE"}

package/dist/clients/script-debugger/script-debugger-client.js

@@ -88,6 +88,7 @@ export class ScriptDebuggerClient {
             const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
             const siteId = options.siteId ?? DEFAULT_SITE_ID;
             const locale = this.normalizeLocale(options.locale ?? DEFAULT_LOCALE);
+            const normalizedSiteId = this.normalizeSiteId(siteId);
             const warnings = [];
             this.logger.debug('Starting script evaluation', {
                 scriptLength: script.length,
@@ -96,6 +97,9 @@ export class ScriptDebuggerClient {
                 customBreakpoint: options.breakpointFile ? `${options.breakpointFile}:${options.breakpointLine}` : undefined,
             });
             try {
+                const resolvedTriggerUrl = options.triggerUrl
+                    ? this.resolveTriggerUrl(options.triggerUrl, normalizedSiteId)
+                    : undefined;
                 // Resolve breakpoint target for this request.
                 const cartridgeConfig = await this.resolveCartridgeConfig(options);
                 if (!cartridgeConfig) {
@@ -117,7 +121,10 @@ export class ScriptDebuggerClient {
                 // Set breakpoints for this specific request only.
                 await this.setBreakpoints(cartridgeConfig);
                 // Trigger request execution in storefront.
-                const triggerPromise = this.triggerDefaultStart(siteId, locale);
+                const triggerPromise = this.triggerDefaultStart(normalizedSiteId, locale, resolvedTriggerUrl)
+                    .catch(() => {
+                    // Trigger request is best-effort while we poll debugger threads.
+                });
                 // Poll for halted thread
                 const thread = await this.waitForHaltedThread(timeout);
                 if (!thread) {
@@ -138,9 +145,7 @@ export class ScriptDebuggerClient {
                 await this.clearBreakpoints();
                 await this.resumeThread(thread.id);
                 // Let trigger settle in background (timeout is expected in some cases).
-                triggerPromise.catch(() => {
-                    // Expected - request may timeout after thread resumes.
-                });
+                void triggerPromise;
                 return {
                     success: true,
                     result: evalResult,
@@ -259,6 +264,29 @@ export class ScriptDebuggerClient {
         this.cachedAuthHeader = `Basic ${Buffer.from(credentials).toString('base64')}`;
         return this.cachedAuthHeader;
     }
+    /**
+     * Build auth header for storefront trigger requests.
+     *
+     * Preference order:
+     * 1) Dedicated storefront credentials from dw.json
+     * 2) Primary basic auth credentials (username/password)
+     *
+     * OAuth credentials are intentionally not sent to storefront routes.
+     */
+    getStorefrontTriggerAuthHeader() {
+        const storefrontUsername = this.config.storefrontUsername?.trim();
+        const storefrontPassword = this.config.storefrontPassword?.trim();
+        if (storefrontUsername || storefrontPassword) {
+            if (!storefrontUsername || !storefrontPassword) {
+                throw new Error('Storefront credentials must include both storefrontUsername and storefrontPassword');
+            }
+            return `Basic ${Buffer.from(`${storefrontUsername}:${storefrontPassword}`).toString('base64')}`;
+        }
+        if (this.config.username && this.config.password) {
+            return `Basic ${Buffer.from(`${this.config.username}:${this.config.password}`).toString('base64')}`;
+        }
+        return undefined;
+    }
     /**
      * Get WebDAV client credentials
      */
@@ -452,13 +480,59 @@ export class ScriptDebuggerClient {
         const cleaned = trimmed.replace(/^\/+/, '').replace(/\/+$/, '');
         return cleaned.length > 0 ? cleaned : DEFAULT_LOCALE;
     }
+    /**
+     * Resolve a storefront trigger input into a fully-qualified URL for the configured instance.
+     *
+     * Supported forms:
+     * - Full URL (https://hostname/...)
+     * - Hostname-prefixed URL without scheme (hostname/...)
+     * - Absolute path (/on/demandware.store/... or /s/...)
+     * - Site-relative path (/womens/?lang=en_US -> /s/{siteId}/womens/?lang=en_US)
+     */
+    resolveTriggerUrl(triggerUrl, normalizedSiteId) {
+        const raw = triggerUrl.trim();
+        if (!raw) {
+            throw new Error('triggerUrl must not be empty');
+        }
+        const configuredHost = (this.config.hostname ?? '').toLowerCase();
+        const lowerRaw = raw.toLowerCase();
+        if (lowerRaw.startsWith('http://') || lowerRaw.startsWith('https://')) {
+            let parsed;
+            try {
+                parsed = new URL(raw);
+            }
+            catch {
+                throw new Error(`Invalid triggerUrl: ${raw}`);
+            }
+            if (parsed.hostname.toLowerCase() !== configuredHost) {
+                throw new Error(`triggerUrl hostname must match configured hostname (${this.config.hostname})`);
+            }
+            return parsed.toString();
+        }
+        if (lowerRaw.startsWith(configuredHost)) {
+            return `${this.protocol}://${raw}`;
+        }
+        const normalizedPath = raw.startsWith('/') ? raw : `/${raw}`;
+        if (normalizedPath.startsWith('/on/demandware.store/') || normalizedPath.startsWith('/s/')) {
+            return `${this.protocol}://${this.config.hostname}${normalizedPath}`;
+        }
+        const relativeSitePath = normalizedPath === '/' ? '/' : normalizedPath;
+        return `${this.protocol}://${this.config.hostname}/s/${normalizedSiteId}${relativeSitePath}`;
+    }
     /**
      * Trigger the Default-Start endpoint via HTTP
      */
-    async triggerDefaultStart(siteId, locale) {
-        // Normalize site ID in case it's passed as "Sites-{id}-Site"
+    async triggerDefaultStart(siteId, locale, triggerUrl) {
         const normalizedSiteId = this.normalizeSiteId(siteId);
         const normalizedLocale = this.normalizeLocale(locale);
+        if (triggerUrl) {
+            this.logger.debug('Triggering custom storefront URL', {
+                siteId: normalizedSiteId,
+                triggerUrl,
+            });
+            await this.triggerStorefrontUrl(triggerUrl);
+            return;
+        }
         // 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`;
@@ -487,13 +561,18 @@ export class ScriptDebuggerClient {
             timeoutMs: TRIGGER_TIMEOUT_MS,
             timeoutMessage: `Storefront trigger timed out after ${TRIGGER_TIMEOUT_MS}ms`,
         });
+        const storefrontAuthHeader = this.getStorefrontTriggerAuthHeader();
+        const headers = {
+            Accept: 'text/html,application/xhtml+xml',
+        };
+        if (storefrontAuthHeader) {
+            headers.Authorization = storefrontAuthHeader;
+        }
         try {
             const response = await fetch(url, {
                 method: 'GET',
                 signal: timeoutController?.signal,
-                headers: {
-                    Accept: 'text/html,application/xhtml+xml',
-                },
+                headers,
             });
             if (!response.ok) {
                 this.logger.debug('Storefront trigger non-OK response', { url, status: response.status });