@W-22451824 feat: SCAPI migration for jobs, code, bm, sites, site-archive, and CAP

.changeset/bm-users-create.md

@@ -0,0 +1,5 @@
+---
+'@salesforce/b2c-cli': minor
+---
+
+Add `b2c bm users create` to create a Business Manager user (create-or-replace), rounding out the `bm users` lifecycle alongside list/get/search/update/delete. Runs over SCAPI with OCAPI fallback like the other `bm users` commands. Flags: `--email` (required), `--first-name`, `--last-name`, `--external-id`, `--password`, `--role` (repeatable), `--disabled`, and preferred locales. Note that most instances use SSO with Account Manager and reject creating *local* BM users with `LocalUserCreationException` — creation succeeds only when the instance is configured to allow local users.

.changeset/scapi-migration.md

@@ -0,0 +1,15 @@
+---
+'@salesforce/b2c-cli': major
+'@salesforce/b2c-tooling-sdk': major
+'b2c-vs-extension': minor
+'@salesforce/b2c-dx-docs': minor
+'@salesforce/b2c-agent-plugins': patch
+---
+
+Migrate `job`, `code`, `bm users`, `bm roles`, `sites`, and catalog discovery to SCAPI-first operation with a temporary OCAPI compatibility fallback. `auto` tries SCAPI when its coordinates and stateless authentication are available, pins the selected backend for multi-request operations, and falls back only on safe capability/auth/request rejections. Site cartridge-path writes, portable BM user search, disabled-user updates, system-job triggers, SDK/CLI/MCP code-version discovery, and VS Code jobs/code/catalog surfaces now participate. Inventory-list enumeration, BM `whoami`, access-key administration, raw OCAPI user-search JSON, and running-job cancellation remain explicit OCAPI compatibility operations because the current live SCAPI schemas have no equivalent.
+
+`setup instance create` accepts optional SCAPI coordinates for SCAPI-first active-code-version detection. They are not required in `auto`; missing coordinates select OCAPI, and failed interactive detection reports the reason before allowing manual entry.
+
+This is a major release because SCAPI and OCAPI JSON/results intentionally retain their backend-specific shapes. Consumers that require a stable legacy shape must explicitly select OCAPI or use the exported compatibility/fallback primitives during the migration. SDK high-level code helpers accept an explicit scripts backend; dual-backend factories and `JobsCompatibilityBackend` expose reusable fallback without making implicit backend selection an SDK-wide policy.
+
+SCAPI currently requires client-credentials or JWT Bearer authentication. Browser-based user auth continues through OCAPI/WebDAV and is selected by `auto`; explicit SCAPI with user auth errors clearly until the platform adds support.

.changeset/scapi-ocapi-deprecation-detection.md

@@ -0,0 +1,10 @@
+---
+'@salesforce/b2c-tooling-sdk': patch
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-dx-docs': patch
+'@salesforce/b2c-agent-plugins': patch
+---
+
+Detect deprecated OCAPI instances and guide users to SCAPI.
+
+When an instance has OCAPI disabled, `code`, `job`, `bm`, `sites`, and `cap` commands now fail with an actionable message — naming the exact SCAPI scope the operation needs (e.g. `sfcc.scripts` / `sfcc.scripts.rw`) — instead of an opaque "Failed to ..." error. Documentation and agent skills for `code`, `job`, and `bm` are now SCAPI-first, presenting OCAPI as the deprecated fallback.

docs/cli/auth.md

@@ -10,7 +10,7 @@ Commands for authentication and token management.
 
 The CLI supports **stateful auth** (session stored on disk) in addition to **stateless auth** (client credentials or one-off browser login):
 
