@salesforce/ui-bundle-template-feature-react-search 11.12.1 → 11.13.0

package/dist/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,33 @@
  */
 
 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,
+  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,
+} from './org-setup-utils.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
@@ -53,6 +77,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 +274,6 @@ function parseArgs() {
   const permsetNamesExplicit = [];
   let yes = false;
   const flags = {
-    skipLogin: false,
     skipDeploy: false,
     skipPermset: false,
     skipRole: false,
@@ -115,7 +281,6 @@ function parseArgs() {
     skipGraphql: false,
     skipUIBundleBuild: false,
     skipSelfReg: false,
-    skipDev: false,
   };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--target-org' && args[i + 1]) {
@@ -124,39 +289,42 @@ 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-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 (spec §5.5/§5.6, AC-14): 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-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 +344,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 (spec §5.4). 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 now carries the
+// multi-bundle acknowledgment of spec §5.1 item 2 (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 +403,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() {
@@ -335,7 +484,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.
@@ -375,20 +524,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 +570,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
@@ -516,7 +679,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 +687,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]}).`);
@@ -658,6 +822,119 @@ function resolveGuestUsername(siteName, targetOrg) {
   }
 }
 
+/**
+ * M1 license pre-check (spec §5.3). Query the UserLicense that the selfRegProfile
+ * belongs to and decide whether self-registration can proceed. The profile name
+ * is validate-and-fail (Q10, AC-8): 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 (spec §5.3). `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 escaped = licenseName.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+  const query =
+    `SELECT LicenseDefinitionKey, Name, Status, TotalLicenses, UsedLicenses ` +
+    `FROM UserLicense WHERE Name = '${escaped}'`;
+  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,
@@ -931,6 +1208,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,12 +1228,11 @@ async function main() {
     }
   }
 
+  const parsed = parseArgs();
   const {
-    targetOrg,
     uiBundleName,
     permsetNamesExplicit,
     yes,
-    skipLogin: argSkipLogin,
     skipDeploy: argSkipDeploy,
     skipPermset: argSkipPermset,
     skipRole: argSkipRole,
@@ -957,8 +1240,17 @@ async function main() {
     skipData: argSkipData,
     skipGraphql: argSkipGraphql,
     skipUIBundleBuild: argSkipUIBundleBuild,
-    skipDev: argSkipDev,
-  } = parseArgs();
+  } = parsed;
+
+  // Resolve the target org up front (spec §5.4): 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 +1261,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);
@@ -979,12 +1271,29 @@ async function main() {
   const selfRegConfig = loadSelfRegConfig(config);
   const hasSelfRegConfig = selfRegConfig !== null;
 
+  // Validate the selfRegProfile name for SOQL-safety up front (spec §5.3, AC-8),
+  // 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 M1 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
   // 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 (spec §5.6, AC-13): it is an unconditional
+  // precondition run before deploy, not a toggleable step. The dev step is also
+  // gone (spec §5.5): launching the dev server moved to `npm run dev:preview`, so
+  // setup terminates cleanly after graphql (AC-11).
   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 },
@@ -992,7 +1301,6 @@ async function main() {
     { key: 'selfReg', label: 'Self-Registration — enable for site', enabled: !argSkipSelfReg && hasSelfRegConfig, available: hasSelfRegConfig, 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,7 +1309,6 @@ async function main() {
     on[s.key] = selections[i];
   });
 
-  const skipLogin = !on.login;
   const skipUIBundleBuild = !on.uiBundleBuild;
   const skipDeploy = !on.deploy;
   const skipPermset = !on.permset;
@@ -1009,41 +1316,35 @@ async function main() {
   const skipSelfReg = !on.selfReg;
   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 data=%s graphql=%s uiBundle=%s',
     !skipDeploy,
     !skipPermset,
     !skipRole,
     !skipSelfReg,
     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 (spec §5.6, AC-13): 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 +1389,19 @@ async function main() {
   const deployStep = stepDefs.find((s) => s.key === 'deploy');
   if (!skipDeploy) {
     await runStep(deployStep, targetOrg, () => {
+      // License pre-check (spec §5.3): 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 +1440,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,20 +1510,32 @@ 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, () => {
-      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);
-    });
+    // M1 license pre-check (spec §5.3): 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');
   }
@@ -1233,7 +1559,9 @@ 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) {
       const apexCode = [
         'try {',
@@ -1246,7 +1574,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',
@@ -1255,7 +1583,6 @@ 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
@@ -1294,7 +1621,7 @@ async function main() {
           const batch = records.slice(i, i + batchSize);
           const refIds = batch.map((r) => r.attributes?.referenceId || `_idx${i}`);
           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],
@@ -1323,7 +1650,7 @@ async function main() {
         console.log(`  ${entry.sobject}: imported ${imported} records`);
       }
     }
-    if (existsSync(tmpApex)) unlinkSync(tmpApex);
+    });
    });
   } else {
     recordSkipped(dataStep, dataStep.available ? 'not selected' : 'no data plan');
@@ -1360,29 +1687,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 (spec §5.5, AC-11). 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());
 }