Doc fixes and review nits

- Drop unimplemented "Compare with Instance" diff from features.md and
  remove its placeholder image; the diffCartridge command is stub
  functionality.
- Fix project-root pinning docs: "Use as B2C Commerce Root" only shows on
  a workspace-root folder when the workspace has more than one folder
  open; "Reset" is palette-only.
- Replace internal-source pointer with an inline rule in the cloned
  sandbox indicators paragraph.
- Add 24h TTL to the VSIX release data loader cache so a maintainer who
  cuts a release won't see a stale version on the next local docs build.
- Include pnpm-lock.yaml in the .vscode-test cache key so a test-cli /
  test-electron version bump invalidates the cache.
- Comment the activation test's command-registration check to explain why
  it doubles as a swallowed-failure detector.
- Tidy webdav-mappings.test.ts stub.

Author: clavery

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

@@ -63,7 +63,7 @@ jobs:
         uses: actions/cache@v5
         with:
           path: packages/b2c-vs-extension/.vscode-test
-          key: ${{ runner.os }}-vscode-test-${{ hashFiles('packages/b2c-vs-extension/.vscode-test.mjs') }}
+          key: ${{ runner.os }}-vscode-test-${{ hashFiles('packages/b2c-vs-extension/.vscode-test.mjs', 'pnpm-lock.yaml') }}
           restore-keys: |
             ${{ runner.os }}-vscode-test-
 

docs/vscode-extension/configuration.md

@@ -66,8 +66,8 @@ The Sandbox Realm Explorer auto-polls a realm only when at least one sandbox is
 
 In a multi-root workspace, the extension auto-detects the project root by walking up from the active editor (or the first workspace folder) looking for `dw.json` / `package.json` markers. Two commands let you override the auto-detected root:
 
-- **B2C DX: Use as B2C Commerce Root** — right-click any folder in the Explorer and select this command to pin it. The status bar shows a `$(pinned)` indicator while a pin is active.
-- **B2C DX: Reset B2C Commerce Root to Auto-Detect** — clears the pin and returns to auto-detection.
+- **B2C DX: Use as B2C Commerce Root** — only available on a workspace-root folder when more than one folder is open in the workspace. Right-click that folder in the Explorer and select the command to pin it. While a pin is active, the status bar shows a `$(pinned)` indicator.
+- **B2C DX: Reset B2C Commerce Root to Auto-Detect** — clears the pin and returns to auto-detection. Run from the Command Palette (this command has no Explorer context-menu entry).
 
 The pin is workspace-scoped (stored in workspace state). Pin a specific folder when you have multiple cartridge projects in a single workspace and want to keep CLI commands targeting one of them.
 

docs/vscode-extension/features.md

@@ -12,7 +12,7 @@ Browse and manage on-demand sandboxes (ODS) for one or more realms in a dedicate
 
 **Lifecycle commands** (palette + right-click): create, start, stop, restart, clone, view details, view clone details, extend expiration, open Business Manager, delete.
 
-**Cloned sandbox indicators** — clones are tagged in the tree (the source sandbox shows as `cloning` while a target is being set up; the target shows as `setting up` until it stabilizes). The display logic is identical to the CLI's: see `computeSandboxDisplay` in the package source for the precise rules.
+**Cloned sandbox indicators** — clones are tagged in the tree. While a clone is being set up, the source sandbox is shown as `cloning` and the new (target) sandbox is shown as `setting up`. Once the clone stabilizes, both rows display their actual states (`started`, `stopped`, etc.) and the cloned target keeps a visual marker so you can tell it apart from a freshly created sandbox.
 
 <!-- TODO(screenshot): sandbox-explorer.png — started + cloned sandbox in the tree -->
 ![Sandbox Realm Explorer](./images/sandbox-explorer.png)
@@ -59,16 +59,13 @@ A **Cartridges** tree view (under the **B2C-DX** activity-bar container) lists e
 
 **Title-bar actions**: **Refresh Cartridges**, **Deploy Cartridges**, **Code Versions** (list / create / activate).
 
-**Per-cartridge right-click actions**: **Upload Cartridge**, **Download from Instance**, **Compare with Instance** (diff view), **Add to Site Cartridge Path**, **Remove from Site Cartridge Path**.
+**Per-cartridge right-click actions**: **Upload Cartridge**, **Download from Instance**, **Add to Site Cartridge Path**, **Remove from Site Cartridge Path**.
 
 **Workspace toggles**: **Toggle Code Sync** / **Start Code Sync** / **Stop Code Sync** start a watcher that uploads on save. **Upload to Instance** is also available from the file Explorer's context menu when a code-sync session is active.
 
 <!-- TODO(screenshot): code-sync.png — Cartridges view with code-version dropdown -->
 ![Cartridge Code Sync](./images/code-sync.png)
 
