fix(ios): Resolve Mac Catalyst build failures and App Store distribution issues

[macCesar]

Summary

This PR fixes critical build failures that prevented Mac Catalyst apps from compiling and being distributed through the App Store. These issues have affected developers since at least SDK 12.x, requiring workarounds that disrupted normal development workflows.

Problems Addressed

1. Framework Search Path Issue

Symptom: Intermittent build failures with framework linking errors
Root cause: Relative framework search path "Frameworks" failed to resolve correctly in certain build scenarios
Solution: Use absolute path "$(PROJECT_DIR)/Frameworks" for reliable framework location

2. Missing TitaniumKit.framework Symlinks

Symptom: Compilation errors and App Store rejections
Build-time error:

<module-includes>:1:9: error: could not build module 'TitaniumKit'
@import TitaniumKit;
        ^
<unknown>:0: error: Unable to find module dependency: 'TitaniumKit'

App Store rejection:

ERROR ITMS-90206: "Invalid Bundle. The bundle at 'YourApp.app/Contents/Frameworks/
TitaniumKit.framework' contains disallowed file 'Versions'."

Asset validation failed: The bundle 'YourApp.app/Contents/Frameworks/
TitaniumKit.framework' does not exist.

Root cause: Mac Catalyst requires macOS framework structure with proper symlink hierarchy (Versions/Current -> A and root-level symlinks), but builds were producing iOS framework structure
Solution: Automatically create required symlinks at two critical points:

• Before xcodebuild (fixes compilation errors)
• After xcodebuild in final app bundle (fixes App Store validation)

3. Incremental Build Issues

Symptom: EEXIST: file already exists errors when rebuilding without ti clean
Root cause: Previous SDK versions created directories instead of symlinks, or symlinks became broken during incremental builds
Solution: Detect and remove directories, files, and broken symlinks before creating new ones

Changes

Modified Files

• iphone/cli/commands/_build.js

Specific Changes

1. Line 3524: Updated FRAMEWORK_SEARCH_PATHS from "Frameworks" to "$(PROJECT_DIR)/Frameworks"

2. Lines 7116-7242: Added createTitaniumKitSymlinks() function

   • Guards execution to Mac Catalyst targets only (macos, dist-macappstore)
   • Creates proper macOS framework structure with symlinks
   • Handles both build directory and final app bundle locations
   • Intelligently handles incremental builds:
     • Detects directories created by previous SDK versions
     • Detects broken symlinks (symlinks pointing to non-existent targets)
     • Verifies existing symlinks point to correct targets
     • Removes incorrect/broken items before creating new ones
   • Uses lstatSync() instead of existsSync() to detect broken symlinks
   • Provides informative logging for debugging

3. Lines 7101, 7104, 7433: Integrated symlink creation into build pipeline

   • Called before xcodebuild to fix compilation
   • Called after xcodebuild to fix App Store packaging

Impact

What This Fixes

• ✅ Mac Catalyst apps now compile successfully
• ✅ Incremental builds work without ti clean required
• ✅ Broken symlinks from previous builds are automatically fixed
• ✅ Directories created by SDK 13.0.1.GA are automatically converted to symlinks
• ✅ App Store validation passes for Mac Catalyst apps
• ✅ Enables distribution through Mac App Store
• ✅ Applies to all Titanium apps targeting Mac Catalyst

What This Doesn't Affect

• Standard iOS device/simulator builds continue to work identically
• Android builds are completely unaffected
• Changes only execute for Mac Catalyst targets due to explicit guards

Testing

Verified across multiple scenarios with different Titanium projects:

• ✅ Fresh project builds successfully
• ✅ Incremental builds work without ti clean
• ✅ Development builds (Debug-maccatalyst) compile and run
• ✅ Distribution builds (Release-maccatalyst) create valid xcarchive
• ✅ App Store validation accepts framework structure
• ✅ Broken symlinks from previous builds are automatically repaired
• ✅ Standard iOS builds unaffected
• ✅ Existing iOS projects continue working normally

Additional Context

The issues fixed by this PR affected any Titanium application attempting to:

• Compile for Mac Catalyst (Target: macos)
• Create distribution builds for Mac App Store (Target: dist-macappstore)

