diff --git a/skills/commerce-b2b-open-code-integration/SKILL.md b/skills/commerce-b2b-open-code-integration/SKILL.md new file mode 100644 index 0000000..6d657a2 --- /dev/null +++ b/skills/commerce-b2b-open-code-integration/SKILL.md @@ -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/` + +**Step 5: If Site Metadata NOT Present** + +Automatically retrieve: `sf project retrieve start -m DigitalExperienceBundle:site/` + +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/` +- 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//sfdc_cms__lwc/` +- Labels: `force-app/main/default/digitalExperiences/site//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/` + +If not found: Error and list available components + +**2. Check Destination** + +- Check if already exists: `force-app/main/default/digitalExperiences/site//sfdc_cms__lwc/` +- If exists: Ask to overwrite +- If no: Skip this component + +**3. Identify Dependencies** + +Scan the component files for: + +**a) HTML Dependencies:** `` tags +```html + +``` +Pattern: Extract component name from ``, 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..*` +```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/` + - Copy dependent labels from: `sfdc_cms__label/` (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//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//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/ + +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/ + +2. Deploy to org: + sf project deploy start -d force-app/main/default/digitalExperiences/site/ + +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/ + +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