@salesforce/b2c-dx-mcp 1.10.1 → 2.1.0

package/dist/tools/scapi/scapi-custom-api-generate-scaffold.js

@@ -21,7 +21,8 @@ const CUSTOM_API_SCAFFOLD_ID = 'custom-api';
  * Exported for tests so we can inject getScaffold / resolveScaffoldParameters and cover error branches.
  */
 export async function executeScaffoldCustomApi(args, services, overrides) {
-    const projectRoot = services.resolveWithProjectDirectory(args.projectRoot);
+    const projectDirectory = services.resolveProjectDirectory(args.projectDirectory);
+    const projectRoot = services.resolveWithProjectDirectory(args.cartridgeDirectory ?? args.projectRoot, args.projectDirectory);
     const getScaffold = overrides?.getScaffold ??
         (async (id, opts) => {
             const registry = createScaffoldRegistry();
@@ -34,6 +35,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Scaffold not found: ${CUSTOM_API_SCAFFOLD_ID}. Ensure @salesforce/b2c-tooling-sdk is installed.`,
         };
     }
@@ -44,6 +47,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: 'No cartridges found in project. Custom API scaffold requires an existing cartridge. Create a cartridge first: use `b2c scaffold cartridge --name app_custom`, or manually create a directory with a `.project` file (e.g., cartridges/app_custom/.project).',
         };
     }
@@ -73,6 +78,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Parameter validation failed: ${message}`,
         };
     }
@@ -83,11 +90,13 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Missing required parameter: ${missingRequired[0].name}. For cartridgeName, ensure the cartridge exists in the project (under projectRoot).`,
         };
     }
     const outputDir = resolveOutputDirectory({
-        outputDir: args.outputDir,
+        outputDir: args.outputDirectory ?? args.outputDir,
         scaffold,
         projectRoot,
     });
@@ -108,6 +117,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
                 skipReason: f.skipReason,
             })),
             postInstructions: result.postInstructions,
+            projectDirectory,
+            projectRoot,
         };
     }
     catch (error) {
@@ -117,6 +128,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Scaffold generation failed: ${message}`,
         };
     }
@@ -136,10 +149,11 @@ export function createScaffoldCustomApiTool(loadServices, executeOverrides) {
         name: 'scapi_custom_api_generate_scaffold',
         description: `Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. \
 Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin) default to shopper, \
-apiDescription, projectRoot, outputDir.`,
+apiDescription, cartridgeDirectory, outputDirectory.`,
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         isGA: true,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: {
             apiName: z
                 .string()
@@ -155,14 +169,34 @@ apiDescription, projectRoot, outputDir.`,
                 .optional()
                 .describe('Admin (no siteId) or shopper (siteId, customer-facing). Default: shopper'),
             apiDescription: z.string().optional().describe('Short description of the API.'),
+            cartridgeDirectory: z
+                .string()
+                .nullish()
+                .describe('Optional cartridge discovery root, resolved relative to projectDirectory. Defaults to projectDirectory.'),
             projectRoot: z
                 .string()
                 .nullish()
-                .describe('Project root for cartridge discovery. Default: project directory. Set to override the project directory.'),
-            outputDir: z.string().optional().describe('Output directory override. Default: project root'),
+                .describe('Deprecated alias for cartridgeDirectory. cartridgeDirectory takes precedence.'),
+            outputDirectory: z
+                .string()
+                .optional()
+                .describe('Optional output directory. Relative paths resolve from cartridgeDirectory.'),
+            outputDir: z
+                .string()
+                .optional()
+                .describe('Deprecated alias for outputDirectory. outputDirectory takes precedence.'),
         },
