fix(ios/catalyst): make debug builds launch

Report iOS as the platform name again. Ecosystem hooks and plugins switch on
`normalizedPlatformName`, and an unknown value leaves them in a branch that
never resolves, hanging the prepare. Only `projectRoot` stays catalyst specific.

Read entitlements from App_Resources/iOS, since catalyst has no folder of its
own. The merge silently produced nothing before, so the app group was dropped
and the template sandbox entitlement survived.

Disable the app sandbox for debug builds, which have no provisioning profile,
and point metadata generation at the iOSSupport frameworks so UIKit resolves.

Recreate the symlink layout of versioned frameworks after unzipping, as the
runtime archives them flattened and codesign then rejects the bundle.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: farfromrefug

lib/services/ios-entitlements-service.ts

@@ -20,11 +20,16 @@ export class IOSEntitlementsService {
 
 	private getDefaultAppEntitlementsPath(projectData: IProjectData): string {
 		const entitlementsName = IOSEntitlementsService.DefaultEntitlementsName;
+		const requestedPlatform = this.$mobileHelper.normalizePlatformName(
+			this.$options.platformOverride ?? this.$devicePlatformsConstants.iOS,
+		);
+		// Catalyst has no App_Resources folder of its own, it reuses the iOS one.
+		const platform = this.$mobileHelper.isCatalystPlatform(requestedPlatform)
+			? this.$devicePlatformsConstants.iOS
+			: requestedPlatform;
 		const entitlementsPath = path.join(
 			projectData.appResourcesDirectoryPath,
-			this.$mobileHelper.normalizePlatformName(
-				this.$options.platformOverride ?? this.$devicePlatformsConstants.iOS,
-			),
+			platform,
 			entitlementsName,
 		);
 		return entitlementsPath;

lib/services/ios-project-service.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import * as fs from "fs";
 import * as shell from "shelljs";
 import * as _ from "lodash";
 import * as constants from "../constants";
@@ -166,7 +167,7 @@ export class IOSProjectService
 			const requestedPlatform = this.$mobileHelper.normalizePlatformName(
 				this.$options.platformOverride ?? this.$devicePlatformsConstants.iOS,
 			);
-			// Mac Catalyst ships no runtime of its own, it reuses the iOS one.
+			// Hooks and plugins switch on the iOS name, Catalyst must keep it.
 			const runtimePlatform = this.$mobileHelper.isCatalystPlatform(
 				requestedPlatform,
 			)
@@ -182,8 +183,8 @@ export class IOSProjectService
 
 			this._platformData = {
 				frameworkPackageName: runtimePackage.name,
-				normalizedPlatformName: requestedPlatform,
-				platformNameLowerCase: requestedPlatform.toLowerCase(),
+				normalizedPlatformName: runtimePlatform,
+				platformNameLowerCase: runtimePlatform.toLowerCase(),
 				appDestinationDirectoryPath: path.join(
 					projectRoot,
 					projectData.projectName,
@@ -427,6 +428,57 @@ export class IOSProjectService
 		if (this.$fs.exists(xcframeworksFilePath)) {
 			await this.$fs.unzip(xcframeworksFilePath, internalDirPath);
 			this.$fs.deleteFile(xcframeworksFilePath);
+			this.restoreVersionedFrameworkSymlinks(internalDirPath);
+		}
+	}
+
+	/**
+	 * Recreates the symlink layout of versioned frameworks after extraction.
+	 */
+	private restoreVersionedFrameworkSymlinks(rootPath: string): void {
+		// Runtimes zip macOS style frameworks flattened, which breaks codesign.
+		const frameworks = fastGlob.sync("**/*.framework", {
+			cwd: rootPath,
+			onlyDirectories: true,
+			absolute: true,
+			deep: 4,
+		});
+
+		for (const frameworkPath of frameworks) {
+			const versionsPath = path.join(frameworkPath, "Versions");
+			if (!this.$fs.exists(versionsPath)) {
+				continue;
+			}
+
+			const versions = this.$fs
+				.readDirectory(versionsPath)
+				.filter((name) => name !== "Current");
+			if (!versions.length) {
+				continue;
+			}
+
+			const version = versions.includes("A") ? "A" : versions[0];
+			const currentPath = path.join(versionsPath, "Current");
+			if (!fs.lstatSync(currentPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+				shell.rm("-rf", currentPath);
+				fs.symlinkSync(version, currentPath);
+			}
+
+			for (const name of this.$fs.readDirectory(
+				path.join(versionsPath, version),
+			)) {
+				const topLevelPath = path.join(frameworkPath, name);
+				if (
+					fs
+						.lstatSync(topLevelPath, { throwIfNoEntry: false })
+						?.isSymbolicLink()
+				) {
+					continue;
+				}
+
+				shell.rm("-rf", topLevelPath);
+				fs.symlinkSync(path.join("Versions", "Current", name), topLevelPath);
+			}
 		}
 	}
 

lib/services/ios/xcodebuild-args-service.ts

@@ -47,6 +47,11 @@ export class XcodebuildArgsService implements IXcodebuildArgsService {
 			buildConfig.release ? Configurations.Release : Configurations.Debug,
 			"-allowProvisioningUpdates",
 			"SUPPORTS_MACCATALYST=YES",
+			// Sandbox needs a provisioning profile, debug runs have none.
+			...(buildConfig.release ? [] : ["ENABLE_APP_SANDBOX=NO"]),
+			// Metadata generation needs UIKit, which lives under iOSSupport.
+			"OTHER_CFLAGS=$(inherited) -iframework " +
+				"$(SDKROOT)/System/iOSSupport/System/Library/Frameworks",
 			// no `-sdk` here: the destination already selects macOS + the Mac Catalyst
 			// variant, and forcing an SDK on top of it makes xcodebuild pick iphoneos
 			"BUILD_DIR=" + path.join(platformData.projectRoot, constants.BUILD_DIR),