/experience-ui-bundle-deploy

name: experience-ui-bundle-deploy
description: "MUST activate when the project has a uiBundles/*/src/ directory and the task involves deploying to an org or post-deploy org setup. Deploys a UI bundle app and runs ordered setup: org auth, build, metadata deploy, permission-set and role assignment, Experience Cloud self-registration, social login / SSO / IDP linking (Auth Providers + SAML on a React site), site logout URL, seed-data import, and GraphQL schema fetch + codegen. Trigger signals: *.network-meta.xml, org-setup.config.json (socialLogin/logoutUrl), data-plan.json, sfdx-project.json, or mentions of deploy, org setup, social login/SSO, or logout URL on an Experience site. DO NOT TRIGGER when: creating a new UI bundle project (use experience-ui-bundle-project-generate); styling pages without deploying (use experience-ui-bundle-frontend-generate); adding a feature such as auth, search, or file upload without deploying (use the matching experience-ui-bundle-*-generate skill); configuring MFA permission sets (use experience-ui-bundle-mfa-configure)."
metadata:
  version: "1.3"
  domains: ["Experience", "Developer Experience"]
  relatedSkills:
    - "experience-ui-bundle-frontend-generate"
    - "experience-ui-bundle-mfa-configure"
    - "experience-ui-bundle-project-generate"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["npm"]
      semver: ">=7.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  minApiVersion: "66.0"
allowed-tools: Bash Read Write Edit

Deploying a UI Bundle App

Deploy order is load-bearing: a step's output is the next step's precondition (deploy before schema fetch; permissions before schema fetch; role/self-reg before the schema the guest user must see). This is the canonical setup sequence, ported from the reference `org-setup.mjs`. The `org-setup.mjs` line citations in `references/` are port-provenance (why each rule exists) pointing at that external reference script — not files shipped with this skill — so you don't need to open them to run the steps.

Run each step in order. **Every optional step is presence-driven**: if its convention file is absent, no-op cleanly and move on — do not fabricate config. For the two destructive/expensive steps (self-registration, data import), **ask the user before running**.

Inputs to gather up front

Read these from the project; **ask the user** only for what's missing:

• **Target org** — alias/username for `--target-org`. Ask if not obvious.
• **Source root** — run `scripts/get-source-root.sh` to resolve the metadata

source dir from `sfdx-project.json` (`packageDirectories[0].path` + `/main/default`). It exits non-zero if the project file is missing or malformed. Never hardcode `force-app/main/default`.

• **`org-setup.config.json`** (optional) — drives permset assignment, role,

self-registration, and social login. Absent keys mean "skip that step". **Exception:** if the file is missing but `permissionsets/` has permsets to assign, don't silently skip — scaffold the config or gather equivalent inputs (see step 4).

• **`data-plan.json`** (optional, in the project's `data/` dir) — presence enables the data step.

Step 1 — Org authentication (always)

Unconditional precondition; cannot be skipped. If the org is already connected (`sf org display --target-org <org> --json` succeeds), no-op. Otherwise:

sf org login web --alias <org>

A failed login aborts the whole setup before deploy.

Step 2 — Pre-deploy UI bundle build

Build **every** UI bundle so `dist/` exists before metadata deploy (UI bundle entities deploy the built output). For each bundle dir under `uiBundles/`:

npm install
npm run build

Run when deploying UI bundles and `dist/` is missing or source changed.

Step 3 — Deploy metadata

If self-registration is configured:

1. **Deploy license pre-check first** (see `references/license-checks.md`) — it blocks the deploy with a clear, license-naming message instead of a cryptic failure. 2. **Add the self-reg profile to `networkMemberGroups`** on the local source — apply **Edit A** of `assets/network-selfreg-xml-recipe.md`. This must happen **before** this deploy so the profile ships as a recognised site member; do NOT deploy the network file on its own here (this deploy ships it). Best-effort and idempotent — skip if already a member.

Then deploy the whole project (all metadata) by pointing `--source-dir` at the resolved source root:

sf project deploy start --source-dir <sourceRoot> --target-org <org>

`<sourceRoot>` is the value from `scripts/get-source-root.sh` (e.g. `force-app/main/default`). Always pass `--source-dir`. Do NOT run bare `sf project deploy start` with no path: that command relies on source-tracking to decide what to deploy, and on an org without source-tracking (most non-scratch orgs) it aborts with *"This org does not have source-tracking enabled … specify the files or a manifest to deploy."* Passing `--source-dir` deploys the same full set on both source-tracked and non-tracked orgs and never emits that hint. If the deploy reports conflicts on a source-tracked org, re-run with `--ignore-conflicts` — do NOT roll back or reduce the deployed set.

Do NOT hand-build a `package.xml`, assemble a `--metadata-dir` mdapi zip, or otherwise convert to metadata-format — none of that is needed and it is not part of this flow.

Timeout 180s. Must complete before permission assignment and schema fetch — objects, fields, and permission sets appear in the org only after deploy.

Step 3b — Set the site logout URL (config-gated)

Run only when `org-setup.config.json` has a top-level `logoutUrl`. If absent, no-op cleanly and say so. **Non-destructive and idempotent** — no ask needed.

Runs **here, after the deploy** (not folded into it) because the platform rejects a relative logout URL (*"The logout page URL must be an absolute URL."*), and a shipped site-relati