/experience-ui-bundle-deploy

name: experience-ui-bundle-deploy
description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves deploying, pushing to an org, or post-deploy org setup. Use this skill to deploy a UI bundle app to a Salesforce org and run the full ordered setup: org authentication, pre-deploy build, metadata deploy, permission-set assignment, role assignment, Experience Cloud self-registration, seed-data import, and GraphQL schema fetch plus codegen. Activate when a uiBundles/ project also has files like *.network-meta.xml, org-setup.config.json, a data-plan.json in the data/ dir, or sfdx-project.json and the user mentions deploying, pushing, org setup, or post-deploy tasks. DO NOT TRIGGER when: creating a new UI bundle project from scratch (use experience-ui-bundle-project-generate); styling or editing pages in an existing app without deploying (use experience-ui-bundle-frontend-generate); adding a specific feature such as auth, search, or file upload without deploying (use the matching experience-ui-bundle-*-generate skill)."
metadata:
  version: "1.1"
  relatedSkills:
    - "experience-ui-bundle-frontend-generate"
    - "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, and

self-registration. 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 4 — Assign permission sets

Discover permission sets under `<packageDir>/main/default/permissionsets/`. If none exist and none were passed explicitly, skip.

**If permsets exist but `org-setup.config.json` is missing, do NOT silently skip.** A missing config makes every discovered permset resolve to `skip`, so nothing gets assigned and the later GraphQL schema comes back incomplete (the caller lacks FLS). Instead, help the user supply the assignments — either scaffold `org-setup.config.j