diff --git a/skills/integrate-b2b-commerce-open-code/SKILL.md b/skills/integrate-b2b-commerce-open-code/SKILL.md deleted file mode 100644 index 5c0a45c..0000000 --- a/skills/integrate-b2b-commerce-open-code/SKILL.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -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 deleted file mode 100644 index ae552e0..0000000 --- a/skills/integrate-b2b-commerce-open-code/docs/component-replacement-workflow.md +++ /dev/null @@ -1,65 +0,0 @@ -# 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 deleted file mode 100644 index 89679a7..0000000 --- a/skills/integrate-b2b-commerce-open-code/docs/dependency-resolution.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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 deleted file mode 100644 index 9114f2e..0000000 --- a/skills/integrate-b2b-commerce-open-code/docs/ootb-to-opencode-mapping.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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 diff --git a/skills/integrating-b2b-commerce-open-code-components/SKILL.md b/skills/integrating-b2b-commerce-open-code-components/SKILL.md new file mode 100644 index 0000000..9b20faa --- /dev/null +++ b/skills/integrating-b2b-commerce-open-code-components/SKILL.md @@ -0,0 +1,150 @@ +--- +name: integrate-b2b-commerce-open-code-components +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", "add open code components", "forcedotcom/b2b-commerce-open-source-components", or want to add open source commerce components to their store. Copies all components and labels so they become available in Experience Builder. +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 +- Add open source components to a new or existing B2B Commerce store +- Make open code components available in Experience Builder + +## Overview + +This skill copies all open source B2B Commerce components from the official Salesforce repository (https://github.com/forcedotcom/b2b-commerce-open-source-components) into a B2B Commerce store's site metadata. After integration, the components appear in the Experience Builder component palette. + +--- + +## Startup Flow + +When this skill is triggered, perform these checks automatically before copying. + +### Check 1: Open Source Repository + +Verify the repo is cloned at `.tmp/b2b-commerce-open-source-components`: + +1. **If directory does not exist:** clone silently — `git clone https://github.com/forcedotcom/b2b-commerce-open-source-components .tmp/b2b-commerce-open-source-components` +2. **If directory exists** and contains `force-app/main/default/sfdc_cms__lwc` and `sfdc_cms__label`, present options: + > "Open source repository is already cloned. How would you like to proceed?" + > 1. **Reuse existing** — Use the already cloned repository + > 2. **Re-clone** — Remove and clone fresh from GitHub +3. **If directory exists but structure is invalid:** remove and re-clone automatically +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: +- **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/` + +--- + +## Integration Task + +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/` + +**Steps:** + +1. Check if destination directories already contain files +2. If files exist, present options: + > "Components already exist in **{store-name}**. How would you like to proceed?" + > 1. **Overwrite all** — Replace all existing components with latest from repo + > 2. **Copy only new** — Skip existing components, copy only ones not yet present +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" + +**Output:** +``` +✅ Integration Complete! + +Copied: X components and Y label sets to + +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 +``` + +--- + +## Example Interaction + +**User:** "Integrate open code components to my store" + +**Agent:** _(Check 1: repo exists)_ +> "Open source repository is already cloned. How would you like to proceed?" +> 1. **Reuse existing** — Use the already cloned repository +> 2. **Re-clone** — Remove and clone fresh from GitHub + +**User:** "1" + +**Agent:** _(Check 2: store metadata)_ +- ✓ Found store metadata for My_B2B_Store1 + +**Agent:** _(Integration Task: files exist)_ +> "Components already exist in **My_B2B_Store1**. How would you like to proceed?" +> 1. **Overwrite all** — Replace all existing components with latest from repo +> 2. **Copy only new** — Skip existing components, copy only ones not yet present + +**User:** "1" + +**Agent:** +- ✓ Copied 45 components and 38 label sets + +``` +✅ Integration Complete! + +Copied: 45 components and 38 label sets to My_B2B_Store1 + +Next Steps: +1. Deploy: sf project deploy start -d force-app/main/default/digitalExperiences/site/My_B2B_Store1 +2. Open Experience Builder and use new components from the palette +3. Publish your site when ready +``` + +--- + +## Error Handling + +| Error | Message | Action | +|-------|---------|--------| +| Store not found | "Store '{name}' not found in org." | List stores again | +| Git clone failed | "Failed to clone repository. Check internet connection." | Retry or abort | +| Invalid repo structure | "Repository structure has changed. Expected sfdc_cms__lwc and sfdc_cms__label." | Warn user, abort | +| File copy failed | "Failed to copy files. Check file permissions." | Show error details | + +--- + +## Verification Checklist + +- [ ] Startup Flow completed: repo cloned, store metadata available +- [ ] Components copied to correct destination path (`sfdc_cms__lwc/`) +- [ ] Labels copied to correct destination path (`sfdc_cms__label/`) +- [ ] No file permission errors during copy +- [ ] Deployment command provided and user informed about testing + +--- + +## Anti-Patterns + +**DO NOT:** copy without checking for existing files first, modify component code or labels from the open source repo, add components to wrong site directory, deploy without user confirmation. + +**DO:** warn before overwriting existing files, verify paths before operations, report count of copied components and labels, inform user of next steps.