-<!-- TODO(screenshot): code-sync-diff.png — Compare with Instance result -->
-![Code Sync diff](./images/code-sync-diff.png)
-
 ## SCAPI API Browser
 
 Browse SCAPI OpenAPI schemas for your instance and open a Swagger UI panel for any endpoint. Requires OAuth credentials (`clientId`, `clientSecret`) and `shortCode` in `dw.json` — see the [Authentication Setup guide](../guide/authentication).

docs/vscode-extension/images/code-sync-diff.png

@@ -76,7 +76,7 @@ The extension reads B2C Commerce credentials and project settings using the **sa
 
 See the [Authentication Setup guide](../guide/authentication) for credential formats and OAuth scope requirements, and the [CLI Configuration guide](../guide/configuration) for the full list of supported config sources and precedence rules.
 
-For multi-root workspaces, right-click any folder in the Explorer and choose **Use as B2C Commerce Root** to pin which folder the extension treats as the project root. Pair with **Reset B2C Commerce Root to Auto-Detect** to clear the pin.
+For multi-root workspaces (more than one folder open), right-click a workspace-root folder in the Explorer and choose **Use as B2C Commerce Root** to pin which folder the extension treats as the project root. To clear the pin, run **B2C DX: Reset B2C Commerce Root to Auto-Detect** from the Command Palette.
 
 ## Next Steps
 

docs/vscode-extension/installation.md

@@ -23,8 +23,10 @@
  * release ships, this fallback is the expected state.
  *
  * Cache: writes the resolved data to `docs/.vitepress/cache/release-vscode.json`
- * to avoid re-hitting the API on repeat local builds. Delete that file (or
- * `pnpm run docs:build` from a clean cache) to force a refresh.
+ * with a 24-hour TTL so repeat local builds don't re-hit the API but a
+ * maintainer who cuts a release won't see a stale version on the very next
+ * local build. CI runners have no persisted cache, so each CI build hits the
+ * API once. Delete the cache file to force an immediate refresh.
  */
 
 import fs from 'node:fs';
@@ -41,6 +43,12 @@ export interface ReleaseData {
   publishedAt?: string;
 }
 
+interface CachedReleaseData extends ReleaseData {
+  cachedAt: string;
+}
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
 const REPO = 'SalesforceCommerceCloud/b2c-developer-tooling';
 const TAG_PREFIX = 'b2c-vs-extension@';
 const SEMVER_TAG_RE = /^b2c-vs-extension@\d+\.\d+\.\d+$/;
@@ -62,19 +70,22 @@ const CACHE_FILE = path.resolve(__dirname, '..', '.vitepress', 'cache', 'release
 
 function readCache(): ReleaseData | undefined {
   try {
-    if (fs.existsSync(CACHE_FILE)) {
-      return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8')) as ReleaseData;
-    }
+    if (!fs.existsSync(CACHE_FILE)) return undefined;
+    const cached = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8')) as CachedReleaseData;
+    if (!cached.cachedAt) return undefined;
+    if (Date.now() - Date.parse(cached.cachedAt) > CACHE_TTL_MS) return undefined;
+    const {cachedAt: _cachedAt, ...data} = cached;
+    return data;
   } catch {
-    /* ignore */
+    return undefined;
   }
-  return undefined;
 }
 
 function writeCache(data: ReleaseData): void {
   try {
     fs.mkdirSync(path.dirname(CACHE_FILE), {recursive: true});
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+    const payload: CachedReleaseData = {...data, cachedAt: new Date().toISOString()};
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2));
   } catch {
     /* ignore */
   }

docs/vscode-extension/release.data.ts

@@ -48,6 +48,10 @@ suite('extension activation', () => {
     assert.ok(ext?.isActive, 'extension should be active after suiteSetup activate()');
   });
 
