diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 00000000..6815aeb4 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,32 @@ +{ + "name": "b2c-developer-tooling", + "interface": { + "displayName": "B2C Developer Tooling" + }, + "plugins": [ + { + "name": "b2c-cli", + "source": { + "source": "local", + "path": "./skills/b2c-cli" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, + { + "name": "b2c", + "source": { + "source": "local", + "path": "./skills/b2c" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.changeset/agent-plugins-initial.md b/.changeset/agent-plugins-initial.md new file mode 100644 index 00000000..1eb7d03e --- /dev/null +++ b/.changeset/agent-plugins-initial.md @@ -0,0 +1,5 @@ +--- +'@salesforce/b2c-agent-plugins': minor +--- + +Initial release. This package tracks the version of the B2C Commerce agent skills plugins (`b2c-cli` and `b2c`). Its version is stamped into the Claude Code marketplace entries and the Codex plugin manifests at release time, and skills-only changes get a dedicated `b2c-agent-plugins@X.Y.Z` GitHub release tag with updated skills zips attached. Target this package in a changeset when you change skills under `skills/b2c-cli/skills/` or `skills/b2c/skills/`. diff --git a/.changeset/skills-plugin-install-improvements.md b/.changeset/skills-plugin-install-improvements.md new file mode 100644 index 00000000..aec466ff --- /dev/null +++ b/.changeset/skills-plugin-install-improvements.md @@ -0,0 +1,12 @@ +--- +'@salesforce/b2c-cli': patch +'@salesforce/b2c-dx-docs': patch +--- + +Broaden skills-plugin install support and improve the installation docs. + +- Add a Codex plugin marketplace so the three plugins (`b2c-cli`, `b2c`, `b2c-dx-mcp`) can be installed directly from Codex CLI's plugin directory. +- Add a new `b2c-onboarding` skill (in the `b2c` plugin) that walks new developers through CLI verify, `dw.json` setup, sandbox connect, and first cartridge deploy, then hands off to the topic-specific skill for the user's goal. +- Add per-plugin READMEs with install instructions for each supported client. +- Document Copilot CLI + VS Code Copilot install paths and the Codex marketplace install path. +- Remove the `b2c-experimental` plugin from the public marketplace. diff --git a/.changeset/skills-versioning-pipeline.md b/.changeset/skills-versioning-pipeline.md new file mode 100644 index 00000000..9bbc5e9b --- /dev/null +++ b/.changeset/skills-versioning-pipeline.md @@ -0,0 +1,5 @@ +--- +'@salesforce/b2c-tooling-sdk': patch +--- + +Skills installer (`b2c setup skills`) now resolves the latest skills release by querying GitHub for releases that actually carry skills zips, instead of relying on GitHub's opinionated "latest release" endpoint. Falls back to a CDN-backed lookup when the GitHub API is rate-limited. Zip downloads continue to use the GitHub release CDN with no API calls. Resolved versions are cached locally for 1 hour to keep consecutive installs fast. diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fb1c4efa..575188a3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -16,7 +16,8 @@ "license": "Apache-2.0", "source": "./skills/b2c-cli", "category": "productivity", - "strict": false + "strict": false, + "version": "1.0.0" }, { "name": "b2c", @@ -27,18 +28,8 @@ "license": "Apache-2.0", "source": "./skills/b2c", "category": "productivity", - "strict": false - }, - { - "name": "b2c-experimental", - "description": "Experimental B2C Commerce skills including scaffold templates. Not installed by default.", - "author": { - "name": "Salesforce" - }, - "license": "Apache-2.0", - "source": "./skills/b2c-experimental", - "category": "productivity", - "strict": false + "strict": false, + "version": "1.0.0" }, { "name": "b2c-dx-mcp", diff --git a/.github/workflows/changesets.yml b/.github/workflows/changesets.yml index 6b635ec1..72ed634b 100644 --- a/.github/workflows/changesets.yml +++ b/.github/workflows/changesets.yml @@ -37,7 +37,7 @@ jobs: id: changesets uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1.7.0 with: - version: pnpm changeset version + version: pnpm run version title: 'Next Release: changelog and version packages' commit: 'chore: version packages' env: diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ece9d673..1be0e845 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -96,6 +96,13 @@ jobs: HAS_CHANGES=true fi fi + # Also check agent-plugins tag + if [ "$HAS_CHANGES" = "false" ]; then + PLUGINS_VERSION=$(node -p "require('./skills/package.json').version") + if ! git rev-parse "b2c-agent-plugins@${PLUGINS_VERSION}" >/dev/null 2>&1; then + HAS_CHANGES=true + fi + fi if [ "$HAS_CHANGES" = "false" ]; then echo "skip=true" >> $GITHUB_OUTPUT echo "::notice::All package versions match npm — nothing to publish" @@ -184,6 +191,16 @@ jobs: fi echo "@salesforce/b2c-docs: version=${DOCS_VERSION}" + # Check if agent-plugins version changed (private package — uses git tag) + PLUGINS_VERSION=$(node -p "require('./skills/package.json').version") + if git rev-parse "b2c-agent-plugins@${PLUGINS_VERSION}" >/dev/null 2>&1; then + echo "publish_plugins=false" >> $GITHUB_OUTPUT + else + echo "publish_plugins=true" >> $GITHUB_OUTPUT + echo "version_plugins=${PLUGINS_VERSION}" >> $GITHUB_OUTPUT + fi + echo "@salesforce/b2c-agent-plugins: version=${PLUGINS_VERSION}" + - name: Create snapshot versions if: steps.release-type.outputs.type == 'nightly' run: | @@ -357,6 +374,13 @@ jobs: extract_latest docs/CHANGELOG.md echo "" fi + + if [[ "${{ steps.packages.outputs.publish_plugins }}" == "true" && -f skills/CHANGELOG.md ]]; then + echo "## Agent Skills Plugins" + echo "" + extract_latest skills/CHANGELOG.md + echo "" + fi } > /tmp/release-notes.md - name: Create GitHub Release @@ -375,6 +399,8 @@ jobs: RELEASE_TAG="b2c-vs-extension@${{ steps.packages.outputs.version_vsx }}" elif [[ "${{ steps.packages.outputs.publish_docs }}" == "true" ]]; then RELEASE_TAG="docs@${{ steps.packages.outputs.version_docs }}" + elif [[ "${{ steps.packages.outputs.publish_plugins }}" == "true" ]]; then + RELEASE_TAG="b2c-agent-plugins@${{ steps.packages.outputs.version_plugins }}" else echo "No packages published, skipping release" exit 0 @@ -385,7 +411,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Package skills artifacts - if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true' + if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true' && steps.packages.outputs.publish_plugins == 'true' run: | # Create b2c-skills.zip containing skills/b2c/skills/ cd skills/b2c && zip -r ../../b2c-skills.zip skills/ @@ -397,9 +423,9 @@ jobs: ls -la *.zip - name: Upload skills to release - if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true' + if: steps.release-type.outputs.type == 'stable' && steps.changesets.outputs.skip != 'true' && steps.quick-check.outputs.skip != 'true' && steps.packages.outputs.publish_plugins == 'true' run: | - # Determine the release tag (same logic as Create GitHub Release) + # Determine the release tag (same priority as Create GitHub Release) if [[ "${{ steps.packages.outputs.publish_cli }}" == "true" ]]; then RELEASE_TAG="@salesforce/b2c-cli@${{ steps.packages.outputs.version_cli }}" elif [[ "${{ steps.packages.outputs.publish_sdk }}" == "true" ]]; then @@ -410,9 +436,10 @@ jobs: RELEASE_TAG="@salesforce/mrt-utilities@${{ steps.packages.outputs.version_mrt }}" elif [[ "${{ steps.packages.outputs.publish_vsx }}" == "true" ]]; then RELEASE_TAG="b2c-vs-extension@${{ steps.packages.outputs.version_vsx }}" + elif [[ "${{ steps.packages.outputs.publish_docs }}" == "true" ]]; then + RELEASE_TAG="docs@${{ steps.packages.outputs.version_docs }}" else - echo "No package release to upload to" - exit 0 + RELEASE_TAG="b2c-agent-plugins@${{ steps.packages.outputs.version_plugins }}" fi gh release upload "$RELEASE_TAG" b2c-skills.zip b2c-cli-skills.zip diff --git a/README.md b/README.md index 76455df6..1af71ce8 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,43 @@ Salesforce B2C Commerce Command Line Tools. > [!TIP] > **Just looking for the B2C CLI or MCP install instructions?** Visit the documentation site at [https://salesforcecommercecloud.github.io/b2c-developer-tooling/](https://salesforcecommercecloud.github.io/b2c-developer-tooling/) for the latest install guide and CLI reference. +## Agent Skills & Plugins + +Install B2C Commerce agent skills and plugins in your AI-powered editor. Three plugins are available: `b2c-cli` (CLI operations), `b2c` (development patterns), and `b2c-dx-mcp` (MCP server — Claude Code only). + +- **Claude Code**: run these commands in chat: + + ``` + /plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling + /plugin install b2c-cli@b2c-developer-tooling + /plugin install b2c@b2c-developer-tooling + /plugin install b2c-dx-mcp@b2c-developer-tooling + ``` + +- **VS Code (GitHub Copilot)**: Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) → **Chat: Install Plugin From Source** → enter the repo `SalesforceCommerceCloud/b2c-developer-tooling`. + +- **GitHub Copilot CLI**: + + ``` + copilot plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling + copilot plugin install b2c-cli@b2c-developer-tooling + copilot plugin install b2c@b2c-developer-tooling + ``` + +- **Cursor**: add the marketplace from this repo URL in Cursor Settings → Plugins, then install `b2c-cli` / `b2c`. + +- **Codex CLI**: run `/plugins` and add from this repo (GitHub URL). + +- **Gemini CLI**: `gemini extensions install https://github.com/SalesforceCommerceCloud/b2c-developer-tooling` + +- **Any supported IDE (file-copy install via CLI)**: + + ``` + npx @salesforce/b2c-cli setup skills + ``` + +For Windsurf, OpenCode, Agentforce Vibes, manual installs, and the full install matrix, see [docs/guide/agent-skills](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills). + ## Packages This is a pnpm monorepo with the following packages: diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index fcc09f3a..e60ef911 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -218,7 +218,7 @@ export default defineConfig({ }, themeConfig: { - logo: '/logo.svg', + logo: '/logo-mark.svg', outline: { level: [2, 3], }, @@ -232,6 +232,7 @@ export default defineConfig({ }, nav: [ {text: 'Guides', link: '/guide/'}, + {text: 'Skills', link: '/guide/agent-skills'}, {text: 'MCP', link: '/mcp/'}, {text: 'Reference', link: '/cli/'}, {text: 'SDK', link: '/api/'}, diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index facb2e8b..69bca1d3 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -18,11 +18,11 @@ /* Hero image sizing */ .VPHero .container { - max-width: 100% !important; + max-width: calc(var(--vp-layout-max-width) - 100px); } .VPHero .image-container { - max-width: 550px !important; + max-width: 600px !important; padding: 24px; margin-bottom: 20px; } @@ -30,6 +30,9 @@ @media (min-width: 960px) { .VPHero .image-container { margin-bottom: 0; + transform: none; + max-width: 100% !important; + margin-left: 60px; } } @@ -38,7 +41,21 @@ } .VPHero .image-container img { - max-width: 550px !important; - max-height: 470px; + max-width: 600px !important; + max-height: 500px; object-fit: contain; } + +/* Home features icon treatment */ +.VPFeature .box .icon { + background-color: var(--vp-c-brand-soft); + width: 56px; + height: 56px; + font-size: 28px; + border-radius: 12px; +} + +.VPFeature .box .icon img { + width: 32px; + height: 32px; +} diff --git a/docs/guide/agent-skills.md b/docs/guide/agent-skills.md index 4db42ffa..62b57e99 100644 --- a/docs/guide/agent-skills.md +++ b/docs/guide/agent-skills.md @@ -4,23 +4,14 @@ description: AI agent skills and plugins for Salesforce B2C Commerce — teach A # Agent Skills & Plugins -Turn your coding agent into a B2C Commerce specialist. Skills give Claude Code, Cursor, Agentforce Vibes, Copilot, and Codex deep platform expertise across the full stack — **SCAPI Custom APIs, SLAS authentication, SFRA controllers and forms, ISML, Page Designer, hooks, custom objects, custom job steps, web services** — and operational workflows like **deploying cartridges, running jobs, debugging 404s and logs, managing On-Demand Sandboxes, MRT/PWA Kit, eCDN, site archives, and IMPEX metadata XML**. +Turn your coding agent into a B2C Commerce specialist. Skills cover the full platform — storefront and headless development, operational workflows, and everything in between — so your agent knows both how B2C Commerce works and which CLI commands to run. -Skills follow the open [Agent Skills](https://agentskills.io/home) standard and work with [Agentforce Vibes](#installation-with-agentforce-vibes), [Claude Code](https://claude.ai/code), Cursor, GitHub Copilot, VS Code, Codex, OpenCode, and others. Skills teach your agent how B2C Commerce works and which B2C CLI commands to run and when — the CLI does the actual work against your instance. - -Install from your IDE's plugin system (Claude Code below), the B2C CLI (`b2c setup skills`), or by dropping skills into your IDE's skills directory manually. +Skills follow the open [Agent Skills](https://agentskills.io/home) standard and work with Agentforce Vibes, Claude Code, Cursor, GitHub Copilot (VS Code and CLI), Codex, OpenCode, and others. Install from your IDE's plugin marketplace or the B2C CLI (`b2c setup skills`). ## Quick Start -Install via your IDE's plugin marketplace where supported — otherwise use the B2C CLI installer: - ::: code-group -```bash [Agentforce Vibes] -# Marketplace install coming soon. For now, use the B2C CLI: -npx @salesforce/b2c-cli setup skills --ide agentforce-vibes -``` - ```bash [Claude Code] claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling # Use --scope user to install globally (available in all projects) @@ -42,8 +33,14 @@ copilot plugin install b2c@b2c-developer-tooling ``` ```bash [Codex] +codex plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +# Then in Codex, run /plugins, select the "B2C Developer Tooling" +# marketplace, and select and install the desired plugins. +``` + +```bash [Agentforce Vibes] # Marketplace install coming soon. For now, use the B2C CLI: -npx @salesforce/b2c-cli setup skills --ide codex +npx @salesforce/b2c-cli setup skills --ide agentforce-vibes ``` ```bash [B2C CLI] @@ -52,39 +49,33 @@ npx @salesforce/b2c-cli setup skills ::: -For additional IDEs (Agentforce Vibes, Cursor, Windsurf, OpenCode) and full B2C CLI options see [Installation with B2C CLI](#installation-with-b2c-cli), [Installation with Agentforce Vibes](#installation-with-agentforce-vibes), or [Installation with Other IDEs](#installation-with-other-ides). - ## Available Plugins - - + - - - - +
PluginTypeDescription
PluginDescription
b2c-cliSkills B2C CLI commands and operations — code deployment, job execution, site archives, WebDAV, On-Demand Sandbox management
b2cSkills B2C Commerce development patterns — controllers, ISML, forms, localization, logging, metadata, web services, custom job steps, Page Designer, Business Manager extensions, Custom APIs
b2c-dx-mcpMCPMCP server for AI-assisted B2C Commerce development with project-aware tooling. See MCP InstallationAutomatic project type detection and B2C Commerce workflows for your AI assistant. See MCP Installation
-## Install Claude Plugin +## Claude Code Add the marketplace: @@ -120,7 +111,28 @@ claude plugin uninstall b2c-cli@b2c-developer-tooling claude plugin marketplace remove b2c-developer-tooling ``` -## Installation with B2C CLI +## Codex + +Add the marketplace: + +```bash +codex plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +``` + +Then in Codex run `/plugins`, select the **B2C Developer Tooling** marketplace, and select and install the desired plugins. + +Codex does not yet support installing plugins from the command line — installs happen from the interactive `/plugins` picker. You can also point Codex at a local marketplace directory by running `codex plugin marketplace add `. + +Upgrade or remove the marketplace later with: + +```bash +codex plugin marketplace upgrade b2c-developer-tooling +codex plugin marketplace remove b2c-developer-tooling +``` + +> **Note:** The `b2c-dx-mcp` plugin is available only for Claude Code. For other clients, install the MCP server directly — see [MCP Installation](/mcp/installation). + +## B2C CLI Interactive — select skillsets and IDEs: @@ -172,7 +184,7 @@ b2c setup skills b2c-cli --ide cursor --global --force See [Setup Commands](/cli/setup) for full documentation. -## Installation with Agentforce Vibes +## Agentforce Vibes See [Skills in Agentforce Vibes](https://developer.salesforce.com/docs/platform/einstein-for-devs/guide/skills.html) for platform details. @@ -182,28 +194,19 @@ b2c setup skills b2c-cli --ide agentforce-vibes b2c setup skills b2c --ide agentforce-vibes --global ``` -Manual install directories: - -| Location | Scope | -|----------|-------| -| `.a4drules/skills/` | Project | -| `~/Library/Application Support/Code/User/globalStorage` | Global (macOS) | -| `~/.config/Code/User/globalStorage` | Global (Linux) | -| `%APPDATA%\Code\User\globalStorage` | Global (Windows) | - -## Installation with Other IDEs +## Other IDEs ::: tip Use [`b2c setup skills`](/cli/setup) for any supported IDE. ::: -| IDE | Flag | Project | User | -|-----|------|---------|------| -| [Cursor](https://cursor.com/docs/context/skills) | `--ide cursor` | `.cursor/skills/` | `~/.cursor/skills/` | -| [Windsurf](https://docs.windsurf.com/) | `--ide windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | -| [VS Code / Copilot](https://code.visualstudio.com/docs/copilot/customization/agent-skills) | `--ide vscode` | `.github/skills/` | `~/.copilot/skills/` | -| [Codex CLI](https://github.com/openai/codex) | `--ide codex` | `.codex/skills/` | `~/.codex/skills/` | -| [OpenCode](https://opencode.ai/) | `--ide opencode` | `.opencode/skills/` | `~/.config/opencode/skills/` | +| IDE | Flag | +|-----|------| +| [Cursor](https://cursor.com/docs/context/skills) | `--ide cursor` | +| [Windsurf](https://docs.windsurf.com/) | `--ide windsurf` | +| [VS Code / Copilot](https://code.visualstudio.com/docs/copilot/customization/agent-skills) | `--ide vscode` | +| [Codex CLI](https://github.com/openai/codex) | `--ide codex` | +| [OpenCode](https://opencode.ai/) | `--ide opencode` | ### Manual Installation @@ -214,14 +217,16 @@ b2c setup skills b2c --ide manual b2c setup skills b2c --ide manual --directory ./my-skills ``` -Or download skill zips from the [latest release](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/releases/latest): +For reference, the install locations each `--ide` flag writes to: -```bash -curl -LO https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/releases/latest/download/b2c-cli-skills.zip -curl -LO https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/releases/latest/download/b2c-skills.zip -unzip b2c-cli-skills.zip -d /path/to/your/ide/skills/ -unzip b2c-skills.zip -d /path/to/your/ide/skills/ -``` +| IDE | Project | User | +|-----|---------|------| +| Cursor | `.cursor/skills/` | `~/.cursor/skills/` | +| Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` | +| VS Code / Copilot | `.github/skills/` | `~/.copilot/skills/` | +| Codex CLI | `.codex/skills/` | `~/.codex/skills/` | +| OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` | +| Agentforce Vibes | `.a4drules/skills/` | IDE's global storage | ## Usage Examples diff --git a/docs/index.md b/docs/index.md index ceb0555e..efc85958 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -description: Developer tools for Salesforce B2C Commerce — CLI, MCP Server, Agent Skills, and SDK. Build and operate B2C Commerce from the terminal or with AI coding agents. +description: Developer tools for Salesforce B2C Commerce — the full power of the platform as a CLI, Agent Skills, MCP Server, SDK, and IDE extensions. layout: b2c-home isHome: true @@ -25,17 +25,26 @@ hero: link: /cli/ features: - - icon: "\u26A1" + - icon: + src: /icons/cli.svg + width: 48 + height: 48 title: CLI for Every Workflow details: Deploy cartridges, run jobs, manage ODS and MRT, import/export site archives, work with WebDAV, and automate CI/CD — all from the terminal. The foundation everything else builds on. - link: /cli/ - linkText: CLI reference - - icon: "\U0001F9E0" + link: /guide/ + linkText: Get started + - icon: + src: /icons/skills.svg + width: 48 + height: 48 title: Coding Skills for Your AI Agent details: 30+ preconfigured skills teach Claude Code, Cursor, Agentforce Vibes, Copilot, and Codex how B2C Commerce works — SCAPI, SLAS, SFRA, ISML, Page Designer, hooks, custom objects — and which CLI commands to run when. link: /guide/agent-skills linkText: Install skills - - icon: "\U0001F916" + - icon: + src: /icons/mcp.svg + width: 48 + height: 48 title: MCP Server details: A focused set of MCP tools that complement the CLI for agent-driven workflows. Pairs naturally with skills. link: /mcp/ @@ -62,15 +71,10 @@ brew install SalesforceCommerceCloud/tools/b2c-cli ## Install Agent Skills -Detailed setup: [Agentforce Vibes](/guide/agent-skills#installation-with-agentforce-vibes) · [Claude Code](/guide/agent-skills#install-claude-plugin) · [Copilot](/guide/agent-skills#installation-with-other-ides) · [Codex](/guide/agent-skills#installation-with-other-ides) · [All IDEs](/guide/agent-skills) +Detailed setup: [Claude Code](/guide/agent-skills#claude-code) · [Codex](/guide/agent-skills#codex) · [Copilot](/guide/agent-skills#other-ides) · [Agentforce Vibes](/guide/agent-skills#agentforce-vibes) · [All IDEs](/guide/agent-skills) ::: code-group -```bash [Agentforce Vibes] -# Marketplace install coming soon. For now, use the B2C CLI: -npx @salesforce/b2c-cli setup skills --ide agentforce-vibes -``` - ```bash [Claude Code] claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling # Use --scope user to install globally (available in all projects) @@ -92,10 +96,17 @@ copilot plugin install b2c@b2c-developer-tooling ``` ```bash [Codex] +codex plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +# Then in Codex, run /plugins, select the "B2C Developer Tooling" +# marketplace, and select and install the desired plugins. +``` + +```bash [Agentforce Vibes] # Marketplace install coming soon. For now, use the B2C CLI: -npx @salesforce/b2c-cli setup skills --ide codex +npx @salesforce/b2c-cli setup skills --ide agentforce-vibes ``` + ```bash [B2C CLI] npx @salesforce/b2c-cli setup skills ``` diff --git a/docs/public/icons/cli.svg b/docs/public/icons/cli.svg new file mode 100644 index 00000000..5595a5c1 --- /dev/null +++ b/docs/public/icons/cli.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/docs/public/icons/mcp.svg b/docs/public/icons/mcp.svg new file mode 100644 index 00000000..fa1200fb --- /dev/null +++ b/docs/public/icons/mcp.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/public/icons/skills.svg b/docs/public/icons/skills.svg new file mode 100644 index 00000000..0e0433c2 --- /dev/null +++ b/docs/public/icons/skills.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/docs/public/logo-mark.svg b/docs/public/logo-mark.svg new file mode 100644 index 00000000..ef9c6230 --- /dev/null +++ b/docs/public/logo-mark.svg @@ -0,0 +1,4 @@ + + + + diff --git a/package.json b/package.json index b00ee781..a1921f07 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "skills:eval": "uv run skills/eval/run_eval.py --model us.anthropic.claude-sonnet-4-6 --verbose", "skills:eval:optimize": "uv run skills/eval/run_loop.py --model us.anthropic.claude-sonnet-4-6 --verbose", "changeset": "changeset", - "version": "changeset version", + "version": "changeset version && node scripts/sync-plugin-versions.mjs", "release": "echo 'Releases are handled by CI (publish.yml). Use workflow_dispatch for manual releases.' && exit 1" }, "keywords": [], diff --git a/packages/b2c-tooling-sdk/src/skills/github.ts b/packages/b2c-tooling-sdk/src/skills/github.ts index b8f2ae8a..33880018 100644 --- a/packages/b2c-tooling-sdk/src/skills/github.ts +++ b/packages/b2c-tooling-sdk/src/skills/github.ts @@ -14,6 +14,8 @@ import {getLogger} from '../logging/logger.js'; const GITHUB_REPO = 'SalesforceCommerceCloud/b2c-developer-tooling'; const GITHUB_API_BASE = 'https://api.github.com'; const GITHUB_DOWNLOAD_BASE = 'https://github.com'; +const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com'; +const LATEST_VERSION_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour /** * Asset filename patterns for skill archives. @@ -24,19 +26,125 @@ const ASSET_NAMES: Record = { }; /** - * Build direct download URL for a release asset. - * These URLs don't require API calls and avoid rate limiting. + * Build a direct CDN download URL for a release asset. + * Assumes a concrete tag — call `resolveLatestVersion()` first if you have 'latest'. + */ +function buildDownloadUrl(tag: string, assetName: string): string { + return `${GITHUB_DOWNLOAD_BASE}/${GITHUB_REPO}/releases/download/${tag}/${assetName}`; +} + +/** + * Tag name used for skill-only releases (matches publish.yml). + */ +function pluginsTag(version: string): string { + const bare = version.replace(/^v/, ''); + return `b2c-agent-plugins@${bare}`; +} + +/** + * File path for the resolved-latest-version cache. + */ +function getLatestVersionCachePath(): string { + return path.join(getCacheDir(), '.latest-version.json'); +} + +/** + * Read a cached "latest" version if still fresh (1-hour TTL). + */ +function readLatestVersionCache(): string | null { + try { + const p = getLatestVersionCachePath(); + if (!fs.existsSync(p)) return null; + const entry = JSON.parse(fs.readFileSync(p, 'utf-8')) as {version: string; resolvedAt: string}; + const age = Date.now() - new Date(entry.resolvedAt).getTime(); + if (age > LATEST_VERSION_CACHE_TTL_MS) return null; + return entry.version; + } catch { + return null; + } +} + +function writeLatestVersionCache(version: string): void { + try { + const p = getLatestVersionCachePath(); + fs.mkdirSync(path.dirname(p), {recursive: true}); + fs.writeFileSync(p, JSON.stringify({version, resolvedAt: new Date().toISOString()})); + } catch { + // Caching is best-effort + } +} + +/** + * Detect whether a fetch response is an unauthenticated GitHub rate-limit. + */ +function isRateLimited(response: Response): boolean { + if (response.status !== 403 && response.status !== 429) return false; + const remaining = response.headers.get('x-ratelimit-remaining'); + return remaining === '0' || response.status === 429; +} + +/** + * Resolve the version of the most recent skills release. * - * @param version - 'latest' or specific version tag - * @param assetName - Name of the asset file - * @returns Direct download URL + * Strategy: + * 1. API primary — paginate /releases and return the first entry that has + * a skills asset attached. + * 2. Rate-limit fallback — fetch skills/package.json from main via + * raw.githubusercontent.com. This is the version that will be tagged + * b2c-agent-plugins@ at release time. + * + * Caches the resolved version for 1 hour to avoid re-resolving on consecutive + * calls within the same session. Always returns a bare version string like + * "1.2.3" (no 'v' prefix, no tag format). */ -function getDirectDownloadUrl(version: string, assetName: string): string { - if (version === 'latest') { - return `${GITHUB_DOWNLOAD_BASE}/${GITHUB_REPO}/releases/latest/download/${assetName}`; +async function resolveLatestVersion(): Promise { + const logger = getLogger(); + + const cached = readLatestVersionCache(); + if (cached) { + logger.debug({version: cached}, 'Using cached latest version'); + return cached; } - const tag = version.startsWith('v') ? version : `v${version}`; - return `${GITHUB_DOWNLOAD_BASE}/${GITHUB_REPO}/releases/download/${tag}/${assetName}`; + + // Primary — GitHub REST API with asset filtering + try { + const releases = await listReleases(30); + if (releases.length > 0) { + const version = releases[0].version; + writeLatestVersionCache(version); + return version; + } + logger.warn('GitHub API returned no releases with skills artifacts; falling back to main branch'); + } catch (err) { + const isRateLimit = err instanceof Error && /rate.?limit|403|429/i.test(err.message); + if (isRateLimit) { + logger.warn( + {err: (err as Error).message}, + 'GitHub API rate-limited; falling back to main branch for version resolution', + ); + } else { + logger.warn( + {err: (err as Error).message}, + 'GitHub API unavailable; falling back to main branch for version resolution', + ); + } + } + + // Fallback — read skills/package.json from main via raw.githubusercontent.com + const rawUrl = `${GITHUB_RAW_BASE}/${GITHUB_REPO}/main/skills/package.json`; + logger.debug({url: rawUrl}, 'Fetching version from raw.githubusercontent.com'); + const response = await fetch(rawUrl, {headers: {'User-Agent': 'b2c-cli'}}); + if (!response.ok) { + throw new Error( + `Unable to resolve latest skills version: raw fetch failed with ${response.status} ${response.statusText}`, + ); + } + const data = (await response.json()) as {version?: string}; + if (!data.version) { + throw new Error('Unable to resolve latest skills version: skills/package.json has no version field'); + } + writeLatestVersionCache(data.version); + return data.version; } /** @@ -80,11 +188,22 @@ function parseRelease(release: { */ export async function getRelease(version: string = 'latest'): Promise { const logger = getLogger(); - const endpoint = - version === 'latest' - ? `${GITHUB_API_BASE}/repos/${GITHUB_REPO}/releases/latest` - : `${GITHUB_API_BASE}/repos/${GITHUB_REPO}/releases/tags/${version.startsWith('v') ? version : `v${version}`}`; + // For 'latest', resolve to a concrete tag via the skills-aware resolver. + // This avoids GitHub's /releases/latest endpoint, which returns whichever + // release GitHub flags as latest regardless of whether it contains skills. + let tag: string; + if (version === 'latest') { + const resolved = await resolveLatestVersion(); + tag = pluginsTag(resolved); + } else if (/^b2c-agent-plugins@/.test(version) || version.includes('@')) { + // Caller passed an explicit tag (including other packages' tags, for tests/internal use). + tag = version; + } else { + tag = pluginsTag(version); + } + + const endpoint = `${GITHUB_API_BASE}/repos/${GITHUB_REPO}/releases/tags/${encodeURIComponent(tag)}`; logger.debug({endpoint}, 'Fetching release info'); const response = await fetch(endpoint, { @@ -96,7 +215,10 @@ export async function getRelease(version: string = 'latest'): Promise + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/skills/b2c/.codex-plugin/plugin.json b/skills/b2c/.codex-plugin/plugin.json new file mode 100644 index 00000000..f2793a25 --- /dev/null +++ b/skills/b2c/.codex-plugin/plugin.json @@ -0,0 +1,40 @@ +{ + "name": "b2c", + "version": "1.0.0", + "description": "B2C Commerce development skills including Custom API development guides.", + "author": { + "name": "Salesforce" + }, + "homepage": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/", + "repository": "https://github.com/SalesforceCommerceCloud/b2c-developer-tooling", + "license": "Apache-2.0", + "keywords": [ + "salesforce", + "b2c-commerce", + "commerce-cloud", + "sfra", + "scapi", + "ocapi" + ], + "skills": "./skills/", + "interface": { + "displayName": "B2C Commerce Dev", + "shortDescription": "B2C Commerce development patterns and API guidance.", + "longDescription": "Skills for Salesforce B2C Commerce development — controllers, ISML templates, hooks, forms, Custom APIs, services, Page Designer, and Business Manager extensions.", + "developerName": "Salesforce", + "category": "Productivity", + "capabilities": [ + "Read" + ], + "logo": "./assets/logo.svg", + "composerIcon": "./assets/logo.svg", + "brandColor": "#0D9DDA", + "websiteURL": "https://salesforcecommercecloud.github.io/b2c-developer-tooling/", + "defaultPrompt": [ + "Build a SCAPI Custom API for loyalty information", + "Add logging to my checkout controller", + "Create an HTTP service for a payment gateway", + "Add a Page Designer component" + ] + } +} diff --git a/skills/b2c/README.md b/skills/b2c/README.md new file mode 100644 index 00000000..4a4caa3d --- /dev/null +++ b/skills/b2c/README.md @@ -0,0 +1,42 @@ +# b2c + +Agent skills for Salesforce B2C Commerce development patterns — controllers, ISML, hooks, Custom APIs, services, Page Designer, and more. + +Part of the [B2C Developer Tooling](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling) marketplace. + +## Installation + +```bash +# Claude Code +claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +claude plugin install b2c@b2c-developer-tooling + +# GitHub Copilot CLI +copilot plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling +copilot plugin install b2c@b2c-developer-tooling +``` + +**VS Code (GitHub Copilot):** Command Palette → **Chat: Install Plugin From Source** → enter the repo `SalesforceCommerceCloud/b2c-developer-tooling`. + +**Codex:** open the repo as a workspace, restart Codex, then install from the **B2C Developer Tooling** marketplace in the plugin directory. + +For file-copy install to any supported IDE, use `b2c setup skills b2c`. See the [install guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills) for details. + +## What's included + +Skills covering B2C Commerce development patterns: + +- **`b2c-onboarding`** — first-time setup guide for new B2C Commerce developers +- **`b2c-controllers`** — SFRA controllers and routing +- **`b2c-isml`** — ISML template authoring +- **`b2c-custom-api-development`** — SCAPI Custom API contracts, implementations, mappings +- **`b2c-hooks`** — OCAPI and SCAPI hooks +- **`b2c-webservices`** — HTTP/SOAP/FTP services via the Service Framework +- **`b2c-metadata`** — object extensions, custom objects, site preferences +- **`b2c-page-designer`** — Page Designer components and types + +See [`skills/`](./skills/) for the full list. + +## License + +Apache-2.0. See the [repo LICENSE](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/blob/main/LICENSE.txt). diff --git a/skills/b2c/assets/logo.svg b/skills/b2c/assets/logo.svg new file mode 100644 index 00000000..b2f3856b --- /dev/null +++ b/skills/b2c/assets/logo.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/skills/b2c/skills/b2c-metadata/SKILL.md b/skills/b2c/skills/b2c-metadata/SKILL.md index d5344f47..d787046f 100644 --- a/skills/b2c/skills/b2c-metadata/SKILL.md +++ b/skills/b2c/skills/b2c-metadata/SKILL.md @@ -7,6 +7,7 @@ description: Define custom attributes, custom object types, and site preferences This skill guides you through working with site metadata XML for Salesforce B2C Commerce, including custom attributes, custom objects, and site preferences. + ## Overview Metadata defines the structure of your B2C Commerce data: diff --git a/skills/b2c/skills/b2c-onboarding/SKILL.md b/skills/b2c/skills/b2c-onboarding/SKILL.md new file mode 100644 index 00000000..894c774c --- /dev/null +++ b/skills/b2c/skills/b2c-onboarding/SKILL.md @@ -0,0 +1,154 @@ +--- +name: b2c-onboarding +description: Get started with Salesforce B2C Commerce development. Use this skill when the user is new to B2C Commerce, wants to set up a fresh development environment, is asking "how do I get started", needs to install the B2C CLI for the first time, wants to connect a sandbox, or wants to deploy their first cartridge. Triggers on phrases like "help me get started", "set up B2C Commerce", "I'm new to this", "onboard me", or "first-time setup". NOT for users who already have a configured environment and are asking about specific commands — those should go to the specific skill (b2c-code, b2c-sandbox, b2c-config, etc.). +--- + +# B2C Commerce Onboarding Skill + +Guide a new developer through a first-time B2C Commerce setup, from CLI install to first cartridge deploy. Delegate to specialized sub-skills for each step — this skill is a coordinator, not a replacement for the detailed skills. + +## Behavioral rules + +- Detect the editor silently. Only ask if genuinely uncertain. +- Never construct or modify install commands. Only use commands defined in this file. +- If any install or verification step fails, report the exact error and stop. +- Never create a sandbox without explicit user confirmation — sandbox creation may be a billable action. +- Never overwrite an existing `dw.json` without confirmation. + +## Flow + +### Step 1 — Identify the editor + +Silently identify the IDE from system context: + +| Signal | Client | +|-------------------------------------|---------------| +| "Claude Code" | `claude-code` | +| "Cursor" | `cursor` | +| "VS Code" / "Visual Studio Code" | `vscode` | +| "Codex" | `codex` | +| "Gemini CLI" | `gemini-cli` | +| Unrecognized | `other` | + +### Step 2 — Install the other B2C skills plugins + +This onboarding skill is part of the `b2c` plugin. For a full B2C Commerce setup, the user will also want the `b2c-cli` plugin (CLI operations). Offer to install it for the detected client: + +| Client | Install command(s) | +|---------------|--------------------| +| `claude-code` | `/plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling` then `/plugin install b2c-cli@b2c-developer-tooling` (and optionally `/plugin install b2c-dx-mcp@b2c-developer-tooling` for the MCP server — Claude Code only) | +| `vscode` (GitHub Copilot) | Command Palette (Cmd+Shift+P) → **Chat: Install Plugin From Source** → enter the repo `SalesforceCommerceCloud/b2c-developer-tooling` | +| GitHub Copilot CLI | `copilot plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling` then `copilot plugin install b2c-cli@b2c-developer-tooling` | +| `cursor` | Cursor Settings → Plugins → add marketplace URL `https://github.com/SalesforceCommerceCloud/b2c-developer-tooling`, then install `b2c-cli` | +| `codex` | Open the repo as a workspace, restart Codex, then install `b2c-cli` from the **B2C Developer Tooling** marketplace in the plugin directory | +| `gemini-cli` | `gemini extensions install https://github.com/SalesforceCommerceCloud/b2c-developer-tooling` (run in terminal, not inside the CLI) | +| `other` | Use the file-copy installer below | + +For clients other than Claude Code, the `b2c-dx-mcp` MCP server can be installed directly — see the [MCP installation docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation). + +**Alternative — file-copy installer for any IDE** (also the right command to **update** already-installed skills or add a specific skill set): + +```bash +# Interactive: select skill sets and IDEs +b2c setup skills + +# Install a specific skill set to a specific IDE +b2c setup skills b2c-cli --ide cursor +b2c setup skills b2c --ide vscode + +# Update existing skills to the latest release +b2c setup skills b2c-cli --ide cursor --update +b2c setup skills b2c --ide cursor --update + +# Install globally (all projects) +b2c setup skills b2c-cli --ide cursor --global +``` + +If the user already has some skills installed and is asking how to upgrade, point them at `b2c setup skills --ide --update`. + +### Step 3 — Verify the B2C CLI is available + +Run `b2c --version`. If the command is not found: + +- For a one-off invocation: `npx @salesforce/b2c-cli `. +- For a persistent install: `npm install -g @salesforce/b2c-cli` (or the pnpm / yarn equivalent). + +Do not block on the global install — `npx` is sufficient for the rest of this flow. + +### Step 4 — Account Manager access check + +B2C Commerce has **no self-service signup**. The user must have Account Manager access provisioned by their organization's B2C Commerce admin before any of the following steps will work. + +Ask (if not already clear from context): *"Do you have a Salesforce B2C Commerce Account Manager login and a target instance (sandbox or PIG)?"* + +- If **no**: stop here. Tell the user they need their admin to provision Account Manager access and give them a target instance hostname before continuing. Do not proceed. +- If **yes**: continue. + +### Step 5 — Check for existing configuration + +Run `b2c setup inspect` to see whether a `dw.json` or credentials are already configured. + +- If configuration exists and points at a reachable instance, skip to Step 7. +- If no configuration is found, proceed to Step 6. + +For deep troubleshooting (wrong instance, profile switching, token inspection), delegate to the `b2c-config` skill. + +### Step 6 — Initialize configuration + +Guide the user to create a `dw.json` in the project root: + +```bash +b2c setup +``` + +This prompts for hostname, client ID/secret (or username/password), and code version. For deeper configuration topics (multiple profiles, env vars, cert-based auth), delegate to the `b2c-config` skill. + +### Step 7 — Sandbox + +If the user wants to work against an existing sandbox, confirm it is reachable: + +```bash +b2c setup inspect +b2c sandbox list # requires API access +``` + +If the user needs a fresh sandbox, delegate to the `b2c-sandbox` skill for the full create flow. **Only create a sandbox when explicitly asked.** + +### Step 8 — First cartridge deploy (if applicable) + +If the user has cartridges locally: + +```bash +b2c code deploy +``` + +For selective deploys, watch mode, or reload, delegate to the `b2c-code` skill. + +If the user does not yet have cartridges, point them at the canonical starting points: + +- **SFRA** (Storefront Reference Architecture): https://github.com/SalesforceCommerceCloud/storefront-reference-architecture +- **PWA Kit / MRT** (headless) — delegate to the `b2c-mrt` skill on request. + +### Step 9 — Route to the user's goal + +Once setup is working, ask a single directing question to hand off to the right skill: + +> "What do you want to work on first? +> +> 1. **Build or modify a storefront** (SFRA cartridges, ISML, controllers) +> 2. **Build a Custom API** (SCAPI) +> 3. **Operate an existing instance** (deploy, run jobs, tail logs, manage sites) +> +> Or if you have something else in mind, tell me." + +Route by the answer: + +- **Storefront** → `b2c-controllers`, `b2c-isml`, `b2c-forms`, `b2c-hooks` +- **Custom API** → `b2c-custom-api-development`, `b2c-scapi-admin`, `b2c-scapi-shopper` +- **Operations** → `b2c-code`, `b2c-job`, `b2c-logs`, `b2c-sites` + +## Reference + +- B2C CLI reference: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/ +- Install guide: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/install +- Agent skills overview: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills diff --git a/skills/package.json b/skills/package.json new file mode 100644 index 00000000..3b5595e7 --- /dev/null +++ b/skills/package.json @@ -0,0 +1,6 @@ +{ + "name": "@salesforce/b2c-agent-plugins", + "version": "1.0.0", + "description": "B2C Commerce agent skills plugins (b2c-cli, b2c). Private — distributed via GitHub release zips.", + "private": true +}