@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/content/guidance/b2c-cli/b2c-mrt/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: b2c-mrt
+description: Deploy and manage Managed Runtime (MRT) storefronts using the b2c CLI. Use this skill whenever the user needs to deploy a PWA Kit bundle, manage MRT environments and projects, set environment variables, configure URL redirects, or manage organization connections — even if they just say "deploy my PWA" or "set up a staging environment".
+---
+
+# B2C MRT Skill
+
+Use the `b2c` CLI to manage Managed Runtime (MRT) projects, environments, bundles, and deployments for PWA Kit storefronts.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli mrt bundle deploy`).
+
+## Configuration & Authentication
+
+The CLI resolves the MRT API key from `MRT_API_KEY` (or `SFCC_MRT_API_KEY`), `dw.json`, `~/.mobify`, or configuration plugins. Project and environment defaults can also come from `package.json` under `b2c` (`mrtProject`, `mrtEnvironment`) or environment variables. `package.json` cannot supply API keys or other secrets. **Flags like `--api-key`, `-p`, and `-e` are usually unnecessary** when defaults are configured — only pass them to override.
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (use `--json` for scripting; keep secrets masked unless the user explicitly requests their values). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+### MRT Backends (legacy vs SCAPI)
+
+Most MRT commands run against the legacy MRT Cloud API (API key). Two commands — `mrt bundle history` and `mrt bundle deploy <bundleId>` — can also run over the SCAPI MRT backend. Choose with `--mrt-backend` (`MRT_BACKEND` / `SFCC_MRT_BACKEND`, or `mrtBackend` in `dw.json`):
+
+- `auto` (default) — use SCAPI when it's configured (`--short-code` + `--tenant-id` + client-credentials or JWT Bearer auth; scopes `sfcc.storefront.deployments[.rw]`), otherwise legacy. Falls back to legacy on safe pre-execution errors.
+- `legacy` — always the MRT Cloud API.
+- `scapi` — always SCAPI, with no fallback; errors if prerequisites are missing. Also errors on unsupported commands and on the local-build push path (`deploy` with no bundle ID).
+
+Notes:
+
+- Under `--json`, these commands emit the **serving backend's native shape** (legacy `{count, next, previous, deployments}` vs SCAPI `{limit, offset, total, data}`). The human table is normalized; `--json` is not. Pin `legacy` or `scapi` when a script needs a stable shape.
+- Legacy-only flags (`--api-key`, `--cloud-origin` / `-u`, `--credentials-file` / `-c`) are ignored — with a warning — when SCAPI serves the request.
+- `--storefront` (long) and `-s` (short) are aliases of `--project` / `-p` — the SCAPI storefront ID is the project slug, so all four are interchangeable on every `mrt` command. On `mrt project create` this flag sets the new project's slug (auto-generated from the name if omitted); `mrt bundle save` uses `-d` for `--save-dir`, keeping `-s` free for the storefront alias.
+
+## Command Structure
+
+```
+mrt
+├── org                          - Organizations and B2C connections
+│   ├── member                   - Organization-level member management
+│   └── cert                     - Custom domain certificates
+├── project                      - Project management
+│   ├── member                   - Team member management
+│   └── notification             - Deployment notifications
+├── env                          - Environment management (incl. clone)
+│   ├── var                      - Environment variables
+│   ├── redirect                 - URL redirects
+│   └── access-control           - Access control headers
+├── bundle                       - Bundle and deployment management (incl. delete)
+└── user                         - User profile and settings
+```
+
+## Quick Examples
+
+### Deploy a Bundle
+
+```bash
+# Push local build to staging
+b2c mrt bundle deploy -p my-storefront -e staging
+
+# Push to production with release message
+b2c mrt bundle deploy -p my-storefront -e production -m "Release v1.0.0"
+
+# Deploy existing bundle by ID
+b2c mrt bundle deploy 12345 -p my-storefront -e production
+
+# Build and upload a v2-format bundle (upload only; deploy the returned ID separately)
+b2c mrt bundle upload-v2 -p my-storefront
+```
+
+### Manage Environments
+
+```bash
+# List environments
+b2c mrt env list -p my-storefront
+
+# Create a new environment
+b2c mrt env create qa -p my-storefront --name "QA Environment"
+
+# Clone an existing environment (-e is the source; positional arg is the new slug)
+b2c mrt env clone qa -p my-storefront -e staging --clone-redirects --clone-env-vars
+
+# Get environment details
+b2c mrt env get -p my-storefront -e production
+
+# Invalidate CDN cache
+b2c mrt env invalidate -p my-storefront -e production
+```
+
+### Environment Variables
+
+```bash
+# List variables
+b2c mrt env var list -p my-storefront -e production
+
+# Set variables
+b2c mrt env var set API_KEY=secret DEBUG=true -p my-storefront -e staging
+
+# Delete a variable
+b2c mrt env var delete OLD_VAR -p my-storefront -e production
+```
+
+### View Deployment History
+
+```bash
+# List bundles in project
+b2c mrt bundle list -p my-storefront
+
+# View deployment history for environment
+b2c mrt bundle history -p my-storefront -e production
+
+# Download a bundle artifact
+b2c mrt bundle download 12345 -p my-storefront
+
+# Delete one or more bundles (uses bulk-delete for >1)
+b2c mrt bundle delete 12345 -p my-storefront
+b2c mrt bundle delete 12345 12346 12347 -p my-storefront --force
+```
+
+### Organization Members and Certificates
+
+Organization members are distinct from project members; they hold a role at the organization level. Custom-domain certificates are organization-scoped and referenced by `b2c mrt env create`/`update`/`clone` via `--certificate-id`.
+
+```bash
+# List, add, update, remove organization members
+b2c mrt org member list --org my-org
+b2c mrt org member add alice@example.com --org my-org --role member --view-all-projects
+b2c mrt org member update alice@example.com --org my-org --no-cert-permission
+b2c mrt org member remove alice@example.com --org my-org
+
+# Manage custom domain certificates
+b2c mrt org cert list --org my-org
+b2c mrt org cert create shop.example.com --org my-org   # output includes the DNS validation record
+b2c mrt org cert get 123 --org my-org
+b2c mrt org cert restart-validation 123 --org my-org
+b2c mrt org cert delete 123 --org my-org
+```
+
+### Project Management
+
+```bash
+# List projects
+b2c mrt project list
+
+# Get project details
+b2c mrt project get -p my-storefront
+
+# List project members
+b2c mrt project member list -p my-storefront
+
+# Add a member
+b2c mrt project member add user@example.com -p my-storefront --role developer
+```
+
+### URL Redirects
+
+```bash
+# List redirects
+b2c mrt env redirect list -p my-storefront -e production
+
+# Create a redirect
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/old-path" --to "/new-path"
+
+# Clone redirects between environments
+b2c mrt env redirect clone -p my-storefront --source staging --target production
+```
+
+## Configuration
+
+### dw.json
+
+Configure MRT settings in your project's `dw.json`:
+
+```json
+{
+  "mrtProject": "my-storefront",
+  "mrtEnvironment": "staging"
+}
+```
+
+### Environment Variables
+
+```bash
+export MRT_API_KEY=your-api-key
+export MRT_PROJECT=my-storefront
+export MRT_ENVIRONMENT=staging
+export MRT_BACKEND=auto        # auto (default) | legacy | scapi
+```
+
+### ~/.mobify Config
+
+Store your API key in `~/.mobify`:
+
+```json
+{
+  "api_key": "your-mrt-api-key"
+}
+```
+
+## Detailed References
+
+- [Project Commands](references/PROJECT-COMMANDS.md) - Projects, members, and notifications
+- [Environment Commands](references/ENVIRONMENT-COMMANDS.md) - Environments, variables, redirects
+- [Bundle Commands](references/BUNDLE-COMMANDS.md) - Deployments, history, downloads
+
+### More Commands
+
+See `b2c mrt --help` for a full list of available commands and options.

package/content/guidance/b2c-cli/b2c-mrt/references/BUNDLE-COMMANDS.md

@@ -0,0 +1,185 @@
+# MRT Bundle Commands Reference
+
+Detailed reference for MRT bundle deployment, listing, history, and download commands.
+
+## Bundle Deploy
+
+Push a local build or deploy an existing bundle to Managed Runtime.
+
+### Push Local Build
+
+```bash
+# Push local build to project (no deployment)
+b2c mrt bundle deploy --project my-storefront
+
+# Push and deploy to staging
+b2c mrt bundle deploy -p my-storefront -e staging
+
+# Push and deploy to production with message
+b2c mrt bundle deploy -p my-storefront -e production --message "Release v1.0.0"
+
+# Push from custom build directory
+b2c mrt bundle deploy -p my-storefront --build-dir ./dist
+
+# Specify Node.js version
+b2c mrt bundle deploy -p my-storefront --node-version 20.x
+
+# Set SSR parameters
+b2c mrt bundle deploy -p my-storefront --ssr-param SSRProxyPath=/api
+
+# Multiple SSR parameters
+b2c mrt bundle deploy -p my-storefront \
+  --ssr-param SSRProxyPath=/api \
+  --ssr-param SSRTimeout=30000
+```
+
+### Deploy Existing Bundle
+
+Deploying an existing bundle (with a bundle ID) is backend-aware — it honors `--mrt-backend` (`auto` / `legacy` / `scapi`). Pushing a local build is legacy-pinned. See the "MRT Backends" section in the skill overview.
+
+```bash
+# Deploy existing bundle by ID
+b2c mrt bundle deploy 12345 -p my-storefront -e production
+
+# Deploy with JSON output
+b2c mrt bundle deploy 12345 -p my-storefront -e staging --json
+
+# Deploy via the SCAPI backend and wait for completion
+b2c mrt bundle deploy 12345 -p my-storefront -e production --mrt-backend scapi --wait
+```
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--message`, `-m` | Bundle message/description | |
+| `--build-dir`, `-b` | Path to build directory | `build` |
+| `--ssr-only` | Server-only file patterns | `ssr.js,ssr.mjs,server/**/*` |
+| `--ssr-shared` | Shared file patterns | `static/**/*,client/**/*` |
+| `--node-version`, `-n` | Node.js version for SSR | `24.x` |
+| `--ssr-param` | SSR parameters (key=value, can repeat) | |
+
+## Bundle Upload (v2)
+
+Build and upload a **v2-format** bundle. This is **upload only** — it does not deploy. Deploy the returned bundle ID separately with `b2c mrt bundle deploy <bundleId> -e <env>`.
+
+Unlike `deploy` (v1), the v2 archive is a gzip tar whose files live under a root directory (default `bld/`), and the SSR configuration is written **inside** the archive at `{root-dir}/{config-path}` (default `bld/.mrt/config.json`) rather than sent as request fields.
+
+The SSR configuration is read from the build's on-disk v2 config file at `{build-dir}/{config-path}` when present. Otherwise it is read from `config.server.ts` in the project directory (`--project-directory`, default the current directory — a compiled `config.server.js`/`config.server.mjs` or the legacy `build/config.server.js` is also accepted), then defaults. Flags override the resolved values per key. If the build already emits the v2 config file, it is excluded from the archive and replaced by the resolved config (no duplicate entry).
+
+`config.server.ts` is evaluated from source (via jiti), so keep type-only imports as `import type`. A `config.server.ts` that exists but fails to import errors the command rather than silently falling back to defaults.
+
+Both `deploy` (v1) and `upload-v2` record the project's `package.json` dependencies (`dependencies` + `devDependencies`) as bundle metadata (v1 `bundle_metadata.dependencies`; v2 `bundleMetadata.dependencies` inside the archive config), matching pwa-kit/storefront-next. An explicit `--dependencies` (v2) or dependencies already in the v2 config file take precedence; collection is best-effort and never blocks a bundle.
+
+```bash
+# Build and upload from ./build
+b2c mrt bundle upload-v2 --project my-storefront
+
+# Upload from a custom build directory
+b2c mrt bundle upload-v2 -p my-storefront --build-dir ./dist
+
+# Allow SSR patterns that match no files
+b2c mrt bundle upload-v2 -p my-storefront --match-mode ignore_missing
+
+# SSR parameters and bundle metadata
+b2c mrt bundle upload-v2 -p my-storefront --ssr-param EnvBasePath=/mobify --node-version 20.x
+b2c mrt bundle upload-v2 -p my-storefront --dependencies @./deps.json --cc-override plugin-a
+```
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--message`, `-m` | Bundle message/description | |
+| `--build-dir`, `-b` | Path to build directory | `build` |
+| `--root-dir` | Archive path prefix for built files and the config file | `bld` |
+| `--config-path` | In-archive config file path, relative to `--root-dir` | `.mrt/config.json` |
+| `--match-mode` | Handling of SSR patterns matching no files (`strict` or `ignore_missing`) | `strict` |
+| `--ssr-only` | Server-only file patterns | `ssr.js,ssr.mjs,server/**/*` |
+| `--ssr-shared` | Shared file patterns | `static/**/*,client/**/*` |
+| `--node-version`, `-n` | Node.js version for SSR | `24.x` |
+| `--ssr-param` | SSR parameters (key=value, can repeat) | |
+| `--dependencies` | Bundle dependencies as inline JSON or a `@path` to a JSON file | |
+| `--cc-override` | Commerce Cloud override identifier (can repeat) | |
+
+## Bundle List
+
+List bundles in a project.
+
+```bash
+b2c mrt bundle list --project my-storefront
+b2c mrt bundle list -p my-storefront --limit 10
+b2c mrt bundle list -p my-storefront --offset 20
+b2c mrt bundle list -p my-storefront --json
+```
+
+**Output columns:** Bundle ID, Message, Status, Created
+
+## Bundle History
+
+View deployment history for an environment. Backend-aware (`--mrt-backend`); under `--json` it returns the serving backend's native response verbatim (legacy vs SCAPI shapes differ).
+
+```bash
+b2c mrt bundle history -p my-storefront -e production
+b2c mrt bundle history -p my-storefront -e staging --limit 5
+b2c mrt bundle history -p my-storefront -e production --json
+b2c mrt bundle history -p my-storefront -e staging --mrt-backend scapi
+```
+
+**Output columns:** Bundle ID, Message, Status, Type, Created
+
+## Bundle Download
+
+Download a bundle artifact.
+
+```bash
+# Download to current directory (bundle-{id}.tgz)
+b2c mrt bundle download 12345 -p my-storefront
+
+# Download to specific path
+b2c mrt bundle download 12345 -p my-storefront -o ./artifacts/bundle.tgz
+
+# Get download URL only (for use in scripts)
+b2c mrt bundle download 12345 -p my-storefront --url-only
+
+# JSON output with download URL
+b2c mrt bundle download 12345 -p my-storefront --json
+```
+
+## Common Workflows
+
+### Development to Production Pipeline
+
+```bash
+# 1. Build your PWA Kit application
+npm run build
+
+# 2. Push to staging for testing
+b2c mrt bundle deploy -p my-storefront -e staging -m "v1.0.0-rc1"
+
+# 3. After testing, deploy same bundle to production
+# First, find the bundle ID from the staging deployment
+b2c mrt bundle list -p my-storefront --limit 1
+
+# 4. Deploy that bundle to production
+b2c mrt bundle deploy 12345 -p my-storefront -e production
+```
+
+### Rollback to Previous Bundle
+
+```bash
+# 1. View deployment history
+b2c mrt bundle history -p my-storefront -e production
+
+# 2. Deploy previous bundle
+b2c mrt bundle deploy 12340 -p my-storefront -e production
+```
+
+### Download and Inspect Bundle
+
+```bash
+# Download the bundle
+b2c mrt bundle download 12345 -p my-storefront -o bundle.tgz
+
+# Extract and inspect
+tar -xzf bundle.tgz
+ls -la
+```

package/content/guidance/b2c-cli/b2c-mrt/references/ENVIRONMENT-COMMANDS.md

@@ -0,0 +1,195 @@
+# MRT Environment Commands Reference
+
+Detailed reference for MRT environment, variable, redirect, and access control commands.
+
+## Environment Management
+
+### List Environments
+
+```bash
+b2c mrt env list --project my-storefront
+b2c mrt env list -p my-storefront --json
+```
+
+### Create Environment
+
+```bash
+# Basic staging environment
+b2c mrt env create staging --project my-storefront --name "Staging Environment"
+
+# Production environment in specific region
+b2c mrt env create production -p my-storefront --name "Production" \
+  --production --region eu-west-1
+
+# With external hostname configuration
+b2c mrt env create prod -p my-storefront --name "Production" \
+  --production \
+  --external-hostname www.example.com \
+  --external-domain example.com
+
+# With cookie forwarding and source maps
+b2c mrt env create dev -p my-storefront --name "Development" \
+  --allow-cookies --enable-source-maps
+
+# The new environment's slug may be given as the positional OR via --environment / -e
+b2c mrt env create -p my-storefront -e staging --name "Staging Environment"
+```
+
+> **Slug as positional or flag:** the environment slug can be supplied as the positional argument **or** via `-e` / `--environment` (also honoring `MRT_ENVIRONMENT` / `dw.json`). An explicit positional wins if both are given.
+
+**Flags:**
+| Flag | Description |
+|------|-------------|
+| `--name`, `-n` | Display name (required) |
+| `--region`, `-r` | AWS region for SSR deployment |
+| `--production` | Mark as production environment |
+| `--hostname` | Hostname pattern for V8 Tag loading |
+| `--external-hostname` | Full external hostname (e.g., www.example.com) |
+| `--external-domain` | External domain for Universal PWA SSR |
+| `--allow-cookies` | Forward HTTP cookies to origin |
+| `--enable-source-maps` | Enable source map support |
+
+### Get Environment Details
+
+```bash
+b2c mrt env get --project my-storefront --environment staging
+b2c mrt env get -p my-storefront -e production --json
+```
+
+### Update Environment
+
+```bash
+b2c mrt env update -p my-storefront -e staging --name "Updated Staging"
+b2c mrt env update -p my-storefront -e production --allow-cookies
+b2c mrt env update -p my-storefront -e dev --no-enable-source-maps
+```
+
+### Delete Environment
+
+```bash
+b2c mrt env delete staging --project my-storefront
+b2c mrt env delete old-env -p my-storefront --force
+
+# The env slug may be given as the positional OR via --environment / -e
+b2c mrt env delete -p my-storefront -e old-env --force
+```
+
+> **Slug as positional or flag:** the environment slug can be supplied as the positional argument **or** via `-e` / `--environment` (also honoring `MRT_ENVIRONMENT` / `dw.json`). An explicit positional wins if both are given.
+
+### Invalidate Cache
+
+Invalidate CDN cached content for an environment.
+
+```bash
+# Invalidate all cached content
+b2c mrt env invalidate -p my-storefront -e production
+
+# Invalidate specific paths
+b2c mrt env invalidate -p my-storefront -e production \
+  --path "/products/*" --path "/categories/*"
+```
+
+### B2C Commerce Connection
+
+Get or set B2C Commerce instance connection for an environment.
+
+```bash
+# Get current configuration
+b2c mrt env b2c -p my-storefront -e production
+
+# Set B2C instance
+b2c mrt env b2c -p my-storefront -e production --instance-id aaaa_prd
+
+# Set B2C instance with specific sites
+b2c mrt env b2c -p my-storefront -e production \
+  --instance-id aaaa_prd --sites RefArch,SiteGenesis
+
+# Clear sites list
+b2c mrt env b2c -p my-storefront -e production --clear-sites
+```
+
+## Environment Variables
+
+### List Variables
+
+```bash
+b2c mrt env var list --project my-storefront --environment production
+b2c mrt env var list -p my-storefront -e staging --json
+```
+
+### Set Variables
+
+```bash
+# Single variable
+b2c mrt env var set MY_VAR=value -p my-storefront -e production
+
+# Multiple variables
+b2c mrt env var set API_KEY=secret DEBUG=true FEATURE_FLAG=enabled \
+  -p my-storefront -e staging
+
+# Value with spaces (use quotes)
+b2c mrt env var set "MESSAGE=hello world" -p my-storefront -e production
+
+# Using environment variables for auth
+export MRT_API_KEY=your-api-key
+export MRT_PROJECT=my-storefront
+export MRT_ENVIRONMENT=staging
+b2c mrt env var set MY_VAR=value
+```
+
+### Delete Variable
+
+```bash
+b2c mrt env var delete MY_VAR -p my-storefront -e production
+```
+
+## URL Redirects
+
+### List Redirects
+
+```bash
+b2c mrt env redirect list -p my-storefront -e production
+b2c mrt env redirect list -p my-storefront -e production --limit 50
+b2c mrt env redirect list -p my-storefront -e production --json
+```
+
+### Create Redirect
+
+```bash
+# Basic redirect
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/old-path" --to "/new-path"
+
+# Permanent redirect (301)
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/legacy/*" --to "/modern/$1" --permanent
+
+# Temporary redirect (302, default)
+b2c mrt env redirect create -p my-storefront -e production \
+  --from "/promo" --to "/sale"
+```
+
+### Delete Redirect
+
+```bash
+b2c mrt env redirect delete abc-123 -p my-storefront -e production
+b2c mrt env redirect delete abc-123 -p my-storefront -e production --force
+```
+
+### Clone Redirects
+
+Copy redirects from one environment to another.
+
+```bash
+b2c mrt env redirect clone -p my-storefront \
+  --source staging --target production
+```
+
+## Access Control Headers
+
+### List Access Control Headers
+
+```bash
+b2c mrt env access-control list -p my-storefront -e staging
+b2c mrt env access-control list -p my-storefront -e production --json
+```