refactor sfra detect and workspace types

Author: yhsieh1

packages/b2c-dx-mcp/README.md

@@ -61,23 +61,25 @@ When neither `--toolsets` nor `--tools` are provided, the MCP server automatical
 **How it works:**
 
 1. The server analyzes your working directory (from `--working-directory` flag, `SFCC_WORKING_DIRECTORY` env var, or current directory)
-2. It checks for project markers like `package.json` dependencies, folder structures, and config files
-3. It enables all toolsets that match any detected project type
+2. It checks for project markers like `package.json` dependencies and `.project` files
+3. It enables all toolsets that match any detected project type, plus the base SCAPI toolset
+
+**Base Toolset:**
+
+The **SCAPI** toolset is always enabled, providing API discovery and custom API scaffolding capabilities.
 
 **Project Types and Toolsets:**
 
 | Project Type | Detection | Toolsets Enabled |
 |--------------|-----------|------------------|
 | **PWA Kit v3** | `@salesforce/pwa-kit-*`, `@salesforce/retail-react-app`, or `ccExtensibility` | PWAV3, MRT, SCAPI |
 | **Storefront Next** | `@salesforce/storefront-next-*` packages in package.json | STOREFRONTNEXT, MRT, SCAPI |
-| **SFRA** | `cartridges/` folder with controllers or templates | CARTRIDGES, SCAPI |
-| **Custom API** | `rest-apis/*/api.json` or `rest-apis/*/schema.yaml` files | CARTRIDGES, SCAPI |
-| **Headless** | `dw.json` file (no specific framework detected) | SCAPI |
-| **Unknown** | No B2C project markers found | SCAPI (fallback) |
+| **Cartridges** | Any cartridge with `.project` file (detected via `findCartridges`) | CARTRIDGES, SCAPI |
+| **No project detected** | No B2C project markers found | SCAPI (base toolset only) |
 
 **Hybrid Projects:**
 
-If multiple project types are detected (e.g., SFRA + Custom API), toolsets from all matched types are combined.
+If multiple project types are detected (e.g., cartridges + PWA Kit v3), toolsets from all matched types are combined.
 
 **Example:**
 
@@ -109,6 +111,8 @@ If multiple project types are detected (e.g., SFRA + Custom API), toolsets from
 
 > **Note:** Cursor supports `${workspaceFolder}` variable expansion, but Claude Desktop does not. For Claude Desktop, use an explicit path or set the `SFCC_WORKING_DIRECTORY` environment variable.
 
