feat(vs-extension): API Browser shopper-schema → sfnext scapi add (#457)

* feat(vs-extension): API Browser shopper-schema → sfnext scapi add

Right-click a Shopper schema in the API Browser to run
`pnpm sfnext scapi add <family> <name> <version>` in an integrated
terminal. Menu is gated on Storefront Next workspace detection
(via @salesforce/b2c-tooling-sdk/discovery) so it only appears in
sfnext projects. Logs detection + invocation to the B2C DX output
channel for diagnosis.

* refactor(vs-extension): trim verbose API Browser diagnostic logging

Author: clavery

.changeset/api-browser-sfnext-scapi-add.md

@@ -0,0 +1,5 @@
+---
+'b2c-vs-extension': minor
+---
+
+API Browser: right-click a Shopper schema to run `pnpm sfnext scapi add` in an integrated terminal. The action is only shown when the workspace is detected as a Storefront Next project.

packages/b2c-vs-extension/package.json

@@ -261,6 +261,12 @@
         "title": "Open API Documentation",
         "category": "B2C DX - API Browser"
       },
+      {
+        "command": "b2c-dx.apiBrowser.scapiAdd",
+        "title": "Add to Storefront (sfnext scapi add)",
+        "icon": "$(add)",
+        "category": "B2C DX - API Browser"
+      },
       {
         "command": "b2c-dx.sandbox.refresh",
         "title": "Refresh",
@@ -680,6 +686,11 @@
         }
       ],
       "view/item/context": [
+        {
+          "command": "b2c-dx.apiBrowser.scapiAdd",
+          "when": "view == b2cApiBrowser && viewItem == apiSchema-shopper && b2c-dx.isStorefrontNext",
+          "group": "1_storefront@1"
+        },
         {
           "command": "b2c-dx.webdav.addCatalog",
           "when": "view == b2cWebdavExplorer && viewItem == virtual-root-catalogs",
@@ -902,6 +913,10 @@
           "command": "b2c-dx.apiBrowser.openSwagger",
           "when": "false"
         },
+        {
+          "command": "b2c-dx.apiBrowser.scapiAdd",
+          "when": "false"
+        },
         {
           "command": "b2c-dx.sandbox.removeRealm",
           "when": "false"

packages/b2c-vs-extension/src/api-browser/api-browser-tree-provider.ts

@@ -27,6 +27,12 @@ export interface SchemaEntry {
   status?: 'current' | 'deprecated';
 }
 
+export function isShopperSchema(schema: Pick<SchemaEntry, 'apiFamily' | 'apiName'>): boolean {
+  const family = (schema.apiFamily ?? '').toLowerCase();
+  const name = (schema.apiName ?? '').toLowerCase();
+  return family.startsWith('shopper') || name.startsWith('shopper');
+}
+
 export class ApiSchemaTreeItem extends vscode.TreeItem {
   readonly nodeType = 'apiSchema' as const;
   readonly schema: SchemaEntry;
@@ -36,7 +42,11 @@ export class ApiSchemaTreeItem extends vscode.TreeItem {
     this.schema = schema;
     this.id = `api:schema:${schema.apiFamily}:${schema.apiName}:${schema.apiVersion}`;
     this.description = schema.apiVersion;
-    this.contextValue = 'apiSchema';
+
+    // The contextValue drives the Storefront Next "scapi add" right-click menu,
+    // which is only offered for Shopper schemas (see isShopperSchema + package.json).
+    const isShopper = isShopperSchema(schema);
+    this.contextValue = isShopper ? 'apiSchema-shopper' : 'apiSchema-admin';
 
     // Tooltip type is best-effort — the authoritative classification happens
     // when the spec is loaded (see detectApiType in swagger-webview.ts) since
@@ -45,12 +55,12 @@ export class ApiSchemaTreeItem extends vscode.TreeItem {
     let apiType: string;
     if (schema.apiFamily === 'custom') {
       apiType = 'Custom';
-    } else if (schema.apiName.startsWith('shopper-') || schema.apiFamily === 'shopper') {
+    } else if (isShopper) {
       apiType = 'Shopper';
     } else {
       apiType = 'Admin';
     }
-    this.tooltip = `${schema.apiName} ${schema.apiVersion} (${apiType})`;
+    this.tooltip = `${schema.apiName} ${schema.apiVersion} (${apiType}) — apiFamily="${schema.apiFamily}"`;
 
     if (schema.status === 'deprecated') {
       this.iconPath = new vscode.ThemeIcon('warning', new vscode.ThemeColor('list.warningForeground'));

packages/b2c-vs-extension/src/api-browser/index.ts

@@ -6,9 +6,26 @@
 import * as vscode from 'vscode';
 import type {B2CExtensionConfig} from '../config-provider.js';
 import {registerSafeCommand} from '../safety.js';
-import {ApiBrowserTreeDataProvider, type SchemaEntry} from './api-browser-tree-provider.js';
+import {
+  ApiBrowserTreeDataProvider,
+  ApiSchemaTreeItem,
+  isShopperSchema,
+  type SchemaEntry,
+} from './api-browser-tree-provider.js';
 import {SwaggerWebviewManager} from './swagger-webview.js';
 
+const SFNEXT_TERMINAL_NAME = 'sfnext scapi add';
+
+function runSfnextScapiAdd(schema: SchemaEntry, cwd: string, log: vscode.OutputChannel): void {
+  const existing = vscode.window.terminals.find((t) => t.name === SFNEXT_TERMINAL_NAME);
+  const terminal = existing ?? vscode.window.createTerminal({name: SFNEXT_TERMINAL_NAME, cwd});
+  const command = `pnpm sfnext scapi add ${schema.apiFamily} ${schema.apiName} ${schema.apiVersion}`;
+  log.appendLine(`[API Browser] Spawning terminal "${SFNEXT_TERMINAL_NAME}" (cwd=${cwd})`);
+  log.appendLine(`[API Browser] $ ${command}`);
+  terminal.show();
+  terminal.sendText(command);
+}
+
 export function registerApiBrowser(
   context: vscode.ExtensionContext,
   configProvider: B2CExtensionConfig,
@@ -30,9 +47,24 @@ export function registerApiBrowser(
     swaggerManager.openSwaggerPanel(schema);
   });
 
+  const scapiAddDisposable = registerSafeCommand(
+    'b2c-dx.apiBrowser.scapiAdd',
+    (item: ApiSchemaTreeItem | SchemaEntry) => {
+      const schema = item instanceof ApiSchemaTreeItem ? item.schema : item;
+      if (!schema || !isShopperSchema(schema)) {
+        const msg = `Storefront Next scapi add is only available for Shopper schemas (got apiFamily="${schema?.apiFamily ?? '<missing>'}", apiName="${schema?.apiName ?? '<missing>'}").`;
+        log.appendLine(`[API Browser] ${msg}`);
+        vscode.window.showErrorMessage(msg);
+        return;
+      }
+      const cwd = configProvider.getWorkingDirectory();
+      runSfnextScapiAdd(schema, cwd, log);
+    },
+  );
+
   configProvider.onDidReset(() => {
     treeProvider.refresh();
   });
 
-  context.subscriptions.push(treeView, refreshDisposable, openSwaggerDisposable, swaggerManager);
+  context.subscriptions.push(treeView, refreshDisposable, openSwaggerDisposable, scapiAddDisposable, swaggerManager);
 }

packages/b2c-vs-extension/src/extension.ts

@@ -4,6 +4,7 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 import {DwJsonSource} from '@salesforce/b2c-tooling-sdk/config';
+import {detectWorkspaceType} from '@salesforce/b2c-tooling-sdk/discovery';
 import {configureLogger} from '@salesforce/b2c-tooling-sdk/logging';
 
 import * as path from 'path';
@@ -48,6 +49,27 @@ function applyLogLevel(log: vscode.OutputChannel): void {
   }
 }
 
+async function updateStorefrontNextContext(
+  configProvider: B2CExtensionConfig,
+  log: vscode.OutputChannel,
+): Promise<void> {
+  const workingDir = configProvider.getWorkingDirectory();
+  log.appendLine(`[Workspace] Running detectWorkspaceType for cwd=${workingDir}`);
+  let isStorefrontNext = false;
+  try {
+    const result = await detectWorkspaceType(workingDir);
+    log.appendLine(
+      `[Workspace] Detection result: projectTypes=[${result.projectTypes.join(', ')}] matchedPatterns=[${result.matchedPatterns.join(', ')}]`,
+    );
+    isStorefrontNext = result.projectTypes.includes('storefront-next');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.appendLine(`[Workspace] storefront-next detection failed: ${message}`);
+  }
+  await vscode.commands.executeCommand('setContext', 'b2c-dx.isStorefrontNext', isStorefrontNext);
+  log.appendLine(`[Workspace] setContext b2c-dx.isStorefrontNext=${isStorefrontNext} (cwd=${workingDir})`);
+}
+
 export async function activate(context: vscode.ExtensionContext) {
   const log = vscode.window.createOutputChannel('B2C DX');
 
@@ -101,6 +123,13 @@ async function activateInner(context: vscode.ExtensionContext, log: vscode.Outpu
 
   registerSafety(context, configProvider);
 
+  void updateStorefrontNextContext(configProvider, log);
+  context.subscriptions.push(
+    configProvider.onDidReset(() => {
+      void updateStorefrontNextContext(configProvider, log);
+    }),
+  );
+
   const cartridgeService = new CartridgeService(configProvider);
   context.subscriptions.push(cartridgeService);