@salesforce/templates 66.13.5 → 66.13.7

package/lib/templates/project/reactinternalapp/scripts/org-setup.mjs

@@ -5,19 +5,21 @@
  *
  * Usage:
  *   node scripts/org-setup.mjs --target-org <alias>           # interactive step picker (all selected)
+ *   node scripts/org-setup.mjs                                # prompt to pick an authenticated org
  *   node scripts/org-setup.mjs --target-org <alias> --yes     # skip picker, run all steps
- *   node scripts/org-setup.mjs --target-org afv5 --skip-login
  *   node scripts/org-setup.mjs --target-org afv5 --skip-data --skip-ui-bundle-build
  *   node scripts/org-setup.mjs --target-org myorg --ui-bundle-name my-app
  *
+ * Login is an unconditional precondition (not a toggleable step); the dev server
+ * is launched separately via `npm run dev:preview` (scripts/org-setup-dev.mjs).
+ *
  * Steps (in order):
- *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
- *   2. uiBundle  — (all UI bundles) npm install && npm run build so dist exists for deploy (skip with --skip-ui-bundle-build)
- *   3. deploy    — sf project deploy start --target-org <alias> (requires dist for entity deployment)
- *   4. permset   — assign permsets per org-setup.config.json (skip with --skip-permset; override via --permset-name)
- *   5. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
- *   6. graphql   — (in UI bundle) npm run graphql:schema then npm run graphql:codegen
- *   7. dev       — (in UI bundle) npm run dev — launch dev server (skip with --skip-dev)
+ *   login (precondition) — sf org login web only if org not already connected; always runs before deploy
+ *   1. uiBundle  — (all UI bundles) npm install && npm run build so dist exists for deploy (skip with --skip-ui-bundle-build)
+ *   2. deploy    — sf project deploy start --target-org <alias> (requires dist for entity deployment)
+ *   3. permset   — assign permsets per org-setup.config.json (skip with --skip-permset; override via --permset-name)
+ *   4. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
+ *   5. graphql   — (in UI bundle) npm run graphql:schema then npm run graphql:codegen
  *
  * Permset assignment config (scripts/org-setup.config.json):
  *   {
@@ -37,11 +39,39 @@
  */
 
 import { spawnSync, spawn as nodeSpawn } from 'node:child_process';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readdirSync, existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import {
+  readdirSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  openSync,
+  closeSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
 
 import { validateConfig } from './org-setup-config-schema.mjs';
+import {
+  addProfileToMemberGroups,
+  enableSelfRegInXml,
+  NetworkXmlError,
+} from './org-setup-xml.mjs';
+import {
+  discoverAllUIBundleDirs as discoverAllUIBundleDirsIn,
+  discoverUIBundleDir as discoverUIBundleDirIn,
+  resolveTargetOrg,
+  evaluateLicenseRows,
+  validateProfileNameForSoql,
+  validateSoqlName,
+  validateApiName,
+  escapeSoqlString,
+  parseApexInsertResults,
+  planApexBatches,
+} from './org-setup-utils.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
@@ -53,6 +83,149 @@ const ROOT = resolve(__dirname, '..');
  */
 class StepError extends Error {}
 
+const APEX_TMP_PREFIX = 'org-setup-';
+// Legacy fixed-name temp files that older versions of this script wrote to ROOT
+// and could leave behind on a hard kill. Swept at startup for backward cleanup.
+const LEGACY_ROOT_TMP_FILES = ['.tmp-setup-selfreg.apex', '.tmp-setup-delete.apex'];
+
+/**
+ * Remove leftover Apex temp artifacts from a prior hard-killed run (cleanup AT
+ * START). Two sources: per-run dirs under os.tmpdir() created by
+ * withApexTempDir, and legacy fixed-name files this script used to write to
+ * ROOT. Best-effort: a failure to remove one entry never blocks setup.
+ *
+ * Scoped to DIRECTORY entries only: the per-run artifacts are dirs created by
+ * withApexTempDir via mkdtempSync, whereas the per-org lock files share the same
+ * `org-setup-` prefix but are plain files (`org-setup-lock-<org>.lock`). Sweeping
+ * files too would delete a live run's lock before acquireOrgLock could see it,
+ * defeating the concurrency guard. The dir sweep is still intentionally broad
+ * across PIDs; the per-target-org lock acquired in main() is what makes that
+ * safe — only one live run per org.
+ */
+function sweepStaleApexTempDirs() {
+  const base = tmpdir();
+  let entries = [];
+  try {
+    entries = readdirSync(base, { withFileTypes: true });
+  } catch {
+    /* tmpdir unreadable — nothing to sweep */
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith(APEX_TMP_PREFIX)) {
+      try {
+        rmSync(join(base, entry.name), { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+  for (const legacy of LEGACY_ROOT_TMP_FILES) {
+    const p = resolve(ROOT, legacy);
+    if (existsSync(p)) {
+      try {
+        rmSync(p, { force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}
+
+/**
+ * Run `fn(writeApex)` with a private temp dir under os.tmpdir() that is ALWAYS
+ * removed afterwards (cleanup IN FINALLY), even when fn throws or
+ * the spawned Apex step fails. `writeApex(basename, contents)` writes a file in
+ * that dir and returns its absolute path. Replaces the old fixed-name
+ * `.tmp-setup-*.apex` files in ROOT, which collided across concurrent runs and
+ * leaked on throw.
+ */
+function withApexTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), APEX_TMP_PREFIX));
+  try {
+    return fn((basename, contents) => {
+      const p = join(dir, basename);
+      writeFileSync(p, contents);
+      return p;
+    });
+  } finally {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+/** Filesystem-safe lock path for a target org. */
+function orgLockPath(targetOrg) {
+  const safe = String(targetOrg).replace(/[^a-zA-Z0-9._-]/g, '_');
+  return join(tmpdir(), `org-setup-lock-${safe}.lock`);
+}
+
+/**
+ * Liveness probe: signal 0 throws ESRCH if the pid is gone, EPERM if it exists
+ * but we can't signal it (still alive, owned by another user).
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+/**
+ * Acquire a single-host advisory per-target-org lock. If a LIVE
+ * run already holds it, exit early with a clear message rather than interleaving
+ * destructive Apex (deletes/imports) against the same org. A lock left by a
+ * hard-killed run (dead pid) is reclaimed. Different-org runs use different lock
+ * files and proceed in parallel.
+ *
+ * Released via process.on('exit') — NOT a finally block — because main() exits
+ * through process.exit() (the runStep fail-fast path, the end-of-run summary,
+ * and the top-level .catch), and process.exit() does not run finally blocks.
+ */
+function acquireOrgLock(targetOrg) {
+  const lockPath = orgLockPath(targetOrg);
+  if (existsSync(lockPath)) {
+    const holder = Number(readFileSync(lockPath, 'utf8').trim());
+    if (holder && isProcessAlive(holder)) {
+      console.error(
+        `\nAnother org-setup run (pid ${holder}) is already targeting "${targetOrg}".\n` +
+          `Wait for it to finish, or if it was killed, remove ${lockPath} and retry.`,
+      );
+      process.exit(1);
+    }
+    // Stale lock (holder dead / hard-killed) — reclaim it.
+    rmSync(lockPath, { force: true });
+  }
+  // O_EXCL ('wx') create closes the check-then-write race between two
+  // near-simultaneous runs: the loser gets EEXIST.
+  let fd;
+  try {
+    fd = openSync(lockPath, 'wx');
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      console.error(
+        `\nAnother org-setup run just acquired the lock for "${targetOrg}". Retry shortly.`,
+      );
+      process.exit(1);
+    }
+    throw e;
+  }
+  writeFileSync(fd, String(process.pid));
+  closeSync(fd);
+
+  process.on('exit', () => {
+    try {
+      rmSync(lockPath, { force: true });
+    } catch {
+      /* best effort */
+    }
+  });
+}
+
 /**
  * npm strips .gitignore from published packages — generate them on first run.
  * Templates are stored in scripts/gitignore-templates.json (generated at build
@@ -107,7 +280,6 @@ function parseArgs() {
   const permsetNamesExplicit = [];
   let yes = false;
   const flags = {
-    skipLogin: false,
     skipDeploy: false,
     skipPermset: false,
     skipRole: false,
@@ -115,7 +287,7 @@ function parseArgs() {
     skipGraphql: false,
     skipUIBundleBuild: false,
     skipSelfReg: false,
-    skipDev: false,
+    skipSocialLogin: false,
   };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--target-org' && args[i + 1]) {
@@ -124,39 +296,44 @@ function parseArgs() {
       uiBundleName = args[++i];
     } else if (args[i] === '--permset-name' && args[i + 1]) {
       permsetNamesExplicit.push(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-deploy') flags.skipDeploy = true;
     else if (args[i] === '--skip-permset') flags.skipPermset = true;
     else if (args[i] === '--skip-role') flags.skipRole = true;
     else if (args[i] === '--skip-data') flags.skipData = true;
     else if (args[i] === '--skip-self-reg') flags.skipSelfReg = true;
+    else if (args[i] === '--skip-social-login') flags.skipSocialLogin = true;
     else if (args[i] === '--skip-graphql') flags.skipGraphql = true;
     else if (args[i] === '--skip-ui-bundle-build') flags.skipUIBundleBuild = true;
-    else if (args[i] === '--skip-dev') flags.skipDev = true;
-    else if (args[i] === '--yes' || args[i] === '-y') yes = true;
+    // --skip-login and --skip-dev are retired: login is now an unconditional
+    // precondition and the dev step moved to `npm run dev:preview`.
+    // Accept them silently as no-ops so existing invocations don't hard-error.
+    else if (args[i] === '--skip-login' || args[i] === '--skip-dev') {
+      /* no-op (retired flag) */
+    } else if (args[i] === '--yes' || args[i] === '-y') yes = true;
     else if (args[i] === '--help' || args[i] === '-h') {
       console.log(`
 Setup CLI — one-command setup for apps in this project
 
 Usage:
-  node scripts/org-setup.mjs --target-org <alias> [options]
-
-Required:
-  --target-org <alias>   Target Salesforce org alias (e.g. myorg)
+  node scripts/org-setup.mjs [--target-org <alias>] [options]
 
 Options:
+  --target-org <alias>   Target Salesforce org alias (e.g. myorg). If omitted, you
+                         are prompted to pick from authenticated orgs (or the
+                         default org is used when not running interactively).
   --ui-bundle-name <name> UI bundle folder name under uiBundles/ (default: auto-detect)
   --permset-name <name>  Assign only this permission set (repeatable). Default: all sets under permissionsets/
-  --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-social-login    Do not enable social login (auth providers + community profile)
   --skip-data            Do not prepare data or run data import
   --skip-graphql         Do not fetch schema or run GraphQL codegen
   --skip-ui-bundle-build Do not npm install / build the UI bundle
-  --skip-dev             Do not launch the dev server at the end
   -y, --yes              Skip interactive step picker; run all enabled steps immediately
   -h, --help             Show this help
 
+To launch the dev server after setup, run:  npm run dev:preview
+
 Permset config (scripts/org-setup.config.json):
   Control per-permset assignment via a config file. Example:
     {
@@ -176,41 +353,22 @@ Permset config (scripts/org-setup.config.json):
       process.exit(0);
     }
   }
-  if (!targetOrg) {
-    console.error('Error: --target-org <alias> is required.');
-    process.exit(1);
-  }
+  // NOTE: no hard-exit on a missing --target-org here. Resolution is
+  // deferred to resolveTargetOrg(), which either prompts (TTY) or falls back to
+  // the default org / exits with a clear message (non-TTY).
   return { targetOrg, uiBundleName, permsetNamesExplicit, yes, ...flags };
 }
 
+// Bundle discovery lives in org-setup-utils.mjs so org-setup-dev.mjs shares it verbatim.
+// These thin wrappers bind the shared helpers to this script's UIBUNDLES_DIR and
+// keep the existing call-site signatures. discoverUIBundleDir carries the
+// multi-bundle acknowledgment (TTY picker / non-TTY warning).
 function discoverAllUIBundleDirs(uiBundleName) {
-  if (!existsSync(UIBUNDLES_DIR)) {
-    console.error(`Error: uiBundles directory not found: ${UIBUNDLES_DIR}`);
-    process.exit(1);
-  }
-  const entries = readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
-  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
-  if (dirs.length === 0) {
-    console.error(`Error: No UI bundle folder found under ${UIBUNDLES_DIR}`);
-    process.exit(1);
-  }
-  if (uiBundleName) {
-    const requested = dirs.find((d) => d.name === uiBundleName);
-    if (!requested) {
-      console.error(`Error: UI bundle directory not found: ${uiBundleName}`);
-      process.exit(1);
-    }
-    return [resolve(UIBUNDLES_DIR, requested.name)];
-  }
-  return dirs.map((d) => resolve(UIBUNDLES_DIR, d.name));
+  return discoverAllUIBundleDirsIn(UIBUNDLES_DIR, uiBundleName);
 }
 
 function discoverUIBundleDir(uiBundleName) {
-  const all = discoverAllUIBundleDirs(uiBundleName);
-  if (all.length > 1 && !uiBundleName) {
-    console.log(`Multiple UI bundles found; using first: ${all[0].split(/[/\\]/).pop()}`);
-  }
-  return all[0];
+  return discoverUIBundleDirIn(UIBUNDLES_DIR, uiBundleName);
 }
 
 /** API names from permissionsets/*.permissionset-meta.xml in the first package directory. */
@@ -254,7 +412,7 @@ function loadValidatedConfig() {
 /**
  * Derive the site name from the single networks/<siteName>.network-meta.xml the
  * app ships. An app ships exactly one site, so the site name is derivable from
- * deployed metadata rather than restated per-assignment (spec §5.2). Returns
+ * deployed metadata rather than restated per-assignment. Returns
  * null when there is no networks dir or no .network-meta.xml file.
  */
 function deriveSiteName() {
@@ -271,7 +429,15 @@ function deriveSiteName() {
       `cannot derive guest site: multiple network metadata files found in ${networksDir} (${files.join(', ')}); guestUser assignment requires exactly one`,
     );
   }
-  return files[0].replace(/\.network-meta\.xml$/, '');
+  const siteName = files[0].replace(/\.network-meta\.xml$/, '');
+  // The site name is interpolated into SOQL (Network lookup, guest-user lookup),
+  // so validate it here — the single chokepoint both callers pass through. Its
+  // source is the metadata filename, not org-setup.config.json, so point the fix
+  // there.
+  validateSoqlName(siteName, 'site name', {
+    remediation: `the networks/<siteName>.network-meta.xml filename (currently "${files[0]}")`,
+  });
+  return siteName;
 }
 
 /**
@@ -335,7 +501,7 @@ function loadRoleConfig(config) {
 /**
  * Self-registration config, read from the already-validated config. The site is
  * NOT stored here — it is derived from the single
- * networks/<siteName>.network-meta.xml the app ships (spec §5.2), exactly like
+ * networks/<siteName>.network-meta.xml the app ships, exactly like
  * the guestUser permset path. deriveSiteName() is called lazily inside the
  * selfReg step body so its "multiple network files" StepError is recorded in
  * the ledger rather than escaping config load.
@@ -359,6 +525,435 @@ function loadSelfRegConfig(config) {
   };
 }
 
+/**
+ * Social login config, read from the already-validated config.
+ *
+ * Config shape:
+ *   {
+ *     "socialLogin": {
+ *       "communityMemberProfile": "Customer Community User",
+ *       "authProviderNames": ["Google", "Facebook", "My_SAML_Provider"],
+ *       "communityUserPermset": "myapp_Guest_User_Api_Access"   // optional
+ *     }
+ *   }
+ *
+ * - communityMemberProfile: profile added to NetworkMemberGroup (required for access)
+ * - authProviderNames: DeveloperNames of AuthProvider (OAuth) or SamlSsoConfig (SAML) records to link to site
+ * - communityUserPermset: permset assigned to community users so getCurrentUser()
+ *   works (requires PermissionsApiEnabled for /chatter/users/me via /sf/api/)
+ *
+ * Returns null if no "socialLogin" section exists in config (the step is hidden).
+ */
+function loadSocialLoginConfig(config) {
+  const section = config.socialLogin;
+  if (!section) return null;
+  return {
+    communityMemberProfile: section.communityMemberProfile,
+    authProviderNames: section.authProviderNames,
+    communityUserPermset: section.communityUserPermset || null,
+  };
+}
+
+/**
+ * Enable the "Allow using standard external profiles for self-registration,
+ * user creation, and login" org setting via Metadata API deploy.
+ *
+ * This setting is required for SSO registration handlers to create users with
+ * standard community profiles (e.g. "Customer Community User"). Without it,
+ * auth providers return FIELD_INTEGRITY_EXCEPTION on user insert.
+ *
+ * The correct metadata field is `enableOotbProfExtUserOpsEnable` in
+ * CommunitiesSettings. The REST/Tooling API approaches also fail on many
+ * org types. Deploying via Metadata API is the most reliable method.
+ */
+function enableExternalProfiles(targetOrg) {
+  const dir = mkdtempSync(join(tmpdir(), APEX_TMP_PREFIX));
+  try {
+    // Create a minimal sfdx project with just the Communities setting
+    const settingsDir = join(dir, 'force-app', 'main', 'default', 'settings');
+    mkdirSync(settingsDir, { recursive: true });
+
+    writeFileSync(join(dir, 'sfdx-project.json'), JSON.stringify({
+      packageDirectories: [{ path: 'force-app', default: true }],
+      sourceApiVersion: '68.0',
+    }));
+
+    writeFileSync(join(settingsDir, 'Communities.settings-meta.xml'), [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<CommunitiesSettings xmlns="http://soap.sforce.com/2006/04/metadata">',
+      '    <enableOotbProfExtUserOpsEnable>true</enableOotbProfExtUserOpsEnable>',
+      '</CommunitiesSettings>',
+    ].join('\n'));
+
+    const result = spawnSync('sf', [
+      'project', 'deploy', 'start',
+      '--target-org', targetOrg,
+      '--source-dir', join(dir, 'force-app'),
+      '--json',
+    ], { cwd: dir, stdio: 'pipe', shell: true, timeout: 120000 });
+
+    const out = result.stdout?.toString() || '';
+    let deployResult;
+    try { deployResult = JSON.parse(out); } catch { deployResult = null; }
+
+    if (deployResult?.status === 0 || deployResult?.result?.status === 'Succeeded') {
+      console.log('  Enabled "Allow using standard external profiles" org setting.');
+    } else {
+      // Check if it failed because the setting is already enabled or not deployable
+      const errMsg = deployResult?.message || deployResult?.result?.details?.componentFailures?.[0]?.problem || '';
+      if (errMsg.includes('already') || errMsg.includes('enableOotbProfExtUserOpsEnable')) {
+        console.log('  Warning: could not deploy "Allow standard external profiles" setting.');
+        console.log(`  Detail: ${errMsg}`);
+        console.log('  The setting may already be active. Enable manually via Setup > Digital Experiences > Settings if needed.');
+      } else {
+        console.log('  Warning: could not enable "Allow standard external profiles".');
+        console.log(`  Deploy result: ${errMsg || 'unknown error'}`);
+        console.log('  Enable manually via Setup > Digital Experiences > Settings.');
+      }
+    }
+  } finally {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+/**
+ * Enable Auth Providers for a community by creating AuthConfigProviders junction
+ * records via Anonymous Apex + REST API callouts.
+ *
+ * React (Site Container) sites intentionally hide SSO configuration in the Admin
+ * UI, so this must be done programmatically. The approach:
+ *   1. Query the AuthConfig record for the site (one per community).
+ *   2. Query AuthProvider records by DeveloperName.
+ *   3. Query SamlSsoConfig records by DeveloperName (for SAML providers).
+ *   4. Check existing AuthConfigProviders to avoid duplicates.
+ *   5. Create missing AuthConfigProviders via REST API (DML is not allowed on this object).
+ *
+ * AuthConfig.AuthOptionsAuthProvider auto-flips to true when AuthConfigProviders
+ * are inserted — no separate update needed.
+ *
+ * @param {string[]} authProviderNames - DeveloperNames of AuthProvider or SamlSsoConfig records
+ * @param {string} siteName - Name of the Network/community
+ * @param {string} targetOrg - Target org alias
+ */
+function enableAuthProvidersForSite(authProviderNames, siteName, targetOrg) {
+  // DML is not allowed on AuthConfigProviders, so we use Anonymous Apex with
+  // HTTP callouts to the REST API to create the junction records.
+  // Whitelist each DeveloperName before it is interpolated into the generated
+  // Apex `DeveloperName IN (…)` literal — same call-site guard the data-import
+  // path applies with validateApiName, and defense-in-depth alongside the
+  // up-front socialLogin validation in main(). loadSocialLoginConfig already
+  // rejects an empty list, so the resulting literal is never empty here.
+  const providerNamesLiteral = authProviderNames
+    .map((n) => `'${validateSoqlName(n, 'socialLogin.authProviderNames entry')}'`)
+    .join(', ');
+
+  const apex = `
+// Enable Auth Providers (OAuth + SAML) for community "${siteName}"
+Http http = new Http();
+String baseUrl = Url.getOrgDomainUrl().toExternalForm();
+String token = UserInfo.getSessionId();
+
+// Step 1: Find the AuthConfig for this site
+List<AuthConfig> authConfigs = [
+    SELECT Id, Url
+    FROM AuthConfig
+    WHERE Url LIKE '%${siteName}%'
+    LIMIT 1
+];
+if (authConfigs.isEmpty()) {
+    System.debug('ERROR_NO_AUTHCONFIG');
+    return;
+}
+AuthConfig ac = authConfigs[0];
+System.debug('AUTHCONFIG_FOUND:' + ac.Id + ':' + ac.Url);
+
+// Step 2: Query AuthProvider records by DeveloperName (OAuth providers)
+List<AuthProvider> oauthProviders = [
+    SELECT Id, DeveloperName, FriendlyName
+    FROM AuthProvider
+    WHERE DeveloperName IN (${providerNamesLiteral})
+];
+System.debug('OAUTH_PROVIDERS_FOUND:' + oauthProviders.size());
+
+// Step 3: Query SamlSsoConfig records by DeveloperName (SAML providers)
+List<SamlSsoConfig> samlProviders = [
+    SELECT Id, DeveloperName
+    FROM SamlSsoConfig
+    WHERE DeveloperName IN (${providerNamesLiteral})
+];
+System.debug('SAML_PROVIDERS_FOUND:' + samlProviders.size());
+
+// Combine both into a unified list with (Id, DeveloperName, Type)
+List<Map<String, String>> allProviders = new List<Map<String, String>>();
+for (AuthProvider ap : oauthProviders) {
+    allProviders.add(new Map<String, String>{
+        'Id' => ap.Id,
+        'DeveloperName' => ap.DeveloperName,
+        'Type' => 'OAuth'
+    });
+}
+for (SamlSsoConfig sp : samlProviders) {
+    allProviders.add(new Map<String, String>{
+        'Id' => sp.Id,
+        'DeveloperName' => sp.DeveloperName,
+        'Type' => 'SAML'
+    });
+}
+
+if (allProviders.isEmpty()) {
+    System.debug('ERROR_NO_PROVIDERS');
+    return;
+}
+System.debug('TOTAL_PROVIDERS_FOUND:' + allProviders.size());
+
+// Step 4: Check existing AuthConfigProviders to avoid duplicates
+Set<Id> existingProviderIds = new Set<Id>();
+for (AuthConfigProviders acp : [
+    SELECT AuthProviderId FROM AuthConfigProviders WHERE AuthConfigId = :ac.Id
+]) {
+    existingProviderIds.add(acp.AuthProviderId);
+}
+
+// Step 5: Create missing junction records via REST API
+Integer inserted = 0;
+for (Map<String, String> provider : allProviders) {
+    String providerId = provider.get('Id');
+    String providerName = provider.get('DeveloperName');
+    String providerType = provider.get('Type');
+
+    if (existingProviderIds.contains(providerId)) {
+        System.debug('ALREADY_LINKED:' + providerName + ':' + providerType);
+        continue;
+    }
+    HttpRequest req = new HttpRequest();
+    req.setEndpoint(baseUrl + '/services/data/v62.0/sobjects/AuthConfigProviders');
+    req.setMethod('POST');
+    req.setHeader('Authorization', 'Bearer ' + token);
+    req.setHeader('Content-Type', 'application/json');
+    req.setBody('{"AuthConfigId":"' + ac.Id + '","AuthProviderId":"' + providerId + '"}');
+    HttpResponse res = http.send(req);
+    if (res.getStatusCode() == 201 || res.getStatusCode() == 200) {
+        System.debug('INSERTED:' + providerName + ':' + providerType);
+        inserted++;
+    } else {
+        System.debug('INSERT_FAILED:' + providerName + ':' + providerType + ':' + res.getStatusCode() + ':' + res.getBody());
+    }
+}
+if (inserted == 0 && existingProviderIds.size() >= allProviders.size()) {
+    System.debug('ALL_ALREADY_LINKED');
+} else {
+    System.debug('TOTAL_INSERTED:' + inserted);
+}
+`;
+
+  const apexOut = withApexTempDir((writeApex) => {
+    const tmpApex = writeApex('auth-providers.apex', apex);
+    const result = spawnSync('sf', [
+      'apex', 'run', '--target-org', targetOrg, '--file', tmpApex,
+    ], { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 60000 });
+    const out = result.stdout?.toString() || '';
+    const err = result.stderr?.toString() || '';
+    if (result.status !== 0 && !out.includes('Compiled successfully')) {
+      process.stderr.write(err || out);
+      throw new StepError('failed to execute AuthConfigProviders apex');
+    }
+    return out;
+  });
+
+  // Parse output for status — match only |DEBUG| lines to avoid false positives
+  // from the "Execute Anonymous:" source echo that sf apex run always prints.
+  if (apexOut.match(/\|DEBUG\|ERROR_NO_AUTHCONFIG/)) {
+    throw new StepError(`no AuthConfig found for site "${siteName}" — ensure the site is published/active`);
+  }
+  if (apexOut.match(/\|DEBUG\|ERROR_NO_PROVIDERS/)) {
+    throw new StepError(`no AuthProvider or SamlSsoConfig records found for names: ${authProviderNames.join(', ')} — create them in Setup first`);
+  }
+
+  // Check for insert failures
+  const insertFails = [...apexOut.matchAll(/\|DEBUG\|INSERT_FAILED:([^:]+):(OAuth|SAML):(\d+):([^\n]+)/g)];
+  if (insertFails.length > 0) {
+    for (const m of insertFails) {
+      console.error(`    ✖ ${m[1]} (${m[2]}) — HTTP ${m[3]}: ${m[4].trim()}`);
+    }
+    throw new StepError(`failed to link ${insertFails.length} Auth Provider(s) to site AuthConfig`);
+  }
+
+  const totalMatch = apexOut.match(/\|DEBUG\|TOTAL_INSERTED:(\d+)/);
+  if (totalMatch) {
+    console.log(`  Linked ${totalMatch[1]} Auth Provider(s) to site "${siteName}".`);
+  } else if (apexOut.match(/\|DEBUG\|ALL_ALREADY_LINKED/)) {
+    console.log(`  All Auth Provider(s) already linked to site "${siteName}"; no changes needed.`);
+  }
+
+  // Log individual provider statuses
+  const alreadyLinked = [...apexOut.matchAll(/\|DEBUG\|ALREADY_LINKED:([^:]+):(OAuth|SAML)/g)];
+  for (const m of alreadyLinked) {
+    console.log(`    ✔ ${m[1]} (${m[2]}, already linked)`);
+  }
+  const inserted = [...apexOut.matchAll(/\|DEBUG\|INSERTED:([^:]+):(OAuth|SAML)/g)];
+  for (const m of inserted) {
+    console.log(`    + ${m[1]} (${m[2]}, newly linked)`);
+  }
+}
+
+/**
+ * Add a community user profile to the NetworkMemberGroup so that SSO-registered
+ * users (who get assigned this profile by the registration handler) can access
+ * the community.
+ *
+ * Without this, users created by the SSO registration handler get
+ * "NO_ACCESS: User was not authorized for the community".
+ *
+ * @param {string} profileName - Profile name to add (e.g. "Customer Community User")
+ * @param {string} siteName - Name of the Network/community
+ * @param {string} targetOrg - Target org alias
+ */
+function addCommunityMemberProfile(profileName, siteName, targetOrg) {
+  // Query Network Id
+  const netQuery = `SELECT Id FROM Network WHERE Name = '${siteName}'`;
+  const netResult = spawnSync('sf', [
+    'data', 'query', '--query', netQuery, '--target-org', targetOrg, '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  let networkId = null;
+  if (netResult.status === 0) {
+    try {
+      const json = JSON.parse(netResult.stdout);
+      networkId = json.result?.records?.[0]?.Id || null;
+    } catch { /* fall through */ }
+  }
+  if (!networkId) {
+    throw new StepError(`could not find Network "${siteName}" in org`);
+  }
+
+  // Query Profile Id
+  const profQuery = `SELECT Id FROM Profile WHERE Name = '${profileName}'`;
+  const profResult = spawnSync('sf', [
+    'data', 'query', '--query', profQuery, '--target-org', targetOrg, '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  let profileId = null;
+  if (profResult.status === 0) {
+    try {
+      const json = JSON.parse(profResult.stdout);
+      profileId = json.result?.records?.[0]?.Id || null;
+    } catch { /* fall through */ }
+  }
+  if (!profileId) {
+    throw new StepError(`could not find Profile "${profileName}" in org`);
+  }
+
+  // Check if already a member
+  const memberQuery = `SELECT Id FROM NetworkMemberGroup WHERE NetworkId = '${networkId}' AND ParentId = '${profileId}'`;
+  const memberResult = spawnSync('sf', [
+    'data', 'query', '--query', memberQuery, '--target-org', targetOrg, '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  let alreadyExists = false;
+  if (memberResult.status === 0) {
+    try {
+      const json = JSON.parse(memberResult.stdout);
+      alreadyExists = (json.result?.records?.length || 0) > 0;
+    } catch { /* proceed to create */ }
+  }
+  if (alreadyExists) {
+    console.log(`  Profile "${profileName}" is already a member of community "${siteName}"; skipping.`);
+    return;
+  }
+
+  // Create NetworkMemberGroup record
+  const createResult = spawnSync('sf', [
+    'data', 'create', 'record',
+    '--sobject', 'NetworkMemberGroup',
+    '--values', `NetworkId='${networkId}' ParentId='${profileId}'`,
+    '--target-org', targetOrg,
+    '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  if (createResult.status !== 0) {
+    const out = (createResult.stderr || '') + (createResult.stdout || '');
+    if (out) process.stderr.write(out);
+    throw new StepError(`failed to add profile "${profileName}" to NetworkMemberGroup for "${siteName}"`);
+  }
+  try {
+    const json = JSON.parse(createResult.stdout);
+    const id = json.result?.id;
+    console.log(`  Added profile "${profileName}" to community "${siteName}" (NetworkMemberGroup: ${id}).`);
+  } catch {
+    console.log(`  Added profile "${profileName}" to community "${siteName}".`);
+  }
+}
+
+/**
+ * Assign a permission set to all existing community users with a given profile.
+ *
+ * After SSO login, community users need the app's API-enabled permset so that
+ * getCurrentUser() (which calls /chatter/users/me via the /sf/api/ proxy) works.
+ * Without PermissionsApiEnabled the proxy returns API_DISABLED_FOR_ORG and the
+ * React app treats the user as unauthenticated.
+ *
+ * This is idempotent: already-assigned users are skipped.
+ */
+function assignPermsetToCommunityUsers(permsetName, profileName, targetOrg) {
+  // Resolve PermissionSet Id
+  const psQuery = `SELECT Id FROM PermissionSet WHERE Name = '${permsetName}'`;
+  const psResult = spawnSync('sf', [
+    'data', 'query', '--query', psQuery, '--target-org', targetOrg, '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  let permsetId = null;
+  if (psResult.status === 0) {
+    try {
+      const json = JSON.parse(psResult.stdout);
+      permsetId = json.result?.records?.[0]?.Id || null;
+    } catch { /* fall through */ }
+  }
+  if (!permsetId) {
+    throw new StepError(`could not find PermissionSet "${permsetName}" in org`);
+  }
+
+  // Find community users on the given profile who do NOT already have the permset
+  const usersQuery = [
+    `SELECT Id, Username FROM User`,
+    `WHERE Profile.Name = '${profileName}'`,
+    `AND IsActive = true`,
+    `AND UserType IN ('CspLitePortal', 'CustomerSuccess', 'PowerCustomerSuccess')`,
+    `AND Id NOT IN (SELECT AssigneeId FROM PermissionSetAssignment WHERE PermissionSetId = '${permsetId}')`,
+  ].join(' ');
+  const usersResult = spawnSync('sf', [
+    'data', 'query', '--query', usersQuery, '--target-org', targetOrg, '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+  let users = [];
+  if (usersResult.status === 0) {
+    try {
+      const json = JSON.parse(usersResult.stdout);
+      users = json.result?.records || [];
+    } catch { /* empty list */ }
+  }
+
+  if (users.length === 0) {
+    console.log(`  No community users on profile "${profileName}" need permset "${permsetName}"; skipping.`);
+    return;
+  }
+
+  // Assign the permset to each user
+  let assigned = 0;
+  for (const user of users) {
+    const createResult = spawnSync('sf', [
+      'data', 'create', 'record',
+      '--sobject', 'PermissionSetAssignment',
+      '--values', `PermissionSetId='${permsetId}' AssigneeId='${user.Id}'`,
+      '--target-org', targetOrg,
+      '--json',
+    ], { cwd: ROOT, encoding: 'utf8' });
+    if (createResult.status === 0) {
+      assigned++;
+    } else {
+      // Log but don't fail — user might already have it via race condition
+      const out = (createResult.stdout || '') + (createResult.stderr || '');
+      if (!out.includes('DUPLICATE_VALUE')) {
+        console.warn(`  Warning: could not assign "${permsetName}" to ${user.Username}: ${out.slice(0, 120)}`);
+      }
+    }
+  }
+  console.log(`  Assigned permset "${permsetName}" to ${assigned}/${users.length} community user(s).`);
+}
+
 /**
  * Ensure the self-registration profile is listed in networkMemberGroups.
  * This must happen BEFORE the initial deploy so that the profile is a recognised
@@ -375,20 +970,31 @@ function ensureNetworkMemberProfile(selfRegConfig, siteName) {
   }
   const xml = readFileSync(networkXmlPath, 'utf8');
 
-  // Check if profile is already in networkMemberGroups
-  const profileEscaped = selfRegProfile.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const profileRegex = new RegExp(`<profile>\\s*${profileEscaped}\\s*</profile>`);
-  if (profileRegex.test(xml)) {
+  // Parse + assert the target node exists, then mutate via a targeted edit.
+  // This is the BEST-EFFORT pre-deploy prep (not inside runStep, see lines
+  // ~1050): on a missing <networkMemberGroups> node we surface a LOUD
+  // console.error but do NOT throw — a bare throw here aborts before deploy and
+  // bypasses the ledger. The authoritative failure is recorded later by the
+  // post-deploy selfReg step.
+  let result;
+  try {
+    result = addProfileToMemberGroups(xml, selfRegProfile);
+  } catch (e) {
+    if (e instanceof NetworkXmlError) {
+      console.error(
+        `  ERROR: cannot add self-reg profile to ${siteName}.network-meta.xml — ${e.message}. ` +
+        `Continuing pre-deploy; the self-registration step will record the authoritative failure.`,
+      );
+      return;
+    }
+    throw e;
+  }
+
+  if (!result.changed) {
     console.log(`  Profile "${selfRegProfile}" already in networkMemberGroups; no update needed.`);
     return;
   }
-
-  // Add the profile to networkMemberGroups
-  const updatedXml = xml.replace(
-    /(<networkMemberGroups>)/,
-    `$1\n        <profile>${selfRegProfile}</profile>`
-  );
-  writeFileSync(networkXmlPath, updatedXml);
+  writeFileSync(networkXmlPath, result.xml);
   console.log(`  Added profile "${selfRegProfile}" to networkMemberGroups in ${siteName}.network-meta.xml`);
 }
 
@@ -410,23 +1016,26 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
   }
   const xml = readFileSync(networkXmlPath, 'utf8');
 
-  // Skip network modification and deploy if self-registration is already configured
-  const alreadyEnabled = /<selfRegistration>true<\/selfRegistration>/.test(xml);
-  const alreadyHasProfile = /<selfRegProfile>/.test(xml);
-  if (alreadyEnabled || alreadyHasProfile) {
+  // Parse + assert the <selfRegistration> node exists, then mutate via a
+  // targeted edit. This runs inside
+  // runStep(selfReg, failFast:false) (line ~1211), so a missing node must throw
+  // a StepError — caught, recorded `failed`, non-zero exit — rather than the
+  // old silent no-op. The helper's idempotency check
+  // (already true / selfRegProfile present) yields changed:false here.
+  let result;
+  try {
+    result = enableSelfRegInXml(xml, selfRegProfile);
+  } catch (e) {
+    if (e instanceof NetworkXmlError) {
+      throw new StepError(`${siteName}.network-meta.xml: ${e.message}`);
+    }
+    throw e;
+  }
+
+  if (!result.changed) {
     console.log(`  Network "${siteName}" already has self-registration configured; skipping metadata update and deploy.`);
   } else {
-    // Set selfRegistration to true and add selfRegProfile
-    let updatedXml = xml.replace(
-      /<selfRegistration>false<\/selfRegistration>/,
-      '<selfRegistration>true</selfRegistration>'
-    );
-    updatedXml = updatedXml.replace(
-      /(\s*)(<selfRegistration>)/,
-      `$1<selfRegProfile>${selfRegProfile}</selfRegProfile>\n$1$2`
-    );
-
-    writeFileSync(networkXmlPath, updatedXml);
+    writeFileSync(networkXmlPath, result.xml);
     console.log(`  Updated ${siteName}.network-meta.xml: selfRegistration=true, selfRegProfile=${selfRegProfile}`);
 
     // Re-deploy only the network file
@@ -440,8 +1049,13 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
     }
   }
 
-  // 3. Create Account (idempotent)
-  const acctQuery = `SELECT Id FROM Account WHERE Name = '${accountName.replace(/'/g, "\\'")}' LIMIT 1`;
+  // 3. Create Account (idempotent).
+  // accountName is a free-form display value (e.g. "O'Brien Rentals & Co.") that
+  // legitimately contains punctuation, so it is ESCAPED rather than whitelisted:
+  // escape it for the SOQL read here, and create it via Apex below
+  // (apexLiteral-escaped) rather than the `--values Name='...'` CLI arg, whose
+  // space-separated key=value parsing an escaped name cannot safely satisfy.
+  const acctQuery = `SELECT Id FROM Account WHERE Name = '${escapeSoqlString(accountName)}' LIMIT 1`;
   const acctQueryResult = spawnSync('sf', [
     'data', 'query',
     '--query', acctQuery,
@@ -458,24 +1072,34 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
   if (accountId) {
     console.log(`  Account "${accountName}" already exists (${accountId}); skipping creation.`);
   } else {
-    const createResult = spawnSync('sf', [
-      'data', 'create', 'record',
-      '--sobject', 'Account',
-      '--values', `Name='${accountName}'`,
-      '--target-org', targetOrg,
-      '--json',
-    ], { cwd: ROOT, encoding: 'utf8' });
-    if (createResult.status !== 0) {
-      if (createResult.stderr) console.error(createResult.stderr);
-      throw new StepError(`failed to create Account "${accountName}"`);
-    }
-    try {
-      const json = JSON.parse(createResult.stdout);
-      accountId = json.result?.id;
-      console.log(`  Created Account "${accountName}" (${accountId}).`);
-    } catch {
+    // Create via Anonymous Apex (apexLiteral escapes the name) instead of
+    // `sf data create record --values`: the CLI parses --values as
+    // space-separated key=value pairs, so a name with a space, quote, or `&`
+    // either mis-parses or opens a field-injection surface. Apex string
+    // escaping closes that off and mirrors the NSR create just below.
+    const apex = [
+      `Account acct = new Account(Name = ${apexLiteral(accountName)});`,
+      `insert acct;`,
+      `System.debug('ACCOUNT_CREATED:' + acct.Id);`,
+    ].join('\n');
+    const apexOut = withApexTempDir((writeApex) => {
+      const tmpApex = writeApex('account.apex', apex);
+      const apexResult = spawnSync('sf', [
+        'apex', 'run', '--target-org', targetOrg, '--file', tmpApex,
+      ], { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 60000 });
+      const out = apexResult.stdout?.toString() || '';
+      if (apexResult.status !== 0 && !out.includes('Compiled successfully')) {
+        process.stderr.write(apexResult.stderr?.toString() || out);
+        throw new StepError(`failed to create Account "${accountName}"`);
+      }
+      return out;
+    });
+    const acctMatch = apexOut.match(/ACCOUNT_CREATED:(\w+)/);
+    if (!acctMatch) {
       throw new StepError('failed to parse Account creation result');
     }
+    accountId = acctMatch[1];
+    console.log(`  Created Account "${accountName}" (${accountId}).`);
   }
 
   // 4. Query Network Id
@@ -516,7 +1140,6 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
   if (nsrExists) {
     console.log('  NetworkSelfRegistration record already exists; skipping.');
   } else {
-    const tmpApex = resolve(ROOT, '.tmp-setup-selfreg.apex');
     const apex = [
       `Account acct = [SELECT Id FROM Account WHERE Id = '${accountId}' LIMIT 1];`,
       `NetworkSelfRegistration nsr = new NetworkSelfRegistration();`,
@@ -525,16 +1148,18 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
       `insert nsr;`,
       `System.debug('NSR_CREATED:' + nsr.Id);`,
     ].join('\n');
-    writeFileSync(tmpApex, apex);
-    const apexResult = spawnSync('sf', [
-      'apex', 'run', '--target-org', targetOrg, '--file', tmpApex,
-    ], { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 60000 });
-    const apexOut = apexResult.stdout?.toString() || '';
-    if (existsSync(tmpApex)) unlinkSync(tmpApex);
-    if (apexResult.status !== 0 && !apexOut.includes('Compiled successfully')) {
-      process.stderr.write(apexResult.stderr?.toString() || apexOut);
-      throw new StepError('failed to create NetworkSelfRegistration record');
-    }
+    const apexOut = withApexTempDir((writeApex) => {
+      const tmpApex = writeApex('selfreg.apex', apex);
+      const apexResult = spawnSync('sf', [
+        'apex', 'run', '--target-org', targetOrg, '--file', tmpApex,
+      ], { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 60000 });
+      const out = apexResult.stdout?.toString() || '';
+      if (apexResult.status !== 0 && !out.includes('Compiled successfully')) {
+        process.stderr.write(apexResult.stderr?.toString() || out);
+        throw new StepError('failed to create NetworkSelfRegistration record');
+      }
+      return out;
+    });
     const nsrMatch = apexOut.match(/NSR_CREATED:(\w+)/);
     if (nsrMatch) {
       console.log(`  Created NetworkSelfRegistration (${nsrMatch[1]}).`);
@@ -549,6 +1174,7 @@ function enableSelfRegistration(selfRegConfig, siteName, targetOrg) {
  * works correctly.
  */
 function assignRoleToCurrentUser(roleName, targetOrg) {
+  validateSoqlName(roleName, 'role name');
   const roleQuery = `SELECT Id FROM UserRole WHERE Name = '${roleName}'`;
   const roleResult = spawnSync('sf', [
     'data', 'query',
@@ -629,10 +1255,30 @@ function assignRoleToCurrentUser(roleName, targetOrg) {
 }
 
 /**
- * Query the org for a guest user whose profile name matches the given site name.
+ * Query the org for the guest user of the given site.
+ *
+ * Salesforce auto-creates a guest profile named "<Site> Profile" for each
+ * Experience Cloud site. The old `Profile.Name LIKE '%<siteName>%'` substring
+ * match collided across sites — e.g. site "shop" also matched "shop-admin"'s
+ * guest profile — and then blindly took records[0]. This uses an exact match on
+ * the profile name instead. SOQL string equality on a text field is
+ * case-insensitive by default (it wraps both sides in UPPER()), so a site whose
+ * label casing differs from the derived name still matches without explicit
+ * normalization. siteName is whitelist-validated at the deriveSiteName()
+ * chokepoint, so it is safe to interpolate here.
+ *
+ * Residual limitation: on a non-English org the auto-generated " Profile" suffix
+ * may be localized, in which case no row matches and the assignment soft-skips
+ * (returned null) with a clear message — the caller records that as a skip, not
+ * a crash.
+ *
+ * Returns the guest Username, or null (with a logged reason) when the query
+ * fails, no guest user exists, or the match is ambiguous.
  */
 function resolveGuestUsername(siteName, targetOrg) {
-  const query = `SELECT Username FROM User WHERE Profile.Name LIKE '%${siteName}%' AND UserType = 'Guest'`;
+  const query =
+    `SELECT Username FROM User ` +
+    `WHERE Profile.Name = '${siteName} Profile' AND UserType = 'Guest'`;
   const result = spawnSync('sf', [
     'data', 'query',
     '--query', query,
@@ -648,7 +1294,15 @@ function resolveGuestUsername(siteName, targetOrg) {
     const json = JSON.parse(result.stdout);
     const records = json.result?.records;
     if (!records || records.length === 0) {
-      console.error(`  No guest user found for site "${siteName}".`);
+      console.error(`  No guest user found for site "${siteName}" (looked for profile "${siteName} Profile").`);
+      return null;
+    }
+    if (records.length > 1) {
+      const names = records.map((r) => r.Username).join(', ');
+      console.error(
+        `  Ambiguous guest user for site "${siteName}": ${records.length} guest users share ` +
+          `profile "${siteName} Profile" (${names}); refusing to guess.`,
+      );
       return null;
     }
     return records[0].Username;
@@ -658,6 +1312,118 @@ function resolveGuestUsername(siteName, targetOrg) {
   }
 }
 
+/**
+ * License pre-check for self-registration. Query the UserLicense that the
+ * selfRegProfile belongs to and decide whether self-registration can proceed.
+ * The profile name is validate-and-fail: a SOQL-special character throws a config
+ * error rather than being escaped — profile names are developer-authored config,
+ * not user input, so a `'` / `\` / control char is a mistake to surface loudly.
+ *
+ * Selection is on the stable LicenseDefinitionKey; the seat math lives in JS
+ * (evaluateLicenseRows) because SOQL cannot compare two fields. A query failure
+ * or 0 rows is treated as "not satisfied" (soft skip), not a hard error.
+ *
+ * @returns {{ satisfied: boolean, reason: string|null }}
+ */
+function checkSelfRegLicense(selfRegConfig, targetOrg) {
+  const profileName = validateProfileNameForSoql(selfRegConfig.selfRegProfile);
+  const query =
+    `SELECT UserLicense.LicenseDefinitionKey, UserLicense.Name, UserLicense.Status, ` +
+    `UserLicense.TotalLicenses, UserLicense.UsedLicenses ` +
+    `FROM Profile WHERE Name = '${profileName}'`;
+  const result = spawnSync('sf', [
+    'data', 'query',
+    '--query', query,
+    '--target-org', targetOrg,
+    '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+
+  if (result.status !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    return {
+      satisfied: false,
+      reason: `could not query the UserLicense for profile "${profileName}" (sf data query failed)`,
+    };
+  }
+  let rows;
+  try {
+    rows = JSON.parse(result.stdout).result?.records ?? [];
+  } catch {
+    return {
+      satisfied: false,
+      reason: `could not parse the UserLicense query result for profile "${profileName}"`,
+    };
+  }
+  const { satisfied, reason } = evaluateLicenseRows(rows, profileName);
+  return { satisfied, reason };
+}
+
+/**
+ * Read the UserLicense the selfRegProfile requires straight from the local
+ * profile metadata's <userLicense> element. The deploy pre-check runs BEFORE
+ * the profile is deployed, so querying the org's Profile table returns 0 rows
+ * and can only report "profile missing" — which never tells the user which
+ * license to add. The profile source we are about to deploy is the
+ * authoritative declaration of the required license.
+ *
+ * @returns {string|null} the license name, or null if the file / field is absent
+ */
+function readProfileUserLicense(selfRegProfile) {
+  const profilePath = resolve(SFDX_SOURCE, 'profiles', `${selfRegProfile}.profile-meta.xml`);
+  if (!existsSync(profilePath)) return null;
+  const xml = readFileSync(profilePath, 'utf8');
+  const m = xml.match(/<userLicense>\s*([^<]+?)\s*<\/userLicense>/);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Deploy license pre-check. `sf project deploy start` fails with a
+ * cryptic error when the org lacks the UserLicense the selfRegProfile's metadata
+ * declares. Resolve the required license NAME from the local profile source, then
+ * query the org's UserLicense by that name so a miss names the actual license the
+ * admin must add — not the not-yet-deployed profile. Seat/status math is shared
+ * with the self-reg gate via evaluateLicenseRows.
+ *
+ * @returns {{ satisfied: boolean, reason: string|null }}
+ */
+function checkDeployLicense(selfRegConfig, targetOrg) {
+  const licenseName = readProfileUserLicense(selfRegConfig.selfRegProfile);
+  // No <userLicense> in the profile source (or profile file absent) — nothing to
+  // gate on; let deploy proceed and surface any real error on its own.
+  if (!licenseName) return { satisfied: true, reason: null };
+
+  const query =
+    `SELECT LicenseDefinitionKey, Name, Status, TotalLicenses, UsedLicenses ` +
+    `FROM UserLicense WHERE Name = '${escapeSoqlString(licenseName)}'`;
+  const result = spawnSync('sf', [
+    'data', 'query',
+    '--query', query,
+    '--target-org', targetOrg,
+    '--json',
+  ], { cwd: ROOT, encoding: 'utf8' });
+
+  if (result.status !== 0) {
+    if (result.stderr) console.error(result.stderr);
+    return { satisfied: false, reason: `could not query UserLicense "${licenseName}" (sf data query failed)` };
+  }
+  let rows;
+  try {
+    rows = JSON.parse(result.stdout).result?.records ?? [];
+  } catch {
+    return { satisfied: false, reason: `could not parse the UserLicense query result for "${licenseName}"` };
+  }
+  if (rows.length === 0) {
+    return {
+      satisfied: false,
+      reason: `required license "${licenseName}" is not present in the org — add it before deploying`,
+    };
+  }
+  // evaluateLicenseRows expects the license nested under `.UserLicense` (its
+  // Profile-query shape); reshape the direct UserLicense rows to match so the
+  // seat/status logic — and its license-named messages — stay shared.
+  return evaluateLicenseRows(rows.map((r) => ({ UserLicense: r })), selfRegConfig.selfRegProfile);
+}
+
 function isOrgConnected(targetOrg) {
   const result = spawnSync('sf', ['org', 'display', '--target-org', targetOrg, '--json'], {
     cwd: ROOT,
@@ -681,8 +1447,20 @@ function apexLiteral(value) {
 }
 
 function buildApexInsert(sobject, records, refIds) {
+  // The sobject type and every field key land as bare identifiers inside the
+  // generated Apex (`new ${sobject}()`, `r.put('${key}', …)`), where they can't
+  // be quoted-and-escaped like a value — so they get the strict API-name
+  // whitelist. refIds are the record referenceIds echoed back through a JSON
+  // marker; they carry no Apex-identifier role, so escaping (not whitelisting)
+  // is the right treatment for their single-quoted literal. All three come from
+  // app-shipped seed fixtures, so a violation is a fixture bug surfaced loudly.
+  validateApiName(sobject, 'sobject type');
   const lines = [
     'Database.DMLOptions dmlOpts = new Database.DMLOptions();',
+    // Intentional: bypass duplicate rules for seed-data import. These are
+    // controlled fixtures the app ships, not user input, and duplicate-rule
+    // blocks (plus matching-service timeouts the REST Sforce-Duplicate-Rule-Action
+    // header can't override) would abort an otherwise-valid setup.
     'dmlOpts.DuplicateRuleHeader.allowSave = true;',
     `List<${sobject}> recs = new List<${sobject}>();`,
   ];
@@ -690,17 +1468,31 @@ function buildApexInsert(sobject, records, refIds) {
     lines.push(`{ ${sobject} r = new ${sobject}();`);
     for (const [key, val] of Object.entries(rec)) {
       if (key === 'attributes') continue;
+      validateApiName(key, `field API name on ${sobject}`);
       lines.push(`r.put('${key}', ${apexLiteral(val)});`);
     }
     lines.push('recs.add(r); }');
   }
   lines.push('Database.SaveResult[] results = Database.insert(recs, dmlOpts);');
-  const refArray = refIds.map((r) => `'${r}'`).join(',');
+  const refArray = refIds.map((r) => `'${escapeSoqlString(r)}'`).join(',');
   lines.push(`String[] refs = new String[]{${refArray}};`);
+  // Emit ONE machine-readable line instead of one System.debug per record: a
+  // JSON array of {ref, id?|err?}. The Node side parses this with
+  // parseApexInsertResults and treats a missing/unparseable marker as a hard
+  // batch failure (a truncated debug line must not read as "0 errors"). Measured
+  // batching keeps each batch — and thus this payload — well under the log line
+  // size.
+  lines.push('List<Object> setupOut = new List<Object>();');
   lines.push('for (Integer i = 0; i < results.size(); i++) {');
-  lines.push("  if (results[i].isSuccess()) System.debug('REF:' + refs[i] + ':' + results[i].getId());");
-  lines.push("  else System.debug('ERR:' + refs[i] + ':' + results[i].getErrors()[0].getMessage());");
+  lines.push('  Map<String,Object> m = new Map<String,Object>{ \'ref\' => refs[i] };');
+  lines.push('  if (results[i].isSuccess()) { m.put(\'id\', results[i].getId()); }');
+  lines.push('  else { m.put(\'err\', results[i].getErrors()[0].getMessage()); }');
+  lines.push('  setupOut.add(m);');
   lines.push('}');
+  // Use LoggingLevel.ERROR to ensure this critical line appears near the end of
+  // the debug log and isn't truncated by excessive DEBUG-level noise from DML
+  // operations, workflow rules, or process builders that fire during insert.
+  lines.push("System.debug(LoggingLevel.ERROR, 'SETUP_RESULT_JSON:' + JSON.serialize(setupOut));");
   return lines.join('\n');
 }
 
@@ -931,6 +1723,13 @@ async function runStep(step, targetOrg, body) {
 }
 
 async function main() {
+  // Cleanup AT START: remove Apex temp artifacts left by a prior hard-killed run.
+  // Safe to run before the per-org lock is acquired because it only removes
+  // org-setup-* temp DIRECTORIES and legacy ROOT temp files — never the
+  // org-setup-lock-<org>.lock files (plain files), so it cannot clobber a
+  // concurrent run's live lock.
+  sweepStaleApexTempDirs();
+
   // Ensure .gitignore files exist (npm strips them from published packages).
   const gitignoreTemplates = loadGitignoreTemplates();
   if (gitignoreTemplates) {
@@ -944,21 +1743,30 @@ async function main() {
     }
   }
 
+  const parsed = parseArgs();
   const {
-    targetOrg,
     uiBundleName,
     permsetNamesExplicit,
     yes,
-    skipLogin: argSkipLogin,
     skipDeploy: argSkipDeploy,
     skipPermset: argSkipPermset,
     skipRole: argSkipRole,
     skipSelfReg: argSkipSelfReg,
+    skipSocialLogin: argSkipSocialLogin,
     skipData: argSkipData,
     skipGraphql: argSkipGraphql,
     skipUIBundleBuild: argSkipUIBundleBuild,
-    skipDev: argSkipDev,
-  } = parseArgs();
+  } = parsed;
+
+  // Resolve the target org up front: explicit --target-org is used verbatim;
+  // otherwise prompt (TTY) or fall back to the default org / exit.
+  const targetOrg = await resolveTargetOrg(parsed);
+
+  // Per-target-org lock: acquired right after the start-of-run
+  // sweep and before any step runs, so two runs against the same org cannot
+  // interleave destructive Apex. The startup sweep above deliberately skips lock
+  // files, so it never races this. Released on process exit.
+  acquireOrgLock(targetOrg);
 
   const permsetNames =
     permsetNamesExplicit.length > 0 ? permsetNamesExplicit : discoverPermissionSetNames();
@@ -969,8 +1777,8 @@ async function main() {
         ? `Permset — assign ${permsetNames.join(', ')}`
         : `Permset — assign ${permsetNames.length} permission sets`;
 
-  // Validate org-setup.config.json ONCE, before any step runs (spec §5.2). The
-  // three load*Config helpers read from this already-validated object.
+  // Validate org-setup.config.json ONCE, before any step runs. The three
+  // load*Config helpers read from this already-validated object.
   const config = loadValidatedConfig();
 
   const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
@@ -978,21 +1786,64 @@ async function main() {
   const hasRoleConfig = roleConfig !== null;
   const selfRegConfig = loadSelfRegConfig(config);
   const hasSelfRegConfig = selfRegConfig !== null;
+  const socialLoginConfig = loadSocialLoginConfig(config);
+  const hasSocialLoginConfig = socialLoginConfig !== null;
+
+  // Validate the selfRegProfile name for SOQL-safety up front, alongside the
+  // config validation and BEFORE any org mutation (login/deploy). A quote /
+  // backslash / control char is a config mistake, not a runtime value to
+  // escape — fail fast here with a clean, actionable message rather than
+  // letting the license gate throw a raw stack trace deep in the run after deploy.
+  if (hasSelfRegConfig) {
+    try {
+      validateProfileNameForSoql(selfRegConfig.selfRegProfile);
+    } catch (err) {
+      console.error(`Invalid org-setup.config.json:\n  - ${err.message}`);
+      process.exit(1);
+    }
+  }
 
-  // failFast is a fixed, implementer-owned classification (spec §5.2) — NOT
+  // Same fail-fast treatment for the socialLogin identifiers, alongside the
+  // self-reg guard above and BEFORE any org mutation. communityMemberProfile,
+  // every authProviderNames entry, and the optional communityUserPermset are all
+  // interpolated into generated SOQL / CLI value strings — the Profile and
+  // PermissionSet `WHERE Name = '…'` lookups, the AuthProvider/SamlSsoConfig
+  // `DeveloperName IN (…)` list, and the NetworkMemberGroup/User queries. These
+  // are developer-authored identifiers the app ships, so a quote / backslash /
+  // control char is a config mistake to surface loudly here rather than a value
+  // to silently escape (same rationale as validateSoqlName's self-reg use).
+  if (hasSocialLoginConfig) {
+    try {
+      validateSoqlName(socialLoginConfig.communityMemberProfile, 'socialLogin.communityMemberProfile');
+      for (const providerName of socialLoginConfig.authProviderNames ?? []) {
+        validateSoqlName(providerName, 'socialLogin.authProviderNames entry');
+      }
+      if (socialLoginConfig.communityUserPermset) {
+        validateSoqlName(socialLoginConfig.communityUserPermset, 'socialLogin.communityUserPermset');
+      }
+    } catch (err) {
+      console.error(`Invalid org-setup.config.json:\n  - ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // failFast is a fixed, implementer-owned classification — NOT
   // user-configurable. A fail-fast failure aborts the run immediately; a
   // skippable failure is recorded and the run continues. The exit code is
   // non-zero on any failure regardless of class.
+  // Login is NOT in this picker: it is an unconditional precondition run before
+  // deploy, not a toggleable step. The dev step is also gone: launching the dev
+  // server moved to `npm run dev:preview`, so setup terminates cleanly after
+  // graphql.
   const stepDefs = [
-    { key: 'login', label: 'Login — org authentication', enabled: !argSkipLogin, available: true, failFast: true },
     { key: 'uiBundleBuild', label: 'UI Bundle Build — npm install + build (pre-deploy)', enabled: !argSkipUIBundleBuild, available: true, failFast: true },
     { key: 'deploy', label: 'Deploy — sf project deploy start', enabled: !argSkipDeploy, available: true, failFast: true },
     { key: 'permset', label: permsetStepLabel, enabled: !argSkipPermset, available: true, failFast: false },
     { key: 'role', label: `Role — assign "${roleConfig?.roleName ?? '?'}" to current user`, enabled: !argSkipRole && hasRoleConfig, available: hasRoleConfig, failFast: false },
     { key: 'selfReg', label: 'Self-Registration — enable for site', enabled: !argSkipSelfReg && hasSelfRegConfig, available: hasSelfRegConfig, failFast: false },
+    { key: 'socialLogin', label: 'Social Login — enable auth providers + community profile', enabled: !argSkipSocialLogin && hasSocialLoginConfig, available: hasSocialLoginConfig, failFast: false },
     { key: 'data', label: 'Data — delete + import records via Apex', enabled: !argSkipData && hasDataPlan, available: hasDataPlan, failFast: true },
     { key: 'graphql', label: 'GraphQL — schema introspect + codegen', enabled: !argSkipGraphql, available: true, failFast: true },
-    { key: 'dev', label: 'Dev — launch dev server', enabled: !argSkipDev, available: true, failFast: false },
   ];
 
   const selections = yes ? stepDefs.map((s) => s.enabled) : await promptSteps(stepDefs);
@@ -1001,49 +1852,44 @@ async function main() {
     on[s.key] = selections[i];
   });
 
-  const skipLogin = !on.login;
   const skipUIBundleBuild = !on.uiBundleBuild;
   const skipDeploy = !on.deploy;
   const skipPermset = !on.permset;
   const skipRole = !on.role;
   const skipSelfReg = !on.selfReg;
+  const skipSocialLogin = !on.socialLogin;
   const skipData = !on.data;
   const skipGraphql = !on.graphql;
-  const skipDev = !on.dev;
 
-  const needsUIBundle = !skipUIBundleBuild || !skipGraphql || !skipDev;
-  const uiBundleDir = needsUIBundle ? discoverUIBundleDir(uiBundleName) : null;
+  const needsUIBundle = !skipUIBundleBuild || !skipGraphql;
+  const uiBundleDir = needsUIBundle ? await discoverUIBundleDir(uiBundleName) : null;
   const doData = !skipData;
 
   console.log('Setup — target org:', targetOrg, '| UI bundle:', uiBundleDir ?? '(none)');
   console.log(
-    'Steps: login=%s deploy=%s permset=%s role=%s selfReg=%s data=%s graphql=%s uiBundle=%s dev=%s',
-    !skipLogin,
+    'Steps: login=always deploy=%s permset=%s role=%s selfReg=%s socialLogin=%s data=%s graphql=%s uiBundle=%s',
     !skipDeploy,
     !skipPermset,
     !skipRole,
     !skipSelfReg,
+    !skipSocialLogin,
     doData,
     !skipGraphql,
-    !skipUIBundleBuild,
-    !skipDev
+    !skipUIBundleBuild
   );
 
-  const loginStep = stepDefs.find((s) => s.key === 'login');
-  if (!skipLogin) {
-    await runStep(loginStep, targetOrg, async () => {
-      if (isOrgConnected(targetOrg)) {
-        console.log('\n--- Login ---');
-        console.log(`Org ${targetOrg} is already authenticated; skipping browser login.`);
-      } else {
-        // Login is fail-fast (spec §5.2): drop the previous { optional: true } so a
-        // failed browser login records `failed`, prints the summary, and aborts.
-        run('Login (browser)', 'sf', ['org', 'login', 'web', '--alias', targetOrg]);
-      }
-    });
-  } else {
-    recordSkipped(loginStep, 'not selected');
-  }
+  // Login is an unconditional precondition: it is not part of
+  // the step picker and cannot be skipped. It still no-ops when the org is already
+  // connected, and stays fail-fast — a failed browser login aborts before deploy.
+  const loginStep = { key: 'login', label: 'Login — org authentication', failFast: true };
+  await runStep(loginStep, targetOrg, async () => {
+    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]);
+    }
+  });
 
   // Ensure the self-reg profile is in networkMemberGroups before deploy so that
   // subsequent selfRegProfile / selfRegistration updates don't fail. This is
@@ -1088,6 +1934,19 @@ async function main() {
   const deployStep = stepDefs.find((s) => s.key === 'deploy');
   if (!skipDeploy) {
     await runStep(deployStep, targetOrg, () => {
+      // License pre-check: deploy fails with a cryptic error when the
+      // org lacks the UserLicense the selfRegProfile's metadata requires. Verify a
+      // seat is available BEFORE `sf project deploy start` so the run aborts with a
+      // clean message NAMING the missing license. The required license is read from
+      // the local profile source (the profile isn't in the org yet pre-deploy, so
+      // querying it would only report "profile missing"). Only gates when self-reg
+      // is configured — that config names the profile the license is derived from.
+      if (selfRegConfig) {
+        const licenseGate = checkDeployLicense(selfRegConfig, targetOrg);
+        if (!licenseGate.satisfied) {
+          throw new StepError(`deploy blocked — ${licenseGate.reason}`);
+        }
+      }
       run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
         timeout: 180000,
       });
@@ -1126,7 +1985,7 @@ async function main() {
         let effectiveUsername = null;
         if (assignment.assignee === 'guestUser') {
           // Site name is derived from the single network metadata file the app
-          // ships (spec §5.2) — never restated per-assignment.
+          // ships — never restated per-assignment.
           const siteName = deriveSiteName();
           if (!siteName) {
             console.error(`Permission set "${permsetName}" — assignee is "guestUser" but no networks/<siteName>.network-meta.xml was found to derive the site; skipping.`);
@@ -1196,41 +2055,95 @@ async function main() {
 
   const selfRegStep = stepDefs.find((s) => s.key === 'selfReg');
   if (!skipSelfReg) {
-    console.log('\n--- Enable self-registration ---');
-    // Config shape (selfRegProfile, accountName) is guaranteed by the schema.
-    // The site is derived inside the step body so a "multiple network files"
-    // StepError is recorded in the ledger rather than escaping. No manual
-    // recordSkipped inference.
-    await runStep(selfRegStep, targetOrg, () => {
+    // License pre-check: self-registration requires a seat on the
+    // UserLicense the selfRegProfile belongs to. Verify it BEFORE running the step
+    // — recordSkipped is only reachable here, ahead of runStep (mirroring the
+    // not-selected branch); once inside a step body an unmet precondition could
+    // only record `failed`. A missing / inactive / seatless license is a soft
+    // precondition, not a setup failure, so warn + recordSkipped and move on.
+    const licenseGate = checkSelfRegLicense(selfRegConfig, targetOrg);
+    if (!licenseGate.satisfied) {
+      console.warn(`\n--- Self-registration skipped ---\n  ⚠ ${licenseGate.reason}`);
+      recordSkipped(selfRegStep, licenseGate.reason);
+    } else {
+      console.log('\n--- Enable self-registration ---');
+      // Config shape (selfRegProfile, accountName) is guaranteed by the schema.
+      // The site is derived inside the step body so a "multiple network files"
+      // StepError is recorded in the ledger rather than escaping. No manual
+      // recordSkipped inference.
+      await runStep(selfRegStep, targetOrg, () => {
+        const siteName = deriveSiteName();
+        if (!siteName) {
+          throw new StepError(
+            'self-registration is configured but no networks/<siteName>.network-meta.xml was found to derive the site',
+          );
+        }
+        enableSelfRegistration(selfRegConfig, siteName, targetOrg);
+      });
+    }
+  } else {
+    recordSkipped(selfRegStep, selfRegStep.available ? 'not selected' : 'no config');
+  }
+
+  const socialLoginStep = stepDefs.find((s) => s.key === 'socialLogin');
+  if (!skipSocialLogin) {
+    console.log('\n--- Social Login — enable auth providers + community profile ---');
+    await runStep(socialLoginStep, targetOrg, () => {
       const siteName = deriveSiteName();
       if (!siteName) {
         throw new StepError(
-          'self-registration is configured but no networks/<siteName>.network-meta.xml was found to derive the site',
+          'socialLogin is configured but no networks/<siteName>.network-meta.xml was found to derive the site',
+        );
+      }
+
+      const totalSubSteps = socialLoginConfig.communityUserPermset ? 4 : 3;
+
+      // Sub-step 1: Enable "Allow using standard external profiles" org setting.
+      // This is required so the SSO registration handler can create users with
+      // standard community profiles (e.g. "Customer Community User").
+      console.log(`  [1/${totalSubSteps}] Enabling "Allow standard external profiles" setting...`);
+      enableExternalProfiles(targetOrg);
+
+      // Sub-step 2: Link Auth Providers to the site's AuthConfig.
+      // React (Site Container) sites hide SSO config in Admin UI, so this must
+      // be done programmatically via AuthConfig/AuthConfigProviders records.
+      console.log(`  [2/${totalSubSteps}] Linking Auth Providers to site AuthConfig...`);
+      enableAuthProvidersForSite(socialLoginConfig.authProviderNames, siteName, targetOrg);
+
+      // Sub-step 3: Add the community member profile to NetworkMemberGroup.
+      // Without this, users created by the registration handler get
+      // "NO_ACCESS: User was not authorized for the community".
+      console.log(`  [3/${totalSubSteps}] Adding community member profile to NetworkMemberGroup...`);
+      addCommunityMemberProfile(socialLoginConfig.communityMemberProfile, siteName, targetOrg);
+
+      // Sub-step 4 (optional): Assign API-enabled permset to community users.
+      // Without this, getCurrentUser() fails because /chatter/users/me requires
+      // PermissionsApiEnabled which the standard community profile lacks.
+      if (socialLoginConfig.communityUserPermset) {
+        console.log(`  [4/${totalSubSteps}] Assigning API permset to community users...`);
+        assignPermsetToCommunityUsers(
+          socialLoginConfig.communityUserPermset,
+          socialLoginConfig.communityMemberProfile,
+          targetOrg,
         );
       }
-      enableSelfRegistration(selfRegConfig, siteName, targetOrg);
     });
   } else {
-    recordSkipped(selfRegStep, selfRegStep.available ? 'not selected' : 'no config');
+    recordSkipped(socialLoginStep, socialLoginStep.available ? 'not selected' : 'no config');
   }
 
   const dataStep = stepDefs.find((s) => s.key === 'data');
   if (doData) {
    await runStep(dataStep, targetOrg, () => {
-    // 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,
-    });
-    // Normalize Lease__c Tenant refs to 1–15 so all refs resolve (Tenant__c.json has 15 records)
-    const leasePath = resolve(DATA_DIR, 'Lease__c.json');
-    if (existsSync(leasePath)) {
-      let leaseContent = readFileSync(leasePath, 'utf8');
-      leaseContent = leaseContent.replace(/@TenantRef(\d+)/g, (_m, n) => {
-        const k = ((parseInt(n, 10) - 1) % 15) + 1;
-        return `@TenantRef${k}`;
+    // Prepare data for uniqueness (run before import so repeat imports don't conflict).
+    // Per-app data normalization (reference remapping, unique-field mangling) ships with
+    // the app's seed data as data/prepare-import-unique-fields.js — this script stays
+    // object-agnostic and simply runs it if present.
+    const prepareScript = resolve(DATA_DIR, 'prepare-import-unique-fields.js');
+    if (existsSync(prepareScript)) {
+      run('Prepare data (unique fields)', 'node', [prepareScript, '--data-dir', DATA_DIR], {
+        cwd: ROOT,
       });
-      writeFileSync(leasePath, leaseContent);
     }
 
     // Delete existing records so every run inserts the full dataset without duplicate conflicts.
@@ -1238,8 +2151,14 @@ async function main() {
     console.log('\n--- Clean existing data for fresh import ---');
     const planEntries = JSON.parse(readFileSync(DATA_PLAN, 'utf8'));
     const sobjectsReversed = [...planEntries.map((e) => e.sobject)].reverse();
-    const tmpApex = resolve(ROOT, '.tmp-setup-delete.apex');
+    // One private temp dir for both the delete sweep and the import batches;
+    // always removed in finally, even if a batch throws.
+    withApexTempDir((writeApex) => {
     for (const sobject of sobjectsReversed) {
+      // Bare identifier inside a dynamic-SOQL string literal — whitelist it (the
+      // same guard buildApexInsert applies) so a malformed data-plan sobject
+      // can't alter the delete query.
+      validateApiName(sobject, 'sobject type');
       const apexCode = [
         'try {',
         `  List<SObject> recs = Database.query('SELECT Id FROM ${sobject} LIMIT 10000');`,
@@ -1251,7 +2170,7 @@ async function main() {
         '  // non-deletable records (e.g. Contact linked to Case) are skipped via allOrNone=false',
         '}',
       ].join('\n');
-      writeFileSync(tmpApex, apexCode);
+      const tmpApex = writeApex('data.apex', apexCode);
       spawnSync('sf', ['apex', 'run', '--target-org', targetOrg, '--file', tmpApex], {
         cwd: ROOT,
         stdio: 'pipe',
@@ -1260,15 +2179,20 @@ async function main() {
       });
       console.log(`  ${sobject}: cleaned`);
     }
-    if (existsSync(tmpApex)) unlinkSync(tmpApex);
 
     // Import via Anonymous Apex with Database.DMLOptions.duplicateRuleHeader.allowSave = true.
     // This bypasses both duplicate-rule blocks AND matching-service timeouts that the REST
     // API headers (Sforce-Duplicate-Rule-Action) cannot override.
-    console.log('\n--- Data import tree ---');
+    console.log('\n--- Data import (Apex) ---');
     const refMap = new Map();
+    // Apex anonymous code is capped at ~1M chars total, but each batch is much
+    // smaller in practice. The real constraint is the SETUP_RESULT_JSON debug log
+    // line: Salesforce truncates debug lines at ~5KB, and large batches produce
+    // JSON arrays that exceed that limit. With RESULT_JSON_PER_RECORD = 150 and
+    // MAX_BATCH = 100, the worst-case output is ~15KB of JSON, which fits
+    // comfortably after the debug-line prefix and the marker.
     const APEX_CHAR_LIMIT = 25000;
-    const APEX_MAX_BATCH = 200;
+    const APEX_MAX_BATCH = 100;
 
     for (const entry of planEntries) {
       for (const file of entry.files) {
@@ -1290,16 +2214,52 @@ async function main() {
           }
         }
 
+        // Measured batching: size each record's rendered Apex (using
+        // the same apexLiteral the insert uses) and pack batches under the char
+        // limit, instead of the old estCharsPerRec = 40 + fields*55 guess that
+        // under-counted long text fields and could overflow the anon-Apex limit.
+        // Overhead is measured from the real builder with zero records so the
+        // fixed boilerplate can't drift from buildApexInsert. Each record also
+        // grows the per-batch `String[] refs = new String[]{'…',…}` line, so its
+        // rendered refId literal is counted here too (mirroring the same
+        // referenceId/_idx fallback the batch emit uses) — otherwise sizing
+        // under-counts and a packed batch could edge past APEX_CHAR_LIMIT.
+        //
+        // CRITICAL: also account for the SETUP_RESULT_JSON output size. The
+        // System.debug line can exceed the Salesforce debug log line limit when
+        // the serialized JSON array is large. Estimate ~85 chars per success
+        // result ({"ref":"_idxNNN","id":"001XXXXXXXXXXXXXXX"}) and ~150 chars per
+        // potential error ({"ref":"_idxNNN","err":"typical error message"}), taking
+        // the higher value to be conservative. This ensures the batching prevents
+        // log truncation that would fail parseApexInsertResults.
+        const overhead = buildApexInsert(entry.sobject, [], []).length;
+        const RESULT_JSON_PER_RECORD = 150;
+        const recordSizes = records.map((rec, i) => {
+          let size = `{ ${entry.sobject} r = new ${entry.sobject}();\n`.length + 'recs.add(r); }\n'.length;
+          for (const [key, val] of Object.entries(rec)) {
+            if (key === 'attributes') continue;
+            size += `r.put('${key}', ${apexLiteral(val)});\n`.length;
+          }
+          const refId = rec.attributes?.referenceId || `_idx${i}`;
+          size += `'${escapeSoqlString(refId)}',`.length;
+          // Add the estimated size of this record's JSON result entry in the
+          // SETUP_RESULT_JSON output. Without this, large batches can produce
+          // debug log lines that exceed Salesforce's limit and get truncated.
+          size += RESULT_JSON_PER_RECORD;
+          return size;
+        });
+        const batches = planApexBatches(recordSizes, {
+          charLimit: APEX_CHAR_LIMIT,
+          maxBatch: APEX_MAX_BATCH,
+          overhead,
+        });
+
         let imported = 0;
-        const sampleRec = records[0] || {};
-        const fieldsPerRec = Object.keys(sampleRec).filter((k) => k !== 'attributes').length;
-        const estCharsPerRec = 40 + fieldsPerRec * 55;
-        const batchSize = Math.min(APEX_MAX_BATCH, Math.max(5, Math.floor(APEX_CHAR_LIMIT / estCharsPerRec)));
-        for (let i = 0; i < records.length; i += batchSize) {
-          const batch = records.slice(i, i + batchSize);
-          const refIds = batch.map((r) => r.attributes?.referenceId || `_idx${i}`);
+        for (const { start, count } of batches) {
+          const batch = records.slice(start, start + count);
+          const refIds = batch.map((r, j) => r.attributes?.referenceId || `_idx${start + j}`);
           const apex = buildApexInsert(entry.sobject, batch, refIds);
-          writeFileSync(tmpApex, apex);
+          const tmpApex = writeApex('data.apex', apex);
           const apexResult = spawnSync(
             'sf',
             ['apex', 'run', '--target-org', targetOrg, '--file', tmpApex],
@@ -1311,24 +2271,29 @@ async function main() {
             process.stderr.write(apexErr || apexOut);
             throw new StepError(`${entry.sobject}: apex execution failed`);
           }
-          const okMatches = [...apexOut.matchAll(/\|DEBUG\|REF:([^:\n]+):(\w+)/g)];
-          const errMatches = [...apexOut.matchAll(/\|DEBUG\|ERR:([^:\n]+):([^\n]+)/g)];
-          if (errMatches.length) {
-            for (const m of errMatches.slice(0, 5)) {
-              console.error(`    ${m[1]}: ${m[2].trim()}`);
+          const parsed = parseApexInsertResults(apexOut);
+          if (!parsed.ok) {
+            // A missing/truncated result marker must fail loudly — never read as
+            // "0 errors" and let a partial import look successful.
+            process.stderr.write(apexErr || apexOut);
+            throw new StepError(`data import (${entry.sobject}) — ${parsed.error}`);
+          }
+          if (parsed.errors.length) {
+            for (const e of parsed.errors.slice(0, 5)) {
+              console.error(`    ${e.ref}: ${e.message.trim()}`);
             }
-            if (errMatches.length > 5) console.error(`    ... and ${errMatches.length - 5} more`);
-            throw new StepError(`data import tree (${entry.sobject}) — ${errMatches.length} record error(s)`);
+            if (parsed.errors.length > 5) console.error(`    ... and ${parsed.errors.length - 5} more`);
+            throw new StepError(`data import (${entry.sobject}) — ${parsed.errors.length} record error(s)`);
           }
           if (entry.saveRefs) {
-            for (const m of okMatches) refMap.set(m[1], m[2]);
+            for (const s of parsed.successes) refMap.set(s.ref, s.id);
           }
-          imported += okMatches.length;
+          imported += parsed.successes.length;
         }
         console.log(`  ${entry.sobject}: imported ${imported} records`);
       }
     }
-    if (existsSync(tmpApex)) unlinkSync(tmpApex);
+    });
    });
   } else {
     recordSkipped(dataStep, dataStep.available ? 'not selected' : 'no data plan');
@@ -1365,29 +2330,12 @@ async function main() {
     recordOk(uiBundleBuildStep);
   }
 
-  const devStep = stepDefs.find((s) => s.key === 'dev');
-  if (!skipDev) {
-    // dev is skippable and terminal: a failure here is a local runtime issue
-    // (port in use, tooling), not a broken setup. Print the summary BEFORE the
-    // (blocking, long-lived) dev server starts so the developer sees the setup
-    // outcome up front; the server then runs in the foreground until Ctrl+C.
-    recordOk(devStep);
-    printSummary(targetOrg);
-    console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
-    const devResult = run('Dev server', 'npm', ['run', 'dev'], { cwd: uiBundleDir, optional: true });
-    if (devResult.status !== 0) {
-      // Replace the optimistic `ok` with a skippable failure and reprint.
-      const row = results.find((r) => r.key === 'dev');
-      row.status = 'failed';
-      row.reason = 'dev server failed to start — setup itself completed; check local runtime';
-      printSummary(targetOrg);
-    }
-    process.exit(finalExitCode());
-  } else {
-    recordSkipped(devStep, 'not selected');
-  }
-
+  // Setup terminates cleanly here. Launching the dev server is
+  // no longer part of setup — run `npm run dev:preview` (scripts/org-setup-dev.mjs) for that.
   printSummary(targetOrg);
+  if (finalExitCode() === 0) {
+    console.log('\nTo launch the dev server, run:  npm run dev:preview');
+  }
   process.exit(finalExitCode());
 }