-        async execute(args, { services }) {
-            return executeScaffoldCustomApi(args, services, executeOverrides);
+        async execute(args, context) {
+            const output = await executeScaffoldCustomApi(args, context.services, executeOverrides);
+            context.setResolvedDirectory('cartridgeDirectory', {
+                path: output.projectRoot,
+                source: args.cartridgeDirectory || args.projectRoot ? 'argument' : 'projectDirectory',
+            });
+            context.setResolvedDirectory('outputDirectory', {
+                path: output.outputDir,
+                source: args.outputDirectory || args.outputDir ? 'argument' : 'projectDirectory',
+            });
+            return output;
         },
         formatOutput(output) {
             if (output.error) {

package/dist/tools/scapi/scapi-custom-apis-get-status.js

@@ -94,6 +94,7 @@ CLI: b2c scapi custom status`,
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         isGA: true,
         requiresInstance: false,
+        usesConfigurationContext: true,
         inputSchema: {
             status: z.enum(['active', 'not_registered']).optional().describe('Filter by status. Omit for all.'),
             groupBy: z.enum(['site', 'type']).optional().describe('Group by siteId or type (Admin/Shopper).'),

package/dist/tools/scapi/scapi-schemas-list.js

@@ -199,6 +199,7 @@ export function createScapiSchemasListTool(loadServices) {
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         isGA: true,
         requiresInstance: false, // SCAPI uses OAuth directly, doesn't need B2CInstance (hostname)
+        usesConfigurationContext: true,
         inputSchema: {
             apiFamily: z.string().optional().describe('API family (e.g., "checkout", "product", "custom").'),
             apiName: z.string().optional().describe('API name (e.g., "shopper-baskets", "shopper-products").'),

package/dist/utils/constants.d.ts

@@ -5,22 +5,11 @@ export declare const ALL_TOOLSETS = "ALL";
 /**
  * Available toolsets that can be enabled.
  */
-export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "STOREFRONTNEXT_DEPRECATED"];
-/**
- * Deprecated toolsets. These can only be enabled by explicitly naming them via
- * `--toolsets`; they are never auto-activated by project detection and are NOT
- * included when `--toolsets ALL` is used.
- *
- * `STOREFRONTNEXT_DEPRECATED` holds the legacy `sfnext_*` MCP tools. They are
- * superseded by the `storefront-next` and `storefront-next-figma` agent-skills
- * plugins and are not compatible with the Storefront Next 1.0 GA release. They
- * will be removed in a future release.
- */
-export declare const DEPRECATED_TOOLSETS: readonly ["STOREFRONTNEXT_DEPRECATED"];
+export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
 /**
  * Valid toolset names including the special "ALL" value.
  */
-export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "STOREFRONTNEXT_DEPRECATED"];
+export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
 /**
  * Type representing a valid toolset name.
  */

package/dist/utils/constants.js

@@ -10,26 +10,7 @@ export const ALL_TOOLSETS = 'ALL';
 /**
  * Available toolsets that can be enabled.
  */
-export const TOOLSETS = [
-    'CARTRIDGES',
-    'DIAGNOSTICS',
-    'MRT',
-    'PWAV3',
-    'SCAPI',
-    'STOREFRONTNEXT',
-    'STOREFRONTNEXT_DEPRECATED',
-];
-/**
- * Deprecated toolsets. These can only be enabled by explicitly naming them via
- * `--toolsets`; they are never auto-activated by project detection and are NOT
- * included when `--toolsets ALL` is used.
- *
- * `STOREFRONTNEXT_DEPRECATED` holds the legacy `sfnext_*` MCP tools. They are
- * superseded by the `storefront-next` and `storefront-next-figma` agent-skills
- * plugins and are not compatible with the Storefront Next 1.0 GA release. They
- * will be removed in a future release.
- */
-export const DEPRECATED_TOOLSETS = ['STOREFRONTNEXT_DEPRECATED'];
+export const TOOLSETS = ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'];
 /**
  * Valid toolset names including the special "ALL" value.
  */

package/oclif.manifest.json

@@ -388,7 +388,7 @@
           "type": "boolean"
         },
         "toolsets": {
-          "description": "Toolsets to enable (comma-separated). Options: all, CARTRIDGES, DIAGNOSTICS, MRT, PWAV3, SCAPI, STOREFRONTNEXT, STOREFRONTNEXT_DEPRECATED",
+          "description": "Toolsets to enable (comma-separated). Options: all, CARTRIDGES, DIAGNOSTICS, MRT, PWAV3, SCAPI, STOREFRONTNEXT",
           "env": "SFCC_TOOLSETS",
           "name": "toolsets",
           "hasDynamicHelp": false,
@@ -429,5 +429,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.10.1"
+  "version": "2.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.10.1",
+  "version": "2.1.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,7 +80,7 @@
     "yaml": "2.9.0",
     "postcss": "8.5.15",
     "zod": "3.25.76",
-    "@salesforce/b2c-tooling-sdk": "1.23.0"
+    "@salesforce/b2c-tooling-sdk": "1.24.1"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -126,7 +126,7 @@
     "test": "c8 mocha --forbid-only --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:ci:win": "c8 --check-coverage=false mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
-    "test:agent": "mocha --forbid-only --reporter min --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
+    "test:agent": "pnpm run pretest && mocha --forbid-only --reporter min --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:e2e": "mocha --forbid-only \"test/e2e/**/*.test.ts\"",
     "test:e2e:ci": "mocha --forbid-only --reporter json --reporter-option output=test-results-e2e.json \"test/e2e/**/*.test.ts\"",
     "coverage": "c8 report",

package/content/sfnext/auth.md

@@ -1,62 +0,0 @@
-# Authentication & Session Management
-
-## Architecture
-
-Split-cookie architecture with server/client contexts:
-
-- **Server middleware** (`auth.server.ts`): Manages SLAS tokens, writes cookies
-- **Client middleware** (`auth.client.ts`): Reads cookies, maintains cache
-- **React Context** (`AuthProvider`): Provides auth state to components
-
-## Cookie Design
-
-| Cookie Name | Purpose | User Type | Expiry | HttpOnly |
-|-------------|---------|-----------|--------|----------|
-| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
-| `cc-nx` | Registered refresh token | Registered | 90 days | No |
-| `cc-at` | Access token | Both | 30 min | No |
-| `usid` | User session ID | Both | Matches refresh | No |
-| `customerId` | Customer ID | Registered | Matches refresh | No |
-
-**Key Points**:
-
-- Only ONE refresh token exists (guest OR registered, never both)
-- User type derived from which refresh token exists
-- Cookies auto-namespaced with `siteId`
-- Tokens auto-refresh when expired
-
-## Usage in Loaders/Actions
-
-```typescript
-import { getAuth } from '@/middlewares/auth.server';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-
-    // Access auth properties
-    const accessToken = auth.access_token;
-    const customerId = auth.customer_id;
-    const isGuest = auth.userType === 'guest';
-    const isRegistered = auth.userType === 'registered';
-
-    return { isGuest, customerId };
-}
-```
-
-## Usage in Components
-
-```typescript
-import { useAuth } from '@/providers/auth';
-
-export function MyComponent() {
-    const auth = useAuth();
-
-    if (auth?.userType === 'guest') {
-        return <LoginPrompt />;
-    }
-
-    return <div>Welcome, customer {auth?.customer_id}</div>;
-}
-```
-
-**Reference:** See README-AUTH.md for complete authentication documentation.

package/content/sfnext/components.md

@@ -1,123 +0,0 @@
-# Component Patterns
-
-## Use the `createPage` HOC
-
-The `createPage` higher-order component standardizes page patterns with built-in Suspense and page key handling:
-
-```typescript
-import { use } from 'react';
-import { createPage } from '@/components/create-page';
-
-// Define your view component
-function ProductView({
-    product,
-    category
-}: {
-    product: Promise<Product>;
-    category?: Promise<Category>
-}) {
-    const productData = use(product);
-    const categoryData = category ? use(category) : null;
-
-    return (
-        <div>
-            <h1>{productData.name}</h1>
-            {categoryData && <p>Category: {categoryData.name}</p>}
-        </div>
-    );
-}
-
-// Create page with fallback
-const ProductPage = createPage({
-    component: ProductView,
-    fallback: <ProductSkeleton />
-});
-
-export default ProductPage;
-```
-
-**Benefits:**
-
-- Eliminates repetitive Suspense/Await boilerplate
-- Consistent loading states across pages
-- Built-in page key management for navigation transitions
-- Type-safe with full TypeScript support
-
-## shadcn/ui Components
-
-**RULES**:
-
-- ✅ Add via: `npx shadcn@latest add <component-name>`
-- ❌ DO NOT modify `src/components/ui/` directly
-- ✅ Create custom components elsewhere
-
-## Suspense Boundaries
-
-Use granular Suspense boundaries for better UX:
-
-```typescript
-// ✅ RECOMMENDED - Multiple Suspense boundaries
-export default function ProductPage({ loaderData: { product, reviews } }) {
-    return (
-        <div>
-            <Suspense fallback={<ProductHeaderSkeleton />}>
-                <Await resolve={product}>
-                    {(data) => <ProductHeader product={data} />}
-                </Await>
-            </Suspense>
-
-            <Suspense fallback={<ReviewsSkeleton />}>
-                <Await resolve={reviews}>
-                    {(data) => <ProductReviews reviews={data} />}
-                </Await>
-            </Suspense>
-        </div>
-    );
-}
-
-// ⚠️ OK - Single Suspense boundary (less granular)
-export default createPage({
-    component: ProductView,
-    fallback: <ProductPageSkeleton />
-});
-```
-
-## File Organization
-
-```
-src/components/product-tile/
-├── index.tsx              # Component
-├── index.test.tsx         # Tests
-└── stories/
-    ├── index.stories.tsx  # Storybook stories
-    └── __snapshots__/     # Storybook snapshots (optional)
-        └── product-tile-snapshot.tsx.snap
-
-# Skeleton components are separate components
-src/components/product-skeleton/
-├── index.tsx
-├── index.test.tsx
-└── stories/
-    └── index.stories.tsx
-```
-
-## Styling
-
-**Tailwind CSS 4** is the only styling approach allowed. Use utility classes directly in components.
-
-**Key rules:**
-
-- ✅ Use Tailwind utility classes
-- ✅ Use `cn()` utility for conditional classes
-- ❌ NO inline styles, NO CSS modules, NO separate CSS files
-
-**See `styling` section for:** Tailwind CSS 4, Shadcn/ui components, icons, responsive design, theme configuration, dark mode, best practices
-
-## Best Practices
-
-1. **Extract view components** - Separate data handling from presentation
-2. **Type safety** - Define proper TypeScript interfaces
-3. **Consistent fallbacks** - Reusable skeleton components
-4. **Colocate tests** - Keep tests next to components
-5. **Story coverage** - Create stories for all reusable components
-6. **Tailwind utilities only** - Use Tailwind CSS classes, avoid inline styles or CSS modules

package/content/sfnext/config.md

@@ -1,180 +0,0 @@
-# Configuration Management
-
-## Overview
-
-All configuration is centralized in `config.server.ts` with environment variable overrides via `.env` files. The configuration system provides type-safe access to app settings with automatic parsing and validation.
-
-## Required Variables
-
-Copy `.env.default` to `.env` and set these required Commerce Cloud credentials:
-
-```bash
-PUBLIC__app__commerce__api__clientId=your-client-id
-PUBLIC__app__commerce__api__organizationId=your-org-id
-PUBLIC__app__commerce__api__siteId=your-site-id
-PUBLIC__app__commerce__api__shortCode=your-short-code
-PUBLIC__app__defaultSiteId=your-site-id
-PUBLIC__app__commerce__sites='[{"id":"your-site-id","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'
-```
-
-**Note:** The `commerce.sites` array defines your site configuration including locales, currencies, and supported options. See `.env.default` for a complete example with multiple locales and currencies.
-
-## Adding Configuration
-
-1. **Define type in `src/config/schema.ts`**:
-
-```typescript
-export type Config = {
-  app: {
-    myFeature: {
-      enabled: boolean;
-      maxItems: number;
-    };
-  };
-};
-```
-
-2. **Add defaults in `config.server.ts`**:
-
-```typescript
-export default defineConfig({
-  app: {
-    myFeature: {
-      enabled: false,
-      maxItems: 10,
-    },
-  },
-});
-```
-
-3. **Override via environment variables**:
-
-```bash
-PUBLIC__app__myFeature__enabled=true
-PUBLIC__app__myFeature__maxItems=20
-```
-
-## Usage Patterns
-
-**In React Components**:
-
-```typescript
-import { useConfig } from '@/config';
-
-export function MyComponent() {
-    const config = useConfig();
-
-    if (config.myFeature.enabled) {
-        const maxItems = config.myFeature.maxItems;
-        // Your feature code
-    }
-}
-```
-
-**In Server Loaders/Actions**:
-
-```typescript
-import { getConfig } from '@/config';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const config = getConfig(context);
-
-    if (config.myFeature.enabled) {
-        // Your loader code
-    }
-}
-```
-
-**In Client Loaders**:
-
-```typescript
-import { getConfig } from '@/config';
-
-export function clientLoader() {
-    const config = getConfig(); // No context needed - uses window.__APP_CONFIG__
-    
-    if (config.myFeature.enabled) {
-        // Your loader code
-    }
-}
-```
-
-**Note:** `getConfig()` and `useConfig()` return `AppConfig` which is the `app` section of the full `Config` type. So you access properties directly (e.g., `config.myFeature.enabled`) without the `app` prefix.
-
-## Environment Variable Rules
-
-Use the `PUBLIC__` prefix with double underscores (`__`) to set any config path:
-
-```bash
-# Environment variable         →  Config path (in Config type)  →  Access via getConfig()/useConfig()
-PUBLIC__app__commerce__sites='[...]' → config.app.commerce.sites → config.commerce.sites
-PUBLIC__app__defaultSiteId=RefArchGlobal → config.app.defaultSiteId → config.defaultSiteId
-PUBLIC__app__myFeature__enabled=true → config.app.myFeature.enabled → config.myFeature.enabled
-```
-
-**Multi-site Configuration Example:**
-
-```bash
-PUBLIC__app__commerce__sites='[
-  {
-    "id": "RefArchGlobal",
-    "defaultLocale": "en-US",
-    "defaultCurrency": "USD",
-    "supportedLocales": [
-      {"id": "en-US", "preferredCurrency": "USD"},
-      {"id": "de-DE", "preferredCurrency": "EUR"}
-    ],
-    "supportedCurrencies": ["USD", "EUR"]
-  }
-]'
-```
-
-**Accessing Site Configuration:**
-
-```typescript
-const config = getConfig(context);
-const currentSite = config.commerce.sites[0]; // Get first site
-const locale = currentSite.defaultLocale;      // "en-US"
-const currency = currentSite.defaultCurrency;  // "USD"
-```
-
-Values are automatically parsed (numbers, booleans, JSON arrays/objects).
-
-Rules:
-1. **`PUBLIC__` prefix**: Exposed to browser (client-safe values)
-2. **No prefix**: Server-only (secrets, never exposed)
-3. **`__` separator**: Navigate nested paths (`PUBLIC__app__commerce__sites`)
-4. **Case-insensitive**: All casings work (normalized to match `config.server.ts`)
-5. **Auto-parsing**: Strings, numbers, booleans, JSON arrays/objects
-6. **Validation**: Paths must exist in `config.server.ts` (prevents typos)
-7. **Depth limit**: Maximum 10 levels deep (use JSON values for deeper nesting)
-8. **Path precedence**: More specific paths override less specific ones
-9. **Protected paths**: `app__engagement` cannot be overridden via environment variables
-10. **MRT limits**: Variable names max 512 characters, total PUBLIC__ values max 32KB
-
-**Note:** Site configuration (locales, currencies) is now managed via `PUBLIC__app__commerce__sites` array instead of individual `PUBLIC__app__site__locale` variables. This enables multi-site support.
-
-**Setting nested objects with JSON:**
-
-```bash
-# Instead of multiple variables:
-PUBLIC__app__myFeature__option1=value1
-PUBLIC__app__myFeature__option2=value2
-
-# Use a single JSON value:
-PUBLIC__app__myFeature='{"option1":"value1","option2":"value2","nested":{"enabled":true}}'
-```
-
-## Security
-
-```bash
-# ✅ Safe for client (PUBLIC__ prefix)
-PUBLIC__app__commerce__api__clientId=abc123
-
-# ✅ Server-only (no prefix)
-COMMERCE_API_SLAS_SECRET=your-secret
-```
-
-Read server-only secrets directly from `process.env` - never add to config.
-
-**Reference:** See src/config/README.md for complete configuration documentation.