+> **Warning:** MCP clients like Cursor and Claude Desktop often spawn servers from the home directory (`~`) rather than the project directory. Always set `--working-directory` or `SFCC_WORKING_DIRECTORY` for reliable auto-discovery and scaffolding operations.
+
 ### Configuration Examples
 
 ```json

packages/b2c-dx-mcp/src/registry.ts

@@ -17,49 +17,45 @@ import {createScapiTools} from './tools/scapi/index.js';
 import {createStorefrontNextTools} from './tools/storefrontnext/index.js';
 
 /**
- * Maps a single project type to its associated MCP toolsets.
+ * Base toolset that is always enabled.
+ * Provides SCAPI discovery and custom API scaffolding tools.
+ */
+const BASE_TOOLSET: Toolset = 'SCAPI';
+
+/**
+ * Toolset mapping by project type.
+ * Each project type enables specific toolsets IN ADDITION to the base toolset.
+ */
+const PROJECT_TYPE_TOOLSETS: Record<ProjectType, Toolset[]> = {
+  cartridges: ['CARTRIDGES'],
+  'pwa-kit-v3': ['PWAV3', 'MRT'],
+  'storefront-next': ['STOREFRONTNEXT', 'MRT'],
+};
+
+/**
+ * Gets toolsets for a project type, always including the base toolset.
  */
 function getToolsetsForProjectType(projectType: ProjectType): Toolset[] {
-  switch (projectType) {
-    case 'custom-api': {
-      return ['CARTRIDGES', 'SCAPI'];
-    }
-    case 'headless': {
-      return ['SCAPI'];
-    }
-    case 'pwa-kit-v3': {
-      return ['PWAV3', 'MRT', 'SCAPI'];
-    }
-    case 'sfra': {
-      return ['CARTRIDGES', 'SCAPI'];
-    }
-    case 'storefront-next': {
-      return ['STOREFRONTNEXT', 'MRT', 'SCAPI'];
-    }
-    default: {
-      // Fallback: provide basic SCAPI tools
-      return ['SCAPI'];
-    }
-  }
+  const additionalToolsets = PROJECT_TYPE_TOOLSETS[projectType] ?? [];
+  return [...additionalToolsets, BASE_TOOLSET];
 }
 
 /**
  * Maps multiple detected project types to a union of MCP toolsets.
  *
  * Combines toolsets from all matched project types, enabling hybrid
- * project support (e.g., SFRA + Custom API gets both CARTRIDGES and SCAPI).
+ * project support (e.g., cartridges + pwa-kit-v3 gets CARTRIDGES + PWAV3 + MRT + SCAPI).
  *
  * @param projectTypes - Array of detected project types
- * @returns Union of all toolsets for the detected project types
+ * @returns Union of all toolsets for the detected project types (always includes base toolset)
  */
 function getToolsetsForProjectTypes(projectTypes: ProjectType[]): Toolset[] {
-  // Fallback to SCAPI when no project types detected
-  if (projectTypes.length === 0) {
-    return ['SCAPI'];
-  }
-
   const toolsetSet = new Set<Toolset>();
 
+  // Always include base toolset
+  toolsetSet.add(BASE_TOOLSET);
+
+  // Add toolsets for each detected project type
   for (const projectType of projectTypes) {
     for (const toolset of getToolsetsForProjectType(projectType)) {
       toolsetSet.add(toolset);

packages/b2c-tooling-sdk/src/discovery/index.ts

@@ -23,13 +23,18 @@
  *
  * ## Project Types
  *
- * The detector recognizes the following project types:
+ * The detector recognizes 3 workspace types:
  *
- * - `pwa-kit-v3` - PWA Kit v3 storefront (template copy or extensible flavor)
+ * - `cartridges` - Any cartridge-based project (detected via .project files)
+ * - `pwa-kit-v3` - PWA Kit v3 storefront
  * - `storefront-next` - Storefront Next/Odyssey project
- * - `sfra` - SFRA/cartridge-based storefront (has cartridges/ directory)
- * - `custom-api` - Custom SCAPI project (has api.json files)
- * - `headless` - Generic headless project (has dw.json but no specific framework)
+ *
+ * ## Toolset Mapping
+ *
+ * - base (fallback): SCAPI
+ * - cartridges: CARTRIDGES + SCAPI
+ * - pwa-kit-v3: PWAV3 + MRT + SCAPI
+ * - storefront-next: STOREFRONTNEXT + MRT + SCAPI
  *
  * ## Custom Patterns
  *
@@ -40,7 +45,7 @@
  *
  * const myPattern: DetectionPattern = {
  *   name: 'my-framework',
- *   projectType: 'custom-api',
+ *   projectType: 'cartridges',
  *   detect: async (path) => {
  *     // Custom detection logic
  *     return false;
@@ -66,11 +71,10 @@ export type {ProjectType, DetectionPattern, DetectionResult, DetectOptions} from
 // Patterns (for customization)
 export {
   DEFAULT_PATTERNS,
+  cartridgesPattern,
   pwaKitV3Pattern,
   storefrontNextPattern,
   sfraPattern,
-  customApiPattern,
-  dwJsonPattern,
 } from './patterns/index.js';
 
 // Utilities (for building custom patterns)

packages/b2c-tooling-sdk/src/discovery/patterns/base.ts

@@ -0,0 +1,30 @@
+/*
+ * 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
+ */
+/**
+ * Cartridge project detection pattern.
+ *
+ * Detects any project containing cartridges by looking for .project files
+ * (Eclipse project markers used in SFCC development).
+ *
+ * @module discovery/patterns/cartridges
+ */
+import type {DetectionPattern} from '../types.js';
+import {findCartridges} from '../../operations/code/cartridges.js';
+
+/**
+ * Detection pattern for cartridge-based projects.
+ *
+ * Uses the SDK's findCartridges function to detect any cartridges in the workspace.
+ * This covers SFRA, custom APIs, and any other cartridge-based development.
+ */
+export const cartridgesPattern: DetectionPattern = {
+  name: 'cartridges',
+  projectType: 'cartridges',
+  detect: async (workspacePath) => {
+    const cartridges = findCartridges(workspacePath);
+    return cartridges.length > 0;
+  },
+};

packages/b2c-tooling-sdk/src/discovery/patterns/cartridges.ts

@@ -6,35 +6,29 @@
 /**
  * Detection patterns for workspace discovery.
  *
+ * Simplified to 3 workspace types:
+ * - cartridges: Any project with cartridges
+ * - pwa-kit-v3: PWA Kit v3 storefront
+ * - storefront-next: Storefront Next (Odyssey)
+ *
  * @module discovery/patterns
  */
 import type {DetectionPattern} from '../types.js';
+import {cartridgesPattern} from './cartridges.js';
 import {pwaKitV3Pattern} from './pwa-kit.js';
 import {storefrontNextPattern} from './storefront-next.js';
-import {sfraPattern} from './sfra.js';
-import {customApiPattern} from './custom-api.js';
-import {dwJsonPattern} from './base.js';
 
 /**
- * Default detection patterns in priority order.
+ * Default detection patterns.
  *
- * Patterns are sorted by priority when detection runs, but this
- * array provides a logical grouping:
- * 1. Framework-specific patterns (PWA Kit v3, Storefront Next, SFRA)
- * 2. Project-type patterns (Custom API)
- * 3. Fallback patterns (dw.json)
+ * All patterns are checked - multiple can match for hybrid projects.
  */
-export const DEFAULT_PATTERNS: DetectionPattern[] = [
-  pwaKitV3Pattern,
-  storefrontNextPattern,
-  sfraPattern,
-  customApiPattern,
-  dwJsonPattern,
-];
+export const DEFAULT_PATTERNS: DetectionPattern[] = [pwaKitV3Pattern, storefrontNextPattern, cartridgesPattern];
 
 // Individual pattern exports for customization
+export {cartridgesPattern} from './cartridges.js';
 export {pwaKitV3Pattern} from './pwa-kit.js';
 export {storefrontNextPattern} from './storefront-next.js';
+
+// Additional patterns (not in DEFAULT_PATTERNS, available for custom use)
 export {sfraPattern} from './sfra.js';
-export {customApiPattern} from './custom-api.js';
-export {dwJsonPattern} from './base.js';