@salesforce/webapp-template-app-react-template-b2x-experimental 1.83.0 → 1.84.1

package/dist/.a4drules/skills/{webapp-react-add-component → webapp-react}/SKILL.md

@@ -1,9 +1,11 @@
 ---
-name: webapp-react-add-component
-description: Creates React components, pages, headers, and footers using shadcn UI and Tailwind CSS. Use when the user asks to create a component, add a widget, build a UI element, add a page, create a new page, add a section (e.g. "add a contacts page"), add a header, add a footer, add a navigation bar, or add anything to the web application.
+name: webapp-react
+description: Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS).
 ---
 
-# Add React Component
+# React Web App (Components, Pages, Layout)
+
+Use this skill whenever you are editing React/TSX code in the web app (creating or modifying components, pages, header/footer, or layout).
 
 ## Step 1 — Identify the type of component
 

package/dist/.a4drules/skills/{webapp-react-add-component → webapp-react}/implementation/header-footer.md

@@ -116,6 +116,14 @@ AppLayout (appLayout.tsx)
 - **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
 - **Design tokens:** `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`
 
+### Mobile hamburger / Menu icon — Must be functional
+
+If the header includes a hamburger or `Menu` icon for mobile:
+
+- **Do not** add a Menu/hamburger icon that does nothing. It must toggle a visible mobile menu.
+- **Required:** (1) State: `const [isOpen, setIsOpen] = useState(false)`. (2) Button: `onClick={() => setIsOpen(!isOpen)}`, `aria-label="Toggle menu"`. (3) Conditional panel: `{isOpen && ( <div>...nav links...</div> )}` with responsive visibility (e.g. `md:hidden`). (4) Close on navigate: each link in the panel should `onClick={() => setIsOpen(false)}`.
+- Implement in `appLayout.tsx` (or the component that owns the header). Use the `Menu` icon from `lucide-react`.
+
 ### Confirm — Header / Footer
 
 - Header and footer appear on every page (navigate to at least two routes)

package/dist/.a4drules/skills/{webapp-react-add-component → webapp-react}/implementation/page.md

@@ -2,13 +2,14 @@
 
 ### Rules
 
-1. **`routes.tsx` is the only route registry** — never add routes in `app.tsx` or inside page files.
-2. **All pages are children of the AppLayout route** — do not create top-level routes that bypass the layout shell.
-3. **Default export per page** — each page file has exactly one default-export component.
-4. **Path aliases in all imports** — use `@/pages/...`, `@/components/...`; no deep relative paths.
-5. **No inline styles** — Tailwind utility classes and design tokens only.
-6. **Catch-all last** — `path: '*'` (NotFound) must always remain the last child in the layout route.
-7. **Never modify `appLayout.tsx`** when adding a page — layout changes are a separate concern.
+1. **Edit the component that owns the UI, never output raw HTML** — When editing the home page or any page content, modify the actual `.tsx` file that renders the target. If the target is inside a child component (e.g. `<GlobalSearchInput />` in `Home.tsx`), edit the child's file (e.g. `GlobalSearchInput.tsx`), not the parent. Do not wrap the component with extra elements in the parent; go into the component and change its JSX. Do not paste or generate raw HTML.
+2. **`routes.tsx` is the only route registry** — never add routes in `app.tsx` or inside page files.
+3. **All pages are children of the AppLayout route** — do not create top-level routes that bypass the layout shell.
+4. **Default export per page** — each page file has exactly one default-export component.
+5. **Path aliases in all imports** — use `@/pages/...`, `@/components/...`; no deep relative paths.
+6. **No inline styles** — Tailwind utility classes and design tokens only.
+7. **Catch-all last** — `path: '*'` (NotFound) must always remain the last child in the layout route.
+8. **Never modify `appLayout.tsx`** when adding a page — layout changes are a separate concern.
 
 ### Step 1 — Create the page file
 