-- **Stateful (browser)**: After you run `b2c auth login`, your access token *and* a long-lived refresh token are stored on disk in the CLI data directory. Subsequent commands silently refresh the access token without re-prompting. If both tokens are missing/expired, the CLI falls back to stateless auth.
+- **Stateful (browser)**: After you run `b2c auth login`, your access token _and_ a long-lived refresh token are stored on disk in the CLI data directory. Subsequent commands silently refresh the access token without re-prompting. If both tokens are missing/expired, the CLI falls back to stateless auth.
 - **Stateful (client credentials)**: Use `b2c auth client` to authenticate with client ID and secret (or user/password) for non-interactive/automation use. Only the access token is persisted — the client secret is never stored. When the access token expires, re-run `b2c auth client` with the same credentials. There is no automatic refresh.
 - **Stateless**: You provide `--client-id` (and optionally `--client-secret`) per run or via environment/config; no session is persisted.
 
@@ -45,11 +45,11 @@ After a successful login, subsequent commands reuse and refresh the stored token
 
 ### Flags
 
-| Flag | Environment Variable | Description |
-|------|---------------------|-------------|
-| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname |
-| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (can be repeated) |
-| `--auth-methods` | `SFCC_AUTH_METHODS` | Browser-based flow to use: `user` (default — Authorization Code + PKCE) or `implicit` (deprecated) |
+| Flag                     | Environment Variable        | Description                                                                                        |
+| ------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname                                                                           |
+| `--auth-scope`           | `SFCC_OAUTH_SCOPES`         | OAuth scopes to request (can be repeated)                                                          |
+| `--auth-methods`         | `SFCC_AUTH_METHODS`         | Browser-based flow to use: `user` (default — Authorization Code + PKCE) or `implicit` (deprecated) |
 
 ### Choosing a flow
 
@@ -100,19 +100,20 @@ b2c auth client --client-id <id> --client-secret <secret> --grant-type client_cr
 
 ### Flags
 
-| Flag | Environment Variable | Description |
-|------|---------------------|-------------|
-| `--client-id` | `SFCC_CLIENT_ID` | Client ID (required) |
-| `--client-secret` | `SFCC_CLIENT_SECRET` | Client secret (required) |
-| `--grant-type` / `-t` | | Force grant type: `client_credentials` or `password` |
-| `--user` | `SFCC_OAUTH_USER_NAME` | Username for password grant |
-| `--user-password` | `SFCC_OAUTH_USER_PASSWORD` | Password for password grant |
-| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request |
-| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname |
+| Flag                     | Environment Variable        | Description                                          |
+| ------------------------ | --------------------------- | ---------------------------------------------------- |
+| `--client-id`            | `SFCC_CLIENT_ID`            | Client ID (required)                                 |
+| `--client-secret`        | `SFCC_CLIENT_SECRET`        | Client secret (required)                             |
+| `--grant-type` / `-t`    |                             | Force grant type: `client_credentials` or `password` |
+| `--user`                 | `SFCC_OAUTH_USER_NAME`      | Username for password grant                          |
+| `--user-password`        | `SFCC_OAUTH_USER_PASSWORD`  | Password for password grant                          |
+| `--auth-scope`           | `SFCC_OAUTH_SCOPES`         | OAuth scopes to request                              |
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname                             |
 
 ### Grant type auto-detection
 
 If `--grant-type` is not specified:
+
 - **client_credentials** is used when only `--client-id` and `--client-secret` are provided
 - **password** is used when `--user` and `--user-password` are also provided
 
@@ -176,19 +177,19 @@ b2c auth token
 
 ### Flags
 
