@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/commerce-react-storefront-create/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: commerce-react-storefront-create
+description: "Stand up the commerce-b2b-headless reference React storefront in a Salesforce B2B Commerce org, end to end — discover the org's WebStores, pick one, fill the four org-specific values (WebStore Id, BuyerGroup Id, buyer permission set group, Vite org alias), build + deploy the UI Bundle, assign the site guest user the auth permission set, and hand back the live Experience Cloud storefront URL. Use whenever the user says \"create a react storefront in my org\", \"set up the headless B2B storefront\", \"deploy commerce-b2b-headless\", \"stand up a React storefront for <org-alias>\", \"get me a hosted headless commerce storefront\", or points at a cloned commerce-b2b-headless repo and wants it running against their org."
+metadata:
+  relatedSkills:
+  - experience-ui-bundle-deploy
+  version: "1.0"
+  minApiVersion: "65.0"
+  domains:
+  - "Commerce"
+  - "Experience"
+  cliTools:
+  - tool:
+    - "git"
+    semver: ">=2.0"
+  - tool:
+    - "jq"
+    semver: ">=1.6.0"
+  - tool:
+    - "npm"
+    semver: ">=8.0.0"
+  - tool:
+    - "sf"
+    semver: ">=2.130.0"
+---
+
+# create-react-storefront
+
+## What this does
+
+Deploys the **commerce-b2b-headless** reference React storefront (a React 19 + Vite `UIBundle`
+served from the Experience Cloud Site Container) into a user's B2B Commerce org and returns the
+hosted storefront URL. The repo is a *reference implementation* — it ships four org-specific
+values as `<…_Placeholder>` strings that throw at runtime until replaced. This skill's whole job
+is to resolve those four values against the target org, then drive build → deploy → guest-user
+entitlement so the storefront actually renders.
+
+The repo's `scripts/org-setup.mjs` (`npm run setup`) automates login → build → deploy → permset →
+dev-server, but it does **not** discover the WebStore, replace the placeholders, or entitle the
+site's guest user (the README's own "Limitations" say there is no auto-discovery). Those
+gaps are exactly the manual work below — do them, and the deploy is reliable.
+
+**Requires:** Node 22+, `sf` CLI 2.130+, and a target org with B2B Commerce + Multi-framework React
+enabled (API version `67.0+`). Only work against orgs the user owns or is authorized to modify — deploy,
+Apex edits, and permission-set assignment are real, side-effecting writes.
+
+## Fixed facts about the repo (don't re-derive these)
+
+| Thing | Value |
+|---|---|
+| Repo clone URL | `https://github.com/trailheadapps/commerce-b2b-headless.git` (ask for an existing clone first; a new clone goes to a user-confirmed path under the cwd — Step 3) |
+| UI Bundle dir (`$BUNDLE`) | `force-app/main/default/uiBundles/commerceb2bheadless` |
+| WebStore config file | `$BUNDLE/src/config/commerce.ts` |
+| Registration Apex | `UIBundleRegistration.cls` (in the repo's Apex classes folder) |
+| Vite config | `$BUNDLE/vite.config.ts` |
+| Auth permission set | `UIBundleApexAccess` (grants the 6 auth Apex classes) |
+| Site name | `commerceb2bheadless` — also the storefront URL path: `https://<site-domain>/commerceb2bheadless` |
+| Connect `urlPathPrefix` | `commerceb2bheadlessvforcesite` (internal match key for Step 7 — **not** the URL path) |
+| Default API version | `v67.0` (leave unless the org runs a different version) |
+
+## The four values you must set
+
+Everything else in the repo is portable. These four are environment-specific — resolve each against
+the target org, then write it into the file. Steps 4a–4d below do this.
+
+| # | Value | File / symbol | Prefix |
+|---|---|---|---|
+| 1 | WebStore Id | `commerce.ts` → `WEBSTORE_ID` | `0ZE` |
+| 2 | Default BuyerGroup Id | `UIBundleRegistration.cls` → `DEFAULT_BUYER_GROUP_ID` | `0ZI` |
+| 3 | Buyer permission set group | `UIBundleRegistration.cls` → `BUYER_PERMISSION_SET_GROUP` (DeveloperName) | — |
+| 4 | Vite org alias (optional) | `vite.config.ts` → `salesforce({ orgAlias: '…' })` | — |
+
+---
+
+## Workflow
+
+Narrow with `sf` queries before you ask the user anything, and don't ask what a query can answer.
+Two choices are always the user's to make, even when there is only one option: **which store**
+(Step 2) and **where the repo lives** (Step 3). Confirm the plan (which org, which store, what will
+be written and deployed) before the first write.
+
+### Step 1 — Resolve the target org
+
+If the user gave an org alias, use it. Otherwise list what's connected and ask which one:
+
+```bash
+sf org list --json | jq -r '.result.nonScratchOrgs[]?.alias, .result.scratchOrgs[]?.alias'
+```
+
+Confirm it's reachable: `sf org display --target-org <alias>`. If not connected, log in:
+`sf org login web --alias <alias> --instance-url https://<my-domain>.my.salesforce.com`.
+
+### Step 2 — Discover the org's WebStores, let the user pick
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Name, Type FROM WebStore WHERE Type = 'B2B' ORDER BY Name"
+```
+
+The storefront is B2B-only, so list only `Type = 'B2B'` stores. **Always ask the user which store
+to deploy against — show every B2B store by Name and let them choose, even when there is only
+one. Never pick a store on the user's behalf**, and don't fold the choice into a later plan
+confirmation: the store decides which catalog, buyer groups, and pricing the deployed storefront
+serves. Capture the chosen store's `Id` (`0ZE…`); this is **value #1** and also scopes the
+BuyerGroup lookup in Step 4b. If the query returns nothing, the org has no B2B store provisioned —
+stop and point the user at the `b2b-commerce-org-setup` plugin to create one first.
+
+### Step 3 — Ask where the repo is, or clone it
+
+**Ask the user first** — don't probe default locations or assume a path: do they already have a
+clone of `commerce-b2b-headless` (and where is it), or should you clone it from
+`https://github.com/trailheadapps/commerce-b2b-headless.git`?
+
+**Existing clone** — set `$REPO` to the path the user gives, then verify it's the right repo:
+
+```bash
+ls "$REPO/README.md" "$REPO/force-app/main/default/uiBundles/commerceb2bheadless" >/dev/null && echo OK
+```
+
+If the check fails, tell the user what's missing and ask again — don't switch to cloning unasked.
+
+**Clone** — the clone goes inside the current working directory. Check that directory's structure
+first, so the clone doesn't silently land inside another git repo or on top of an existing folder:
+
+```bash
+pwd && ls -A
+git rev-parse --show-toplevel 2>/dev/null   # prints a path ⇒ cwd is inside another git repo
+ls -d commerce-b2b-headless 2>/dev/null     # prints a name ⇒ the target folder already exists
+```
+
+Propose `$(pwd)/commerce-b2b-headless` as the clone path and call out anything the check surfaced
+(cwd is inside another repo; the folder already exists — offer to use it as the existing clone).
+If the cwd looks like the wrong place, ask the user for a path instead of proposing one. Either
+way, **wait for the user to confirm the path or give their own**. Only then clone and verify:
+
+```bash
+git clone https://github.com/trailheadapps/commerce-b2b-headless.git "<confirmed-path>"
+ls "<confirmed-path>/force-app/main/default/uiBundles/commerceb2bheadless" >/dev/null && echo OK
+```
+
+If the clone fails with "Repository not found" or an auth prompt, the user's GitHub account can't
+see the repo — don't stop; ask for a URL they can reach (e.g. their fork) or an existing local
+clone, and continue from there. Set `$REPO` to the confirmed path.
+
+Either way, the repo is a **reference implementation you adapt**, not a drop-in — the placeholder
+edits below are mandatory. Skim `$REPO/README.md` to
+confirm you're on a compatible version if anything looks different from the Fixed-facts table.
+
+### Step 4 — Fill the four org-specific values
+
+Use `Edit` to replace each placeholder in place. Do **not** deploy with any `<…Placeholder>` string
+still present — the app throws at runtime and buyers hit `INSUFFICIENT_ACCESS`.
+
+**4a — WebStore Id** → `$BUNDLE/src/config/commerce.ts`
+Replace `WEBSTORE_ID: "<Webstore_Id_Placeholder>"` with the `0ZE…` Id from Step 2.
+
+**4b — Default BuyerGroup Id** → `UIBundleRegistration.cls` `DEFAULT_BUYER_GROUP_ID`
+Prefer the BuyerGroup actually bound to the chosen store; fall back to listing all:
+
+```bash
+# Preferred — the BuyerGroup(s) entitled to this store:
+sf data query --target-org <alias> \
+  --query "SELECT BuyerGroupId, BuyerGroup.Name FROM WebStoreBuyerGroup WHERE WebStoreId = '<0ZE…>'"
+# Fallback — all BuyerGroups:
+sf data query --target-org <alias> --query "SELECT Id, Name FROM BuyerGroup"
+```
+
+If more than one, show the names and let the user pick. Replace `<Buyer_Group_Id_Placeholder>` with
+the `0ZI…` Id. New self-registered buyers get enrolled here so the store entitlement applies.
+
+**4c — Buyer permission set group** → `UIBundleRegistration.cls` `BUYER_PERMISSION_SET_GROUP`
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM PermissionSetGroup ORDER BY DeveloperName"
+```
+
+This must match the PSG the store hands buyers at **Commerce App → your store → Buyer Access →
+Self-Registration**. Show the list, let the user confirm which one, and replace
+`<Buyer_permission_set_group>` with its **DeveloperName**. Wrong/missing group ⇒ registration
+succeeds but order placement fails with `INSUFFICIENT_ACCESS`.
+
+**4d — Vite org alias (optional but recommended)** → `$BUNDLE/vite.config.ts`
+If the machine has more than one org, pin the build to this one so the SDK's CSRF endpoint matches
+the org's API version. Change `salesforce()` to `salesforce({ orgAlias: '<alias>' })`. Skipping it
+falls back to `65.0`, which mismatches newer orgs and 401s every authenticated request.
+
+### Step 5 — Build the UI Bundle, then hand off the deploy
+
+The `dist/` is what gets shipped, and the WebStore Id (Step 4a) is baked into it at build time. Build from
+inside the bundle, deleting any existing `dist/` first — if the build fails partway, a leftover
+`dist/` from an earlier build (old or placeholder values baked in) would otherwise deploy silently.
+Confirm the chosen WebStore Id made it into the bundle before deploying:
+
+```bash
+cd $REPO && npm install
+cd $BUNDLE && npm install && rm -rf dist && npm run build   # tsc -b && vite build → fresh dist/
+grep -l '<0ZE…>' dist/assets/*.js >/dev/null && echo "WebStore Id baked"
+```
+
+**Before the deploy, flag the guest Chatter setting.** The repo's metadata is a demo-org
+configuration: `force-app/main/default/networks/commerceb2bheadless.network-meta.xml` ships
+`<enableGuestChatter>true</enableGuestChatter>`, which exposes Chatter to unauthenticated guest
+users. Tell the user before deploying and offer to set it to `false`; change it only if they agree.
+On a production org (or if the user isn't sure), don't deploy until they confirm they've reviewed
+the README's "Review all org, site & network settings before production" section, which lists the
+other network, site, profile, and permission-set flags to check.
+
+#### Deploy — delegate
+
+```yaml
+id: deploy-source
+purpose: delegate
+delegates_to: experience-sites-ui-framework/experience-ui-bundle-deploy
+```
+
+The shared `experience-ui-bundle-deploy` skill owns UI Bundle deploys, so this skill keeps no deploy
+recipe of its own. Use the installed skill if this client has it; otherwise `describe`
+`experience-ui-bundle-deploy` and follow its served guidance — its helper scripts, including the
+source-root resolver, are served with it. Point it at `$REPO` as the project and `<alias>` as the
+target org, and run **only its "Deploy metadata" step** (its org-auth precondition no-ops, since
+Step 1 already connected the org). Let it resolve the source root itself. The reference repo ships
+no `org-setup.config.json`, so that step's self-registration pre-check doesn't apply.
+
+Tell the user which of its other steps you are not running, and why: its build (done above, with
+the stale-`dist/` delete it lacks), and its permission-set, role, self-registration, social-login,
+data-import, and GraphQL steps. Step 6 here entitles the guest user, and the storefront needs
+nothing else from that sequence.
+
+The deploy ships the Apex, the UIBundle (with the fresh `dist/`), the Site/Network/digitalExperiences,
+the `UIBundleApexAccess` permission set, and the buyer profile in one shot. Only if neither the
+installed skill nor a `describe` of it is available, report the deploy handoff as blocked. Tell the
+user it needs `experience-ui-bundle-deploy`, or offer the One-command alternative below as their
+choice — don't improvise a deploy.
+
+### Step 6 — Entitle the site's guest user (auth permission set)
+
+The app puts every storefront route — home, category, search, product, cart, checkout, orders,
+profile — behind login: an anonymous visitor is redirected to `/login`. So the site's **guest user**
+only ever serves the login / register / forgot-password / reset-password pages, and the one thing it
+needs is `UIBundleApexAccess` for the auth Apex classes. Find the guest user and the permset:
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id, Name, GuestUserId FROM Site WHERE Name = 'commerceb2bheadless'"
+sf data query --target-org <alias> \
+  --query "SELECT Id FROM PermissionSet WHERE Name = 'UIBundleApexAccess'"
+```
+
+Assign it (without it, `/login` 403s "no access to UIBundleLogin"):
+
+```bash
+sf data create record --target-org <alias> --sobject PermissionSetAssignment \
+  --values "AssigneeId=<GuestUserId> PermissionSetId=<UIBundleApexAccessId>"
+```
+
+A `DUPLICATE_VALUE` error means the assignment already exists from an earlier run — treat it as done.
+Either way, confirm it landed (expect one row; zero means redo the assignment):
+
+```bash
+sf data query --target-org <alias> \
+  --query "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<GuestUserId>' AND PermissionSet.Name = 'UIBundleApexAccess'"
+```
+
+**Don't give the guest user a commerce permission set** — for example, by mirroring an LWR store
+guest's permset. Anonymous browsing isn't reachable in this app, so there's nothing for it to
+unlock (and an LWR store's guest often holds no such permset). If the
+user later removes the login guard to allow guest browsing, B2B guest access is configured on the
+store — `WebStore.OptionsGuestBrowsingEnabled`, the guest buyer profile, and a guest buyer group (the
+`merchant-storefront-guest-access` skill) — and the WebStore likely also needs binding to the
+headless site's Network (`WebStoreNetwork`). That path is unverified for this app, so flag it rather
+than attempt it.
+
+### Step 7 — Resolve and hand back the hosted storefront URL
+
+The app is served at `https://<site-domain>/commerceb2bheadless`. Get the authoritative live URL from
+the Connect communities endpoint, matching on the site's internal `urlPathPrefix` (which differs from
+the URL path):
+
+```bash
+sf api request rest '/services/data/v67.0/connect/communities' --target-org <alias> \
+  | jq -r '.communities[] | select(.urlPathPrefix=="commerceb2bheadlessvforcesite") | "\(.name)\t\(.status)\t\(.siteUrl)"'
+```
+
+Report the `siteUrl` as **"here is your hosted React Storefront"**. If `status` is not `Live`, the
+site needs publishing — direct the user to **Setup → Digital Experiences → All Sites →
+commerceb2bheadless → Publish** (Experience Builder), then re-fetch the URL. If the endpoint returns
+nothing, construct the fallback `https://<my-domain>.my.site.com/commerceb2bheadless` — the path is
+the site name, not the `vforcesite` prefix. Get `<my-domain>` from `sf org display`'s instance URL;
+non-production instances use a different site-domain suffix, so tell the user to verify the URL in
+All Sites.
+
+---
+
+## One-command alternative
+
+If the four values are already set (Step 4 done), the repo's own orchestrator does build → deploy →
+permset in one go:
+
+```bash
+cd $REPO && npm run setup -- --target-org <alias> --skip-dev --skip-data
+```
+
+Caveats — it does **not** replace the placeholders and it assigns `UIBundleApexAccess` to the
+**current user**, not the guest user, so you **still** run Step 4 before it and Step 6 (the guest
+assignment) after it. Drop `--skip-dev` only if the user wants the local Vite dev server
+(`localhost:5173`) instead of / in addition to the hosted site. If the bundle has no GraphQL
+codegen wired, add `--skip-graphql`.
+
+## Troubleshooting (from the repo README)
+
+- **`/login` returns 403 "no access to UIBundleLogin"** — guest user missing `UIBundleApexAccess`; redo Step 6.
+- **Anonymous visitors land on `/login`** — by design; every storefront route requires login (Step 6). Register or log in as a buyer to browse.
+- **`/commerce/...` returns 404 from the Site Container** — org is older than API version `67.0` (no Site Container support); upgrade the org.
+- **Storefront shows no products** — the buyer's Account isn't in a BuyerGroup with active price book entries for the catalog.
+- **Every authenticated request 401s** — Vite fell back to API `65.0`; set the org alias (Step 4d) and rebuild.
+- **Order placement fails `INSUFFICIENT_ACCESS`** — wrong/missing buyer PSG (Step 4c).
+- **Storefront still shows old or placeholder values after a redeploy** — a stale `dist/` shipped; delete it and rebuild (Step 5).
+
+## Notes
+
+- **Dual-network:** the headless storefront runs on its own Network, coexisting with the legacy LWR store's Network. Both stay in the org.
+- **Don't rename** the Apex classes, `UIBundleApexAccess`, or the site URL prefix — they're cross-referenced by the React app, the permission set, and this skill's queries.
+- This is a live-org workflow: name the org, the store, and every write before doing it, and never deploy against an org the user hasn't authorized.
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `list-webstores` | read | — | `GET /services/data/v67.0/query` | — |
+| `write-webstore-id-placeholder` | write | — | — | `list-webstores` |
+| `list-buyer-groups-for-store` | read | — | `GET /services/data/v67.0/query` | `list-webstores` |
+| `list-buyer-groups-all` | read | — | `GET /services/data/v67.0/query` | `list-buyer-groups-for-store` |
+| `write-buyer-group-id-placeholder` | write | — | — | `list-buyer-groups-for-store`, `list-buyer-groups-all` |
+| `list-permission-set-groups` | read | — | `GET /services/data/v67.0/query` | — |
+| `write-psg-placeholder` | write | — | — | `list-permission-set-groups` |
+| `write-vite-org-alias` | write | — | — | — |
+| `build-ui-bundle` | write | — | — | `write-webstore-id-placeholder`, `write-buyer-group-id-placeholder`, `write-psg-placeholder`, `write-vite-org-alias` |
+| `deploy-source` | delegate | — | → `experience-sites-ui-framework/experience-ui-bundle-deploy` | `build-ui-bundle` |
+| `find-site-and-guest-user` | read | — | `GET /services/data/v67.0/query` | `deploy-source` |
+| `find-uibundleapexaccess-permset` | read | — | `GET /services/data/v67.0/query` | `deploy-source` |
+| `assign-auth-permset-to-guest` | write | — | `POST /services/data/v67.0/sobjects/PermissionSetAssignment` | `find-site-and-guest-user`, `find-uibundleapexaccess-permset` |
+| `resolve-storefront-url` | read | — | `GET /services/data/v67.0/connect/communities` | `deploy-source` |
+| `verify-guest-permset-assignment` | verify | — | `GET /services/data/v67.0/query` | `assign-auth-permset-to-guest` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->