package/dist/.a4drules/skills/webapp-ui-ux/SKILL.md

@@ -1,11 +1,13 @@
 ---
-name: ui-ux
-description: Comprehensive design guide for React + Tailwind + shadcn/ui applications. Searchable database with priority-based recommendations for styles, color palettes, font pairings, UX guidelines, and chart types.
+name: webapp-ui-ux
+description: Use when editing any UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or visual/UX changes. Comprehensive design guide and searchable database for React + Tailwind + shadcn/ui (styles, color palettes, font pairings, UX guidelines, chart types).
 ---
 
-# ui-ux
+# Web App UI/UX
 
-Comprehensive design guide for React + Tailwind + shadcn/ui applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
+Use this skill whenever you are editing UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or any visual/UX change.
+
+Comprehensive design guide for React + Tailwind + shadcn/ui. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
 
 ## Prerequisites
 
@@ -200,9 +202,10 @@ These are frequently overlooked issues that make UI look unprofessional:
 
 | Rule | Do | Don't |
 |------|----|----- |
-| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Icons: Lucide only** | Use **lucide-react** for all UI icons: `import { IconName } from 'lucide-react'` | Use Heroicons, react-icons, or other icon libraries; use emojis as icons |
+| **No emojis ever** | Use words + Lucide icons for labels, empty states, tooltips, headings | Use emojis anywhere in UI or user-facing text (e.g. 🎨 🚀 ⚙️) |
 | **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
-| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Correct brand logos** | Research official SVG from Simple Icons (when needed outside Lucide) | Guess or use incorrect logo paths |
 | **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
 
 ### Interaction & Cursor
@@ -237,8 +240,8 @@ These are frequently overlooked issues that make UI look unprofessional:
 Before delivering UI code, verify these items:
 
 ### Visual Quality
-- [ ] No emojis used as icons (use SVG instead)
-- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] No emojis anywhere (UI, labels, empty states, tooltips—use words + Lucide icons only)
+- [ ] All icons from **lucide-react** only (no Heroicons, react-icons, or emojis)
 - [ ] Brand logos are correct (verified from Simple Icons)
 - [ ] Hover states don't cause layout shift
 - [ ] Use theme colors directly (bg-primary) not var() wrapper

package/dist/.a4drules/webapp-react.md

@@ -18,6 +18,15 @@ For layout, navigation, and generation rules, see **webapp.md**.
 - Dev server: `npm run dev`
 - Build: `npm run build`
 
+## Routing (React Router)
+
+Use a **single** router package for the app. When using `createBrowserRouter` and `RouterProvider` from `react-router`, all routing imports must come from **`react-router`** — not from `react-router-dom`.
+
+- ✅ `import { createBrowserRouter, RouterProvider, Link, useNavigate, useLocation, Outlet } from 'react-router';`
+- ❌ `import { Link } from 'react-router-dom';` when the app uses `RouterProvider` from `react-router`
+
+Mixing packages causes "Cannot destructure property 'basename' of ... as it is null" because `Link`/hooks from `react-router-dom` read a different context than the one provided by `RouterProvider` from `react-router`.
+
 ## Component Library (MANDATORY)
 
 Use **shadcn/ui** for UI components:
@@ -28,6 +37,42 @@ import { Card, CardHeader, CardContent } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 ```
 
+## Icons & No Emojis (MANDATORY)
+
+- **Icons:** Use **lucide-react** only. Do not use Heroicons, Simple Icons, or other icon libraries in the web app.
+  - ✅ `import { Menu, Settings, Bell } from 'lucide-react';` then `<Menu className="w-5 h-5" />`
+  - ❌ Any emoji character as an icon or visual element (e.g. 🎨 🚀 ⚙️ 🔔)
+  - ❌ Other icon libraries (e.g. `@heroicons/react`, `react-icons`, custom SVG icon sets)
+- **No emojis ever:** Do not use emojis anywhere in the app: no emojis in UI labels, buttons, headings, empty states, tooltips, or any user-facing text. Use words and lucide-react icons instead.
+  - ✅ "Settings" with `<Settings />` icon
+  - ❌ "⚙️ Settings" or "Settings 🔧"
+- For icon usage patterns and naming, see the **webapp-ui-ux** skill (`.a4drules/skills/webapp-ui-ux/`, especially `data/icons.csv`).
+
+## Editing UI — Source Files Only (CRITICAL)
+
+When asked to edit the home page, a section, or any on-screen UI:
+
+- **Always edit the actual React/TSX source files.** Never output, paste, or generate raw HTML. The UI is built from components; the agent must locate the component file(s) that render the target area and change **JSX in those files**.
+- **Do not** replace JSX with HTML strings, and do not copy browser-rendered DOM (e.g. expanded `<div>`, `data-slot`, long class strings) into the codebase. That is the output of React + shadcn; the source is `.tsx` with `<Card>`, `<Input>`, etc.
+- **Edit inside the component that owns the UI.** If the element to change is rendered by a **child component** (e.g. `<GlobalSearchInput />` in `Home.tsx`), make the edit **inside that component's file** (e.g. `GlobalSearchInput.tsx`). Do **not** only wrap the component with extra elements in the parent (e.g. adding a `<section>` or `<div>` around `<GlobalSearchInput />`). The parent composes components; the visual/content change belongs in the component that actually renders that part of the UI.
+- **Where to edit:**
+  - **Home page content:** `src/pages/Home.tsx` — but if the target is inside a child (e.g. `<GlobalSearchInput />`), edit the child's file, not the parent.
+  - **Layout, header, nav:** `src/appLayout.tsx`.
+  - **Feature-specific UI (e.g. search, list):** open the **specific component file** that renders the target (e.g. `GlobalSearchInput.tsx` for the search input UI).
+- **Steps:** (1) Identify which **component** owns the section (follow the import: e.g. `GlobalSearchInput` → its file). (2) Open that component's file and modify the JSX there. (3) Only change the parent (e.g. `Home.tsx`) if the change is layout/ordering of components, not the internals of a child. Do not emit a standalone HTML snippet as the “edit.”
+
+## Mobile Nav / Hamburger — Must Be Functional
+
+When adding a navigation menu that includes a hamburger (or Menu icon) for mobile:
+
+- **Do not** add a hamburger/Menu icon that does nothing. The icon must **toggle a visible mobile menu**.
+- **Required implementation:**
+  1. **State:** e.g. `const [isOpen, setIsOpen] = useState(false);`
+  2. **Toggle button:** The hamburger/Menu button must have `onClick={() => setIsOpen(!isOpen)}` and `aria-label="Toggle menu"` (or equivalent).
+  3. **Conditional panel:** A mobile-only menu panel that renders when `isOpen` is true, e.g. `{isOpen && ( <div className="..."> ... nav links ... </div> )}`. Use responsive classes (e.g. `md:hidden`) so the panel is shown only on small screens if the desktop nav is separate.
+  4. **Close on navigation:** Each nav link in the mobile panel should call `onClick={() => setIsOpen(false)}` (or similar) so the menu closes when the user navigates.
+- Implement this in `appLayout.tsx` (or the component that owns the header/nav). See existing apps for the full pattern (state + button + conditional panel + link onClick).
+
 ## Styling
 
 - Use **Tailwind CSS** utility classes
@@ -137,11 +182,20 @@ window.location.reload();
 - ❌ Using LWC patterns (`@wire`, LDS) in React
 - ❌ Hardcoded Salesforce IDs or URLs
 - ❌ Missing error handling for async operations
+- ❌ Mixing `react-router` and `react-router-dom` (e.g. `RouterProvider` from `react-router` but `Link` from `react-router-dom`) — use one package for all routing imports
+- ❌ Using emojis anywhere in the app (labels, icons, empty states, headings, tooltips)
+- ❌ Using any icon library other than **lucide-react** (no Heroicons, react-icons, or emoji-as-icon)
+- ❌ Outputting or pasting raw HTML when editing UI — always edit the React/TSX source files (e.g. `Home.tsx`, `appLayout.tsx`, feature components)
+- ❌ Adding a hamburger or Menu icon for mobile nav without implementing toggle state, conditional menu panel, and close-on-navigate
 
 ## Quality Checklist
 
 - [ ] Entry point maintained (`app.tsx`)
 - [ ] Uses shadcn/ui and Tailwind
+- [ ] Icons from **lucide-react** only; no emojis anywhere in UI or user-facing text
+- [ ] UI changes made by editing .tsx source files (never by pasting raw HTML)
+- [ ] If mobile hamburger exists: it has toggle state, conditional menu panel, and close on link click
+- [ ] All routing imports from same package as router (e.g. `react-router` only)
 - [ ] DataSDK used for all Salesforce API calls
 - [ ] Proper error handling with try/catch
 - [ ] Loading and error states implemented

package/dist/AGENT.md

@@ -26,6 +26,8 @@ Used for SFDX metadata (LWC, Aura, etc.). Scripts here are for the base SFDX tem
 | `npm run prettier` | Format supported metadata files |
 | `npm run prettier:verify` | Check Prettier |
 
+**One-command setup:** From project root run `node scripts/setup-cli.mjs --target-org <alias>` to run login (if needed), deploy, optional permset/data import, GraphQL schema/codegen, web app build, and optionally the dev server. Use `node scripts/setup-cli.mjs --help` for options (e.g. `--skip-login`, `--skip-data`, `--webapp-name`).
+
 Root **does not** run the React app. The root `npm run build` is a no-op for the base SFDX project.
 
 ### 2. React web app (where you do most work)

package/dist/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.84.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.84.0...v1.84.1) (2026-03-10)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+# [1.84.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.83.0...v1.84.0) (2026-03-09)
+
+
+### Features
+
+* **template:** add setup-cli and prepare-import-unique-fields scripts ([#240](https://github.com/salesforce-experience-platform-emu/webapps/issues/240)) ([5cad14c](https://github.com/salesforce-experience-platform-emu/webapps/commit/5cad14c9be8176b2faf2429fe8e8a56383aac1ae))
+
+
+
+
+
 # [1.83.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.82.0...v1.83.0) (2026-03-09)
 
 

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.83.0",
-    "@salesforce/webapp-experimental": "^1.83.0",
+    "@salesforce/sdk-data": "^1.84.1",
+    "@salesforce/webapp-experimental": "^1.84.1",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-form": "^1.28.4",
     "class-variance-authority": "^0.7.1",
@@ -40,7 +40,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.83.0",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.84.1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/webapplication.json

@@ -2,6 +2,6 @@
   "outputDir": "dist",
   "routing": {
     "trailingSlash": "never",
-    "fallback": "/index.html"
+    "fallback": "index.html"
   }
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.83.0",
+  "version": "1.84.1",
   "description": "Base SFDX project template",
   "private": true,
   "files": [
@@ -18,7 +18,8 @@
     "test:unit:coverage": "sfdx-lwc-jest --coverage",
     "prettier": "prettier --write \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
     "prettier:verify": "prettier --check \"**/*.{cls,cmp,component,css,html,js,json,md,page,trigger,xml,yaml,yml}\"",
-    "precommit": "lint-staged"
+    "precommit": "lint-staged",
+    "setup": "node scripts/setup-cli.mjs"
   },
   "devDependencies": {
     "@lwc/eslint-plugin-lwc": "^2.0.0",

package/dist/scripts/prepare-import-unique-fields.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Updates unique fields in data JSON files so "sf data import tree" can be run
+ * repeatedly (e.g. after org already has data). Run before data import.
+ *
+ * Usage:
+ *   node scripts/prepare-import-unique-fields.js
+ *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/force-app/main/default/data
+ *
+ * Expects data dir to contain (optional) JSON files:
+ *   Contact.json (Email with unique domain per run, LastName, FirstName, Phone — standard Contact)
+ *   Agent__c.json (License_Number__c — unique per record)
+ *   Property_Management_Company__c.json (Company_Code__c, max 10 chars)
+ *   Property_Owner__c.json (Email__c)
+ * Missing files are skipped. Customize this script for your app's objects/fields.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// When run from project root: scripts/prepare-import-unique-fields.js → data dir under force-app
+const DEFAULT_DATA_DIR = path.resolve(__dirname, '..', 'force-app/main/default/data');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let dataDir = DEFAULT_DATA_DIR;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--data-dir' && args[i + 1]) {
+      dataDir = path.resolve(args[++i]);
+      break;
+    }
+  }
+  return dataDir;
+}
+
+const dataDir = parseArgs();
+const runId = Date.now();
+const runSuffix2 = String(runId % 100).padStart(2, '0'); // 00-99 for Company_Code__c (10-char limit)
+
+// Contact: Email (unique domain + local), LastName, FirstName, Phone — avoid duplicate rules
+const contactPath = path.join(dataDir, 'Contact.json');
+if (fs.existsSync(contactPath)) {
+  let contact = JSON.parse(fs.readFileSync(contactPath, 'utf8'));
+  if (contact.records) {
+    contact.records.forEach((r, i) => {
+      if (r.Email && r.Email.includes('@')) {
+        const parts = r.Email.replace(/\+[0-9]+@/, '@').split('@');
+        const local = (parts[0] || 'user') + '+' + runId;
+        const domain = 'run' + runId + '.example.com';
+        r.Email = local + '@' + domain;
+      }
+      if (r.LastName)
+        r.LastName = String(r.LastName).replace(/-[0-9]+$/, '') + '-' + runId;
+      if (r.FirstName)
+        r.FirstName = String(r.FirstName).replace(/-[0-9]+$/, '') + '-' + (i + 1);
+      if (r.Phone)
+        r.Phone = String(r.Phone).replace(/\d{2}$/, runSuffix2);
+    });
+    fs.writeFileSync(contactPath, JSON.stringify(contact, null, 2));
+    console.log('Updated Contact.json (Email, LastName, FirstName, Phone)');
+  }
+}
+
+// Agent__c: License_Number__c — unique per record (field is often unique in org)
+const agentPath = path.join(dataDir, 'Agent__c.json');
+if (fs.existsSync(agentPath)) {
+  let agent = JSON.parse(fs.readFileSync(agentPath, 'utf8'));
+  if (agent.records) {
+    agent.records.forEach((r, i) => {
+      if (r.License_Number__c) {
+        const base = r.License_Number__c.replace(/-[0-9]+(-[0-9]+)?$/, '');
+        r.License_Number__c = base + '-' + runId + '-' + (i + 1);
+      }
+    });
+    fs.writeFileSync(agentPath, JSON.stringify(agent, null, 2));
+    console.log('Updated Agent__c.json (License_Number__c)');
+  }
+}
+
+// Property_Management_Company__c: Company_Code__c — max 10 chars, use 8-char base + 2-digit suffix
+const companyPath = path.join(dataDir, 'Property_Management_Company__c.json');
+if (fs.existsSync(companyPath)) {
+  let company = JSON.parse(fs.readFileSync(companyPath, 'utf8'));
+  if (company.records) {
+    company.records.forEach((r) => {
+      if (r.Company_Code__c)
+        r.Company_Code__c = r.Company_Code__c.slice(0, 8) + runSuffix2;
+    });
+    fs.writeFileSync(companyPath, JSON.stringify(company, null, 2));
+    console.log('Updated Property_Management_Company__c.json (Company_Code__c)');
+  }
+}
+
+// Property_Owner__c: Email__c — add +runId before @
+const ownerPath = path.join(dataDir, 'Property_Owner__c.json');
+if (fs.existsSync(ownerPath)) {
+  let owner = JSON.parse(fs.readFileSync(ownerPath, 'utf8'));
+  if (owner.records) {
+    owner.records.forEach((r) => {
+      if (r.Email__c && r.Email__c.includes('@'))
+        r.Email__c = r.Email__c.replace(/\+[0-9]+@/, '@').replace('@', '+' + runId + '@');
+    });
+    fs.writeFileSync(ownerPath, JSON.stringify(owner, null, 2));
+    console.log('Updated Property_Owner__c.json (Email__c)');
+  }
+}
+
+console.log('Unique fields updated: runId=%s companySuffix=%s', runId, runSuffix2);

package/dist/scripts/setup-cli.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * One-command setup: login, deploy, optional permset/data, GraphQL schema/codegen, web app build.
+ * Use this script to make setup easier for each app generated from this template.
+ *
+ * Usage:
+ *   node scripts/setup-cli.mjs --target-org <alias>   # run all steps
+ *   node scripts/setup-cli.mjs --target-org afv5 --skip-login
+ *   node scripts/setup-cli.mjs --target-org afv5 --skip-data --skip-webapp-build
+ *   node scripts/setup-cli.mjs --target-org myorg --webapp-name my-app
+ *
+ * Steps (in order):
+ *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
+ *   2. deploy    — sf project deploy start --target-org <alias>
+ *   3. permset   — sf org assign permset (skip with --skip-permset; name via --permset-name)
+ *   4. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
+ *   5. graphql   — (in webapp) npm run graphql:schema then npm run graphql:codegen
+ *   6. webapp    — (in webapp) npm install && npm run build
+ *   7. dev       — (in webapp) npm run dev — launch dev server (skip with --skip-dev)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, existsSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const WEBAPPLICATIONS_DIR = resolve(ROOT, 'force-app/main/default/webapplications');
+const DATA_DIR = resolve(ROOT, 'force-app/main/default/data');
+const DATA_PLAN = resolve(ROOT, 'force-app/main/default/data/data-plan.json');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let targetOrg = null;
+  let webappName = null;
+  let permsetName = 'Property_Management_Access';
+  const flags = {
+    skipLogin: false,
+    skipDeploy: false,
+    skipPermset: false,
+    skipData: false,
+    skipGraphql: false,
+    skipWebappBuild: false,
+    skipDev: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--target-org' && args[i + 1]) {
+      targetOrg = args[++i];
+    } else if (args[i] === '--webapp-name' && args[i + 1]) {
+      webappName = args[++i];
+    } else if (args[i] === '--permset-name' && args[i + 1]) {
+      permsetName = args[++i];
+    } else if (args[i] === '--skip-login') flags.skipLogin = true;
+    else if (args[i] === '--skip-deploy') flags.skipDeploy = true;
+    else if (args[i] === '--skip-permset') flags.skipPermset = true;
+    else if (args[i] === '--skip-data') flags.skipData = true;
+    else if (args[i] === '--skip-graphql') flags.skipGraphql = true;
+    else if (args[i] === '--skip-webapp-build') flags.skipWebappBuild = true;
+    else if (args[i] === '--skip-dev') flags.skipDev = true;
+    else if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Setup CLI — one-command setup for apps in this project
+
+Usage:
+  node scripts/setup-cli.mjs --target-org <alias> [options]
+
+Required:
+  --target-org <alias>   Target Salesforce org alias (e.g. myorg)
+
+Options:
+  --webapp-name <name>   Web app folder name under webapplications/ (default: auto-detect)
+  --permset-name <name>  Permission set to assign (default: Property_Management_Access)
+  --skip-login           Skip login step (login is auto-skipped if org is already connected)
+  --skip-deploy          Do not deploy metadata
+  --skip-permset         Do not assign permission set
+  --skip-data            Do not prepare data or run data import
+  --skip-graphql         Do not fetch schema or run GraphQL codegen
+  --skip-webapp-build    Do not npm install / build the web application
+  --skip-dev             Do not launch the dev server at the end
+  -h, --help             Show this help
+`);
+      process.exit(0);
+    }
+  }
+  if (!targetOrg) {
+    console.error('Error: --target-org <alias> is required.');
+    process.exit(1);
+  }
+  return { targetOrg, webappName, permsetName, ...flags };
+}
+
+function discoverWebappDir(webappName) {
+  if (webappName) {
+    const dir = resolve(WEBAPPLICATIONS_DIR, webappName);
+    if (!existsSync(dir)) {
+      console.error(`Error: Web app directory not found: ${dir}`);
+      process.exit(1);
+    }
+    return dir;
+  }
+  if (!existsSync(WEBAPPLICATIONS_DIR)) {
+    console.error(`Error: webapplications directory not found: ${WEBAPPLICATIONS_DIR}`);
+    process.exit(1);
+  }
+  const entries = readdirSync(WEBAPPLICATIONS_DIR, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+  if (dirs.length === 0) {
+    console.error(`Error: No web app folder found under ${WEBAPPLICATIONS_DIR}`);
+    process.exit(1);
+  }
+  if (dirs.length > 1) {
+    console.log(`Multiple web apps found; using first: ${dirs[0].name}`);
+  }
+  return resolve(WEBAPPLICATIONS_DIR, dirs[0].name);
+}
+
+function isOrgConnected(targetOrg) {
+  const result = spawnSync('sf', ['org', 'display', '--target-org', targetOrg, '--json'], {
+    cwd: ROOT,
+    stdio: 'pipe',
+    shell: true,
+  });
+  return result.status === 0;
+}
+
+function run(name, cmd, args, opts = {}) {
+  const { cwd = ROOT, optional = false } = opts;
+  console.log('\n---', name, '---');
+  const result = spawnSync(cmd, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: true,
+    ...(opts.timeout && { timeout: opts.timeout }),
+  });
+  if (result.status !== 0 && !optional) {
+    console.error(`\nSetup failed at step: ${name}`);
+    process.exit(result.status ?? 1);
+  }
+  return result;
+}
+
+function main() {
+  const {
+    targetOrg,
+    webappName,
+    permsetName,
+    skipLogin,
+    skipDeploy,
+    skipPermset,
+    skipData,
+    skipGraphql,
+    skipWebappBuild,
+    skipDev,
+  } = parseArgs();
+
+  const webappDir = discoverWebappDir(webappName);
+  const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
+  const doData = !skipData && hasDataPlan;
+
+  console.log('Setup — target org:', targetOrg, '| web app:', webappDir);
+  console.log(
+    'Steps: login=%s deploy=%s permset=%s data=%s graphql=%s webapp=%s dev=%s',
+    !skipLogin,
+    !skipDeploy,
+    !skipPermset,
+    doData,
+    !skipGraphql,
+    !skipWebappBuild,
+    !skipDev
+  );
+  if (skipData && hasDataPlan) {
+    console.log('(Data dir present; use without --skip-data to run data import.)');
+  } else if (!hasDataPlan && !skipData) {
+    console.log('(No data plan found; skipping data step.)');
+  }
+
+  if (!skipLogin) {
+    if (isOrgConnected(targetOrg)) {
+      console.log('\n--- Login ---');
+      console.log(`Org ${targetOrg} is already authenticated; skipping browser login.`);
+    } else {
+      run('Login (browser)', 'sf', ['org', 'login', 'web', '--alias', targetOrg], { optional: true });
+    }
+  }
+
+  if (!skipDeploy) {
+    run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
+      timeout: 180000,
+    });
+  }
+
+  if (!skipPermset && permsetName) {
+    console.log('\n--- Assign permission set ---');
+    const permsetResult = spawnSync(
+      'sf',
+      ['org', 'assign', 'permset', '--name', permsetName, '--target-org', targetOrg],
+      {
+        cwd: ROOT,
+        stdio: 'pipe',
+        shell: true,
+      }
+    );
+    if (permsetResult.status === 0) {
+      console.log('Permission set assigned.');
+    } else {
+      const out =
+        (permsetResult.stderr?.toString() || '') + (permsetResult.stdout?.toString() || '');
+      if (out.includes('Duplicate') && out.includes('PermissionSet')) {
+        console.log('Permission set already assigned; skipping.');
+      } else if (out.includes('not found') && out.includes('target org')) {
+        console.log(`Permission set "${permsetName}" not in org; skipping.`);
+      } else {
+        process.stdout.write(permsetResult.stdout?.toString() || '');
+        process.stderr.write(permsetResult.stderr?.toString() || '');
+        console.error('\nSetup failed at step: Assign permission set');
+        process.exit(permsetResult.status ?? 1);
+      }
+    }
+  }
+
+  if (doData) {
+    // Prepare data for uniqueness (run before import so repeat imports don't conflict)
+    const prepareScript = resolve(__dirname, 'prepare-import-unique-fields.js');
+    run('Prepare data (unique fields)', 'node', [prepareScript, '--data-dir', DATA_DIR], {
+      cwd: ROOT,
+    });
+    // Data import tree: if only DUPLICATES_DETECTED (org duplicate rules), warn and continue
+    console.log('\n--- Data import tree ---');
+    const importResult = spawnSync(
+      'sf',
+      ['data', 'import', 'tree', '--plan', DATA_PLAN, '--target-org', targetOrg, '--json'],
+      { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 120000 }
+    );
+    const out = (importResult.stdout?.toString() || '') + (importResult.stderr?.toString() || '');
+    if (importResult.status !== 0) {
+      let onlyDuplicates = false;
+      try {
+        const j = JSON.parse(out);
+        const errors = Array.isArray(j?.data) ? j.data : [];
+        onlyDuplicates =
+          errors.length > 0 &&
+          errors.every((e) => e.StatusCode === 'DUPLICATES_DETECTED' || e.statusCode === 'DUPLICATES_DETECTED');
+      } catch (_) {
+        onlyDuplicates = out.includes('DUPLICATES_DETECTED') && /Use one of these records\?/.test(out);
+      }
+      if (onlyDuplicates) {
+        console.warn(
+          'Data import hit org duplicate rules (e.g. Contact). Skipping import; rest of setup continues.'
+        );
+      } else {
+        process.stdout.write(importResult.stdout?.toString() || '');
+        process.stderr.write(importResult.stderr?.toString() || '');
+        console.error('\nSetup failed at step: Data import tree');
+        process.exit(importResult.status ?? 1);
+      }
+    }
+  }
+
+  if (!skipGraphql || !skipWebappBuild) {
+    run('Web app npm install', 'npm', ['install'], { cwd: webappDir });
+  }
+
+  if (!skipGraphql) {
+    run('Set default org for schema', 'sf', ['config', 'set', 'target-org', targetOrg, '--global']);
+    run('GraphQL schema (introspect)', 'npm', ['run', 'graphql:schema'], { cwd: webappDir });
+    run('GraphQL codegen', 'npm', ['run', 'graphql:codegen'], { cwd: webappDir });
+  }
+
+  if (!skipWebappBuild) {
+    run('Web app build', 'npm', ['run', 'build'], { cwd: webappDir });
+  }
+
+  console.log('\n--- Setup complete ---');
+
+  if (!skipDev) {
+    console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
+    run('Dev server', 'npm', ['run', 'dev'], { cwd: webappDir });
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-app-react-template-b2x-experimental",
-  "version": "1.83.0",
+  "version": "1.84.1",
   "description": "Base reference app template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",