@W-22653715 adding docs browser in vs extension

.changeset/cip-analytics-vs-extension.md

@@ -0,0 +1,11 @@
+---
+'b2c-vs-extension': minor
+---
+
+Add B2C-DX Analytics (CIP/CCAC) feature to the VS Code extension. Surfaces three webview panels:
+
+- **Query Builder** — visual SELECT/FROM/WHERE/ORDER BY/LIMIT composer with raw-SQL toggle and a workspace-scoped Saved Queries library tagged per tenant.
+- **Tables Browser** — schema explorer for the active CIP warehouse tenant.
+- **Curated Reports** — parameter forms for every `cip report …` command with date pickers, validation, sortable result grid, and CSV/JSON export.
+
+Adds multi-realm management (group, add, edit, switch, remove) so a single workspace can target multiple tenants. CIP commands now route through `registerSafeCommand` so SafetyGuard policies are enforced and a `cipAnalytics` feature category is recorded by usage telemetry. The shared webview stylesheet is copied into `dist/cip-analytics/` at build time so the packaged extension no longer reaches into `src/` for runtime assets.

.changeset/docs-browser-vs-extension.md

@@ -0,0 +1,11 @@
+---
+'b2c-vs-extension': minor
+---
+
+Add Docs Browser: an offline-first, in-editor reference for the SFCC Script
+API derived from `@salesforce/b2c-script-types`. Search from the new
+**Docs** sidebar or panel, right-click any `dw.*` symbol in a JavaScript or
+TypeScript cartridge file to **View B2C Docs**, and revisit recently opened
+entries. Class pages list constants, properties, and methods inline with
+full signatures so you can navigate without leaving the panel. Disable with
+`b2c-dx.features.docsBrowser`.

.changeset/docs-seo-descriptions.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-dx-docs': patch
+---
+
+Add page-specific SEO meta descriptions to the SCAPI Schemas CLI reference and CI/CD guide pages, replacing the site-wide default description.

.changeset/fix-isml-scanner-bundling.md

@@ -0,0 +1,5 @@
+---
+'b2c-vs-extension': patch
+---
+
+Fix the VS Code extension failing to activate when ISML support is enabled. The `src/isml/scanner.ts` module loaded `vscode-html-languageservice` via runtime `require()` calls that esbuild left unbundled. Because the VSIX is packaged with `vsce --no-dependencies`, the deep submodule paths could not be resolved at runtime and activation crashed silently — no "B2C DX" output channel, no instance selector, no commands. Switched to direct ESM imports so esbuild inlines the scanner code into the bundle.

.changeset/fix-qs-picomatch-vulnerabilities.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/mrt-utilities': patch
+---
+
+Bump qs to 6.15.2 and picomatch to 2.3.2/4.0.4 to resolve CVE-2026-2391 and CVE-2026-33671

.changeset/isml-vs-extension.md

@@ -0,0 +1,5 @@
+---
+'b2c-vs-extension': minor
+---
+
+Add ISML language support in the VS Code extension, including `.isml` file association, grammar and snippets, auto-close and linked editing for tags, diagnostics and quick fixes, symbols/folding/hover, semantic completions (`Resource.msg`, `URLUtils`, `res.render`, `require`), and template path links/definitions/references across cartridges.

.changeset/vs-extension-xml-validation.md

@@ -0,0 +1,10 @@
+---
+'b2c-vs-extension': minor
+'@salesforce/b2c-dx-docs': patch
+---
+
+Add XSD-based validation for B2C metadata XML files. The extension now contributes 48 schemas (catalogs, promotions, jobs, services, customer feeds, A/B tests, page-meta-tags, sorting rules, source codes, content libraries, and more) so opening a B2C metadata XML produces inline diagnostics, autocomplete, and hover documentation.
+
+**File-glob coverage** spans both common workspace conventions: the canonical SFCC site-archive layout (`sites/<id>/promotions.xml`, `catalogs/<id>/catalog.xml`, …) and exploded-archive workspaces under a `metadata/` folder (`metadata/promotions/*.xml`, `metadata/catalogs/*.xml`, …).
+
+**New install requirement:** the extension declares `redhat.vscode-xml` as an extension dependency. VS Code installs it automatically the first time this extension activates after the upgrade. Users / teams whose policies block third-party extensions should disable `b2c-dx.features.xmlValidation` (or remove the dependency declaration) before deploying the upgrade.

