@W-20591323 workspace type auto-discovery

[yhsieh1]

Summary

This PR introduces Workspace Type Auto-Discovery for the B2C DX MCP server. When neither --toolsets nor --tools flags are provided, the server automatically detects the project type and enables appropriate toolsets.

Key features:

• Three project types: pwa-kit-v3, storefront-next, and cartridges (any project with .project files)
• Base toolset (SCAPI) is always enabled, providing API discovery and custom API scaffolding
• Union toolset selection enables all toolsets matching any detected project type
• --working-directory flag (global flag in SDK BaseCommand) allows explicit project path; Cursor supports ${workspaceFolder} variable expansion; falls back to process.cwd() when not provided on MCP

Changes

New Files (in packages/b2c-tooling-sdk/src/discovery/)

• detector.ts - WorkspaceTypeDetector class and detectWorkspaceType() convenience function

  • Runs all detection patterns against workspace
  • Returns all matched project types
  • Supports custom patterns via DetectOptions

• types.ts - Type definitions:

  • ProjectType - Union type: 'pwa-kit-v3' | 'storefront-next' | 'cartridges'
  • DetectionPattern - Pattern interface with name, projectType, and detect() function
  • DetectionResult - Result with projectTypes[], matchedPatterns[], autoDiscovered
  • DetectOptions - Options for custom patterns

• utils.ts - Utility functions for pattern implementations:

  • readPackageJson() - Parse package.json from directory
  • exists() - Check if file/directory exists
  • glob() - Find files matching pattern
  • globDirs() - Find directories matching pattern

• index.ts - Module exports and documentation

• patterns/index.ts - Default patterns array and re-exports

• patterns/pwa-kit.ts - Detects PWA Kit v3 projects (two flavors: template copy with @salesforce/pwa-kit-* packages, or extensible with @salesforce/retail-react-app / ccExtensibility)

• patterns/storefront-next.ts - Detects @salesforce/storefront-next-* packages in package.json

• patterns/cartridges.ts - Detects any cartridge project by finding .project files using findCartridges() from the SDK

• patterns/sfra.ts - (Not used in DEFAULT_PATTERNS) Detects SFRA-specific patterns like cartridges/ folder with controllers or templates. Available for future use or custom detection scenarios.

Modified Files

• packages/b2c-tooling-sdk/package.json - Added ./discovery export

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

  • Added BASE_TOOLSET constant (SCAPI) - always enabled
  • Added PROJECT_TYPE_TOOLSETS mapping for project-specific toolsets
  • Added getToolsetsForProjectTypes() function for union toolset selection
  • Updated registerToolsets() to use workingDirectory and detect multiple project types
  • Added warning when --working-directory is not provided

• packages/b2c-tooling-sdk/src/cli/base-command.ts:

  • Added --working-directory flag with SFCC_WORKING_DIRECTORY env var support as global flag
  • Available to all CLI commands, not just MCP

• packages/b2c-dx-mcp/src/commands/mcp.ts:

  • Updated documentation for working directory usage

• packages/b2c-dx-mcp/src/utils/types.ts:

  • Added workingDirectory to StartupFlags interface

• packages/b2c-dx-mcp/README.md:

  • Added "Workspace Auto-Discovery" section
  • Documented project types and toolset mappings
  • Added Cursor vs Claude Desktop configuration examples

New Test Files

• packages/b2c-tooling-sdk/test/discovery/detector.test.ts - Tests for WorkspaceTypeDetector
• packages/b2c-tooling-sdk/test/discovery/utils.test.ts - Tests for readPackageJson, exists, glob, globDirs
• packages/b2c-tooling-sdk/test/discovery/patterns/pwa-kit.test.ts - Tests for pwaKitV3Pattern
• packages/b2c-tooling-sdk/test/discovery/patterns/storefront-next.test.ts - Tests for storefrontNextPattern
• packages/b2c-tooling-sdk/test/discovery/patterns/cartridges.test.ts - Tests for cartridgesPattern
• packages/b2c-tooling-sdk/test/discovery/patterns/sfra.test.ts - Tests for sfraPattern (not used in DEFAULT_PATTERNS but available for custom use)

Updated Test Files

• packages/b2c-dx-mcp/test/registry.test.ts - Updated to use workingDirectory property
• packages/b2c-dx-mcp/test/commands/mcp.test.ts - Added test for --working-directory flag

Project Type to Toolset Mapping

