catalyst-core 0.3.0-canary.2 → 0.3.0-canary.3

package/changelog.md

@@ -78,7 +78,7 @@ The app contract validators in `server/utils/validator.js` used to log a bare me
 
 The route and store checks moved out of the per-request path. `validateGetRoutes` and `validateConfigureStore` now run once when the renderer module loads — at server startup in production, and on the first SSR request in development, where the handler is loaded lazily — rather than once per request inside the handler's `try`/`catch`. The shape of `addMiddlewares` from `server/server.js` is checked during server setup.
 
-Module aliases and `config/config.json` keys are not checked at load time; a missing alias or key still surfaces where it is used. An application that satisfies the contract sees no change. The full contract — the files Catalyst imports by fixed path and the required module aliases — is documented under File Conventions.
+Separately, `catalyst start`, `build` and `serve` now check `config/config.json` and `package.json` before starting and exit with a coded error when either is missing, a required config key is missing, or a required module alias is missing. An application that satisfies the contract sees no change. The full contract — the files Catalyst imports by fixed path and the required module aliases — is documented under File Conventions.
 The webpack-era keys `WEBPACK_DEV_SERVER_HOSTNAME`, `WEBPACK_DEV_SERVER_PORT` and `ANALYZE_BUNDLE` are no longer required or read; remove them from `config/config.json`.
 
 ## [0.3.0-beta.5] - 2026-08-18

package/dist/errors/registry.js

