diff --git a/.changeset/vscode-extension-docs.md b/.changeset/vscode-extension-docs.md new file mode 100644 index 000000000..694b72235 --- /dev/null +++ b/.changeset/vscode-extension-docs.md @@ -0,0 +1,5 @@ +--- +'@salesforce/b2c-dx-docs': patch +--- + +Document the B2C DX VS Code Extension. New `/vscode-extension/` section with overview, installation (with a dynamic download link to the latest VSIX release), configuration reference, and a feature tour covering Sandbox Realm Explorer, Cartridge Code Sync, WebDAV Browser, Content Libraries, SCAPI API Browser, B2C Script Debugger, scaffold/CAP install, log tailing, and B2C CLI plugin support. diff --git a/.changeset/vscode-telemetry.md b/.changeset/vscode-telemetry.md new file mode 100644 index 000000000..334d85e12 --- /dev/null +++ b/.changeset/vscode-telemetry.md @@ -0,0 +1,5 @@ +--- +'b2c-vs-extension': minor +--- + +Add anonymous usage telemetry (extension activation/deactivation lifecycle, broad feature-category usage, exceptions) to help prioritize fixes during the Developer Preview. Sending is non-blocking. Honors the new `b2c-dx.telemetry.enabled` setting (default `true`), VS Code's `telemetry.telemetryLevel`, and the `SFCC_DISABLE_TELEMETRY` / `SF_DISABLE_TELEMETRY` environment variables. No credentials, hostnames, or business data are collected. diff --git a/.github/workflows/ci-vs-extension.yml b/.github/workflows/ci-vs-extension.yml index f454ec60f..c3f1acbd0 100644 --- a/.github/workflows/ci-vs-extension.yml +++ b/.github/workflows/ci-vs-extension.yml @@ -6,11 +6,19 @@ on: - main paths: - 'packages/b2c-vs-extension/**' + - 'packages/b2c-tooling-sdk/**' + - 'pnpm-lock.yaml' + - 'pnpm-workspace.yaml' + - '.github/workflows/ci-vs-extension.yml' pull_request: branches: - main paths: - 'packages/b2c-vs-extension/**' + - 'packages/b2c-tooling-sdk/**' + - 'pnpm-lock.yaml' + - 'pnpm-workspace.yaml' + - '.github/workflows/ci-vs-extension.yml' permissions: contents: read @@ -51,6 +59,14 @@ jobs: restore-keys: | ${{ runner.os }}-pnpm-store- + - name: Cache VS Code test binary + uses: actions/cache@v5 + with: + path: packages/b2c-vs-extension/.vscode-test + key: ${{ runner.os }}-vscode-test-${{ hashFiles('packages/b2c-vs-extension/.vscode-test.mjs', 'pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-vscode-test- + - name: Install dependencies run: pnpm install --frozen-lockfile diff --git a/.gitignore b/.gitignore index 6aa1730bd..daa30cafa 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,7 @@ docs/.vitepress/cache docs/api/ *dw.json* +!packages/b2c-vs-extension/src/test/fixtures/**/dw.json .env .config/wt.toml .b2c/ diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index e429d1594..1808d5d43 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -76,6 +76,14 @@ const guidesSidebar = [ {text: 'Commerce Apps (CAPs)', link: '/guide/commerce-apps'}, ], }, + { + text: 'VS Code Extension', + items: [ + {text: 'Overview', link: '/vscode-extension/'}, + {text: 'Installation', link: '/vscode-extension/installation'}, + {text: 'Configuration', link: '/vscode-extension/configuration'}, + ], + }, { text: 'MCP Server', items: [ @@ -197,7 +205,7 @@ document.addEventListener('click', (e) => { export default defineConfig({ title: 'B2C Developer Toolkit', - description: 'Agentic B2C Developer Toolkit — CLI, Agent Skills, MCP Server, SDK, and IDE extensions for Salesforce B2C Commerce', + description: 'Agentic B2C Developer Toolkit — CLI, Agent Skills, MCP Server, SDK, and the B2C DX VS Code Extension for Salesforce B2C Commerce', base: basePath, head: [['script', {}, versionSwitchScript]], @@ -263,6 +271,7 @@ export default defineConfig({ nav: [ {text: 'Guides', link: '/guide/'}, {text: 'Skills', link: '/guide/agent-skills'}, + {text: 'VS Code', link: '/vscode-extension/'}, {text: 'MCP', link: '/mcp/'}, {text: 'Reference', link: '/cli/'}, {text: 'SDK', link: '/api/'}, @@ -280,6 +289,7 @@ export default defineConfig({ sidebar: { '/mcp/tools/': referenceSidebar, '/mcp/': guidesSidebar, + '/vscode-extension/': guidesSidebar, '/cli/': referenceSidebar, '/guide/': guidesSidebar, '/api/': [ diff --git a/docs/guide/ide-integration.md b/docs/guide/ide-integration.md index ecde3ac09..ef64a2632 100644 --- a/docs/guide/ide-integration.md +++ b/docs/guide/ide-integration.md @@ -4,7 +4,9 @@ description: Configure IDE tooling like Prophet VS Code extension and IntelliJ S # IDE Integration -This guide explains how to connect IDE extensions to your B2C CLI configuration. +This guide explains how to connect third-party IDE extensions (Prophet, IntelliJ SFCC) to your B2C CLI configuration. + +> Looking for the **Salesforce-published B2C DX VS Code Extension**? See the dedicated [VS Code Extension](../vscode-extension/) section — it consumes `dw.json` and the active instance directly, no bridge script required. ## Prophet VS Code Extension diff --git a/docs/guide/index.md b/docs/guide/index.md index c6fe36875..46a8f36a8 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -1,7 +1,11 @@ --- -description: Introduction to the Agentic B2C Developer Toolkit — CLI, Agent Skills, MCP Server, and SDK for Salesforce Agentforce Commerce. +description: Introduction to the Agentic B2C Developer Toolkit — CLI, Agent Skills, MCP Server, VS Code extension, and SDK for Salesforce Agentforce Commerce. --- + + # Introduction The Agentic B2C Developer Toolkit exposes the B2C Commerce platform as commands, MCP tools, and coding skills — so you and your AI agents can build, deploy, and operate storefronts from the terminal or directly inside your IDE. No clicking through Business Manager to deploy, no context-switching to run a job, no manual copy-paste when your agent needs to touch a live sandbox. @@ -9,6 +13,7 @@ The Agentic B2C Developer Toolkit exposes the B2C Commerce platform as commands, - **B2C CLI** — a single command for every workflow: cartridge deploys, jobs, ODS/MRT, WebDAV, site archives, SLAS, eCDN, Account Manager, CI/CD. - **Agent Skills** — 30+ preconfigured skills that teach your coding agent (Claude Code, Cursor, Agentforce Vibes, Copilot, Codex) how B2C Commerce works — SCAPI Custom APIs, SLAS, SFRA controllers and forms, ISML, Page Designer, hooks, custom objects — and which CLI commands to run when. - **MCP Server** — a focused set of MCP tools that complement the CLI for agent-driven workflows. +- **VS Code Extension** *(Developer Preview)* — sandbox management, cartridge code sync, content libraries, SCAPI explorer, and a server-side script debugger right inside VS Code. - **Tooling SDK** — everything the CLI does, available as a typed TypeScript SDK for custom integrations. ## Quick CLI Install @@ -74,6 +79,29 @@ claude plugin install b2c-dx-mcp --scope project See the [MCP Server Installation Guide](/mcp/installation) for full setup steps and troubleshooting. +## Quick VS Code Extension Install + +The B2C DX VS Code Extension brings sandbox management, code sync, content libraries, the SCAPI explorer, and a server-side debugger into VS Code. It isn't on the Marketplace yet — install the latest pre-built `.vsix` from GitHub. + +
+ +Latest version: {{ vsxRelease.version }} · Download {{ vsxRelease.vsixAssetName }} · Release notes + +```bash +code --install-extension {{ vsxRelease.vsixAssetName }} +# or, in Cursor: +cursor --install-extension {{ vsxRelease.vsixAssetName }} +``` + +
+
+ +The extension hasn't shipped a release yet. Browse the GitHub releases page for `b2c-vs-extension@*` tags. + +
+ +See the [VS Code Extension](/vscode-extension/) section for the full overview, [installation](/vscode-extension/installation), and [configuration](/vscode-extension/configuration). + ## Next Steps - [Authentication Setup](./authentication) - Set up Account Manager, OCAPI, and WebDAV @@ -81,6 +109,7 @@ See the [MCP Server Installation Guide](/mcp/installation) for full setup steps - [Configuration](./configuration) - Configure instances and credentials - [IDE Integration](./ide-integration) - Connect Prophet VS Code to B2C CLI configuration - [MCP Server](/mcp/) - AI-assisted development with Model Context Protocol +- [VS Code Extension](/vscode-extension/) - Sandbox management, code sync, and the script debugger inside VS Code - [CLI Reference](/cli/) - Browse available commands - [MCP Tools](/mcp/toolsets) - Explore MCP tools for cartridges, MRT, SCAPI, and so on - [SDK Reference](/api/) - Explore the SDK diff --git a/docs/index.md b/docs/index.md index f0fb5f624..65bb6b8dc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,7 @@ renameNotice: hero: name: Agentic B2C Developer Toolkit text: "" - tagline: CLI, Agent Skills, MCP Server, and IDE extensions for Salesforce Agentforce Commerce — everything you and your coding agent need to build, deploy, and operate B2C Commerce together. + tagline: CLI, Agent Skills, MCP Server, and the B2C DX VS Code Extension for Salesforce Agentforce Commerce — everything you and your coding agent need to build, deploy, and operate B2C Commerce together. image: src: /hero-collage.png alt: Agentic B2C Developer Toolkit — CLI, Agentforce Vibes, and Claude Code @@ -22,11 +22,11 @@ hero: text: Agent Skills link: /guide/agent-skills - theme: alt - text: MCP Server - link: /mcp/ + text: VS Code + link: /vscode-extension/ - theme: alt - text: Reference - link: /cli/ + text: MCP + link: /mcp/ features: - icon: @@ -53,8 +53,20 @@ features: details: A focused set of MCP tools that complement the CLI for agent-driven workflows. Pairs naturally with skills. link: /mcp/ linkText: MCP Server + - icon: + src: /icons/cli.svg + width: 48 + height: 48 + title: VS Code Extension (Developer Preview) + details: B2C DX activity-bar containers for sandbox lifecycle, cartridge code sync, WebDAV, content libraries, SCAPI, and a B2C script debugger — all driven by the same dw.json the CLI uses. + link: /vscode-extension/ + linkText: VS Code Extension --- + + ## Install the CLI ::: code-group @@ -117,3 +129,28 @@ npx @salesforce/b2c-cli setup skills ::: +## Install the VS Code Extension + +The extension is not yet published to the VS Code Marketplace — install the latest pre-built `.vsix` from GitHub releases. + +
+

+ Latest release: {{ vsxRelease.version }} + · + Download {{ vsxRelease.vsixAssetName }} + · + Release notes +

+

Then install with:

+ 
code --install-extension {{ vsxRelease.vsixAssetName }}
+# or, in Cursor:
+cursor --install-extension {{ vsxRelease.vsixAssetName }}
+
+
+ +Browse the [GitHub releases page]({{ vsxRelease.fallbackUrl }}) for `b2c-vs-extension@*` tags and install the `.vsix` via `code --install-extension .vsix`. + +
+ +Detailed setup: [Installation](/vscode-extension/installation) · [Configuration](/vscode-extension/configuration) + diff --git a/docs/vscode-extension/configuration.md b/docs/vscode-extension/configuration.md new file mode 100644 index 000000000..140f24293 --- /dev/null +++ b/docs/vscode-extension/configuration.md @@ -0,0 +1,120 @@ +--- +description: Connect the B2C DX VS Code Extension to a B2C Commerce instance — credentials, OAuth, telemetry, and the b2c-dx.* settings reference. +--- + +# Configuration + +The extension reuses the [B2C CLI](../guide/configuration)'s configuration system, so anything that works with `b2c` works here — `dw.json`, `SFCC_*` environment variables, and active-instance selection. + +This page covers: + +- [Connecting to a B2C Instance](#connecting-to-a-b2c-instance) — credentials per feature. +- [Switching the Active Instance](#switching-the-active-instance) — single-workspace, multi-instance. +- [Settings Reference](#settings-reference) — the `b2c-dx.*` toggles and verbosity controls. + +## Connecting to a B2C Instance + +The extension needs different credentials depending on which feature you use. **A `dw.json` at your workspace root is the recommended setup** — populate the fields each feature needs, and the extension picks them up automatically. + +### Per-feature requirements + +A summary by feature: + +| Feature | Required `dw.json` fields | +| ------- | ------------------------- | +| **Sandbox Realm Explorer** | OAuth (browser login by default; `client-id` + `client-secret` for headless). `Sandbox API User` role with a tenant filter. | +| **WebDAV Browser** | `hostname`, `username`, `password` (WebDAV access key). OAuth (`client-id` + `client-secret`) also accepted. | +| **Content Libraries** | Same as WebDAV. Optionally `contentLibrary` (or `libraries`) to seed the tree. | +| **Cartridge Code Sync** | WebDAV for transfer **and** OCAPI (`client-id` + `client-secret`) for code-version operations. | +| **SCAPI API Browser** | `client-id`, `client-secret`, `short-code`, `tenant-id`. | +| **B2C Script Debugger** | WebDAV (for source-mapping). | +| **Log Tailing** | WebDAV (logs are read from `Logs/`). | +| **CAP install** | WebDAV; some apps additionally require OAuth client credentials. | +| **Scaffold**, **Page Designer Assistant** | None — local-only. | + +### Example `dw.json` + +```jsonc +{ + // WebDAV (Code Sync, WebDAV Browser, Content Libraries, Log Tailing, Debugger) + "hostname": "abcd-001.dx.commercecloud.salesforce.com", + "username": "your-bm-username", + "password": "your-webdav-access-key", + "code-version": "version1", + + // OCAPI / OAuth (Sandbox API, Code Versions, CAP) + "client-id": "...", + "client-secret": "...", + + // SCAPI (API Browser) + "short-code": "...", + "tenant-id": "...", + + // Optional — content tree seed + "contentLibrary": "your-library-id" +} +``` + +You can also set any of these via `SFCC_*` environment variables (`SFCC_SERVER`, `SFCC_USERNAME`, `SFCC_CLIENT_ID`, `SFCC_TENANT_ID`, etc.). See the [CLI Configuration guide](../guide/configuration) for the complete list and precedence rules, and the [Authentication Setup guide](../guide/authentication) for OAuth scope requirements and Account Manager API client setup. + + + +## Switching the Active Instance + +When `dw.json` defines multiple named instances (the recommended pattern for working across dev / staging / sandbox), click the cloud icon in the status bar to run **B2C DX: Switch Active Instance** — a quick-pick over the configured instances. Selecting a new one updates the underlying `dw.json` active-instance pointer and refreshes every view. + +The same pointer is shared with the CLI: switching here is equivalent to running `b2c setup instance set-active `. + +## Settings Reference + +These VS Code settings live under the `b2c-dx.*` namespace. **You usually don't need to change any of them** — they exist for niche cases like disabling a feature you don't use, or quieting the log channel for a bug report. To browse: **Settings** (Cmd+,) → search for `b2c-dx`. + +### Feature toggles + +Each feature is enabled by default. Set to `false` to skip its activation entirely (no tree views, no commands, no context-menu entries). Useful for trimming the UI, isolating activation issues, or running in a project where a feature isn't applicable. + +| Setting | Default | +| ------- | ------- | +| `b2c-dx.features.sandboxExplorer` | `true` | +| `b2c-dx.features.webdavBrowser` | `true` | +| `b2c-dx.features.contentLibraries` | `true` | +| `b2c-dx.features.codeSync` | `true` | +| `b2c-dx.features.logTailing` | `true` | +| `b2c-dx.features.scaffold` | `true` | +| `b2c-dx.features.apiBrowser` | `true` | +| `b2c-dx.features.cap` | `true` | + +The B2C Script Debugger registers regardless of these toggles — it activates only when a `b2c-script` launch configuration is used. + +### Verbosity, polling, telemetry + +| Setting | Default | Description | +| ------- | ------- | ----------- | +| `b2c-dx.logLevel` | `info` | Verbosity for the **B2C DX** output channel. Allowed: `trace`, `debug`, `info`, `warn`, `error`, `silent`. Applied immediately on change. Drop to `debug` or `trace` when filing a bug. | +| `b2c-dx.sandbox.pollingInterval` | `10` | Seconds between polls while a sandbox is in a transitional state (`creating`, `starting`, `stopping`, `deleting`, `cloning`). Range: 2–300. Polling stops automatically once the realm settles. | +| `b2c-dx.telemetry.enabled` | `true` | Send anonymous usage telemetry. Honors VS Code's `telemetry.telemetryLevel` — disabling that disables this regardless of this setting. | + +### Complete defaults (copy-paste) + +```jsonc +// .vscode/settings.json +{ + "b2c-dx.features.sandboxExplorer": true, + "b2c-dx.features.webdavBrowser": true, + "b2c-dx.features.contentLibraries": true, + "b2c-dx.features.codeSync": true, + "b2c-dx.features.logTailing": true, + "b2c-dx.features.scaffold": true, + "b2c-dx.features.apiBrowser": true, + "b2c-dx.features.cap": true, + "b2c-dx.logLevel": "info", + "b2c-dx.sandbox.pollingInterval": 10, + "b2c-dx.telemetry.enabled": true +} +``` + +## Next Steps + +- [Overview](./) — what the extension can do. +- [Authentication Setup](../guide/authentication) — Account Manager API clients, WebDAV access keys, OAuth scopes. +- [CLI Configuration](../guide/configuration) — full `dw.json` reference and precedence rules. diff --git a/docs/vscode-extension/images/README.md b/docs/vscode-extension/images/README.md new file mode 100644 index 000000000..fd9d046ae --- /dev/null +++ b/docs/vscode-extension/images/README.md @@ -0,0 +1,39 @@ +# Screenshot placeholders + +Each `.svg` in this directory is a visible "Screenshot placeholder" used by the VS Code extension docs pages. They render as dashed-border boxes with the slot title and a description, so reviewers can see exactly where a real screenshot belongs. + +## Replacing a placeholder + +1. Capture the screenshot as a PNG at retina resolution (typically ~2560×1440 max). +2. Save it as `./.png` in this directory (use the same `` name as the SVG). +3. In the markdown page that references it, swap the `.svg` extension for `.png`: + + ```diff + - ![Sandbox Realm Explorer](./images/sandbox-explorer.svg) + + ![Sandbox Realm Explorer](./images/sandbox-explorer.png) + ``` + +4. Remove the corresponding `` comment. +5. (Optional) Delete the `.svg` placeholder once all slots referencing it are replaced. + +To enumerate every remaining placeholder, grep the docs: + +```bash +grep -rn "TODO(screenshot)" docs/vscode-extension/ +``` + +## Slot inventory + +| Slot | Used on | +| ---- | ------- | +| `overview` | `index.md` | +| `sandbox-explorer`, `sandbox-context-menu` | `features.md`, `index.md` | +| `webdav-browser`, `webdav-mounted` | `features.md`, `index.md` | +| `content-libraries` | `features.md` | +| `code-sync` | `features.md`, `index.md` | +| `api-browser` | `features.md` | +| `script-debugger` | `features.md`, `index.md` | +| `page-designer-assistant` | `features.md`, `index.md` | +| `scaffold-picker` | `features.md` | +| `release-assets`, `install-vsix` | `installation.md` | +| `settings`, `output-channel` | `configuration.md` | diff --git a/docs/vscode-extension/images/api-browser.png b/docs/vscode-extension/images/api-browser.png new file mode 100644 index 000000000..093eaaa46 Binary files /dev/null and b/docs/vscode-extension/images/api-browser.png differ diff --git a/docs/vscode-extension/images/api-browser.svg b/docs/vscode-extension/images/api-browser.svg new file mode 100644 index 000000000..e1919abb0 --- /dev/null +++ b/docs/vscode-extension/images/api-browser.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + SCAPI API Browser + Swagger UI panel + replace with api-browser.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/code-sync.svg b/docs/vscode-extension/images/code-sync.svg new file mode 100644 index 000000000..6153473ae --- /dev/null +++ b/docs/vscode-extension/images/code-sync.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Cartridge Code Sync + Cartridges view with code-version dropdown + replace with code-sync.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/content-libraries.svg b/docs/vscode-extension/images/content-libraries.svg new file mode 100644 index 000000000..b6a4519de --- /dev/null +++ b/docs/vscode-extension/images/content-libraries.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Content Libraries + Content tree with the export context menu + replace with content-libraries.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/install-vsix.png b/docs/vscode-extension/images/install-vsix.png new file mode 100644 index 000000000..953670886 Binary files /dev/null and b/docs/vscode-extension/images/install-vsix.png differ diff --git a/docs/vscode-extension/images/install-vsix.svg b/docs/vscode-extension/images/install-vsix.svg new file mode 100644 index 000000000..d2cc8bd35 --- /dev/null +++ b/docs/vscode-extension/images/install-vsix.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Install from VSIX + "Install from VSIX..." command palette entry + replace with install-vsix.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/library-explorer.png b/docs/vscode-extension/images/library-explorer.png new file mode 100644 index 000000000..341fc4e9a Binary files /dev/null and b/docs/vscode-extension/images/library-explorer.png differ diff --git a/docs/vscode-extension/images/output-channel.svg b/docs/vscode-extension/images/output-channel.svg new file mode 100644 index 000000000..984c1a901 --- /dev/null +++ b/docs/vscode-extension/images/output-channel.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + B2C DX output channel + B2C DX log stream in the Output panel + replace with output-channel.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/overview.png b/docs/vscode-extension/images/overview.png new file mode 100644 index 000000000..5851b4a92 Binary files /dev/null and b/docs/vscode-extension/images/overview.png differ diff --git a/docs/vscode-extension/images/page-designer-assistant.svg b/docs/vscode-extension/images/page-designer-assistant.svg new file mode 100644 index 000000000..b393702d1 --- /dev/null +++ b/docs/vscode-extension/images/page-designer-assistant.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Page Designer Assistant + Webview UI for scaffolding pages + replace with page-designer-assistant.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/release-assets.svg b/docs/vscode-extension/images/release-assets.svg new file mode 100644 index 000000000..2fe79b040 --- /dev/null +++ b/docs/vscode-extension/images/release-assets.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Release assets + GitHub release asset list with the .vsix + replace with release-assets.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/sandbox-context-menu.svg b/docs/vscode-extension/images/sandbox-context-menu.svg new file mode 100644 index 000000000..f1d01cf27 --- /dev/null +++ b/docs/vscode-extension/images/sandbox-context-menu.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Sandbox context menu + Right-click context menu over a started sandbox + replace with sandbox-context-menu.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/sandbox-explorer.png b/docs/vscode-extension/images/sandbox-explorer.png new file mode 100644 index 000000000..dc82898f1 Binary files /dev/null and b/docs/vscode-extension/images/sandbox-explorer.png differ diff --git a/docs/vscode-extension/images/sandbox-explorer.svg b/docs/vscode-extension/images/sandbox-explorer.svg new file mode 100644 index 000000000..9987b7d8c --- /dev/null +++ b/docs/vscode-extension/images/sandbox-explorer.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Sandbox Realm Explorer + Started + cloned sandbox in the tree + replace with sandbox-explorer.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/scaffold-picker.svg b/docs/vscode-extension/images/scaffold-picker.svg new file mode 100644 index 000000000..bba722952 --- /dev/null +++ b/docs/vscode-extension/images/scaffold-picker.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Scaffold quick-pick + "New from Scaffold..." picker + replace with scaffold-picker.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/script-debugger.png b/docs/vscode-extension/images/script-debugger.png new file mode 100644 index 000000000..5443c64e9 Binary files /dev/null and b/docs/vscode-extension/images/script-debugger.png differ diff --git a/docs/vscode-extension/images/script-debugger.svg b/docs/vscode-extension/images/script-debugger.svg new file mode 100644 index 000000000..94f1bf5fa --- /dev/null +++ b/docs/vscode-extension/images/script-debugger.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + B2C Script Debugger + Paused on a breakpoint + replace with script-debugger.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/settings.svg b/docs/vscode-extension/images/settings.svg new file mode 100644 index 000000000..6194700f1 --- /dev/null +++ b/docs/vscode-extension/images/settings.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + Settings + Settings UI filtered to b2c-dx + replace with settings.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/webdav-browser.svg b/docs/vscode-extension/images/webdav-browser.svg new file mode 100644 index 000000000..b7d413811 --- /dev/null +++ b/docs/vscode-extension/images/webdav-browser.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + WebDAV Browser + Catalogs and libraries expanded + replace with webdav-browser.png + \ No newline at end of file diff --git a/docs/vscode-extension/images/webdav-mounted.svg b/docs/vscode-extension/images/webdav-mounted.svg new file mode 100644 index 000000000..8e92f46af --- /dev/null +++ b/docs/vscode-extension/images/webdav-mounted.svg @@ -0,0 +1,21 @@ + + + + + + + + + + SCREENSHOT PLACEHOLDER + WebDAV mounted + "Open as Workspace Folder" result + replace with webdav-mounted.png + \ No newline at end of file diff --git a/docs/vscode-extension/index.md b/docs/vscode-extension/index.md new file mode 100644 index 000000000..07de32e9e --- /dev/null +++ b/docs/vscode-extension/index.md @@ -0,0 +1,70 @@ +--- +description: B2C DX VS Code Extension — sandbox management, cartridge code sync, WebDAV browser, content libraries, SCAPI API browser, script debugger, and project scaffolding. +--- + +# B2C DX VS Code Extension + +::: warning Developer Preview +The B2C DX VS Code Extension is in **active development**. Features may change, break, or be removed without notice. The extension is not yet published to the VS Code Marketplace — install the latest pre-built `.vsix` from GitHub releases (see [Installation](./installation)). + +Please file issues and feature requests on the [GitHub repository](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/issues). +::: + +Manage your B2C Commerce sandboxes, sync cartridges, browse content libraries and SCAPI schemas, debug server-side scripts, and scaffold new projects — all from inside VS Code. If your project already works with the [B2C CLI](../guide/), the extension picks up the same connection automatically. + +[![B2C DX activity bar](./images/overview.png)](./images/overview.png) + +## Highlights + +### Sandbox Realm Explorer + +Spin up, start, stop, clone, and clean up your on-demand sandboxes from a tree view. Cloned sandboxes are clearly marked, and the right-click menu only shows actions that make sense for the sandbox's current state. + +[![Sandbox Realm Explorer](./images/sandbox-explorer.png)](./images/sandbox-explorer.png) + +### Library Explorer + +Find Page Designer pages and components fast, with one-click export (with assets, without assets, or assets only), live editing of component XML, and round-trip imports of site archives. The library tree is filterable when you have hundreds of pages. + +[![Library Explorer](./images/library-explorer.png)](./images/library-explorer.png) + +### B2C Script Debugger + +Step through anything that runs server-side: cartridge controllers, jobs, custom scripts, SCAPI hooks, and Custom APIs. Set breakpoints, drop log points, watch variables, and step in and out — the full debugger experience you'd expect from any other Node project. + +[![B2C Script Debugger](./images/script-debugger.png)](./images/script-debugger.png) + +### Cartridge Management and Code Watch/Upload + +Edit cartridges locally and have changes show up on your sandbox automatically. Deploy on demand, diff against the active code version, and manage code versions without leaving the editor. + +### SCAPI API Explorer + +Explore every SCAPI API your instance exposes and try requests against them in a built-in Swagger UI. Authentication is handled for you using the same credentials your CLI already has. + +[![SCAPI API Explorer](./images/api-browser.png)](./images/api-browser.png) + +### WebDAV Browser + +Browse your sandbox's catalogs, libraries, and IMPEX folders right inside VS Code. Open remote files like local ones, drag-and-drop to upload, or mount a remote folder as a workspace folder. + +### Scaffolding + +Generate new cartridges, controllers, hooks, jobs, and other boilerplate from a curated set of templates. Available from **File → New File...** or by right-clicking a folder in the Explorer. + +### Log Tailing + +Stream live `error-*.log`, `warn-*.log`, and `info-*.log` files from your sandbox into a VS Code output channel. Use **Start Tailing Logs** to begin and **Stop Tailing Logs** to end. + +### Active Instance Status Bar + +The bottom-left of the window shows your active instance — the name, the hostname, and a pin icon if you've locked a particular folder as the project root. Click it to switch instances; every view updates instantly. + +### B2C CLI Plugin Support + +The extension runs the [B2C CLI](../guide/) under the hood, so any plugin you've installed via `b2c plugins install` automatically applies here too. Add a plugin that introduces a new config source, a custom sandbox command, or middleware, and the extension picks it up the next time the workspace loads — no separate plugin registry. (The MCP server works the same way; see the [MCP plugins note](../mcp/#plugins).) + +## Next Steps + +- [Installation](./installation) — download and install the extension. +- [Connecting to your sandbox](./configuration#connecting-to-a-b2c-instance) — what each feature needs. diff --git a/docs/vscode-extension/installation.md b/docs/vscode-extension/installation.md new file mode 100644 index 000000000..a2499a259 --- /dev/null +++ b/docs/vscode-extension/installation.md @@ -0,0 +1,77 @@ +--- +description: Install the B2C DX VS Code Extension from a pre-built .vsix release artifact. +--- + + + +# Installation + +::: warning Not on the Marketplace yet +The extension isn't on the VS Code or Open VSX marketplaces yet. For now, grab the latest build from GitHub and install it manually — it only takes a minute. +::: + +## Get the latest build + +
+ +Latest version: **{{ release.version }}** (released {{ new Date(release.publishedAt).toLocaleDateString(undefined, {dateStyle: 'medium'}) }}). + +

+ Download {{ release.vsixAssetName }} + See what's new +

+ +
+
+ +We couldn't find a published build right now. Head over to the [releases page]({{ release.fallbackUrl }}) and grab the latest `b2c-vs-extension@*` tag. + +
+ +## Install it + +Once you've got the file, install it from the command line or from the Extensions view in VS Code. + +::: code-group + +```bash [VS Code] +code --install-extension b2c-vs-extension-X.Y.Z.vsix +``` + +```bash [Cursor] +cursor --install-extension b2c-vs-extension-X.Y.Z.vsix +``` + +```text [Extensions view] +1. Open the Extensions view (Cmd+Shift+X / Ctrl+Shift+X) +2. Click the "..." menu in the view header +3. Choose "Install from VSIX..." +4. Pick the file you just downloaded +``` + +::: + + +![Install from VSIX](./images/install-vsix.png) + +Reload the window when prompted. You'll see new **B2C-DX**, **B2C-DX: SCAPI**, and **B2C-DX Sandboxes** icons in the activity bar. + +## Before you start + +A few things to have ready: + +- **VS Code 1.105 or newer** (Cursor and VS Codium work too). +- **The B2C CLI** installed — `npm install -g @salesforce/b2c-cli`. The extension uses it under the hood for some workflows. See the [CLI Installation guide](../guide/installation) for other install options. + +## Connect to your sandbox + +The extension uses the same connection your CLI already uses, so most of the time there's nothing more to set up. Different features need different credentials though — see [Connecting to your sandbox](./configuration#connecting-to-a-b2c-instance) for what each one needs and a copy-paste example. + +New here? The [Authentication Setup guide](../guide/authentication) walks through getting your credentials in the first place. + +## Next Steps + +- [Overview](./) — what the extension can do. +- [Connecting to your sandbox](./configuration#connecting-to-a-b2c-instance) — what each feature needs. diff --git a/docs/vscode-extension/release.data.ts b/docs/vscode-extension/release.data.ts new file mode 100644 index 000000000..8c38a3e6e --- /dev/null +++ b/docs/vscode-extension/release.data.ts @@ -0,0 +1,140 @@ +/* + * Copyright (c) 2025, Salesforce, Inc. + * SPDX-License-Identifier: Apache-2 + * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0 + */ + +/* + * VitePress build-time data loader for the latest published B2C DX VS Code + * extension `.vsix` asset. Consumed by `installation.md` via `