-| Flag | Environment Variable | Description |
-|------|---------------------|-------------|
-| `--client-id` | `SFCC_CLIENT_ID` | Client ID for OAuth |
-| `--client-secret` | `SFCC_CLIENT_SECRET` | Client Secret for OAuth |
-| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (can be repeated) |
-| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (default: account.demandware.com) |
-| `--short-code` | `SFCC_SHORTCODE` | SCAPI short code |
-| `--tenant-id` | `SFCC_TENANT_ID` | Organization/tenant ID |
-| `--auth-methods` | `SFCC_AUTH_METHODS` | Allowed auth methods in priority order (comma-separated): client-credentials, jwt, user, implicit, basic, api-key |
-| `--user-auth` | | Use browser-based user authentication (Authorization Code + PKCE flow) |
-| `--jwt-cert` | `SFCC_JWT_CERT` | Path to JWT certificate file (cert.pem) for JWT Bearer authentication |
-| `--jwt-key` | `SFCC_JWT_KEY` | Path to JWT private key file (key.pem) for JWT Bearer authentication |
-| `--jwt-passphrase` | `SFCC_JWT_PASSPHRASE` | Passphrase for encrypted JWT private key |
+| Flag                     | Environment Variable        | Description                                                                                                       |
+| ------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--client-id`            | `SFCC_CLIENT_ID`            | Client ID for OAuth                                                                                               |
+| `--client-secret`        | `SFCC_CLIENT_SECRET`        | Client Secret for OAuth                                                                                           |
+| `--auth-scope`           | `SFCC_OAUTH_SCOPES`         | OAuth scopes to request (can be repeated)                                                                         |
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (default: account.demandware.com)                                                        |
+| `--short-code`           | `SFCC_SHORTCODE`            | SCAPI short code                                                                                                  |
+| `--tenant-id`            | `SFCC_TENANT_ID`            | Organization/tenant ID                                                                                            |
+| `--auth-methods`         | `SFCC_AUTH_METHODS`         | Allowed auth methods in priority order (comma-separated): client-credentials, jwt, user, implicit, basic, api-key |
+| `--user-auth`            |                             | Use browser-based user authentication (Authorization Code + PKCE flow)                                            |
+| `--jwt-cert`             | `SFCC_JWT_CERT`             | Path to JWT certificate file (cert.pem) for JWT Bearer authentication                                             |
+| `--jwt-key`              | `SFCC_JWT_KEY`              | Path to JWT private key file (key.pem) for JWT Bearer authentication                                              |
+| `--jwt-passphrase`       | `SFCC_JWT_PASSPHRASE`       | Passphrase for encrypted JWT private key                                                                          |
 
 ### Examples
 
@@ -219,7 +220,7 @@ eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
 With `--json`:
 
 ```json
-{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...","expires_in":1799}
+{"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 1799}
 ```
 
 ### Use Cases
@@ -257,13 +258,15 @@ For complete authentication setup instructions, see the [Authentication Setup Gu
 
 ### Quick Reference
 
-| Operation | Auth Required |
-|-----------|--------------|
-| [Code](/cli/code) deploy/watch | WebDAV credentials |
-| [Code](/cli/code) list/activate/delete, [Jobs](/cli/jobs), [Sites](/cli/sites) | OAuth + OCAPI configuration |
-| SCAPI commands ([eCDN](/cli/ecdn), [schemas](/cli/scapi-schemas), [custom-apis](/cli/custom-apis)) | OAuth + SCAPI scopes |
-| [Sandbox](/cli/sandbox), [SLAS](/cli/slas) | OAuth + appropriate roles |
-| [MRT](/cli/mrt) | API Key |
+| Operation                                                                                          | Auth Required                                                                                           |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [Code](/cli/code) deploy/watch                                                                     | WebDAV credentials                                                                                      |
+| [Code](/cli/code) list/activate/delete, [Jobs](/cli/jobs), [BM](/cli/bm) users/roles               | OAuth + SCAPI scopes (OCAPI fallback; OCAPI is [deprecated](/guide/authentication#ocapi-configuration)) |
+| [Sites](/cli/sites) list/cartridge reads                                                           | OAuth + SCAPI scopes (`sfcc.sites`; OCAPI fallback)                                                     |
+| [Sites](/cli/sites) cartridge-path writes                                                          | OAuth + `sfcc.sites.rw` (OCAPI / site-archive fallback)                                                 |
+| SCAPI commands ([eCDN](/cli/ecdn), [schemas](/cli/scapi-schemas), [custom-apis](/cli/custom-apis)) | OAuth + SCAPI scopes                                                                                    |
+| [Sandbox](/cli/sandbox), [SLAS](/cli/slas)                                                         | OAuth + appropriate roles                                                                               |
+| [MRT](/cli/mrt)                                                                                    | API Key                                                                                                 |
 
 See [Configuration](/guide/configuration) for setting up credentials via environment variables or config files.