feat(ci): recompose upstream Hermes xcframework with macOS slice

Saadnajmi · claude · Saadnajmi · commit 6d4c48bfa465 · 2026-04-17T17:20:58.000-07:00
Instead of building Hermes from source (~90 min), download the
upstream tarball from Maven, extract frameworks from the universal
xcframework, add the standalone macOS framework, and recompose
a new xcframework that includes all platforms.

Replaces the previous checkUpstreamHermesHasMacSlice approach
(which only checked if macOS was already in the universal) with
downloadUpstreamHermesTarball + recompose (which actively adds it).

Build-from-source is kept as a fallback when no upstream tarball
is available.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/microsoft-resolve-hermes.yml b/.github/workflows/microsoft-resolve-hermes.yml
@@ -11,7 +11,7 @@ jobs:
     outputs:
       hermes-commit: ${{ steps.resolve.outputs.hermes-commit }}
       cache-hit: ${{ steps.cache.outputs.cache-hit }}
-      upstream-has-mac-slice: ${{ steps.check-upstream.outputs.upstream-has-mac-slice }}
+      recomposed: ${{ steps.recompose.outputs.recomposed }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -27,41 +27,87 @@ jobs:
       - name: Install npm dependencies
         run: yarn install
 
-      - name: Check if upstream Hermes xcframework includes mac slice
-        id: check-upstream
+      - name: Download upstream Hermes tarball
+        id: download
         working-directory: packages/react-native
         run: |
           node -e "
-            const {checkUpstreamHermesHasMacSlice} = require('./scripts/ios-prebuild/macosVersionResolver');
-            checkUpstreamHermesHasMacSlice('Debug').then(r => {
-              require('fs').writeFileSync('/tmp/hermes-check-result.json', JSON.stringify(r));
+            const {downloadUpstreamHermesTarball} = require('./scripts/ios-prebuild/macosVersionResolver');
+            downloadUpstreamHermesTarball('Debug').then(r => {
+              require('fs').writeFileSync('/tmp/hermes-download-result.json', JSON.stringify(r));
             });
           "
-          RESULT=$(cat /tmp/hermes-check-result.json)
-          HAS_MAC_SLICE=$(node -e "console.log(JSON.parse(process.argv[1]).hasMacSlice)" "$RESULT")
-          echo "upstream-has-mac-slice=$HAS_MAC_SLICE" >> "$GITHUB_OUTPUT"
-          echo "Upstream Hermes xcframework has mac slice: $HAS_MAC_SLICE"
-
-          if [ "$HAS_MAC_SLICE" = "true" ]; then
-            TARBALL=$(node -e "console.log(JSON.parse(process.argv[1]).tarballPath || '')" "$RESULT")
-            if [ -n "$TARBALL" ] && [ -f "$TARBALL" ]; then
-              mkdir -p ${{ github.workspace }}/hermes-destroot
-              tar -xzf "$TARBALL" -C ${{ github.workspace }}/hermes-destroot --strip-components=2
-              echo "Extracted upstream Hermes to hermes-destroot"
-              ls -la ${{ github.workspace }}/hermes-destroot/
+          RESULT=$(cat /tmp/hermes-download-result.json)
+          if [ "$RESULT" != "null" ]; then
+            TARBALL=$(node -e "console.log(JSON.parse(process.argv[1]).tarballPath)" "$RESULT")
+            VERSION=$(node -e "console.log(JSON.parse(process.argv[1]).version)" "$RESULT")
+            echo "tarball=$TARBALL" >> "$GITHUB_OUTPUT"
+            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+            echo "Downloaded upstream Hermes tarball for version $VERSION"
+          else
+            echo "No upstream tarball available"
+          fi
+
+      - name: Recompose xcframework with macOS slice
+        id: recompose
+        if: steps.download.outputs.tarball != ''
+        run: |
+          TARBALL="${{ steps.download.outputs.tarball }}"
+
+          # Extract tarball
+          mkdir -p hermes-destroot
+          tar -xzf "$TARBALL" -C hermes-destroot --strip-components=2
+
+          echo "=== Upstream tarball contents ==="
+          ls -la hermes-destroot/Library/Frameworks/
+
+          # Collect existing frameworks from the universal xcframework
+          XCFW="hermes-destroot/Library/Frameworks/universal/hermes.xcframework"
+          FRAMEWORKS=()
+          for fw in "$XCFW"/*/hermes.framework; do
+            if [ -d "$fw" ]; then
+              echo "Found slice: $fw"
+              FRAMEWORKS+=(-framework "$fw")
             fi
+          done
+
+          # Add standalone macOS framework
+          MAC_FW="hermes-destroot/Library/Frameworks/macosx/hermes.framework"
+          if [ -d "$MAC_FW" ]; then
+            echo "Found standalone macOS slice: $MAC_FW"
+            FRAMEWORKS+=(-framework "$MAC_FW")
+          else
+            echo "::error::Upstream tarball missing macosx/hermes.framework"
+            echo "recomposed=false" >> "$GITHUB_OUTPUT"
+            exit 0
           fi
 
-      - name: Upload upstream Hermes as artifact
-        if: steps.check-upstream.outputs.upstream-has-mac-slice == 'true'
+          # Remove old xcframework and create new one with macOS included
+          rm -rf "$XCFW"
+          echo "Creating new universal xcframework with ${#FRAMEWORKS[@]} frameworks..."
+          xcodebuild -create-xcframework "${FRAMEWORKS[@]}" \
+            -output "$XCFW" \
+            -allow-internal-distribution
+
+          # Clean up standalone macOS dir (now included in universal)
+          rm -rf hermes-destroot/Library/Frameworks/macosx
+
+          echo "=== Recomposed xcframework ==="
+          ls -la "$XCFW"/
+
+          echo "recomposed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Upload recomposed Hermes artifacts
+        if: steps.recompose.outputs.recomposed == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: hermes-artifacts
           path: hermes-destroot
           retention-days: 30
 
+      # Fallback: resolve Hermes commit for build-from-source
       - name: Resolve Hermes commit at merge base
-        if: steps.check-upstream.outputs.upstream-has-mac-slice != 'true'
+        if: steps.recompose.outputs.recomposed != 'true'
         id: resolve
         working-directory: packages/react-native
         run: |
@@ -70,15 +116,15 @@ jobs:
           echo "Resolved Hermes commit: $COMMIT"
 
       - name: Restore Hermes cache
-        if: steps.check-upstream.outputs.upstream-has-mac-slice != 'true'
+        if: steps.recompose.outputs.recomposed != 'true'
         id: cache
         uses: actions/cache/restore@v4
         with:
           key: hermes-v1-${{ steps.resolve.outputs.hermes-commit }}-Debug
           path: hermes-destroot
 
       - name: Upload cached Hermes artifacts
-        if: steps.check-upstream.outputs.upstream-has-mac-slice != 'true' && steps.cache.outputs.cache-hit == 'true'
+        if: steps.recompose.outputs.recomposed != 'true' && steps.cache.outputs.cache-hit == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: hermes-artifacts
@@ -87,7 +133,7 @@ jobs:
 
   build-hermesc:
     name: "Build hermesc"
-    if: ${{ needs.resolve-hermes.outputs.upstream-has-mac-slice != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: resolve-hermes
     runs-on: macos-15
     timeout-minutes: 30
@@ -128,7 +174,7 @@ jobs:
 
   build-hermes-slice:
     name: "Hermes ${{ matrix.slice }}"
-    if: ${{ needs.resolve-hermes.outputs.upstream-has-mac-slice != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: [resolve-hermes, build-hermesc]
     runs-on: macos-15
     timeout-minutes: 45
@@ -196,7 +242,7 @@ jobs:
 
   assemble-hermes:
     name: "Assemble Hermes xcframework"
-    if: ${{ needs.resolve-hermes.outputs.upstream-has-mac-slice != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
+    if: ${{ needs.resolve-hermes.outputs.recomposed != 'true' && needs.resolve-hermes.outputs.cache-hit != 'true' }}
     needs: [resolve-hermes, build-hermes-slice]
     runs-on: macos-15
     timeout-minutes: 15
diff --git a/packages/react-native/scripts/ios-prebuild/macosVersionResolver.js b/packages/react-native/scripts/ios-prebuild/macosVersionResolver.js
@@ -187,26 +187,20 @@ async function getLatestStableVersionFromNPM() /*: Promise<string> */ {
 }
 
 /**
- * Checks whether the upstream Hermes tarball (from Maven) already contains
- * macOS slices. If it does, we can skip building Hermes from source entirely.
+ * Downloads the upstream Hermes tarball from Maven or Sonatype.
+ * The caller is responsible for extracting and recomposing the
+ * xcframework (e.g. adding the macOS slice to the universal).
  *
  * Tries multiple version resolution strategies in order:
  * 1. Mapped version from peerDependencies (stable branches)
  * 2. Version at merge base with facebook/react-native (main branch)
  * 3. Latest stable version from npm (last resort)
  *
- * Returns {hasMacSlice: boolean, tarballPath?: string, version?: string}.
- * When hasMacSlice is true, tarballPath points to the downloaded tarball and
- * version is the upstream version string used for the lookup.
- *
- * The check looks for a macOS platform entry inside the universal
- * hermes.xcframework (via its Info.plist), not just for a standalone
- * macosx/ directory. Upstream tarballs ship a standalone macosx/hermes.framework
- * but don't include it in the universal xcframework yet.
+ * Returns {tarballPath, version} on success, or null if no tarball is available.
  */
-async function checkUpstreamHermesHasMacSlice(
+async function downloadUpstreamHermesTarball(
   buildType /*: BuildFlavor */ = 'Debug',
-) /*: Promise<{| hasMacSlice: boolean, tarballPath?: string, version?: string |}> */ {
+) /*: Promise<?{| tarballPath: string, version: string |}> */ {
   const packageJsonPath = path.resolve(__dirname, '..', '..', 'package.json');
 
   // Build a list of candidate versions to try (in priority order)
@@ -232,8 +226,10 @@ async function checkUpstreamHermesHasMacSlice(
   }
 
   if (candidates.length === 0) {
-    macosLog('Could not determine any upstream version to check Hermes tarball');
-    return {hasMacSlice: false};
+    macosLog(
+      'Could not determine any upstream version to download Hermes tarball',
+    );
+    return null;
   }
 
   const mavenRepoUrl = 'https://repo1.maven.org/maven2';
@@ -255,74 +251,29 @@ async function checkUpstreamHermesHasMacSlice(
 
     for (const tarballUrl of urlsToTry) {
       macosLog(
-        `Checking upstream Hermes tarball (version: ${version}, ${buildType}) at ${tarballUrl}...`,
+        `Trying upstream Hermes tarball (version: ${version}, ${buildType}) at ${tarballUrl}...`,
       );
 
-      // Check if the tarball exists
-      try {
-        const headResponse = await fetch(tarballUrl, {method: 'HEAD'});
-        if (headResponse.status !== 200) {
-          macosLog(`Tarball not found, trying next URL...`);
-          continue;
-        }
-      } catch (_) {
-        macosLog('Failed to reach server, trying next URL...');
-        continue;
-      }
-
-      // Download the tarball to a temp directory
-      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-check-'));
-      const tarballPath = path.join(tmpDir, 'hermes-ios.tar.gz');
-
       try {
-        macosLog(`Downloading upstream tarball...`);
-        const response = await fetch(tarballUrl);
+        const response /*: Response */ = await fetch(tarballUrl);
         if (!response.ok) {
           macosLog(
-            `Download failed: ${response.status} ${response.statusText}`,
+            `Tarball not available: ${response.status} ${response.statusText}`,
           );
-          fs.rmSync(tmpDir, {recursive: true, force: true});
           continue;
         }
 
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-'));
+        const tarballPath = path.join(tmpDir, 'hermes-ios.tar.gz');
         const buffer = await response.arrayBuffer();
         fs.writeFileSync(tarballPath, Buffer.from(buffer));
 
-        // Extract the xcframework's Info.plist and check for a macOS
-        // platform entry. We can't just look for a macosx/ directory in
-        // the tarball — upstream ships a standalone macosx/hermes.framework
-        // but doesn't include macOS in the universal xcframework yet.
-        let hasMacSlice = false;
-        try {
-          const plist = execSync(
-            `tar -xzf "${tarballPath}" -O --wildcards '*/universal/hermes.xcframework/Info.plist' 2>/dev/null`,
-            {encoding: 'utf8', maxBuffer: 1024 * 1024},
-          );
-          hasMacSlice = plist.includes('macos') || plist.includes('macOS');
-        } catch (_) {
-          // Info.plist not found or extraction failed — no mac slice
-          macosLog('Could not extract xcframework Info.plist from tarball.');
-        }
-
-        if (hasMacSlice) {
-          macosLog(
-            `Upstream Hermes tarball (${version}) includes macOS in the universal xcframework — build from source can be skipped!`,
-          );
-          return {hasMacSlice: true, tarballPath, version};
-        } else {
-          macosLog(
-            `Upstream Hermes tarball (${version}) does NOT include macOS in the universal xcframework.`,
-          );
-          fs.rmSync(tmpDir, {recursive: true, force: true});
-          // Don't try other versions — if the tarball exists but lacks
-          // the mac slice, older versions won't have it either.
-          return {hasMacSlice: false};
-        }
+        macosLog(
+          `Downloaded upstream Hermes tarball (${version}) to ${tarballPath}`,
+        );
+        return {tarballPath, version};
       } catch (e) {
-        macosLog(`Error checking tarball for ${version}: ${e.message}`);
-        try {
-          fs.rmSync(tmpDir, {recursive: true, force: true});
-        } catch (_) {}
+        macosLog(`Error downloading tarball for ${version}: ${e.message}`);
         continue;
       }
     }
@@ -331,7 +282,7 @@ async function checkUpstreamHermesHasMacSlice(
   macosLog(
     'No upstream Hermes tarball found for any candidate version — will build from source.',
   );
-  return {hasMacSlice: false};
+  return null;
 }
 
 function abort(message /*: string */) {
@@ -344,5 +295,5 @@ module.exports = {
   hermesCommitAtMergeBase,
   findVersionAtMergeBase,
   getLatestStableVersionFromNPM,
-  checkUpstreamHermesHasMacSlice,
+  downloadUpstreamHermesTarball,
 };