@@ -28,7 +28,9 @@ export const ERROR_CODES = {
 
     BUNDLE_UPSTREAM_ERROR: "BUNDLE-000",
     IOS_UPSTREAM_ERROR: "IOS-000",
+    IOS_SIMULATOR_APP_NOT_FOUND: "IOS-001",
     ANDROID_UPSTREAM_ERROR: "ANDROID-000",
+    ANDROID_EMULATOR_BOOT_TIMEOUT: "ANDROID-001",
 
     RUNTIME_NATIVE_PERMISSION_DENIED: "RUNTIME-NATIVE-001",
     RUNTIME_NATIVE_PERMISSION_REQUIRED: "RUNTIME-NATIVE-002",
@@ -231,12 +233,27 @@ export const ERROR_DEFINITIONS = {
         defaultDetails: "This wraps an error from Xcode/CocoaPods. See the printed upstream output for the cause.",
         suggestedAction: "Read the upstream Xcode/CocoaPods error printed above and fix the underlying issue.",
     },
+    [ERROR_CODES.IOS_SIMULATOR_APP_NOT_FOUND]: {
+        category: "IOS",
+        defaultMessage: "Could not find an installed iOS Simulator app",
+        defaultDetails:
+            "Neither DeviceHub.app (Xcode 27+, bundle id com.apple.dt.Devices) nor the legacy Simulator.app (bundle id com.apple.iphonesimulator) is installed under Xcode's Contents/Applications. The simulator itself may still boot headlessly via simctl, but catalyst-core cannot open or focus its window.",
+        suggestedAction: "Confirm a full Xcode.app (not just Command Line Tools) is installed and selected via xcode-select -p, then reopen it once from Spotlight so macOS registers its app bundle.",
+    },
     [ERROR_CODES.ANDROID_UPSTREAM_ERROR]: {
         category: "ANDROID",
         defaultMessage: "Android build failed in an upstream toolchain step",
         defaultDetails: "This wraps an error from Gradle. See the printed upstream output for the cause.",
         suggestedAction: "Read the upstream Gradle error printed above and fix the underlying issue.",
     },
+    [ERROR_CODES.ANDROID_EMULATOR_BOOT_TIMEOUT]: {
+        category: "ANDROID",
+        defaultMessage: "Timed out waiting for the Android emulator to boot",
+        defaultDetails:
+            "buildApp:android launched the configured AVD but it did not appear in `adb devices` or did not finish booting (sys.boot_completed=1 and init.svc.bootanim=stopped) within the timeout.",
+        suggestedAction:
+            "Try booting the AVD manually first (emulator -avd <name>) to see the actual startup error, check available disk space/RAM, or increase the emulator's cold-boot allowance if the device is unusually slow.",
+    },
 
     [ERROR_CODES.RUNTIME_NATIVE_PERMISSION_DENIED]: {
         category: "RUNTIME-NATIVE",

package/dist/errors-index.json

@@ -244,6 +244,13 @@
         "suggestedAction": "Read the upstream Xcode/CocoaPods error printed above and fix the underlying issue.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-000.md"
     },
+    "IOS-001": {
+        "category": "IOS",
+        "message": "Could not find an installed iOS Simulator app",
+        "details": "Neither DeviceHub.app (Xcode 27+, bundle id com.apple.dt.Devices) nor the legacy Simulator.app (bundle id com.apple.iphonesimulator) is installed under Xcode's Contents/Applications. The simulator itself may still boot headlessly via simctl, but catalyst-core cannot open or focus its window.",
+        "suggestedAction": "Confirm a full Xcode.app (not just Command Line Tools) is installed and selected via xcode-select -p, then reopen it once from Spotlight so macOS registers its app bundle.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-001.md"
+    },
     "ANDROID-000": {
         "category": "ANDROID",
         "message": "Android build failed in an upstream toolchain step",
@@ -251,6 +258,13 @@
         "suggestedAction": "Read the upstream Gradle error printed above and fix the underlying issue.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/ANDROID/ANDROID-000.md"
     },
+    "ANDROID-001": {
+        "category": "ANDROID",
+        "message": "Timed out waiting for the Android emulator to boot",
+        "details": "buildApp:android launched the configured AVD but it did not appear in `adb devices` or did not finish booting (sys.boot_completed=1 and init.svc.bootanim=stopped) within the timeout.",
+        "suggestedAction": "Try booting the AVD manually first (emulator -avd <name>) to see the actual startup error, check available disk space/RAM, or increase the emulator's cold-boot allowance if the device is unusually slow.",
+        "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/ANDROID/ANDROID-001.md"
+    },
     "RUNTIME-NATIVE-001": {
         "category": "RUNTIME-NATIVE",
         "message": "Permission denied",

package/dist/native/buildAndroid/build.js

@@ -2,6 +2,10 @@
 
 const fs = require("fs");
 const path = require("path");
+const {
+  spawn,
+  execFileSync
+} = require("child_process");
 const {
   buildAndroidAAB
 } = require("../renameAndroidProject.js");
@@ -101,36 +105,176 @@ function createBuildPhase(ctx) {
       return false;
     }
   }
+
+  // Returns the serial of an online emulator (adb state "device"), or null if
+  // none is online. `devices.includes("emulator")` alone would also match a
+  // serial like "emulator-5554" whose state is "offline" or still enumerating —
+  // i.e. a device that's connected but not actually ready — so this checks the
+  // state column explicitly rather than doing a substring match.
   async function checkEmulator(ADB_PATH) {
     try {
       // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - ADB_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
       const devices = ctx.runCommand(`${ADB_PATH} devices`);
-      return devices.includes("emulator");
+      const onlineEmulator = devices.split("\n").map(line => line.trim().split(/\s+/)).find(([id, state]) => id?.startsWith("emulator-") && state === "device");
+      return onlineEmulator ? onlineEmulator[0] : null;
     } catch (error) {
       progress.log("Error checking emulator status: " + error.message, "error");
-      return false;
+      return null;
     }
   }
+
+  // The Android emulator binary is a long-running server process — it does not
+  // exit after boot, it keeps running until the emulator window is closed. Using
+  // runInteractiveCommand (which only resolves on the child's `close` event, see
+  // utils.js) would block forever waiting for an exit that never happens before
+  // the app finishes booting. Spawn it detached instead (same approach as
+  // androidSetup.js's startEmulator) and let handleEmulatorSetup poll for
+  // readiness separately.
+  /**
+   * Launch the emulator detached and return once it has actually spawned
+   * (not once it exits — see the note above on why runInteractiveCommand
+   * can't be used here).
+   * @returns {Promise<number>} the spawned process's pid, so a caller whose
+   *   boot-readiness wait times out can kill it instead of leaving a
+   *   CPU/RAM-heavy orphaned emulator running past a failed build.
+   */
   async function startEmulator(EMULATOR_PATH, androidConfig) {
     progress.log(`Starting emulator: ${androidConfig.emulatorName}...`, "info");
-    // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - EMULATOR_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
-    return ctx.runInteractiveCommand(EMULATOR_PATH, ["-avd", androidConfig.emulatorName, "-read-only"], {}).then(() => {
-      progress.log("Emulator started successfully", "success");
-    }).catch(error => {
-      progress.log("Error starting emulator: " + error.message, "error");
-      throw error;
+    return new Promise((resolve, reject) => {
+      // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - spawn with an argv array (no shell), so androidConfig.emulatorName can't be interpreted as shell syntax even though it comes from a locally-editable config file.
+      const child = spawn(EMULATOR_PATH, ["-avd", androidConfig.emulatorName, "-read-only"], {
+        detached: true,
+        stdio: "ignore"
+      });
+      child.once("error", error => {
+        progress.log("Error starting emulator: " + error.message, "error");
+        reject(error);
+      });
+      // "error" only fires for spawn failures (e.g. bad EMULATOR_PATH); once the
+      // process has actually spawned we can detach and let the caller poll adb
+      // for boot readiness rather than waiting on this child at all.
+      child.once("spawn", () => {
+        const {
+          pid
+        } = child;
+        child.unref();
+        progress.log("Emulator process started, waiting for it to boot...", "info");
+        resolve(pid);
+      });
     });
   }
+
+  // Best-effort cleanup for an emulator process this build spawned but that
+  // never became ready — kills the whole detached process group (negative pid)
+  // so we don't leave a CPU/RAM-heavy orphaned emulator running after a failed
+  // build. Never throws: a failure here shouldn't mask the original timeout error.
+  function killOrphanedEmulator(pid, emulatorName) {
+    try {
+      process.kill(-pid, "SIGTERM");
+      progress.log(`Stopped orphaned emulator process (pid ${pid}) after boot failure`, "info");
+    } catch (error) {
+      progress.log(`Could not stop orphaned emulator "${emulatorName}" (pid ${pid}): ${error.message}. ` + "You may need to quit it manually.", "warning");
+    }
+  }
+  function listEmulatorSerials(ADB_PATH) {
+    try {
+      // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - ADB_PATH is derived from androidConfig.sdkPath, a trusted internal config value.
+      const devices = ctx.runCommand(`${ADB_PATH} devices`);
+      return devices.split("\n").map(line => line.trim().split(/\s+/)[0]).filter(id => id && id.startsWith("emulator-"));
+    } catch {
+      return [];
+    }
+  }
+
+  // Waits for a NEW emulator-XXXX serial to appear in `adb devices` (one not in
+  // knownSerials, captured before startEmulator was called), so boot polling can
+  // be scoped to the emulator this build just launched rather than whichever
+  // device `adb shell` (with no -s) happens to pick when multiple are connected.
+  async function waitForNewEmulatorSerial(ADB_PATH, knownSerials, {
+    timeoutMs = 30000,
+    pollIntervalMs = 1000
+  } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const current = listEmulatorSerials(ADB_PATH);
+      const newSerial = current.find(id => !knownSerials.includes(id));
+      if (newSerial) return newSerial;
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+    return null;
+  }
+
+  /**
+   * Poll a specific emulator (by adb serial, e.g. "emulator-5554") until it
+   * reports a completed boot and a stopped boot animation, or the timeout
+   * elapses.
+   * @param {string} ADB_PATH Path to the adb executable.
+   * @param {string} serial The emulator's adb serial to target (adb -s).
+   * @param {Object} [options]
+   * @param {number} [options.timeoutMs=120000] Overall deadline in milliseconds.
+   * @param {number} [options.pollIntervalMs=2000] Delay between readiness checks.
+   * @returns {Promise<boolean>} true once both readiness signals are observed;
+   *   false if the deadline elapses first (a transient/hung adb call counts
+   *   against the same deadline via the per-call execFileSync timeout below).
+   */
+  async function waitForEmulatorBoot(ADB_PATH, serial, {
+    timeoutMs = 120000,
+    pollIntervalMs = 2000
+  } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    const getprop = prop => {
+      const remaining = Math.max(deadline - Date.now(), 1000);
+      return execFileSync(ADB_PATH, ["-s", serial, "shell", "getprop", prop], {
+        encoding: "utf8",
+        timeout: remaining
+      }).trim();
+    };
+    while (Date.now() < deadline) {
+      try {
+        const bootCompleted = getprop("sys.boot_completed");
+        const bootAnimDone = getprop("init.svc.bootanim");
+        if (bootCompleted === "1" && bootAnimDone === "stopped") return true;
+      } catch {
+        // adb not ready yet (device still enumerating), or this call hit its
+        // own per-call timeout — either way, keep polling against the outer
+        // deadline rather than treating it as fatal.
+      }
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+    return false;
+  }
+
+  // Message mirrors errors/registry.js ERROR_DEFINITIONS[ANDROID-001] (see
+  // errors/ANDROID/ANDROID-001.md) — this CJS subtree can't import the ESM
+  // error registry (see buildErrorFormat.js), so the code is prefixed onto the
+  // thrown message directly rather than imported.
+  function emulatorBootTimeoutError(detail) {
+    return new Error(`[ANDROID-001] Timed out waiting for the Android emulator to boot: ${detail}`);
+  }
   async function handleEmulatorSetup(ADB_PATH, EMULATOR_PATH, androidConfig) {
     progress.log("Setting up emulator...", "info");
-    const emulatorRunning = await checkEmulator(ADB_PATH);
-    if (!emulatorRunning) {
+    let serial = await checkEmulator(ADB_PATH);
+    let pid = null;
+    if (!serial) {
       progress.log("No emulator running, attempting to start one...", "info");
-      await startEmulator(EMULATOR_PATH, androidConfig);
-      await new Promise(resolve => setTimeout(resolve, 5000));
+      const knownSerials = listEmulatorSerials(ADB_PATH);
+      pid = await startEmulator(EMULATOR_PATH, androidConfig);
+      serial = await waitForNewEmulatorSerial(ADB_PATH, knownSerials);
+      if (!serial) {
+        killOrphanedEmulator(pid, androidConfig.emulatorName);
+        throw emulatorBootTimeoutError(`emulator "${androidConfig.emulatorName}" never appeared in adb devices`);
+      }
     } else {
-      progress.log("Emulator already running", "success");
+      progress.log(`Emulator ${serial} already online, confirming it's fully booted...`, "info");
+    }
+    // Wait for boot readiness whether the emulator was already online (it may
+    // still be finishing its boot animation) or was just launched above.
+    const booted = await waitForEmulatorBoot(ADB_PATH, serial);
+    if (!booted) {
+      if (pid) killOrphanedEmulator(pid, androidConfig.emulatorName);
+      throw emulatorBootTimeoutError(`emulator "${androidConfig.emulatorName}" (${serial}) never finished booting`);
     }
+    progress.log("Emulator booted successfully", "success");
     return {
       type: "emulator",
       name: androidConfig.emulatorName
@@ -286,6 +430,7 @@ function createBuildPhase(ctx) {
     checkEmulator,
     handleEmulatorSetup,
     startEmulator,
+    waitForEmulatorBoot,
     buildApp,
     launchApp,
     createAABConfig,

package/dist/native/buildIos/build.js

@@ -72,6 +72,33 @@ module.exports = function createBuildPhase(ctx) {
     }
   }
 
+  // Xcode 27 replaced the standalone Simulator.app (com.apple.iphonesimulator)
+  // with DeviceHub.app (com.apple.dt.Devices); older Xcode installs still ship
+  // the former. Resolve whichever is actually installed instead of hardcoding
+  // the app name, which no longer resolves via `open -a` on either app.
+  function resolveSimulatorAppBundleId() {
+    const candidates = ["com.apple.dt.Devices", "com.apple.iphonesimulator"];
+    for (const bundleId of candidates) {
+      try {
+        execSync(`osascript -e 'id of app id "${bundleId}"'`, {
+          stdio: "ignore"
+        }); // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - bundleId is a fixed internal candidate list, not user input.
+        return bundleId;
+      } catch {
+        // Not installed under this bundle id; try the next candidate.
+      }
+    }
+    return null;
+  }
+
+  // Text mirrors errors/registry.js ERROR_DEFINITIONS[IOS-001] (see
+  // errors/IOS/IOS-001.md) — this CJS subtree can't import the ESM error
+  // registry (see buildErrorFormat.js), so the message is duplicated here
+  // rather than imported. This condition is recoverable (the simulator can
+  // still boot headlessly via simctl) so callers log it as a warning
+  // instead of throwing.
+  const SIMULATOR_APP_NOT_FOUND_WARNING = "[IOS-001] Could not find an installed iOS Simulator app (checked DeviceHub.app and the legacy Simulator.app). " + "The simulator is booted but its window may not be visible. Suggested action: confirm a full Xcode.app is installed and selected via xcode-select -p, then open it once from Spotlight.";
+
   // ─── Clean ────────────────────────────────────────────────────────────────
 
   async function cleanBuildArtifacts() {
@@ -304,7 +331,12 @@ module.exports = function createBuildPhase(ctx) {
   }
   async function focusSimulator() {
     console.log("Focusing on Simulator...");
-    await runCommand(`osascript -e 'tell application "Simulator" to activate'`);
+    const simulatorAppBundleId = resolveSimulatorAppBundleId();
+    if (!simulatorAppBundleId) {
+      progress.log(SIMULATOR_APP_NOT_FOUND_WARNING, "warning");
+      return;
+    }
+    await runCommand(`osascript -e 'tell application id "${simulatorAppBundleId}" to activate'`);
   }
   async function installAndLaunchApp(APP_PATH) {
     progress.start("install");
@@ -326,6 +358,60 @@ module.exports = function createBuildPhase(ctx) {
 
   // ─── Physical device ──────────────────────────────────────────────────────
 
+  // `instruments -s devices` is deprecated and its plain-text output is fragile
+  // to parse. `xcrun devicectl list devices --json-output <path>` is the modern,
+  // structured replacement (Xcode 15+) and is already used elsewhere in this
+  // file for install/launch, so use it as the primary detection source too.
+  // Note: devicectl lists simulators as well as physical devices, so filter on
+  // hardwareProperties.reality === "physical".
+  //
+  // Write to a temp file rather than `--json-output -` (stdout): Apple's own
+  // scripting guidance is a file path, and stdout support for `-` isn't
+  // guaranteed across every Xcode version this needs to run on — a temp file
+  // works the same way on every devicectl version. Falls back to
+  // xcodebuild -showdestinations below on any failure (old devicectl, no
+  // physical device, malformed output), so this only needs to work when it can.
+  // Matches the identifier format Apple's own tooling uses (hex digits and
+  // hyphens only, e.g. a UUID or the shorter legacy 40-char UDID). device.udid
+  // is later interpolated unquoted into shell command strings (xcodebuild
+  // -destination, xcrun devicectl --device, see installAndLaunchOnPhysicalDevice
+  // and buildProjectForPhysicalDevice) — the old instruments-based parser
+  // structurally constrained what could reach that string via its own regex;
+  // this is the equivalent guard for the JSON-based devicectl path, so a
+  // malformed or hostile identifier in devicectl's output can't inject shell
+  // syntax rather than just being rejected as "not a device".
+  const VALID_UDID_RE = /^[A-Fa-f0-9-]+$/;
+  function tryDevicectl() {
+    const tmpPath = path.join(os.tmpdir(), `catalyst-devicectl-${process.pid}-${Date.now()}.json`);
+    try {
+      execSync(`xcrun devicectl list devices --json-output "${tmpPath}"`); // nosemgrep: javascript.lang.security.audit.dangerous-spawn-shell-command.dangerous-spawn-shell-command - tmpPath is built from os.tmpdir()/process.pid/Date.now(), not user input.
+      const raw = fs.readFileSync(tmpPath, "utf8");
+      const parsed = JSON.parse(raw);
+      const devices = parsed?.result?.devices ?? [];
+      return devices.filter(d => d.hardwareProperties?.reality === "physical")
+      // devicectl lists every device it has ever paired with, reachable or
+      // not — a device that's unplugged or out of range still shows up with
+      // reality: "physical". Only tunnelState !== "unavailable" is actually
+      // installable/launchable right now; "disconnected" (paired, USB/Wi-Fi
+      // not currently active but developer-mode discoverable) still works for
+      // wired installs, so only "unavailable" is excluded here.
+      .filter(d => d.connectionProperties?.tunnelState !== "unavailable").map(d => ({
+        name: d.deviceProperties?.name ?? "Physical Device",
+        version: d.deviceProperties?.osVersionNumber ?? "Unknown",
+        udid: d.hardwareProperties?.udid ?? d.identifier,
+        type: "physical"
+      })).filter(d => typeof d.udid === "string" && VALID_UDID_RE.test(d.udid));
+    } catch (error) {
+      progress.log(`devicectl detection failed (${error.message}); falling back to xcodebuild destinations`, "warning");
+      return [];
+    } finally {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // Nothing to clean up if the command failed before writing the file.
+      }
+    }
+  }
   async function detectPhysicalDevices() {
     progress.start("deviceDetection");
     const {
@@ -337,57 +423,19 @@ module.exports = function createBuildPhase(ctx) {
       const configuredUDID = iosConfig.deviceUDID;
       if (configuredUDID) {
         progress.log(`Using configured device UDID: ${configuredUDID}`, "info");
-        try {
-          const instrumentsOutput = execSync("instruments -s devices").toString();
-          if (instrumentsOutput.includes(configuredUDID)) {
-            const deviceLine = instrumentsOutput.split("\n").find(line => line.includes(configuredUDID));
-            if (deviceLine) {
-              const nameMatch = deviceLine.match(/^(.+?)\s+\(/);
-              const versionMatch = deviceLine.match(/\((\d+\.\d+(?:\.\d+)?)\)/);
-              const deviceName = nameMatch ? nameMatch[1].trim() : "Physical Device";
-              const deviceVersion = versionMatch ? versionMatch[1] : "Unknown";
-              progress.log(`✅ Found configured physical device: ${deviceName} (${deviceVersion})`, "success");
-              physicalDevices.push({
-                name: deviceName,
-                version: deviceVersion,
-                udid: configuredUDID,
-                type: "physical"
-              });
-              progress.complete("deviceDetection");
-              return physicalDevices[0];
-            }
-          } else {
-            progress.log(`⚠️  Configured device UDID not found in connected devices`, "warning");
-            progress.log("Falling back to auto-detection...", "info");
-          }
-        } catch (error) {
-          progress.log(`Error verifying configured device: ${error.message}`, "warning");
-          progress.log("Falling back to auto-detection...", "info");
+        const configuredDevice = tryDevicectl().find(d => d.udid === configuredUDID);
+        if (configuredDevice) {
+          progress.log(`✅ Found configured physical device: ${configuredDevice.name} (${configuredDevice.version})`, "success");
+          progress.complete("deviceDetection");
+          return configuredDevice;
         }
+        progress.log(`⚠️  Configured device UDID not found in connected devices`, "warning");
+        progress.log("Falling back to auto-detection...", "info");
       } else {
         progress.log("No device UDID configured, using auto-detection", "info");
       }
-      const tryInstruments = () => {
-        try {
-          const out = execSync("instruments -s devices").toString();
-          return out.split("\n").filter(line => {
-            const m = line.match(/^(.+?)\s+\((\d+\.\d+(?:\.\d+)?)\)\s+\[([A-F0-9-]{36})\](?:\s+\(Simulator\))?$/);
-            return m && !line.includes("(Simulator)");
-          }).map(line => {
-            const [, name, version, udid] = line.match(/^(.+?)\s+\((\d+\.\d+(?:\.\d+)?)\)\s+\[([A-F0-9-]{36})\]/);
-            return {
-              name: name.trim(),
-              version,
-              udid,
-              type: "physical"
-            };
-          });
-        } catch {
-          return [];
-        }
-      };
-      physicalDevices = tryInstruments();
-      if (physicalDevices.length > 0) progress.log(`Found ${physicalDevices.length} physical device(s) via instruments`, "success");
+      physicalDevices = tryDevicectl();
+      if (physicalDevices.length > 0) progress.log(`Found ${physicalDevices.length} physical device(s) via devicectl`, "success");
       if (physicalDevices.length === 0) {
         try {
           const xcodebuildOutput = execSync(`xcodebuild -scheme "${SCHEME_NAME}" -showdestinations` // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process - SCHEME_NAME is generated from trusted iOS project config.
@@ -417,25 +465,6 @@ module.exports = function createBuildPhase(ctx) {
           progress.log(`Error: ${error.message}`, "error");
         }
       }
-      if (physicalDevices.length === 0) physicalDevices = tryInstruments();
-      if (physicalDevices.length === 0) {
-        try {
-          for (const line of execSync("xcrun devicectl list devices").toString().split("\n")) {
-            if (line.includes("Connected") && !line.includes("Simulator")) {
-              const udidMatch = line.match(/([A-F0-9-]{36})/);
-              const nameMatch = line.match(/^(.+?)\s+\(/);
-              if (udidMatch && nameMatch) physicalDevices.push({
-                name: nameMatch[1].trim(),
-                version: "Unknown",
-                udid: udidMatch[1],
-                type: "physical"
-              });
-            }
-          }
-        } catch {
-          progress.log("devicectl command not available or failed", "warning");
-        }
-      }
       if (physicalDevices.length > 0) {
         progress.log(`Found ${physicalDevices.length} physical device(s):`, "success");
         physicalDevices.forEach(d => progress.log(`  📱 ${d.name} (${d.version || "Unknown iOS"}) - ${d.udid}`, "info"));
@@ -561,15 +590,26 @@ module.exports = function createBuildPhase(ctx) {
     try {
       progress.log("Launching iOS Simulator...");
       const simulatorsJson = JSON.parse(execSync("xcrun simctl list devices -j").toString());
+      // Multiple devices can share a name across runtimes (e.g. leftover devices
+      // from an old Xcode install after an upgrade) — simctl marks the ones whose
+      // runtime bundle is gone as isAvailable: false, and those fail to boot with
+      // "cannot determine the runtime bundle". Don't let iteration order silently
+      // pick one of those over the available device: prefer an available match,
+      // and among available matches prefer one that's already booted.
+      const isDeviceAvailable = device => device.isAvailable !== false;
       let foundSimulator = null,
         foundSimulatorId = null,
         isBooted = false;
       Object.entries(simulatorsJson.devices).forEach(([, devices]) => {
         devices.forEach(device => {
-          if (device.name === simulatorName) {
+          if (device.name !== simulatorName) return;
+          const available = isDeviceAvailable(device);
+          const alreadyBooted = device.state === "Booted";
+          const isBetterMatch = !foundSimulator || available && !isDeviceAvailable(foundSimulator) || available === isDeviceAvailable(foundSimulator) && alreadyBooted && !isBooted;
+          if (isBetterMatch) {
             foundSimulator = device;
             foundSimulatorId = device.udid;
-            isBooted = device.state === "Booted";
+            isBooted = alreadyBooted;
           }
         });
       });
@@ -600,10 +640,15 @@ module.exports = function createBuildPhase(ctx) {
       } else {
         progress.log(`Simulator ${simulatorName} is already booted`, "success");
       }
-      progress.log("Opening Simulator.app...");
-      await runCommand("open -a Simulator");
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      await runCommand("osascript -e 'tell application \"Simulator\" to activate'");
+      const simulatorAppBundleId = resolveSimulatorAppBundleId();
+      if (simulatorAppBundleId) {
+        progress.log("Opening simulator UI...");
+        await runCommand(`open -b ${simulatorAppBundleId}`);
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        await runCommand(`osascript -e 'tell application id "${simulatorAppBundleId}" to activate'`);
+      } else {
+        progress.log(SIMULATOR_APP_NOT_FOUND_WARNING, "warning");
+      }
       progress.log("iOS Simulator launched successfully.", "success");
       progress.complete("launchSimulator");
     } catch (error) {

package/dist/native/buildIos/config.js

@@ -161,6 +161,7 @@ public enum ConfigConstants {
         for (const [key, value] of Object.entries(iosConfig)) {
           if (addedKeys.has(key)) continue;
           configContent += "\n" + generateSwiftProperty(key, value);
+          addedKeys.add(key);
         }
       }
       if (WEBVIEW_CONFIG.accessControl) {
@@ -220,6 +221,16 @@ public enum ConfigConstants {
         configContent += '\n    public static let appInfo = ""';
         addedKeys.add("appInfo");
       }
+
+      // Ensure cachePattern always exists (default to no patterns, i.e. caching
+      // opt-in disabled) — CacheManager.swift references ConfigConstants.cachePattern
+      // unconditionally, and it's only emitted above when WEBVIEW_CONFIG.ios.cachePattern
+      // is set, which every create-catalyst-app scaffold omits by default (#485).
+      if (!addedKeys.has("cachePattern")) {
+        progress.log("cachePattern not found in config, adding default (no patterns)", "info");
+        configContent += "\n" + generateSwiftProperty("cachePattern", []);
+        addedKeys.add("cachePattern");
+      }
       configContent += `\n}`;
       fs.writeFileSync(appConfigPath, configContent, "utf8");
       progress.log("Configuration constants generated successfully (SPM Package)", "success");

package/dist/native/setupEmulatorIos.js

@@ -242,6 +242,32 @@ async function configureSimulator(config) {
 //     }
 // }
 
+// Xcode 27 replaced the standalone Simulator.app (com.apple.iphonesimulator)
+// with DeviceHub.app (com.apple.dt.Devices); older Xcode installs still ship
+// the former. Resolve whichever is actually installed instead of hardcoding
+// the app name, which no longer resolves via `open -a` on either app.
+function resolveSimulatorAppBundleId() {
+  const candidates = ["com.apple.dt.Devices", "com.apple.iphonesimulator"];
+  for (const bundleId of candidates) {
+    try {
+      (0, _child_process.execSync)(`osascript -e 'id of app id "${bundleId}"'`, {
+        stdio: "ignore"
+      });
+      return bundleId;
+    } catch {
+      // Not installed under this bundle id; try the next candidate.
+    }
+  }
+  return null;
+}
+
+// Text mirrors errors/registry.js ERROR_DEFINITIONS[IOS-001] (see
+// errors/IOS/IOS-001.md) — this CJS subtree can't import the ESM error
+// registry (see native/buildErrorFormat.js), so the message is duplicated
+// here rather than imported. This condition is recoverable (the simulator
+// can still boot headlessly via simctl) so callers log it as a warning
+// instead of throwing.
+const SIMULATOR_APP_NOT_FOUND_WARNING = "[IOS-001] Could not find an installed iOS Simulator app (checked DeviceHub.app and the legacy Simulator.app). " + "The simulator is booted but its window may not be visible. Suggested action: confirm a full Xcode.app is installed and selected via xcode-select -p, then open it once from Spotlight.";
 async function launchIOSSimulator(simulatorName) {
   progress.log("Launching iOS Simulator...");
   try {
@@ -285,15 +311,20 @@ async function launchIOSSimulator(simulatorName) {
       console.log(`Simulator ${simulatorName} is already booted`);
     }
 
-    // Open Simulator.app and focus
-    progress.log("Opening Simulator.app...");
-    (0, _utils.runCommand)("open -a Simulator");
+    // Open the simulator UI (DeviceHub on Xcode 27+, Simulator.app on older Xcode) and focus it
+    const simulatorAppBundleId = resolveSimulatorAppBundleId();
+    if (simulatorAppBundleId) {
+      progress.log("Opening simulator UI...");
+      (0, _utils.runCommand)(`open -b ${simulatorAppBundleId}`);
 
-    // Give the simulator a moment to open/focus
-    await new Promise(resolve => setTimeout(resolve, 1000));
+      // Give the simulator a moment to open/focus
+      await new Promise(resolve => setTimeout(resolve, 1000));
 
-    // Activate the Simulator.app window to bring it to front
-    (0, _utils.runCommand)("osascript -e 'tell application \"Simulator\" to activate'");
+      // Activate the simulator UI window to bring it to front
+      (0, _utils.runCommand)(`osascript -e 'tell application id "${simulatorAppBundleId}" to activate'`);
+    } else {
+      progress.log(SIMULATOR_APP_NOT_FOUND_WARNING, "warning");
+    }
     console.log("iOS Simulator launched successfully.");
   } catch (error) {
     console.error("Failed to launch iOS Simulator. Error:", error.message);

package/dist/scripts/loadEnvironmentVariables.js

@@ -24,7 +24,26 @@ const loadEnvironmentVariables = async () => {
             newConfig[key] =
                 typeof process.env[key] === "object" ? JSON.stringify(process.env[key]) : process.env[key]
         }
-        process.env = newConfig
+        // Merge config.json + filterKeys into the existing process.env instead of
+        // replacing it outright. start.js/serve.js forward the full parent
+        // process.env into this process (spawnSync(..., { env: { ...process.env, ... } }))
+        // specifically so arbitrary env vars (e.g. catalyst-ai's AI_CONFIG, or anything
+        // else a consumer/package expects to read from process.env) survive into the
+        // server process — a wholesale replace here silently discarded all of them
+        // except the small filterKeys allowlist, before any request handler got a
+        // chance to read them.
+        //
+        // Build the merge in a plain object and reassign process.env, rather than
+        // Object.assign(process.env, newConfig) directly: writing through the real
+        // process.env setter coerces every value to a string (process.env.X = true
+        // becomes the string "true"), which would break consumers that compare a
+        // config boolean strictly (e.g. expressServer.ts's
+        // `process.env.OTEL_ENABLE === true` — see its own comment noting it relies
+        // on process.env holding a real boolean here). Reassigning a plain object
+        // preserves the primitive types newConfig already carries, same as the
+        // original wholesale-replace behavior did for config.json values, while
+        // still keeping every pre-existing process.env entry via the spread.
+        process.env = { ...process.env, ...newConfig }
     } catch (error) {
         console.error("Error loading environment variables:", error)
         throw error

package/mcp_v2/lib/helpers.js

@@ -60,10 +60,20 @@ function findCatalystRoot() {
         let dir = start
         while (dir !== path.parse(dir).root) {
             const pkgPath = path.join(dir, "package.json")
+            // A package.json inside a node_modules segment is an installed copy, not
+            // the catalyst-core source repo itself — for the standard install layout
+            // (<app>/node_modules/catalyst-core/mcp_v2/mcp.js), walking up from
+            // __dirname hits catalyst-core's own installed package.json (name:
+            // "catalyst-core") before it ever reaches the consumer app's root. Only
+            // the isSourcePackage branch below should match on pkg.name, and only for
+            // a real (non-node_modules) source checkout — otherwise keep climbing so
+            // the walk finds the consumer's package.json instead, which matches via
+            // the deps["catalyst-core"] branch further down.
+            const isInstalledCopy = dir.split(path.sep).includes("node_modules")
             if (fs.existsSync(pkgPath)) {
                 try {
                     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"))
-                    if (pkg.name === "catalyst-core") {
+                    if (pkg.name === "catalyst-core" && !isInstalledCopy) {
                         const sourceVersion = pkg.version || null
                         return {
                             dir,
@@ -86,19 +96,21 @@ function findCatalystRoot() {
                     const deps = { ...pkg.dependencies, ...pkg.devDependencies }
                     const declaredRef = deps["catalyst-core"]
                     if (declaredRef) {
-                        const nmPath = path.join(dir, "node_modules", "catalyst-core")
-                        const installed = fs.existsSync(nmPath)
-                        // Read the actual installed version from node_modules
+                        // A fixed `<dir>/node_modules/catalyst-core` path only finds a
+                        // flat install. In a hoisted workspace (npm/yarn workspaces,
+                        // pnpm with hoisting) the package can live several levels above
+                        // `dir` instead. require.resolve with `paths` walks node_modules
+                        // up the tree the same way Node's own module resolution does, so
+                        // it finds the installed copy regardless of hoisting.
                         let installedVersion = null
-                        if (installed) {
-                            try {
-                                const nmPkg = JSON.parse(
-                                    fs.readFileSync(path.join(nmPath, "package.json"), "utf8")
-                                )
-                                installedVersion = nmPkg.version || null
-                            } catch {
-                                /* ignore */
-                            }
+                        let installed = false
+                        try {
+                            const nmPkgPath = require.resolve("catalyst-core/package.json", { paths: [dir] })
+                            const nmPkg = JSON.parse(fs.readFileSync(nmPkgPath, "utf8"))
+                            installedVersion = nmPkg.version || null
+                            installed = true
+                        } catch {
+                            /* not installed relative to dir */
                         }
                         const isGithubRef = declaredRef.startsWith("github:") || declaredRef.includes("#")
                         return {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "catalyst-core",
-    "version": "0.3.0-canary.2",
+    "version": "0.3.0-canary.3",
     "type": "module",
     "main": "./dist/index.jsx",
     "description": "Web framework that provides great performance out of the box",