.changeset/vscode-offline-resilience.md

@@ -0,0 +1,6 @@
+---
+'b2c-vs-extension': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Make the VS Code extension resilient offline and when an instance is unreachable. A malformed `dw.json` no longer prevents the extension from activating, so local code browsing — cartridge discovery, Script API IntelliSense, cartridge-path require resolution, CAP detection, and scaffolding — keeps working without a connection. Connection-dependent views (WebDAV, Content, Sandbox, Logs) now collapse repeated "instance unreachable" errors into a single notification instead of flooding, and the Sandbox view explains when Account Manager OAuth credentials are the missing piece. The SDK's `listInstances()` now tolerates a malformed `dw.json` (returning no instances) rather than throwing.

.github/workflows/ci-vs-extension.yml

@@ -73,6 +73,20 @@ jobs:
       - name: Build packages
         run: pnpm -r run build
 
+      - name: Verify docs index is up to date
+        working-directory: packages/b2c-vs-extension
+        run: |
+          pnpm run build:docs-index
+          if [[ -n "$(git status --porcelain resources/docs/)" ]]; then
+            echo "::error::Committed docs index is stale. Run 'pnpm --filter b2c-vs-extension run build:docs-index' and commit the result."
+            git --no-pager diff --stat resources/docs/
+            exit 1
+          fi
+
+      - name: Verify Docs Browser runtime assets
+        working-directory: packages/b2c-vs-extension
+        run: pnpm run verify:docs-browser-assets
+
       - name: Run VS Extension tests
         working-directory: packages/b2c-vs-extension
         run: xvfb-run -a pnpm run test

docs/.vitepress/config.mts

