catalyst-core 1.2.0-canary.3 → 1.2.0-canary.4

package/changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.2.0] - Unreleased
+
+This release builds, runs and releases the Android and iOS apps from the CLI, without opening Android Studio or Xcode. The web runtime has no breaking changes. Universal apps should read the breaking changes below and the 1.1.x to 1.2.0 section of the Version Upgrades guide. After upgrading, run `npm audit fix`: the `body-parser` floor is raised to `^1.20.9`.
+
+### One command to run, one to release
+
+New apps have four scripts. `npm run android` and `npm run ios` check the toolchain and install what is missing after asking, start the dev server when nothing answers on `NODE_SERVER_PORT`, and build, install and open the app on an emulator, simulator or phone. Android also saves the app as a debug APK in `build-output/android/debug/` that can be shared. `npm run android:release` writes a signed App Bundle, a signed APK and `upload_certificate.pem` to `build-output/android/<version>-<build>/`, and `npm run ios:release` writes a signed IPA and a zip of its dSYMs to `build-output/ios/<version>-<build>/`. The scripts run `catalyst buildApp:android` and `catalyst buildApp:ios`, with `--release` for the store builds, so older apps keep `buildApp:<platform>` and build a release with `npm run buildApp:<platform> -- --release`. `setupEmulator:android` and `setupEmulator:ios` still work and are no longer needed.
+
+### App config
+
+A native app needs `WEBVIEW_CONFIG.appId`, `appName` and `url`. `appId` is the Android application id and the iOS bundle id, and `android.packageName` and `ios.bundleIdentifier` (then `ios.appBundleId`) win over it. `url` is the deployed site a release opens; debug builds load the dev server. New apps get `appId` and `appName` from the project name. A release run in a terminal asks once for an app id or website that is missing or a placeholder, and saves the answer to `config/config.json`.
+
+### Signing
+
+Signing files live in `credentials/android/` and `credentials/ios/`, which new apps keep out of git. The first Android release in a terminal creates one upload key per app after asking; back it up, because Google Play only accepts updates signed with it. `npx catalyst credentials:export <platform>` prints the folder as one value for the `CATALYST_ANDROID_CREDENTIALS` or `CATALYST_IOS_CREDENTIALS` CI secret. On a Mac signed in to Xcode, an iOS release signs with the Apple account or an installed App Store profile and needs no files; the order the build tries is in the iOS release guide. The version comes from `package.json`, and the build number is `CATALYST_BUILD_NUMBER` or the minutes since 2024-01-01 UTC. Android apps target API 36 and align their native libraries for 16 KB memory pages.
+
+### Breaking changes
+
+- An iOS bundle id with an underscore fails with `NATIVE-010`. Set `ios.bundleIdentifier` to an id without one.
+- A release with a placeholder app id (any `com.example.` id or a template id) fails with `NATIVE-003`. A release whose start URL is `localhost`, a private or link-local address, a `.local` name or this machine fails with `NATIVE-001`, unless `WEBVIEW_CONFIG.allowPrivateHost` is `true`. Run in a terminal, the build asks for the value instead.
+- A debug build no longer installs on a connected phone by itself. A terminal run asks once where to run the app and remembers the answer in `.catalyst/local.json`; without a terminal the emulator or simulator is used. Pass `--device` for the phone.
+- The first debug build rewrites `config/config.json` once: a value equal to this machine's LAN address, and a private `LOCAL_IP` that `NODE_SERVER_HOSTNAME` also holds, go back to `localhost`. Each change is printed. It never runs for a release, in CI or with `allowPrivateHost: true`.
+- Keystore passwords in `android.keystoreConfig` and `android.keystore` are no longer used. Apps that uploaded a build signed with the keystore shipped in the template, or with a key generated by an earlier release build, need an upload key reset in Play Console.
+
+### create-catalyst-app
+
+New apps get a new starter page, an animated HTML splash screen that is on by default (`splashScreen.minDuration` `7000`), a restyled offline page, a placeholder `public/icon.png`, and a `server/index.js` with an empty stub for `preServerInit` and each per-request hook. Their `.gitignore` covers `credentials/`, `.catalyst/` and `build-output/`.
+
+### Fixes
+
+- `MetaTag` waits for a `split()` route's chunk before it replaces the head tags, so the server's tags are no longer removed before the route's `setMetaData` is available.
+- Startup warns when `server/index.js` puts a lifecycle hook inside `export default { ... }`, where Catalyst never calls it. Export each hook by name.
+- `npm run start` prints a hint when `NODE_SERVER_HOSTNAME` is not an address of this machine.
+
 ## [1.1.0] - 2026-10-22
 
 This release contains everything in 1.0.2, namely the HTML splash screen, experimental WebMCP support and the new CLI output, plus one fix. There are no breaking API changes.

