feat: B2C Commerce script debugger (SDAPI 2.0 DAP adapter) (#330)

* feat: add B2C Commerce script debugger (SDAPI 2.0 DAP adapter)

SDK layer (operations/debug/):
- SDAPI 2.0 REST client with Basic auth
- Debug session manager with thread polling and keepalive
- DAP adapter extending @vscode/debugadapter for stdio use
- Source mapping between local cartridge paths and server script paths
- Variable store bridging DAP references to SDAPI object paths

CLI command (b2c debug):
- Runs DAP adapter over stdio for use with nvim-dap and other DAP clients
- Resolves credentials from dw.json, auto-discovers cartridges

Key behaviors:
- InitializedEvent deferred until after SDAPI client creation
- Thread re-halt detection when poll catches same thread halted at new location
- Halt OutputEvent includes local path for click-through in editors
- DAP OutputEvent is primary debug output; SDK logger demoted to debug/trace

* feat: VS Code inline debug adapter, terminate request, and logpoints

VS Code extension:
- Register b2c-script debug type with DebugAdapterInlineImplementation
- Auto-discover cartridges and resolve credentials from dw.json
- launch.json snippet for quick configuration

DAP adapter enhancements:
- supportsTerminateRequest: clean session shutdown via terminate button
- supportsLogPoints: breakpoints with log messages eval {expressions}
  server-side and auto-resume (note: briefly halts thread per hit)
- Richer OutputEvent messages: halt locations use local paths,
  breakpoint set counts, continue confirmation
- Evaluate results are expandable when the expression has members

CLI: demote debug command callbacks to logger.debug (DAP OutputEvent
is the primary output channel)

* fix: improve debugger error messages for missing credentials and auth failures

- VS Code extension shows actionable error messages referencing
  configuration (dw.json) when credentials are missing
- DAP adapter outputs friendly messages for 401 (auth failed) and
  412 (debugger not enabled) to both the debug console and notification

* fix: widen sendDAP type to accept DebugProtocol.Request in test

CI's pretest runs tsc -p test which typechecks test files. The sendDAP
helper accepted only ProtocolMessage but callers passed Request objects
with command/arguments properties.

Author: clavery

packages/b2c-cli/eslint.config.mjs

@@ -77,7 +77,7 @@ export default [
     },
   },
   {
-    files: ['src/commands/setup/**/*.ts', 'src/commands/slas/**/*.ts'],
+    files: ['src/commands/setup/**/*.ts', 'src/commands/slas/**/*.ts', 'src/commands/debug/**/*.ts'],
     rules: {
       // ESLint import resolver doesn't understand conditional exports (development condition)
       // but Node.js resolves them correctly at runtime

packages/b2c-cli/src/commands/debug/index.ts

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import {Flags} from '@oclif/core';
+import {InstanceCommand} from '@salesforce/b2c-tooling-sdk/cli';
+import {findCartridges} from '@salesforce/b2c-tooling-sdk/operations/code';
+import {B2CScriptDebugAdapter, type DebugSessionCallbacks} from '@salesforce/b2c-tooling-sdk/operations/debug';
+
+export default class Debug extends InstanceCommand<typeof Debug> {
+  static description = 'Start a DAP debug adapter for B2C Commerce script debugging';
+
+  static examples = [
+    '<%= config.bin %> <%= command.id %>',
+    '<%= config.bin %> <%= command.id %> --cartridge-path ./cartridges',
+    '<%= config.bin %> <%= command.id %> --client-id my-debugger',
+  ];
+
+  static flags = {
+    ...InstanceCommand.baseFlags,
+    'cartridge-path': Flags.string({
+      description: 'Path to cartridges directory',
+      default: '.',
+    }),
+    'client-id': Flags.string({
+      description: 'Client ID for the debugger API',
+      default: 'b2c-cli',
+    }),
+  };
+
+  async run(): Promise<void> {
+    this.requireServer();
+
+    const hostname = this.resolvedConfig.values.hostname!;
+    const username = this.resolvedConfig.values.username;
+    const password = this.resolvedConfig.values.password;
+
+    if (!username || !password) {
+      this.error(
+        'Basic auth credentials (username/password) are required for the script debugger. ' +
+          'Set via --username/--password flags, SFCC_USERNAME/SFCC_PASSWORD env vars, or dw.json.',
+      );
+    }
+
+    const cartridgePath = this.flags['cartridge-path'] ?? '.';
+    const cartridges = findCartridges(cartridgePath);
+    if (cartridges.length === 0) {
+      this.warn(`No cartridges found in ${cartridgePath}`);
+    }
+
+    this.logger.info(
+      `Mapped ${cartridges.length} cartridge(s): ${cartridges.map((c) => c.name).join(', ') || '(none)'}`,
+    );
+
+    const callbacks: DebugSessionCallbacks = {
+      onConnected: (host) => this.logger.debug(`Connected to script debugger on ${host}`),
+      onDisconnected: () => this.logger.debug('Script debugger disconnected'),
+      onDebuggerDisabled: () => this.logger.debug('Script debugger was disabled externally'),
+    };
+
+    const adapter = new B2CScriptDebugAdapter(
+      {
+        hostname,
+        username,
+        password,
+        clientId: this.flags['client-id'],
+        cartridgeRoots: cartridges,
+      },
+      callbacks,
+    );
+
+    // Run the DAP adapter over stdio
+    adapter.start(process.stdin, process.stdout);
+
+    // Wait for the adapter to finish (stdin closes)
+    await new Promise<void>((resolve) => {
+      process.stdin.on('end', resolve);
+      process.stdin.on('close', resolve);
+    });
+  }
+}

packages/b2c-tooling-sdk/package.json

@@ -364,6 +364,17 @@
         "types": "./dist/cjs/i18n/index.d.ts",
         "default": "./dist/cjs/i18n/index.js"
       }
+    },
+    "./operations/debug": {
+      "development": "./src/operations/debug/index.ts",
+      "import": {
+        "types": "./dist/esm/operations/debug/index.d.ts",
+        "default": "./dist/esm/operations/debug/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/operations/debug/index.d.ts",
+        "default": "./dist/cjs/operations/debug/index.js"
+      }
     }
   },
   "main": "./dist/cjs/index.js",
@@ -403,12 +414,12 @@
     "@oclif/prettier-config": "catalog:",
     "@oclif/test": "catalog:",
     "@salesforce/dev-config": "catalog:",
-    "@types/tar-fs": "^2.0.4",
     "@types/chai": "catalog:",
     "@types/ejs": "^3.1.5",
     "@types/mocha": "catalog:",
     "@types/node": "catalog:",
     "@types/sinon": "catalog:",
+    "@types/tar-fs": "^2.0.4",
     "@types/xml2js": "^0.4.14",
     "c8": "catalog:",
     "chai": "catalog:",
@@ -438,8 +449,8 @@
     "node": ">=22.16.0"
   },
   "dependencies": {
+    "@vscode/debugadapter": "1.68.0",
     "applicationinsights": "2.9.8",
-    "tar-fs": "3.1.2",
     "chokidar": "5.0.0",
     "cliui": "catalog:",
     "ejs": "3.1.10",
@@ -454,6 +465,7 @@
     "pino": "10.1.0",
     "pino-pretty": "13.1.2",
     "protobufjs": "7.5.4",
+    "tar-fs": "3.1.2",
     "undici": "7.19.2",
     "xml2js": "0.6.2"
   }