@@ -82,6 +82,7 @@ const guidesSidebar = [
       {text: 'Overview', link: '/vscode-extension/'},
       {text: 'Installation', link: '/vscode-extension/installation'},
       {text: 'Configuration', link: '/vscode-extension/configuration'},
+      {text: 'Docs Browser', link: '/vscode-extension/docs-browser'},
     ],
   },
   {

docs/guide/analytics-reports-cip-ccac.md

@@ -260,6 +260,42 @@ See the SDK API reference:
 - [createCipClient helper](/api/clients/functions/createCipClient)
 - [CIP Operations API](/api/operations/cip/)
 
+## VS Code IDE Integration
+
+The B2C Commerce Developer Tools VS Code extension exposes the same CIP analytics workflows as a graphical experience. Open the **B2C-DX Analytics** view in the activity bar to access them.
+
+::: tip
+You don't need to install or configure the CLI separately — the extension uses the same SDK under the hood and reads from your workspace `dw.json` (or environment variables).
+:::
+
+### Available panels
+
+- **Query Builder** — visual SELECT / FROM / WHERE / ORDER BY / LIMIT composer with a "Saved Queries" library so you can bookmark frequently-used queries per tenant. Switch to **SQL** mode for raw query editing.
+- **Tables Browser** — schema explorer that lists every CIP warehouse table for the active tenant. Click a table to inspect its columns and types.
+- **Curated Reports** — opens any `cip report` command (sales analytics, top-selling products, etc.) in a parameter form with date pickers, validation, CSV/JSON export, and a sortable result grid.
+
+### Realm management
+
+The sidebar tree groups tenants under named realms. Each realm can hold multiple connections (e.g., production + sandbox). Use the toolbar actions to:
+
+- **Add Realm** — create a new realm group (e.g. `abcd`).
+- **Configure / Edit** — set tenant ID, environment (production / staging / custom host), and run a connection test.
+- **Switch Connection** — change which realm/tenant the open panels query against. All open Query Builder, Tables Browser, and Report panels follow the active connection.
+
+### Saving queries
+
+Inside the Query Builder, the **Save** button persists the current SQL into a workspace-scoped library, tagged with the active tenant. Saved queries appear in the **Saved Queries** dropdown — those authored against the current tenant are listed first; queries from other tenants appear dimmed below a divider so you can still recall them after switching connections.
+
+The library is stored in VS Code workspace state (`b2c-dx.cipAnalytics.savedQueries`). It is not committed to source control.
+
+### Telemetry
+
+Opening any CIP Analytics panel records a single per-session usage event under the `cipAnalytics` feature category. No SQL text or query results are collected. To opt out, set `b2c-dx.telemetry.enabled` to `false` in VS Code settings (or disable VS Code's global telemetry). See the [VS Code extension configuration](/vscode-extension/configuration#verbosity-polling-telemetry) for details.
+
+### Safety mode
+
+CIP commands flow through the same SafetyGuard as the rest of the extension. If your workspace defines a [safety policy](/guide/safety) that blocks or confirms a CIP command, the policy is enforced before the panel opens.
+
 ## Next Steps
 
 - [CIP Commands](/cli/cip) for full command reference and flags

docs/vscode-extension/configuration.md

@@ -94,6 +94,27 @@ The B2C Script Debugger registers regardless of these toggles — it activates o
 | `b2c-dx.sandbox.pollingInterval` | `10` | Seconds between polls while a sandbox is in a transitional state (`creating`, `starting`, `stopping`, `deleting`, `cloning`). Range: 2–300. Polling stops automatically once the realm settles. |
 | `b2c-dx.telemetry.enabled` | `true` | Send anonymous usage telemetry. Honors VS Code's `telemetry.telemetryLevel` — disabling that disables this regardless of this setting. |
 
+### XML schema validation
+
+The extension contributes XSD-based validation for B2C metadata XML files via the [Red Hat XML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml), which is declared as an extension dependency and installed automatically. When a file path matches one of the contributed globs, diagnostics, autocomplete, and hover docs are driven by the corresponding B2C schema.
+
+Both common workspace conventions are recognized:
+
+- **Canonical site-archive layout** — `sites/<site-id>/`, `catalogs/<id>/`, `libraries/<id>/`, `customer_lists/<id>/`, `pricebooks/`, `inventory_lists/`, `meta/`.
+- **Exploded `metadata/` workspace layout** — `metadata/sites/<id>/*.xml`, `metadata/catalogs/*.xml`, `metadata/promotions/*.xml`, etc.
+
+Schemas covered include catalog, promotion, slot, customer-group, customer-list, custom-object, inventory, library, payment-method, payment-processor, preference, pricebook, redirect-url, search/search2, shipping, site, sourcecode, store, url-rule, jobs, services, schedules, ab-test (and participants), assignment, cache-settings, commerce-feature-state, coupon (and redemption), csrf-allowlist, customer, customer-cdn-settings, dcext, form, geolocation, gift-certificate, locales, meta (system/custom-objecttype-extensions), oauth-providers, page-meta-tags, price-adjustment-limits, product-list, sitemap-configuration, sorting-rules, storefronts, and tax. The full mapping is at `packages/b2c-vs-extension/resources/xsd-mappings.json`.
+
+To disable XML validation globally in your workspace, set:
+
+```jsonc
+{
+  "xml.validation.enabled": false
+}
+```
+
+To opt out of the Red Hat XML dependency entirely, uninstall this extension or pin to a release prior to the one that introduced XML validation.
+
 ### Complete defaults (copy-paste)
 
 ```jsonc

docs/vscode-extension/docs-browser.md

@@ -0,0 +1,100 @@
+---
+description: B2C DX Docs Browser — search the SFCC Script API reference from inside VS Code without losing flow.
+---
+
+# Docs Browser
+
+The Docs Browser is an in-editor reference for the **SFCC Script API**
+(`dw.*`). It is offline-first — the index ships with the extension, so it
+keeps working without network access.
+
+## Why
+
+You write cartridge code with `dw.*` calls all day. The Docs Browser lets you
+look any of them up without switching to a browser, navigating the official
+documentation, and losing your place. Pair it with the bundled [Script API
+IntelliSense](./index#script-api-intellisense) and you have completion,
+parameter info, and full reference docs in one editor.
+
+## Getting started
+
+1. Open the **B2C-DX** activity bar.
+2. Expand the **Docs** view.
+3. Click an entry to open the themed reader panel beside your code.
+
+The reader panel shows the signature, parameters, return type, throws, and
+prose description. Class pages also include inline tables of constants,
+properties, and methods so you can navigate without going back to the tree.
+Code blocks and tables follow your VS Code theme.
+
+## Searching
+
+- **Keyboard shortcut** → `Alt+D` opens the search picker from anywhere.
+  (On Mac, hold the **Option** key — that's the same key, Apple labels it
+  differently.)
+- **Sidebar title bar** → click the **Search Docs** ($(search)) icon for the
+  same ranked quick-pick. The picker is keyboard-friendly: type, arrow-keys,
+  Enter.
+- **Inside the panel** → use the search box at the top of the panel for the
+  same ranked search, with a result list that updates as you type.
+
+The picker boosts exact matches (`dw.order.BasketMgr`) over substring matches
+(`getCurrent`) and treats dot/slash forms (`dw.order.BasketMgr` vs
+`dw/order/BasketMgr`) as the same target.
+
+## Right-click → View B2C Docs
+
+Place the cursor on a `dw.*` symbol in a JavaScript or TypeScript cartridge
+file and:
+
+- **Keyboard shortcut** → `Alt+Shift+D` opens the matching entry directly.
+  Active only inside cartridge files (the path must contain `/cartridge/`).
+- **Editor right-click → View B2C Docs** does the same.
+- **Command Palette → B2C DX - Docs: View B2C Docs** does the same.
+
+The resolver uses VS Code's Go-to-Definition under the hood: it asks "where
+is this symbol declared?", and because every `dw.*` class lives in its own
+file in the `b2c-script-types` package, the answer maps cleanly to a single
+docs entry. If the symbol can't be resolved exactly (e.g. you point at a
+local helper), the Docs Browser falls back to opening the search picker
+prefilled with the best candidate so you're one keystroke away from the
+right entry.
+
+## What is indexed
+
+| Source | Items | Source of truth |
+| --- | --- | --- |
+| SFCC Script API (`dw.*`) | Every class, interface, enum, method, property, and constant from the Script API surface. | JSDoc inside `@salesforce/b2c-script-types` `.d.ts` files, vendored from the official Salesforce platform documentation build. |
+
+The header shows the exact version and entry count of the index for the
+release you have installed (e.g. `Script API v26.7.0 (8664)`).
+
+## Recently viewed
+
+The Docs Browser remembers the last 10 entries you opened. They appear:
+
+- In the panel's empty state when no entry is selected.
+- At the top of the search picker before you type a query.
+
+History is stored in VS Code global state — it survives restarts and follows
+your VS Code profile across workspaces.
+
+## Settings
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `b2c-dx.features.docsBrowser` | `true` | Enable or disable the Docs Browser entirely. Disabling hides the sidebar, commands, and editor menu entry. |
+
+## Offline behavior
+
+The index is bundled with the extension's VSIX. The Docs Browser performs no
+network requests. After install you can keep using it on a plane, in
+air-gapped environments, or while the documentation site is unreachable.
+
+## Roadmap
+
+ISML tag and Business Manager topic browsing are tracked as follow-up work.
+They were intentionally left out of the first release because they require
+authoritative upstream sources (the official ISML grammar; Salesforce-owned
+Business Manager content) before any data is shipped — hand-curated content
+was deliberately not pursued.

packages/b2c-tooling-sdk/src/config/sources/dw-json-source.ts

@@ -63,10 +63,22 @@ export class DwJsonSource implements ConfigSource {
    * List all instances from dw.json.
    */
   async listInstances(options?: ResolveConfigOptions): Promise<InstanceInfo[]> {
-    const result = await loadFullDwJson({
-      path: options?.configPath,
-      projectDirectory: options?.projectDirectory ?? options?.workingDirectory,
-    });
+    let result: Awaited<ReturnType<typeof loadFullDwJson>>;
+    try {
+      result = await loadFullDwJson({
+        path: options?.configPath,
+        projectDirectory: options?.projectDirectory ?? options?.workingDirectory,
+      });
+    } catch (error) {
+      // A malformed dw.json (loadFullDwJson re-throws on JSON.parse failure)
+      // must not crash callers that only want to enumerate instances. Mirror
+      // the resolver's tolerance — log a warning and report no instances —
+      // so an unparseable file degrades gracefully (e.g. the VS Code status
+      // bar / instance switcher) instead of throwing.
+      const message = error instanceof Error ? error.message : String(error);
+      getLogger().warn({error: message}, '[DwJsonSource] Failed to read dw.json while listing instances');
+      return [];
+    }
 
     if (!result) {
       return [];

packages/b2c-tooling-sdk/test/config/sources.test.ts

@@ -198,6 +198,19 @@ describe('config/sources', () => {
         expect(instances[0].active).to.be.true;
         expect(instances[1].name).to.equal('staging');
       });
+
+      it('returns an empty array (does not throw) when dw.json is malformed', async () => {
+        // A garbled dw.json must degrade gracefully rather than throw — the
+        // VS Code extension awaits this on its activation path, so a re-thrown
+        // JSON.parse error would disable the whole extension.
+        const dwJsonPath = path.join(tempDir, 'dw.json');
+        fs.writeFileSync(dwJsonPath, '{ "hostname": "broken.demandware.net", }'); // trailing comma
+
+        const source = new DwJsonSource();
+        const instances = await source.listInstances();
+
+        expect(instances).to.deep.equal([]);
+      });
     });
 
     describe('createInstance', () => {

packages/b2c-vs-extension/.gitattributes

@@ -0,0 +1 @@
+resources/docs/*.json linguist-generated=true

packages/b2c-vs-extension/.gitignore

@@ -5,3 +5,4 @@ node_modules
 .vsce-stage/
 *.vsix
 /coverage
+resources/xsd/

packages/b2c-vs-extension/.prettierignore

@@ -1,2 +1,6 @@
 # Template file contains ${placeholders} replaced at runtime; not valid syntax for Prettier
 src/template/
+
+# Intentionally malformed dw.json fixture (trailing comma) used by the activation
+# regression test; Prettier would "fix" it into valid JSON and defeat the test.
+src/test/fixtures/malformed-workspace/dw.json

packages/b2c-vs-extension/.vscode-test.mjs

@@ -1,11 +1,29 @@
 import {defineConfig} from '@vscode/test-cli';
 
-export default defineConfig({
-  files: 'out/test/**/*.test.js',
-  version: 'stable',
-  workspaceFolder: 'src/test/fixtures/empty-workspace',
-  mocha: {
-    ui: 'tdd',
-    timeout: 20000,
+// Run the integration suite twice against different workspaces. The second run
+// points the test host at a workspace whose dw.json is intentionally malformed:
+// it guards the activation path against a regression where a garbled local
+// dw.json would throw out of activateInner() and disable the entire extension
+// (leaving only the two fallback commands), which breaks offline code browsing.
+export default defineConfig([
+  {
+    label: 'valid-workspace',
+    files: 'out/test/**/*.test.js',
+    version: 'stable',
+    workspaceFolder: 'src/test/fixtures/empty-workspace',
+    mocha: {
+      ui: 'tdd',
+      timeout: 20000,
+    },
   },
-});
+  {
+    label: 'malformed-dw-json',
+    files: 'out/test/integration/activation.test.js',
+    version: 'stable',
+    workspaceFolder: 'src/test/fixtures/malformed-workspace',
+    mocha: {
+      ui: 'tdd',
+      timeout: 20000,
+    },
+  },
+]);

packages/b2c-vs-extension/.vscodeignore

@@ -3,6 +3,10 @@
 src/**
 !src/webview.html
 !src/api-browser/swagger-webview.html
+!src/docs-browser/docs-webview.html
+!src/storefront-next-cartridge.html
+!src/scapi-explorer.html
+!src/ods-management.html
 out/**
 **/node_modules/**
 dist/meta.json