package/dist/cli/hints.js

@@ -27,6 +27,11 @@ const HINTS = [
                 : `Something is already on ${where}. Stop it, or set NODE_SERVER_PORT in config/config.json.`
         },
     },
+    {
+        test: /listen EADDRNOTAVAIL\b(?:.*?address not available\s+(\S+):\d+)?/i,
+        hint: (match) =>
+            `NODE_SERVER_HOSTNAME ${match[1] ? `${match[1]} ` : ""}is not an address of this machine; set it to localhost (or this machine's address) in config/config.json.`,
+    },
     {
         test: /SDK location not found|ANDROID_HOME/i,
         hint: () =>

package/dist/errors/registry.js

@@ -330,9 +330,9 @@ export const ERROR_DEFINITIONS = {
         category: "IOS",
         defaultMessage: "iOS code signing is not set up",
         defaultDetails:
-            "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for.",
+            "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
         suggestedAction:
-            "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+            "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
     },
     [ERROR_CODES.IOS_ASC_API_KEY_INVALID]: {
         category: "IOS",

package/dist/errors-index.json

@@ -226,8 +226,8 @@
     "IOS-010": {
         "category": "IOS",
         "message": "iOS code signing is not set up",
-        "details": "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for.",
-        "suggestedAction": "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+        "details": "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
+        "suggestedAction": "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-010.md"
     },
     "IOS-011": {

package/dist/native/buildAppIos.js

@@ -44,6 +44,7 @@ const {
   planSigningForConfig,
   readIosCredentials,
   resolveExportMethod,
+  settleInstalledProfile,
   settleXcodeTeam
 } = require("./buildIos/signing.js");
 const {
@@ -96,10 +97,11 @@ async function askAndSave(options) {
 /**
  * A release that will sign with the Apple account in Xcode needs
  * ios.developmentTeam. When it is unset, use the one team Xcode has that can
- * sign this export (or ask which, in a terminal). In a terminal the team is
- * saved to config/config.json; without one it is used for this build only.
- * Plans with planSigningForConfig, the same function createIosBuild signs
- * with. Returns the appConfig to build with.
+ * sign this export (or ask which, in a terminal). A release that auto-picked
+ * an installed App Store profile pins it as ios.provisioningProfile. In a
+ * terminal the team or profile is saved to config/config.json; without one
+ * it is used for this build only. Plans with planSigningForConfig, the same
+ * function createIosBuild signs with. Returns the appConfig to build with.
  *
  * Config and credential errors are left for createIosBuild, which reports
  * them the usual way.
@@ -140,6 +142,16 @@ async function ensureSigningTeam({
     found?.cleanup();
   }
   const file = path.join(cwd, "config", "config.json");
+  const profile = settleInstalledProfile({
+    plan,
+    log,
+    save: name => writeConfigKeys(file, {
+      "WEBVIEW_CONFIG.ios.provisioningProfile": name
+    }, {
+      log
+    })
+  });
+  if (profile?.saved) return loadAppConfig();
   const team = await settleXcodeTeam({
     plan,
     release,
@@ -193,7 +205,7 @@ async function main() {
       BUILD_OUTPUT_PATH
     };
     for (const change of migration.changes) {
-      log(`config.json ${change.path}: ${change.from} -> ${change.to}`, "info");
+      log(`config.json ${change.path}: ${change.from} -> ${change.to}`, "note");
     }
     const release = flags.release || isReleaseBuildType(appConfig.WEBVIEW_CONFIG?.ios?.buildType);
     // A store build in a terminal asks once for a missing app id or

package/dist/native/buildIos/index.js

@@ -35,6 +35,7 @@ const {
   createProfileScanner,
   pickInstalledProfile,
   XCODE_TEAM_HINT,
+  missingProfileError,
   buildExportOptions,
   writeExportOptionsPlist,
   isSigningFailure,
@@ -186,7 +187,11 @@ function createIosBuild(config, {
   const apiKey = release ? resolveApiKey() : null;
   if (release && signingPlan.style === "automatic" && !signingPlan.teamId) {
     credentials?.cleanup();
-    throw nativeError("IOS-010", "a signed release with automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam", signingPlan.source === "Xcode account" ? {
+    const detail = "a signed release with automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam";
+    const missing = missingProfileError(signingPlan.missingProfileFor, detail);
+    throw missing ? nativeError("IOS-010", missing.detail, {
+      hint: missing.hint
+    }) : nativeError("IOS-010", detail, signingPlan.source === "Xcode account" ? {
       hint: XCODE_TEAM_HINT
     } : {});
   }
@@ -611,7 +616,9 @@ function createIosBuild(config, {
       try {
         await runCommandStreaming("xcodebuild", ["archive", "-project", `${PROJECT_NAME}.xcodeproj`, "-scheme", SCHEME_NAME, "-configuration", "Release", "-destination", "generic/platform=iOS", "-archivePath", archivePath, ...signingArgs]);
       } catch (error) {
-        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the release archive", error) : error;
+        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the release archive", error, {
+          missingProfileFor: signing.missingProfileFor
+        }) : error;
         failure.stage = "Archiving the release build";
         throw failure;
       }
@@ -629,7 +636,9 @@ function createIosBuild(config, {
       try {
         await runCommandStreaming("xcodebuild", ["-exportArchive", "-archivePath", archivePath, "-exportPath", exportPath, "-exportOptionsPlist", optionsPlist, ...(signing.style === "automatic" ? xcodeAuthArgs(ctx.apiKey) : [])]);
       } catch (error) {
-        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the IPA for export", error) : error;
+        const failure = isSigningFailure(error.output) ? signingSetupError("Xcode could not sign the IPA for export", error, {
+          missingProfileFor: signing.missingProfileFor
+        }) : error;
         failure.stage = "Exporting the IPA";
         throw failure;
       }

package/dist/native/buildIos/signing.js

@@ -10,6 +10,7 @@ exports.createProfileScanner = createProfileScanner;
 exports.findInstalledProfileIdentity = findInstalledProfileIdentity;
 exports.isReleaseBuildType = isReleaseBuildType;
 exports.isSigningFailure = isSigningFailure;
+exports.missingProfileError = missingProfileError;
 exports.needsXcodeTeam = needsXcodeTeam;
 exports.parseIdentities = parseIdentities;
 exports.parseIdentity = parseIdentity;
@@ -27,6 +28,7 @@ exports.readProvisioningProfile = readProvisioningProfile;
 exports.readXcodeTeams = readXcodeTeams;
 exports.resolveExportMethod = resolveExportMethod;
 exports.scanInstalledProfiles = scanInstalledProfiles;
+exports.settleInstalledProfile = settleInstalledProfile;
 exports.settleXcodeTeam = settleXcodeTeam;
 exports.setupP12Signing = setupP12Signing;
 exports.signingFailureLine = signingFailureLine;
@@ -296,13 +298,19 @@ function planIosSigning({
   if (release && exportMethod === "app-store-connect" && bundleId && scanProfiles) {
     const scan = scanProfiles();
     const {
-      identity
+      identity,
+      missing
     } = pickInstalledProfile(scan, {
       bundleId,
       teamId,
       needsPush: notifications,
       now
     });
+    // Nothing else to sign with: IOS-010 leads with the missing profile.
+    if (missing) return {
+      ...automatic("Xcode account"),
+      missingProfileFor: bundleId
+    };
     if (identity) {
       // By name, as people know it, unless another installed profile shares it.
       const sameName = scan.profiles.filter(profile => profile.name === identity.profileName).length;
@@ -580,7 +588,9 @@ function isAppStoreProfile(profile) {
  * profile (.mobileprovision, no devices, get-task-allow false) for exactly
  * this bundle id, for `teamId` when set, with aps-environment when
  * `needsPush`. Expired profiles are skipped; the newest one whose
- * certificate is in the keychain wins. Without a match, `reason` says why.
+ * certificate is in the keychain wins. Without a match, `reason` says why,
+ * and `missing` is true when no App Store profile for the bundle id is
+ * installed at all.
  *
  * @param {ReturnType<typeof scanInstalledProfiles>} scan
  * @param {object} options
@@ -589,7 +599,7 @@ function isAppStoreProfile(profile) {
  * @param {string} [options.teamId]
  * @param {boolean} [options.needsPush]
  * @param {Date} [options.now]
- * @returns {{ identity: { sha1: string, name: string, teamId?: string, uuid: string, profileName?: string } | null, reason?: string }}
+ * @returns {{ identity: { sha1: string, name: string, teamId?: string, uuid: string, profileName?: string } | null, reason?: string, missing?: boolean }}
  */
 function pickInstalledProfile(scan, {
   profile,
@@ -611,13 +621,19 @@ function pickInstalledProfile(scan, {
   };
   let candidates = scan?.profiles || [];
   /** Keep the candidates that pass; when none does, that check is the reason. */
-  const steps = wanted ? [[c => c.name === wanted || String(c.uuid).toLowerCase() === wanted.toLowerCase(), () => "no installed profile has that name or UUID"], [c => !(c.expires && c.expires <= now.getTime()), left => `it expired on ${left[0].expirationDate}`], [c => profileMatchesBundleId(c.applicationIdentifier, bundleId), left => `it is for ${appIdOf(left[0])}, not ${bundleId}`]] : [[c => c.file.endsWith(".mobileprovision") && c.applicationIdentifier && appIdOf(c) === bundleId, () => `no installed profile is for exactly ${bundleId}`], [isAppStoreProfile, () => `no installed App Store profile is for ${bundleId}`], [c => !teamId || c.teamId === teamId, () => `no installed App Store profile for ${bundleId} is for team ${teamId}`], [c => !needsPush || Boolean(c.apsEnvironment), () => `no installed App Store profile for ${bundleId} has push notifications`], [c => !(c.expires && c.expires <= now.getTime()), () => `every installed App Store profile for ${bundleId} has expired`]];
-  for (const [keep, reason] of steps) {
+  const steps = wanted ? [[c => c.name === wanted || String(c.uuid).toLowerCase() === wanted.toLowerCase(), () => "no installed profile has that name or UUID"], [c => !(c.expires && c.expires <= now.getTime()), left => `it expired on ${left[0].expirationDate}`], [c => profileMatchesBundleId(c.applicationIdentifier, bundleId), left => `it is for ${appIdOf(left[0])}, not ${bundleId}`]] : [[c => c.file.endsWith(".mobileprovision") && c.applicationIdentifier && appIdOf(c) === bundleId, () => `no installed profile is for exactly ${bundleId}`, true], [isAppStoreProfile, () => `no installed App Store profile is for ${bundleId}`, true], [c => !teamId || c.teamId === teamId, () => `no installed App Store profile for ${bundleId} is for team ${teamId}`], [c => !needsPush || Boolean(c.apsEnvironment), () => `no installed App Store profile for ${bundleId} has push notifications`], [c => !(c.expires && c.expires <= now.getTime()), () => `every installed App Store profile for ${bundleId} has expired`]];
+  for (const [keep, reason, missing] of steps) {
     const left = candidates.filter(keep);
-    if (!left.length) return {
-      identity: null,
-      reason: reason(candidates)
-    };
+    if (!left.length) {
+      return missing ? {
+        identity: null,
+        reason: reason(candidates),
+        missing: true
+      } : {
+        identity: null,
+        reason: reason(candidates)
+      };
+    }
     candidates = left;
   }
   const newestFirst = [...candidates].sort((a, b) => b.expires - a.expires);
@@ -685,6 +701,25 @@ function findInstalledProfileIdentity({
 
 const XCODE_TEAM_HINT = exports.XCODE_TEAM_HINT = "Open Xcode > Settings > Accounts and sign in with the Apple account that has your company's team, or set WEBVIEW_CONFIG.ios.developmentTeam.";
 
+/**
+ * IOS-010's detail and hint for an App Store release that found no installed
+ * App Store profile for its bundle id (plan.missingProfileFor) and has no
+ * other signing source: the missing profile first, then every way to sign,
+ * the Xcode account last. Null for any other plan.
+ *
+ * @param {string | undefined} bundleId - plan.missingProfileFor
+ * @param {string} [detail] - what failed after that, e.g. the Xcode account
+ * @returns {{ detail: string, hint: string } | null}
+ */
+function missingProfileError(bundleId, detail) {
+  if (!bundleId) return null;
+  const missing = `no App Store provisioning profile for ${bundleId} is installed on this Mac`;
+  return {
+    detail: detail ? `${missing}, and ${detail}` : missing,
+    hint: `Install the App Store profile for ${bundleId} (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles), set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name, put a .p12 and its profile or an App Store Connect API key in credentials/ios/, or sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team.`
+  };
+}
+
 /**
  * The teams in IDEProvisioningTeamByIdentifier (account id -> teams), one
  * per team id. `free` is isFreeProvisioningTeam, undefined when Xcode did
@@ -753,31 +788,35 @@ function needsXcodeTeam(plan, {
  * Store, release-testing or enterprise export, so it is left out unless the
  * export is for debugging; a team Xcode did not mark either way is kept.
  * One team is used; several are a question, NATIVE-005 without a terminal;
- * none is IOS-010.
+ * none is IOS-010, which leads with `missingProfileFor` when that is set.
  *
  * @param {object} options
  * @param {ReturnType<typeof parseXcodeTeams>} options.teams - from readXcodeTeams
  * @param {string} [options.exportMethod]
  * @param {boolean} [options.isTTY]
  * @param {typeof select} [options.choose]
+ * @param {string} [options.missingProfileFor] - plan.missingProfileFor
  * @returns {Promise<{ teamId: string, teamName: string, free: boolean | undefined }>}
  */
 async function chooseXcodeTeam({
   teams,
   exportMethod = "app-store-connect",
   isTTY,
-  choose = _utils.select
+  choose = _utils.select,
+  missingProfileFor
 }) {
-  if (!teams) {
-    throw (0, _utils.nativeError)("IOS-010", "could not read which teams are signed in to Xcode", {
+  const noTeam = detail => {
+    const missing = missingProfileError(missingProfileFor, detail);
+    return missing ? (0, _utils.nativeError)("IOS-010", missing.detail, {
+      hint: missing.hint
+    }) : (0, _utils.nativeError)("IOS-010", detail, {
       hint: XCODE_TEAM_HINT
     });
-  }
+  };
+  if (!teams) throw noTeam("could not read which teams are signed in to Xcode");
   const usable = exportMethod === "debugging" ? teams : teams.filter(team => team.free !== true);
   if (!usable.length) {
-    throw (0, _utils.nativeError)("IOS-010", teams.length ? `Xcode is signed in with a personal team only, and a personal team cannot sign ${exportMethod} builds` : "no Apple account with a team is signed in to Xcode", {
-      hint: XCODE_TEAM_HINT
-    });
+    throw noTeam(teams.length ? `Xcode is signed in with a personal team only, and a personal team cannot sign ${exportMethod} builds` : "no Apple account with a team is signed in to Xcode");
   }
   if (usable.length === 1) return usable[0];
   const label = team => `${team.teamName || "Unnamed team"} (${team.teamId})`;
@@ -831,7 +870,8 @@ async function settleXcodeTeam({
     teams: readTeams(),
     exportMethod,
     isTTY: interactive,
-    choose
+    choose,
+    missingProfileFor: plan.missingProfileFor
   });
   const label = `${team.teamName || "Unnamed team"} (${team.teamId})`;
   if (!interactive) {
@@ -849,6 +889,44 @@ async function settleXcodeTeam({
   };
 }
 
+/**
+ * The profile step for a release that auto-picked an installed App Store
+ * profile (planIosSigning's "installed profile"): in a terminal save it as
+ * ios.provisioningProfile with `save`, so later builds sign with the same
+ * one; without a terminal (CI, agents) only use it for this build, since
+ * config.json is never written there. Null for any other plan.
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof planIosSigning>} options.plan - from planSigningForConfig
+ * @param {boolean} [options.isTTY] - defaults to isInteractive()
+ * @param {(profile: string) => void} options.save - writes WEBVIEW_CONFIG.ios.provisioningProfile
+ * @param {(message: string, type?: string) => void} [options.log]
+ * @returns {{ provisioningProfile: string, saved: boolean } | null}
+ */
+function settleInstalledProfile({
+  plan,
+  isTTY,
+  save,
+  log = () => {}
+}) {
+  if (plan?.source !== "installed profile") return null;
+  // The name, or the UUID when another installed profile shares the name.
+  const profile = plan.provisioningProfile;
+  if (!(isTTY ?? (0, _utils.isInteractive)())) {
+    log(`Using the installed profile "${plan.profileName}". Set WEBVIEW_CONFIG.ios.provisioningProfile to keep it.`, "note");
+    return {
+      provisioningProfile: profile,
+      saved: false
+    };
+  }
+  log(`Signing with the installed profile "${plan.profileName}" (team ${plan.teamId})`, "info");
+  save(profile);
+  return {
+    provisioningProfile: profile,
+    saved: true
+  };
+}
+
 /**
  * Local signing with credentials/ios/: import the .p12 into a temporary
  * keychain, put that keychain on the user search list, and install the
@@ -1103,15 +1181,24 @@ function signingFailureLine(output) {
 
 /**
  * The coded error for a signing failure, keeping xcodebuild's transcript for
- * the diagnostic. The detail ends with the line that says what went wrong.
+ * the diagnostic. The detail ends with the line that says what went wrong,
+ * and starts with the missing App Store profile when `missingProfileFor` is set.
  *
  * @param {string} detail
  * @param {any} [cause]
+ * @param {object} [options]
+ * @param {string} [options.missingProfileFor] - plan.missingProfileFor
  * @returns {any}
  */
-function signingSetupError(detail, cause) {
+function signingSetupError(detail, cause, {
+  missingProfileFor
+} = {}) {
   const said = signingFailureLine(cause?.output);
-  const error = (0, _utils.nativeError)("IOS-010", said ? `${detail}: ${said}` : detail);
+  const failed = said ? `${detail}: ${said}` : detail;
+  const missing = missingProfileError(missingProfileFor, failed);
+  const error = missing ? (0, _utils.nativeError)("IOS-010", missing.detail, {
+    hint: missing.hint
+  }) : (0, _utils.nativeError)("IOS-010", failed);
   if (cause) {
     error.cause = cause;
     if (cause.output) error.output = cause.output;

package/dist/native/setupServer.js

@@ -415,12 +415,14 @@ async function ensureDevServer({
 // One-time migration: older setups wrote this machine's LAN address into
 // config.json (every "localhost", and any http://<ip>), which makes Express
 // bind only that address and breaks adb reverse. Put localhost back, but only
-// for this machine's own addresses: a container IP, 0.0.0.0 or a loopback
-// address is the app's own setting.
+// for this machine's own addresses (or the one it had on another network):
+// a container IP, 0.0.0.0 or a loopback address is the app's own setting.
 // ---------------------------------------------------------------------------
 
 const MIGRATION_KEY = "lanAddresses";
 const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+// 10/8, 172.16/12, 192.168/16 and link-local 169.254/16.
+const PRIVATE_LAN_IPV4 = /^(?:10|172\.(?:1[6-9]|2\d|3[01])|192\.168|169\.254)\./;
 const isCI = env => {
   const value = env.CI;
   return value !== undefined && value !== "" && value !== "0" && String(value).toLowerCase() !== "false";
@@ -429,10 +431,13 @@ const isCI = env => {
 /**
  * The changes the migration would make, without writing anything. Only a
  * value equal to one of this machine's current IPv4 addresses, or an
- * http:// URL on one of them, goes back to localhost. Any other address,
- * private ones included (a LOCAL_IP pointing at a VPN or LAN staging server),
- * is the app's own setting. WEBVIEW_CONFIG.url is never touched, and nothing
- * is when WEBVIEW_CONFIG.allowPrivateHost is true.
+ * http:// URL on one of them, goes back to localhost. So does a private
+ * LOCAL_IP that NODE_SERVER_HOSTNAME also holds: an earlier setup wrote this
+ * machine's address on another network into both, and the dev server can't
+ * bind it here. Any other address, private ones included (a LOCAL_IP
+ * pointing at a VPN or LAN staging server), is the app's own setting.
+ * WEBVIEW_CONFIG.url is never touched, and nothing is when
+ * WEBVIEW_CONFIG.allowPrivateHost is true.
  *
  * @param {object} config - the parsed config.json (not modified)
  * @param {object} [options]
@@ -451,6 +456,11 @@ function planLanAddressMigration(config, {
   };
   // This machine's IPv4 addresses, without loopback and 0.0.0.0/8.
   const saved = new Set([...localHosts].filter(host => IPV4.test(host) && !/^(?:127|0)\./.test(host)));
+  // The LAN address this machine had when LOCAL_IP was written.
+  const leftover = typeof wv?.LOCAL_IP === "string" ? wv.LOCAL_IP.trim() : "";
+  if (IPV4.test(leftover) && PRIVATE_LAN_IPV4.test(leftover) && String(config.NODE_SERVER_HOSTNAME ?? "").trim() === leftover) {
+    saved.add(leftover);
+  }
   if (!saved.size) return {
     config,
     changes
@@ -532,8 +542,8 @@ function migrateLanAddresses({
     } : undefined).changes;
     const changes = planned.length ? writeConfigKeys(file, Object.fromEntries(planned.map(change => [change.path, change.to]))) : [];
     if (changes.length) {
-      log(`Put localhost back in config/config.json where an earlier setup saved this machine's LAN address:`, "info");
-      for (const change of changes) log(`  ${change.path}: ${change.from} -> ${change.to}`, "info");
+      log(`Put localhost back in config/config.json where an earlier setup saved this machine's LAN address:`, "note");
+      for (const change of changes) log(`  ${change.path}: ${change.from} -> ${change.to}`, "note");
     }
     const state = (0, _localState.readLocalState)({
       cwd

package/dist/native/utils.js

@@ -508,7 +508,7 @@ const NATIVE_ERRORS = exports.NATIVE_ERRORS = {
   },
   "IOS-010": {
     message: "iOS code signing is not set up",
-    hint: "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios."
+    hint: "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios."
   },
   "IOS-011": {
     message: "App Store Connect API key settings are incomplete or wrong",

package/dist/server/expressServer.js

@@ -358,26 +358,33 @@ async function createServer() {
       if (!res.headersSent) res.status(500).send("Internal Server Error");
     }
   });
-  app.listen({
+
+  // Express 4 never hands a bind failure to the listen callback: the
+  // http.Server emits it. Unhandled, an address this machine does not have
+  // (EADDRNOTAVAIL) left a raw uncaught exception and a server that never
+  // listened. Report it, then exit. Only until the server listens: a later
+  // error goes to the uncaughtException handler as before.
+  const onListenError = error => {
+    const known = hintFor(error.message);
+    process.stderr.write(diagnostic({
+      message: `Could not start the server: ${error.message}`,
+      scope: process.env.NODE_ENV === "development" ? "dev server" : "server",
+      hint: known?.hint,
+      docs: known?.docs
+    }));
+    safeCall(onServerError);
+    process.exit(1);
+  };
+  const server = app.listen({
     port,
     host
-  }, error => {
+  }, () => {
+    server.removeListener("error", onListenError);
     const {
       NODE_SERVER_HOSTNAME,
       NODE_SERVER_PORT
     } = process.env;
     const isDev = process.env.NODE_ENV === "development";
-    if (error) {
-      const known = hintFor(error.message);
-      process.stderr.write(diagnostic({
-        message: `Could not start the server: ${error.message}`,
-        scope: isDev ? "dev server" : "server",
-        hint: known?.hint,
-        docs: known?.docs
-      }));
-      safeCall(onServerError);
-      return;
-    }
 
     // Reached from the listen callback, so this means a port was bound --
     // it says nothing about whether anything compiled. Claiming a
@@ -409,6 +416,7 @@ async function createServer() {
     process.stdout.write(`${wrapped ? NEXT_STEP : ""}${GUTTER}${t.dim(isDev ? "Watching for changes. " : "Serving ")}` + `${isDev ? "" : t.accent(`${process.env.BUILD_OUTPUT_PATH || "build"}/`)}` + `${t.dim(isDev ? "Press Ctrl+C to stop." : ". Press Ctrl+C to stop.")}\n`);
     if (wrapped) process.stdout.write(`${BANNER_END}\n`);
   });
+  server.once("error", onListenError);
 }
 createServer().catch(err => {
   console.error(err?.stack || err);