+  // This is the workhorse check. The extension's top-level try/catch
+  // (extension.ts:117-136) registers only three stub commands on failure
+  // (openUI, promptAgent, listWebDav), so any swallowed activation error
+  // surfaces here as a flood of missing commands.
   test('every contributed command is registered', async () => {
     const registered = new Set(await vscode.commands.getCommands(true));
     const missing = pkg.contributes.commands.filter((c) => !registered.has(c.command));

packages/b2c-vs-extension/src/test/integration/activation.test.ts

@@ -8,73 +8,56 @@ import * as assert from 'assert';
 import type {B2CExtensionConfig} from '../config-provider.js';
 import {WebDavMappingsProvider} from '../webdav-tree/webdav-mappings.js';
 
-interface ResetEmitter {
-  fire(): void;
-}
-
-function makeStubConfig(values: Record<string, unknown>): {provider: B2CExtensionConfig; reset: ResetEmitter} {
-  let resetListener: (() => void) | undefined;
+function makeStubConfig(values: Record<string, unknown>): B2CExtensionConfig {
   const stub = {
     getConfig: () => ({values}),
-    onDidReset: (listener: () => void) => {
-      resetListener = listener;
-      return {dispose() {}};
-    },
-  };
-  return {
-    provider: stub as unknown as B2CExtensionConfig,
-    reset: {
-      fire() {
-        resetListener?.();
-      },
-    },
+    onDidReset: (_listener: () => void) => ({dispose() {}}),
   };
+  return stub as unknown as B2CExtensionConfig;
 }
 
 suite('WebDavMappingsProvider', () => {
   test('seedFromConfig dedupes contentLibrary against libraries', () => {
-    const {provider} = makeStubConfig({libraries: ['lib-a', 'lib-b'], contentLibrary: 'lib-a'});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(
+      makeStubConfig({libraries: ['lib-a', 'lib-b'], contentLibrary: 'lib-a'}),
+    );
     mappings.seedFromConfig();
 
     assert.deepStrictEqual(mappings.getLibraryIds().sort(), ['lib-a', 'lib-b']);
   });
 
   test('seedFromConfig adds contentLibrary when not already in libraries', () => {
-    const {provider} = makeStubConfig({libraries: ['lib-a'], contentLibrary: 'lib-c'});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({libraries: ['lib-a'], contentLibrary: 'lib-c'}));
     mappings.seedFromConfig();
 
     assert.deepStrictEqual(mappings.getLibraryIds().sort(), ['lib-a', 'lib-c']);
   });
 
   test('seedFromConfig copies catalogs verbatim', () => {
-    const {provider} = makeStubConfig({catalogs: ['cat-1', 'cat-2']});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({catalogs: ['cat-1', 'cat-2']}));
     mappings.seedFromConfig();
 
     assert.deepStrictEqual(mappings.getCatalogIds(), ['cat-1', 'cat-2']);
   });
 
   test('getEffectiveContentLibrary prefers explicit contentLibrary over libraries[0]', () => {
-    const {provider} = makeStubConfig({libraries: ['lib-a', 'lib-b'], contentLibrary: 'lib-b'});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(
+      makeStubConfig({libraries: ['lib-a', 'lib-b'], contentLibrary: 'lib-b'}),
+    );
     mappings.seedFromConfig();
 
     assert.strictEqual(mappings.getEffectiveContentLibrary(), 'lib-b');
   });
 
   test('getEffectiveContentLibrary falls back to libraries[0] when contentLibrary is unset', () => {
-    const {provider} = makeStubConfig({libraries: ['lib-a', 'lib-b']});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({libraries: ['lib-a', 'lib-b']}));
     mappings.seedFromConfig();
 
     assert.strictEqual(mappings.getEffectiveContentLibrary(), 'lib-a');
   });
 
   test('addCatalog is a no-op when the id is already present', () => {
-    const {provider} = makeStubConfig({catalogs: ['cat-1']});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({catalogs: ['cat-1']}));
     mappings.seedFromConfig();
 
     let fires = 0;
@@ -90,8 +73,7 @@ suite('WebDavMappingsProvider', () => {
   });
 
   test('removeCatalog is a no-op when the id is absent', () => {
-    const {provider} = makeStubConfig({catalogs: ['cat-1']});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({catalogs: ['cat-1']}));
     mappings.seedFromConfig();
 
     let fires = 0;
@@ -106,8 +88,7 @@ suite('WebDavMappingsProvider', () => {
   });
 
   test('addLibrary / removeLibrary mirror catalog behavior', () => {
-    const {provider} = makeStubConfig({libraries: []});
-    const mappings = new WebDavMappingsProvider(provider);
+    const mappings = new WebDavMappingsProvider(makeStubConfig({libraries: []}));
     mappings.seedFromConfig();
 
     let fires = 0;