From a17ce24147b67ba987294e1c2edbc555bd717273 Mon Sep 17 00:00:00 2001 From: nkurapati Date: Mon, 30 Mar 2026 23:09:46 +0530 Subject: [PATCH] refactor skill --- .../SKILL.md | 474 ------------------ .../integrate-b2b-commerce-open-code/SKILL.md | 271 ++++++++++ .../docs/component-replacement-workflow.md | 65 +++ .../docs/dependency-resolution.md | 63 +++ .../docs/ootb-to-opencode-mapping.md | 48 ++ 5 files changed, 447 insertions(+), 474 deletions(-) delete mode 100644 skills/commerce-b2b-open-code-integration/SKILL.md create mode 100644 skills/integrate-b2b-commerce-open-code/SKILL.md create mode 100644 skills/integrate-b2b-commerce-open-code/docs/component-replacement-workflow.md create mode 100644 skills/integrate-b2b-commerce-open-code/docs/dependency-resolution.md create mode 100644 skills/integrate-b2b-commerce-open-code/docs/ootb-to-opencode-mapping.md diff --git a/skills/commerce-b2b-open-code-integration/SKILL.md b/skills/commerce-b2b-open-code-integration/SKILL.md deleted file mode 100644 index 858122e..0000000 --- a/skills/commerce-b2b-open-code-integration/SKILL.md +++ /dev/null @@ -1,474 +0,0 @@ ---- -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, Experience Builder access, and internet connectivity -allowed-tools: Bash Read Write -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 - -## 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 - -**Step 7: Safety Check** - -Before proceeding with component replacement: -- Ensure all changes are committed to git: `git status` -- If uncommitted changes exist, commit or stash them -- This allows rollback with `git checkout -- ` if needed - ---- - -## 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 -5. Verify repo structure: Check for `force-app/main/default/sfdc_cms__lwc` and `sfdc_cms__label` directories -6. If structure is incorrect: Warn user that repository structure has changed and may require manual intervention - -### 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" - -**Task Sequence:** Prerequisites Flow → Task 1 → Task 2 - -**Output:** -``` -✅ Integration Complete! - -Next Steps: -1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/ -2. Open Experience Builder and use new components from the palette -3. Publish your site when ready -``` - -### Use Case 2: Replace All OOTB Components - -**User Intent:** "Replace all OOTB components with open code versions" - -**Task Sequence:** Prerequisites Flow → Task 1 → Task 2 → Task 4 → For each component: Task 6 - -**Output:** -``` -✅ Replacement Complete! - -Summary: -- Total OOTB components found: X -- Successfully replaced: Y -- Could not map: Z (list them) - -Modified files: [list content.json files] - -Next Steps: -1. Review: git diff force-app/main/default/digitalExperiences/site/ -2. Deploy: 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" - -**Task Sequence:** Prerequisites Flow → Task 1 → Determine OOTB format (try commerce_builder:, commerce_cart:, commerce:) → Task 5 → Task 6 → Task 3 - -**Output:** -``` -✅ Component Replacement Complete! - -Replaced: commerce_builder:cartBadge → site:cartBadge -Copied: cartBadge + dependencies (cartBadgeUi, productAddToCartUtils) -Labels: cartBadge labels -Modified: [list content.json files] - -Next Steps: -1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/ -2. Test the component in Experience Builder -``` - ---- - -## Example Interaction - -**User:** "Replace all OOTB components with open code versions" - -**Agent:** "Would you like to work with an existing B2B store or create a new one?" - -**User:** "Use my existing store" - -**Agent:** Lists stores → User selects "MyB2BStore" - -**Agent:** "Site metadata already exists locally. Do you want to overwrite with latest from org? (y/n)" - -**User:** "n" - -**Agent:** Executes Tasks 1-2-4-6 with progress updates: -- ✓ Cloned repository -- ✓ Copied 45 components and 38 label sets -- ✓ Found 12 OOTB components in site -- ✓ Replaced 10 components successfully -- ⚠ Could not map: commerce_custom:specialComponent, commerce_custom:anotherOne - -**Agent:** Provides completion summary with next steps - ---- - -## 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 -- Deploy without committing or stashing changes first -- 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 diff --git a/skills/integrate-b2b-commerce-open-code/SKILL.md b/skills/integrate-b2b-commerce-open-code/SKILL.md new file mode 100644 index 0000000..5c0a45c --- /dev/null +++ b/skills/integrate-b2b-commerce-open-code/SKILL.md @@ -0,0 +1,271 @@ +--- +name: integrate-b2b-commerce-open-code +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, Experience Builder access, and internet connectivity +allowed-tools: Bash Read Write +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 + +## 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 + +## References + +Before executing any workflow, **MUST** load the relevant reference docs: + +- [ootb-to-opencode-mapping.md](docs/ootb-to-opencode-mapping.md) - OOTB-to-open-code naming rules and mapping table. Load when replacing components (Use Cases 2 & 3). +- [dependency-resolution.md](docs/dependency-resolution.md) - Dependency scanning algorithm (HTML/JS/labels) and recursive resolution. Load when copying specific components (Use Case 3). +- [component-replacement-workflow.md](docs/component-replacement-workflow.md) - How to scan site metadata, find OOTB components, and replace definitions. Load when replacing components (Use Cases 2 & 3). + +--- + +## Startup Flow + +When this skill is triggered, perform these checks automatically before presenting options to the user. + +### Check 1: Open Source Repository + +Verify the repo is cloned at `.tmp/b2b-commerce-open-source-components`: + +1. If directory exists and contains `force-app/main/default/sfdc_cms__lwc` and `sfdc_cms__label`: reuse it +2. If directory does not exist: clone silently — `git clone https://github.com/forcedotcom/b2b-commerce-open-source-components .tmp/b2b-commerce-open-source-components` +3. If directory exists but structure is invalid: remove and re-clone +4. If clone fails: inform user and abort + +### Check 2: Store and Site Metadata + +Verify a store is selected and site metadata is available locally: + +1. Check if `force-app/main/default/digitalExperiences/site/` contains any store directories +2. **If store metadata exists:** use it. If multiple stores found, ask user to select one. +3. **If no store metadata found:** delegate to the **creating-b2b-commerce-store** skill (`skills/creating-b2b-commerce-store/SKILL.md`) to create/select a store and retrieve metadata. + +**Required state** after both checks (used by all subsequent tasks): +- **Store name** — the selected `fullName` value (e.g., `My_B2B_Store1`) +- **Site metadata path** — `force-app/main/default/digitalExperiences/site//` +- **Repo path** — `.tmp/b2b-commerce-open-source-components/` + +### Present Options + +Once all checks pass, present the user with: + +> "Open code repository is ready and store metadata is available for **{store-name}**. What would you like to do?" +> +> 1. **Only Integrate** — Copy all open code components to your store (available in Experience Builder) +> 2. **Replace All** — Replace all OOTB components with open code equivalents +> 3. **Replace Specific** — Replace individual OOTB components with open code versions + +Proceed to the corresponding use case workflow based on user selection. + +--- + +## Core Tasks + +### Task 1: Copy All Open Code Resources + +Copy all components and labels from cloned repo to site directory: + +- **Source:** `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/*` and `sfdc_cms__label/*` +- **Destination:** `force-app/main/default/digitalExperiences/site//sfdc_cms__lwc/` and `sfdc_cms__label/` + +Warn before overwriting existing files. Report count of components and labels copied. + +### Task 2: Copy Specific Component with Dependencies + +Copy a single component and recursively resolve all its dependencies. + +> **MUST** read [dependency-resolution.md](docs/dependency-resolution.md) before executing this task. + +1. Verify component exists in cloned repo +2. Scan for HTML, JavaScript, and label dependencies +3. Copy component + all dependencies + label sets +4. Report full dependency tree + +### Task 3: Extract All OOTB Components from Site Metadata + +Scan `content.json` files in `sfdc_cms__themeLayout/*` and `sfdc_cms__view/*` to find all OOTB component definitions. + +> **MUST** read [component-replacement-workflow.md](docs/component-replacement-workflow.md) before executing this task. + +Filter: keep any `"definition"` value that starts with `commerce` (e.g., `commerce_builder:*`, `commerce_cart:*`, `commerce:*`, `commerce_my_account:*`). Return deduplicated list. + +### Task 4: Find Specific OOTB Component + +Check if a specific OOTB component is used in the site. If not found, display all used components and offer alternatives. + +> **MUST** read [component-replacement-workflow.md](docs/component-replacement-workflow.md) before executing this task. + +### Task 5: Replace OOTB Component with Open Code Equivalent + +Map an OOTB component name to its open code equivalent and update all `content.json` references. + +> **MUST** read [ootb-to-opencode-mapping.md](docs/ootb-to-opencode-mapping.md) before executing this task. + +Verify the open code component exists in the cloned repo before replacing. Only modify the `"definition"` value in JSON files. + +--- + +## Use Case Workflows + +All workflows begin after the Startup Flow completes and the user selects an option. + +### Option 1: Only Integrate + +**Task Sequence:** Task 1 + +**Output:** +``` +✅ Integration Complete! + +Next Steps: +1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/ +2. Open Experience Builder and use new components from the palette +3. Publish your site when ready +``` + +### Option 2: Replace All OOTB Components + +**Task Sequence:** Task 1 → Task 3 → For each component: Task 5 + +> **MUST** load: [ootb-to-opencode-mapping.md](docs/ootb-to-opencode-mapping.md), [component-replacement-workflow.md](docs/component-replacement-workflow.md) + +**Output:** +``` +✅ Replacement Complete! + +Summary: +- Total OOTB components found: X +- Successfully replaced: Y +- Could not map: Z (list them) + +Modified files: [list content.json files] + +Next Steps: +1. Review: git diff force-app/main/default/digitalExperiences/site/ +2. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/ +3. Test the store thoroughly in Experience Builder +``` + +### Option 3: Replace Specific Components + +> **MUST** load: [ootb-to-opencode-mapping.md](docs/ootb-to-opencode-mapping.md), [component-replacement-workflow.md](docs/component-replacement-workflow.md), [dependency-resolution.md](docs/dependency-resolution.md) + +Ask user: "Would you like to enter a component name or select from a list of OOTB components currently in your site?" + +**If user chooses "Enter component name(s)":** +- Accept one or more component names (comma-separated) +- For each component: Run Task 4 to verify it exists in site metadata +- For each verified component: Task 5 → Task 2 + +**If user chooses "Select from list":** +1. Run Task 3 to extract all OOTB components from site metadata +2. Display the list with multi-select (user can pick one or more): + ``` + OOTB components found in your site: + [ ] commerce_builder:cartBadge + [ ] commerce_builder:cartContents + [ ] commerce_builder:searchInput + [ ] commerce:searchInput + [ ] commerce_cart:items + ... + Select the components to replace (comma-separated numbers or 'all'): + ``` +3. For each selected component: Task 5 → Task 2 + +**Output:** +``` +✅ Component Replacement Complete! + +Replaced: +- commerce_builder:cartBadge → site:cartBadge +- commerce_builder:searchInput → site:searchInput + +Copied components + dependencies: +- cartBadge, cartBadgeUi, productAddToCartUtils +- searchInput + +Modified: [list content.json files] + +Next Steps: +1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/ +2. Test the components in Experience Builder +``` + +--- + +## Example Interaction + +**User:** "I want to integrate open code components" + +**Agent:** _(runs Startup Flow silently)_ +- ✓ Open source repo already cloned +- ✓ Found store metadata for My_B2B_Store1 + +**Agent:** +> "Open code repository is ready and store metadata is available for **My_B2B_Store1**. What would you like to do?" +> 1. **Only Integrate** — Copy all open code components to your store +> 2. **Replace All** — Replace all OOTB components with open code equivalents +> 3. **Replace Specific** — Replace individual OOTB components + +**User:** "2" + +**Agent:** Executes Option 2 with progress updates: +- ✓ Copied 45 components and 38 label sets +- ✓ Found 12 OOTB components in site +- ✓ Replaced 10 components successfully +- ⚠ Could not map: commerce_custom:specialComponent, commerce_custom:anotherOne + +**Agent:** Provides completion summary with next steps + +--- + +## Error Handling + +| Error | Message | Action | +|-------|---------|--------| +| Store not found | "Store '{name}' not found in org." | List stores again | +| Component not in repo | "Component '{name}' not found in open source repo." | List available components | +| Component not in site | "Component '{name}' is not currently used in this site." | Show used components | +| No OOTB components | "No OOTB commerce components found. Site may already use open code." | Offer to integrate instead | +| Git clone failed | "Failed to clone repository. Check internet connection." | Retry or abort | +| File copy failed | "Failed to copy files. Check file permissions." | Show error details | +| No mapping found | "No direct mapping found for '{component}'." | Ask user to select manually | + +--- + +## Verification Checklist + +- [ ] Startup Flow completed: repo cloned, store metadata available +- [ ] User selected an option (Integrate / Replace All / Replace Specific) +- [ ] Components and labels copied to correct destination paths +- [ ] Dependencies resolved recursively (if copying specific component) +- [ ] OOTB components identified and mapped correctly (if replacing) +- [ ] `content.json` files updated — only `definition` value changed, JSON structure preserved +- [ ] No JSON syntax errors introduced +- [ ] Deployment command provided and user informed about testing + +--- + +## Anti-Patterns + +**DO NOT:** copy without checking for existing files, modify open source component code, replace without verifying existence in site metadata, skip dependency resolution, deploy without user confirmation, modify `content.json` structure beyond the `definition` value, add components to wrong site directory. + +**DO:** warn before overwriting, verify paths before operations, inform user of next steps, provide clear error messages, track and report all changes, preserve JSON structure, resolve dependencies recursively, verify mappings exist before replacement. diff --git a/skills/integrate-b2b-commerce-open-code/docs/component-replacement-workflow.md b/skills/integrate-b2b-commerce-open-code/docs/component-replacement-workflow.md new file mode 100644 index 0000000..ae552e0 --- /dev/null +++ b/skills/integrate-b2b-commerce-open-code/docs/component-replacement-workflow.md @@ -0,0 +1,65 @@ +# Component Replacement Workflow + +Detailed steps for scanning site metadata, finding OOTB components, and replacing them with open code equivalents. + +## Extracting All OOTB Components from Site Metadata + +### Step 1: Scan Theme Layouts + +- Search in: `force-app/main/default/digitalExperiences/site//sfdc_cms__themeLayout/*/content.json` +- Parse each `content.json` file +- Extract all values from `"definition"` keys + +### Step 2: Scan Views + +- Search in: `force-app/main/default/digitalExperiences/site//sfdc_cms__view/*/content.json` +- Parse each `content.json` file +- Extract all values from `"definition"` keys + +### Step 3: Filter to OOTB Components + +Keep any `"definition"` value that starts with `commerce` (covers `commerce_builder:*`, `commerce_cart:*`, `commerce:*`, `commerce_my_account:*`, and any other commerce namespaces). + +### Step 4: Return Deduplicated List + +Example output: `["commerce_builder:cartBadge", "commerce_builder:cartContents", "commerce/searchInput"]` + +--- + +## Finding a Specific OOTB Component + +1. Run the extraction above to get all OOTB components +2. Check if the target component exists in the list +3. If found: return the list of `content.json` files where it appears +4. If not found: + - Inform user: "Component {name} not found in site metadata" + - Display all components currently used in the site + - Ask: "Would you like to replace one of these instead?" + +--- + +## Replacing an OOTB Component + +### Step 1: Determine Open Code Name + +Apply the mapping rules from [ootb-to-opencode-mapping.md](ootb-to-opencode-mapping.md). + +The OOTB component definition comes from `content.json` — any `"definition"` value starting with `commerce` is an OOTB component. Use the full definition value (e.g., `commerce_builder:cartBadge`) to apply the mapping. + +### Step 2: Verify Open Code Component Exists + +Check in cloned repo: `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/` + +If not found, list all available open code components and ask user to select. + +### Step 3: Update Site Metadata + +For each `content.json` file where the OOTB component is found: +- Replace the `"definition"` value only +- Preserve all other JSON properties and structure + +### Step 4: Track Changes + +- Log every file modified +- Count total replacements made +- Report summary to user diff --git a/skills/integrate-b2b-commerce-open-code/docs/dependency-resolution.md b/skills/integrate-b2b-commerce-open-code/docs/dependency-resolution.md new file mode 100644 index 0000000..89679a7 --- /dev/null +++ b/skills/integrate-b2b-commerce-open-code/docs/dependency-resolution.md @@ -0,0 +1,63 @@ +# Component Dependency Resolution + +Algorithm for identifying and copying all dependencies when integrating a specific open code component. + +## Overview + +Open code components can depend on other components and labels. When copying a single component, all dependencies must be resolved recursively to ensure the component works correctly. + +## Dependency Types + +### 1. HTML Dependencies — `` tags + +Components reference other components via custom element tags in HTML templates. + +```html + + +``` + +**Pattern:** Extract component name from `` where `component-name` is in kebab-case. Convert to camelCase for the directory name. + +**Conversion:** `cart-badge-ui` → `cartBadgeUi` + +### 2. JavaScript Dependencies — `import ... from 'site/*'` + +Components import modules from other site components. + +```javascript +import { handleAddToCartSuccessWithToast } from 'site/productAddToCartUtils'; +``` + +**Pattern:** Extract the module name after `site/`. The module name maps directly to the component directory name. + +### 3. Label Dependencies — `@salesforce/label/site.*` + +Components import custom labels scoped to a component. + +```javascript +import maximumCount from '@salesforce/label/site.cartBadge.maximumCount'; +``` + +**Pattern:** Extract the component name between `site.` and the next `.` — this identifies which label set to copy from `sfdc_cms__label/`. + +## Resolution Algorithm + +1. **Scan** all files in the target component directory (`.html`, `.js`) for the three dependency patterns above +2. **Collect** a deduplicated set of dependent component names and label set names +3. **For each dependency:** + - Copy the component from: `sfdc_cms__lwc//` + - Copy labels from: `sfdc_cms__label//` (if the directory exists) +4. **Recurse** — scan each newly copied dependency for its own dependencies +5. **Track** all visited components to avoid circular dependency loops +6. **Report** the full dependency tree when complete + +## Source and Destination Paths + +**Source (cloned repo):** +- Components: `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc//` +- Labels: `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__label//` + +**Destination (local project):** +- Components: `force-app/main/default/digitalExperiences/site//sfdc_cms__lwc//` +- Labels: `force-app/main/default/digitalExperiences/site//sfdc_cms__label//` diff --git a/skills/integrate-b2b-commerce-open-code/docs/ootb-to-opencode-mapping.md b/skills/integrate-b2b-commerce-open-code/docs/ootb-to-opencode-mapping.md new file mode 100644 index 0000000..9114f2e --- /dev/null +++ b/skills/integrate-b2b-commerce-open-code/docs/ootb-to-opencode-mapping.md @@ -0,0 +1,48 @@ +# OOTB to Open Code Component Mapping + +Rules and examples for mapping out-of-the-box (OOTB) B2B Commerce component definitions to their open code equivalents. + +## Naming Patterns + +- **OOTB:** `{namespace}:{componentName}` (e.g., `commerce_builder:cartBadge`) +- **Open Code:** `site:{domain}{Context}[{Variant}]` in camelCase (e.g., `site:cartBadge`) + +## Mapping Rules + +| OOTB Pattern | Open Code Pattern | Notes | +|--------------|-------------------|-------| +| `commerce_builder/{name}` | `site/{name}` | Builder components map directly | +| `commerce_cart/{name}` | `site/cart{Name}Ui` | Cart runtime components get Ui suffix | +| `commerce/{name}` | `site/{name}Ui` | Runtime components get 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 | + +## Examples + +``` +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 +``` + +## Applying the Mapping + +1. **Parse** the OOTB component name — extract namespace and component name +2. **Match** against the mapping table above (check specific overrides like `commerce/error` before general rules) +3. **Generate** the open code component name +4. **Verify** the open code component exists in the cloned repo at: + `.tmp/b2b-commerce-open-source-components/force-app/main/default/sfdc_cms__lwc/` +5. If no mapping or component found, list available open code components and ask user to select manually + +## Updating Site Metadata + +For each `content.json` file where the OOTB component is found: +- Replace `"definition": "commerce_builder:cartBadge"` with `"definition": "site:cartBadge"` +- Preserve all other JSON properties — only the `definition` value changes +- Log every file modified and count total replacements