These were fundamental build system issues, not app-specific problems.

⚠️ Module Compatibility

Mac Catalyst builds require native modules to include an ios-arm64_x86_64-maccatalyst slice in their xcframework.

What this means:

• If a module doesn't support Mac Catalyst, builds targeting Mac will fail
• iOS device and simulator builds are completely unaffected
• This is expected behavior - not all modules can or should support Mac

Example error when a module lacks Mac Catalyst support:

error: While building for Mac Catalyst, no library for this platform was found in
'module.xcframework'

For module developers:
To enable Mac Catalyst support in your module:

1. Add mac: true to your module's manifest file
2. Rebuild the module - the SDK will automatically build all three slices

Note: Some modules may have legitimate reasons to not support Mac Catalyst (iOS-only APIs, hardware dependencies, etc.).

Backward Compatibility

This change is fully backward compatible:

• No breaking changes to existing APIs
• No changes to tiapp.xml configuration
• No impact on existing iOS/Android workflows
• Mac Catalyst builds that previously required workarounds now work natively
• Automatically migrates projects from SDK 13.0.1.GA directory structure to proper symlinks

---

Note: This fix enables Mac Catalyst as a viable deployment target for all Titanium developers, opening the Mac App Store distribution channel that was previously blocked by these issues.

[hansemannn]

Some of these changes look quite verbose, so I'm wondering if only parts of these changes are actually relevant for this precise fix.

[hansemannn]

Remove these comments, it's looks odd as part of an overall build script. If necessary, add it to the comments

[macCesar]

@hansemannn Thanks for the detailed feedback! I've addressed your concerns in the latest commit:

Changes made:

1. Removed "Bug #X" comments - Replaced with descriptive explanations that make sense in context

2. Simplified ensureSymlink function - Reduced from 44 to 23 lines (~50% less code):

   • Removed redundant fs.existsSync check as you suggested
   • Consolidated the symlink validation logic
   • Removed verbose debug logging
   • Removed unused logger parameter

3. Kept FRAMEWORK_SEARCH_PATHS - The $(PROJECT_DIR)/Frameworks path is necessary for Mac Catalyst. Without it, the linker fails with "Unable to find module dependency: TitaniumKit"

Testing performed:

• ✅ Clean build (ti build -p ios -T macos)
• ✅ Incremental build (detects existing symlinks correctly)
• ✅ Distribution build (ti build -p ios -T dist-macappstore)
• ✅ Framework structure verified with correct symlinks

Ready for your review when you have a chance!

[hansemannn]

Excellent work, we can approve it now! :)

[hansemannn]

@macCesar After merging all changes for 13.1.1 (incl. yours) to 13_1_X, the build fails due to a Mac Catalyst error:

https://github.com/tidev/titanium-sdk/actions/runs/21472015632/job/61846652200

Can you please review the issue? Note: The build was triggered by the tab-bar fixes, but only because that was the last cherry-picked commit before pushing it to the branch where the CI starts.

[hbugdoll]

@hansemannn I don't think it was a Mac Catalyst error.
After macOS and Simulator xcarchives were created, the build process aborted at the beginning of the iOS step with:
error:iOS 26.0 is not installed.

Therefore error: Unable to find a destination matching the provided destination specifier: { ... platform:iOS } and only platform:macOS destitations were available.

Now with your update to Xcode 26.2, it seems to be working 👍
https://github.com/tidev/titanium-sdk/actions/runs/21473518471/job/61851657778

Edit: Ah, I saw your discussion on Slack too late (I only use it in the browser, not the app).

[macCesar]

@hansemannn @hbugdoll Thanks for clarifying!

So the failure was NOT caused by my PR, is that correct?

Sorry, I'm not very familiar with this type of CI/workflows! Still learning 🙂

Glad to hear everything is working now with Xcode 26.2!

[hbugdoll]

So the failure was NOT caused by my PR, is that correct?

Yep.

[hbugdoll]

For the sake of completeness: GitHub's macOS 15 runner was changed...

• [macOS] Deprecation of simulator runtimes for Xcode 26.0.1 on macOS 15 on January 26th actions/runner-images#13570
• [macOS-15] Remove Xcode 26.0 default platform actions/runner-images#13575