Base Toolset (always enabled): SCAPI - provides API discovery and custom API scaffolding

Project Type	Detection	Additional Toolsets
pwa-kit-v3	@salesforce/pwa-kit-* packages, @salesforce/retail-react-app, or ccExtensibility field	PWAV3, MRT
storefront-next	@salesforce/storefront-next-* packages in package.json	STOREFRONTNEXT, MRT
cartridges	Any .project files found (via findCartridges())	CARTRIDGES

Hybrid Projects: When multiple project types are detected (e.g., PWA Kit + cartridges), toolsets from all matched types are combined with the base toolset.

Test Plan

1. Auto-Discovery Basic Tests

1a. PWA Kit project detection (template copy flavor)

Setup: Open a PWA Kit project using template copy (has @salesforce/pwa-kit-react-sdk in package.json)

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--working-directory", "/path/to/pwa-kit-project", "--allow-non-ga-tools"]
    }
  }
}

• PWA Kit detected - Server logs contain Auto-discovered project types: pwa-kit-v3
• Correct toolsets enabled - SCAPI (base), PWAV3, and MRT tools are registered

1a-ext. PWA Kit project detection (extensible flavor)

Setup: Open a PWA Kit extensible project (has @salesforce/retail-react-app in package.json and/or ccExtensibility field)

• PWA Kit detected - Server logs contain Auto-discovered project types: pwa-kit-v3
• Correct toolsets enabled - SCAPI (base), PWAV3, and MRT tools are registered

1b. Storefront Next project detection

Setup: Open a Storefront Next project (has @salesforce/storefront-next-* in package.json)

• Storefront Next detected - Server logs contain Auto-discovered project types: storefront-next
• Correct toolsets enabled - SCAPI (base), STOREFRONTNEXT, and MRT tools are registered

1c. Cartridges project detection

Setup: Open a cartridge project (any project with .project files - SFRA, Custom API, or other cartridge types)

• Cartridges detected - Server logs contain Auto-discovered project types: cartridges
• Correct toolsets enabled - SCAPI (base) and CARTRIDGES tools are registered

1d. Unknown project fallback

Setup: Open a non-B2C project (no B2C markers)

• Base toolset enabled - Server logs contain Auto-discovered project types: none
• SCAPI tools enabled - Only SCAPI (base toolset) tools are registered

---

2. Working Directory Configuration Tests

2a. Cursor with ${workspaceFolder}

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--working-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
    }
  }
}

• Variable expansion works - Opening different projects detects different project types
• No warning logged - Since --working-directory is provided, no warning is logged

2b. Explicit path

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--working-directory", "/path/to/your/project", "--allow-non-ga-tools"]
    }
  }
}

• Explicit path works - Correct project type detected for the specified path

2c. Environment variable

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--allow-non-ga-tools"],
      "env": {
        "SFCC_WORKING_DIRECTORY": "/path/to/your/project"
      }
    }
  }
}

• Env var works - Correct project type detected
• No warning logged - Since SFCC_WORKING_DIRECTORY is set, no warning is logged

2d. No working directory (fallback to cwd)

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--allow-non-ga-tools"]
    }
  }
}

• Falls back to process.cwd() - Detection runs on current working directory
• Warning logged - Server logs warning: "No --working-directory flag or SFCC_WORKING_DIRECTORY env var provided..."

---

3. Toolset Override Tests

3a. Explicit --toolsets disables auto-discovery

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--toolsets", "CARTRIDGES", "--allow-non-ga-tools"]
    }
  }
}

• Auto-discovery skipped - Only CARTRIDGES tools registered, regardless of project type

3b. Explicit --tools disables auto-discovery

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--tools", "scapi_discovery", "--allow-non-ga-tools"]
    }
  }
}

• Auto-discovery skipped - Only specified tool registered

---

4. Claude Desktop Tests

Note: Claude Desktop does not support ${workspaceFolder} variable expansion.

4a. Explicit path required

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--working-directory", "/path/to/your/project", "--allow-non-ga-tools"]
    }
  }
}

• Works with explicit path - Correct project type detected

4b. Variable not expanded

Config:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": ["--working-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
    }
  }
}

• Literal string passed - ${workspaceFolder} is not expanded, detection fails or uses literal path

---

• Tests pass (pnpm test)
• Code is formatted (pnpm run format)

[clavery]

Looks good. I think the pwa/snext ones are robust. Had some comments on the SFRA and general b2c backend.