@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/content/guidance/storefront-next/sfnext-scapi-management/SKILL.md

@@ -1,203 +0,0 @@
----
-name: sfnext-scapi-management
-description: Add, remove, and list typed SCAPI clients in a Storefront Next project using `b2c sfnext scapi` commands, and browse API schemas to discover endpoints before writing loaders. Use this skill whenever the user says 'sfnext scapi', 'add an API to my storefront next project', 'what SCAPI clients does my sfnext project have', 'remove an API client', 'list available APIs for sfnext', 'browse schema before writing a loader', or asks how to integrate a specific SCAPI (shopper-baskets, shopper-search, etc.) into their Storefront Next project as a typed client. Also use when they want to check what parameters an endpoint accepts before coding. NOT for making actual SCAPI calls from loaders — see sfnext-data-fetching. NOT for standalone schema browsing outside a Storefront Next project — see b2c-cli:b2c-scapi-schemas.
----
-
-# SCAPI Client Management Skill
-
-This skill covers managing which typed SCAPI clients are available in a Storefront Next project and how to discover their shapes before writing data-fetching code.
-
-## Overview
-
-Storefront Next projects use typed SCAPI clients generated from OpenAPI schemas. Two complementary command sets work together:
-
-| Command Set | Purpose | When to Use |
-|-------------|---------|-------------|
-| `b2c sfnext scapi` | Manage which clients exist in your project | Adding/removing APIs, checking what's configured |
-| `b2c scapi schemas` | Browse API shapes (endpoints, fields, types) | Before writing a loader — discover what's available |
-
-## Managing Project Clients
-
-### List Available APIs
-
-See what SCAPI APIs can be added to your project:
-
-```bash
-# show all APIs available to add
-b2c sfnext scapi available
-
-# filter by API family
-b2c sfnext scapi available --api-family product
-
-# JSON output for scripting
-b2c sfnext scapi available --json
-```
-
-### Add a Client
-
-Add a typed SCAPI client to your project. This generates type-safe client code accessible via `createApiClients(context)`:
-
-```bash
-# add the shopper-products API
-b2c sfnext scapi add product shopper-products v1
-
-# add a custom API
-b2c sfnext scapi add custom my-loyalty-api v1
-
-# force re-add (overwrite existing)
-b2c sfnext scapi add product shopper-products v1 --force
-```
-
-After adding, the client becomes available in your loaders:
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-### List Current Project Clients
-
-See which SCAPI clients are currently configured in your project:
-
-```bash
-# list all configured clients
-b2c sfnext scapi list
-
-# JSON output
-b2c sfnext scapi list --json
-```
-
-### Remove a Client
-
-Remove an unused client to reduce bundle size:
-
-```bash
-# remove a client
-b2c sfnext scapi remove product shopper-products
-```
-
-## Discovering API Shapes
-
-Before writing a loader or action, use `b2c scapi schemas` to explore what endpoints and fields an API offers.
-
-### The Schema-First Workflow
-
-```
-1. b2c scapi schemas list              → Find the API family/name/version
-2. b2c scapi schemas get ... --list-paths   → See available endpoints
-3. b2c scapi schemas get ... --expand-paths → See request params + response shape
-4. Write your loader using the discovered types
-```
-
-### Step 1: Find the API
-
-```bash
-# list all available schemas
-b2c scapi schemas list
-
-# filter to product APIs
-b2c scapi schemas list --api-family product
-```
-
-### Step 2: See Available Endpoints
-
-```bash
-# list all paths in shopper-products
-b2c scapi schemas get product shopper-products v1 --list-paths
-```
-
-Output shows endpoints like `/products/{productId}`, `/products`, etc.
-
-### Step 3: Expand Endpoint Details
-
-```bash
-# see the full shape of a specific endpoint
-b2c scapi schemas get product shopper-products v1 --expand-paths /products/{productId}
-
-# see the response schema type
-b2c scapi schemas get product shopper-products v1 --expand-schemas Product
-
-# combine: endpoint + its response type
-b2c scapi schemas get product shopper-products v1 \
-  --expand-paths /products/{productId} \
-  --expand-schemas Product,ProductResult
-```
-
-### Step 4: Write Your Loader
-
-Now that you know the endpoint path and parameter structure, write your loader:
-
-```typescript
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-## Example: Adding and Using a New API
-
-Complete walkthrough — adding shopper-search and writing a search loader:
-
-```bash
-# 1. Check what's available
-b2c sfnext scapi available --api-family search
-
-# 2. Add the client
-b2c sfnext scapi add search shopper-search v1
-
-# 3. Discover endpoints
-b2c scapi schemas get search shopper-search v1 --list-paths
-
-# 4. Inspect the productSearch endpoint
-b2c scapi schemas get search shopper-search v1 \
-  --expand-paths /product-search \
-  --expand-schemas ProductSearchResult
-```
-
-Then write the loader:
-
-```typescript
-export function loader({ request, context }: LoaderFunctionArgs) {
-    const url = new URL(request.url);
-    const q = url.searchParams.get('q') ?? '';
-    const clients = createApiClients(context);
-
-    return {
-        results: clients.shopperSearch.productSearch({
-            params: { query: { q, limit: 25 } }
-        }).then(({ data }) => data),
-    };
-}
-```
-
-## Common Pitfalls
-
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Writing a loader without checking the schema | Wrong parameter names or missing required fields | Run `--expand-paths` first to see exact param structure |
-| Adding an API but client not appearing | Missing `pnpm install` after add | Run `pnpm install` to regenerate types |
-| Trying to browse custom API schemas before registration | Schema returns empty/404 | Deploy and register the custom API first (see `sfnext-custom-apis`) |
-| Using wrong API version | Types don't match runtime behavior | Use `scapi available` to verify the current version |
-
-## Related Skills
-
-- `storefront-next:sfnext-data-fetching` - Using the clients in loaders, actions, and useScapiFetcher
-- `storefront-next:sfnext-custom-apis` - End-to-end custom API implementation and consumption
-- `b2c-cli:b2c-scapi-schemas` - Full reference for schema browsing commands and flags
-- `storefront-next:sfnext-project-setup` - Project creation and initial structure
-
-## Reference Documentation
-
-- [CLI Commands Reference](references/CLI-COMMANDS.md) - Detailed command reference for `b2c sfnext scapi`

package/content/guidance/storefront-next/sfnext-scapi-management/references/CLI-COMMANDS.md

@@ -1,122 +0,0 @@
-# CLI Commands Reference
-
-Detailed reference for `b2c sfnext scapi` subcommands that manage typed SCAPI clients in a Storefront Next project.
-
-## How It Works
-
-The `b2c sfnext scapi` commands are provided by the `@salesforce/storefront-next-dev` package, which is auto-installed as a JIT (just-in-time) plugin when you first run any `sfnext` command. If you have `@salesforce/storefront-next-dev` in your project's `devDependencies`, the local version is used automatically.
-
-## `b2c sfnext scapi available`
-
-Lists all SCAPI APIs that can be added to your project.
-
-```bash
-b2c sfnext scapi available [--api-family <family>] [--api-name <name>] [--json]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--api-family` | Filter by API family (e.g., `product`, `search`, `checkout`, `customer`, `custom`) |
-| `--api-name` | Filter by API name (e.g., `shopper-products`) |
-| `--json` | Output as JSON |
-
-**Example output:**
-
-```
-API Family    API Name              Version  Status
-product       shopper-products      v1       current
-search        shopper-search        v1       current
-checkout      shopper-baskets-v2    v1       current
-customer      shopper-customers     v1       current
-custom        my-loyalty-api        v1       current
-```
-
-## `b2c sfnext scapi add`
-
-Adds a typed SCAPI client to the project. Generates type definitions and registers the client in the `createApiClients()` factory.
-
-```bash
-b2c sfnext scapi add <apiFamily> <apiName> <version> [--force]
-```
-
-| Argument/Flag | Description |
-|---------------|-------------|
-| `<apiFamily>` | API family (e.g., `product`, `search`, `custom`) |
-| `<apiName>` | API name (e.g., `shopper-products`, `my-loyalty-api`) |
-| `<version>` | API version (e.g., `v1`) |
-| `--force` | Overwrite if client already exists |
-
-**What it does:**
-1. Fetches the OpenAPI schema for the specified API
-2. Generates TypeScript type definitions
-3. Registers the client in the project's API client configuration
-4. The client becomes accessible via `createApiClients(context).<camelCaseName>`
-
-**Client property naming:**
-
-| API Name | Client Property |
-|----------|----------------|
-| `shopper-products` | `clients.shopperProducts` |
-| `shopper-search` | `clients.shopperSearch` |
-| `shopper-baskets-v2` | `clients.shopperBasketsV2` |
-| `my-loyalty-api` | `clients.myLoyaltyApi` |
-
-## `b2c sfnext scapi list`
-
-Lists SCAPI clients currently configured in the project.
-
-```bash
-b2c sfnext scapi list [--json]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--json` | Output as JSON |
-
-Shows all clients that have been added to the project and are available via `createApiClients()`.
-
-## `b2c sfnext scapi remove`
-
-Removes a typed SCAPI client from the project.
-
-```bash
-b2c sfnext scapi remove <apiFamily> <apiName>
-```
-
-| Argument | Description |
-|----------|-------------|
-| `<apiFamily>` | API family of the client to remove |
-| `<apiName>` | API name of the client to remove |
-
-**What it does:**
-1. Removes the generated type definitions
-2. Unregisters the client from the API client configuration
-3. The client property is no longer available on `createApiClients()` output
-
-**When to use:** Remove unused API clients to reduce bundle size and type-checking scope.
-
-## Complementary: `b2c scapi schemas`
-
-While `b2c sfnext scapi` manages which clients exist in your project, use `b2c scapi schemas` to explore what those APIs offer before writing code:
-
-```bash
-# list all schemas
-b2c scapi schemas list [--api-family <family>] [--api-name <name>] [--status <status>]
-
-# get schema with selective expansion
-b2c scapi schemas get <apiFamily> <apiName> <version> [options]
-```
-
-Key flags for `b2c scapi schemas get`:
-
-| Flag | Description |
-|------|-------------|
-| `--list-paths` | List all endpoint paths |
-| `--list-schemas` | List all type/schema names |
-| `--expand-paths <paths>` | Expand specific paths (comma-separated) |
-| `--expand-schemas <schemas>` | Expand specific schemas (comma-separated) |
-| `--expand-all` | Full schema without collapsing |
-| `--yaml` | Output as YAML |
-| `--json` | Output wrapped JSON with metadata |
-
-See `b2c-cli:b2c-scapi-schemas` skill for complete documentation of schema browsing.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-create-component/SKILL.md

@@ -1,195 +0,0 @@
----
-name: sfnext-create-component
-description: Author a new Storefront Next design-system component the right way — pick the correct layer (primitive vs composite), reuse-or-extend before creating, define CVA variants bound to semantic tokens, add data-slot attributes, satisfy the accessibility checklist, and ship a Storybook story. Use when asked to create, add, or build a new UI component, button/badge/tile/card variant, or design-system primitive. This is the design-system authoring discipline; for createPage/Suspense/shadcn page-rendering patterns see sfnext-components.
----
-
-# Create a Component Skill
-
-This skill is the authoring discipline for adding a new component to a Storefront Next storefront: choosing the right layer, reusing before creating, and meeting the token / a11y / Storybook requirements that keep the design system consistent.
-
-> **It complements `sfnext-components`.** That skill covers engineering patterns — `createPage`, Suspense/`Await` streaming, shadcn/ui setup, the `cn()` utility. **This** skill covers design-system authoring — the layer model, the extend-before-create gate, CVA variants bound to semantic tokens, `data-slot`, accessibility, and story coverage. Use both together when building UI.
-
-## Before you start — scan first (extend before create)
-
-Do not create a new component file until you have run this scan:
-
-1. Search `src/components/` for components with a similar name or behaviour.
-2. Search `src/components/ui/` for Shadcn primitives — run `npx shadcn@latest add <name>` to check whether it exists before hand-rolling one.
-3. Apply the REUSE / EXTEND / CREATE decision:
-   - **REUSE** — an existing component already does this → use it as-is.
-   - **EXTEND** — an existing component is close → add a new CVA variant (cheaper than a new file).
-   - **CREATE** — nothing exists → proceed with this skill.
-
-See [Component Authoring Reference](references/COMPONENT-AUTHORING.md) for the full layer model and the extend-before-create rule.
-
-## Step 1 — Decide the layer
-
-| Question | Layer | Location |
-|----------|-------|----------|
-| Pure UI element, no data or business logic? | **Primitive** | `src/components/ui/` (check shadcn first) |
-| Assembles primitives or takes data props? | **Composite** | `src/components/` |
-
-For primitives, always check shadcn before hand-rolling:
-
-```bash
-# from packages/template-retail-rsc-app
-npx shadcn@latest add <component-name>
-```
-
-Shadcn components land in `src/components/ui/` already wired to the token system. If it exists in shadcn, use it — do not hand-roll a replacement.
-
-## Step 2 — Create the file with the copyright header
-
-```
-src/components/<feature>/<component-name>.tsx    ← preferred (feature-grouped)
-src/components/<component-name>.tsx              ← acceptable for standalone components
-```
-
-Start every `.ts`/`.tsx` file with the Apache 2.0 copyright header (ESLint enforces it), then imports:
-
-```tsx
-import * as React from 'react'
-import { cva, type VariantProps } from 'class-variance-authority'
-import { cn } from '@/lib/utils'
-// Import primitives from src/components/ui/ — not from @radix-ui directly
-import { Button } from '@/components/ui/button'
-```
-
-## Step 3 — Type the props explicitly
-
-```tsx
-interface ProductTileProps {
-  productId: string
-  name: string
-  price: number
-  imageUrl: string
-  currency?: string
-  className?: string
-}
-```
-
-No `any`. Extend `React.ComponentProps<'element'>` for native passthrough. Use discriminated unions for mutually exclusive prop shapes.
-
-## Step 4 — Define CVA variants (if the component has visual states)
-
-```tsx
-const productTileVariants = cva(
-  'relative flex flex-col overflow-hidden rounded-md bg-card text-card-foreground',
-  {
-    variants: {
-      density: {
-        comfortable: 'gap-4 p-4',
-        compact: 'gap-2 p-2',
-      },
-    },
-    defaultVariants: { density: 'comfortable' },
-  }
-)
-```
-
-**Token rules:** every class that affects color MUST use a semantic token utility (`bg-primary`, `text-foreground`, `border-border`, …). No raw hex, no `bg-black`, no `text-gray-500`. See [Token System Reference](references/TOKEN-SYSTEM.md).
-
-## Step 5 — Write the component
-
-```tsx
-export function ProductTile({
-  productId,
-  name,
-  price,
-  imageUrl,
-  currency = 'USD',
-  className,
-  density,
-  ...props
-}: ProductTileProps & VariantProps<typeof productTileVariants>) {
-  return (
-    <article
-      data-slot="product-tile"
-      data-product-id={productId}
-      className={cn(productTileVariants({ density }), className)}
-      {...props}
-    >
-      <div data-slot="product-tile-image">{/* image */}</div>
-      <div data-slot="product-tile-body" className="flex flex-col gap-1">
-        <span data-slot="product-tile-name" className="text-sm font-medium text-foreground">
-          {name}
-        </span>
-        <span data-slot="product-tile-price" className="text-sm text-muted-foreground">
-          {new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(price)}
-        </span>
-      </div>
-    </article>
-  )
-}
-```
-
-Required on every component:
-- `data-slot` on the root and each named region.
-- `className` accepted and merged via `cn()` **last** so callers can override.
-- Native props spread via `{...props}`.
-
-## Step 6 — Create the Storybook story
-
-Every new component in `src/components/` needs a `.stories.tsx` — one story per CVA variant plus a `Snapshot` story for CI diffing.
-
-```tsx
-import type { Meta, StoryObj } from '@storybook/react'
-import { ProductTile } from './product-tile'
-
-const meta: Meta<typeof ProductTile> = {
-  title: 'Components/Product/ProductTile',
-  component: ProductTile,
-}
-export default meta
-
-type Story = StoryObj<typeof ProductTile>
-
-const defaultProps = { productId: 'P001', name: 'Classic Shirt', price: 89.99, imageUrl: '/placeholder.jpg' }
-
-export const Default: Story = { args: defaultProps }
-export const Compact: Story = { args: { ...defaultProps, density: 'compact' } }
-
-export const Snapshot: Story = {
-  name: 'Snapshot',
-  render: () => (
-    <div className="grid grid-cols-2 gap-4">
-      <ProductTile {...defaultProps} density="comfortable" />
-      <ProductTile {...defaultProps} density="compact" />
-    </div>
-  ),
-}
-```
-
-## Step 7 — Accessibility check
-
-- [ ] Interactive elements are `<button>` or `<a>`, never `<div onClick>`.
-- [ ] All form inputs have `<Label htmlFor>`.
-- [ ] Focus ring: `focus-visible:ring-ring focus-visible:ring-[3px]`.
-- [ ] No color-only information (pair with icon or text).
-- [ ] `aria-label` on icon-only buttons.
-
-## Verification
-
-Before marking the task complete, run from the monorepo root:
-
-```bash
-pnpm typecheck
-pnpm lint
-pnpm test-storybook:snapshot:agent
-```
-
-All three must pass with zero errors and zero warnings. Lint runs with `--max-warnings 0`.
-
-## Related Skills
-
-- `storefront-next:sfnext-components` - createPage HOC, Suspense/Await, shadcn/ui, Tailwind page-rendering patterns
-- `storefront-next:sfnext-testing` - Vitest unit tests and Storybook interaction/a11y tests
-- `storefront-next:sfnext-create-vertical` - Brand theming via the token layer
-- `storefront-next:sfnext-extensions` - Injecting a component into a page via UITarget
-
-## Reference Documentation
-
-- [Component Authoring Reference](references/COMPONENT-AUTHORING.md) - Layer model, CVA, data-slot, extend-before-create
-- [Token System Reference](references/TOKEN-SYSTEM.md) - Semantic token classes and dark mode rules
-- [Project Structure Reference](references/PROJECT-STRUCTURE.md) - Where components live in the monorepo
-- [Troubleshooting Reference](references/TROUBLESHOOTING.md) - Token, lint, and snapshot pitfalls

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-create-component/evals/trigger-evals.json

@@ -1,12 +0,0 @@
-[
-  {"query": "I need to build a new ProductTile component for our Storefront Next storefront. It should have comfortable and compact density variants and follow the design-system rules — semantic tokens, data-slot attributes, and a Storybook story.", "should_trigger": true},
-  {"query": "Add a new badge component with primary, secondary, and destructive variants using CVA. How do I make sure the variant classes use semantic tokens and not raw colors?", "should_trigger": true},
-  {"query": "I want to create a reusable card component in the design system. Which layer does it belong in, primitive or composite, and what accessibility checks must it pass before I'm done?", "should_trigger": true},
-  {"query": "Before I build a new button, how do I check whether I should reuse an existing one, add a CVA variant, or create a brand-new component?", "should_trigger": true},
-  {"query": "Build a new swatch-group UI element with proper data-slot attributes, a focus ring, and one Storybook story per variant.", "should_trigger": true},
-  {"query": "How do I wire up a route loader that streams product data into my page using Suspense and Await?", "should_trigger": false},
-  {"query": "I need to create a new brand vertical with its own color palette and dark header. Where do the brand tokens live?", "should_trigger": false},
-  {"query": "How do I register a Page Designer component in the component registry and add its meta definition?", "should_trigger": false},
-  {"query": "Set up authentication middleware with the split-cookie SLAS architecture for my storefront.", "should_trigger": false},
-  {"query": "How do I add an extension that injects a promo banner at the header.before.nav target point?", "should_trigger": false}
-]