vs-extension: build/packaging hardening + Phase 1 correctness & UX fixes (#475)

* chore(vs-extension): harden build and packaging pipeline

- Move SDK package.json inlining from a post-bundle string-replace to a
  source-load esbuild plugin so minification cannot break the substitution.
  Build-time assertion guards against drift if SDK call sites change.
- Stage all SDK data dirs (cip-proto, script-api, content-schemas,
  scaffolds) into dist/data/ — was only scaffolds, leaving latent breakage
  when content-validation / CIP / Script API code paths reach packageRoot.
- Replace zip/unzip CLI shellouts in inject-script-types.mjs with pure-Node
  JSZip. Removes the host-binary requirement (improves Windows compatibility)
  and the [Content_Types].xml shell-glob escapes. Fixes a regression where
  injected entries were emitted without their leading-dot extension form.
- Production hardening: minify, drop:['debugger'], target node22,
  legalComments:'none'.
- esbuild define injects __EXT_VERSION__ and __TELEMETRY_CONNECTION_STRING__
  so telemetry.ts no longer readFileSync(package.json) at runtime.
- Single syncStaticAssets() shared by watch and production paths so the
  two layouts can no longer drift.
- vscode:prepublish now builds @salesforce/b2c-script-types before the SDK
  and the bundle, so a stale plugin tree can no longer ship.
- .vscodeignore: drop dead negations for HTML files that don't exist; add
  dist/meta.json so ANALYZE_BUNDLE artifacts don't ship.

* fix(vs-extension): correctness and UX hardening (Phase 1)

Implements 7 audit items targeting present-day defects, not hypothetical
threats. Trust model: SCAPI specs are trusted, user-typed input via own
forms is trusted, single-developer workstation.

- ContentFileSystemProvider.stat() now returns a stable mtime (cached in
  a Map<string, number> keyed by libraryId:contentId, bumped on writeFile
  success) instead of Date.now() per call. VS Code no longer thinks
  content files are constantly mutating; phantom "file modified
  externally" prompts and silent buffer reloads are gone.
- WebDAV FileSystemProvider.rename() now delegates to instance.webdav.move
  instead of unconditionally throwing NoPermissions. F2-rename works in
  the explorer; cross-root attempts and 412 conflicts map to the right
  FileSystemError values.
- Replaced sync fs.readFileSync/existsSync/statSync on the activation hot
  path (B2CExtensionConfig) with vscode.workspace.fs async equivalents.
  CAP file-decoration provider now answers via the existing capUris Set
  in O(1) instead of two syscalls per paint.
- Long-running operations (sandbox clone polling, CAP install, deploy,
  content export, Swagger UI proxy fetches) are now cancellable via
  withProgress({cancellable: true}) and token.isCancellationRequested
  checks at loop boundaries. Server-side abort requires SDK AbortSignal
  support which is a separate change.
- Every TreeDataProvider now sets a stable TreeItem.id (e.g.,
  realm:NAME, sandbox:REALM:ID, webdav:TYPE:PATH, api:family:NAME, etc.)
  so expand state survives refresh and treeView.reveal() works without
  try/catch fallback.
- 11 commands that previously bypassed registerSafeCommand — including
  b2c-dx.sandbox.clone (a billable mutation) — now route through the
  SafetyGuard pipeline with feature-usage telemetry. Added scriptTypes
  to FeatureCategory and the command-prefix mapping.
- Dead code removal: createDeleteAndDeployCommand, tempDirs cleanup loop
  in cartridge-commands, openExternal branch in Page Designer message
  handler, and the never-implemented b2c-dx.codeSync.diffCartridge stub.

Author: clavery

.changeset/vsix-build-packaging-hardening.md

@@ -0,0 +1,5 @@
+---
+'b2c-vs-extension': patch
+---
+
+Harden the extension build and packaging pipeline. The esbuild bundle now minifies, drops debugger statements, targets Node 22 (matching VS Code 1.105's runtime), and inlines `require('@salesforce/b2c-tooling-sdk/package.json')` at SDK source-load time so minification can no longer break the substitution. SDK data directories that the runtime expects (`cip-proto`, `script-api`, `content-schemas`, `scaffolds`) are all staged into `dist/data/` instead of just `scaffolds`. The `inject-script-types` step that adds the bundled TypeScript Server plugin to the VSIX now uses pure-Node JSZip instead of shelling out to `zip`/`unzip`, removing the host-binary requirement (Windows CI compatibility) and fixing a regression where `[Content_Types].xml` entries for the injected plugin were emitted without their leading dot. The extension version and telemetry connection string are now injected as build-time constants, eliminating a runtime `readFileSync(package.json)`. `vscode:prepublish` now builds `@salesforce/b2c-script-types` before the extension bundle so a stale plugin tree can no longer ship.

.changeset/vsix-phase1-correctness-ux.md

@@ -0,0 +1,13 @@
+---
+'b2c-vs-extension': patch
+---
+
+Correctness and UX hardening pass across the extension:
+
+- **Content libraries**: `ContentFileSystemProvider.stat()` now returns a stable `mtime` instead of `Date.now()` per call. VS Code no longer believes content files are constantly mutating, eliminating phantom "file modified externally" prompts and silent buffer reloads that could clobber unsaved edits.
+- **WebDAV explorer**: F2-rename now works. The `rename()` method delegates to the SDK's `webdav.move` (already used by drag-and-drop) instead of throwing `NoPermissions`. Cross-root attempts and 412 conflicts are mapped to the right `vscode.FileSystemError`.
+- **Activation performance**: replaced sync `fs.readFileSync` / `existsSync` / `statSync` on the activation hot path (`B2CExtensionConfig`) and in the per-paint CAP file-decoration provider with `vscode.workspace.fs` async equivalents and a Set lookup, respectively. CAP decorations now answer in O(1) without filesystem syscalls.
+- **Cancellation**: long-running operations (sandbox clone polling, CAP install, deploy, content export, Swagger UI proxy fetches) now show a working Cancel button. Cancelling stops the local poll/wait; aborting the server-side operation requires SDK `AbortSignal` support which is a separate change.
+- **Tree state stability**: every tree provider (sandbox, WebDAV, content libraries, API browser, cartridges) now sets a stable `TreeItem.id`, so expand/collapse state survives refresh and `treeView.reveal()` works without try/catch fallback.
+- **Safety + telemetry coverage**: 11 contributed commands previously bypassed `registerSafeCommand`, including `b2c-dx.sandbox.clone` (a billable operation). All now route through the safety guard and feature-usage telemetry. Added a `scriptTypes` feature category and command-prefix mapping.
+- **Dead code removal**: removed an unused `createDeleteAndDeployCommand`, the unused `tempDirs` cleanup loop in `cartridge-commands`, the dead `openExternal` branch in the Page Designer webview message handler, and the never-implemented `b2c-dx.codeSync.diffCartridge` command.

packages/b2c-vs-extension/.vscodeignore

@@ -3,11 +3,9 @@
 src/**
 !src/webview.html
 !src/api-browser/swagger-webview.html
-!src/storefront-next-cartridge.html
-!src/scapi-explorer.html
-!src/ods-management.html
 out/**
 **/node_modules/**
+dist/meta.json
 
 !src/template/**
 .gitignore

packages/b2c-vs-extension/package.json

@@ -569,12 +569,6 @@
         "icon": "$(cloud-download)",
         "category": "B2C DX - Code Sync"
       },
-      {
-        "command": "b2c-dx.codeSync.diffCartridge",
-        "title": "Compare with Instance",
-        "icon": "$(diff)",
-        "category": "B2C DX - Code Sync"
-      },
       {
         "command": "b2c-dx.codeSync.addToSitePath",
         "title": "Add to Site Cartridge Path",
@@ -1022,10 +1016,6 @@
           "command": "b2c-dx.codeSync.downloadCartridge",
           "when": "false"
         },
-        {
-          "command": "b2c-dx.codeSync.diffCartridge",
-          "when": "false"
-        },
         {
           "command": "b2c-dx.codeSync.addToSitePath",
           "when": "false"
@@ -1040,7 +1030,7 @@
   "scripts": {
     "build": "node scripts/esbuild-bundle.mjs",
     "watch": "node scripts/esbuild-bundle.mjs --watch",
-    "vscode:prepublish": "pnpm run typecheck:agent && pnpm --filter @salesforce/b2c-tooling-sdk run build && node scripts/esbuild-bundle.mjs",
+    "vscode:prepublish": "pnpm run typecheck:agent && pnpm --filter @salesforce/b2c-script-types run build && pnpm --filter @salesforce/b2c-tooling-sdk run build && node scripts/esbuild-bundle.mjs",
     "package": "pnpm exec vsce package --no-dependencies && node scripts/inject-script-types.mjs",
     "lint": "eslint",
     "lint:agent": "eslint --quiet",
@@ -1062,6 +1052,7 @@
     "@vscode/vsce": "^3.9.1",
     "c8": "catalog:",
     "esbuild": "^0.24.0",
+    "jszip": "3.10.1",
     "swagger-ui-dist": "^5.18.0",
     "eslint": "catalog:",
     "eslint-config-prettier": "catalog:",

packages/b2c-vs-extension/scripts/esbuild-bundle.mjs

@@ -4,121 +4,195 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 /**
- * Bundles the extension with esbuild. Injects a shim for import.meta.url so
- * SDK code that uses createRequire(import.meta.url) works in CJS output.
+ * Bundles the extension with esbuild.
+ *
+ * - Shims `import.meta.url` so SDK code that uses `createRequire(import.meta.url)`
+ *   works in CJS output.
+ * - Inlines `require('@salesforce/b2c-tooling-sdk/package.json')` and
+ *   `require.resolve(...)` calls at LOAD time (i.e., on the SDK source before
+ *   esbuild parses/minifies it) so the runtime doesn't try to resolve out of
+ *   node_modules — `vsce --no-dependencies` never ships node_modules. Doing
+ *   this at load time (rather than as a post-bundle string-replace) means
+ *   minification can't break the pattern. A build-time assertion guards against
+ *   regex drift.
+ * - Stages static assets (SDK data dirs, script-types plugin, swagger-ui)
+ *   into dist/ via a single helper used by both watch and production paths.
+ * - Build-time `define` injects the extension version and telemetry connection
+ *   string so the runtime doesn't have to readFileSync(package.json).
  */
 import esbuild from 'esbuild';
 import fs from 'node:fs';
-import path from 'path';
-import {fileURLToPath} from 'url';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // scripts/ -> package root
 const pkgRoot = path.resolve(__dirname, '..');
+const sdkRoot = path.join(pkgRoot, '..', 'b2c-tooling-sdk');
+const sdkPkgJsonPath = path.join(sdkRoot, 'package.json');
+const scriptTypesRoot = path.join(pkgRoot, '..', 'b2c-script-types');
+const watchMode = process.argv.includes('--watch');
+
+const extPkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
 
 // In CJS there is no import.meta; SDK's version.js uses createRequire(import.meta.url). Shim it.
 // Use globalThis so the value is visible inside all module wrappers in the bundle.
 const IMPORT_META_URL_SHIM =
   "if (typeof globalThis.__import_meta_url === 'undefined') { try { globalThis.__import_meta_url = require('url').pathToFileURL(__filename).href; } catch (_) {} }";
 
+// Match a `require()` of the SDK package.json *before* minification. Bound to the literal
+// `require` identifier (not a renamed minified local) because we run on source files.
+const SDK_PKG_REQUIRE_RE = /require\s*\(\s*["']@salesforce\/b2c-tooling-sdk\/package\.json["']\s*\)/g;
+const SDK_PKG_REQUIRE_RESOLVE_RE =
+  /require\s*\.\s*resolve\s*\(\s*["']@salesforce\/b2c-tooling-sdk\/package\.json["']\s*\)/g;
+// `require('path').join(__dirname, 'package.json')` evaluates at runtime to <extension-dist>/package.json,
+// so `path.dirname(...)` gives the extension's dist/ directory — where SDK data dirs are staged.
+const SDK_PKG_REQUIRE_RESOLVE_REPLACEMENT = "require('path').join(__dirname, 'package.json')";
+
+let sdkPkgRequireHits = 0;
+let sdkPkgResolveHits = 0;
+let sdkPkgInlinedJson;
+
 function loaderFor(filePath) {
+  if (filePath.endsWith('.tsx')) return 'tsx';
   const ext = path.extname(filePath);
-  if (ext === '.ts' || filePath.endsWith('.tsx')) return 'ts';
+  if (ext === '.ts') return 'ts';
   return 'js';
 }
 
-const importMetaUrlPlugin = {
-  name: 'import-meta-url-shim',
+/**
+ * Source-level transform plugin:
+ * - Replace `import.meta.url` with a globalThis shim (CJS has no import.meta).
+ * - Inline `require('@salesforce/b2c-tooling-sdk/package.json')` and `require.resolve(...)`
+ *   with the JSON literal / runtime __dirname path. Done at LOAD time so minification can't
+ *   break the pattern.
+ */
+const sdkSourceShimPlugin = {
+  name: 'sdk-source-shim',
   setup(build) {
+    build.onStart(() => {
+      sdkPkgRequireHits = 0;
+      sdkPkgResolveHits = 0;
+      sdkPkgInlinedJson = JSON.stringify(JSON.parse(fs.readFileSync(sdkPkgJsonPath, 'utf8')));
+    });
     build.onLoad({filter: /\.(ts|tsx|js|mjs|cjs)$/}, (args) => {
-      const contents = fs.readFileSync(args.path, 'utf-8');
-      const replaced = contents.includes('import.meta.url')
-        ? contents.replace(/import\.meta\.url/g, 'globalThis.__import_meta_url')
-        : contents;
-      return {contents: replaced, loader: loaderFor(args.path)};
+      const original = fs.readFileSync(args.path, 'utf8');
+      const hasImportMeta = original.includes('import.meta.url');
+      const hasRequirePkg = SDK_PKG_REQUIRE_RE.test(original);
+      // test() advances lastIndex; reset before re-using elsewhere.
+      SDK_PKG_REQUIRE_RE.lastIndex = 0;
+      const hasResolvePkg = SDK_PKG_REQUIRE_RESOLVE_RE.test(original);
+      SDK_PKG_REQUIRE_RESOLVE_RE.lastIndex = 0;
+
+      if (!hasImportMeta && !hasRequirePkg && !hasResolvePkg) return null;
+
+      let contents = original;
+      if (hasImportMeta) {
+        contents = contents.replace(/import\.meta\.url/g, 'globalThis.__import_meta_url');
+      }
+      if (hasResolvePkg) {
+        // Must run BEFORE the bare-require replacement, since `require.resolve(...)` also matches the bare regex.
+        contents = contents.replace(SDK_PKG_REQUIRE_RESOLVE_RE, () => {
+          sdkPkgResolveHits++;
+          return SDK_PKG_REQUIRE_RESOLVE_REPLACEMENT;
+        });
+      }
+      if (hasRequirePkg) {
+        contents = contents.replace(SDK_PKG_REQUIRE_RE, () => {
+          sdkPkgRequireHits++;
+          return sdkPkgInlinedJson;
+        });
+      }
+      return {contents, loader: loaderFor(args.path)};
+    });
+    build.onEnd((result) => {
+      if (watchMode) return;
+      if (result.errors && result.errors.length > 0) return;
+      if (sdkPkgRequireHits === 0 && sdkPkgResolveHits === 0) {
+        throw new Error(
+          '[sdk-source-shim] expected at least one require()/require.resolve() of ' +
+            "'@salesforce/b2c-tooling-sdk/package.json' in SDK source, found none. " +
+            'SDK code may have changed; update SDK_PKG_REQUIRE_RE / SDK_PKG_REQUIRE_RESOLVE_RE.',
+        );
+      }
+      console.log(
+        `[sdk-source-shim] inlined ${sdkPkgRequireHits} require() and ${sdkPkgResolveHits} require.resolve() call(s).`,
+      );
     });
   },
 };
 
-// Inline SDK package.json so the bundle doesn't require() it at runtime (vsce --no-dependencies
-// never includes node_modules). The SDK uses createRequire() so esbuild leaves it as runtime require;
-// we replace that require in the bundle output with the actual JSON (post-build).
-// Also replace require.resolve('@salesforce/b2c-tooling-sdk/package.json') so it doesn't throw when
-// the extension runs from a VSIX (no node_modules). We use __dirname so path.dirname(...) is the extension dist.
-const sdkPkgJsonPath = path.join(pkgRoot, '..', 'b2c-tooling-sdk', 'package.json');
-const REQUIRE_RESOLVE_PACKAGE_JSON_RE =
-  /require\d*\.resolve\s*\(\s*["']@salesforce\/b2c-tooling-sdk\/package\.json["']\s*\)/g;
-const REQUIRE_RESOLVE_REPLACEMENT = "require('path').join(__dirname, 'package.json')";
-
-// Copy SDK scaffold templates into dist/ so the extension can find them at runtime.
-// The extension passes this path explicitly via createScaffoldRegistry({ builtInScaffoldsDir }).
-const sdkRoot = path.join(pkgRoot, '..', 'b2c-tooling-sdk');
-
-function copySdkScaffolds() {
-  const src = path.join(sdkRoot, 'data', 'scaffolds');
-  const dest = path.join(pkgRoot, 'dist', 'data', 'scaffolds');
-  if (!fs.existsSync(src)) return;
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return false;
   fs.cpSync(src, dest, {recursive: true});
+  return true;
 }
 
-// Stage @salesforce/b2c-script-types into the extension's node_modules so the
-// TypeScript Server plugin (declared in contributes.typescriptServerPlugins) is
-// resolvable from the extension root at runtime, even with `vsce --no-dependencies`.
+/**
+ * Copy SDK data directories into dist/data/. The SDK uses
+ * `path.dirname(require.resolve('@salesforce/b2c-tooling-sdk/package.json'))` as packageRoot
+ * and joins data subdirs to it. Since `sdkSourceShimPlugin` rewrites that resolve to
+ * `path.join(__dirname, 'package.json')`, packageRoot becomes the extension's dist/, so
+ * these data dirs must be staged there.
+ */
+const SDK_DATA_DIRS = ['scaffolds', 'cip-proto', 'script-api', 'content-schemas'];
+function copySdkDataDirs() {
+  for (const dir of SDK_DATA_DIRS) {
+    copyDir(path.join(sdkRoot, 'data', dir), path.join(pkgRoot, 'dist', 'data', dir));
+  }
+}
+
+/** Stage @salesforce/b2c-script-types into the extension's node_modules so the TypeScript Server
+ * plugin (declared in contributes.typescriptServerPlugins) is resolvable from the extension root
+ * at runtime, even with `vsce --no-dependencies`. */
 function copyScriptTypesPlugin() {
-  const src = path.join(pkgRoot, '..', 'b2c-script-types');
-  const dest = path.join(pkgRoot, 'node_modules', '@salesforce', 'b2c-script-types');
-  if (!fs.existsSync(src)) {
-    console.warn('[script-types] source not found, skipping:', src);
+  if (!fs.existsSync(scriptTypesRoot)) {
+    console.warn('[script-types] source not found, skipping:', scriptTypesRoot);
     return;
   }
+  const dest = path.join(pkgRoot, 'node_modules', '@salesforce', 'b2c-script-types');
   // Wipe any stale staged copy (or pnpm symlink) so we don't accumulate.
   if (fs.existsSync(dest) || fs.lstatSync(dest, {throwIfNoEntry: false})) {
     fs.rmSync(dest, {recursive: true, force: true});
   }
   fs.mkdirSync(path.dirname(dest), {recursive: true});
-  // Copy only the runtime artifacts; skip src/, eslint/tsconfig dev files.
   for (const entry of ['package.json', 'plugin', 'types', 'README.md', 'jsconfig.template.json']) {
-    const s = path.join(src, entry);
+    const s = path.join(scriptTypesRoot, entry);
     if (!fs.existsSync(s)) continue;
     fs.cpSync(s, path.join(dest, entry), {recursive: true});
   }
   console.log('[script-types] staged', path.relative(pkgRoot, dest));
 }
 
-function inlineSdkPackageJson() {
-  const outPath = path.join(pkgRoot, 'dist', 'extension.cjs');
-  let str = fs.readFileSync(outPath, 'utf8');
-  const sdkPkg = JSON.stringify(JSON.parse(fs.readFileSync(sdkPkgJsonPath, 'utf8')));
-  str = str.replace(/require\d*\s*\(\s*["']@salesforce\/b2c-tooling-sdk\/package\.json["']\s*\)/g, sdkPkg);
-  str = str.replace(REQUIRE_RESOLVE_PACKAGE_JSON_RE, REQUIRE_RESOLVE_REPLACEMENT);
-  fs.writeFileSync(outPath, str, 'utf8');
-}
-
 /** Copy Swagger UI assets to dist/swagger-ui/ for the API Browser webview. */
 function copySwaggerUiAssets() {
-  // Resolve the swagger-ui-dist package location (pnpm may hoist it)
   const swaggerUiIndex = fileURLToPath(import.meta.resolve('swagger-ui-dist'));
   const swaggerUiDist = path.dirname(swaggerUiIndex);
   const outDir = path.join(pkgRoot, 'dist', 'swagger-ui');
   fs.mkdirSync(outDir, {recursive: true});
-
   const files = ['swagger-ui-bundle.js', 'swagger-ui-standalone-preset.js', 'swagger-ui.css'];
   for (const file of files) {
     fs.copyFileSync(path.join(swaggerUiDist, file), path.join(outDir, file));
   }
-  console.log(`[swagger-ui] Copied ${files.length} assets to dist/swagger-ui/`);
+  console.log(`[swagger-ui] copied ${files.length} assets to dist/swagger-ui/`);
 }
 
-const watchMode = process.argv.includes('--watch');
+/** Single helper invoked by both watch and production paths so they ship the same dist/ layout. */
+function syncStaticAssets() {
+  copySdkDataDirs();
+  copyScriptTypesPlugin();
+  copySwaggerUiAssets();
+}
 
 const buildOptions = {
   entryPoints: [path.join(pkgRoot, 'src', 'extension.ts')],
   bundle: true,
   platform: 'node',
   format: 'cjs',
-  target: 'node18',
+  // VS Code 1.105 ships Node 22; align with engines.
+  target: 'node22',
   outfile: path.join(pkgRoot, 'dist', 'extension.cjs'),
   sourcemap: true,
   metafile: true,
@@ -128,27 +202,31 @@ const buildOptions = {
   conditions: watchMode ? ['development', 'require', 'node', 'default'] : ['require', 'node', 'default'],
   mainFields: ['main', 'module'],
   banner: {js: IMPORT_META_URL_SHIM},
-  plugins: [importMetaUrlPlugin],
+  plugins: [sdkSourceShimPlugin],
+  // Build-time constants — read once at bundle time so the runtime doesn't readFileSync(package.json).
+  define: {
+    __EXT_VERSION__: JSON.stringify(extPkg.version),
+    __TELEMETRY_CONNECTION_STRING__: JSON.stringify(extPkg.telemetry?.connectionString ?? ''),
+  },
+  minify: !watchMode,
+  drop: watchMode ? [] : ['debugger'],
+  legalComments: 'none',
   logLevel: 'info',
 };
 
 if (watchMode) {
-  copySdkScaffolds();
-  copyScriptTypesPlugin();
+  syncStaticAssets();
   const ctx = await esbuild.context(buildOptions);
   await ctx.watch();
   console.log('[esbuild] watching for changes...');
 } else {
   const result = await esbuild.build(buildOptions);
 
-  inlineSdkPackageJson();
-  copySdkScaffolds();
-  copyScriptTypesPlugin();
-  copySwaggerUiAssets();
+  syncStaticAssets();
 
   if (result.metafile && process.env.ANALYZE_BUNDLE) {
     const metaPath = path.join(pkgRoot, 'dist', 'meta.json');
-    fs.writeFileSync(metaPath, JSON.stringify(result.metafile, null, 2), 'utf-8');
+    fs.writeFileSync(metaPath, JSON.stringify(result.metafile, null, 2), 'utf8');
     const inputs = Object.entries(result.metafile.inputs).map(([file, info]) => ({
       file: path.relative(pkgRoot, file),
       bytes: info.bytes,