mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-03 05:41:08 +08:00
Add B2B Commerce Open Code Integration skill
This commit is contained in:
nkurapati
parent
133aafe7a3
commit
3e6485001a
490
skills/commerce-b2b-open-code-integration/SKILL.md
Normal file
490
skills/commerce-b2b-open-code-integration/SKILL.md
Normal file
@ -0,0 +1,490 @@
|
||||
---
|
||||
name: commerce-b2b-open-code-integration
|
||||
description: Integrate Salesforce B2B Commerce open source components from GitHub into B2B Commerce stores. Use when users mention "integrate open code components", "open source B2B commerce", "replace OOTB components", "forcedotcom/b2b-commerce-open-source-components", or want to add/replace commerce components with open source versions. Handles component integration, dependency resolution, and OOTB component replacement.
|
||||
license: Apache-2.0
|
||||
compatibility: Requires Salesforce CLI (sf), Git, B2B Commerce license, and Experience Builder access
|
||||
metadata:
|
||||
author: afv-library
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when you need to:
|
||||
- Integrate all open source B2B Commerce components into a store
|
||||
- Replace all OOTB (out-of-the-box) components with open code equivalents
|
||||
- Replace specific OOTB components with open code versions
|
||||
- Add open source components to a new or existing B2B Commerce store
|
||||
- Copy components with automatic dependency resolution
|
||||
|
||||
## Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables integration of open source B2B Commerce components from the official Salesforce repository (https://github.com/forcedotcom/b2b-commerce-open-source-components) into existing or new B2B Commerce stores.
|
||||
|
||||
**Three main scenarios:**
|
||||
1. **Integrate** - Add all open code components to a store (components become available in Experience Builder)
|
||||
2. **Replace All** - Replace all OOTB components with open code equivalents in site metadata
|
||||
3. **Replace Specific** - Replace individual OOTB components with open code equivalents
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites Flow
|
||||
|
||||
### Store Selection/Creation
|
||||
|
||||
**Step 1: Check for Existing Store or Create New**
|
||||
|
||||
Ask user: "Would you like to work with an existing B2B store or create a new one?"
|
||||
|
||||
**Step 2: If Creating New Store**
|
||||
|
||||
- Prompt agent: "Create a Commerce B2B Store"
|
||||
- Reference existing rules: `rules/commerce/commerce-b2b-store-requirements.md`
|
||||
- Reference existing prompts: `prompts/commerce/create-retrieve-b2b-storefront.md`
|
||||
- Wait for store creation to complete before proceeding
|
||||
|
||||
**Step 3: If Selecting Existing Store**
|
||||
|
||||
- Run: `sf org list metadata --metadata-type DigitalExperienceConfig --json`
|
||||
- Parse response and extract `fullName` values
|
||||
- Display list to user: "Please select a store from the following:"
|
||||
- Capture user selection
|
||||
|
||||
### Site Metadata Verification
|
||||
|
||||
**Step 4: Check Local Site Metadata**
|
||||
|
||||
Check if path exists: `force-app/main/default/digitalExperiences/site/<selected-store-name>`
|
||||
|
||||
**Step 5: If Site Metadata NOT Present**
|
||||
|
||||
Automatically retrieve: `sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name>`
|
||||
|
||||
Use the `fullName` value from Step 3.
|
||||
|
||||
**Step 6: If Site Metadata Already Present**
|
||||
|
||||
- Ask user: "Site metadata already exists locally. Do you want to overwrite with latest from org? (y/n)"
|
||||
- If yes: Run `sf project retrieve start -m DigitalExperienceBundle:site/<selected-store-name>`
|
||||
- If no: Proceed with existing local metadata
|
||||
|
||||
---
|
||||
|
||||
## Core Tasks
|
||||
|
||||
### Task 1: Clone Open Source Repository
|
||||
|
||||
**Purpose:** Clone the B2B Commerce open source components repository
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Check if repo already cloned in tmp folder: `/tmp/b2b-commerce-open-source-components`
|
||||
2. If exists:
|
||||
- Warn user: "Repository already cloned. Cloning again will overwrite any local changes. Continue? (y/n)"
|
||||
- If no: Skip to next task
|
||||
- If yes: Remove existing and proceed
|
||||
3. Clone: `git clone https://github.com/forcedotcom/b2b-commerce-open-source-components /tmp/b2b-commerce-open-source-components`
|
||||
4. Verify clone successful
|
||||
|
||||
### Task 2: Copy All Open Code Resources
|
||||
|
||||
**Purpose:** Copy all components and labels from repo to selected site
|
||||
|
||||
**Source Paths (from cloned repo):**
|
||||
- Components: `force-app/main/default/sfdc_cms__lwc/*`
|
||||
- Labels: `force-app/main/default/sfdc_cms__label/*`
|
||||
|
||||
**Destination Paths (local project):**
|
||||
- Components: `force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__lwc/`
|
||||
- Labels: `force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__label/`
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Check if destination directories already contain files
|
||||
2. If files exist:
|
||||
- Warn user: "Components already exist. This will overwrite existing changes. Continue? (y/n)"
|
||||
- If no: Proceed with copying only new files (skip existing)
|
||||
- If yes: Overwrite all
|
||||
3. Copy all component directories from source to destination
|
||||
4. Copy all label directories from source to destination
|
||||
5. Report: "Copied X components and Y label sets"
|
||||
|
||||
### Task 3: Copy Specific Open Code Component
|
||||
|
||||
**Purpose:** Copy a single component with all its dependencies
|
||||
|
||||
**Inputs:**
|
||||
- Component name (e.g., "cartBadge")
|
||||
|
||||
**Steps:**
|
||||
|
||||
**1. Check if Component Exists**
|
||||
|
||||
Verify source exists: `/tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/<component-name>`
|
||||
|
||||
If not found: Error and list available components
|
||||
|
||||
**2. Check Destination**
|
||||
|
||||
- Check if already exists: `force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__lwc/<component-name>`
|
||||
- If exists: Ask to overwrite
|
||||
- If no: Skip this component
|
||||
|
||||
**3. Identify Dependencies**
|
||||
|
||||
Scan the component files for:
|
||||
|
||||
**a) HTML Dependencies:** `<site-*>` tags
|
||||
```html
|
||||
<!-- Example: <site-cart-badge-ui> -->
|
||||
```
|
||||
Pattern: Extract component name from `<site-{component-name}>`, component-name is kebab case, needs to be converted to camelCase
|
||||
|
||||
**b) JavaScript Dependencies:** `import ... from 'site/*'`
|
||||
```javascript
|
||||
// Example: import { handleAddToCartSuccessWithToast } from 'site/productAddToCartUtils'
|
||||
```
|
||||
Pattern: Extract module name after `site/`
|
||||
|
||||
**c) Label Dependencies:** `@salesforce/label/site.<component-name>.*`
|
||||
```javascript
|
||||
// Example: import maximumCount from '@salesforce/label/site.cartBadge.maximumCount';
|
||||
```
|
||||
Pattern: Extract component name between `site.` and next `.`
|
||||
|
||||
**4. Copy Component and Dependencies**
|
||||
|
||||
- Copy main component directory
|
||||
- For each dependency found:
|
||||
- Copy dependent component from: `sfdc_cms__lwc/<dependency-name>`
|
||||
- Copy dependent labels from: `sfdc_cms__label/<dependency-name>` (if exists)
|
||||
- Recursively resolve dependencies (dependencies may have dependencies)
|
||||
|
||||
**5. Report:**
|
||||
- "Copied component: {component-name}"
|
||||
- "Copied dependencies: {list of dependencies}"
|
||||
|
||||
### Task 4: Extract All OOTB Components from Site Metadata
|
||||
|
||||
**Purpose:** Identify all OOTB components currently used in the site
|
||||
|
||||
**Steps:**
|
||||
|
||||
**1. Scan Theme Layouts**
|
||||
|
||||
- Search in: `force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__themeLayout/*/content.json`
|
||||
- Parse each `content.json` file
|
||||
- Extract values from `"definition"` keys
|
||||
|
||||
**2. Scan Views**
|
||||
|
||||
- Search in: `force-app/main/default/digitalExperiences/site/<selected-store-name>/sfdc_cms__view/*/content.json`
|
||||
- Parse each `content.json` file
|
||||
- Extract values from `"definition"` keys
|
||||
|
||||
**3. Filter OOTB Components**
|
||||
|
||||
Keep only components matching patterns:
|
||||
- `commerce_builder/*`
|
||||
- `commerce_cart/*`
|
||||
- `commerce/*`
|
||||
- `commerce_my_account/*`
|
||||
|
||||
**4. Return List**
|
||||
|
||||
Deduplicated list of OOTB component definitions
|
||||
|
||||
Example: `["commerce_builder:cartBadge", "commerce_builder:cartContents", "commerce/searchInput"]`
|
||||
|
||||
### Task 5: Find Specific OOTB Component in Site Metadata
|
||||
|
||||
**Purpose:** Check if a specific OOTB component is used in the site
|
||||
|
||||
**Inputs:**
|
||||
- OOTB component name (e.g., "commerce_builder:cartBadge")
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Run Task 4 to get all OOTB components
|
||||
2. Check if input component exists in the list
|
||||
3. If found: Return true with locations (which content.json files)
|
||||
4. If not found:
|
||||
- Inform user: "Component {name} not found in site metadata"
|
||||
- Display: "Components currently used in this site:"
|
||||
- List all found components
|
||||
- Ask: "Would you like to replace one of these instead?"
|
||||
|
||||
### Task 6: Replace OOTB Component with Open Code Component
|
||||
|
||||
**Purpose:** Map and replace OOTB component references with open code equivalents
|
||||
|
||||
**Component Naming Pattern:**
|
||||
|
||||
OOTB components follow pattern: `{namespace}:{componentName}`
|
||||
Open code components follow pattern: `site/{domain}{Context}[{Variant}]` in camelCase
|
||||
|
||||
**Mapping Rules:**
|
||||
|
||||
| OOTB Pattern | Open Code Pattern | Notes |
|
||||
|--------------|-------------------|-------|
|
||||
| `commerce_builder/{name}` | `site/{name}` | Builder components |
|
||||
| `commerce_cart/{name}` | `site/cart{Name}Ui` | Cart runtime with Ui suffix |
|
||||
| `commerce/{name}` | `site/{name}Ui` | Runtime components with Ui suffix |
|
||||
| `commerce/error` | `site/commonError` | Shared utilities use "common" domain |
|
||||
| `commerce_builder/formattedCurrency` | `site/commonFormattedCurrency` | Common utilities |
|
||||
| `commerce/formattedCurrency` | `site/commonFormattedCurrencyUi` | Runtime with Ui suffix |
|
||||
| `commerce_my_account/myAccountLayout` | `site/themelayoutMyaccount` | Account layouts |
|
||||
| `commerce/layoutSite` | `site/themelayoutSite` | Layout → themelayout domain |
|
||||
|
||||
**Example Mappings:**
|
||||
|
||||
```
|
||||
commerce_builder:cartContents → site:cartContents
|
||||
commerce_cart:items → site:cartItemsUi
|
||||
commerce_builder:searchInput → site:searchInput
|
||||
commerce:searchInput → site:searchInputUi
|
||||
commerce:error → site:commonError
|
||||
commerce_my_account:myAccountLayout → site:themelayoutMyaccount
|
||||
```
|
||||
|
||||
**Steps:**
|
||||
|
||||
**1. Parse OOTB Component Name**
|
||||
|
||||
Extract namespace, category, and component name
|
||||
|
||||
**2. Apply Mapping Rules**
|
||||
|
||||
- Match against mapping table
|
||||
- Generate open code component name
|
||||
|
||||
**3. Verify Open Code Component Exists**
|
||||
|
||||
- Check in cloned repo: `/tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/`
|
||||
- Look for camelCase directory name (e.g., "cartBadge" for "site:cartBadge")
|
||||
|
||||
**4. If Not Found**
|
||||
|
||||
- List all available open code components from repo
|
||||
- Ask user: "No direct mapping found. Would you like to select from available components?"
|
||||
|
||||
**5. Update Site Metadata**
|
||||
|
||||
- For each `content.json` file where component is found:
|
||||
- Replace `"definition": "commerce_builder:cartBadge"`
|
||||
- With `"definition": "site:cartBadge"`
|
||||
- Preserve all other properties in the JSON
|
||||
|
||||
**6. Track Changes**
|
||||
|
||||
- Log all files modified
|
||||
- Count replacements made
|
||||
|
||||
---
|
||||
|
||||
## Use Case Workflows
|
||||
|
||||
### Use Case 1: Only Integrate Open Code Components
|
||||
|
||||
**User Intent:** "Integrate open code components to my store"
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Execute Prerequisites Flow
|
||||
2. Execute Task 1: Clone Open Source Repository
|
||||
3. Execute Task 2: Copy All Open Code Resources
|
||||
4. Provide next steps:
|
||||
|
||||
```
|
||||
✅ Integration Complete!
|
||||
|
||||
Next Steps:
|
||||
1. Deploy components to your org:
|
||||
sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>
|
||||
|
||||
2. Open Experience Builder:
|
||||
- Navigate to your store in Experience Builder
|
||||
- The new components will appear in the component palette
|
||||
- Drag and drop them into your pages
|
||||
- Configure and test each component
|
||||
|
||||
3. Publish your site when ready
|
||||
```
|
||||
|
||||
### Use Case 2: Replace All OOTB Components
|
||||
|
||||
**User Intent:** "Replace all OOTB components with open code versions"
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Execute Prerequisites Flow
|
||||
2. Execute Task 1: Clone Open Source Repository
|
||||
3. Execute Task 2: Copy All Open Code Resources
|
||||
4. Execute Task 4: Extract All OOTB Components
|
||||
5. For each OOTB component found:
|
||||
- Execute Task 6: Replace OOTB Component
|
||||
- If successful: Log replacement
|
||||
- If mapping not found: Log warning and continue
|
||||
6. Report summary:
|
||||
|
||||
```
|
||||
✅ Replacement Complete!
|
||||
|
||||
Summary:
|
||||
- Total OOTB components found: X
|
||||
- Successfully replaced: Y
|
||||
- Could not map: Z (list them)
|
||||
|
||||
Modified files:
|
||||
- List of all content.json files changed
|
||||
|
||||
Next Steps:
|
||||
1. Review changes:
|
||||
git diff force-app/main/default/digitalExperiences/site/<store-name>
|
||||
|
||||
2. Deploy to org:
|
||||
sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>
|
||||
|
||||
3. Test the store thoroughly in Experience Builder
|
||||
```
|
||||
|
||||
### Use Case 3: Replace Specific Component
|
||||
|
||||
**User Intent:** "Replace cartBadge with open code version"
|
||||
|
||||
**Workflow:**
|
||||
|
||||
1. Execute Prerequisites Flow
|
||||
2. Execute Task 1: Clone Open Source Repository
|
||||
3. Extract component name from user intent (e.g., "cartBadge")
|
||||
4. Determine OOTB format:
|
||||
- If user provides "commerce_builder:cartBadge" → use as-is
|
||||
- If user provides "cartBadge" → try common patterns:
|
||||
- First try: `commerce_builder:cartBadge`
|
||||
- Then try: `commerce_cart:cartBadge`
|
||||
- Then try: `commerce:cartBadge`
|
||||
5. Execute Task 5: Find Specific OOTB Component
|
||||
6. If found:
|
||||
- Execute Task 6: Replace OOTB Component
|
||||
- Determine open code component name from mapping
|
||||
- Execute Task 3: Copy Specific Open Code Component
|
||||
7. Report:
|
||||
|
||||
```
|
||||
✅ Component Replacement Complete!
|
||||
|
||||
Replaced: commerce_builder:cartBadge → site:cartBadge
|
||||
|
||||
Copied components:
|
||||
- cartBadge (main)
|
||||
- cartBadgeUi (dependency)
|
||||
- productAddToCartUtils (dependency)
|
||||
|
||||
Copied labels:
|
||||
- cartBadge labels
|
||||
|
||||
Modified files:
|
||||
- List of content.json files updated
|
||||
|
||||
Next Steps:
|
||||
1. Review changes and deploy:
|
||||
sf project deploy start -d force-app/main/default/digitalExperiences/site/<store-name>
|
||||
|
||||
2. Test the component in Experience Builder
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors and Responses
|
||||
|
||||
**1. Store Not Found**
|
||||
- Message: "Store '{name}' not found in org. Would you like to see available stores?"
|
||||
- Action: List stores again
|
||||
|
||||
**2. Component Not Found in Repo**
|
||||
- Message: "Component '{name}' not found in open source repo."
|
||||
- Action: List available components from repo
|
||||
|
||||
**3. Component Not Used in Site**
|
||||
- Message: "Component '{name}' is not currently used in this site."
|
||||
- Action: Show components that are used
|
||||
|
||||
**4. No OOTB Components Found**
|
||||
- Message: "No OOTB commerce components found in site metadata. The site may already be using open code components."
|
||||
- Action: Offer to integrate all components instead
|
||||
|
||||
**5. Git Clone Failed**
|
||||
- Message: "Failed to clone repository. Check internet connection."
|
||||
- Action: Retry or abort
|
||||
|
||||
**6. File Copy Failed**
|
||||
- Message: "Failed to copy files. Check file permissions."
|
||||
- Action: Show error details and abort
|
||||
|
||||
**7. No Mapping Found**
|
||||
- Message: "No direct mapping found for '{ootb-component}' to open code component."
|
||||
- Action: Show available components and ask user to manually select
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before completing the integration, verify:
|
||||
|
||||
### Store Setup
|
||||
- [ ] Store has been selected or created successfully
|
||||
- [ ] Site metadata has been retrieved to local project
|
||||
- [ ] Site metadata path exists and is accessible
|
||||
|
||||
### Repository
|
||||
- [ ] Open source repository cloned successfully to `/tmp/b2b-commerce-open-source-components`
|
||||
- [ ] Repository contains expected directories: `sfdc_cms__lwc` and `sfdc_cms__label`
|
||||
|
||||
### Component Integration
|
||||
- [ ] Components copied to correct destination path
|
||||
- [ ] Labels copied to correct destination path
|
||||
- [ ] All dependencies identified and copied (if specific component)
|
||||
- [ ] No file permission errors during copy
|
||||
|
||||
### Component Replacement (if applicable)
|
||||
- [ ] All OOTB components identified correctly
|
||||
- [ ] Mapping applied correctly for each component
|
||||
- [ ] `content.json` files updated with new component definitions
|
||||
- [ ] No JSON syntax errors introduced
|
||||
- [ ] Original JSON structure preserved (only `definition` value changed)
|
||||
|
||||
### Deployment Readiness
|
||||
- [ ] All files are in correct directory structure
|
||||
- [ ] No git conflicts or unstaged changes blocking deployment
|
||||
- [ ] Deployment command provided to user
|
||||
- [ ] User informed about testing requirements
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
**❌ DO NOT:**
|
||||
- Copy components without checking for existing files first
|
||||
- Modify component code or labels from the open source repo
|
||||
- Replace components without verifying they exist in site metadata
|
||||
- Skip dependency resolution for specific component copies
|
||||
- Deploy without user confirmation
|
||||
- Continue on error without informing user
|
||||
- Clone repository multiple times unnecessarily
|
||||
- Modify content.json structure beyond the `definition` value
|
||||
- Add components to wrong site directory
|
||||
- Skip verification of open code component existence before replacement
|
||||
|
||||
**✅ DO:**
|
||||
- Always warn before overwriting existing files
|
||||
- Always verify paths and existence before operations
|
||||
- Always inform user of next steps
|
||||
- Always provide clear error messages
|
||||
- Always track and report changes made
|
||||
- Always preserve JSON structure when updating metadata
|
||||
- Always resolve dependencies recursively
|
||||
- Always verify mappings exist before replacement
|
||||
Loading…
Reference in New Issue
Block a user